aiogram-max
Запускает бота, написанного на aiogram, в мессенджере MAX — без правок кода бота.
from aiogram import Dispatcher
from aiogram_max import make_bot
bot = make_bot(max_token="...") # единственная изменённая строка
await Dispatcher().start_polling(bot)
Роутеры, фильтры (Command, магический F), FSM, middleware и типы остаются
родными aiogram-овскими.
Статус
Рабочая библиотека, проверенная на живом MAX. Настоящий
Dispatcher.start_polling ходит в MAX Bot API, хендлеры срабатывают, ответы
и callback.answer() доезжают до мессенджера.
Покрыто 40 методов — всё, чему нашёлся аналог у платформы: сообщения и правки, вложения всех типов, клавиатуры и callback'и, группы с участниками и пинами, вебхук, команды бота, разметка. Каждый проверен на реальном боте, а не только тестами.
Как это работает
Весь исходящий трафик aiogram проходит через одну функцию:
BaseSession.make_request(bot, method: TelegramMethod, timeout) -> TelegramType
Bot не ходит в сеть сам: он собирает типизированный объект метода
(SendMessage, GetUpdates, AnswerCallbackQuery, …) и отдаёт его сессии.
Мы подменяем сессию — и перехватываем поток целиком:
Бот на aiogram (код не меняется)
Dispatcher / Router / фильтры / FSM
Bot.send_message(...)
│ TelegramMethod
▼
MaxSession(BaseSession) ← вся библиотека здесь
│ HTTP
▼
MAX Bot API
Long polling тоже работает штатно: aiogram сам зовёт GetUpdates, а сессия
ходит в GET /updates?marker= и собирает из событий MAX валидные
aiogram-Update.
Отличие от obabot, решающего похожую
задачу: там своя система типов (obabot.Message, obabot.FSMContext) и
импорты в боте меняются. Здесь типы остаются aiogram-овскими, подменяется
только транспорт.
Что уже проверено тестами
| Что | Как проверено |
|---|---|
MAX-событие → валидный aiogram Update |
test_get_updates_returns_aiogram_updates |
Роутер + фильтр Command |
test_dispatcher_routes_message_to_handler |
Inline-клавиатура → MAX inline_keyboard |
там же, сверка тела запроса |
Callback + магический фильтр F.data |
test_callback_query_flows_through_aiogram |
FSM (StatesGroup, FSMContext) |
test_fsm_state_survives_platform_swap |
Родной Dispatcher.start_polling |
test_native_polling_loop_delivers_max_events |
Правка сообщения (seq ↔ mid) |
test_edit_message_uses_max_mid |
| Неподдерживаемый метод | test_unsupported_method_raises_in_strict_mode |
| Живые payload'ы MAX | tests/test_live_fixtures.py (6 тестов на снятых с API событиях) |
| Потеря кнопки без аналога | test_dropped_button_warns_but_keeps_the_rest |
| Маппинг parse_mode / notify / reply | test_supported_params_are_mapped_not_dropped |
| Вложения: загрузка и отправка | test_send_photo_uploads_and_attaches_token |
| Ожидание обработки файла на стороне MAX | test_send_photo_waits_until_attachment_is_ready |
| MarkdownV2 → html (включая подчёркивание) | tests/test_markup.py, 11 тестов |
entities → html без потерь |
test_entities_are_no_longer_dropped_silently |
MarkupPolicy.RAW не трогает текст |
test_raw_policy_leaves_text_alone |
Неподдерживаемое в MAX
У MAX нет части возможностей Telegram. Политика задаётся при создании бота:
make_bot(token) # WARN, по умолчанию
make_bot(token, unsupported=UnsupportedPolicy.STRICT)
Расхождения бывают трёх видов:
- Метода нет вовсе (
SendPoll,SendDice).WARN— предупреждение и пропуск,STRICT—UnsupportedByMaxс именем метода. - Метод есть, а параметра нет (кнопка
web_app,switch_inline_query). Такая кнопка выбрасывается, остальные остаются:WARNпишет в лог что именно потерялось,STRICTпадает. Молча не выбрасываем никогда — «кнопка исчезла, а бот не упал» ищется потом часами. - Семантика другая — это работа слоя конвертации, а не политики:
message_id(int) ↔ MAXmid(str) сшиваются черезseq.
Где аналог есть — параметр переводится, а не теряется:
| aiogram | MAX |
|---|---|
parse_mode="HTML" |
format: html |
parse_mode="MarkdownV2" |
конвертация в html, см. «Разметка» |
entities=[...] |
конвертация в html, см. «Разметка» |
disable_notification=True |
notify: false |
reply_to_message_id |
link: {type: reply, mid} |
Отдельный случай — пустой callback.answer(). В Telegram он снимает
индикатор загрузки на кнопке и стоит почти в каждом хендлере; у MAX такой
семантики нет, POST /answers с пустым телом отвечает 400 proto.payload
(«message or notification required»). Запрос не уходит вовсе. С текстом —
answer("Принято") — уходит как notification.
Разметка
Работает из коробки: бот шлёт привычный телеграмный parse_mode или
entities, библиотека переводит это в html, который MAX понимает.
await bot.send_message(chat_id, "*жирный* и __подчёркнутый__", parse_mode="MarkdownV2")
# в MAX уедет: {"text": "<b>жирный</b> и <u>подчёркнутый</u>", "format": "html"}
Форматируете под MAX сами — отключите посредника:
make_bot(token, markup=MarkupPolicy.RAW) # текст уйдёт как есть
Почему html, а не markdown. MAX принимает оба формата, но markdown у него
CommonMark, а в CommonMark __текст__ — это жирный. В MarkdownV2 та же запись
означает подчёркивание, и перевод «markdown в markdown» молча превратил бы
одно в другое. Тип underline MAX отдаёт только за <u>. Вдобавок html не
требует правил экранирования, которых в MarkdownV2 полтора десятка, причём
внутри кодовых спанов они другие.
Что MAX действительно поддерживает. Официальная страница «Форматирование» отдаёт 404, поэтому таблица снята с живого API: бот отправил пробу, MAX вернул разобранную разметку.
| Разметка | format: html |
format: markdown |
|---|---|---|
| жирный | <b> → strong |
**x** → strong |
| курсив | <i> → emphasized |
*x*, _x_ → emphasized |
| подчёркнутый | <u> → underline |
нет: __x__ даёт strong |
| зачёркнутый | <s> → strikethrough |
~~x~~ → strikethrough |
| моноширинный | <code>, <pre> → monospaced |
`x` → monospaced |
| ссылка | <a href> → link |
[x](url) → link |
| заголовок | не проверялся | # x → heading |
| цитата | <blockquote> — не распознаётся |
> x — не распознаётся |
| списки, спойлер | нет | нет |
Чего у MAX нет вовсе — спойлер, цитата, кастомные эмодзи — проходит через ту
же политику unsupported: WARN пишет в лог что именно потерялось, STRICT
падает. Текст при этом сохраняется, теряется только оформление.
Грабли MAX, которые стоит знать
- Индикатор набора у MAX есть, вопреки расхожему мнению: работает и в
личке, и в группе. Только называется иначе — телеграмное
typingон не понимает, нужноtyping_on, и библиотека переводит сама. - Вложение не готово сразу после заливки. Отправка отвечает
400 attachment.not.ready, пока MAX обрабатывает файл. Библиотека ждёт и повторяет сама, но знать об этом стоит: в Telegram такого шага нет. recipient.user_id— это получатель сообщения, а не собеседник. В событии от пользователя там лежит id бота, в сообщении бота пользователю — id пользователя. Подставите его какchat_id— бот начнёт молча отвечать сам себе.chat_idв диалоге MAX присылает, брать надо только его.- Позиция в ленте —
marker, и она жеupdate_id. MAX отдаёт в ответе «следующую ожидаемую» позицию, что совпадает по смыслу с телеграмнымoffset. Поэтомуupdate_idсобытия — его позиция в ленте (marker - 1для последнего события пачки), а не порядковый номер внутри процесса. Для бота с дедупом поupdate_idэто принципиально: счётчик из памяти после рестарта начинается заново, и свежие события выглядят уже обработанными. seq— не маленький счётчик. Живое значение:116993690454357274. Вint64влезает и aiogram переваривает, но узкое поле БД (integerвместоbigint) на этом сломается./startприходит обычнымmessage_created, а не отдельным событием — фильтрCommandработает без спецобработки.- Идентификатор сообщения двойной: aiogram знает
message_id(int изseq), MAX правит и удаляет по строковомуmid. Соответствие держит сессия в памяти (последние 10 000 сообщений), поэтому правка переживает рестарт только в пределах жизни процесса. Обратного преобразованияmid → seqMAX не даёт, так что иначе никак.
Что ещё не сделано
- Webhook (у MAX это рекомендованный для прода транспорт).
- Разметка подписей (
caption,caption_entities) — вместе с вложениями. - Покрыто 40 методов из 185 в aiogram — всё, чему есть аналог у MAX. Что уже работает, что можно добавить и чего в MAX нет вовсе — в docs/method-coverage.md.
Установка
pip install aiogram-max # после публикации; пока — pip install -e .
Python 3.12+, единственные зависимости — aiogram и httpx. Библиотека
типизирована (py.typed), mypy strict проходит без ignore'ов.
Разработка
uv venv && uv pip install -e ".[dev]"
.venv/bin/ruff check . && .venv/bin/mypy && .venv/bin/pytest -q
Как добавить метод и чем NotImplementedYet отличается от UnsupportedByMax —
в CONTRIBUTING.md.
Лицензия
MIT
Metadata
Release files for aiogram-max 1.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiogram_max-1.1.2.tar.gz | 131.1 kB | Without provenance | Details for aiogram_max-1.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiogram_max-1.1.2-py3-none-any.whl | Python 3 | none | any | Details for aiogram_max-1.1.2-py3-none-any.whl |
Total release size: 171.3 kB
Release files / aiogram_max-1.1.2.tar.gz
| Download URL | aiogram_max-1.1.2.tar.gz |
|---|---|
| Size | 131.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e6a673c8267df2a1527617504d549ccee983b3d4c2cb1eeeb90e7f41b8737e91
|
|
BLAKE2b-256 checksum How to use checksums |
3c71d22df013e5c7027a9ce1143f5db55ce6ec9a7b7eda332b2f676f26a926a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aiogram_max-1.1.2-py3-none-any.whl
| Download URL | aiogram_max-1.1.2-py3-none-any.whl |
|---|---|
| Size | 40.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
adc58c1c3835908a71164320a2aa2546b8e5419ca4f7be09787a952333b2fba6
|
|
BLAKE2b-256 checksum How to use checksums |
329bcf8f4d60144f3124e9ee42e61e6125d61fb62f335d7f4e86da205114d9d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for aiogram-max 1.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.