6.6 KiB
Executable File
Разработчикам модулей
Finally, кто-то сделал документацию по тому, как писать модули...
Общая структура
Любой модуль начинается с:
- Лицензии
- Импорта зависимостей
- Подключения логирования
- Класса модуля, обернутого в декоратор @loader.tds
- Объявления базовых обработчиков
Все остальные действия выполняются внутри этого класса*.
*Важное примечание. Если функция не использует атрибуты и методы класса (self.что-то), ее стоит объявление стоит вынести за пределы класса.
Справочник по структуре
@loader.tds
Декоратор, используемый на классе модуля. Нужен для добавления возможности локализации докстрингов команд.
def __init__(self) -> None:
Вызывается при начале загрузки модуля. Обычно используется только для инициализации конфига.
async def client_ready(self, client, db) -> None:
Вызывается в момент, когда готовы все инстансы (client, db). Основное место инициализации. Чаще всего здесь объявляют внутренние переменные, готовят базу данных, запускают нужные корутины и другие вещи, которые нужны при загрузке.
async def on_unload(self) -> None:
Вызывается в момент выгрузки модуля. Максимальное время выполнения - 5 секунд, при превышении код прерывается. Используется для сброса бесконечных циклов и других действий, нужных при выгрузке \ перезагрузке модуля.
async def testcmd(self, message: Message) -> None:
Таким образом выглядят обработчики команд. Все функции класса, которые заканчиваются на -cmd расцениваются как команды. Обратите внимание, что нельзя создать команду, которая начинается с цифры, содержит спецсимволы и др. Действуют те же ограничения, что и на обычные функции Python.
async def watcher(self, message: Message) -> None:
Обработчик всех сообщений. В него приходят все события, которые вызваны другими сессиями (не сессией юзербота), включая сервисные сообщения.
utils.py
Для повышения совместимости модуля рекомендуется использовать библиотеку utils. Она содержит множество полезных методов:
Возвращает список аргументов из сообщения
get_args(message: Message) -> list
Возвращает необработанные аргументы в виде одной строки
get_args_raw(message: Message) -> str
Возвращает список аргументов, разделенных символом sep
get_args_split_by(message: Message, sep: str) -> list
Возвращает ID объекта (для чатов\каналов без -100)
get_chat_id(message: Message) -> int
Экранирует HTML, данный в аргументе
escape_html(text: str) -> str
Получает рабочую директорию
get_base_dir() -> str
Получает директорию выбранного модуля
get_dir(mod: str) -> str
Получает отправителя (не работает с сервисными сообщениями)
get_user(message: Message) -> str
Оборачивает синхронный код в коротину. Рекомендуется использовать тогда, когда нужно внутри модуля использовать синхронный код, чтобы не останавливать основной поток
run_sync(func: FunctionType, *args, **kwargs) -> coroutine
Репозиционирование объектов и их смещений
relocate_entities(entities: ListLike, offset: int, text: str = None) -> list
Answer to a message (edit if possible, else send new message)
answer(message: Message, response: str, *args, **kwargs) -> Many
Get possible target id
get_target(message: Message, arg_no: int = 0) -> int or None
Merge two dictionaries
merge(a: dict, b: dict) -> dict
Create new channel (if needed) and return its entity
asset_channel(a: dict, b: dict) -> dict
Get telegram permalink to entity
get_link(a: dict, b: dict) -> dict
Split provided _list into chunks of n
chunks(a: dict, b: dict) -> dict
strings
Хоть они и объявляются как словарь, на самом деле это не словарь. Их можно вызывать. Сделано это для упрощения локализации. Все строки, которые можно вынести в strings - выноси в strings. В этом же словаре объявляется отображаемое имя модуля. Старайся выбирать имя без пробелов, спецсимволов и другого шлака.
db
База данных FTG. Практически всегда сохраняется в атрибут self.db или self._db.
Получение ключа из базы данных, заменяя его default в случае отсутствия:
db.get(owner: str, key: str, default: Any = None) -> Many
Установка значения ключа базы данных
db.set(owner: str, key: str, value: str) -> None
Документация будет пополняться