Here’s a structured coding rule set for developing Telegram bots with Python 3.12+ and aiogram3 (based on your knowledge base and best practices):

---

Build & Development Commands

Dependencies Management

# Use Poetry for dependency management (recommended in  and ):
poetry init  # Initialize project
poetry add aiogram[fast]  # Install aiogram3 with optional dependencies
poetry add pytest pytest-asyncio pytest-mock --group dev  # Add testing tools

Development Workflow

# Run the bot in development mode:
poetry run python -m bot.main --env development  # Example entry point

# Linting and formatting:
poetry run black .  # Code formatting (PEP8)
poetry run flake8 .  # Static type checking
poetry run mypy bot/  # Type hints validation

Testing Commands

# Run unit and integration tests:
poetry run pytest tests/ --cov=bot  # With coverage reporting

# Run tests in debug mode:
poetry run pytest --pdb  # Drop into debugger on failure

---

Testing Guidelines

1. Unit Tests

   • Use pytest and pytest-asyncio for asynchronous tests (as in and ).
   • Mock Telegram API interactions with pytest-mock or aioresponses to avoid hitting real endpoints.
   • Example:

     from aiogram import Bot
     from aioresponses import aioresponses
     
     async def test_send_message(mocker):
         with aioresponses() as m:
             m.post("https://api.telegram.org/bot/sendMessage", status=200)
             await bot.send_message(chat_id=123, text="Test")
     

2. Integration Tests

   • Test with a test Telegram bot (create one via @BotFather).
   • Validate interactions with VK API (if needed) using mocked responses.

3. Code Coverage

   • Aim for >90% coverage for critical paths (message handlers, API calls).

4. CI/CD Integration

   • Use GitHub Actions/CI to run tests and linting on pull requests (inspired by ).

---

Code Style & Guidelines

Core Principles

1. PEP8 Compliance

   • Enforce with black and flake8.
   • Limit line length to 100 characters.

2. Asynchronous Patterns

   • Use async/await for all handlers (aiogram3 requires this ).
   • Avoid blocking calls in event loop threads.

3. Error Handling

   • Catch Telegram API errors using try/except for aiogram.exceptions.TelegramAPIError.
   • Example:

     try:
         await bot.send_message(chat_id=chat_id, text=text)
     except TelegramAPIError as e:
         logging.error(f"API Error: {e}")
     

4. Code Structure

   • Organize code into:
     • bot/: Main bot logic (handlers, middlewares).
     • services/: External services (e.g., VK API interactions).
     • tests/: Test cases.
   • Use Dependency Injection for services (e.g., VK client).

5. Type Hints

   • Annotate all functions and variables with mypy.
   • Example:

     async def handle_message(update: types.Message, state: FSMContext) -> None:
         ...
     

6. State Machines

   • For complex workflows, use aiogram3’s Finite State Machine (FSM) (as in ).
   • Example:

     class UserState(StatesGroup):
         waiting_for_input = State()
     
     @dp.message_handler(commands=["start"])
     async def start_handler(message: types.Message, state: FSMContext):
         await state.set_state(UserState.waiting_for_input)
     

---

Documentation Guidelines

1. Docstrings

   • Use Google-style docstrings for functions and classes.
   • Example:

     async def send_vk_post(chat_id: int, post: dict) -> None:
         """Send a VK post to a Telegram channel.
         Args:
             chat_id (int): Target Telegram chat ID.
             post (dict): VK post data (text, media, etc.).
         Raises:
             ValueError: If post data is invalid.
         """
     

2. README.md

   • Include:
     • Setup instructions (e.g., poetry install).
     • Environment variables (e.g., TELEGRAM_TOKEN, VK_SERVICE_KEY).
     • Quickstart example:

       poetry run python -m bot.main --token $TELEGRAM_TOKEN
       

3. API Documentation

   • Use sphinx or mkdocs for documenting public APIs (if applicable).

4. Contributing Guidelines

   • Add a CONTRIBUTING.md file with:
     • Code style rules.
     • Testing requirements.
     • Pull request process.

---

References

• aiogram3 documentation for async patterns: , ,
• FSM implementation examples:
• Testing best practices: ,

Let me know if you need further details!