AIOgram FAQ по миграции с версии 2.x на 3.0

Внимание. Перевод статьи сделан по первой версии и может измениться в будущем.
Актуальная версия доступна в официальной документации по ссылке: Документация.

Третья версия вводит много изменений, которые могут нарушить работу вашего кода, но также привносит архитектурные улучшения, помогающие сократить количество глобальных переменных, предоставляет полезные механизмы для разделения кода на модули или создания общих модулей через пакеты на PyPi, делает middleware и фильтры более контролируемыми и другие изменения.

На этой странице вы можете прочитать об изменениях, относительно последней стабильной версии 2.x.

Dispatcher.

• Класс Dispatcher теперь не принимает экземпляр Bot в инициализатор, он должен передаваться в Dispatcher только для запуска опроса или обработки события из вебхука. Также такой подход добавляет возможность использовать несколько экземпляров бота одновременно ("multibot").
• Теперь класс Dispatcher может быть расширен за счет того, что к нему можно добавить еще один элемент, похожий на него, названный Router (Подробнее читайте здесь). С помощью маршрутов (routes) вы легко можете разделить свой код на несколько модулей и, возможно, использовать эти модули в разных проектах.
• Из всех декораторов обработчиков событий и методов регистрации удален суффикс _handler (Подробнее читайте здесь).
• Executor полностью удален, теперь для запуска опроса (polling) или вебхука вы можете использовать Dispatcher непосредственно.
• Метод Throttling полностью удален, вы можете использовать middleware для управления контекстом выполнения и использовать любой механизм ограничения скорости, который вам необходим.
• Из API-типов Bot и объекта Dispatcher удалены глобальные переменные контекста, теперь, если вы хотите получить текущий экземпляр бота в обработчиках или фильтрах, то вы должны принимать аргумент bot: Bot и использовать его вместо Bot.get_current(). Внутри middlewares он может быть получен через data["bot"].
• Теперь, чтобы пропустить ожидающие обновления, вам следует вызвать метод aiogram.methods.delete_webhook.DeleteWebhook напрямую, а не передавать skip_updates=True методу start_polling.

Фильтрация событий (Filtering events).

• Фильтры по ключевым словам больше нельзя использовать, используйте фильтры явно. (Подробнее читайте здесь).
• Из-за удаления фильтров по ключевым словам, включенных по умолчанию (теперь не включены статус и тип контента), их нужно указывать явно, если вы хотите их использовать. Например, вместо использования @dp.message_handler(content_types=ContentType.PHOTO) вы должны использовать @router.message(F.photo).
• Большинство обычных фильтров заменено "волшебным фильтром". (Подробнее читайте здесь).
• Теперь обработчик сообщений по умолчанию получает любой тип контента, если вы хотите определенный тип, просто добавьте фильтры (волшебные или любые другие).
• Фильтр статуса теперь по умолчанию не включен, это означает, что если вы использовали state="*" во второй версии, то в третьей вы не должны передавать фильтр статуса, и наоборот, если статус во второй не был указан, теперь вы должны указать статус.
• Добавлена возможность регистрации глобальных фильтров на роутере, что помогает уменьшить количество повторений в коде и облегчает контроль над тем, для чего используется каждый роутер.

Bot API.

• Теперь все методы API являются классами с проверкой (через pydantic) (все вызовы API также доступны в виде методов в классе Bot).
• Добавлено больше предопределенных перечислений и перемещено в подпакет aiogram.enums. Например, перечисление типов чата теперь представлено как aiogram.enums.ChatType вместо aiogram.types.chat.ChatType. (Подробнее читайте здесь)
• HTTP-сессия клиента теперь разделена на контейнер, который может быть использован между различными экземплярами Bot в приложении.
• Исключения API больше не классифицируются по специфическому сообщению из-за того, что Telegram не имеет документированных кодов ошибок. Но все ошибки классифицированы по коду состояния HTTP, и для каждого метода может быть только один случай с одним и тем же кодом, поэтому в большинстве случаев вам нужно проверять только ошибку по типу (по коду состояния), не проверяя сообщение об ошибке. (Подробнее читайте здесь)

Middlewares.

• Теперь middlewares могут контролировать контекст выполнения, например, используя контекстные менеджеры (Подробнее читайте здесь)
• Вся контекстная информация теперь общая для middlewares, фильтров и обработчиков для использования от начала до конца. Например, теперь вы можете легко передавать некоторые данные в контекст внутри middlewares и получать их на уровне фильтров таким же образом, как в обработчиках через именованные аргументы.
• Добавлен механизм с названием "флаги" (flags), который помогает настроить поведение обработчика в сочетании с middlewares. (Подробнее читайте здесь)

Разметка клавиатуры (Keyboard Markup).

• Сейчас у aiogram.types.inline_keyboard_markup.InlineKeyboardMarkup и aiogram.types.reply_keyboard_markup.ReplyKeyboardMarkup нет методов для расширения, вместо этого вы должны использовать "строители разметки" (markup builders) aiogram.utils.keyboard.ReplyKeyboardBuilder и aiogram.utils.keyboard.KeyboardBuilder соответственно (Подробнее читайте здесь)

Данные обратных вызовов (Callbacks data).

• Теперь фабрика callback-данных строго типизирована через модели pydantic (Подробнее читайте здесь)

Машина состояний (Finite State machine).

• Фильтр состояния больше не будет автоматически добавляться ко всем обработчикам, вам нужно будет явно указать состояние, если вы хотите его использовать.
• Добавлена возможность изменения стратегии FSM (машин состояний), например, если вы хотите контролировать состояния для каждого пользователя в разделах чата, а не для всего чата, вы можете указать это в Dispatcher.
• Теперь у aiogram.fsm.state.State и aiogram.fsm.state.StateGroup нет вспомогательных методов, таких как .set(), .next(), и так далее. Вместо этого вы должны устанавливать состояния, передавая их напрямую в aiogram.fsm.context.FSMContext (Подробнее читайте здесь).
• Прокси состояния устарел, вам следует обновлять данные состояния, вызывая соответственно state.set_data(...) и state.get_data().

Отправка файлов (Sending Files).

• Теперь вам следует упаковывать отправку файлов в объект InputFile перед отправкой, вместо того чтобы непосредственно передавать объект IO в метод API. (Подробнее читайте здесь)

Webhook.

• Упрощена конфигурация веб-приложения aiohttp.
• Теперь по умолчанию добавлена возможность загрузки файлов при ответе через webhook.