Шаблон плагина exteraGram

Этот репозиторий - стартовый шаблон для разработки Python-плагинов exteraGram. Используйте его как основу для своего проекта: настройте метаданные, добавьте код плагина и соберите готовый .plugin-файл.

Начало работы

1. Создайте свой репозиторий на основе этого шаблона через Use this template на GitHub или склонируйте репозиторий.

2. Отредактируйте config.json: задайте ID, название, описание, автора, версию, иконку и минимальные версии приложения и SDK.

3. Замените примерный код в plugin/ кодом своего плагина.

4. Соберите плагин командой:

   make build

Готовый файл появится в build/plugin.plugin. Для сборки нужен Python 3; устанавливать дополнительные Python-пакеты не требуется.

Структура шаблона

• config.json - метаданные плагина.
• plugin/ - исходный код плагина; точка входа - plugin/plugin.py.
• scripts/plugin_build.py - подстановка значений конфигурации и сборка исходников в один файл.
• scripts/update_sdk.py - загрузка и установка последних SDK stubs.
• sdk/stubs/ - SDK stubs для автодополнения и статической проверки в редакторе. Это не runtime-библиотека.
• build/ - каталог результата сборки; он исключён из Git.

Метаданные и шаблоны

Значения из config.json подставляются в строковые литералы Python через ссылки $json.<ключ>. Например, для такого конфига:

{
  "id": "my_plugin",
  "name": "My Plugin",
  "description": "Plugin description",
  "author": "@username",
  "version": "1.0.0",
  "icon": "sticker_pack/0",
  "app_version": ">=12.5.1",
  "sdk_version": ">=1.4.4.3"
}

В исходнике можно написать:

__id__ = '$json.id'
__name__ = "$json.name"

Сборщик подставит соответствующие значения из конфига. Подстановка работает в строках с одинарными, двойными и тройными кавычками, а также в шаблонных строках с обратными кавычками. Поддерживаются вложенные пути, например $json.api.gemani. Конечное значение должно быть скалярным; неизвестный путь, список или объект вызовет ошибку сборки.

Исходники и импорты

Добавляйте Python-файлы и подпапки в plugin/; сборщик рекурсивно включает их в итоговый файл. Для локальных модулей используйте импорты на уровне модуля, например:

from .helpers import format_message

Импорты внешних библиотек и SDK остаются в собранном файле. Циклические импорты, алиасы локальных импортов и локальные импорты внутри функций не поддерживаются и приводят к ошибке сборки.

Команды

make build      # собрать build/plugin.plugin
make venv       # создать виртуальное окружение .venv/
make sdk        # скачать последние официальные SDK stubs
make clean      # удалить build/

Виртуальное окружение для сборки не требуется: make build использует Python, указанный переменной PYTHON (по умолчанию python3). SDK stubs и настройка редактора описаны в sdk/README.md.