Skip to main content

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, 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 версия библиотеки с основным набором функций

Установка

with pip

pip install django-telegram-framework

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

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

  1. Добавить telegram_framework в INSTALLED_APPS
INSTALLED_APPS = [
    '...',
    '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.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),
]
  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 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'
    )
  1. Запустить тесты
pytest

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

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

Metadata

Release files for django-telegram-framework 6.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-telegram-framework 6.0.1
File Size Uploaded Provenance Actions
django_telegram_framework-6.0.1.tar.gz 31.7 kB Without provenance Details for django_telegram_framework-6.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-telegram-framework 6.0.1
File Interpreter ABI Platform Actions
django_telegram_framework-6.0.1-py3-none-any.whl Python 3 none any Details for django_telegram_framework-6.0.1-py3-none-any.whl

Total release size: 91.0 kB

Release files / django_telegram_framework-6.0.1.tar.gz

Download URL django_telegram_framework-6.0.1.tar.gz
Size 31.7 kB
Tags Source
SHA-256 checksum
How to use checksums
def691c8aee3247424abdf10e69e9824308d383f191512e772afcc1a73fcc6b4
BLAKE2b-256 checksum
How to use checksums
b7d564f4a4313f82b9b7d2b82c288c06138285c5e410a9ebf8e70a3e43d4eb56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / django_telegram_framework-6.0.1-py3-none-any.whl

Download URL django_telegram_framework-6.0.1-py3-none-any.whl
Size 59.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
752478201039d08a6697050ac18e096d23f162c7c061c87510086440eb8a6a08
BLAKE2b-256 checksum
How to use checksums
911e9656fd8369298d5f5e877a09d81729f2d31c08f7afa5abd3ddc09818ec83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for django-telegram-framework 6.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

6.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page