django-telegram-app 0.1.1__tar.gz

django_telegram_app-0.1.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: "shifqu"

django_telegram_app-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: "CI Validation"
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  validate-code:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --editable .[dev]
+
+      - name: Lint
+        run: |
+          ruff check --fix django_telegram_app/ tests/
+          pylint django_telegram_app/ tests/
+          ruff format --check django_telegram_app/ tests/
+          pyright django_telegram_app/ tests/
+
+      - name: Tests with Coverage
+        run: |
+          coverage run -m runtests
+
+      - name: Coverage Report
+        run: |
+          coverage report --skip-covered --show-missing

django_telegram_app-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write  # REQUIRED for PyPI trusted publishing
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --editable .[dev]
+
+      - name: Build sdist & wheel
+        run: python -Im build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

django_telegram_app-0.1.1/.gitignore

@@ -0,0 +1,178 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+# .pdm.toml
+# .pdm-python
+# .pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.dockerenv
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+# Ruff
+.ruff_cache/
+
+# Mac
+.DS_Store

django_telegram_app-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shifqu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_telegram_app-0.1.1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: django-telegram-app
+Version: 0.1.1
+Summary: A Django app that integrates with Telegram to create bots.
+Author-email: Sonny Valkeneers <sonny@softllama.net>
+License-Expression: MIT
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=5.2
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: coverage>=7.11; extra == "dev"
+Requires-Dist: django-types>=0.22; extra == "dev"
+Requires-Dist: ruff>=0.14; extra == "dev"
+Requires-Dist: pylint<4.0; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: build>=1.3; extra == "dev"
+Dynamic: license-file
+
+# django-telegram-app
+A Django app to integrate Telegram bots into your project.
+
+Detailed documentation is in the [`docs/`](docs/) directory.
+
+---
+[![Code style: Ruff](https://img.shields.io/badge/style-ruff-8b5000)](https://github.com/astral-sh/ruff)
+[![Typing: Pyright](https://img.shields.io/badge/typing-pyright-725a42
+)](https://github.com/RobertCraigie/pyright-python)
+[![Linting: Pylint](https://img.shields.io/badge/typing-pylint-755147
+)](https://github.com/pylint-dev/pylint)
+[![Framework: Django](https://img.shields.io/badge/framework-django-727242)](https://docs.djangoproject.com/en/5.2/)
+[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://opensource.org/license/mit)
+[![CI Validation](https://github.com/shifqu/django-telegram-app/actions/workflows/ci.yml/badge.svg)](https://github.com/shifqu/django-telegram-app/actions/workflows/ci.yml)
+
+---
+
+## Features
+
+- ✅ Command-based bot architecture with step-based flow
+- ✅ Swappable `TelegramSettings` model
+- ✅ Inline admin integration for linking Telegram settings to users
+- ✅ Extensible: add commands per app via auto-discovery
+- ✅ Built-in system checks for misconfiguration
+- ✅ Django ORM integration (no direct API handling required)
+- ✅ Easy to test (includes custom TelegramTestCase)
+
+## Requirements (officially supported)
+
+- Python **3.10+**
+- Django **5.2+**
+
+## Quick start
+
+1. Install the package
+    ```bash
+    pip install django-telegram-app
+    ```
+
+1. Add "django_telegram_app" to your INSTALLED_APPS setting like this:
+    ```python
+    INSTALLED_APPS = [
+        ...,
+        "django_telegram_app",
+    ]
+    ```
+
+2. Include the telegram URLconf in your project urls.py like this:
+    ```python
+    ...
+    from django_telegram_app.conf import settings as telegram_app_settings
+    ...
+    path(telegram_app_settings.ROOT_URL, include("django_telegram_app.urls")),
+    ```
+
+3. Create your own commands in each app under `{appname}/telegrambot/commands/`. Refer to the documentation for more details on how to write custom commands.
+
+4. Add the provided telegramsettings inline to your user-model like this:
+    ```python
+    # user/admin.py
+    from django_telegram_app.admin import TelegramSettingInline
+    ...
+    class CustomUserAdmin(UserAdmin):
+        ...
+        inlines = [TelegramSettingInline]
+        # or add it to an existing entry
+    ```
+
+5. Configure the telegram settings. Refer to the documentation for all possible settings. 
+Minimal configuration is like this:
+    ```python
+    # project/settings.py
+    ...
+    TELEGRAM = {
+        "BOT_URL": "https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/"
+    }
+    ...
+    ```
+
+6. Run `python manage.py migrate` to create the models.
+
+7. Run `python manage.py setwebhook` to set the url on which you would like to receive telegram updates.
+
+8. Start the development server and visit the admin to edit users and add/complete TelegramSettings there.
+
+## License
+
+This project is licensed under the MIT License — see the [`LICENSE`](LICENSE) file for details.

django_telegram_app-0.1.1/README.md

@@ -0,0 +1,88 @@
+# django-telegram-app
+A Django app to integrate Telegram bots into your project.
+
+Detailed documentation is in the [`docs/`](docs/) directory.
+
+---
+[![Code style: Ruff](https://img.shields.io/badge/style-ruff-8b5000)](https://github.com/astral-sh/ruff)
+[![Typing: Pyright](https://img.shields.io/badge/typing-pyright-725a42
+)](https://github.com/RobertCraigie/pyright-python)
+[![Linting: Pylint](https://img.shields.io/badge/typing-pylint-755147
+)](https://github.com/pylint-dev/pylint)
+[![Framework: Django](https://img.shields.io/badge/framework-django-727242)](https://docs.djangoproject.com/en/5.2/)
+[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://opensource.org/license/mit)
+[![CI Validation](https://github.com/shifqu/django-telegram-app/actions/workflows/ci.yml/badge.svg)](https://github.com/shifqu/django-telegram-app/actions/workflows/ci.yml)
+
+---
+
+## Features
+
+- ✅ Command-based bot architecture with step-based flow
+- ✅ Swappable `TelegramSettings` model
+- ✅ Inline admin integration for linking Telegram settings to users
+- ✅ Extensible: add commands per app via auto-discovery
+- ✅ Built-in system checks for misconfiguration
+- ✅ Django ORM integration (no direct API handling required)
+- ✅ Easy to test (includes custom TelegramTestCase)
+
+## Requirements (officially supported)
+
+- Python **3.10+**
+- Django **5.2+**
+
+## Quick start
+
+1. Install the package
+    ```bash
+    pip install django-telegram-app
+    ```
+
+1. Add "django_telegram_app" to your INSTALLED_APPS setting like this:
+    ```python
+    INSTALLED_APPS = [
+        ...,
+        "django_telegram_app",
+    ]
+    ```
+
+2. Include the telegram URLconf in your project urls.py like this:
+    ```python
+    ...
+    from django_telegram_app.conf import settings as telegram_app_settings
+    ...
+    path(telegram_app_settings.ROOT_URL, include("django_telegram_app.urls")),
+    ```
+
+3. Create your own commands in each app under `{appname}/telegrambot/commands/`. Refer to the documentation for more details on how to write custom commands.
+
+4. Add the provided telegramsettings inline to your user-model like this:
+    ```python
+    # user/admin.py
+    from django_telegram_app.admin import TelegramSettingInline
+    ...
+    class CustomUserAdmin(UserAdmin):
+        ...
+        inlines = [TelegramSettingInline]
+        # or add it to an existing entry
+    ```
+
+5. Configure the telegram settings. Refer to the documentation for all possible settings. 
+Minimal configuration is like this:
+    ```python
+    # project/settings.py
+    ...
+    TELEGRAM = {
+        "BOT_URL": "https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/"
+    }
+    ...
+    ```
+
+6. Run `python manage.py migrate` to create the models.
+
+7. Run `python manage.py setwebhook` to set the url on which you would like to receive telegram updates.
+
+8. Start the development server and visit the admin to edit users and add/complete TelegramSettings there.
+
+## License
+
+This project is licensed under the MIT License — see the [`LICENSE`](LICENSE) file for details.

django_telegram_app-0.1.1/django_telegram_app/__init__.py

@@ -0,0 +1 @@
+"""Telegram app."""

django_telegram_app-0.1.1/django_telegram_app/admin.py

@@ -0,0 +1,52 @@
+"""Telegram admin."""
+
+from django.contrib import admin
+
+from django_telegram_app.models import CallbackData, Message
+from django_telegram_app.resolver import get_telegram_settings_model
+
+
+class TelegramSettingInline(admin.TabularInline):
+    """Represent a telegram setting inline in the admin."""
+
+    model = get_telegram_settings_model()
+
+
+class CallbackDataAdmin(admin.ModelAdmin):
+    """Represent the CallbackData admin."""
+
+    list_display = ("token", "data_truncated")
+
+    def has_add_permission(self, request):  # noqa: ARG002  # pylint: disable=unused-argument
+        """Do not allow to add callback_data."""
+        return False
+
+    def has_delete_permission(self, request, obj=None):  # noqa: ARG002  # pylint: disable=unused-argument
+        """Do not allow to delete callback_data."""
+        return False
+
+    def has_change_permission(self, request, obj=None):  # noqa: ARG002  # pylint: disable=unused-argument
+        """Do not allow to change callback_data."""
+        return False
+
+
+class MessageAdmin(admin.ModelAdmin):
+    """Represent the Message admin."""
+
+    list_display = ("update_id", "message_truncated", "error")
+
+    def has_add_permission(self, request):  # noqa: ARG002  # pylint: disable=unused-argument
+        """Do not allow to add messages."""
+        return False
+
+    def has_delete_permission(self, request, obj=None):  # noqa: ARG002  # pylint: disable=unused-argument
+        """Do not allow to delete messages."""
+        return False
+
+    def has_change_permission(self, request, obj=None):  # noqa: ARG002  # pylint: disable=unused-argument
+        """Do not allow to change messages."""
+        return False
+
+
+admin.site.register(CallbackData, CallbackDataAdmin)
+admin.site.register(Message, MessageAdmin)

django_telegram_app-0.1.1/django_telegram_app/apps.py

@@ -0,0 +1,15 @@
+"""Telegram app configuration."""
+
+from django.apps import AppConfig
+
+
+class TelegramConfig(AppConfig):
+    """Represent the telegram AppConfig."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_telegram_app"
+    label = "django_telegram_app"
+
+    def ready(self):
+        """Import checks."""
+        import django_telegram_app.checks  # noqa: F401

django_telegram_app-0.1.1/django_telegram_app/bot/__init__.py

@@ -0,0 +1,58 @@
+"""Bot module for the Telegram app."""
+
+from __future__ import annotations
+
+import functools
+import pkgutil
+from importlib import import_module
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from django.apps import apps
+from django.conf import settings
+
+if TYPE_CHECKING:
+    from django_telegram_app.bot.base import BaseCommand
+    from django_telegram_app.models import AbstractTelegramSettings
+
+
+def find_commands(telegrambot_dir: Path):
+    """Return a list of all the command names that are available for the provided telegrambot path."""
+    command_dir = telegrambot_dir / "commands"
+    return [name for _, name, is_pkg in pkgutil.iter_modules([command_dir]) if not is_pkg and not name.startswith("_")]
+
+
+def load_command_class(app_name: str, name: str, settings: AbstractTelegramSettings) -> BaseCommand:
+    """Return the Command class instance for the given command name and application name.
+
+    Allow all errors raised by the import process (ImportError, AttributeError) to propagate.
+    """
+    module = import_module(f"{app_name}.telegrambot.commands.{name}")
+    return module.Command(settings)
+
+
+@functools.cache
+def get_commands():
+    """Return a dictionary mapping command names to their callback applications.
+
+    Look for a telegrambot.commands package in each installed application -- if a commands package exists, register all
+    commands in that package.
+
+    All user-defined commands from the specified settings module are included.
+
+    The dictionary is in the format {command_name: app_name}. Key-value
+    pairs from this dictionary can then be used in calls to
+    load_command_class(app_name, command_name)
+
+    The dictionary is cached on the first call and reused on subsequent
+    calls.
+    """
+    commands: dict[str, str] = {}
+    if not settings.configured:
+        return commands
+
+    for app_config in apps.get_app_configs():
+        path = Path(app_config.path) / "telegrambot"
+        commands.update({name: app_config.name for name in find_commands(path)})
+
+    return commands