Знакомство с 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_
что значит ‘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.
Как написать Telegram-бота на Python: инструкция
В этой инструкции разберем процесс создания простого бота-ремайндера, единственная задача которого — напоминать пользователю о важных делах. Это базовая конструкция, которую можно усложнять и менять под свои потребности.
Инструкция подойдет для новичков, которые знают Python на базовом уровне, пробовали писать код и установили на компьютер редактор кода.
Первый этап: подготовка проекта и развертывание окружения
Найдем в поиске Telegram BotFather — официального бота мессенджера, который создает другие боты и управляет ими. В интерфейсе выбираем /start, затем — /newbot, и следом задаем имя и адрес. В этой инструкции это будут Elbrus Reminder и elbrus_reminder_bot соответственно.
После этого шага BotFather пришлет сообщение с токеном и ссылкой на бот:
Токен нужно хранить в безопасном месте — он дает контроль над ботом. и, как следствие, позволяет получить доступ к данным пользователей.
На время закроем Telegram и создадим на компьютере папку с именем проекта: например, reminder_bot. Откроем папку в среде разработки и создадим рабочий файл с понятным названием — bot.py.
Откроем терминал редактора кода и создадим для проекта новое окружение. В среде разработки с помощью команды python -m venv .venv создадим папку с окружением .venv .
Если окружение не активировалось автоматически, можно сделать это вручную, прописав путь к файлу активации в формате source .venv/bin/activate , где source — команда языка программирования Bash. Другой вариант — перезапустить среду разработки. Он работает для Visual Studio Code, но нужно предварительно принять предложение редактора привязать среду к папке проекта сразу после создания окружения.
Второй этап: подключаем библиотеки
Проект создан и окружение готово: пора переходить к написанию кода. По правилам хорошего тона в первую очередь через import добавляем несколько предустановленных библиотек Python. При создании бота нам пригодятся logging и time , которые отвечают за определение времени и логирование сообщений.
Затем добавим асинхронную библиотеку aiogram, на основе которой будет работать бот. Она, например, определяет, какое сообщение пришло, как его нужно обработать и какие порты нужны. Сначала устанавливаем ее через терминал командой pip install aiogram , а в редакторе кода пишем следующее:
Из этой библиотеки нам нужны только отдельные модули и классы — все ее возможности для создания базовой версии бота не пригодятся. Поэтому вместо одиночного import использована команда from <> import <> .
Когда библиотеки импортированы, создадим переменные с токеном бота и сообщением, которое он будет отправлять пользователю. Вы можете заменить это сообщение на любое другое, которое вам необходимо. Это статические переменные, поэтому их имена написаны капслоком:
Токены, ключи и прочие данные для настройки проекта лучше загружать более безопасным способом (например, создавать переменные окружения или файлы конфигурации). Но в данном случае сделаем все в одном файле для наглядности, а примеры более безопасной работы с такими переменными разберем в следующих постах.
Теперь создадим экземпляр класса Bot , передав ему в качестве аргумента наш токен, и экземпляр класса Dispatcher (dp), который в качестве аргумента получит bot . В результате получаем связку объекта класса bot с ключем, который привязан к боту, и диспетчера, который привязан к этому боту:
Следующим шагом добавим конструкцию под названием декоратор ( massage_handler ) — она помогает получить из диспетчера нужный функционал. В качестве аргумента прописываем команды, которые обрабатывает декоратор — в данном случае это команда /start , которая запускает бот.
Под декоратором прописываем функцию, которая будет обрабатывать команду /start и определяет логику, в соответствии с которой будет работать бот. Поскольку мы работаем с асинхронной библиотекой, функция тоже должна быть асинхронной. Для этого перед указанием def добавим ключевое слово async :
Функция приветствует пользователя и обрабатывает сообщение, которое он отправляет в ответ. Из сообщения можно получить информацию о пользователе, который его прислал, время отправки и его ID.
Создаем переменную и сохраняем в ней user id :
Затем получаем из сообщения короткое и полное имя пользователя:
Для того, чтобы в логах отображалась информация о пользователе, передаем в виде текста ID и полное имя, а также используем возможности библиотеки time , чтобы определить время, когда писал пользователь:
Здесь отойдем в сторону и проверим корректность работы модуля time . Сделать это можно в терминале: для этого напишем import time , а затем — time.asctime .
Вернемся к коду. Поскольку функция, которую мы используем, асинхронна, вместо обычного для функций return используем await :
Ответить пользователю в боте можно несколькими способами — в данном случае используем reply. Выше в переменной MSG мы задали стандартное сообщение: «Программировал ли ты сегодня, <>?». Зададим частоту напоминаний: семь раз каждые семь суток (60х60х24 — количество секунд в одних сутках) с момента отправки команды /start боту от пользователя:
Затем настроим отправку сообщения с указанием имени пользователя в этом же цикле:
Третий этап: финал
Переходим к финальной части: в конце скрипта напишем несколько строк. Они могут показаться странными для новичка, но это общепринятая практика, к которой многие программисты прибегают при разработке. В этой строке мы проверяем, равна ли переменная __name__ строке «__main__» . Это условие всегда будет True, если мы запускаем этот файл как python-скрипт через терминал:
Теперь делаем нашего бота доступным в сети:
Сохраняем файл. Запускаем бота в терминале, открытом в папке проекта, с помощью команды python bot.py .
Вернемся в BotFather и перейдем по ссылке, которую получили вместе с токеном. Нажимаем «Начать» — готово, бот, написанный меньше, чем в 30 строк, работает.
Так выглядит его код целиком:
В следующий раз подробно расскажем, как написать подобный бот на языке программирования JavaScript. Подписывайтесь, чтобы не пропустить инструкцию.
Best Practices Python — Where to store API KEYS/TOKENS
I am building a system that uses API tokens and keys to access services, but where is the best place to store them? I want to push the code to GitHub without pushing the tokens.
Currently, I’ve placed them in a blank file named Constants.py and, in the main python file, I import Constants.py .
3 Answers 3
What you are attempting is the correct way to segregate sensitive information from code. You should include the constants.py in your .gitignore file which will prevent git from tracking that file and thus not pushing it to github.
There are a few options:
Store it locally as you have and, as Sebastin Santy noted, add constants.py to your .gitignore file.
Store it as an environment variable if you’re using a conda virtual environment. Virtual environments aren’t stored; the requirements for creating one are in the requirements.txt file. You can find more on the steps from the conda documetation
If you have more than one set of environment variables, you might consider using decouple
If you’re using AWS, you’ll want to store the (what would be third party) keys in their own area with its own IAM. There are two ways recommended by AWS.
За границей Hello World: полный гайд по разработке Telegram ботов с помощью Python и Aiogram 3. Часть 1
Захотев однажды научиться разрабатывать ботов для Telegram на языке программирования Python, я просто зашёл в Яндекс и вбил что-то вроде «telegram бот на python для новичков» и нашёл казалось бы огромное множество гайдов и туториалов. Однако копнув немного глубже стало понятно, что большая часть гайдов заканчивается на прикреплении клавиатур к сообщениям, или ещё хуже, на написании эхо-бота.
Пришлось копаться в документации, шерстить форумы и учиться на примерах кода с GitHub. Этот гайд создан как полное руководство по разработке полноценного Telegram бота для работы с нейросетями, такими как ChatGPT и Dall-e, начиная установкой IDE и получением токена и заканчивая подключением оплаты, базы данных и загрузки бота на сервер.
Я считаю что гайд будет полезен прежде всего тем, кто уже пробовал разобраться в теме и имеет базовые знания. Чтобы гайд был полезным необходимо иметь базовые знания в Python, всё остальное вы можете изучить в процессе. Продвинутым разработчикам ботов большая часть будет знакома и вряд ли принесёт пользу, однако есть шанс, что и вы найдёте для себя что-то полезное. Жду любую конструктивную критику как по коду и его стилю, так и по изложению.
Что мы получим в итоге?
В конце гайда у нас получится полностью функционирующий бот, с админкой, оплатой, базой данных, реферальной программой и подключенным API OpenAI. По мере выхода статей код будет появляться в репозитории на GitHub.
Используемые технологии
Будут использованы следующие технологии:
VS Code (или любой другой удобный редактор или IDE)
Aiogram 3
Подготовка окружения
Разработка любой программы начинается с подготовки среды, так что приступим. Для начала устанавливаем VS Code или любую другую вашу любимую IDE или редактор кода. Скачиваем установщик с сайта, запускаем, устанавливаем. По умолчанию среда уже готова к работе, но рекомендую установить дополнительные расширения для Python, а также по желанию темы и другие плюшки.
Конечно же надо установить сам Python, но раз вы читаете это, то уверен, что либо уже сделали это, либо разберётесь сами. Скажу лишь, что использую версию 3.10, однако код также должен работать на версиях Python 3.8 и выше.
В VS Code переходим на вкладку Git, скачиваем и устанавливаем Git. Далее инициализируйте репозиторий и желательно опубликуйте его на GitHub (для удобства дальнейшей работы), это можно сделать прямо из VS Code.
После этого создадим виртуальное окружение, чтобы не засорять пакетами глобальyую среду. Подробнее про виртуальные окружения и преимущества их использования можете почитать здесь. Открываем палитру команд (Ctrl-Shift-P на Windows) и запускаем команду Python: Create Environment .
Далее выбираем venv и интерпретатор Python. Чтобы активировать виртуальное окружение, в терминале выполните команду .\.venv\Scripts\activate . Также выберите интерпретатор Python по умолчанию.
Выбранный интерпретатор должен находиться в папке .venv
Теперь пришло время установить все используемые библиотеки. Их список вы можете найти у меня на github. Там же я буду выкладывать весь код по мере выхода статей. Если вы скачали файл, то установить библиотеки можно командой:
pip install -r requirements.txt
Обратите внимание что мы будем использовать aiogram версии 3, который ещё находится в бета-тестировании, 3 версия НЕ совместима с предыдущими, так что не забывайте об этом.
Следующий шаг — установка PostgreSQL. Сама установка не является чем-то сложным, поэтому не будем её подробно рассматривать. Для более удобной работы с базами данных можете установить графический клиент, такой как pgAdmin (идущий в комплекте с PostgreSQL), DBeaver или Navicat, самый удобный и используемый мною каждый день в работе (имеет бесплатную пробную версию).
На этом настройка окружения завершена, можно приступать к созданию структуры бота.
Создание структуры
Наш бот будет разделён на несколько логических частей — файлов. Можно писать весь код в одном файле — он будет также работать, однако отладка и поиск нужной функции или класса станет сущим адом.
Файловая структура нашего бота:
main.py — точка входа, код запуска бота и инициализации всех остальных модулей
config.py — файл со всеми конфигурационными параметрами, такими как токен бота и данные подключения к БД. Хранение настроек в Python-файле является не самой лучшей практикой, однако если настройки меняются очень редко, то такой способ является самым простым. Можно также хранить настройки в переменных окружения или специальных файлах (ini, json) и через config.py лишь предоставлять абстракцию данных, однако в этом боте будет использован самый простой способ
db.py — функции подключения и работы с базой данных. Данный файл будет являться абстракцией базы данных от основного кода
text.py — все тексты, используемые ботом. В этом файле будут лежать все приветствия, сообщения об ошибках и другие текстовые данные для бота. Хранение текста в Python-файле также является не лучшей практикой, так как изменить тексты можно только через код, однако тексты меняются не так часто (чаще всего никогда), поэтому снова пойдём самым простым путём
kb.py — все клавиатуры, используемые ботов. В этом файле будут находиться абсолютно все клавиатуры, как статические, так и динамически генерируемые через функции
middlewares.py — название файла говорит само за себя. В этом файле будут лежать все используемые мидлвари (их будет всего две)
states.py — будет хранить вспомогательные классы для FSM (машины состояний), а также фабрики Callback Data для кнопок Inline клавиатур
utils.py — различные функции. В этом файле будут лежать функции для рассылки, генерации текста и изображений через API и другие
handlers.py — основной файл, в котором будет содержать почти весь код бота. Будет состоять из функций-обработчиков с декораторами (фильтрами)
admin.py — обработчики событий, клавиатуры, классы и весь остальной код админки бота. Опять же если придерживаться лучших практик, стоило бы вынести это в отдельную папку, в которой уже создать модули клавиатур, текстов, хэндлеров (обработчиков) и всего остального. Наша админка будет иметь базовый функционал, поэтому реализуем всё в одном файле
В итоге ваша папка должна выглядеть так:
Получение токена
На эту тему написано настолько много материала, что крайне не хочется дублировать его, поэтому дам краткую инструкцию по получению токена:
Создайте бота командой /newbot
Следуя указаниям бота введите все данные, типа названия
Скопируйте токен и вставьте его в переменную BOT_TOKEN в файле config.py
Можно также произвести настройку бота в BotFather, к примеру настроить описание, аватарку и другие параметры.
Пишем первый код!
Теперь, когда все подготовительные действия сделаны, можем приступить к написанию кода. Мы не будем писать эхо-бота, а сразу перейдём к чему-то более полезному — бот, отправляющий пользователю его ID.
В файле main.py пишем следующий код:
Сначала мы импортируем все нужные нам классы и модули:
asyncio — для асинхронного запуска бота
logging — для настройки логгирования, которое поможет в отладке
aiogram — основной модуль библиотеки aiogram, из которого мы импортируем классы Bot и Dispatcher
aiogram.enums.parse_mode — содержит настройки разметки сообщений (HTML, Markdown)
aiogram.fsm.storage.memory — хранилища данных для состояний пользователей
config — настройки бота, пока что только токен
handlers — пока пустой, но скоро мы напишем в нём функционал нашего бота
Затем мы объявляем функцию main() , в которой будет запускаться бот. Далее мы создаём объект бота с нашим токеном. Обратите внимание на параметр parse_mode , он отвечает за используемую по умолчанию разметку сообщений. Мы используем HTML, чтобы избежать проблем с экранированием символов. Затем мы создаём объект диспетчера, параметр storage=MemoryStorage() говорит о том, что все данные бота, которые мы не сохраняем в БД (к примеру состояния), будут стёрты при перезапуске. Этот вариант является оптимальным, так как хранение состояний диспетчера требуется редко.
Строка dp.include_router(router) подключает к нашему диспетчеру все обработчики, которые используют router, их вы увидите в следующем файле. Строка await bot.delete_webhook(drop_pending_updates=True) удаляет все обновления, которые произошли после последнего завершения работы бота. Это нужно, чтобы бот обрабатывал только те сообщения, которые пришли ему непосредственно во время его работы, а не за всё время. следующая строка запускает бота. Давайте запустим и проверим, как работает наш бот. После запуска вы должны увидеть следующий вывод в лог:
Это означает, что наш бот запущен и слушает обновления, однако пока что он ничего не делает, так как мы не добавили ни одного обработчика. Давайте исправим это, написав в файле handlers.py следующий код:
Сначала мы импортируем все необходимое из aiogram. После этого создаём роутер для дальнешей привязки к нему обработчиков. Затем мы объявили две функции-обработчика событий, а также назначили им фильтры. Рассмотрим их подробнее. Декоратор @router.message означает, что функция является обработчиком входящих сообщений. Command(«start») запускает обработчик только если входящее сообщение — команда /start . Далее мы объявляем саму функцию и в её теле отвечаем пользователю на сообщение текстом приветствия. Если мы имеем доступ к объекту сообщения, то всегда можем отправить в тот же чат любое сообщение методом msg.answer(«Text») , что является аналогом await bot.send_message(msg.chat.id, «Text») .
Второй обработчик реагирует на все сообщения, так как у него не задан ни один фильтр. В теле функции мы снова отвечаем пользователю сообщением и подставляем в него значение msg.chat.id . Запустим снова код и посмотрим на результат. Обратите внимание, что запускать надо не handlers.py, а main.py, так как именно он является точкой входа в нашу программу. В консоли снова появится аналогичное сообщение об успешном запуске бота, можно перейти в чат с ботом и отправить ему команду /start .
Мы должны получить следующие ответы от бота:
Если у вас получилось также, то поздравляю, вы настроили всё правильно и запустили минимально рабочего бота.
Заключение
В следующей части мы сделаем меню бота и подключим к боту API OpenAI. Так как это моя первая статья на Хабре, жду любой конструктивной критики в комментариях по оформлению, стилю изложения и разумеется коду.
UPD: Обновил код, удалил использование глобального объекта диспетчера, заменил на роутер. Спасибо более опытным коллегам за подсказку