Модули

Модули - основная составляющая Peluserbot. Благодаря ним, бот может расширять свой функционал во время его работы, а также появляется возможность разделять куски кода по файлам.

Рассмотрим простейший модуль для Peluserbot:

from pyrogram import Client, filters

from core import Module

module = Module(
    name='My echo module'
)

@Client.on_message(filters.text & filters.chat('pelmeshke'))
async def echo_handler(app, message):
    await message.reply(message.text)

Описание модуля

В начале файла модуля после объявления всех импортов должно быть объявление объекта Module, который хранит в себе основную информацию о модуле. Например:

from core import Module, Author

module = Module(
    name='string_id=module_name',
    description='string_id=description',
    authors=Author('pelmeshke', job='Creator'),
    version='v1.0.0',
    release_date='01-01-1970',
    strings={
        'en': {
            'module_name': 'My module',
            'description': 'My module\'s description',
        },
    },
    strings_source_filename=None,
    database=None,
    database_schema='CREATE TABLE IF NOT EXISTS users ('
                    'user_id BIGINT PRIMARY KEY,'
                    'name TEXT'
                    ');'
    config={'parameter': 1},
    requirements=[],
    changelog={'v1.0.0': 'New version!'},
    is_for_bot=False,
    update_source_link=None,
    states=[]
)

Само по себе наличие этого объекта необязательно, но рекомендуется для того, чтобы пользователь знал больше о вашем модуле

Параметры конструктора (все параметры необязательны):

• name - имя модуля, str. Имя модуля должно быть кратким и более-менее уникальным. Для локализации допустимо ссылаться на строки модуля в формате "string_id=my_string"

• description - описание модуля, str. Описание должно лаконично в общих деталях рассказывать, что делает модуль. Для локализации допустимо ссылаться на строки модуля в формате "string_id=my_string"

• authors - авторы модуля, Union[Author, list[Author]]. Информация о авторе модуля предоставляется в виде объекта Author, который принимает аргументы:

• • name - имя автора
• • link - ссылка на сайт/гитхаб автора
• • telegram_username - юзернейм автора
• • job - вклад в создание модуля (создатель, художник, переводчик и т.д.). Для локализации допустимо ссылаться на строки модуля в формате "string_id=my_string"

• version - версия модуля, str. Версия модуля может быть любого удобного разработчику формата, но советуется руководствоваться здравым смыслом и семантическим версионированием

• release_date - дата релиза, str

• strings - строки модуля, dict. О строках читайте в отдельной статье.

• strings_source_filename - имя файла со строками, str. О строках читайте в отдельной статье.

• database - база данных модуля. На выбор базы данных нет ограничений для разработчиков. Чтобы взаимодействовать с ней, у объекта модуля есть атрибут database. О базах данных для модулей читайте в отдельной статье.

• database_scheme - схема для базы данных, str. Если вы не хотите усложнять себе жизнь выбором базы данных, то модуля может создать автоматически базу данных SQLite, используя database_scheme в качестве начального запроса для создания нужных вам таблиц. Чтобы взаимодействовать с базой, у объекта модуля есть атрибут database. О базах данных для модулей читайте в отдельной статье.

• config - конфиг модуля по умолчанию, dict. О конфигах для модулей читайте в отдельной статье.

• requirements - зависимости модуля, list[str]. Нужные библиотеки, необходимые для работы модуля

• changelog - список изменений, dict. Словарь, в котором представлен список изменений для каждой (по усмотрению) версии модуля

• is_for_bot - флаг, показывающий, предусмотрен ли модуль для работы обычных ботов. Модули для ботов могут подвергаться таким ограничениям, как невозможность отредактировать сообщение отправившего (чего у юзерботов нет)

• states - состояния конечной машины состояний. О конечной машине состояний (FSM) читайте в отдельной статье

В примере выше мы объявили объект Module с атрибутом name:

module = Module(
    name='My echo module'
)

Хендлеры модуля

Хендлер (обработчик) - объект, вылавливающий обновление (update, это может сообщение и прочее), подходящее под некоторые фильтры. Из примера выше хендлер это:

@CLient.on_message(filters.text & filters.chat('pelmeshke'))
async def echo_handler(app, message):
    await message.reply(message.text)

Здесь функция echo_handler объявлена декоратором @CLient.on_message как хендлер с фильтром filters.text & filters.chat('pelmeshke')

Про хендлеры и фильтры вы можете почитать поподробнее в документации Pyrogram.

Рекомендуется использовать различимые названия для функций и не использовать функцию с одним именем для двух хендлеров:

# Так делать не надо

@Client.on_message(...)
@Client.on_edited_message(...)
async def my_handler(app, message):
    ...

# Можно делать так

@Client.on_message(...)
async def my_handler(app, message):
    ...

@Client.on_edited_message(...)
async def my_edit_handler(app, message):
    await my_handler(app, message)