Référence des événements

La phase 1 prend en charge six sujets d'événements. Chaque sujet livre une petite dataclass typée à votre gestionnaire. Les dataclasses sont définies dans Python/mte/events.py et importables depuis le paquet de premier niveau mte.

Table sujet ↔ dataclass

Sujet	Dataclass de charge utile	Champs
document.opened	mte.DocumentOpened	document: int, path: str
document.closed	mte.DocumentClosed	document: int
document.saved	mte.DocumentSaved	document: int
selection.changed	mte.SelectionChanged	document: int
document.activeChanged	mte.ActiveDocumentChanged	document: int
app.aboutToQuit	mte.AppAboutToQuit	(aucun champ)

document est un identifiant entier opaque attribué par l'hôte. Comparez les identifiants avec == ; ne les persistez pas entre redémarrages de l'éditeur.

S'abonner via le décorateur sucré

Recommandé pour les sujets fixes de la phase 1 — le nom du décorateur correspond au sujet et le type de la charge utile est inféré :

import mte

def register(ctx):

    @ctx.events.on_document_saved
    def _saved(ev: mte.DocumentSaved):
        ctx.log.info(f"saved doc {ev.document}")

    @ctx.events.on_document_opened
    def _opened(ev: mte.DocumentOpened):
        ctx.log.info(f"opened {ev.document} at {ev.path}")

    @ctx.events.on_app_about_to_quit
    def _quit(_ev: mte.AppAboutToQuit):
        ctx.log.info("editor is closing")

S'abonner via l'API brute

def _saved(ev):
    ctx.log.info(f"saved {ev.document}")

handler_id = ctx.events.subscribe("document.saved", _saved)

• Renvoie le handler_id alloué localement (une chaîne "py-ev/N").
• Les sujets inconnus lèvent ValueError à l'abonnement — pas d'échec silencieux.

Désabonnez-vous quand cela ne vous intéresse plus :

ctx.events.unsubscribe(handler_id)

Remarque : après unsubscribe, l'hôte cesse de vous livrer le sujet, mais le répartiteur local du worker garde son entrée jusqu'à l'arrêt de l'extension. Ne comptez pas sur unsubscribe pour libérer de la mémoire — c'est un signal de politique, pas une primitive de ramasse-miettes.

Sémantique de livraison

• Les événements se déclenchent après l'achèvement de l'action correspondante. Sur document.saved, le fichier est déjà sur le disque. Sur document.closed, l'identifiant du document est déjà invalide.
• Plusieurs abonnés au même sujet se déclenchent tous, dans un ordre indéfini.
• Les exceptions levées dans votre gestionnaire sont interceptées par le worker et écrites sur stderr (visibles dans le journal de l'hôte comme [worker stderr] …). Un gestionnaire défaillant n'empêche pas les autres abonnés de se déclencher.
• Les dataclasses de charge utile sont immuables ; ne modifiez pas les champs de ev.

Pas encore disponible

PYTHON_PLUGIN_ARCHITECTURE.md §6.3 liste des sujets publiés par l'hôte qui ne sont pas encore exposés à Python : document.aboutToSave, text.changed, document.modifiedChanged, settings.changed, workspace.rootChanged, workspace.filesChanged, theme.changed. Ils seront ajoutés progressivement à mesure que les dataclasses côté Python seront implémentées ; le côté C++ les expose déjà aux extensions natives.

La publication de vos propres événements personnalisés vers d'autres extensions sur le bus partagé est prévue pour la phase 2 mais pas câblée en phase 1.