Pakning og installation¶

Et Python-udvidelsesmodul er en mappe med en plugin.json og et Python-modul. Du kan installere et på to måder: pakke det som et .mteplugin-arkiv og bruge editorens installationsprogram (anbefales), eller lægge mappen i en udvidelsesmodulmappe i hånden.

Tag udgangspunkt i skabelonen

Et startsæt, der er klar til at kopiere, ligger i Python/templates/plugin-template-python/ i arkivet — tre filer (plugin.json, main.py, README.md) plus en CLAUDE.md, der er rettet mod Claude. Omdøb mappen til dit udvidelsesmoduls korte navn, redigér fire felter i plugin.json, og gå i gang med at skrive register(ctx). Det installerede SDK leverer den samme skabelon under share/MTEPluginSDK/plugin-template-python/.

Udvidelsesmodulmappens layout¶

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

Alt, hvad udvidelsesmodulet har brug for, skal ligge inde i denne mappe. Underimport virker, men skal være flad — module-navne med punktummer i plugin.json er en fremtidig udvidelse.

Du må gerne tilføje ekstra filer (README, LICENSE) — værten ser bort fra det, den ikke genkender.

`.mteplugin`-pakker (anbefales)¶

Pak udvidelsesmodulets filer som en zip, og giv arkivet filendelsen .mteplugin (en almindelig .zip virker også). Der tages imod begge former:

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

Den enkelte omsluttende mappe — det naturlige resultat af at pakke en mappe — fjernes: udvidelsesmodulet installeres altid i <Plugins>/<id>/ efter manifestets id, aldrig efter arkivets mappenavn. Det er også derfor, at det at installere version 2 af et modul erstatter version 1 i stedet for at ligge ved siden af den.

Installér den via Indstillinger → Udvidelsesmoduler → Installér udvidelsesmodul..., og genstart editoren.

Installér kun pakker, du har tillid til

Installationsprogrammet kontrollerer, at en pakke er strukturelt i orden (se nedenfor) — det gør ikke et modul, du ikke har tillid til, trygt at køre. Når et udvidelsesmodul først er indlæst, kører det med samme adgang til dine filer, indstillinger og dit netværk som editoren og kører ikke i sandkasse. Den statiske efterprøvning af register(...) kører ingen kode ved installationen, men modulets kode kører ved næste start. Behandl en .mteplugin (og enhver konfigurations- eller JSON-fil, den leverer) som et ukendt program: installér den kun fra en kilde, du har tillid til. Se Udvidelsesmoduler for hele advarslen.

Hvad installationsprogrammet efterprøver¶

Pakken efterprøves fuldt ud mod en kopi, der kastes væk, inden noget som helst på disken røres — en dårlig pakke kan aldrig forstyrre en eksisterende installation:

plugin.json kan fortolkes, har et id, apiVersion passer til editoren, entry er "python", og module er der.
Arkivets indhold er trygt: ingen absolutte stier eller ..-poster, højst 10 000 poster, højst 256 MiB udpakket og mindst én .py-fil.
Efter udpakningen til en midlertidig mappe findes den erklærede <module>.py og erklærer en def register(...) på øverste niveau — den samme statiske efterprøvning, som opdagelsen bruger. Der køres ingen Python-kode ved installationen.

Enhver fejl giver et fejlvindue, der kan læses af mennesker, og efterlader editorens udvidelsesmoduler urørte.

At opdatere og afinstallere¶

At installere en pakke, hvis id allerede er installeret, erstatter den. Er det modul indlæst lige nu, lægges opdateringen i kø og anvendes ved næste start.
Afinstallér fra den samme indstillingsside; fjernelsen sker også ved næste start, mens intet er indlæst.
Medleverede (indbyggede) udvidelsesmoduler kan ikke tilsidesættes af en installeret pakke med det samme id.

At installere i hånden (at lægge en mappe ind)¶

Editoren opdager udvidelsesmoduler i to mapper ved hver opstart:

Medleverede — ved siden af programfilen, i <exe-dir>/Plugins/. Indbyggede moduler (f.eks. HelloPython) ligger her.
Brugerens — pr. bruger og skrivbar. På Windows er det %LOCALAPPDATA%/MTE/Plugins/, på macOS ~/Library/Application Support/MTE/Plugins/ og på Linux ~/.local/share/MTE/Plugins/.

Begge mapper gennemsøges. Optræder det samme id i begge, vinder den første forekomst (de medleverede går forud). Genstart editoren for at få nye mapper med — genindlæsning under kørslen understøttes ikke.

To acceptable layout¶

Gennemsøgningen leder efter plugin.json enten direkte i udvidelsesmodulmappen (løst) eller inde i ét niveau af umiddelbare undermapper (en mappe pr. modul):

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

En mappe pr. udvidelsesmodul er det anbefalede layout; det er den form, installationsprogrammet frembringer.

Afhængigheder (`pyRequires`)¶

plugin.json må erklære pip-krav som en tabel i selve filen:

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

Ved udvidelsesmodulets første start sætter editoren et virtuelt miljø op i <AppLocalData>/PluginVenv/<id>/ (python -m venv plus pip install, hvilket kræver netadgang den ene gang) og kører modulets arbejder under det virtuelle miljøs fortolker. Senere starter genbruger det; ændrer du pyRequires, sættes det op på ny af sig selv (det virtuelle miljø bærer et stempel af de krav, det blev bygget til).

Går opsætningen galt (intet netværk, et forkert stavet krav), bliver modulet opregnet, men ikke indlæst, med pip-fejlen i loggen; næste start forsøger igen.
Afinstallerer man et udvidelsesmodul, fjernes dets virtuelle miljø sammen med modulmappen (et virtuelt miljø er afledte data — det bygges op igen ud fra pyRequires, hvis du nogensinde installerer modulet igen).

Maskiner uden net eller med stramme regler¶

Lever et færdigbygget virtuelt miljø inde i pakken som en venv/-mappe i modulets rod. Er den der, vinder den over alt andet — der køres aldrig pip. Byg den på en maskine med samme styresystem og arkitektur, for virtuelle miljøer kan ikke flyttes mellem platforme.

At lægge afhængigheder ind (små, rene Python-afhængigheder)¶

For et enkelt rent Python-modul virker det stadig at lægge det ind i modulmappen, og det undgår hele maskineriet med virtuelle miljøer:

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

import your_dep

Erklærede tilladelser¶

plugin.json må bære en permissions-tabel (f.eks. ["network"]). Indstillingssiden for udvidelsesmoduler viser den i en skrivebeskyttet kolonne Tilladelser, så brugerne kan se, hvad et modul erklærer om sig selv. Det er en erklæring og ikke en håndhævelse — sandkassekørsel er fremtidigt arbejde.

Hvor skrivbare data lander¶

Udvidelsesmodulmappen rummer kode. Data under kørslen (mellemlagre, opsætning pr. bruger, indekser) hører til i en særskilt datamappe pr. modul, som værten står for — ctx.data_dir() giver dens absolutte sti tilbage. Skriv IKKE ind i modulmappen fra din .py under kørslen; en afinstallation fjerner hele <Plugins>/<id>/-mappen, og skrivninger andre steder i modultræet ryddes aldrig op.

At udbrede til andre maskiner¶

Lever .mteplugin-filen — den er selvstændig og efterprøves i den anden ende. En zip, en tarball eller en git-klon af mappen ind i udvidelsesmodulmappen pr. bruger virker også.

At slå til og fra¶

Indstillingssiden for udvidelsesmoduler opregner hvert opdaget modul (indbyggede og Python-moduler sammen) med de samme kolonner for oprindelse og status. Slår man et modul fra, bliver det ved med at være opregnet, men dets fabrik kaldes ikke ved opstart — der startes ingen arbejder. Slå det til igen, og genstart for at få det tilbage.