django-telegram-framework 5.7.0

Python Django package repository template

Django Telegram Framework

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

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

Примеры использования

---

Workflows

Package

Support

Downloads

Languages

Development

• 
• 
• 
• 

---

Menu

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

Идея проекта

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

• Имеет чёткую структуру модулей
• Может использовать разные библиотеки для взаимодействия с telegram (pyTelegramBotAPI, python-telegram-bot и другие)
• Позволяет быстро реализовать 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
• Использовать link по аналогии с urls в Django

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

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

Зависимости

• django > 5
• pyTelegramBotAPi (Нужно установить отдельно)
• Для python-telegram-bot==13.15 нужны дополнительно следующие зависимости:
  • python-telegram-bot==13.15
  • urllib3==1.26.15
  • standard-imghdr==3.13.0
• Подробности в Полной документации

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

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

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

Установка

with pip

pip install django-telegram-framework

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

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

0. Добавить telegram_framework в INSTALLED_APPS

INSTALLED_APPS = [
    '...',
    '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.create_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 pytest import fixture
from telegram_framework.test import asserts


@fixture
def bot_client():
    client = asserts.prepare_client()
    return client


@fixture
def chat(bot_client):  # pylint: disable=redefined-outer-name
    return asserts.prepare_chat(bot_client, 'quickstart.bot')


def test_start(bot_client, chat):
    """
    Test /start: success
    """
    # Бот должен реагировать на сообщения
    chat = asserts.assert_command_was_handled(
        '/start',
        chat,
        bot_client,
    )
    # Последнее сообщение в чате должно содержать приветствие
    asserts.assert_chat_last_message_text_equal(
        chat,
        'Приветствую тебя. Я Quickstart Telegram Bot'
    )


def test_any_text_message(bot_client, chat):
    """
    Test send any text message: success
    """
    # Бот должен реагировать на сообщение,
    chat = asserts.assert_text_message_was_handled(
        'quickstart message',
        chat,
        bot_client,
    )
    # Последнее сообщение должно содержать ответ бота
    asserts.assert_chat_last_message_text_equal(
        chat,
        'Тебе отвечает Bot'
    )

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

pytest

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

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

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