Python telegram api tutorial

За границей Hello World: полный гайд по разработке Telegram ботов с помощью Python и Aiogram 3. Часть 1

Захотев однажды научиться разрабатывать ботов для Telegram на языке программирования Python, я просто зашёл в Яндекс и вбил что-то вроде «telegram бот на python для новичков» и нашёл казалось бы огромное множество гайдов и туториалов. Однако копнув немного глубже стало понятно, что большая часть гайдов заканчивается на прикреплении клавиатур к сообщениям, или ещё хуже, на написании эхо-бота.

Пришлось копаться в документации, шерстить форумы и учиться на примерах кода с GitHub. Этот гайд создан как полное руководство по разработке полноценного Telegram бота для работы с нейросетями, такими как ChatGPT и Dall-e, начиная установкой IDE и получением токена и заканчивая подключением оплаты, базы данных и загрузки бота на сервер.

Я считаю что гайд будет полезен прежде всего тем, кто уже пробовал разобраться в теме и имеет базовые знания. Чтобы гайд был полезным необходимо иметь базовые знания в Python, всё остальное вы можете изучить в процессе. Продвинутым разработчикам ботов большая часть будет знакома и вряд ли принесёт пользу, однако есть шанс, что и вы найдёте для себя что-то полезное. Жду любую конструктивную критику как по коду и его стилю, так и по изложению.

Что мы получим в итоге?

В конце гайда у нас получится полностью функционирующий бот, с админкой, оплатой, базой данных, реферальной программой и подключенным API OpenAI. По мере выхода статей код будет появляться в репозитории на GitHub.

Используемые технологии

Будут использованы следующие технологии:

• VS Code (или любой другой удобный редактор или IDE)
• Python
• Aiogram 3
• PostgreSQL
• API OpenAI

Подготовка окружения

Разработка любой программы начинается с подготовки среды, так что приступим. Для начала устанавливаем 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 — обработчики событий, клавиатуры, классы и весь остальной код админки бота. Опять же если придерживаться лучших практик, стоило бы вынести это в отдельную папку, в которой уже создать модули клавиатур, текстов, хэндлеров (обработчиков) и всего остального. Наша админка будет иметь базовый функционал, поэтому реализуем всё в одном файле

В итоге ваша папка должна выглядеть так:

Получение токена

На эту тему написано настолько много материала, что крайне не хочется дублировать его, поэтому дам краткую инструкцию по получению токена:

1. Запустите бота BotFather
2. Создайте бота командой /newbot
3. Следуя указаниям бота введите все данные, типа названия
4. Скопируйте токен и вставьте его в переменную BOT_TOKEN в файле config.py

Можно также произвести настройку бота в BotFather, к примеру настроить описание, аватарку и другие параметры.

Пишем первый код!

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

В файле main.py пишем следующий код:

import asyncio import logging from aiogram import Bot, Dispatcher from aiogram.enums.parse_mode import ParseMode from aiogram.fsm.storage.memory import MemoryStorage import config from handlers import router async def main(): bot = Bot(token=config.BOT_TOKEN, parse_mode=ParseMode.HTML) dp = Dispatcher(storage=MemoryStorage()) dp.include_router(router) await bot.delete_webhook(drop_pending_updates=True) await dp.start_polling(bot, allowed_updates=dp.resolve_used_update_types()) if __name__ == "__main__": logging.basicConfig(level=logging.INFO) asyncio.run(main())

Сначала мы импортируем все нужные нам классы и модули:

• 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 следующий код:

from aiogram import types, F, Router from aiogram.types import Message from aiogram.filters import Command router = Router() @router.message(Command("start")) async def start_handler(msg: Message): await msg.answer("Привет! Я помогу тебе узнать твой ID, просто отправь мне любое сообщение") @router.message() async def message_handler(msg: Message): await msg.answer(f"Твой ID: ")

Сначала мы импортируем все необходимое из 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: Обновил код, удалил использование глобального объекта диспетчера, заменил на роутер. Спасибо более опытным коллегам за подсказку

Источник