Events-Referenz

Phase 1 unterstützt sechs Event-Topics. Jedes Topic liefert eine kleine typisierte Dataclass an Ihren Handler. Die Dataclasses sind in Python/mte/events.py definiert und aus dem Top-Level-Paket mte importierbar.

Topic-↔-Dataclass-Tabelle

Topic	Payload-Dataclass	Felder
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	(keine Felder)

document ist eine opake ganzzahlige Id, die der Host vergibt. Vergleichen Sie Ids mit ==; persistieren Sie sie nicht über Editor-Neustarts hinweg.

Abonnieren per Sugar-Decorator

Empfohlen für die festen Phase-1-Topics — der Decorator-Name entspricht dem Topic, und der Payload-Typ wird abgeleitet:

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")

Abonnieren über die Roh-API

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

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

• Liefert die lokal vergebene handler_id zurück (ein "py-ev/N"-String).
• Unbekannte Topics werfen zum Abonnementzeitpunkt ValueError — kein stilles No-op.

Bestellen Sie ab, wenn es Sie nicht mehr interessiert:

ctx.events.unsubscribe(handler_id)

Hinweis: Nach unsubscribe liefert der Host das Topic nicht mehr an Sie, aber der lokale Dispatcher des Workers behält seinen Eintrag, bis das Plugin herunterfährt. Verlassen Sie sich für die Speicherbereinigung nicht auf unsubscribe — es ist ein Policy-Signal, kein Garbage-Collection-Primitiv.

Zustellsemantik

• Events feuern, nachdem die entsprechende Aktion abgeschlossen ist. Bei document.saved liegt die Datei bereits auf der Platte. Bei document.closed ist die Dokument-Id bereits ungültig.
• Mehrere Abonnenten desselben Topics feuern alle, in undefinierter Reihenfolge.
• Ausnahmen, die in Ihrem Handler geworfen werden, fängt der Worker ab und schreibt sie nach stderr (im Log des Hosts sichtbar als [worker stderr] …). Ein fehlverhaltender Handler hindert andere Abonnenten nicht am Feuern.
• Payload-Dataclasses sind unveränderlich; mutieren Sie keine ev-Felder.

Noch nicht verfügbar

PYTHON_PLUGIN_ARCHITECTURE.md §6.3 listet Topics, die der Host veröffentlicht, die aber noch nicht für Python verfügbar sind: document.aboutToSave, text.changed, document.modifiedChanged, settings.changed, workspace.rootChanged, workspace.filesChanged, theme.changed. Sie werden schrittweise hinzugefügt, sobald die Python-seitigen Dataclasses implementiert sind; die C++-Seite stellt sie für native Plugins bereits bereit.

Das Veröffentlichen eigener benutzerdefinierter Events an andere Plugins über den gemeinsamen Bus ist für Phase 2 geplant, in Phase 1 aber nicht verdrahtet.