Events reference

Phase 1 supports six event topics. Each topic delivers a small typed dataclass to your handler. The dataclasses are defined in Python/mte/events.py and are importable from the top-level mte package.

Topic ↔ dataclass table

Topic	Payload dataclass	Fields
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	(no fields)

document is an opaque integer id assigned by the host. Compare ids with ==; do not persist them across editor restarts.

Subscribe via sugar decorator

Recommended for the fixed Phase 1 topics — the decorator name matches the topic and the payload type is inferred:

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

Subscribe via the raw API

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

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

• Returns the locally-allocated handler_id (a "py-ev/N" string).
• Unknown topics raise ValueError at subscribe time — no silent noop.

Unsubscribe when you no longer care:

ctx.events.unsubscribe(handler_id)

Note: after unsubscribe the host stops delivering the topic to you, but the worker's local dispatcher keeps its entry until the plugin shuts down. Do not rely on unsubscribe for memory cleanup — it's a policy signal, not a garbage-collection primitive.

Delivery semantics

• Events fire after the corresponding action has completed. On document.saved, the file is already on disk. On document.closed, the document id is already invalid.
• Multiple subscribers to the same topic all fire, in undefined order.
• Exceptions raised in your handler are caught by the worker and written to stderr (visible in the host's log as [worker stderr] …). A misbehaving handler does not stop other subscribers from firing.
• Payload dataclasses are immutable; do not mutate ev fields.

Not yet available

PYTHON_PLUGIN_ARCHITECTURE.md §6.3 lists topics the host publishes that are not yet surfaced to Python: document.aboutToSave, text.changed, document.modifiedChanged, settings.changed, workspace.rootChanged, workspace.filesChanged, theme.changed. They will be added incrementally as the Python-side dataclasses are implemented; the C++ side already exposes them for native plugins.

Publishing your own custom events to other plugins over the shared bus is planned for Phase 2 but not wired in Phase 1.