Referencia `plugin.json`¶

Každý zásuvný modul v Pythone deklaruje svoju identitu, vstupný bod a umiestnenie v paneli ponuky v súbore plugin.json vedľa svojho main.py. Je to tá istá schéma, akú používa strana C++; špecifické pre Python sú iba polia entry a module.

Prí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 }
  ]
}

Polia¶

Povinné¶

Pole	Typ	Poznámky
`id`	reťazec	Jedinečný identifikátor v tvare reverzného DNS. Používa sa všade — pri zapínaní a vypínaní, v riadkoch logu, v nastaveniach modulu. Naprieč verziami sa nesmie meniť.
`apiVersion`	celé číslo	Musí sa rovnať hodnote `MTE_PLUGIN_API_VERSION` hostiteľa. Aktuálne `1`. Nezhoda sa prejaví na stránke Zásuvné moduly a modul sa vypíše, ale nenačíta.
`entry`	reťazec	Musí byť `"python"`, aby sa smerovalo cez backend Pythonu. Hodnota `"native"` alebo vynechané pole smeruje cez zavádzač Qt.
`module`	reťazec	Názov modulu Pythonu, ktorý obsahuje `register(ctx)`. Pri hodnote `"main"` hľadá pracovný proces súbor `main.py` v priečinku zásuvného modulu. Bodkové názvy balíkov (`"src.main"`) sú budúcim rozšírením — fáza 1 podporuje iba ploché názvy.

Odporúčané¶

Pole	Typ	Poznámky
`name`	reťazec	Čitateľný zobrazovaný názov na stránke Zásuvné moduly.
`version`	reťazec	Semver; inak voľný tvar.
`vendor`	reťazec	Autor alebo organizácia. Zobrazuje sa na stránke Zásuvné moduly.
`description`	reťazec	Jeden až dva riadky. Zobrazuje sa na stránke Zásuvné moduly.

Voliteľné¶

Pole	Typ	Poznámky
`order`	celé číslo	Poradie načítania medzi zásuvnými modulmi; nižšie sa načíta skôr. Predvolene `1000`. Zhody rozhoduje `id`. `requires` má prednosť.
`requires`	pole reťazcov	ID zásuvných modulov, bez ktorých tento modul nemôže fungovať (natívnych aj pythonových rovnako), napr. `["org.mte.lsp"]` — nejde o balíky pip, tie patria do `pyRequires`. Spúšťajú sa pred týmto modulom bez ohľadu na `order`; keď niektorý chýba, je vypnutý, blokovaný licenciou alebo sa nenačítal, tento modul sa vôbec nespustí a Predvoľby → Zásuvné moduly povedia, ktorý potrebuje a prečo. Rovnaký význam ako pri natívnom module.
`apiMinorVersion`	celé číslo	Najnižšia minor verzia API hostiteľa, ktorú tento modul potrebuje (predvolene `0`). Modul v Pythone nemá skompilované `info()`, takže je to jeho jediné vyhlásenie: uveďte minor verziu najnovšieho volania, ktoré používate. Starší hostiteľ zobrazí modul so stavom „Vyžaduje novšiu verziu aplikácie OctoEdit“ a nespustí ho.
`menus`	pole objektov	Pozri nižšie.
`pyRequires`	pole reťazcov	Reťazce s požiadavkami pip (napr. `["requests>=2.31"]`). Pri prvom spustení modulu editor pripraví virtuálne prostredie pre daný modul, nainštaluje do neho tieto balíky cez pip a pracovný proces modulu spustí pod ním (pozri Balenie). Nereťazcové a prázdne položky sa preskočia.
`permissions`	pole reťazcov	Hrubé deklarácie schopností (napr. `["network"]`), zobrazené iba na čítanie v stĺpci Oprávnenia v Predvoľbách → Zásuvné moduly, aby používatelia videli, čo o sebe modul tvrdí. Iba deklarácia — zatiaľ sa nevynucuje.
`thirdParty`	pole objektov	Komponenty tretích strán, ktoré zásuvný modul so sebou nesie, pre uvedenie autorstva v dialógu O aplikácii. Každá položka: `name` (povinné), `license`, `url`, `file`. Licenčný text pomenovaný v `file` dodajte spolu s modulom do `Plugins/Licenses/<id>/`. Pozri nižšie.

`menus`¶

Každá položka deklaruje jednu hlavnú ponuku, do ktorej zásuvný modul prispieva, a určuje jej polohu. Zopakujte jeden objekt na každú hlavnú ponuku, ktorej sa dotýkate (Tools, Plugins, Help a podobne).

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

Pole	Typ	Poznámky
`title`	reťazec, povinné	Popis hlavnej ponuky, pod ktorou položka žije (`Plugins`, `Tools`, …). Musí zodpovedať najľavejšiemu segmentu ciest, ktoré odovzdávate do `ctx.menus.add_item()`.
`barPriority`	celé číslo, voliteľné	Poradie zľava doprava v paneli ponuky. Nižšie = viac vľavo. Ponuky jadra majú pevné priority rozostúpené po 100 (File `100`, Edit `200`, …, Window `600`); hodnota `570` umiestni vašu podponuku blízko polohy `Plugins`. Opakuje sa naprieč modulmi, ktoré cielia na tú istú hlavnú ponuku; vyhráva posledný, čo nevadí, keďže je to idempotentné.
`itemPriority`	celé číslo, voliteľné	Zvislé poradie celého bloku vášho modulu vnútri koncovej ponuky. Predvolene `1000`. Nižšie = vyššie.

Jednotlivé položky tu NEUVÁDZATE — tie sa pridávajú za behu cez ctx.menus.add_item(). menus sa týka iba umiestnenia v paneli ponuky.

`thirdParty`¶

Deklarujte každý komponent tretej strany, ktorý váš zásuvný modul so sebou nesie, aby ho mohol dialóg O aplikácii uviesť. Každá položka:

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

Pole	Typ	Poznámky
`name`	reťazec, povinné	Komponent. Položky bez neprázdneho názvu sa zahodia.
`license`	reťazec, voliteľné	Označenie v štýle SPDX, napr. `MIT`, `LGPL-3.0`.
`url`	reťazec, voliteľné	Stránka projektu alebo domovská stránka.
`file`	reťazec, voliteľné	Názov súboru s licenčným textom, ktorý dodávate, vyhodnotený ako `Plugins/Licenses/<your-plugin-id>/<file>`.

Licenčné texty vlastníte vy: dodajte ich s balíkom svojho modulu do Plugins/Licenses/<id>/. Editor komponenty vypíše a nasmeruje používateľov do tohto priečinka; texty tretích strán za váš zásuvný modul si vo vlastnom priečinku Licenses/ neuchováva.

Statická kontrola¶

Pri vyhľadávaní — a znova pri inštalácii balíka .mteplugin — hostiteľ prečíta module, otvorí <pluginDir>/<module>.py a overí, či obsahuje def register(...) na najvyššej úrovni — žiadny kód sa nespúšťa. Inštalátor neúspešný balík odmietne chybovým dialógom; vyhľadávanie zásuvný modul potichu preskočí s chybovým riadkom v logu:

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

register držte v stĺpci 0 riadka začínajúceho sa def register(.

Poradie načítania a umiestnenie v paneli ponuky¶

Ak váš zásuvný modul prispieva do ponuky Plugins s barPriority: 570, objaví sa ponuka v paneli ponuky na pozícii 570. Dva moduly s rôznymi hodnotami barPriority pre ten istý názov súperia: vyhrá ten, ktorý sa načítal posledný, no keďže obidva zvyčajne pre danú ponuku deklarujú tú istú hodnotu, nezáleží na tom. Úplný model zoraďovania nájdete v PLUGIN_ARCHITECTURE.md §13.

Čo sem NEPATRÍ¶

Hostiteľ spracúva polia zdokumentované vyššie a všetko ostatné ignoruje — nevymýšľajte si polia; neznámy kľúč je len tichou mŕtvou váhou.

Referencia plugin.json¶