📓Module structure

Introduction

A module is typically a Python package (a directory containing an __init__.py file) located within the bot's main modules/ directory. It follows a specific structure to integrate with the PBModular framework.

Module structure example:

my_module/
├── extensions/              # Optional: Directory for ModuleExtensions
│   ├── __init__.py
│   └── extra_handlers.py
├── strings/                 # Optional: Directory for translations
│   ├── en.yaml
│   └── ru.yaml
├── __init__.py              # Required: Imports the main module class
├── config.yaml              # Required: Module metadata, permissions, config
├── main.py                  # Typical location for the main BaseModule class
└── requirements.txt         # Optional: Python package dependencies

WARNING

info.yaml is deprecated. Consider using the config.yaml

Main components

1. init.py: Makes the directory a Python package. Crucially, it must import the main module class (e.g., from .main import MyModule) so the ModuleLoader can find and instantiate it.

2. config.yaml: (Recommended) The primary configuration file. Contains:

   • info: Basic module details (name, author, version, description, src_url, python version hint, auto_load flag).

   • permissions: A list of required permissions (e.g., use_db, require_db, use_loader). See ☑️ Module permissions.

   • config: A dictionary for module-specific configuration values accessible via self.module_config.

     INFO

     Fallback: If missing, info.yaml (with just info and permissions) is checked for backward compatibility.

3. Main Class File (e.g., main.py): Contains the class definition that inherits from base.module.BaseModule. This class houses the core logic, state, and handler methods for the module.

# main.py
from base.module import BaseModule

class MyModule(BaseModule):
    # ... properties, methods, handlers ...
    pass

4. Handlers: Methods within the BaseModule (or its ModuleExtensions) decorated with @command, @callback_query, @message, or @inline_query to respond to Telegram events. They receive self and optionally client (Pyrogram client), update (Message/CallbackQuery/InlineQuery), and sm_controller (the FSM controller, if FSM is configured). See 🚦 Finite State Machine (FSM).
5. requirements.txt (Optional): Lists any third-party Python packages needed by the module, using standard pip format. These are automatically installed/updated by the ModuleManager.
6. strings/ (Optional): Contains YAML files for localization/translations (e.g., en.yaml, ru.yaml). The framework automatically loads these into self.rawS (all languages) and self.S (current/fallback language). See 🌎 Traslations.
7. extensions/ (Optional): A suggested location for ModuleExtension files (base.mod_ext.ModuleExtension). These allow splitting the module's code into multiple files for better organization, while sharing the main module's context (like self.S, self.db). See 📁 Multifiling.