Django Telegram Framework

Библиотека (Framework) для быстрого создания Telegram ботов и интеграции с django

Тут можно найти Полную документацию проекта

---

Workflows

Package

Support

Downloads

Languages

Development

• 
• 
• 
• 

---

Menu

• Идея проекта
• Проект с открытым исходным кодом
• Отличие от других Telegram проектов
• Функции библиотеки
• Зависимости
• Статус разработки
• Установка
• Быстрый старт
• Тестирование
• Внести свой вклад в проект

Идея проекта

Создать удобный и надежный framework для быстрого и удобного создания telegram ботов который:

• Имеет чёткую структуру модулей
• Может использовать разные библиотеки для взаимодействия с telegram (pyTelegramBotAPI, Telethone, python-telegram-bot, aiogram и другие)
• Позволяет быстро реализовать start-up проект одному разработчику или в небольшой команде
• Имеет интеграцию с django для соднаия web страниц и использования django admin
• Быстро подключается к базе данных с помощью Django ORM

Проект с открытым исходным кодом

Это проект с открытым исходным кодом с лицензией Happy Code.

• Свободное использование
• создание Forks
• публикация issues и bugs
• contributions

очень приветствуются

Отличие от других Telegram проектов

В отличие от библиотек для создания telegram ботов, таких как pyTelegramBotAPI, aiogram, python-telegram-bot и других, этот проект (Framework) имеет чёткую структуру, похожую на структуру django проектов. Framework содержит следующие элементы:

• models - модели данных связанные с базой данных с помощью Django ORM
• actions - обработчики событий telegram bot-а (аналогия с django views)
• links - связь команд и событий бота с обработчиками (аналогия с django urls)
• settings - настройки для всего проекта - django settings
• tests - тесты логики бота с использованием специального Dummy Bot

Под капотом Framework может использовать разные библиотеки в синхронном и асинхронном исполнении. Можно переключать одни библиотеки на другие. Без соединения с telegram (например в DEV) режиме, можно использовать Dummy Bot для разработки и тестирования.

Интеграция с django позволяет:

• Добавить web site
• Использовать django админку
• Использовать django ORM

Функции библиотеки

• Интеграция telegram бота в django проект
• Понятная структура и интерфейсы для разработки бота
• Функции автоматического тестирования бота
• Совместимость с синхронным pyTelegramBotAPI
• Совместимость с асинхронным pyTelegramBotAPI (В разработке)
• DummyBot для тестирования и работы без подключения к telegram
• Функции телеграм бота (Будут добавляться по мере надобности, пожалуйста напишите, если вам нужна новая функция)
• Совместимость с aiogram, python-telegram-bot, Telethone (На этапе планирования)

Зависимости

• django > 5
• pyTelegramBotAPi (Нужно установить отдельно)
• Подробности в Полной документации

Статус разработки

Написана и проверена 1-ая сырая версия библиотеки с небольшим набором функций

• Пакет уже доступен в PyPi
• Подробности в Полной документации

Установка

with pip

pip install django-telegram-framework

Подробности в Полной документации

Быстрый старт

1. Создать django проект
2. Создать django приложение

python manage.py startapp quickstart

3. В приложении создать файл bot.py
4. Пример кода в файле bot.py

from telegram_framework import (
    messages,
    actions,
    links,
)
# ОПИШИТЕ ОБРАБОТЧИКИ СОБЫТИЙ БОТА

def send_greetings(bot, message):
    # Используйте специальный тип для сообщений
    greetings_message = messages.Message('Приветствую тебя. Я Quickstart Telegram Bot', sender=bot)
    # Отправьте сообщение в телеграмм
    return actions.send_message(message.chat, greetings_message)

def reply_to_message(bot, message):
    # Используйте специальную функцию для создания ответа
    reply = messages.create_reply(message, 'Тебе отвечает Bot', sender=bot)
    # Отправьте ответ в телеграмм
    return actions.send_reply(reply)


# СВЯЖИТЕ ОБРАБОТЧИКИ С ДЕЙСТВИЯМИ ПОЛЬЗОВАТЕЛЯ В TELEGRAM

bot_links = [
    links.on_command(send_greetings, 'start'),
    links.on_command(send_greetings, 'help'),
    links.on_message(reply_to_message),
]

5. В settings.py проекта добавить следующие настройки:

TELEGRAM_BOT_TOKEN = '7777777777:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
TELEGRAM_BOT_TYPE = 'pyTelegramBotAPI'
ROOT_BOT_LINKS = 'quickstart.bot'

6. Установить pyTelegramBotAPI

pip install pyTelegramBotAPI

7. Запустить Бота

python manage.py run_bot

Больше примеров в Полной документации

Тестирование

Django Telegram Framework позволяет удобно тестировать код бота без подключения к telegram. Для этого используется специальный DummyBot

1. В settings.py проекта внесите следующие изменения:

TELEGRAM_BOT_TOKEN = '0'
TELEGRAM_BOT_TYPE = 'Dummy'

2. Пример написания тестов для бота из quickstart приложения

from django.test import SimpleTestCase
from telegram_framework import bots, actions, messages, chats, links
from quickstart.bot import bot_links


class TestCommands(SimpleTestCase):

    def setUp(self):
        # Создайте чат для тестовых сообщений
        chat = chats.Chat()
        # Создайте тестового пользователя
        self.client = bots.get_bot('client')
        # Добавьте его в чат
        chat = chats.add_bot(chat, self.client)
        # Создайте пользователя - бота
        bot = bots.get_bot('bot')
        # Свяжите бота с его обработчиками
        bot = links.add_links(bot, bot_links)
        # Добавьте его в чат
        self.chat = chats.add_bot(chat, bot)
        # В чате пока нет сообщений
        self.assertEqual(0, len(self.chat.messages))

    def test_start(self):
        """
        Test /start: success
        """
        command_text = '/start'
        # Для создания сообщения используйте специальный тип
        # Его будет отправлять клиент sender=self.client
        message = messages.Message(command_text, sender=self.client)
        # Отправьте его в чат
        chat = actions.send_message(self.chat, message)
        # Бот должен реагировать на сообщения
        # Поэтому в чате будет 2 сообщения
        self.assertEqual(2, len(chat.messages))
        # Получите последнее сообщение для проверки
        last_message = chats.get_last_message(chat)
        expected_text = 'Приветствую тебя. Я Quickstart Telegram Bot'
        # Оно должно содержать приветствие
        self.assertEqual(expected_text, last_message.text)


    def test_any_text_message(self):
        """
        Test send any text message: success
        """
        # Используйте специальный тип для создания сообщения
        # Его отправит client (sender=self.client)
        message = messages.Message('quickstart message', sender=self.client)
        # Отправляем сообщение
        chat = actions.send_message(self.chat, message)
        # Бот должен реагировать на сообщение,
        # Поэтому в чате будет 2 сообщения
        self.assertEqual(2, len(chat.messages))
        # Получаем последнее сообщение
        last_message = chats.get_last_message(chat)
        expected_text = 'Тебе отвечает Bot'
        # Оно должно содержать ответ бота
        self.assertEqual(expected_text, last_message.text)

3. Запустить django тесты

python manage.py test

Внести свой вклад в проект

Без проблем! Для быстрого старта можно ознакомиться с:

• Полной документацией
• Как внести свой вклад
• Документацией для разработчиков
• Нормами поведения
• Политикой безопасности
• Структурой управления проектом
• Файлом поддержки