Saltar a contenido

Plugins de Python

Modular Text Editor carga plugins de Python junto a los nativos de C++ a través de la misma superficie de gestión de plugins. Un plugin de Python es una carpeta que contiene un plugin.json y al menos un archivo .py con una función register(ctx) de nivel superior.

El editor lanza un pequeño subproceso trabajador por plugin, ejecuta register(ctx) dentro de él y traslada los comandos, los menús y los eventos a través de un canal RPC. Tu plugin nunca toca Qt ni Scintilla: el objeto ctx es un localizador de servicios de Python puro.

Qué funciona hoy (fases 1–5: funcionalidad completa)

Fase 1: comandos, elementos de menú, suscripciones a eventos (apertura / cierre / guardado / cambio de documento activo / cambio de selección / salida de la aplicación), el registro, la barra de estado.

Fase 2: búfer del editor, selección, cursor, búsqueda, sangría y operaciones con archivos mediante ctx.editor.*; ajustes persistentes mediante ctx.settings.* y ajustes de la aplicación de solo lectura mediante ctx.app_settings.*; proveedores de autocompletado (con un pequeño plazo por pulsación) mediante @ctx.completions.provider(...); y ctx.data_dir() para el directorio con permiso de escritura de cada plugin.

Fase 3: paneles acoplables declarativos mediante ctx.docks.add_panel(...), páginas de Preferencias mediante ctx.settings_page.register(...), ambos construidos con los constructores de formularios mte.ui, y acceso a los controles en tiempo de ejecución mediante ctx.ui.get / ctx.ui.set.

Fase 4: instalador de paquetes .mteplugin — comprime la carpeta de tu plugin e instálala desde Preferencias → Complementos (consulta Empaquetado).

Fase 5: entornos virtuales por plugin — declara las dependencias de pip en pyRequires y el editor aprovisiona un entorno virtual para tu plugin en el primer arranque (consulta Dependencias); una declaración de permissions que se muestra en la página de Plugins; y un sustrato RPC con flujo y cancelación (todavía sin API de cara a los plugins: sostiene los futuros servicios de IA).

Plugin mínimo

Crea <any-folder>/hello/ con estos dos archivos.

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")

Comprime la carpeta como hello.mteplugin e instálala mediante Preferencias → Complementos → Instalar un complemento..., o deja la carpeta a mano en tu directorio de plugins por usuario (consulta Empaquetado). Reinicia el editor y Plugins → Hello → Say Hi aparecerá en la barra de menús.

Qué necesitas en la máquina

  • Un intérprete de Python 3.9 o superior accesible de una de estas dos formas:
    • En el PATH (py.exe, python.exe o python3.exe en Windows; python3 en macOS/Linux), o
    • Apuntado por la variable de entorno MTE_PYTHON (bien una ruta absoluta a un python.exe, bien un nombre simple que se buscará en el PATH).
  • Ningún paquete de pip: la biblioteca cliente mte de la fase 1 se distribuye con el editor y se añade a sys.path por ti.

El editor anota en el registro qué intérprete seleccionó al arrancar:

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

Si ves Python plugins disabled, ve a Solución de problemas.

Qué puede hacer tu plugin

Cada elemento de abajo enlaza con su sección de la API:

Capacidad Sección
Registrar comandos (con un atajo de teclado opcional) ctx.commands
Aportar elementos de menú y separadores ctx.menus
Suscribirse a todos los eventos del editor (documentos, texto, selección, ajustes, tema, espacio de trabajo, …) y publicar los del espacio de trabajo ctx.events y la referencia de eventos
Escribir en el flujo de diagnóstico del editor ctx.log
Publicar mensajes pasajeros en la barra de estado y poseer un segmento persistente ctx.status
Leer y modificar búferes, selecciones (incluidas las de varios cursores), el cursor, archivos, búsquedas, marcadores, marcas, resaltado de URL, sangría y grupos de vista dividida ctx.editor
Listar lenguajes, leer y cambiar el lenguaje de un documento, aportar una definición de lenguaje ctx.languages
Guardar configuración por plugin, leer los ajustes de toda la aplicación (mte.keys), leer los ajustes por documento en capas con .editorconfig ctx.settings / ctx.app_settings / ctx.document_settings
Publicar diagnósticos (líneas onduladas y glifos de margen) ctx.diagnostics
Registrar colores adaptables al tema para tu propia interfaz ctx.theme
Abrir la vista de comparación en paralelo ctx.compare
Registrar un proveedor de autocompletado (con un plazo por pulsación) ctx.completions
Localizar tu directorio por plugin con permiso de escritura ctx.data_dir()
Añadir un panel acoplable declarativo y mostrarlo u ocultarlo desde un comando ctx.docks y mte.ui
Añadir una página en Preferencias ctx.settings_page
Leer y escribir los controles de un panel en tiempo de ejecución ctx.ui
Alternar una marca de verificación persistente en un elemento de menú ctx.menus.set_item_checked
Atenuar un elemento de menú mientras su comando no se puede ejecutar ctx.menus.set_item_enabled

Qué viene ahora