Как установить aiogram в python

Знакомство с aiogram¶

Автор этой книги убеждён, что помимо теории должна быть и практика. Чтобы максимально упростить повторение приведённого далее кода, пришлось пойти на использование подходов, пригодных только для локальной разработки и обучения.

Так, например, во всех или почти во всех главах токен бота будет указываться прямо в исходных текстах. Это плохой подход, поскольку может привести к раскрытию токена, если вы забудете его удалить перед заливкой кода в публичный репозиторий (например, GitHub).

Или иногда в качестве хранилищ данных будут использоваться структуры, расположенные исключительно в оперативной памяти (словари, списки. ). В действительности такие объекты нежелательны, поскольку остановка бота приведёт безвозвратной потере данных.

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

Важно помнить, что автор ставит перед собой цель объяснить именно работу с Telegram Bot API при помощи aiogram, а не вообще весь Computer Science во всём его многообразии.

Терминология¶

Чтобы разговаривать в одних и тех же понятиях, введём некоторые термины, дабы в дальнейшем не путаться:

• ЛС — личные сообщения, в контексте бота это диалог один-на-один с пользователем, а не группа/канал.
• Чат — общее название для ЛС, групп, супергрупп и каналов.
• Апдейт — любое событие из этого списка: сообщение, редактирование сообщения, колбэк, инлайн-запрос, платёж, добавление бота в группу и т.д.
• Хэндлер — асинхронная функция, которая получает от диспетчера/роутера очередной апдейт и обрабатывает его.
• Диспетчер — объект, занимающийся получением апдейтов от Telegram с последующим выбором хэндлера для обработки принятого апдейта.
• Роутер — аналогично диспетчеру, но отвечает за подмножество множества хэндлеров. Можно сказать, что диспетчер — это корневой роутер.
• Фильтр — выражение, которое обычно возвращает True или False и влияет на то, будет вызван хэндлер или нет.
• Мидлварь — прослойка, которая вклинивается в обработку апдейтов.

Установка¶

Для начала давайте создадим каталог для бота, организуем там virtual environment (далее venv) и установим библиотеку aiogram.
Проверим, что установлен Python версии 3.9 (если вы знаете, что установлен 3.9 и выше, можете пропустить этот раздел):

Теперь создадим файл requirements.txt , в котором укажем используемую нами версию aiogram. Также нам понадобится библиотека python-dotenv для файлов конфигурации.

О версиях aiogram

В этой главе используется aiogram 3.x, перед началом работы рекомендую заглянуть в канал релизов библиотеки и проверить наличие более новой версии. Подойдёт любая более новая, начинающаяся с цифры 3, поскольку aiogram 2.x более рассматриваться не будет и считается устаревшим.

Обратите внимание на префикс «venv» в терминале. Он указывает, что мы находимся в виртуальном окружении с именем «venv». Проверим, что внутри venv вызов команды python указывает на всё тот же Python 3.9:

Последней командой deactivate мы вышли из venv, чтобы он нам не мешал.

Если для написания ботов вы используете PyCharm, рекомендую также установить сторонний плагин Pydantic для поддержки автодополнения кода в телеграмных объектах.

Первый бот¶

Давайте создадим файл bot.py с базовым шаблоном бота на aiogram:

Первое, на что нужно обратить внимание: aiogram — асинхронная библиотека, поэтому ваши хэндлеры тоже должны быть асинхронными, а перед вызовами методов API нужно ставить ключевое слово await, т.к. эти вызовы возвращают корутины.

Асинхронное программирование в Python

Не стоит пренебрегать официальной документацией!
Прекрасный туториал по asyncio доступен на сайте Python.

Если вы в прошлом работали с какой-то другой библиотекой для Telegram, например, pyTelegramBotAPI, то концепция хэндлеров (обработчиков событий) вам сразу станет понятна, разница лишь в том, что в aiogram хэндлерами управляет диспетчер.
Диспетчер регистрирует функции-обработчики, дополнительно ограничивая перечень вызывающих их событий через фильтры. После получения очередного апдейта (события от Telegram), диспетчер выберет нужную функцию обработки, подходящую по всем фильтрам, например, «обработка сообщений, являющихся изображениями, в чате с ID икс и с длиной подписи игрек». Если две функции имеют одинаковые по логике фильтры, то будет вызвана та, что зарегистрирована раньше.

Чтобы зарегистрировать функцию как обработчик сообщений, нужно сделать одно из двух действий:
1. Навесить на неё декоратор, как в примере выше. С различными типами декораторов мы познакомимся позднее.
2. Напрямую вызвать метод регистрации у диспетчера или роутера.

Рассмотрим следующий код:

Давайте запустим с ним бота:

Хэндлер cmd_test2 не сработает, т.к. диспетчер о нём не знает. Исправим эту ошибку и отдельно зарегистрируем функцию:

Снова запустим бота:

Синтаксический сахар¶

Для того чтобы сделать код чище и читабельнее, aiogram расширяет возможности стандартных объектов Telegram. Например, вместо bot.send_message(. ) можно написать message.answer(. ) или message.reply(. ) . В последних двух случаях не нужно подставлять chat_id , подразумевается, что он такой же, как и в исходном сообщении.
Разница между answer и reply простая: первый метод просто отправляет сообщение в тот же чат, второй делает «ответ» на сообщение из message :

Более того, для большинства типов сообщений есть вспомогательные методы вида «answer_» или «reply_«, например:

что значит ‘message: types.Message’ ?

Python является интерпретируемым языком с сильной, но динамической типизацией, поэтому встроенная проверка типов, как, например, в C++ или Java, отсутствует. Однако начиная с версии 3.5 в языке появилась поддержка подсказок типов, благодаря которой различные чекеры и IDE вроде PyCharm анализируют типы используемых значений и подсказывают программисту, если он передаёт что-то не то. В данном случае подсказка types.Message соообщает PyCharm-у, что переменная message имеет тип Message , описанный в модуле types библиотеки aiogram (см. импорты в начале кода). Благодаря этому IDE может на лету подсказывать атрибуты и функции.

При вызове команды /dice бот отправит в тот же чат игральный кубик. Разумеется, если его надо отправить в какой-то другой чат, то придётся по-старинке вызывать await bot.send_dice(. ) . Но объект bot (экземпляр класса Bot) может быть недоступен в области видимости конкретной функции. В aiogram 3.x объект бота, которому пришёл апдейт, неявно прокидывается в хэндлер и его можно достать как аргумент bot . Предположим, вы хотите по команде /dice отправлять кубик не в тот же чат, а в канал с ID -100123456789. Перепишем предыдущую функцию:

Передача доп. параметров¶

Иногда при запуске бота может потребоваться передать одно или несколько дополнительных значений. Это может быть объект конфигурации, список администраторов группы, отметка времени и что угодно ещё. Для этого достаточно передать параметры как дополнительные именованные (!) аргументы функции start_polling(. ) (для вебхуков есть аналогичный способ). В хэндлерах для получения этих значений достаточно указать их как те же аргументы. Более того, изменение таких объектов в одних хэндлерах влияют на их содержимое в других. Рассмотрим на примере:

Теперь список mylist можно читать и писать в разных хэндлерах. Существует также ещё один вариант, более подходящий в других ситуациях. Речь, конечно же, о мидлварях, про которые подробно рассказывается в соответствующей главе.

Файлы конфигурации¶

Чтобы не хранить токен прямо в коде (вдруг вы захотите залить своего бота в публичный репозиторий?) можно вынести подобные данные в отдельный конфигурационный файл. Существует хорошее и адекватное мнение, что для прода достаточно переменных окружения, однако в рамках этой книги мы будем пользоваться отдельными файлами .env , чтобы немного упростить себе жизнь и сэкономить читателям время на разворачивание демонстрационного проекта.

Итак, создадим рядом с bot.py отдельный файл config_reader.py со следующим содержимым

Теперь немного отредактируем наш bot.py :

Наконец, создадим файл .env (с точкой в начале), где опишем токен бота:

Если всё сделано правильно, то при запуске python-dotenv подгрузит переменные из файла .env , pydantic их провалидирует и объект бота успешно создастся с нужным токеном.

На этом мы закончим знакомство с библиотекой, а в следующих главах рассмотрим другие «фишки» aiogram и Telegram Bot API.

Installation Guide

aiogram is also available in Arch Linux Repository, so you can install this framework on any Arch-based distribution like Arch Linux, Antergos, Manjaro, etc. To do this, just use pacman to install the python-aiogram package:

From sources

Or if you want to install stable version (The same with version from PyPi):

Recommendations

You can speedup your bots by following next instructions:

Use uvloop instead of default asyncio loop.

uvloop is a fast, drop-in replacement of the built-in asyncio event loop. uvloop is implemented in Cython and uses libuv under the hood.

Installation:

Use ujson instead of the default json module.

UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for Python 2.5+ and 3.

Installation:

Use aiohttp speedups

Use cchardet instead of the chardet module.

cChardet is a high speed universal character encoding detector.

Installation:

Use aiodns for speeding up DNS resolving.

aiodns provides a simple way for doing asynchronous DNS resolutions.

Installation:

Installing speedups altogether.

The following will get you aiohttp along with cchardet , aiodns and brotlipy in one bundle.

Installation:

In addition, you don’t need do anything, aiogram automatically starts using that if it is found in your environment.

Бот на Python. Основы

Для связи написанного кода и бота в Telegram нужно зарегистрировать бота у BotFather и получить его токен.

Давайте создадим файл bot.py с базовым шаблоном бота на aiogram:

Разберем подробнее некоторые фрагменты кода:

Мы обращаемся к декоратору dp — диспетчеру бота, которые будет срабатывать только если ввели команду /test . Тем самым, мы говорим компилятору, что используем специальную библиотеку для создания ботов.

В aiogram хэндлерами управляет диспетчер. Диспетчер регистрирует функции-обработчики, дополнительно ограничивая перечень вызывающих их событий через фильтры. После получения очередного апдейта (события от Telegram), диспетчер выберет нужную функцию обработки, подходящую по всем фильтрам, например, «обработка сообщений, являющихся изображениями, в чате с ID x и с длиной подписи y». Если две функции имеют одинаковые по логике фильтры, то будет вызвана та, что зарегистрирована раньше.

Объявляем асинхронную функцию (может запускаться самостоятельно), переопределяем встроенный в aiogram тип types.Message как message. Используем метод reply, который отвечает на отправленное пользователем сообщение.

Python является интерпретируемым языком с сильной, но динамической типизацией, поэтому встроенная проверка типов, как, например, в C++ или Java, отсутствует. Однако начиная с версии 3.5 в языке появилась поддержка подсказок типов, благодаря которой различные чекеры и IDE вроде PyCharm анализируют типы используемых значений и подсказывают программисту, если он передаёт что-то не то. В данном случае подсказка types.Message соообщает PyCharm-у, что переменная message имеет тип Message , описанный в модуле types библиотеки aiogram (см. импорты в начале кода). Благодаря этому IDE может на лету подсказывать атрибуты и функции.

Когда мы запускаем компилятор, глобальная переменная __name__ получает значение __main__ . Таким образом мы понимаем, что это запуск. Бот работает.

Installation Guide¶

or if you want to install development version (maybe unstable):

Recommendations¶

You can speedup your bots by following next instructions:

Use uvloop instead of default asyncio loop.

uvloop is a fast, drop-in replacement of the built-in asyncio event loop. uvloop is implemented in Cython and uses libuv under the hood.

Installation:

Use ujson instead of default json module.

UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for Python 2.5+ and 3.

Installation:

In addition, you don’t need do nothing, aiogram is automatically starts using that if is found in your environment.