Risoluzione dei problemi¶

Il log diagnostico dell'editor contiene ogni riga rilevante. Su Windows si trova in %LOCALAPPDATA%/MTE/log/. Guarda il file più recente dopo aver avviato l'editor.

«Python plugins disabled»¶

Quattro varianti; il messaggio esatto ti dice quale.

`PluginHost: MTE_PYTHON is not set; falling back to PATH.`¶

Neutro: l'host sta per cercare Python nel PATH. Va bene, a meno che non sia seguito da «no Python interpreter found».

`PluginHost: MTE_PYTHON path '<value>' does not exist.`¶

Hai impostato MTE_PYTHON su un percorso con un separatore di cartella, ma il file a quel percorso manca. Rimedio: puntalo al vero python.exe.

$env:MTE_PYTHON = "C:\Users\me\AppData\Local\Programs\Python\Python313\python.exe"

`PluginHost: MTE_PYTHON='<name>' not found on PATH.`¶

Hai impostato MTE_PYTHON su un nome nudo (senza separatore), ma quel nome non è nel PATH. Rimedio: aggiungi la cartella al PATH oppure usa la forma con percorso completo qui sopra.

`PluginHost: no Python interpreter found (…); Python plugins disabled.`¶

Né MTE_PYTHON né alcuno dei nomi standard della piattaforma (py.exe, python.exe, python3.exe su Windows; python3 su macOS/Linux) è nel PATH. Installa Python 3.9+ e aggiungilo al PATH oppure imposta MTE_PYTHON.

Verifica che cosa vede attualmente il PATH, dalla stessa shell da cui hai avviato l'editor:

(Get-Command py.exe -ErrorAction SilentlyContinue).Source
(Get-Command python.exe -ErrorAction SilentlyContinue).Source

«python worker script … not found»¶

L'editor registra nel log:

PluginHost: python worker script '<path>' not found; Python plugins disabled.

Lo script host del worker (mte_python_host.py) non è accanto all'eseguibile. Succede quando si esegue una build dell'editor in cui il passo POST_BUILD di predisposizione di Python/ è stato saltato. Ricompila:

cmake --build Build\.cmake\x64-debug --target ModularTextEditor --config Debug

Conferma che il file esista dopo la compilazione:

Test-Path Build\MTE_Windows_d\Python\host\mte_python_host.py

Plugin elencato ma non caricato¶

Apri la pagina delle estensioni (Preferenze → Estensioni). Cause comuni:

Sintomo	Riga nel log	Causa
Etichetta di discordanza di `apiVersion` accanto al nome	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Il tuo `plugin.json` dichiara una `apiVersion` diversa da quella che l'editor in esecuzione supporta.
Il plugin appare disattivato	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Qualcuno l'ha disabilitato nella pagina Plugin. Riabilitalo e riavvia.
Del tutto assente	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	La sonda statica ha respinto il tuo modulo. Sposta `register` al primo livello (colonna 0).
Del tutto assente	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` è `"main"` ma non c'è alcun `main.py` accanto.
Del tutto assente	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Aggiungi `id`.

Il comando non scatta¶

Hai cliccato la voce di menu / premuto la scorciatoia ma non è successo nulla.

Controlla se ci sono righe [python:<your.id>] … prodotte dal tuo ctx.log.info(...). Se mancano, la callback non ha mai raggiunto il worker.
Controlla se ci sono righe [worker stderr] …. Le eccezioni dentro la tua callback finiscono lì.
Conferma che l'id del comando nella tua chiamata add_item corrisponda alla lettera al tuo command(id=...): il confronto tra stringhe è esatto.

Errori «worker died»¶

L'host registra nel log:

… worker exited with code N
… worker crashed (code N)

Il sottoprocesso Python si è concluso. Cerca sopra quella riga lo stderr del worker: Python stampa le tracce su stderr e l'host le inoltra come [worker stderr] …. Un crash corrisponde quasi sempre a un'eccezione non catturata in register() oppure in una callback che è rientrata ricorsivamente nell'API C di Python.

Riprenditi correggendo il codice e riavviando l'editor. L'host non riavvia automaticamente un worker andato in crash.

Predisposizione del venv fallita (plugin elencato ma non caricato)¶

Un plugin che dichiara pyRequires ottiene un ambiente virtuale predisposto al primo avvio. Quando quello fallisce, il log ne riporta il motivo:

PluginHost: 'org.example.x' needs a venv (no venv provisioned yet).
PythonRuntime: provisioning venv at '...' (1 requirement(s)); ...
PluginHost: venv provisioning for 'org.example.x' failed: pip install
failed: ... No matching distribution found for no-such-package ...

Cause comuni: nessuna rete al primo avvio, un requisito scritto male, un pacchetto senza wheel per la versione di Python dell'utente. Correggi la causa e riavvia: la predisposizione riprova a ogni lancio finché non riesce (il venv viene marcato come completo solo alla fine). Per forzare una ricostruzione pulita, elimina <AppLocalData>/PluginVenv/<plugin-id>/. Le macchine offline possono invece distribuire un venv/ precostruito dentro il pacchetto — vedi Creazione dei pacchetti.

L'installer ha rifiutato il mio `.mteplugin`¶

Ogni rifiuto arriva con un messaggio di finestra specifico; i più comuni:

Il messaggio dice…	Rimedio
manca il campo obbligatorio `'module'`	Aggiungi `"module": "main"` a `plugin.json`.
nessun modulo Python (file .py)	L'archivio non ha alcun `.py`: hai compresso la cartella giusta?
non contiene il modulo Python dichiarato `'X.py'`	`module` in `plugin.json` non corrisponde al nome del file nell'archivio.
non dichiara un `def register(...)` di primo livello	Stessa regola dell'individuazione: `def register(` deve iniziare alla colonna 0 di `<module>.py`.
punta alla versione N dell'API	Ricompila per l'`apiVersion` corrente (vedi plugin.json).
percorso non sicuro / troppo grande / troppi file	L'archivio ha fatto scattare una protezione — reimpacchettalo in modo semplice (nessuna voce `..`, < 256 MiB una volta estratto).

Il pacchetto viene validato su una copia temporanea, quindi un'installazione rifiutata non tocca mai un plugin esistente.

Non viene registrato proprio nulla nel log¶

Conferma che il tuo gestore sia davvero installato. register(ctx) viene eseguito esattamente una volta per plugin a ogni lancio dell'editor. Se register non è definito al primo livello del modulo, la sonda statica respinge il plugin prima ancora che venga caricato (vedi «Plugin elencato ma non caricato» qui sopra).

Aggiungi una riga di avvio al tuo register:

def register(ctx):
    ctx.log.info("wordcount: register() ran")
    # …

Se non la vedi nel log, il worker non sta eseguendo il tuo register: cerca il motivo nelle righe di log precedenti.

Dove guardare poi¶

Log lato editor: %LOCALAPPDATA%/MTE/log/…
stderr del worker: lo stesso log, con l'etichetta [worker stderr]
Documentazione: API ctx, Eventi, plugin.json
Note di progettazione: PYTHON_PLUGIN_ARCHITECTURE.md (radice del repository)