Dokumentacja zdarzeń

Faza 1 obsługuje sześć tematów zdarzeń. Każdy temat dostarcza do Twojego handlera mały typowany dataclass. Dataclassy zdefiniowane są w Python/mte/events.py i są importowalne z pakietu najwyższego poziomu mte.

Tabela temat ↔ dataclass

Temat	Dataclass ładunku	Pola
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	(brak pól)

document to nieprzezroczyste całkowitoliczbowe id przydzielane przez hosta. Porównuj id operatorem ==; nie utrwalaj ich między restartami edytora.

Subskrypcja przez dekorator (sugar)

Zalecana dla stałych tematów fazy 1 — nazwa dekoratora odpowiada tematowi, a typ ładunku jest wnioskowany:

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

Subskrypcja przez surowe API

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

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

• Zwraca lokalnie przydzielony handler_id (string postaci "py-ev/N").
• Nieznane tematy rzucają ValueError w momencie subskrypcji — bez cichego no-op.

Wypisz się z subskrypcji, gdy przestaje Cię interesować:

ctx.events.unsubscribe(handler_id)

Uwaga: po unsubscribe host przestaje dostarczać Ci ten temat, ale lokalny dyspozytor workera zachowuje swój wpis aż do zamknięcia wtyczki. Nie polegaj na unsubscribe przy sprzątaniu pamięci — to sygnał polityki, a nie prymityw odśmiecania pamięci.

Semantyka dostarczania

• Zdarzenia odpalają się po zakończeniu odpowiadającej im akcji. Przy document.saved plik jest już na dysku. Przy document.closed id dokumentu jest już nieprawidłowe.
• Wielu subskrybentów tego samego tematu odpala się wszystkich, w niezdefiniowanej kolejności.
• Wyjątki rzucone w Twoim handlerze są łapane przez workera i zapisywane na stderr (widoczne w logu hosta jako [worker stderr] …). Wadliwy handler nie powstrzymuje odpalania pozostałych subskrybentów.
• Dataclassy ładunków są niemutowalne; nie modyfikuj pól ev.

Jeszcze niedostępne

PYTHON_PLUGIN_ARCHITECTURE.md §6.3 wymienia tematy publikowane przez hosta, które nie są jeszcze udostępnione Pythonowi: document.aboutToSave, text.changed, document.modifiedChanged, settings.changed, workspace.rootChanged, workspace.filesChanged, theme.changed. Będą dodawane przyrostowo w miarę implementacji dataclassów po stronie Pythona; strona C++ udostępnia je już wtyczkom natywnym.

Publikowanie własnych niestandardowych zdarzeń do innych wtyczek przez wspólną szynę jest planowane na fazę 2, ale nie jest podłączone w fazie 1.