FAQ по переходу з версії 2.x на 3.0#

Небезпека

Цей посібник все ще в розробці.

Ця версія містить численні суттєві зміни та архітектурні покращення. Вона допомагає зменшити кількість глобальних змінних у вашому коді, надає корисні механізми для модуляризації вашого коду та дозволяє створювати спільні модулі за допомогою пакетів на PyPI. Крім того, серед інших покращень, він робить проміжне програмне забезпечення (мідлварі) та фільтри більш контрольованими.

На цій сторінці ви можете прочитати про зміни, внесені в останню стабільну версію 2.x.

Примітка

Ця сторінка більше нагадує детальний список змін, ніж посібник з міграції, але вона буде оновлюватися в майбутньому.

Не соромтеся зробити свій внесок у цю сторінку, якщо ви знайшли щось, про що тут не згадано.

Dispatcher#

  • Клас Dispatcher більше не приймає екземпляр Bot у своєму ініціалізаторі. Замість цього екземпляр Bot слід передавати диспетчеру тільки для запуску полінгу або обробки подій з вебхуків. Такий підхід також дозволяє використовувати декілька екземплярів бота одночасно («мультибот»).

  • Клас Dispatcher тепер можна розширити ще одним об’єктом на кшталт диспетчера з назвою Router (Детальніше »).

  • За допомогою роутерів ви можете легко модулювати свій код і потенційно перевикористовувати ці модулі між проектами.

  • Видалено суфікс _handler з усіх декораторів обробників подій та методів реєстрації. (Детальніше »)

  • The Executor has been entirely removed; you can now use the Dispatcher directly to start poll the API or handle webhooks from it.

  • Метод дроселювання (Throttling) повністю вилучено; тепер ви можете використовувати проміжне програмне забезпечення (middleware) для керування контекстом виконання та реалізовувати будь-який механізм дроселювання за вашим бажанням.

  • Вилучено глобальні контекстні змінні з типів API, об’єктів Bot та Dispatcher, Відтепер, якщо ви хочете отримати доступ до поточного екземпляру бота в обробниках або фільтрах, ви повинні приймати аргумент bot: Bot і використовувати його замість Bot.get_current(). У проміжному програмному забезпеченні (middleware) доступ до нього можна отримати через data["bot"].

  • Щоб пропустити очікувані оновлення, тепер вам слід викликати метод aiogram.methods.delete_webhook.DeleteWebhook безпосередньо, а не передавати skip_updates=True до методу запуску полінгу.

Фільтрація подій#

  • Фільтри за ключовими словами більше не можна використовувати; використовуйте фільтри явно. (Детальніше »)

  • У зв’язку з вилученням keyword фільтрів, всі раніше ввімкнені за замовчуванням фільтри (такі як state і content_type) тепер вимкнено. Якщо ви бажаєте їх використовувати, ви повинні вказати їх явно. Наприклад, замість @dp.message_handler(content_types=ContentType.PHOTO) слід використовувати @router.message(F.photo).

  • Most common filters have been replaced with the «magic filter.» (Read more »)

  • За замовчуванням обробник повідомлень тепер отримує будь-який тип вмісту. Якщо вам потрібен певний тип, просто додайте відповідні фільтри (Magic або будь-який інший).

  • Фільтр стану більше не вмикається за замовчуванням. Це означає, що якщо ви використовували state="*" у v2, вам не слід передавати фільтр стану у v3. І навпаки, якщо стан не було вказано у v2, вам потрібно буде вказати його у v3.

  • Додано можливість реєстрації глобальних фільтрів для кожного роутера, що допомагає зменшити повторення коду і полегшує контроль призначення кожного роутера.

Bot API#

  • Всі методи API тепер є класами з валідацією, реалізованими через pydantic <https://docs.pydantic.dev/>. Ці виклики API також доступні як методи в класі Bot.

  • Додано більше попередньо визначених enums та переміщено їх до підпакету aiogram.enums. Наприклад, enum типу чату тепер має вигляд aiogram.enums.ChatType замість aiogram.types.chat.ChatType.

  • Клієнтська сесія HTTP була відокремлена в контейнер, який можна повторно використовувати для різних екземплярів бота в додатку.

  • Виключення API більше не класифікуються за конкретними повідомленнями, оскільки Telegram не має задокументованих кодів помилок. Проте всі помилки класифікуються за кодами статусу HTTP, і для кожного методу з певним кодом може бути пов’язаний лише один тип помилки. Тому в більшості випадків слід перевіряти лише тип помилки (за кодом статусу), не перевіряючи повідомлення про помилку.

Проміжне ПО (Middlewares)#

  • Проміжне програмне забезпечення тепер може керувати контекстом виконання, наприклад, за допомогою менеджерів контексту. (Детальніше »)

  • Всі контекстні дані тепер наскрізно використовуються між проміжним програмним забезпеченням, фільтрами та обробниками. Наприклад, тепер ви можете легко передати деякі дані в контекст у проміжному програмному забезпеченні і отримати їх у шарі фільтрів так само, як і в обробниках через аргументи ключових слів.

  • Додано механізм з назвою flags, який допомагає налаштовувати поведінку обробника у поєднанні з проміжним програмним забезпеченням. (Детальніше про »)

Розмітка клавіатури#

Callbacks data#

  • Фабрику даних зворотного виклику тепер строго типізовано за допомогою моделей pydantic. (Детальніше »)

Скінченний автомат#

  • Фільтри станів більше не будуть автоматично додаватися до всіх обробників; вам потрібно буде вказати стан, якщо ви хочете його використати.

  • Додано можливість змінювати стратегію FSM. Наприклад, якщо ви хочете контролювати стан для кожного користувача на основі топіків чату, а не користувача в чаті, ви можете вказати це в Диспетчері.

  • Тепер aiogram.fsm.state.State та aiogram.fsm.state.StateGroup не мають допоміжних методів, таких як .set(), .next() тощо.

  • Замість цього вам слід встановлювати стани, передаючи їх безпосередньо до aiogram.fsm.context.FSMContext (Детальніше »)

  • Проксі стану є застарілим; вам слід оновити дані стану, викликавши state.set_data(...) та state.get_data() відповідно.

Надсилання файлів#

  • Відтепер перед відправкою файлів слід обертати їх в об’єкт InputFile замість того, щоб передавати об’єкт вводу-виводу безпосередньо до методу API. (Детальніше »)

Webhook#

  • Спрощено налаштування веб-застосунку aiohttp.

  • By default, the ability to upload files has been added when you make requests in response to updates (available for webhook only).

Сервер Telegram API#

  • Параметр server було перенесено з екземпляра Bot до api в BaseSession.

  • Константа aiogram.bot.api.TELEGRAM_PRODUCTION була переміщена на aiogram.client.telegram.PRODUCTION.