Vianetsintä¶

Editorin diagnostiikkaloki sisältää jokaisen olennaisen rivin. Windowsissa se on kansiossa %LOCALAPPDATA%/MTE/log/. Katso uusinta tiedostoa editorin käynnistämisen jälkeen.

»Python plugins disabled«¶

Neljä muunnelmaa; täsmällinen viesti kertoo, mikä niistä on kyseessä.

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

Neutraali — isäntä on aikeissa etsiä Pythonia PATH-muuttujasta. Tämä on hyvä, ellei perässä tule tekstiä »no Python interpreter found«.

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

Asetit muuttujan MTE_PYTHON polkuun, jossa on hakemistoerotin, mutta tuossa polussa olevaa tiedostoa ei ole. Korjaus: osoita oikeaan python.exe-tiedostoon.

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

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

Asetit muuttujan MTE_PYTHON pelkäksi nimeksi (ilman erotinta), mutta tuota nimeä ei ole PATH-muuttujassa. Korjaus: joko lisää kansio PATH-muuttujaan tai käytä yllä olevaa koko polun muotoa.

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

Sen paremmin MTE_PYTHON kuin mikään alustan vakionimistä (py.exe, python.exe, python3.exe Windowsissa; python3 macOS:ssä ja Linuxissa) ei ole PATH-muuttujassa. Asenna Python 3.9+ ja joko lisää se PATH-muuttujaan tai aseta MTE_PYTHON.

Tarkista, mitä PATH tällä hetkellä näkee, samasta komentotulkista, josta käynnistit editorin:

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

»python worker script … not found«¶

Editori kirjaa:

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

Työntekijän isäntäskripti (mte_python_host.py) ei ole suoritettavan tiedoston vieressä. Näin käy, kun ajetaan editorikäännöstä, jonka Python/-valmistelun POST_BUILD-vaihe ohitettiin. Käännä uudelleen:

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

Vahvista, että tiedosto on olemassa käännöksen jälkeen:

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

Liitännäinen luetellaan muttei ladata¶

Avaa liitännäissivu (Asetukset → Liitännäiset). Yleisiä syitä:

Oire	Rivi lokissa	Syy
Ristiriitainen `apiVersion` -merkintä nimen vieressä	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	`plugin.json`-tiedostosi ilmoittaa eri `apiVersion`-arvon kuin mitä käynnissä oleva editori tukee.
Liitännäinen näkyy harmaana	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Joku poisti sen käytöstä liitännäissivulla. Ota se takaisin käyttöön ja käynnistä uudelleen.
Puuttuu kokonaan	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	Staattinen tarkistus hylkäsi moduulisi. Siirrä funktio `register` ylätasolle (sarakkeeseen 0).
Puuttuu kokonaan	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` on `"main"`, mutta sen vieressä ei ole tiedostoa `main.py`.
Puuttuu kokonaan	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Lisää `id`.

Komento ei laukea¶

Napsautit valikkokohtaa tai painoit pikanäppäintä, muttei mitään tapahtunut.

Tarkista, onko lokissa rivejä [python:<your.id>] … funktiokutsustasi ctx.log.info(...). Jos ne puuttuvat, takaisinkutsu ei koskaan saavuttanut työntekijää.
Tarkista, onko lokissa rivejä [worker stderr] …. Takaisinkutsusi sisäiset poikkeukset päätyvät sinne.
Vahvista, että add_item-kutsusi komentotunniste vastaa sanatarkasti kutsuasi command(id=...) — merkkijonovertailu on täsmällinen.

»worker died« -virheet¶

Isäntä kirjaa:

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

Python-aliprosessi päättyi. Katso tuon rivin yläpuolelta työntekijän stderr-tulostetta — Python tulostaa jäljitykset stderriin ja isäntä välittää ne muodossa [worker stderr] …. Kaatuminen vastaa lähes aina nappaamatonta poikkeusta funktiossa register() tai takaisinkutsussa, joka palasi rekursiivisesti Pythonin C-API:in.

Toivu korjaamalla koodi ja käynnistämällä editori uudelleen. Isäntä ei käynnistä kaatunutta työntekijää automaattisesti uudelleen.

Virtuaaliympäristön valmistelu epäonnistui (liitännäinen luetellaan muttei ladata)¶

Liitännäinen, joka ilmoittaa kentän pyRequires, saa virtuaaliympäristön valmisteltuna ensimmäisellä käynnistyksellään. Kun se epäonnistuu, loki kantaa syyn:

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 ...

Yleisiä syitä: ei verkkoa ensimmäisellä käynnistyksellä, väärin kirjoitettu vaatimus tai paketti, jolle ei ole wheel-tiedostoa käyttäjän Python-versiolle. Korjaa syy ja käynnistä uudelleen — valmistelua yritetään uudelleen joka käynnistyksellä, kunnes se onnistuu (virtuaaliympäristö leimataan valmiiksi vasta lopussa). Pakottaaksesi puhtaan uudelleenrakennuksen poista kansio <AppLocalData>/PluginVenv/<plugin-id>/. Verkottomat koneet voivat sen sijaan toimittaa valmiiksi rakennetun venv/-kansion paketin sisällä — katso Paketointi.

Asennusohjelma hylkäsi `.mteplugin`-tiedostoni¶

Jokaisen hylkäyksen mukana tulee tarkka ikkunaviesti; yleisimmät ovat:

Viesti sanoo …	Korjaus
puuttuu pakollinen kenttä `'module'`	Lisää `"module": "main"` tiedostoon `plugin.json`.
ei Python-moduulia (.py-tiedostoa)	Arkistossa ei ole yhtään `.py`-tiedostoa — pakkasitko oikean kansion?
ei sisällä ilmoitettua Python-moduulia `'X.py'`	`module` tiedostossa `plugin.json` ei vastaa arkistossa olevaa tiedostonimeä.
ei ilmoita ylätason funktiota `def register(...)`	Sama sääntö kuin etsinnässä: `def register(` täytyy alkaa tiedoston `<module>.py` sarakkeesta 0.
kohdistuu API-versioon N	Käännä uudelleen nykyistä `apiVersion`-arvoa vasten (katso plugin.json).
turvaton polku / liian suuri / liikaa tiedostoja	Arkisto laukaisi turvasuojan — paketoi se uudelleen tavallisesti (ei `..`-kohtia, alle 256 MiB purettuna).

Paketti tarkistetaan kertakäyttöistä kopiota vasten, joten hylätty asennus ei koskaan kosketa olemassa olevaa liitännäistä.

Mitään ei kirjata lainkaan¶

Vahvista, että käsittelijäsi on todella asennettu. register(ctx) ajetaan täsmälleen kerran liitännäistä kohti editorin käynnistystä kohti. Jos funktiota register ei ole määritelty moduulin ylätasolla, staattinen tarkistus hylkää liitännäisen ennen kuin sitä ladataan lainkaan (katso »Liitännäinen luetellaan muttei ladata« yllä).

Lisää käynnistysrivi funktioosi register:

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

Jos et näe tuota lokissa, työntekijä ei aja funktiotasi register — tarkista aiemmista lokimerkinnöistä syy.

Mistä katsoa seuraavaksi¶

Editorin puolen loki: %LOCALAPPDATA%/MTE/log/…
Työntekijän stderr: sama loki, merkittynä tunnisteella [worker stderr]
Dokumentaatio: ctx-API, Tapahtumat, plugin.json
Suunnittelumuistiinpanot: PYTHON_PLUGIN_ARCHITECTURE.md (arkiston juuri)