Přeskočit obsah

Balení a instalace

Zásuvný modul v Pythonu je složka s plugin.json a modulem Pythonu. Nainstalovat jej můžete dvěma způsoby: zabalit jej jako archiv .mteplugin a použít instalátor editoru (doporučeno), nebo složku ručně vložit do adresáře se zásuvnými moduly.

Začněte od šablony

Připravený startovací balíček ke zkopírování leží v repozitáři v Python/templates/plugin-template-python/ — tři soubory (plugin.json, main.py, README.md) plus CLAUDE.md určený Claudovi. Přejmenujte složku na krátký název svého modulu, upravte čtyři pole v plugin.json a začněte psát register(ctx). Nainstalovaná sada SDK dodává tutéž šablonu pod share/MTEPluginSDK/plugin-template-python/.

Rozvržení složky modulu

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

Vše, co modul potřebuje, musí sedět uvnitř této složky. Dílčí importy fungují, ale musí být ploché — tečkové názvy v module v plugin.json jsou budoucím rozšířením.

Můžete přidat další soubory (README, LICENSE) — hostitel ignoruje, co nezná.

Balíčky .mteplugin (doporučeno)

Soubory modulu zazipujte a archivu dejte příponu .mteplugin (funguje i obyčejný .zip). Přijímají se oba tvary:

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

Jediná obalová složka — přirozený výsledek zazipování složky — se odstraní: modul se vždy instaluje do <Plugins>/<id>/, podle id z manifestu, nikdy podle názvu složky v archivu. Proto také instalace verze 2 modulu nahradí verzi 1, místo aby seděla vedle ní.

Nainstalujte jej přes Předvolby → Zásuvné moduly → Instalovat zásuvný modul... a restartujte editor.

Instalujte jen balíčky, kterým důvěřujete

Instalátor ověří, že je balíček strukturálně v pořádku (viz níže) — neudělá nedůvěryhodný modul bezpečným ke spuštění. Jakmile se načte, běží modul se stejným přístupem k vašim souborům, nastavení a síti jako editor a není izolovaný. Statická sonda na register(...) při instalaci žádný kód nespouští, ale kód modulu se spustí při příštím startu. Berte .mteplugin (a jakékoli konfigurační soubory či soubory JSON, které s sebou nese) jako neznámý program: instalujte jej jen ze zdroje, kterému důvěřujete. Úplné varování najdete v části Zásuvné moduly.

Co instalátor ověřuje

Balíček se plně ověří proti jednorázové kopii dřív, než se cokoli na disku dotkne — špatný balíček nemůže nikdy narušit stávající instalaci:

  1. plugin.json se zpracuje, má id, apiVersion odpovídá editoru, entry je "python" a module je přítomen.
  2. Výpis archivu je bezpečný: žádné absolutní položky ani položky s .., nejvýš 10 000 položek, nejvýš 256 MiB po rozbalení a alespoň jeden soubor .py.
  3. Po rozbalení do pracovního adresáře deklarovaný <module>.py existuje a deklaruje def register(...) na nejvyšší úrovni — tatáž statická sonda, jakou používá hledání. Při instalaci se nespouští žádný kód Pythonu.

Jakékoli selhání vyústí v čitelné chybové okno a zásuvné moduly editoru zůstanou nedotčené.

Aktualizace a odinstalace

  • Instalace balíčku, jehož id je už nainstalováno, jej nahradí. Je-li onen modul právě načtený, aktualizace se připraví a uplatní při příštím spuštění.
  • Odinstalujte z téže stránky Předvoleb; odebrání se také děje při příštím spuštění, kdy není nic načteno.
  • Dodávané (vestavěné) moduly nelze přebít nainstalovaným balíčkem se stejným id.

Ruční instalace (vložení složky)

Editor hledá zásuvné moduly při každém spuštění ve dvou adresářích:

  1. Dodávané — vedle spustitelného souboru, v <exe-dir>/Plugins/. Bydlí zde vestavěné moduly (například HelloPython).
  2. Uživatelské — pro uživatele, zapisovatelné. Ve Windows je to %LOCALAPPDATA%/MTE/Plugins/, na macOS ~/Library/Application Support/MTE/Plugins/, v Linuxu ~/.local/share/MTE/Plugins/.

Prohledávají se oba adresáře. Objeví-li se totéž id v obou, vyhrává první výskyt (dodávané mají přednost). Aby se nové složky převzaly, editor restartujte — načtení za běhu podporováno není.

Dvě přijatelná rozvržení

Prohledávání hledá plugin.json buď přímo v adresáři modulů (volně), nebo uvnitř jedné úrovně bezprostředního podadresáře (složka na modul):

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

Složka na modul je doporučeným rozvržením; je to tvar, jaký vytváří instalátor.

Závislosti (pyRequires)

plugin.json může deklarovat požadavky pip jako vložené pole:

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

Při prvním spuštění modulu editor připraví virtuální prostředí v <AppLocalData>/PluginVenv/<id>/ (python -m venv + pip install, což jednorázově potřebuje přístup k síti) a pracovníka modulu spustí pod interpretem tohoto prostředí. Další spuštění jej používají znovu; změna pyRequires je připraví automaticky znovu (prostředí nese otisk požadavků, pro které bylo postaveno).

  • Selhání přípravy (žádná síť, překlep v požadavku) nechá modul uvedený, ale nenačtený, s chybou pip v protokolu; další spuštění to zkusí znovu.
  • Odinstalace modulu odstraní jeho virtuální prostředí spolu se složkou modulu (prostředí je odvozenými daty — pokud modul někdy znovu nainstalujete, sestaví se z pyRequires znovu).

Stroje bez sítě a uzamčené

Dodejte uvnitř balíčku předem sestavené virtuální prostředí jako složku venv/ v kořeni modulu. Je-li přítomné, vyhrává nad vším — pip se nikdy nespustí. Sestavte je na stroji s týmž operačním systémem a architekturou, protože virtuální prostředí nejsou mezi platformami přenositelná.

Vendoring (malé závislosti v čistém Pythonu)

U jediného modulu v čistém Pythonu funguje vendoring uvnitř složky modulu dál a zcela se vyhne mašinerii virtuálních prostředí:

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

import your_dep

Deklarovaná oprávnění

plugin.json může nést pole permissions (například ["network"]). Stránka Předvolby → Zásuvné moduly je zobrazuje v sloupci Oprávnění jen ke čtení, aby uživatelé viděli, co o sobě modul deklaruje. Je to deklarace, nikoli vynucení — izolace je prací do budoucna.

Kam jdou zapisovatelná data

Adresář modulů obsahuje kód. Data za běhu (mezipaměti, konfigurace pro uživatele, indexy) jdou do samostatného datového adresáře daného modulu, který spravuje hostitel — ctx.data_dir() vrací jeho absolutní cestu. Do adresáře modulů ze svého .py za běhu NEZAPISUJTE; odinstalace odstraní celou složku <Plugins>/<id>/ a zápisy provedené jinde ve stromu modulů se nikdy neuklízejí.

Nasazení na další stroje

Dodejte soubor .mteplugin — je soběstačný a na přijímající straně se ověří. Funguje i zip, tarball nebo git clone složky do uživatelského adresáře modulů.

Zapnutí a vypnutí

Stránka Předvolby → Zásuvné moduly vypisuje každý nalezený modul (nativní i pythonovské dohromady) s týmiž sloupci o původu a stavu. Vypnutí modulu jej ponechá uvedený, ale zabrání vyvolání jeho továrny při spuštění — žádný pracovník se nespustí. Zapněte jej znovu a restartujte, čímž jej vrátíte.