📓 Структура Модуля

Введение

Модуль - это, как правило, пакет Python (директория, содержащая файл _init__.py), расположенный в главной директории бота modules/. Он имеет определенную структуру для интеграции с фреймворком PBModular.

Пример структуры модуля:.

my_module/
├── extensions/              # Дополнительно: Каталог для ModuleExtensions
│   ├── __init__.py
│   └── extra_handlers.py
├── strings/                 # Дополнительно: Каталог для переводов
│   ├── en.yaml
│   └── ru.yaml
├── __init__.py              # Требуется: Импортирует класс главного модуля
├── config.yaml              # Требуется: Метаданные модуля, разрешения, конфигурация
├── main.py                  # Типичное расположение основного класса BaseModule
└── requirements.txt         # Дополнительно: Зависимости пакета Python

WARNING

info.yaml устарел. Рассмотрите возможность использования config.yaml.

Основные компоненты

1. init.py: Делает каталог пакетом Python. Очень важно, чтобы он импортировал класс главного модуля (например, from .main import MyModule), чтобы ModuleLoader мог найти и инстанцировать его.

2. config.yaml: (Рекомендуется) Основной файл конфигурации. Содержит:

   • info: Основные сведения о модуле (имя, автор, версия, описание, src_url, подсказка версии python, флаг auto_load).

   • permissions: Список необходимых разрешений (например, use_db, require_db, use_loader). См. ☑️ Разрешения модуля.

   • config: Словарь для значений конфигурации модуля, доступный через self.module_config.

     INFO

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

3. Файл основного класса (например, main.py): Содержит определение класса, который наследуется от base.module.BaseModule. Этот класс содержит основную логику, состояние и методы обработчика модуля.

# main.py
from base.module import BaseModule

class MyModule(BaseModule):
    # ... свойства, методы, обработчики...
    pass

1. Хандлеры: Методы внутри BaseModule (или его ModuleExtensions), украшенные @command, @callback_query или @message для реагирования на события Telegram. Они принимают self и опционально client (Pyrogram client) и update (Message/CallbackQuery). Состояние FSM также может быть передано, если оно настроено (см. документацию по FSM).
2. requirements.txt (Необязательно): Перечисляет все сторонние Python-пакеты, необходимые модулю, используя стандартный формат pip. Они автоматически устанавливаются/обновляются ModuleManager.
3. strings/ (Необязательно): Содержит файлы YAML для локализации/перевода (например, en.yaml, ru.yaml). Фреймворк автоматически загружает их в self.rawS (все языки) и self.S (текущий/обратный язык). См. 🌎 Переводы.
4. extensions/ (Необязательно): Предполагаемое местоположение для файлов ModuleExtension (base.mod_ext.ModuleExtension). Они позволяют разделить код модуля на несколько файлов для лучшей организации, при этом разделяя контекст основного модуля (например, self.S, self.db). См. 📁 Мультифайловость.