django-aiogram 4.0.0.dev0__py3-none-any.whl

django_aiogram/__init__.py

@@ -0,0 +1,64 @@
+"""Run aiogram next to Django and send Telegram messages through a Redis queue.
+
+Importing this package is cheap on purpose: aiogram (and the pydantic stack
+underneath it) costs most of a second, and a migration container or a test run
+should not pay that for a bot it never talks to. Every export resolves on first
+attribute access instead (PEP 562).
+"""
+
+from __future__ import annotations
+
+#: not imported from ``typing``: with annotations postponed nothing here needs that
+#: module at runtime, and it was over half of what importing this package cost. Type
+#: checkers understand the sentinel, and a reader can see it is always false
+TYPE_CHECKING = False
+
+__version__ = '4.0.0.dev0'
+
+__all__ = ('TelegramBot', '__version__', 'bot', 'conf', 'get_redis', 'redis_conn')
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from django_aiogram.config.settings import conf as conf
+    from django_aiogram.producer.client import TelegramBot as TelegramBot
+    from django_aiogram.redis import get_redis as get_redis
+    from django_aiogram.redis import redis_conn as redis_conn
+
+    bot: TelegramBot
+
+#: which module each lazy export lives in
+_EXPORTS = {
+    'TelegramBot': 'django_aiogram.producer.client',
+    'get_redis': 'django_aiogram.redis',
+    'redis_conn': 'django_aiogram.redis',
+    'conf': 'django_aiogram.config.settings',
+}
+
+
+def __getattr__(name: str) -> Any:  # noqa: ANN401 - a module attribute is whatever the module exports
+    """Resolve an export on first access, then cache it on the module."""
+    if name == 'bot':
+        # `_singleton`'s module body builds the one instance, and Python's import
+        # lock is what makes two threads racing here share it. That is why this
+        # package holds no lock of its own: an explicit one would need `threading`
+        # imported at module scope, which is most of what importing this used to cost
+        from django_aiogram._singleton import (  # noqa: PLC0415 - the point: pay for aiogram on use, not import
+            bot,
+        )
+
+        globals()['bot'] = bot
+        return bot
+    if name in _EXPORTS:
+        from importlib import import_module  # noqa: PLC0415 - as above
+
+        value = getattr(import_module(_EXPORTS[name]), name)
+        globals()[name] = value
+        return value
+    msg = f'module {__name__!r} has no attribute {name!r}'
+    raise AttributeError(msg)
+
+
+def __dir__() -> list[str]:
+    """List the lazy exports alongside whatever is already materialised."""
+    return sorted(set(globals()) | set(__all__))

django_aiogram/_singleton.py

@@ -0,0 +1,22 @@
+"""The one shared :class:`~django_aiogram.producer.client.TelegramBot` for this process.
+
+A module body, not a lock. Python guarantees a module executes once per process and
+makes concurrent importers wait on that module's own import lock, so two threads
+reaching for ``django_aiogram.bot`` at the same moment get the same instance
+without this package holding a lock of its own — and without ``__init__`` importing
+``threading`` to build one, which is most of what importing the package used to cost
+outside Django.
+
+Why it matters that they get the same one: each instance builds its own event loop and
+its own HTTP session, and ``loop_lock`` serializes access to *a* loop. Two bots means
+two loops, and the lock that exists to keep ``run_until_complete`` from being reentered
+would be guarding one of them while the other was entered.
+
+Importing this module is what pays for aiogram, so nothing imports it at module
+scope: :func:`django_aiogram.__getattr__` reaches it on the first access to
+``bot`` and never again.
+"""
+
+from django_aiogram.producer.client import TelegramBot
+
+bot = TelegramBot()

django_aiogram/admin.py

@@ -0,0 +1,380 @@
+"""A read-only view of the event feed, sized for a table nobody wants to count.
+
+Nothing here reads a setting and nothing registers itself: ``admin.autodiscover``
+imports this module while the app registry is still loading, and reading
+settings at import time is the defect 2.0 existed to remove. Registration
+happens in :meth:`~django_aiogram.apps.TelegramBotAppConfig.ready`, where
+settings are already safe to read.
+"""
+
+import json
+import uuid
+from typing import TYPE_CHECKING, Any, cast
+
+from django.contrib import admin, messages
+from django.contrib.admin.views.main import ORDER_VAR
+from django.core.exceptions import ImproperlyConfigured, ValidationError
+from django.core.paginator import Paginator
+from django.db.models import Field, QuerySet
+from django.http import HttpRequest
+from django.utils.functional import cached_property
+from django.utils.html import format_html, format_html_join
+
+from django_aiogram.config.settings import SETTINGS_NAME, coerce_bool, conf
+from django_aiogram.eventlog.events import failure_kinds, kind_choices
+from django_aiogram.eventlog.writer import log_alias
+from django_aiogram.models import TelegramEvent
+
+#: fetched only on the page that renders them; see TelegramEventAdmin.get_queryset
+PAYLOAD_COLUMNS = ('error', 'detail')
+
+if TYPE_CHECKING:
+    # django-stubs parameterises these; at runtime neither is subscriptable
+    ModelAdminBase = admin.ModelAdmin[TelegramEvent]
+    AnyModelAdmin = admin.ModelAdmin[Any]
+else:
+    ModelAdminBase = admin.ModelAdmin
+    AnyModelAdmin = admin.ModelAdmin
+
+#: how many stages of one message the detail page will render
+MAX_STAGES = 200
+#: rows the changelist will count before it stops asking
+COUNT_LIMIT = 10_000
+
+
+def log_is_on() -> bool:
+    """Report whether the feed is recorded, read per request so a test can override it."""
+    try:
+        return coerce_bool(conf['EVENT_LOG'], f"{SETTINGS_NAME}['EVENT_LOG']")
+    except ImproperlyConfigured:
+        # a misconfigured flag is E031's finding; the admin's answer is to hide
+        return False
+
+
+def may_see_payloads(request: HttpRequest) -> bool:
+    """Whether this user may read message bodies and exception text.
+
+    Split from plain view access on purpose: support needs to see that a message
+    went out and when, without reading what it said.
+    """
+    checker = getattr(request.user, 'has_perm', None)
+    return bool(checker and checker('django_aiogram.view_telegramevent_payload'))
+
+
+class KindFilter(admin.SimpleListFilter):
+    """Filters by kind, from the registry rather than from the table.
+
+    A plain ``list_filter`` on the column would build its dropdown with
+    ``SELECT DISTINCT``, which is a full scan every time the changelist loads.
+    """
+
+    title = 'kind'
+    parameter_name = 'kind'
+
+    def lookups(self, _request: HttpRequest, _model_admin: AnyModelAdmin) -> list[tuple[str, str]]:
+        """Every registered kind, in the order they were registered."""
+        return kind_choices()
+
+    def queryset(self, _request: HttpRequest, queryset: QuerySet[TelegramEvent]) -> QuerySet[TelegramEvent]:
+        """Narrow to the chosen kind, which leads the index it uses."""
+        value = self.value()
+        return queryset.filter(kind=value) if value else queryset
+
+
+class OutcomeFilter(admin.SimpleListFilter):
+    """Everything that went wrong, as one question."""
+
+    title = 'outcome'
+    parameter_name = 'outcome'
+
+    def lookups(self, _request: HttpRequest, _model_admin: AnyModelAdmin) -> list[tuple[str, str]]:
+        """Two answers: the failure kinds, or everything else."""
+        return [('failed', 'Something went wrong'), ('ok', 'Went fine')]
+
+    def queryset(self, _request: HttpRequest, queryset: QuerySet[TelegramEvent]) -> QuerySet[TelegramEvent]:
+        """Narrow to the outcome chosen, as an IN list on the kind index."""
+        failures = failure_kinds()
+        if self.value() == 'failed':
+            return queryset.filter(kind__in=failures)
+        if self.value() == 'ok':
+            return queryset.exclude(kind__in=failures)
+        return queryset
+
+
+class BoundedPaginator(Paginator):  # type: ignore[type-arg]
+    """Counts, but never past ``COUNT_LIMIT`` rows.
+
+    Django's changelist runs ``COUNT(*)`` over the filtered queryset to build
+    the page list. On a table sized by traffic that is a sequential scan on
+    every page load, and the number it produces is stale by the time it renders.
+
+    Counting inside a ``LIMIT`` keeps the answer honest for the filtered views
+    people actually read, and turns the unfiltered one into a bounded index
+    scan rather than the whole table. Past the limit the count stops growing,
+    so the deepest pages are unreachable — by then the answer is a filter, not
+    another page.
+    """
+
+    #: whether the count stopped at the cap, so the page can say it did
+    truncated = False
+
+    @cached_property
+    def count(self) -> int:
+        """Count what fits inside the cap, in one query the index can serve."""
+        # the changelist always paginates a queryset; the base class is typed
+        # for anything sliceable, which has no count()
+        rows = cast('QuerySet[TelegramEvent]', self.object_list)
+        # unordered on purpose. Which rows the cap admits does not change how many
+        # there are, and the ordering is what stopped the index serving this: an `IN`
+        # over the failure kinds cannot yield a global `id DESC` from `(kind, -id)`, so
+        # the database sorted every match before the LIMIT could bite — the same defect
+        # the index was added to remove, surviving in the filter that needs it most
+        rows = rows.order_by()
+        # one row past the cap, so the difference between "exactly ten thousand"
+        # and "more than we will count" is knowable rather than assumed
+        found = int(rows[: COUNT_LIMIT + 1].count())
+        self.truncated = found > COUNT_LIMIT
+        return min(found, COUNT_LIMIT)
+
+
+class TelegramEventAdmin(ModelAdminBase):
+    """Read-only, and deliberately narrow about what it will ask the database."""
+
+    list_display = ('created_at', 'kind', 'function', 'chat_id', 'thread', 'worker', 'error_code')
+    list_filter = (KindFilter, OutcomeFilter)
+    # what makes the box appear; the lookup itself is get_search_results below
+    search_fields = ('correlation_id', 'chat_id')
+    search_help_text = 'An exact correlation id, or an exact chat id.'
+    show_full_result_count = False
+    paginator = BoundedPaginator
+    list_per_page = 50
+    # nothing to join: the model holds no foreign key, which is what keeps an
+    # insert from becoming a constraint check
+    list_select_related = False
+    ordering = ('-id',)
+    # only the columns an index can serve: function, worker and error_code have
+    # none, and one click on those headers sorts a table sized by traffic
+    sortable_by = ('created_at', 'kind', 'chat_id')
+    # no date_hierarchy: its drilldown truncates created_at for every row, which
+    # is a full scan no index can serve
+
+    def get_queryset(self, request: HttpRequest) -> QuerySet[TelegramEvent]:
+        """Read from the alias the writer writes to, router installed or not.
+
+        The two wide columns are left behind. Between them they are most of what a
+        row weighs — about 1.4 MB per fifty-row page under ``EVENT_LOG_PAYLOAD:
+        'full'`` with long tracebacks, and much less on the default ``'summary'``
+        with its 8 KiB cap — and the changelist renders neither, so they were
+        fetched to be discarded, including for a user `get_fields` withholds them
+        from. :meth:`get_object` asks for them
+        back on the one page that shows them.
+        """
+        return super().get_queryset(request).using(log_alias()).defer(*PAYLOAD_COLUMNS)
+
+    def get_object(
+        self,
+        request: HttpRequest,
+        object_id: str,
+        from_field: str | None = None,
+    ) -> TelegramEvent | None:
+        """Fetch one row with its payload columns, since this page renders them.
+
+        Django routes the detail page through `get_queryset` too, so without this
+        every deferred column would cost its own extra query when the template
+        touched it. Written out rather than delegated because the deferral has to
+        be lifted *before* the lookup, not after it.
+
+        Only for a reader allowed to see them. `get_fields` already keeps message
+        bodies and exception text off the page, but fetching them anyway would put
+        both on the wire and into the query log for someone the permission exists
+        to withhold them from.
+        """
+        rows = self.get_queryset(request)
+        if may_see_payloads(request):
+            rows = rows.defer(None)
+        meta = TelegramEvent._meta  # noqa: SLF001 - how Django itself asks a model for its fields
+        field = meta.pk if from_field is None else meta.get_field(from_field)
+        if not isinstance(field, Field):
+            # this model holds no relations, so nothing else can turn up here
+            return None
+        try:
+            return rows.get(**{field.name: field.to_python(object_id)})
+        except (TelegramEvent.DoesNotExist, ValidationError, ValueError):
+            return None
+
+    def changelist_view(self, request: HttpRequest, extra_context: dict[str, Any] | None = None) -> Any:  # noqa: ANN401 - Django types this as a bare response
+        """Render the list, saying so when the count stopped at the cap.
+
+        A page that reports exactly ten thousand results reads as the whole
+        answer. Silently, it would be the same defect the paginator exists to
+        avoid, moved one step along.
+
+        It also drops an ``?o=`` naming a column no index can serve. ``sortable_by``
+        decides whether a header is rendered as a *link* and nothing else — Django reads
+        it in one place, the template tag, while ``ChangeList`` maps ``?o=`` straight onto
+        ``list_display``. So a bookmark, a shared link or a query string kept from before
+        this restriction still ordered the whole table by ``function``, ``worker`` or
+        ``error_code``: on 200 000 rows a sequential scan and a sort for the page. Not for
+        the count — :class:`BoundedPaginator` drops the ordering, for the reason given
+        there — so this is the page query alone, once per view. Filtered rather than
+        refused, because an operator following an old link wants the page; the ordering
+        falls back to the default, which the index serves.
+        """
+        self._drop_unsortable_ordering(request)
+        response = super().changelist_view(request, extra_context)
+        changelist = getattr(response, 'context_data', {}).get('cl')
+        paginator = getattr(changelist, 'paginator', None)
+        if paginator is not None and paginator.count and getattr(paginator, 'truncated', False):
+            self.message_user(
+                request,
+                f'More than {COUNT_LIMIT:,} events match. Narrow the filter or search for an '
+                f'exact id; counting further would scan the table.',
+                messages.WARNING,
+            )
+        return response
+
+    def _drop_unsortable_ordering(self, request: HttpRequest) -> None:
+        """Keep only the ``?o=`` terms whose column is in :attr:`sortable_by`."""
+        requested = request.GET.get(ORDER_VAR)
+        if not requested:
+            return
+        allowed = {str(index) for index, field in enumerate(self.list_display) if field in self.sortable_by}
+        terms = requested.split('.')
+        kept = [term for term in terms if term.lstrip('-') in allowed]
+        if len(kept) == len(terms):
+            return
+        params = request.GET.copy()
+        if kept:
+            params[ORDER_VAR] = '.'.join(kept)
+        else:
+            del params[ORDER_VAR]
+        # django-stubs types `request.GET` immutable, which it is by convention rather
+        # than by construction; rewriting it before `super()` reads the params is what
+        # Django's own admin does, and the alternative — a ChangeList subclass — puts the
+        # rule further from the reason for it
+        request.GET = params  # type: ignore[assignment]
+
+    def get_fields(self, request: HttpRequest, _obj: TelegramEvent | None = None) -> list[Any]:
+        """Hide the two columns that can hold a message body or a stack trace."""
+        fields = [
+            'created_at',
+            'correlation_id',
+            'kind',
+            'function',
+            'chat_id',
+            'user_id',
+            'message_id',
+            'update_id',
+            'worker',
+            'attempt',
+            'duration_ms',
+            'error_code',
+            'stages',
+        ]
+        if may_see_payloads(request):
+            fields[-1:-1] = ['pretty_detail', 'error']
+        return fields
+
+    def get_readonly_fields(self, request: HttpRequest, obj: TelegramEvent | None = None) -> list[Any]:
+        """Everything: the feed records what happened, and that is not editable."""
+        return self.get_fields(request, obj)
+
+    def get_search_results(
+        self,
+        _request: HttpRequest,
+        queryset: QuerySet[TelegramEvent],
+        search_term: str,
+    ) -> tuple[QuerySet[TelegramEvent], bool]:
+        """Match the two typed columns exactly, each on its own index.
+
+        Django's own search cannot: even the `=` prefix builds `iexact`, which
+        renders as `UPPER(correlation_id::text) = ...` — a function on the
+        column, so no index applies and the search becomes a sequential scan of
+        a table sized by traffic. Typed equality is what the indexes are for.
+
+        The cost of typed equality is that a term the column cannot hold raises
+        while the query is built, which is why anything neither column can hold
+        is answered with nothing rather than handed to the database.
+        """
+        term = search_term.strip()
+        if not term:
+            return queryset, False
+        if term.lstrip('-').isdigit():
+            number = int(term)
+            # a chat_id is a BIGINT; a longer number is not one, and asking
+            # would be an error from the backend rather than an empty page
+            if -(2**63) <= number < 2**63:
+                return queryset.filter(chat_id=number), False
+            return queryset.none(), False
+        try:
+            identifier = uuid.UUID(term)
+        except ValueError:
+            return queryset.none(), False
+        return queryset.filter(correlation_id=identifier), False
+
+    @admin.display(description='detail')
+    def pretty_detail(self, obj: TelegramEvent) -> str:
+        """Render the JSON readably, and escaped.
+
+        format_html escapes; mark_safe here would be stored XSS, because a
+        detail holds whatever came off the wire.
+        """
+        return format_html('<pre>{}</pre>', json.dumps(obj.detail, indent=2, ensure_ascii=False, default=str))
+
+    @admin.display(description='every stage of this message')
+    def stages(self, obj: TelegramEvent) -> str:
+        """Render the whole correlated chain, in order, from one indexed query.
+
+        Bounded on purpose: a message that retried ten thousand times is a bug,
+        and rendering all of it would make this page a second one. One row more
+        than the cap is read so the page can say it stopped rather than end at
+        a number that looks like the whole story.
+        """
+        rows = list(
+            TelegramEvent.objects.using(log_alias())
+            .filter(correlation_id=obj.correlation_id)
+            .order_by('id')
+            .values_list('created_at', 'kind', 'worker')[: MAX_STAGES + 1]
+        )
+        body = format_html_join('', '<tr><td>{}</td><td>{}</td><td>{}</td></tr>', rows[:MAX_STAGES])
+        if len(rows) > MAX_STAGES:
+            body += format_html(
+                '<tr><td colspan="3">and more — only the first {} stages are shown</td></tr>',
+                MAX_STAGES,
+            )
+        return format_html('<table>{}</table>', body)
+
+    @admin.display(description='thread', ordering='correlation_id')
+    def thread(self, obj: TelegramEvent) -> str:
+        """Link a row to the rest of its message, through the exact search."""
+        return format_html('<a href="?q={}">{}</a>', obj.correlation_id, str(obj.correlation_id)[:8])
+
+    def has_add_permission(self, _request: HttpRequest) -> bool:
+        """Refuse: the feed is append-only, and only this package appends."""
+        return False
+
+    def has_change_permission(self, _request: HttpRequest, _obj: TelegramEvent | None = None) -> bool:
+        """Refuse: a record of what happened is not something to edit."""
+        return False
+
+    def has_delete_permission(self, _request: HttpRequest, _obj: TelegramEvent | None = None) -> bool:
+        """Refuse: a table this size is pruned in ranges, not a row at a time.
+
+        `manage.py tgbot_prune_events` is what does it.
+        """
+        return False
+
+    def has_view_permission(self, request: HttpRequest, obj: TelegramEvent | None = None) -> bool:
+        """Read the flag per request, so override_settings works in a test."""
+        return log_is_on() and bool(super().has_view_permission(request, obj))
+
+    def has_module_permission(self, request: HttpRequest) -> bool:
+        """Keep the app off the admin index entirely while the log is off."""
+        return log_is_on() and bool(super().has_module_permission(request))
+
+
+def register_event_log_admin(site: admin.AdminSite | None = None) -> None:
+    """Register the read-only admin. Called from ready(), behind the flag."""
+    target = site or admin.site
+    if not target.is_registered(TelegramEvent):
+        target.register(TelegramEvent, TelegramEventAdmin)

django_aiogram/api.py

@@ -0,0 +1,38 @@
+"""Which method names a queued payload is allowed to name.
+
+A payload carries the name of the method to call, so without this list the queue
+could reach anything public on ``Bot``: ``download_file`` writes to the
+container's filesystem, ``token`` hands out the credential.
+
+This lives apart from ``client`` so the delivery consumer can check a payload
+before handing it anywhere, without importing the client.
+"""
+
+import re
+
+import aiogram.methods
+from aiogram import Bot
+
+from django_aiogram.exceptions import UnknownApiMethodError
+
+#: API methods a queued payload must never reach. They are administrative, not
+#: sends: set_webhook would point updates at someone else's URL, and log_out or
+#: close ends the session for the whole deployment.
+DENIED_METHODS = frozenset({'set_webhook', 'delete_webhook', 'log_out', 'close'})
+
+
+def _api_methods() -> frozenset[str]:
+    """Return the Bot attributes that correspond to a Telegram API method."""
+    api = {re.sub(r'(?<!^)(?=[A-Z])', '_', name).lower() for name in aiogram.methods.__all__}
+    public = {name for name in dir(Bot) if not name.startswith('_')}
+    return frozenset(api & public) - DENIED_METHODS
+
+
+API_METHODS = _api_methods()
+
+
+def check_function(function: str) -> str:
+    """Return ``function`` if it names a Telegram API method, else raise."""
+    if function not in API_METHODS:
+        raise UnknownApiMethodError(function, len(API_METHODS))
+    return function

django_aiogram/apps.py

@@ -0,0 +1,56 @@
+"""The Django app that hooks this package into a project's startup.
+
+Importing this module has to stay free of side effects: Django imports it while
+the app registry is still being populated, before settings are safe to read.
+Everything that needs configuration happens in ``ready()``.
+"""
+
+import logging
+
+from django.apps import AppConfig, apps
+from django.core.checks import register
+
+logger = logging.getLogger('django_aiogram')
+
+
+class TelegramBotAppConfig(AppConfig):
+    """Registers the system checks and imports every app's router module."""
+
+    name = 'django_aiogram'
+    label = 'django_aiogram'
+    verbose_name = 'django-aiogram'
+    # app-local, so it does not touch the project's DEFAULT_AUTO_FIELD
+    default_auto_field = 'django.db.models.BigAutoField'
+
+    def ready(self) -> None:
+        """Register the checks and autodiscover routers, unless disabled here."""
+        # deferred: apps.py is imported while the app registry is still loading
+        from django_aiogram.config.settings import SETTINGS_NAME, coerce_bool, conf  # noqa: PLC0415 - as above
+
+        # parsed, not truthiness-tested: 'false' has to disable startup the same
+        # way it disables sending, otherwise the two disagree
+        enabled = coerce_bool(conf['ENABLED'], f"{SETTINGS_NAME}['ENABLED']")
+        recording = coerce_bool(conf['EVENT_LOG'], f"{SETTINGS_NAME}['EVENT_LOG']")
+
+        # above the ENABLED gate on purpose: reading the log is not talking to
+        # Telegram, so an admin process that never sends still has to show it.
+        # The import chain is admin -> models -> django.db, never aiogram
+        if recording and apps.is_installed('django.contrib.admin'):
+            from django_aiogram.admin import register_event_log_admin  # noqa: PLC0415 - as above
+
+            register_event_log_admin()
+
+        if not (enabled or recording):
+            logger.debug('django-aiogram is disabled in this process')
+            return
+
+        # after the gate: checks are the only reason a disabled boot would pay
+        # for anything beyond the settings module
+        from django_aiogram.config.checks import check_settings  # noqa: PLC0415 - only when there is a report to make
+
+        register(check_settings)
+
+        if enabled and coerce_bool(conf['AUTODISCOVER'], f"{SETTINGS_NAME}['AUTODISCOVER']"):
+            from django_aiogram.consumer.routers import autodiscover_tg_routers  # noqa: PLC0415 - only when enabled
+
+            autodiscover_tg_routers()

django_aiogram/config/__init__.py

@@ -0,0 +1,15 @@
+"""What a project configures, and what refuses a bad value.
+
+`settings` reads the `TELEGRAM_BOT` dict and the `DJANGO_AIOGRAM_` environment twins;
+`defaults` is the only place a default lives; `enums` holds the values a setting accepts;
+`checks` judges the result and is the only module here that reports to Django.
+
+Nothing in this package may import from `producer`, `consumer` or `broker`: configuration
+is read by them and reads nothing of them, which is what keeps `manage.py check` from
+paying for aiogram.
+"""
+
+#: deliberately empty: callers import from the modules in this package, not from the
+#: package itself. A re-export here would make a second path to every name, and the one
+#: nobody chose is the one that cannot be moved later
+__all__: tuple[str, ...] = ()