Добро пожаловать!¶
Перед вами то, что я, Groosha, называю книгой по созданию Telegram-ботов на языке Python с помощью фреймворка aiogram. Её [книгу] можно воспринимать как учебный материал, обращаясь к отдельным главам по необходимости, но для первого прочтения рекомендую это делать в том порядке, в котором указаны главы слева от этого текста.
Это третья версия гайда, первая была написана в 2015-2017 годах для библиотеки pyTelegramBotAPI, а вторая появилась в 2019 для aiogram 2.x. В этой, обновлённой версии книги, мы будем использовать aiogram версии 3, полноценный релиз которого состоялся 1 сентября 2023 года.
Для кого эта книга?
Предполагается, что вы знакомы с программированием в целом и языком Python в частности, знаете, что такое «venv» и «pip», а также способны понять и исправить «детские» ошибки вроде SyntaxError и IndentationError. Найдите в интернете пару курсов по Python, пройдите их, а лишь затем принимайтесь за написание ботов, сэкономите себе время и нервные клетки.
Во всех главах в качестве операционной системы мы будем использовать что-нибудь семейства GNU/Linux, например, Ubuntu, Python 3.9 (в Virtual Environment) и среду разработки PyCharm, впрочем, не возбраняется и Visual Studio Code. При этом пользователи Windows не в пролёте: всё, что касается кода, будет спокойно работать и у вас, а для специфичных вещей вроде systemd вы можете использовать Ubuntu в VirtualBox.
Текст книги и исходные тексты в соответствующем репозитории полностью бесплатны, издаются под лицензией MIT и доступны любому для скачивания, модификации и использования в любых целях.
Донаты
На написание и актуализацию книги я потратил очень много времени и сил. Если вы из России и хотите отблагодарить автора материально, можете сделать это через Ю.Money (пожалуйста, указывайте в комментариях, что это за книгу).
На всякий случай уточню, что любое пожертвование является добровольным и не даёт никаких преимуществ, кроме плюсика в карму.
Благодарности
За то, что эта книга в её текущем виде возникла и существует по сей день, спасибо создателю aiogram Alex JRootJunior, контрибуторам в сам aiogram и репозиторий книги, а также вам, дорогие читатели!
Знакомство с 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 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) Передача доп. параметров¶
Иногда при запуске бота может потребоваться передать одно или несколько дополнительных значений. Это может быть какая-нибудь переменная, объект конфигурации, список чего-то, отметка времени и что угодно ещё. Для этого достаточно передать эти данные как именованные (kwargs) аргументы в диспетчер, либо присвоить значения, как если бы вы работали со словарём.
Такая возможность лучше всего подходит для передачи объектов, которые должны жить в единственном экземпляре и не меняться в ходе работы бота (т.е. быть только для чтения). Если предполагается, что значение должно изменяться со временем, то помните, что это сработает только с мутабельными объектами. Чтобы получить значения в хэндлерах, просто укажите их как аргументы. Рассмотрим на примере:
# Где-то в другом месте # Например, в точке входа в приложение from datetime import datetime # bot = . dp = Dispatcher() dp["started_at"] = datetime.now().strftime("%Y-%m-%d %H:%M") await dp.start_polling(bot, mylist=[1, 2, 3]) @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>") @dp.message(Command("info")) async def cmd_info(message: types.Message, started_at: str): await message.answer(f"Бот запущен started_at>") Теперь переменную started_at и список 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.
Урок 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 
Теперь можно написать нашему боту:
Телеграм-боты на Python и AIOgram
Курс «Телеграм-боты на Python и AIOgram» знакомит интересующихся с тем, как разрабатывать telegram-ботов на языке Python с использованием асинхронной библиотеки AIOgram.
Средний уровень
25 976 учащихся
Чему вы научитесь
- Создавать и настраивать телеграм-ботов с помощью @BotFather
- Взаимодействовать с Telegram Bot API посредством http-запросов
- Настраивать IDE VS Code для работы с Python
- Создавать виртуальное окружение для проектов на Python
- Разрабатывать телеграм-ботов с требуемым функционалом на Python с помощью асинхронной библиотеки AIOgram
- Работать со встроейнной в aiogram машиной состояний
- Обрабатывать ошибки, возникающие при работе ботов
- Настраивать систему контроля версий Git и размещать проект на GitHub
- Деплоить бота на удаленный сервер
- Настраивать автодеплой бота на удаленный сервер
- .
О курсе
На этом курсе вы научитесь создавать телеграм-ботов на Python с помощью продвинутой асихронной библиотеки aiogram.
Модули курса
- Общие сведения о телеграм-ботах
- Подготовка инструментов
- Git и GitHub
- Аннотации типов и логирование
- Telegram Bot API
- Асинхронность в Python
- Aiogram
- Первые телеграм-боты
- Структура проекта
- Взаимодействие с ботом
- Машина состояний (FSM)
- База данных
- Обработка ошибок бота
- Деплой бота на сервер
- Автодеплой
- Телеграм-бот с искусственным интеллектом
Когда-то подобного курса не хватало мне самому, поэтому он и появился. С целью облегчить начинающим python-разработчикам вход в тему разработки телеграм-ботов.
Начальные требования
Знание синтаксиса Python и основ программирования, включая ООП.