Skip to content

Latest commit

 

History

History
316 lines (237 loc) · 15.8 KB

README.md

File metadata and controls

316 lines (237 loc) · 15.8 KB

Django Telegram Framework

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

Django Telegram Framework logo

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

Workflows

Tests Pylint

Package

Version Development Status Python version License Wheel

Support

Documentation Discussions Issues

Downloads

Day Downloads Week Downloads Month Downloads All Downloads

Languages

Languages Top Language

Development

  • Release date Last Commit
  • Issues Closed Issues
  • Pull Requests Closed Pull Requests
  • Discussions

Menu

Идея проекта

Создать удобный и надежный 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 (На этапе планирования)

Зависимости

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

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

Установка

with pip

pip install django-telegram-framework

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

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

  1. Создать django проект
  2. Создать django приложение
python manage.py startapp quickstart
  1. В приложении создать файл bot.py
  2. Пример кода в файле 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),
]
  1. В settings.py проекта добавить следующие настройки:
TELEGRAM_BOT_TOKEN = '7777777777:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
TELEGRAM_BOT_TYPE = 'pyTelegramBotAPI'
ROOT_BOT_LINKS = 'quickstart.bot'
  1. Установить pyTelegramBotAPI
pip install pyTelegramBotAPI
  1. Запустить Бота
python manage.py run_bot

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

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

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

  1. В settings.py проекта внесите следующие изменения:
TELEGRAM_BOT_TOKEN = '0'
TELEGRAM_BOT_TYPE = 'Dummy'
  1. Пример написания тестов для бота из 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)
  1. Запустить django тесты
python manage.py test

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

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