Przejdź do treści

Wtyczki w Pythonie

Modular Text Editor ładuje wtyczki w Pythonie obok natywnych wtyczek C++ przez tę samą powierzchnię zarządzania wtyczkami. Wtyczka w Pythonie to folder zawierający jeden plugin.json i co najmniej jeden plik .py z funkcją najwyższego poziomu register(ctx).

Edytor uruchamia mały podproces workera na każdą wtyczkę, wykonuje w nim register(ctx) i przekazuje polecenia / menu / zdarzenia przez kanał RPC. Twoja wtyczka nigdy nie dotyka Qt ani Scintilli — obiekt ctx to zwykły pythonowy lokator usług.

Co działa dziś (fazy 1–5: komplet funkcji)

Faza 1: polecenia, pozycje menu, subskrypcje zdarzeń (otwarcie / zamknięcie / zapis / zmiana aktywnego dokumentu / zmiana zaznaczenia / zamknięcie aplikacji), log, pasek stanu.

Faza 2: bufor edytora / zaznaczenie / karetka / wyszukiwanie / wcięcia / operacje na plikach przez ctx.editor.*, trwałe ustawienia przez ctx.settings.* i ustawienia aplikacji tylko do odczytu przez ctx.app_settings.*, providery uzupełniania (z małym limitem czasu na naciśnięcie klawisza) przez @ctx.completions.provider(...), oraz ctx.data_dir() dla zapisywalnego katalogu per wtyczka.

Faza 3: deklaratywne panele dokowane przez ctx.docks.add_panel(...), strony Preferencji przez ctx.settings_page.register(...), oba budowane z kreatorów formularzy mte.ui, oraz dostęp do kontrolek w czasie działania przez ctx.ui.get / ctx.ui.set.

Faza 4: instalator pakietów .mteplugin — spakuj folder wtyczki do zipa i zainstaluj z Preferencje → Wtyczki (zobacz Pakowanie).

Faza 5: wirtualne środowiska per wtyczka — zadeklaruj zależności pip w pyRequires, a edytor przy pierwszym uruchomieniu przygotuje venv dla Twojej wtyczki (zobacz Zależności); deklaracja permissions pokazywana na stronie Wtyczki; oraz substrat RPC strumieniowania/anulowania (na razie bez API dla wtyczek — stanowi podbudowę przyszłych usług AI).

Minimalna wtyczka

Utwórz <any-folder>/hello/ z tymi dwoma plikami.

hello/plugin.json
{
  "id":         "org.example.hello",
  "name":       "Hello (Python)",
  "version":    "1.0.0",
  "apiVersion": 1,
  "entry":      "python",
  "module":     "main",
  "menus": [
    { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
  ]
}
hello/main.py
import mte  # noqa: F401


def register(ctx):

    @ctx.commands.command(id="hello.sayHi",
                          title="Say Hi",
                          shortcut="Ctrl+Alt+H")
    def _say_hi():
        ctx.status.show("Hello from Python!", timeout_ms=3000)
        ctx.log.info("hello: Say Hi invoked")

    ctx.menus.add_item("Plugins/Hello/Say Hi", "hello.sayHi")

Spakuj folder do zipa jako hello.mteplugin i zainstaluj przez Preferencje → Wtyczki → Zainstaluj wtyczkę... — albo wrzuć folder ręcznie do swojego katalogu wtyczek per użytkownik (zobacz Pakowanie). Uruchom edytor ponownie, a na pasku menu pojawi się Plugins → Hello → Say Hi.

Czego potrzebujesz na maszynie

  • Interpretera Pythona 3.9+ osiągalnego na jeden z dwóch sposobów:
    • Na PATH (py.exe, python.exe lub python3.exe na Windows; python3 na macOS/Linux), lub
    • Wskazanego zmienną środowiskową MTE_PYTHON (albo bezwzględna ścieżka do python.exe, albo goła nazwa do wyszukania na PATH).
  • Żadnych pakietów pip: biblioteka kliencka fazy 1 mte jest dostarczana z edytorem i dodawana do sys.path za Ciebie.

Edytor loguje przy starcie, który interpreter wybrał:

PluginHost: MTE_PYTHON is not set; falling back to PATH.
PluginHost: located Python on PATH: py.exe -> C:/Windows/py.exe
PluginHost: Python plugin backend enabled; interpreter=..., worker=.../mte_python_host.py

Jeśli widzisz Python plugins disabled, przejdź do Rozwiązywania problemów.

Co może robić Twoja wtyczka

Każda pozycja poniżej prowadzi do swojej sekcji API:

Możliwość Sekcja
Rejestrowanie poleceń (z opcjonalnym skrótem klawiszowym) ctx.commands
Dodawanie pozycji menu i separatorów ctx.menus
Subskrypcja każdego zdarzenia edytora (dokumenty, tekst, zaznaczenie, ustawienia, motyw, workspace, …) i publikowanie zdarzeń workspace ctx.events oraz Dokumentacja zdarzeń
Logowanie do strumienia diagnostycznego edytora ctx.log
Wysyłanie tymczasowych komunikatów na pasek stanu, własny trwały segment paska stanu ctx.status
Odczyt/modyfikacja buforów, zaznaczeń (także multi-karetka), karetki, plików, wyszukiwania, zakładek, znaczników, podświetlania URL, wcięć, grup widoku dzielonego ctx.editor
Lista języków, odczyt / przełączenie języka dokumentu, wniesienie definicji języka ctx.languages
Utrwalanie konfiguracji per wtyczka, odczyt ustawień globalnych (mte.keys), odczyt ustawień per dokument z warstwą .editorconfig ctx.settings / ctx.app_settings / ctx.document_settings
Publikowanie diagnostyki (podkreślenia + glify na marginesie) ctx.diagnostics
Rejestracja kolorów z motywu dla własnego UI ctx.theme
Otwarcie widoku porównania obok siebie ctx.compare
Rejestracja providera uzupełniania (z limitem czasu na naciśnięcie klawisza) ctx.completions
Zlokalizowanie zapisywalnego katalogu per wtyczka ctx.data_dir()
Dodanie deklaratywnego panelu dokowanego, pokazanie / ukrycie go z polecenia ctx.docks oraz mte.ui
Dodanie strony w Preferencjach ctx.settings_page
Odczyt / zapis kontrolek panelu w czasie działania ctx.ui
Przełączanie trwałego znacznika zaznaczenia na pozycji menu ctx.menus.set_item_checked
Wygaszenie pozycji menu, gdy jej polecenie nie może zadziałać ctx.menus.set_item_enabled

Co dalej