mirror of
https://github.com/aiogram/aiogram.git
synced 2026-04-08 16:37:47 +00:00
45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
|
# Bot API Codegen Workflow
|
||
|
|
|
||
|
|
## How code generation works
|
||
|
|
aiogram uses `butcher` (via `aiogram-cli`) to auto-generate Python files from the Telegram Bot API schema.
|
||
|
|
|
||
|
|
### Source of truth
|
||
|
|
- `.butcher/schema/schema.json` — full parsed Bot API schema
|
||
|
|
- `.butcher/types/<TypeName>/entity.json` — parsed entity metadata (DO NOT edit)
|
||
|
|
- `.butcher/methods/<MethodName>/entity.json` — parsed method metadata (DO NOT edit)
|
||
|
|
- `.butcher/enums/<EnumName>/entity.json` — parsed enum metadata (DO NOT edit)
|
||
|
|
- `.butcher/templates/` — Jinja2 templates that produce Python code
|
||
|
|
- YAML alias/override files in `.butcher/types/`, `.butcher/methods/` — edit these for customizations
|
||
|
|
|
||
|
|
### Generated files (DO NOT hand-edit)
|
||
|
|
- `aiogram/types/*.py` (except `base.py`, `custom.py`, `_union.py` — framework internals)
|
||
|
|
- `aiogram/methods/*.py` (except `base.py`)
|
||
|
|
- `aiogram/enums/*.py`
|
||
|
|
- `aiogram/client/bot.py` (the `Bot` class shortcuts)
|
||
|
|
- `aiogram/types/__init__.py`, `aiogram/methods/__init__.py`
|
||
|
|
|
||
|
|
### Regeneration commands
|
||
|
|
```bash
|
||
|
|
uv run --extra cli butcher parse # re-parse from API schema
|
||
|
|
uv run --extra cli butcher refresh # refresh entity JSON from parsed schema
|
||
|
|
uv run --extra cli butcher apply all # apply templates → generate Python files
|
||
|
|
```
|
||
|
|
|
||
|
|
### Adding a new type/method/shortcut
|
||
|
|
1. Update the `.butcher` YAML alias/config file for the entity
|
||
|
|
2. Run regeneration (parse → refresh → apply)
|
||
|
|
3. Run lint + mypy + tests
|
||
|
|
4. Commit both the `.butcher` config changes AND the generated Python files
|
||
|
|
|
||
|
|
### API version bumps (maintainers)
|
||
|
|
```bash
|
||
|
|
make update-api args=patch # or minor/major
|
||
|
|
```
|
||
|
|
This runs butcher parse/refresh/apply + version bump scripts that update:
|
||
|
|
- `aiogram/__meta__.py`
|
||
|
|
- `README.rst`
|
||
|
|
- `docs/index.rst`
|
||
|
|
|
||
|
|
## Key constraint
|
||
|
|
The maintainers enforce: **never add types/methods/shortcuts by hand-editing generated files**. All changes must go through `.butcher` config so future regenerations preserve them.
|