Пишем модули для Elys

Архитектура

Модуль Elys — это обычный Python-файл с классом-наследником loader.Module. Ядро загружает его, регистрирует команды и обработчики и прокидывает в экземпляр клиент Telegram, базу данных и инлайн-менеджер.

Hello, world

Минимальный модуль с одной командой:

# meta developer: @yourname
# meta banner: https://example.com/banner.png

from elystl.tl.types import Message

from .. import loader, utils


@loader.tds
class HelloMod(loader.Module):
    """Здоровается с миром"""

    strings = {
        "name": "Hello",
        "hello": "👋 <b>Hello, {}!</b>",
    }
    strings_ru = {
        "hello": "👋 <b>Привет, {}!</b>",
    }

    @loader.command(ru_doc="[имя] — поздороваться")
    async def hello(self, message: Message):
        """[name] — say hello"""
        name = utils.get_args_raw(message) or "world"
        await utils.answer(message, self.strings("hello").format(utils.escape_html(name)))

1. Сохрани файлнапример как hello.py.
2. Отправь его себе в Telegramи ответь на него командой .lm.
3. Проверь.hello Elys → «👋 Привет, Elys!». Справка появится в .help Hello.

Мета-заголовки

Комментарии в начале файла сообщают загрузчику, как ставить модуль.

Команды

@loader.command(
    alias="w",                       # .w == .weather
    ru_doc="<город> — погода",       # описание для .help на русском
    en_doc="<city> — weather",
)
async def weather(self, message: Message):
    """<city> — weather"""          # описание по умолчанию
    if not (city := utils.get_args_raw(message)):
        reply = await message.get_reply_message()
        city = reply.raw_text if reply else None
    if not city:
        return await utils.answer(message, self.strings("no_city"))

    msg = await utils.answer(message, "⏳")
    data = await utils.run_sync(fetch_weather, city)   # блокирующий код — в поток
    await utils.answer(msg, data)

Аргументы

Ответ

await utils.answer(message, text) редактирует исходящее сообщение или отвечает на входящее; длинный текст сам разобьётся на части. Принимает HTML и reply_markup для инлайн-кнопок. Файлы — utils.answer_file(message, file, caption=…).

Строки и переводы

strings — базовые строки (обязателен ключ name). Переводы — словари strings_<lang>: strings_ru, strings_de, strings_ua… Elys выберет язык по .setlang, а при отсутствии ключа вернётся к базовому.

strings = {"name": "Weather", "no_city": "🚫 <b>Specify a city</b>"}
strings_ru = {"no_city": "🚫 <b>Укажи город</b>", "_cls_doc": "Погода в любом городе"}

self.strings("no_city")      # или self.strings["no_city"]

Декоратор @loader.tds делает докстринги переводимыми: описания команд берутся из ru_doc/en_doc в @loader.command или из ключей _cmd_doc_<команда>, описание модуля — из _cls_doc.

Конфиг и валидаторы

Опции попадают в интерактивный .config, хранятся в базе и проверяются валидаторами.

def __init__(self):
    self.config = loader.ModuleConfig(
        loader.ConfigValue(
            "api_key",
            None,
            lambda: "API-ключ сервиса",
            validator=loader.validators.Hidden(),      # скрыт звёздочками
        ),
        loader.ConfigValue(
            "units",
            "metric",
            lambda: "Система единиц",
            validator=loader.validators.Choice(["metric", "imperial"]),
        ),
        loader.ConfigValue(
            "cities",
            ["Moscow"],
            lambda: "Избранные города",
            validator=loader.validators.Series(loader.validators.String(max_len=64)),
        ),
        loader.ConfigValue(
            "timeout",
            10,
            lambda: "Таймаут запроса, сек",
            validator=loader.validators.Integer(minimum=1, maximum=120),
            on_change=self._reconnect,                 # вызовется при изменении
        ),
    )

# чтение / запись
units = self.config["units"]
self.config["timeout"] = 30

Валидаторы

База данных

Каждый модуль получает своё пространство имён (по имени класса). Значения должны быть JSON-сериализуемыми.

self.set("counter", self.get("counter", 0) + 1)

# pointer — «живой» список/словарь: изменения сразу сохраняются в базу
self.notes = self.pointer("notes", [])
self.notes.append({"text": "купить хлеб"})

# доступ к чужому пространству (осторожно!)
prefix = self.db.get("elys.main", "command_prefix", ".")

Вотчеры

Вотчер вызывается на каждое подходящее сообщение. Фильтры задаются аргументами декоратора — так ядро отсеивает лишнее ещё до вызова.

@loader.watcher("in", "only_pm", no_commands=True)
async def autoreply(self, message: Message):
    if self.get("afk"):
        await message.reply("💤 Я сейчас не у телефона")

@loader.watcher(only_groups=True, regex=r"(?i)\belys\b")
async def mention(self, message: Message):
    ...

Пользователь может ограничить вотчер командами .watcher и .watcherbl, поэтому не полагайся на то, что он сработает везде.

Инлайн-формы

self.inline.form() отправляет сообщение с кнопками от инлайн-бота. Колбэк получает InlineCall, через который сообщение можно редактировать.

@loader.command()
async def vote(self, message: Message):
    await self.inline.form(
        "🗳 <b>Нравится Elys?</b>",
        message,
        reply_markup=[
            [
                {"text": "👍 Да", "callback": self._voted, "args": (True,), "style": "success"},
                {"text": "👎 Нет", "callback": self._voted, "args": (False,), "style": "danger"},
            ],
            [{"text": "🌐 GitHub", "url": "https://github.com/ZavozDevs/Elys"}],
        ],
        ttl=3600,          # через час кнопки перестанут работать
    )

async def _voted(self, call: InlineCall, liked: bool):
    await call.answer("Спасибо!")                        # всплывашка
    await call.edit("❤️ Ура!" if liked else "😢 Жаль")   # можно передать reply_markup

Ключи кнопок

Параметры form(): photo, gif, video, file + mime_type, force_me, always_allow, disable_security, ttl, on_unload, silent.

Галереи и списки

await self.inline.gallery(message, next_handler=self._next_cat, caption="🐈 Котики")
await self.inline.list(message, strings=["Стр. 1", "Стр. 2", "Стр. 3"])

Inline-запросы и колбэки

Inline-хендлер

Срабатывает, когда пользователь пишет @твой_бот запрос. Имя хендлера — первое слово запроса.

@loader.inline_handler(ru_doc="<текст> — сделать текст громким")
async def loud(self, query: InlineQuery):
    """<text> — make text loud"""
    text = query.args or "elys"
    return {
        "title": text.upper(),
        "description": "Отправить капсом",
        "message": f"<b>{utils.escape_html(text.upper())}</b>",
    }

Вернуть можно словарь или список словарей; каждый должен содержать один из ключей message, photo, gif, video или file (+ mime_type).

Callback-хендлер

@loader.callback_handler()
async def raw_cb(self, call: InlineCall):
    if not call.data.startswith("weather/"):
        return
    await call.answer(call.data.split("/", 1)[1])

Фоновые циклы

@loader.loop(interval=3600, autostart=True, wait_before=True)
async def refresh(self):
    self.set("rates", await self._fetch_rates())

# управление вручную
self.refresh.start()
self.refresh.stop()
self.refresh.status   # True, если цикл запущен

stop_clause="ключ_бд" привязывает работу цикла к значению в базе. Внутри цикла можно бросить loader.StopLoop, чтобы остановить его.

Права доступа

По умолчанию команда доступна только владельцам. Декораторы безопасности расширяют или сужают круг пользователей — пользователь потом может переопределить это через .security.

@loader.command()
@loader.group_admin_ban_users
async def kick(self, message: Message):
    ...

Жизненный цикл

async def client_ready(self):
    """Клиент готов, конфиг загружен — здесь основная инициализация"""
    self.me = await self.client.get_me()

async def on_dlmod(self):
    """Только при первой установке через .dlmod / .lm"""

async def on_unload(self):
    """Модуль выгружается или перезагружается — закрой сессии и задачи"""
    await self._session.close()

Подпись client_ready(self, client, db) из Hikka тоже поддерживается. В модуле доступны self.client, self.db, self.inline, self.tg_id, self.lookup("Имя") и self.get_prefix().

Исключения

Библиотеки

Общий код можно вынести в библиотеку — класс-наследник loader.Library, имя которого оканчивается на Lib. Модули подключают её по ссылке:

async def client_ready(self):
    self.api = await self.import_lib("https://example.com/weather_lib.py")

import_lib работает только внутри client_ready.

Справочник utils

Совместимость

Отладка

• Используй logging.getLogger(__name__) — записи попадут в .logs.
• .logs debug -f — подробный лог файлом (может содержать личные данные).
• .e self.lookup("Hello").get("counter") — быстро посмотреть состояние модуля.
• После правки файла просто выполни .lm повторно — модуль перезагрузится, вызвав on_unload.

Вклад в ядро

1. ФоркниZavozDevs/Elys и создай ветку.
2. Соблюдай стильформатирование black, проверка ruff/flake8.
3. Пиши осмысленные коммитыв стиле Conventional Commits: fix(loader): …, feat(emoji): ….
4. Сохраняй совместимостьс базами и модулями Hikka/Heroku. Медиа — только из репозитория ZavozDevs/assets.
5. Открой Pull Requestс описанием изменений.

Elys распространяется под лицензией GNU AGPLv3.