Verpakken en installeren¶

Een Python-plug-in is een map met een plugin.json en een Python-module. U kunt er op twee manieren een installeren: verpak haar als een .mteplugin-archief en gebruik het installatieprogramma van de editor (aanbevolen), of zet de map met de hand in een plug-inmap.

Begin bij het sjabloon

Een startpunt dat u kunt kopiëren staat in Python/templates/plugin-template-python/ in het repository — drie bestanden (plugin.json, main.py, README.md) plus een CLAUDE.md die op Claude gericht is. Hernoem de map naar de korte naam van uw plug-in, bewerk vier velden in plugin.json, en begin register(ctx) te schrijven. De geïnstalleerde SDK levert hetzelfde sjabloon mee onder share/MTEPluginSDK/plugin-template-python/.

Indeling van de plug-inmap¶

hello/
├── plugin.json      # required
└── main.py          # required; module name from plugin.json.module

Alles wat de plug-in nodig heeft moet binnen deze map staan. Deelimporten werken maar moeten plat zijn — namen van module met punten in plugin.json zijn een uitbreiding voor later.

U mag extra bestanden toevoegen (README, LICENSE) — de host negeert wat hij niet herkent.

`.mteplugin`-pakketten (aanbevolen)¶

Comprimeer de bestanden van de plug-in en geef het archief de extensie .mteplugin (een gewone .zip werkt ook). Beide vormen worden aanvaard:

hello.mteplugin              hello.mteplugin
├── plugin.json              └── hello-1.0.0/        # any folder name
└── main.py                      ├── plugin.json
                                 └── main.py

De enkele omhullende map — het natuurlijke gevolg van een map comprimeren — wordt weggenormaliseerd: de plug-in installeert altijd naar <Plugins>/<id>/, op de id uit het manifest en nooit op de mapnaam uit het archief. Dat is ook waarom versie 2 van een plug-in installeren versie 1 vervangt in plaats van ernaast te gaan staan.

Installeer haar via Voorkeuren → Plug-ins → Plug-in installeren... en herstart de editor.

Installeer alleen pakketten die u vertrouwt

Het installatieprogramma controleert of een pakket structureel deugt (zie hieronder) — het maakt een niet-vertrouwde plug-in niet veilig om te draaien. Eenmaal geladen draait een plug-in met dezelfde toegang tot uw bestanden, instellingen en netwerk als de editor, en zij zit niet in een sandbox. De statische sonde van register(...) voert bij het installeren geen code uit, maar de code van de plug-in draait wel bij de volgende start. Behandel een .mteplugin (en elk configuratie- of JSON-bestand dat zij meelevert) als een onbekend programma: installeer haar alleen uit een bron die u vertrouwt. Zie Plug-ins voor de volledige waarschuwing.

Wat het installatieprogramma valideert¶

Het pakket wordt volledig tegen een wegwerpkopie gevalideerd voordat er iets op de schijf aangeraakt wordt — een slecht pakket kan een bestaande installatie nooit verstoren:

plugin.json is te ontleden, heeft een id, apiVersion komt met de editor overeen, entry is "python", en module is aanwezig.
De inhoudsopgave van het archief is veilig: geen absolute paden en geen paden met .., hoogstens 10 000 items, hoogstens 256 MiB uitgepakt, en ten minste één .py-bestand.
Na het uitpakken naar een tijdelijke map bestaat de verklaarde <module>.py en verklaart zij een def register(...) op het hoogste niveau — dezelfde statische sonde die het vinden gebruikt. Bij het installeren wordt er geen Python-code uitgevoerd.

Elke mislukking levert een leesbaar foutvenster op en laat de plug-ins van de editor onaangeroerd.

Bijwerken en verwijderen¶

Een pakket installeren waarvan de id al geïnstalleerd is vervangt het. Is die plug-in op dat moment geladen, dan wordt de bijwerking klaargezet en bij de volgende start toegepast.
Verwijderen doet u op dezelfde Voorkeurenpagina; ook het verwijderen gebeurt bij de volgende start, terwijl er niets geladen is.
Meegeleverde (ingebouwde) plug-ins kunnen niet door een geïnstalleerd pakket met dezelfde id overschreven worden.

Met de hand installeren (een map neerzetten)¶

De editor vindt plug-ins bij elke start in twee mappen:

Meegeleverd — naast het uitvoerbare bestand, in <exe-dir>/Plugins/. Hier wonen de ingebouwde plug-ins (bijvoorbeeld HelloPython).
Gebruiker — per gebruiker, beschrijfbaar. Op Windows is dat %LOCALAPPDATA%/MTE/Plugins/, op macOS ~/Library/Application Support/MTE/Plugins/, op Linux ~/.local/share/MTE/Plugins/.

Beide mappen worden doorlopen. Verschijnt dezelfde id in beide, dan wint het eerste voorkomen (meegeleverd heeft voorrang). Herstart de editor om nieuwe mappen op te pikken — herladen tijdens het draaien wordt niet ondersteund.

Twee aanvaardbare indelingen¶

De doorloop zoekt plugin.json ofwel rechtstreeks in de plug-inmap (los) ofwel binnen één niveau van directe submap (map per plug-in):

Plugins/
├── plugin.json         # loose -- one plugin at the top level
├── main.py
└── hello/              # per-plugin folder -- one plugin
    ├── plugin.json
    └── main.py

De map per plug-in is de aanbevolen indeling; het is de vorm die het installatieprogramma oplevert.

Afhankelijkheden (`pyRequires`)¶

plugin.json mag pip-vereisten als een array in de regel verklaren:

"pyRequires": ["requests>=2.31"]

Bij de eerste start van de plug-in richt de editor een virtuele omgeving in in <AppLocalData>/PluginVenv/<id>/ (python -m venv + pip install, waarvoor die ene keer netwerktoegang nodig is) en draait hij de worker van de plug-in onder de interpreter van dat venv. Latere starts hergebruiken het; pyRequires wijzigen richt het automatisch opnieuw in (het venv draagt een stempel van de vereisten waarvoor het gebouwd is).

Mislukkingen bij het inrichten (geen netwerk, een verkeerd getypte vereiste) laten de plug-in opgesomd maar niet geladen, met de pip-fout in het logboek; de volgende start probeert het opnieuw.
Een plug-in verwijderen verwijdert haar venv samen met de plug-inmap (een venv is afgeleid gegeven — het wordt uit pyRequires herbouwd als u haar ooit opnieuw installeert).

Machines zonder netwerk / met een strak regime¶

Lever een vooraf gebouwd venv in het pakket mee, als een map venv/ in de wortel van de plug-in. Is die aanwezig, dan wint hij van alles — pip draait dan nooit. Bouw hem op een machine met hetzelfde besturingssysteem en dezelfde architectuur, want venvs zijn niet draagbaar tussen platformen.

Meeleveren (kleine afhankelijkheden in zuivere Python)¶

Voor één module in zuivere Python werkt meeleveren binnen de plug-inmap nog steeds en vermijdt het het venv-machinerie volledig:

# main.py
import os, sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "vendor"))

import your_dep

Verklaarde rechten¶

plugin.json mag een array permissions dragen (bijvoorbeeld ["network"]). De Voorkeurenpagina Plug-ins toont die in een alleen-lezen kolom Rechten, zodat gebruikers kunnen zien wat een plug-in over zichzelf verklaart. Het is een verklaring, geen afdwinging — de sandbox is werk voor later.

Waar beschrijfbare gegevens heen gaan¶

De plug-inmap bevat code. Gegevens tijdens het draaien (caches, configuratie per gebruiker, indexen) gaan naar een aparte gegevensmap per plug-in die de host beheert — ctx.data_dir() levert het absolute pad ervan op. Schrijf tijdens het draaien NIET vanuit uw .py in de plug-inmap; verwijderen haalt de hele map <Plugins>/<id>/ weg, en schrijfacties elders in de plug-inboom worden nooit opgeruimd.

Uitrollen op andere machines¶

Lever het .mteplugin-bestand — het is zelfvoorzienend en wordt aan de ontvangende kant gevalideerd. Een zip, tarball of git-kloon van de map in de plug-inmap per gebruiker werkt ook.

In- / uitschakelen¶

De Voorkeurenpagina Plug-ins somt elke gevonden plug-in op (inheems + Python, door elkaar) met dezelfde kolommen voor herkomst en status. Een plug-in uitschakelen houdt haar opgesomd maar voorkomt dat haar fabriek bij het starten aangeroepen wordt — er wordt geen worker gestart. Schakel haar weer in en herstart om haar terug te krijgen.