python/aiogram
1
0
Fork 0
mirror of https://github.com/aiogram/aiogram.git synced 2026-04-08 16:37:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5
aiogram/.serena/memories/code_style.md
Alex Root Junior 9f49c0413f
Added full support for the Bot API 9.6 (#1792) 
* Added full support for the Bot API 9.6

* Add support for `managed_bot` updates

* Set `description_parse_mode` default to `"parse_mode"` and use `DateTime` for `addition_date` in `PollOption`

* Update changelog with features and changes from Bot API 9.6

* Add changelog fragment generator and update poll parameter descriptions
2026-04-04 01:22:08 +03:00

2.2 KiB
Raw Blame History

Code Style & Conventions

General

  • from __future__ import annotations at the top of every Python file
  • Full type hints on all function signatures and class fields
  • Max line length: 99 characters (ruff enforced)
  • snake_case for Python names; camelCase used only in __api_method__ strings

Pydantic models

  • All Telegram types extend TelegramObject(BotContextController, BaseModel) from aiogram/types/base.py
  • TelegramObject is frozen; use MutableTelegramObject when mutation is needed
  • Fields default to None for optional API parameters; use Field(None, json_schema_extra={"deprecated": True}) for deprecated fields
  • Use Default("key") sentinel (from aiogram.client.default) for user-configurable defaults like parse_mode, protect_content
  • TYPE_CHECKING guards for circular imports — keep runtime imports lean

API Methods

  • Each method is a class inheriting TelegramMethod[ReturnType] from aiogram/methods/base.py
  • Required class attrs: __returning__ (return type), __api_method__ (camelCase string)
  • Fields with None default = optional param
  • Method docstring format: short description + Source: https://core.telegram.org/bots/api#methodname
  • File name: snake_case of method name (e.g., SendMessage → send_message.py)

Imports order (ruff/isort enforced)

  1. stdlib
  2. third-party
  3. aiogram (first-party)
  4. relative imports

Ruff rules enforced

  • A (annotations), B (bugbear), C4 (comprehensions), DTZ (datetimez), E, F, I (isort), PERF, PL (pylint), Q (quotes), RET, SIM, T10, T20, UP (pyupgrade)
  • Several PLR rules disabled (Telegram API naturally has many params/methods)
  • F401 disabled (re-exports in __init__.py intentional)

Code generation convention

  • Never hand-edit generated files (.butcher/**/entity.json, auto-generated aiogram/types/*.py, aiogram/methods/*.py, aiogram/enums/*.py)
  • Add features via .butcher YAML config/aliases + templates, then regenerate
  • After codegen: always run lint + mypy

Naming patterns

  • Enums: PascalCase class, UPPER_SNAKE members (e.g., ContentType.TEXT)
  • Test files: test_<module_name>.py
  • Test classes: Test<ClassName> with async def test_<scenario>(self, bot: MockedBot)