Vai al contenuto

Plugin Python

Modular Text Editor carica i plugin Python accanto a quelli nativi in C++ attraverso la stessa superficie di gestione dei plugin. Un plugin Python è una cartella che contiene un plugin.json e almeno un file .py con una funzione register(ctx) di primo livello.

L'editor avvia un piccolo sottoprocesso worker per plugin, vi esegue dentro register(ctx) e smista comandi / menu / eventi attraverso un canale RPC. Il tuo plugin non tocca mai Qt o Scintilla: l'oggetto ctx è un semplice localizzatore di servizi Python.

Che cosa funziona oggi (fasi 1–5: complete)

Fase 1: comandi, voci di menu, sottoscrizioni a eventi (apertura / chiusura / salvataggio / cambio del documento attivo / cambio della selezione / uscita dall'applicazione), il log, la barra di stato.

Fase 2: buffer dell'editor / selezione / cursore / ricerca / rientro / operazioni sui file tramite ctx.editor.*, impostazioni persistenti tramite ctx.settings.* e impostazioni dell'applicazione in sola lettura tramite ctx.app_settings.*, fornitori di completamento (con una piccola scadenza legata alla battuta) tramite @ctx.completions.provider(...), e ctx.data_dir() per la cartella scrivibile di ciascun plugin.

Fase 3: pannelli ancorabili dichiarativi tramite ctx.docks.add_panel(...), pagine delle Preferenze tramite ctx.settings_page.register(...), entrambi costruiti con i costruttori di moduli mte.ui, e accesso ai controlli a tempo di esecuzione tramite ctx.ui.get / ctx.ui.set.

Fase 4: installer di pacchetti .mteplugin — comprimi la cartella del tuo plugin e installala da Preferenze → Estensioni (vedi Creazione dei pacchetti).

Fase 5: ambienti virtuali per plugin — dichiara le dipendenze pip in pyRequires e l'editor predispone un venv per il tuo plugin al primo avvio (vedi Dipendenze); una dichiarazione di permissions mostrata nella pagina Plugin; e un substrato RPC con flusso e annullamento (per ora senza API rivolta ai plugin — sostiene i futuri servizi di IA).

Plugin minimo

Crea <any-folder>/hello/ con questi due file.

hello/plugin.json
{
  "id":         "org.example.hello",
  "name":       "Hello (Python)",
  "version":    "1.0.0",
  "apiVersion": 1,
  "entry":      "python",
  "module":     "main",
  "menus": [
    { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
  ]
}
hello/main.py
import mte  # noqa: F401


def register(ctx):

    @ctx.commands.command(id="hello.sayHi",
                          title="Say Hi",
                          shortcut="Ctrl+Alt+H")
    def _say_hi():
        ctx.status.show("Hello from Python!", timeout_ms=3000)
        ctx.log.info("hello: Say Hi invoked")

    ctx.menus.add_item("Plugins/Hello/Say Hi", "hello.sayHi")

Comprimi la cartella come hello.mteplugin e installala tramite Preferenze → Estensioni → Installa estensione... — oppure deposita la cartella a mano nella tua cartella di plugin per utente (vedi Creazione dei pacchetti). Riavvia l'editor e Plugins → Hello → Say Hi compare nella barra dei menu.

Che cosa ti serve sulla macchina

  • Un interprete Python 3.9+ raggiungibile in uno di due modi:
    • nel PATH (py.exe, python.exe o python3.exe su Windows; python3 su macOS/Linux), oppure
    • indicato dalla variabile d'ambiente MTE_PYTHON (o un percorso assoluto a un python.exe, o un nome nudo da cercare nel PATH).
  • Nessun pacchetto pip: la libreria client mte della fase 1 viene distribuita con l'editor ed è aggiunta al sys.path per te.

L'editor registra nel log quale interprete ha scelto all'avvio:

PluginHost: MTE_PYTHON is not set; falling back to PATH.
PluginHost: located Python on PATH: py.exe -> C:/Windows/py.exe
PluginHost: Python plugin backend enabled; interpreter=..., worker=.../mte_python_host.py

Se vedi Python plugins disabled, passa a Risoluzione dei problemi.

Che cosa può fare il tuo plugin

Ogni voce qui sotto rimanda alla propria sezione dell'API:

Capacità Sezione
Registrare comandi (con scorciatoia da tastiera facoltativa) ctx.commands
Contribuire voci di menu e separatori ctx.menus
Sottoscrivere ogni evento dell'editor (documenti, testo, selezione, impostazioni, tema, area di lavoro, …) e pubblicare quelli dell'area di lavoro ctx.events e Documentazione degli eventi
Scrivere nel flusso diagnostico dell'editor ctx.log
Inviare messaggi temporanei alla barra di stato, possedere un segmento persistente della barra di stato ctx.status
Leggere/modificare buffer, selezioni (inclusi più cursori), cursore, file, ricerca, segnalibri, segni, evidenziazione degli URL, rientro, gruppi della vista divisa ctx.editor
Elencare i linguaggi, leggere / cambiare il linguaggio di un documento, contribuire una definizione di linguaggio ctx.languages
Rendere persistente la configurazione del plugin, leggere le impostazioni globali dell'applicazione (mte.keys), leggere le impostazioni per documento stratificate con .editorconfig ctx.settings / ctx.app_settings / ctx.document_settings
Pubblicare diagnostiche (sottolineature ondulate + glifi nel margine) ctx.diagnostics
Registrare colori tematizzabili per la tua interfaccia ctx.theme
Aprire la vista di confronto affiancata ctx.compare
Registrare un fornitore di completamenti (con una scadenza legata alla battuta) ctx.completions
Individuare la tua cartella scrivibile per plugin ctx.data_dir()
Aggiungere un pannello ancorabile dichiarativo, mostrarlo / nasconderlo da un comando ctx.docks e mte.ui
Aggiungere una pagina nelle Preferenze ctx.settings_page
Leggere / scrivere i controlli di un pannello a tempo di esecuzione ctx.ui
Ribaltare un segno di spunta persistente su una voce di menu ctx.menus.set_item_checked
Disattivare una voce di menu mentre il suo comando non può essere eseguito ctx.menus.set_item_enabled

Prossimi passi