PBModular Вики

Russian

English

Russian

English

Appearance

💻 Начальная Cтруктура и Простой Обработчик ​

Введение ​

Структура модуля была описана в предыдущем разделе. Теперь перейдем к его созданию!

INFO

Сначала прочитайте PyroTGFork, здесь описана только специфика написания для PBModular.

Шаг 1: Создание каталога модуля и его конфигурации ​

Создайте каталог для вашего модуля (например, my_module) внутри основной папки modules/. Внутри my_module создайте:

  1. init.py: Этот файл заставляет Python рассматривать каталог как пакет. Он должен импортировать класс вашего главного модуля (см. шаг 2).
  2. config.yaml: Этот файл определяет метаданные и настройки для вашего модуля. Он предпочтительнее, чем старый info.yaml.

Пример config.yaml:

python
# config.yaml
info:
  name: MyModule # Удобное для пользователя название (использовать одно слово)
  author: Your Name
  version: 0.1.0
  description: A brief description of what the module does.
  src_url: https://github.com/your/repo # Необязательно: Ссылка на исходный код
  python: 3.11 # Необязательно: Рекомендуемая версия Python (предупреждает, если она отличается)
  auto_load: true # Необязательно: Загружать ли этот модуль автоматически (по умолчанию: true)

# Необязательно: Список необходимых разрешений (см. раздел "Разрешения модуля")
permissions:
  - use_db # Пример: запрашивает доступ к базе данных

# Дополнительно: Пользовательская конфигурация, специфичная для вашего модуля
config:
  key: "YOUR_DEFAULT_KEY"
  feature_enabled: true

WARNING

Fallback: Если config.yaml отсутствует, загрузчик будет искать info.yaml (содержащий только ключи info и permissions) для обратной совместимости, но использование config.yaml настоятельно рекомендуется.

Шаг 2: Создайте класс главного модуля ​

Создайте файл Python (например, main.py) в каталоге модулей и определите свой главный класс, наследующий от BaseModule.

python
# main.py
from base.module import BaseModule, command
from pyrogram import Client
from pyrogram.types import Message

class MyModule(BaseModule):
    # Логика модуля и обработчики находятся здесь
    pass

Теперь убедитесь, что __init__.py импортирует этот класс:

python
# __init__.py
from .main import MyModule

Шаг 3: Написание обработчика команд ​

Определите асинхронный метод в классе MyModule. Метод должен принимать self, а также опционально client (экземпляр Pyrogram Client) и message (или callback_query, в зависимости от типа обработчика).

python
# main.py (внутри класса MyModule)
    async def on_hello(self, client: Client, message: Message):
        """Replies with a friendly greeting.""" # Docstring, используемый для автопомощи
        await message.reply("Hello World!")

Шаг 4: Регистрация обработчика ​

Используйте декораторы из base.module для регистрации вашего метода в качестве обработчика.

  • @command(names, filters=None, fsm_state=None): Регистрирует обработчик команд.
    • names: Строка или список строк для имени (имен) команды (например, "hello" или ["hi", "hello"]).
    • filters: Дополнительный фильтр Pyrogram (pyrogram.filters.Filter) для добавления более специфических условий. Настоятельно рекомендуется для команд, выходящих за рамки простых триггеров (например, filters.private или filters.regex).
    • fsm_state: Необязательное состояние или список состояний для управления FSM (см. документацию по FSM).
  • @callback_query(filters=None, fsm_state=None): Регистрирует callback обработчик запроса (для встроенных кнопок).
  • @message(filters=None, fsm_state=None): Регистрирует общий обработчик сообщений. Использование фильтров здесь очень важно, чтобы избежать конфликтов и проблем с производительностью.
python
# main.py (внутри класса MyModule)
    from base.module import command
    from pyrogram import filters

    @command("hello", filters=filters.private) # Работает только в приватном чате
    async def on_hello(self, client: Client, message: Message):
        """Отвечает дружеским приветствием."""
        await message.reply("Hello World!")

    @command("start", filters.regex(r"/start payload_\w+")) # Пример с regex
    async def on_start_with_payload(self, client: Client, message: Message):
        """Обработка команды запуска с определенной полезной нагрузкой"""
        payload = message.text.split('_', 1)[1]
        await message.reply(f"Received start with payload: {payload}")

INFO

Фреймворк автоматически обрабатывает регистрацию команд (command_registry) и проверку разрешений (декоратор @allowed_for и команда /allow_cmd).