Reference `plugin.json`¶

Každý zásuvný modul v Pythonu deklaruje svou identitu, vstupní bod a umístění v nabídkové liště v souboru plugin.json vedle svého main.py. Je to totéž schéma, jaké používá strana C++; jen pole entry a module jsou specifická pro Python.

Příklad¶

{
  "id":          "org.example.wordcount",
  "name":        "Word Count",
  "version":     "1.0.0",
  "vendor":      "Example, Inc.",
  "description": "Counts words and characters in the active document.",
  "apiVersion":  1,
  "entry":       "python",
  "module":      "main",
  "pyRequires":  [],
  "order":       900,
  "menus": [
    { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
  ]
}

Pole¶

Povinná¶

Pole	Typ	Poznámky
`id`	řetězec	Jedinečný identifikátor v obráceném zápisu DNS. Používá se všude — zapnutí a vypnutí, řádky protokolu, nastavení modulu. Nesmí se mezi verzemi měnit.
`apiVersion`	celé číslo	Musí se rovnat hodnotě `MTE_PLUGIN_API_VERSION` hostitele. Aktuálně `1`. Neshoda se projeví na stránce Zásuvné moduly a modul je uveden, ale nenačten.
`entry`	řetězec	Musí být `"python"`, aby se směroval přes backend v Pythonu. `"native"` nebo vynechání směruje přes zavaděč Qt.
`module`	řetězec	Název modulu Pythonu, který obsahuje `register(ctx)`. Je-li `"main"`, hledá pracovník uvnitř složky modulu soubor `main.py`. Tečkové názvy balíků (`"src.main"`) jsou budoucím rozšířením — fáze 1 podporuje pouze ploché názvy.

Doporučená¶

Pole	Typ	Poznámky
`name`	řetězec	Čitelný zobrazovaný název ukazovaný na stránce Zásuvné moduly.
`version`	řetězec	Semver; jinak volný tvar.
`vendor`	řetězec	Autor nebo organizace. Zobrazuje se na stránce Zásuvné moduly.
`description`	řetězec	Jeden až dva řádky. Zobrazuje se na stránce Zásuvné moduly.

Volitelná¶

Pole	Typ	Poznámky
`order`	celé číslo	Pořadí načítání napříč moduly; nižší se načte dřív. Výchozí `1000`. Shody rozhoduje `id`. `requires` má přednost.
`requires`	pole řetězců	ID modulů, bez kterých tento modul nemůže fungovat (nativních i Pythonových stejně), například `["org.mte.lsp"]` — nejde o balíčky pip, ty patří do `pyRequires`. Spouštějí se před tímto modulem bez ohledu na `order`; když některý chybí, je vypnutý, blokovaný licencí nebo se nenačetl, tento modul se vůbec nespustí a Předvolby → Zásuvné moduly řeknou, který potřebuje a proč. Stejný význam jako u nativního modulu.
`apiMinorVersion`	celé číslo	Nejnižší minor verze API hostitele, kterou tento modul potřebuje (výchozí `0`). Modul v Pythonu nemá zkompilované `info()`, takže je to jeho jediné prohlášení: uveďte minor verzi nejnovějšího volání, které používáte. Starší hostitel zobrazí modul se stavem »Vyžaduje novější verzi aplikace OctoEdit« a nespustí ho.
`menus`	pole objektů	Viz níže.
`pyRequires`	pole řetězců	Řetězce požadavků pip (například `["requests>=2.31"]`). Při prvním spuštění modulu editor připraví virtuální prostředí pro tento modul, nainstaluje do něj tyto balíčky přes pip a pracovníka modulu pod ním spustí (viz Balení). Nezřetězcové a prázdné položky se přeskočí.
`permissions`	pole řetězců	Hrubé deklarace schopností (například `["network"]`), zobrazené jen ke čtení ve sloupci Oprávnění v Předvolby → Zásuvné moduly, aby uživatelé viděli, co o sobě modul tvrdí. Pouze deklarace — zatím se nevynucuje.
`thirdParty`	pole objektů	Komponenty třetích stran, které modul přibaluje, pro uvedení autorství v okně O aplikaci. Každá položka: `name` (povinné), `license`, `url`, `file`. Text licence pojmenovaný v `file` dodejte vedle modulu pod `Plugins/Licenses/<id>/`. Viz níže.

`menus`¶

Každá položka deklaruje jednu nabídku nejvyšší úrovně, do které modul přispívá, a nastavuje její pozici. Opakujte jeden objekt na každou nabídku nejvyšší úrovně, které se dotýkáte (Tools, Plugins, Help a podobně).

"menus": [
  { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
]

Pole	Typ	Poznámky
`title`	řetězec, povinné	Popisek nabídky nejvyšší úrovně, pod kterou položka bydlí (`Plugins`, `Tools`, …). Musí odpovídat nejlevějšímu segmentu cest, které předáváte do `ctx.menus.add_item()`.
`barPriority`	celé číslo, volitelné	Pořadí zleva doprava v nabídkové liště. Nižší = dál vlevo. Nabídky jádra mají pevné priority s rozestupy po 100 (File `100`, Edit `200`, …, Window `600`); `570` umístí vaši podnabídku poblíž pozice `Plugins`. Opakuje se napříč moduly mířícími na tutéž nabídku nejvyšší úrovně; vyhrává poslední, což je v pořádku, protože je to idempotentní.
`itemPriority`	celé číslo, volitelné	Svislé pořadí celého bloku vašeho modulu uvnitř koncové nabídky. Výchozí `1000`. Nižší = výš.

Jednotlivé položky zde NEUVÁDÍTE — ty přidává ctx.menus.add_item() za běhu. menus se týká pouze umístění v nabídkové liště.

`thirdParty`¶

Deklarujte každou komponentu třetí strany, kterou váš modul přibaluje, aby ji okno O aplikaci mohlo uvést. Každá položka:

"thirdParty": [
  { "name": "SomeLib", "license": "MIT",
    "url": "https://example.com/", "file": "SomeLib-LICENSE.txt" }
]

Pole	Typ	Poznámky
`name`	řetězec, povinné	Komponenta. Položky bez neprázdného názvu se zahodí.
`license`	řetězec, volitelné	Označení ve stylu SPDX, například `MIT`, `LGPL-3.0`.
`url`	řetězec, volitelné	Stránka projektu nebo domovská stránka.
`file`	řetězec, volitelné	Název souboru s textem licence, který dodáváte, vyhodnocený jako `Plugins/Licenses/<your-plugin-id>/<file>`.

Texty licencí vlastníte vy: dodejte je s balíčkem svého modulu pod Plugins/Licenses/<id>/. Editor komponenty vypíše a uživatele na onu složku odkáže; texty třetích stran za váš modul si ve své vlastní složce Licenses/ neuchovává.

Statická sonda¶

V době hledání — a znovu při instalaci balíčku .mteplugin — hostitel přečte module, otevře <pluginDir>/<module>.py a ověří, že obsahuje def register(...) na nejvyšší úrovni — žádný kód se nespouští. Instalátor neúspěšný balíček odmítne chybovým oknem; hledání modul mlčky přeskočí s chybovým řádkem v protokolu:

PythonPluginBackend: skipping 'org.example.wordcount': module
'.../main.py' does not declare a top-level `def register(...)`.

Držte register ve sloupci 0 řádku začínajícího def register(.

Pořadí načítání a umístění v nabídkové liště¶

Přispívá-li váš modul do Plugins s barPriority: 570, objeví se nabídka v nabídkové liště na pozici 570. Dva moduly s odlišnými hodnotami barPriority pro tentýž název o pozici závodí: vyhraje ten, který se načetl jako poslední, ale protože oba pro danou nabídku obvykle deklarují stejné pořadí, nezáleží na tom. Úplný model řazení najdete v PLUGIN_ARCHITECTURE.md §13.

Co sem NEPATŘÍ¶

Hostitel zpracovává výše zdokumentovaná pole a všechno ostatní ignoruje — nevymýšlejte si pole; neznámý klíč je tichou mrtvou váhou.

Reference plugin.json¶