Gå til innhold

Pakking og installasjon

Et Python-programtillegg er en mappe med en plugin.json og et Python-modul. Du kan installere et på to måter: pakke det som et .mteplugin-arkiv og bruke redigererens installasjonsprogram (anbefalt), eller legge mappen i en programtilleggsmappe for hånd.

Ta utgangspunkt i malen

Et startsett som er klart til å kopiere, ligger i Python/templates/plugin-template-python/ i arkivet — tre filer (plugin.json, main.py, README.md) pluss en CLAUDE.md som er rettet mot Claude. Gi mappen programtilleggets korte navn, rediger fire felter i plugin.json, og begynn å skrive register(ctx). Det installerte SDK-et leverer den samme malen under share/MTEPluginSDK/plugin-template-python/.

Programtilleggsmappens oppsett

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

Alt programtillegget trenger, må ligge inne i denne mappen. Underimporter virker, men må være flate — module-navn med punktum i plugin.json er en framtidig utvidelse.

Du kan gjerne legge til ekstra filer (README, LICENSE) — verten ser bort fra det den ikke kjenner igjen.

.mteplugin-pakker (anbefalt)

Pakk programtilleggets filer som en zip, og gi arkivet filendelsen .mteplugin (en alminnelig .zip virker også). Det tas imot begge formene:

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

Den ene omsluttende mappen — det naturlige resultatet av å pakke en mappe — fjernes: programtillegget installeres alltid i <Plugins>/<id>/, etter manifestets id, aldri etter arkivets mappenavn. Det er også derfor det å installere versjon 2 av et programtillegg erstatter versjon 1 i stedet for å ligge ved siden av den.

Installer den gjennom Innstillinger → Programtillegg → Installer programtillegg..., og start redigereren på nytt.

Installer bare pakker du stoler på

Installasjonsprogrammet kontrollerer at en pakke er strukturelt i orden (se nedenfor) — det gjør ikke et programtillegg du ikke stoler på, trygt å kjøre. Når et programtillegg først er lastet inn, kjører det med samme tilgang til filene dine, innstillingene dine og nettverket ditt som redigereren, og det kjører ikke i en sandkasse. Den statiske kontrollen av register(...) kjører ingen kode ved installasjonen, men programtilleggets kode kjører ved neste oppstart. Behandl en .mteplugin (og enhver oppsett- eller JSON-fil den leverer) som et ukjent program: installer den bare fra en kilde du stoler på. Se Programtillegg for hele advarselen.

Hva installasjonsprogrammet kontrollerer

Pakken kontrolleres fullt ut mot en kopi som kastes, før noe som helst på disken røres — en dårlig pakke kan aldri forstyrre en installasjon som alt finnes:

  1. plugin.json lar seg tolke, har en id, apiVersion passer til redigereren, entry er "python", og module er der.
  2. Arkivets innhold er trygt: ingen absolutte stier eller ..-poster, høyst 10 000 poster, høyst 256 MiB utpakket og minst én .py-fil.
  3. Etter utpakkingen til en midlertidig mappe finnes den erklærte <module>.py, og den erklærer en def register(...) på øverste nivå — den samme statiske kontrollen som oppdagelsen bruker. Det kjøres ingen Python-kode ved installasjonen.

Enhver feil gir et feilvindu som kan leses av mennesker, og lar redigererens programtillegg være urørt.

Å oppdatere og avinstallere

  • Å installere en pakke der id-en alt er installert, erstatter den. Er det programtillegget lastet inn akkurat nå, legges oppdateringen i kø og tas i bruk ved neste oppstart.
  • Avinstaller fra den samme innstillingssiden; fjerningen skjer også ved neste oppstart, mens ingenting er lastet inn.
  • Medfølgende (innebygde) programtillegg kan ikke overstyres av en installert pakke med samme id.

Å installere for hånd (å legge inn en mappe)

Redigereren oppdager programtillegg i to mapper ved hver oppstart:

  1. Medfølgende — ved siden av programfilen, i <exe-dir>/Plugins/. Innebygde programtillegg (for eksempel HelloPython) ligger her.
  2. Brukerens — per bruker og skrivbar. På Windows er det %LOCALAPPDATA%/MTE/Plugins/, på macOS ~/Library/Application Support/MTE/Plugins/ og på Linux ~/.local/share/MTE/Plugins/.

Begge mappene gås gjennom. Kommer den samme id-en fram i begge, vinner den første forekomsten (de medfølgende går foran). Start redigereren på nytt for å få med nye mapper — innlasting på nytt under kjøring støttes ikke.

To akseptable oppsett

Gjennomgangen leter etter plugin.json enten direkte i programtilleggsmappen (løst) eller inne i ett nivå av umiddelbare undermapper (en mappe per programtillegg):

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

En mappe per programtillegg er det anbefalte oppsettet; det er den formen installasjonsprogrammet gir.

Avhengigheter (pyRequires)

plugin.json kan erklære pip-krav som en tabell i selve filen:

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

Ved programtilleggets første oppstart setter redigereren opp et virtuelt miljø i <AppLocalData>/PluginVenv/<id>/ (python -m venv pluss pip install, som krever nettilgang den ene gangen) og kjører programtilleggets arbeider under det virtuelle miljøets tolk. Senere oppstarter gjenbruker det; endrer du pyRequires, settes det opp på nytt av seg selv (det virtuelle miljøet bærer et stempel av de kravene det ble bygget for).

  • Går oppsettet galt (intet nettverk, et feilstavet krav), blir programtillegget listet, men ikke lastet inn, med pip-feilen i loggen; neste oppstart prøver igjen.
  • Avinstallerer man et programtillegg, fjernes det virtuelle miljøet sammen med programtilleggsmappen (et virtuelt miljø er avledede data — det bygges opp igjen fra pyRequires hvis du noen gang installerer på nytt).

Maskiner uten nett eller med strenge regler

Lever et ferdigbygget virtuelt miljø inne i pakken som en venv/-mappe i programtilleggets rot. Er den der, vinner den over alt annet — det kjøres aldri pip. Bygg den på en maskin med samme operativsystem og arkitektur, for virtuelle miljøer kan ikke flyttes mellom plattformer.

Å legge avhengigheter inn (små, rene Python-avhengigheter)

For ett enkelt rent Python-modul virker det fortsatt å legge det inn i programtilleggsmappen, og det unngå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ærte tillatelser

plugin.json kan bære en permissions-tabell (for eksempel ["network"]). Innstillingssiden for programtillegg viser den i en skrivebeskyttet kolonne Tillatelser, så brukerne kan se hva et programtillegg erklærer om seg selv. Det er en erklæring og ikke en håndhevelse — kjøring i sandkasse er framtidig arbeid.

Hvor skrivbare data havner

Programtilleggsmappen rommer kode. Data under kjøringen (mellomlagre, oppsett per bruker, indekser) hører hjemme i en egen datamappe per programtillegg som verten styrer — ctx.data_dir() gir den absolutte stien dens tilbake. Skriv IKKE inn i programtilleggsmappen fra .py-en din under kjøringen; en avinstallasjon fjerner hele <Plugins>/<id>/-mappen, og skrivninger andre steder i programtilleggstreet ryddes aldri bort.

Å spre det til andre maskiner

Lever .mteplugin-filen — den er selvstendig og kontrolleres i den andre enden. En zip, en tarball eller en git-kloning av mappen inn i programtilleggsmappen per bruker virker også.

Å slå av og på

Innstillingssiden for programtillegg lister hvert oppdagede programtillegg (innebygde og Python-programtillegg sammen) med de samme kolonnene for opphav og status. Slår man et programtillegg av, blir det værende listet, men fabrikken dens kalles ikke ved oppstart — det startes ingen arbeider. Slå det på igjen, og start på nytt for å få det tilbake.