Знакомство с aiogram¶
Автор этой книги убеждён, что помимо теории должна быть и практика. Чтобы максимально упростить повторение приведённого далее кода, пришлось пойти на использование подходов, пригодных только для локальной разработки и обучения.
Так, например, во всех или почти во всех главах токен бота будет указываться прямо в исходных текстах. Это плохой подход, поскольку может привести к раскрытию токена, если вы забудете его удалить перед заливкой кода в публичный репозиторий (например, GitHub).
Или иногда в качестве хранилищ данных будут использоваться структуры, расположенные исключительно в оперативной памяти (словари, списки. ). В действительности такие объекты нежелательны, поскольку остановка бота приведёт безвозвратной потере данных.
Также механизмом получения апдейтов от Telegram выбран поллинг, поскольку он гарантированно работает в подавляющем большинстве окружений и подходит практически всем разработчикам.
Важно помнить, что автор ставит перед собой цель объяснить именно работу с Telegram Bot API при помощи aiogram, а не вообще весь Computer Science во всём его многообразии.
Терминология¶
Чтобы разговаривать в одних и тех же понятиях, введём некоторые термины, дабы в дальнейшем не путаться:
- ЛС — личные сообщения, в контексте бота это диалог один-на-один с пользователем, а не группа/канал.
- Чат — общее название для ЛС, групп, супергрупп и каналов.
- Апдейт — любое событие из этого списка: сообщение, редактирование сообщения, колбэк, инлайн-запрос, платёж, добавление бота в группу и т.д.
- Хэндлер — асинхронная функция, которая получает от диспетчера/роутера очередной апдейт и обрабатывает его.
- Диспетчер — объект, занимающийся получением апдейтов от Telegram с последующим выбором хэндлера для обработки принятого апдейта.
- Роутер — аналогично диспетчеру, но отвечает за подмножество множества хэндлеров. Можно сказать, что диспетчер — это корневой роутер.
- Фильтр — выражение, которое обычно возвращает True или False и влияет на то, будет вызван хэндлер или нет.
- Мидлварь — прослойка, которая вклинивается в обработку апдейтов.
Установка¶
Для начала давайте создадим каталог для бота, организуем там virtual environment (далее venv) и установим библиотеку aiogram.
Проверим, что установлен Python версии 3.9 (если вы знаете, что установлен 3.9 и выше, можете пропустить этот раздел):
[groosha@main lesson_01]$ python3.9 Python 3.9.9 (main, Jan 11 2022, 16:35:07) [GCC 11.1.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> exit() [groosha@main lesson_01]$ Теперь создадим файл requirements.txt , в котором укажем используемую нами версию aiogram. Также нам понадобится библиотека python-dotenv для файлов конфигурации.
О версиях aiogram
В этой главе используется aiogram 3.x, перед началом работы рекомендую заглянуть в канал релизов библиотеки и проверить наличие более новой версии. Подойдёт любая более новая, начинающаяся с цифры 3, поскольку aiogram 2.x более рассматриваться не будет и считается устаревшим.
[groosha@main 01_quickstart]$ python3.9 -m venv venv [groosha@main 01_quickstart]$ echo "aiogram==3.0" > requirements.txt [groosha@main 01_quickstart]$ echo "python-dotenv==1.0.0" >> requirements.txt [groosha@main 01_quickstart]$ source venv/bin/activate (venv) [groosha@main 01_quickstart]$ pip install -r requirements.txt # . здесь куча строк про установку. Successfully installed . тут длинный список. [groosha@main 01_quickstart]$ Обратите внимание на префикс «venv» в терминале. Он указывает, что мы находимся в виртуальном окружении с именем «venv». Проверим, что внутри venv вызов команды python указывает на всё тот же Python 3.9:
(venv) [groosha@main 01_quickstart]$ python Python 3.9.9 (main, Jan 11 2022, 16:35:07) [GCC 11.1.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> exit() (venv) [groosha@main 01_quickstart]$ deactivate [groosha@main 01_quickstart]$ Последней командой deactivate мы вышли из venv, чтобы он нам не мешал.
Если для написания ботов вы используете PyCharm, рекомендую также установить сторонний плагин Pydantic для поддержки автодополнения кода в телеграмных объектах.
Первый бот¶
Давайте создадим файл bot.py с базовым шаблоном бота на aiogram:
import asyncio import logging from aiogram import Bot, Dispatcher, types from aiogram.filters.command import Command # Включаем логирование, чтобы не пропустить важные сообщения logging.basicConfig(level=logging.INFO) # Объект бота bot = Bot(token="12345678:AaBbCcDdEeFfGgHh") # Диспетчер dp = Dispatcher() # Хэндлер на команду /start @dp.message(Command("start")) async def cmd_start(message: types.Message): await message.answer("Hello!") # Запуск процесса поллинга новых апдейтов async def main(): await dp.start_polling(bot) if __name__ == "__main__": asyncio.run(main()) Первое, на что нужно обратить внимание: aiogram — асинхронная библиотека, поэтому ваши хэндлеры тоже должны быть асинхронными, а перед вызовами методов API нужно ставить ключевое слово await, т.к. эти вызовы возвращают корутины.
Асинхронное программирование в Python
Не стоит пренебрегать официальной документацией!
Прекрасный туториал по asyncio доступен на сайте Python.
Если вы в прошлом работали с какой-то другой библиотекой для Telegram, например, pyTelegramBotAPI, то концепция хэндлеров (обработчиков событий) вам сразу станет понятна, разница лишь в том, что в aiogram хэндлерами управляет диспетчер.
Диспетчер регистрирует функции-обработчики, дополнительно ограничивая перечень вызывающих их событий через фильтры. После получения очередного апдейта (события от Telegram), диспетчер выберет нужную функцию обработки, подходящую по всем фильтрам, например, «обработка сообщений, являющихся изображениями, в чате с ID икс и с длиной подписи игрек». Если две функции имеют одинаковые по логике фильтры, то будет вызвана та, что зарегистрирована раньше.
Чтобы зарегистрировать функцию как обработчик сообщений, нужно сделать одно из двух действий:
1. Навесить на неё декоратор, как в примере выше. С различными типами декораторов мы познакомимся позднее.
2. Напрямую вызвать метод регистрации у диспетчера или роутера.
Рассмотрим следующий код:
# Хэндлер на команду /test1 @dp.message(Command("test1")) async def cmd_test1(message: types.Message): await message.reply("Test 1") # Хэндлер на команду /test2 async def cmd_test2(message: types.Message): await message.reply("Test 2") 
Давайте запустим с ним бота:
Хэндлер cmd_test2 не сработает, т.к. диспетчер о нём не знает. Исправим эту ошибку и отдельно зарегистрируем функцию:
# Хэндлер на команду /test2 async def cmd_test2(message: types.Message): await message.reply("Test 2") # Где-то в другом месте, например, в функции main(): dp.message.register(cmd_test2, Command("test2")) 
Снова запустим бота:
Синтаксический сахар¶
Для того чтобы сделать код чище и читабельнее, aiogram расширяет возможности стандартных объектов Telegram. Например, вместо bot.send_message(. ) можно написать message.answer(. ) или message.reply(. ) . В последних двух случаях не нужно подставлять chat_id , подразумевается, что он такой же, как и в исходном сообщении.
Разница между answer и reply простая: первый метод просто отправляет сообщение в тот же чат, второй делает «ответ» на сообщение из message :
@dp.message(Command("answer")) async def cmd_answer(message: types.Message): await message.answer("Это простой ответ") @dp.message(Command("reply")) async def cmd_reply(message: types.Message): await message.reply('Это ответ с "ответом"') 
Более того, для большинства типов сообщений есть вспомогательные методы вида «answer_» или «reply_», например:
@dp.message(Command("dice")) async def cmd_dice(message: types.Message): await message.answer_dice(emoji="��") что значит ‘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. Перепишем предыдущую функцию:
# не забудьте про импорт from aiogram.enums.dice_emoji import DiceEmoji @dp.message(Command("dice")) async def cmd_dice(message: types.Message, bot: Bot): await bot.send_dice(-100123456789, emoji=DiceEmoji.DICE) Передача доп. параметров¶
Иногда при запуске бота может потребоваться передать одно или несколько дополнительных значений. Это может быть объект конфигурации, список администраторов группы, отметка времени и что угодно ещё. Для этого достаточно передать параметры как дополнительные именованные (!) аргументы функции start_polling(. ) (для вебхуков есть аналогичный способ). В хэндлерах для получения этих значений достаточно указать их как те же аргументы. Более того, изменение таких объектов в одних хэндлерах влияют на их содержимое в других. Рассмотрим на примере:
@dp.message(Command("add_to_list")) async def cmd_add_to_list(message: types.Message, mylist: list[int]): mylist.append(7) await message.answer("Добавлено число 7") @dp.message(Command("show_list")) async def cmd_show_list(message: types.Message, mylist: list[int]): await message.answer(f"Ваш список: mylist>") Теперь список mylist можно читать и писать в разных хэндлерах. Существует также ещё один вариант, более подходящий в других ситуациях. Речь, конечно же, о мидлварях, про которые подробно рассказывается в соответствующей главе.
Файлы конфигурации¶
Чтобы не хранить токен прямо в коде (вдруг вы захотите залить своего бота в публичный репозиторий?) можно вынести подобные данные в отдельный конфигурационный файл. Существует хорошее и адекватное мнение, что для прода достаточно переменных окружения, однако в рамках этой книги мы будем пользоваться отдельными файлами .env , чтобы немного упростить себе жизнь и сэкономить читателям время на разворачивание демонстрационного проекта.
Итак, создадим рядом с bot.py отдельный файл config_reader.py со следующим содержимым
config_reader.py
from pydantic_settings import BaseSettings, SettingsConfigDict from pydantic import SecretStr class Settings(BaseSettings): # Желательно вместо str использовать SecretStr # для конфиденциальных данных, например, токена бота bot_token: SecretStr # Начиная со второй версии pydantic, настройки класса настроек задаются # через model_config # В данном случае будет использоваться файла .env, который будет прочитан # с кодировкой UTF-8 model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8') # При импорте файла сразу создастся # и провалидируется объект конфига, # который можно далее импортировать из разных мест config = Settings() Теперь немного отредактируем наш bot.py :
# импорты from config_reader import config # Для записей с типом Secret* необходимо # вызывать метод get_secret_value(), # чтобы получить настоящее содержимое вместо '*******' bot = Bot(token=config.bot_token.get_secret_value()) Наконец, создадим файл .env (с точкой в начале), где опишем токен бота:
BOT_TOKEN = 0000000000:AaBbCcDdEeFfGgHhIiJjKkLlMmNn Если всё сделано правильно, то при запуске python-dotenv подгрузит переменные из файла .env , pydantic их провалидирует и объект бота успешно создастся с нужным токеном.
На этом мы закончим знакомство с библиотекой, а в следующих главах рассмотрим другие «фишки» aiogram и Telegram Bot API.
Installation Guide¶
or if you want to install development version (maybe unstable):
$ git clone https://github.com/aiogram/aiogram.git $ cd aiogram $ git checkout dev-2.x $ python setup.py install
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:
$ pip install uvloop
UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for Python 2.5+ and 3. Installation:
$ pip install ujson
In addition, you don’t need do nothing, aiogram is automatically starts using that if is found in your environment.
© Copyright 2019, Illemius / Alex Root Junior Revision 9b9c1b08 .
Built with Sphinx using a theme provided by Read the Docs.
Read the Docs v: latest
Versions latest stable Downloads On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.
Урок 1. Быстрый старт. Эхо-бот
Перед началом убедитесь, что у вас установлен интерпретатор языка Python версии не ниже 3.6 (актуальные версии посмотреть и скачать можно здесь). Первый и второй уроки будут проведены на версии 3.6.4, версия библиотеки aiogram 1.0.4 , проверено на версии 1.1.
Этот пункт можно пропустить, если вы не новичок, и уже всё проверили.
Проверить версию интерпретатора можно следующим образом (справедливо для большинства систем): python —version . Будет возвращено Python 3.6.4 . Если у вас установлено несколько версий интерпретатора, будет необходимо указать версию: python3 —version .
Далее устанавливаем библиотеку командой pip install -U aiogram . Если у вас установлено несколько интерпретаторов (например 2 и 3), то необходимо явно указать версию pip: pip3 install -U aiogram . Если у вас установлено несколько версий 3 (например 3.4, 3.5, 3.6), то обращаемся к необходимому интерпретатору командой -m pip . , то есть в данном случае python3.6 -m pip install -U aiogram . Проверить версию библиотеки можно командой pip freeze | grep aiogram (тут так же не забудьте правильно указать версию pip), вернется aiogram==1.0.4 . Возможно, у вас в Windows не будет работать команда grep , тогда используйте просто команду pip freeze и убедитесь в присутствии aiogram в результате выполнения команды.
Начинаем писать код
Давайте для знакомства с библиотекой создадим бота, который будет приветствовать пользователя и высылать в ответ присланный ему текст. Для этого создадим каталог для нашего бота и сохраним там два файла: bot.py и config.py .
Открываем последний любимым текстовым редактором и записываем туда токен, полученный от @BotFather:
TOKEN = '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11' Теперь возьмемся за основной файл — приступаем к редактированию файла bot.py . Для этого импортируем необходимые модули библиотеки aiogram и токен бота, а так же инициализируем объекты бота и диспетчера:
from aiogram import Bot, types from aiogram.dispatcher import Dispatcher from aiogram.utils import executor from config import TOKEN bot = Bot(token=TOKEN) dp = Dispatcher(bot) Команда, с которой начинается общение пользователя с ботом — /start . Поэтому давайте научим нашего бота реагировать на эту команду. Создаем message_handler и объявляем там функцию ответа:
@dp.message_handler(commands=['start']) async def process_start_command(message: types.Message): await message.reply("Привет!\nНапиши мне что-нибудь!") Ещё в ботах принято создавать обработчик команды /help — вдруг пользователь заинтересуется возможностями бота.
Вообще, мы могли бы добавить просто help в массив, передаваемый параметру commands , чтобы получилось:
@dp.message_handler(commands=['start', 'help']) Но зачем приветствовать пользователя снова? Поэтому создадим отдельный message_handler для этой команды:
@dp.message_handler(commands=['help']) async def process_help_command(message: types.Message): await message.reply("Напиши мне что-нибудь, и я отпрпавлю этот текст тебе в ответ!") Обращу внимание новичка на то, что называть функции можно как угодно — хоть abc , хоть qwerty , однако называя функции понятным языком — process_start_command , process_help_command сразу понятно, какая за что отвечает. Главное, чтобы имена не повторялись. Называть как угодно можно также и имя параметра, покажу дальше.
Итак! Осталось сделать обработку текстового сообщения. Для этого пишем следующее:
@dp.message_handler() async def echo_message(msg: types.Message): await bot.send_message(msg.from_user.id, msg.text) Объясняю, что мы только что написали:
Если не указывать тип обрабатываемого сообщения, то библиотека по умолчанию делает обработку только текстовых сообщений — то, что нам и нужно. Поэтому скобки на первой строчке остаются пустыми.
Параметр msg это всё то же сообщение, как и в предыдущих пунктах.
В данном случае на последней строчке мы отправляем пользователю сообщение не ответом, а простым сообщением. Для этого мы воспользовались методом send_message и передали в него два обязательных параметра — айди чата, куда отправляем, и сам текст сообщения. Их мы взяли из объекта msg, который является представителем класса Message. Параметр from_user ссылается на ещё один объект — данный параметр имеет класс User. У него есть параметр id — уникальный идентификатор для чатов и каналов в телеграме. Ну и текст полученного сообщения мы получили из поля text.
Финальный штрих
Чтобы получать сообщения от серверов Telegram воспользуемся поллингом (polling. to poll — опрашивать) — постоянным опросом сервера на наличие новых обновлений. Для этого дописываем в bot.py следующее:
if __name__ == '__main__': executor.start_polling(dp) from aiogram import Bot, types from aiogram.dispatcher import Dispatcher from aiogram.utils import executor from config import TOKEN bot = Bot(token=TOKEN) dp = Dispatcher(bot) @dp.message_handler(commands=['start']) async def process_start_command(message: types.Message): await message.reply("Привет!\nНапиши мне что-нибудь!") @dp.message_handler(commands=['help']) async def process_help_command(message: types.Message): await message.reply("Напиши мне что-нибудь, и я отпрпавлю этот текст тебе в ответ!") @dp.message_handler() async def echo_message(msg: types.Message): await bot.send_message(msg.from_user.id, msg.text) if __name__ == '__main__': executor.start_polling(dp) Осталось запустить программу. Для этого в командной строке переходим в директорию проекта и пишем
python bot.py 
Теперь можно написать нашему боту:
aiogram 3.1.1
aiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python 3.8 using asyncio and aiohttp.
Make your bots faster and more powerful!
- ���� English
- ���� Ukrainian
Features
- Asynchronous (asyncio docs, PEP 492)
- Has type hints (PEP 484) and can be used with mypy
- Supports PyPy
- Supports Telegram Bot API 6.9 and gets fast updates to the latest versions of the Bot API
- Telegram Bot API integration code was autogenerated and can be easily re-generated when API gets updated
- Updates router (Blueprints)
- Has Finite State Machine
- Uses powerful magic filters
- Middlewares (incoming updates and API calls)
- Provides Replies into Webhook
- Integrated I18n/L10n support with GNU Gettext (or Fluent)
It is strongly advised that you have prior experience working with asyncio before beginning to use aiogram.
If you have any questions, you can visit our community chats on Telegram:
- ���� @aiogram
- ���� @aiogramua
- ���� @aiogram_uz
- ���� @aiogram_kz
- ���� @aiogram_ru
- ���� @aiogram_fa
- ���� @aiogram_it
- ���� @aiogram_br