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

django_aiogram/config/defaults.py

@@ -0,0 +1,102 @@
+"""Every setting the package reads, with its default and the reason for it."""
+
+from typing import Any
+
+
+def no_default_kwargs(_function: str, /) -> dict[str, Any]:
+    """Return no extra kwargs, whatever aiogram function is asked about."""
+    return {}
+
+
+DEFAULTS: dict[str, Any] = {
+    # whether this process should talk to Telegram or Redis at all
+    'ENABLED': True,
+    'TOKEN': '',
+    'REDIS_URL': '',
+    # import <app>.<MODULE_NAME> for every installed app on startup
+    'AUTODISCOVER': True,
+    'MODULE_NAME': 'tg_router',
+    # blpop; the keyspace consumer 1.x used was removed in 3.0
+    'DELIVERY': 'blpop',
+    # either json or pickle, json recommended
+    'SERIALIZER': 'json',
+    # the escape hatch for payloads JSON cannot describe. Off by default because
+    # unpickling queued data lets whoever writes the queue execute code
+    'ALLOW_PICKLE': False,
+    # 'redis', 'memory', or a dotted path to a BaseStorage subclass
+    'FSM_STORAGE': 'redis',
+    # forwarded to aiogram's DefaultBotProperties, e.g. {'parse_mode': 'HTML'}
+    'DEFAULT_BOT_PROPERTIES': {},
+    # per-function extras for what DefaultBotProperties cannot express
+    'DEFAULT_KWARGS': no_default_kwargs,
+    # stay under Telegram's published limits instead of waiting to be refused;
+    # set to None to disable. Budgets are per bot, so a second token gets its own
+    'RATE_LIMIT': {
+        'overall_per_second': 30,
+        'per_chat_per_second': 1,
+        'group_per_minute': 20,
+    },
+    'MAX_RETRIES': 10,
+    'RAISE_EXCEPTION': False,
+    'REDIS_MESSAGES_KEY': 'TELEGRAM_BOT_MESSAGE',
+    # names this worker's in-flight list; defaults to the hostname. Set it when
+    # several workers share a host, so they cannot reclaim each other's messages
+    'WORKER_NAME': '',
+    # how long a blocking pop waits before re-checking the shutdown flag
+    'BLPOP_TIMEOUT': 5,
+    # seconds close() gives in-flight sends to finish before canceling them. A float,
+    # which is what makes `DJANGO_AIOGRAM_DRAIN_TIMEOUT=0.5` readable: the
+    # environment coerces on the default's type, and an int default sent a fraction to
+    # the integer branch, where it raised out of apps.ready() and stopped every command
+    'DRAIN_TIMEOUT': 5.0,
+    # how many sends the consumer will leave in flight before it stops taking
+    # messages. 0 means no bound, which is what shipped before the consumer
+    # waited for a send to finish. Acknowledging scans the in-flight list, so an
+    # unbounded one turns draining a backlog into quadratic work
+    'MAX_IN_FLIGHT': 0,
+    # refuse to start where a message cannot survive the worker being killed
+    # mid-send, rather than running at-most-once without saying so
+    'REQUIRE_CRASH_SAFE': False,
+    'REDIS_TIMEOUT': 10,
+    # how often the consumer refreshes the key the healthcheck reads. The key lives
+    # three times as long, so one missed refresh is not a failure — and that TTL is
+    # also the most `--max-age` can ever observe
+    'HEARTBEAT_INTERVAL': 10,
+    # a queue longer than this fails the healthcheck; 0 turns the check off
+    'HEALTHCHECK_MAX_QUEUE': 0,
+    # where updates come from: 'polling' (a process calling getUpdates) or
+    # 'webhook' (Telegram posting them to a URL you serve). Both are supported;
+    # polling is the default because it needs nothing but an outbound connection
+    'MODE': 'polling',
+    # webhook mode: where Telegram posts updates, and the secret it echoes back
+    # in X-Telegram-Bot-Api-Secret-Token so the view can tell it is Telegram
+    'WEBHOOK_URL': '',
+    'WEBHOOK_SECRET': '',
+    # which update types to receive; empty means Telegram's own default set
+    'WEBHOOK_ALLOWED_UPDATES': (),
+    # record what the bot did to a table, one row per event, insert only. Off by
+    # default: it is a table whose size is set by traffic, so turning it on is a
+    # decision, and it needs a retention job to go with it
+    'EVENT_LOG': False,
+    # which kinds to keep; empty means every kind this version knows. Naming any
+    # also opts out of the kinds a later release adds
+    'EVENT_LOG_KINDS': (),
+    # 'none', 'summary' (argument names and sizes) or 'full' (message bodies).
+    # The default keeps personal data out of the table until you ask for it
+    'EVENT_LOG_PAYLOAD': 'summary',
+    'EVENT_LOG_MAX_PAYLOAD_BYTES': 8192,
+    # values under these keys are blanked before a row is written
+    'EVENT_LOG_REDACT_KEYS': ('token', 'secret', 'password', 'authorization', 'api_key', 'session'),
+    # events held in memory while the writer is behind; a full buffer drops the
+    # event rather than making a send wait on the database
+    'EVENT_LOG_BUFFER_SIZE': 1000,
+    'EVENT_LOG_BATCH_SIZE': 200,
+    'EVENT_LOG_FLUSH_INTERVAL': 1,
+    # days a row is kept; 0 keeps them for ever. Nothing on the write path
+    # deletes anything — `manage.py tgbot_prune_events` is what reads this
+    'EVENT_LOG_RETENTION_DAYS': 0,
+    # a DATABASES alias for the log; empty means the default one
+    'EVENT_LOG_DATABASE': '',
+    # write on the calling thread instead of the writer's: tests only
+    'EVENT_LOG_SYNC': False,
+}

django_aiogram/config/enums.py

@@ -0,0 +1,108 @@
+"""Named constants for the strings this package treats as data.
+
+Every value here is frozen: queued payloads carry serialization tags and user
+settings carry delivery, serializer, storage and mode names, so changing a value
+would break in-flight messages and every deployment's ``TELEGRAM_BOT`` block.
+The classes subclass ``str`` so that a member is interchangeable with the string
+it names, which is what keeps existing settings and payloads readable as-is.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class DeliveryKind(str, Enum):
+    """How the consumer learns that a message is waiting."""
+
+    BLPOP = 'blpop'
+
+
+@unique
+class SerializerKind(str, Enum):
+    """Which encoding writes and reads the queue."""
+
+    JSON = 'json'
+    PICKLE = 'pickle'
+
+
+@unique
+class StorageKind(str, Enum):
+    """Built-in aiogram FSM storage backends."""
+
+    REDIS = 'redis'
+    MEMORY = 'memory'
+
+
+@unique
+class UpdateMode(str, Enum):
+    """Where Telegram updates come from."""
+
+    POLLING = 'polling'
+    WEBHOOK = 'webhook'
+
+
+@unique
+class SerializationTag(str, Enum):
+    """Keys that mark a decoded JSON object as something richer than a mapping."""
+
+    MODEL = '__model__'
+    DEFAULT = '__default__'
+    DATETIME = '__datetime__'
+    DATE = '__date__'
+    DECIMAL = '__decimal__'
+    BYTES = '__bytes__'
+    INPUT_FILE = '__input_file__'
+
+
+@unique
+class RateLimitKey(str, Enum):
+    """Budget names inside the ``RATE_LIMIT`` setting."""
+
+    OVERALL_PER_SECOND = 'overall_per_second'
+    PER_CHAT_PER_SECOND = 'per_chat_per_second'
+    GROUP_PER_MINUTE = 'group_per_minute'
+
+
+@unique
+class EventKind(str, Enum):
+    """What one row of the event log records.
+
+    Namespaced by direction and dotted, so a project registering its own kinds
+    has an obvious convention to follow. These land in a database column and in
+    saved admin filters, which is why the values are frozen like the rest.
+    """
+
+    OUTBOUND_QUEUED = 'outbound.queued'
+    OUTBOUND_CONSUMED = 'outbound.consumed'
+    OUTBOUND_SENT = 'outbound.sent'
+    OUTBOUND_RETRIED = 'outbound.retried'
+    OUTBOUND_FAILED = 'outbound.failed'
+    OUTBOUND_DROPPED = 'outbound.dropped'
+    INBOUND_RECEIVED = 'inbound.received'
+    INBOUND_HANDLED = 'inbound.handled'
+    INBOUND_FAILED = 'inbound.failed'
+    FSM_TRANSITION = 'fsm.transition'
+    QUEUE_UNDECODABLE = 'queue.undecodable'
+    QUEUE_REJECTED = 'queue.rejected'
+    LOG_DROPPED = 'log.dropped'
+
+
+@unique
+class PayloadDetail(str, Enum):
+    """How much of a call's arguments the event log keeps."""
+
+    NONE = 'none'
+    SUMMARY = 'summary'
+    FULL = 'full'
+
+
+def choices(kind: type[Enum]) -> frozenset[str]:
+    """Return the values of ``kind`` as a frozenset, for membership checks."""
+    return frozenset(member.value for member in kind)
+
+
+#: here rather than beside the limiter that enforces them: `config.checks` needs the names
+#: to judge the setting, and reaching into `producer` for them would make configuration
+#: depend on the thing it configures — and would pay for whatever the limiter imports on
+#: every boot that registers a check
+KNOWN_RATE_LIMIT_KEYS: frozenset[str] = choices(RateLimitKey)

django_aiogram/config/settings.py

@@ -0,0 +1,266 @@
+"""Resolve the package's settings, lazily, from three sources.
+
+A project configures the package through one ``TELEGRAM_BOT`` dict in its Django
+settings. Anything it leaves out is looked for in the environment, and anything
+the environment leaves out comes from :mod:`django_aiogram.config.defaults`.
+
+Nothing here reads Django settings at import time: before 2.0 it did, which took
+the whole project down — its test suite included — whenever the token or Redis
+was absent.
+"""
+
+import logging
+import math
+import os
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from django.conf import settings as django_settings
+from django.core.exceptions import ImproperlyConfigured
+from django.core.signals import setting_changed
+
+from django_aiogram.config.defaults import DEFAULTS
+
+logger = logging.getLogger('django_aiogram')
+
+SETTINGS_NAME = 'TELEGRAM_BOT'
+ENV_PREFIX = 'DJANGO_AIOGRAM_'
+
+_TRUTHY = frozenset({'1', 'true', 'yes', 'on'})
+_FALSY = frozenset({'0', 'false', 'no', 'off'})
+
+_MISSING = object()
+
+
+def parse_bool(value: str, source: str) -> bool:
+    """Parse a human-written boolean, rejecting anything ambiguous.
+
+    ``source`` names the setting or variable in the error, so a typo is
+    traceable to the place that holds it.
+    """
+    normalized = value.strip().lower()
+    if normalized in _TRUTHY:
+        return True
+    if normalized in _FALSY:
+        return False
+    msg = f'{source} must be one of {sorted(_TRUTHY | _FALSY)}, got {value!r}.'
+    raise ImproperlyConfigured(msg)
+
+
+def coerce_bool(value: object, source: str) -> bool:
+    """Accept the shapes a settings file realistically holds.
+
+    Plain bool(value) would read the string 'false' as True and quietly enable
+    a bot the project meant to switch off.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return bool(value)
+    if isinstance(value, str):
+        return parse_bool(value, source)
+    msg = f'{source} must be a boolean, got {type(value).__name__}.'
+    raise ImproperlyConfigured(msg)
+
+
+def _from_env(key: str, default: object) -> object:
+    """Read a setting from the environment, coercing it to the default's type.
+
+    Returns the ``_MISSING`` sentinel when the variable is unset, which is what
+    lets an empty string through as a deliberate value.
+
+    Only scalars are supported: callables and containers have no sane textual
+    form, so they stay settings-only.
+    """
+    name = ENV_PREFIX + key
+    raw = os.environ.get(name)
+    if raw is None:
+        return _MISSING
+    if isinstance(default, bool):
+        return parse_bool(raw, name)
+    if isinstance(default, int):
+        try:
+            return int(raw)
+        except ValueError:
+            msg = f'{name} must be an integer, got {raw!r}.'
+            raise ImproperlyConfigured(msg) from None
+    if isinstance(default, float):
+        # a setting whose check accepts a number has to accept one from here too. Without
+        # this branch a float-defaulted setting fell through to `_MISSING` and the variable
+        # was *silently ignored*, and while `DRAIN_TIMEOUT` defaulted to an int the same
+        # value raised out of `apps.ready()` — so `DRAIN_TIMEOUT: 0.5` was valid in
+        # settings and stopped every `manage.py` command from the environment
+        try:
+            number = float(raw)
+        except ValueError:
+            msg = f'{name} must be a number, got {raw!r}.'
+            raise ImproperlyConfigured(msg) from None
+        if not math.isfinite(number):
+            # `float()` accepts 'nan', 'inf' and '-inf', and every consumer of these
+            # settings is a deadline: `nan` compares false against everything, so a wait
+            # bounded by it never expires, and `sleep(nan)` raises from inside a thread
+            # nobody is watching. E044 reports it, but only when `check` runs — and the
+            # environment reaches every process, including the ones that never run checks
+            msg = f'{name} must be a finite number, got {raw!r}.'
+            raise ImproperlyConfigured(msg)
+        return number
+    if isinstance(default, str):
+        return raw
+    # a container or a callable has no textual form, so the variable cannot be honoured —
+    # and being silently ignored is the worst of the three answers. An operator throttling
+    # the bot with DJANGO_AIOGRAM_RATE_LIMIT got the default rate and no word about
+    # it, from a page that promises an environment twin for every scalar
+    logger.warning(
+        'ignoring an environment variable for a setting that has no textual form',
+        extra={'tg_setting': key, 'tg_variable': name},
+    )
+    return _MISSING
+
+
+class Settings(Mapping[str, Any]):
+    """Package settings resolved on first access.
+
+    Resolution order is Django settings, then environment, then defaults.
+    Reading Django settings lazily is what keeps importing this package free of
+    side effects, so nothing here may run at import time.
+    """
+
+    def __init__(self) -> None:
+        """Start with nothing resolved; the first lookup does the work."""
+        self._cache: dict[str, Any] | None = None
+
+    def _resolve(self) -> dict[str, Any]:
+        """Build the whole settings dict once, in the documented order of precedence.
+
+        Every key at once rather than per lookup, so a process cannot end up holding one
+        value from Django settings and another from the environment because the two were
+        resolved at different moments.
+
+        The mapping check earns its place: ``key in overrides`` is a membership test, and
+        against a ``TELEGRAM_BOT`` that is a list it answers False for every key — so
+        without it the whole setting would be *silently* ignored and every value taken
+        from the environment or the defaults, including the token. A misconfiguration that
+        loudly refuses is worth more than one that runs as though unconfigured.
+
+        Only ``None`` and an absent setting mean *not configured*. Folding every falsy
+        value into ``{}`` first, which is what ``or {}`` did, let ``[]``, ``()`` and ``''``
+        past the check that exists to catch them — the empty ones, which are exactly what
+        a mistaken assignment produces.
+        """
+        overrides = getattr(django_settings, SETTINGS_NAME, None)
+        if overrides is None:
+            overrides = {}
+        if not isinstance(overrides, Mapping):
+            msg = f'{SETTINGS_NAME} must be a mapping, got {type(overrides).__name__}.'
+            raise ImproperlyConfigured(msg)
+        resolved = dict(DEFAULTS)
+        for key, default in DEFAULTS.items():
+            if key in overrides:
+                resolved[key] = overrides[key]
+                continue
+            value = _from_env(key, default)
+            if value is not _MISSING:
+                resolved[key] = value
+        # unknown keys are kept rather than dropped; checks.py warns about them
+        for key, value in overrides.items():
+            resolved.setdefault(key, value)
+        return resolved
+
+    @property
+    def resolved(self) -> dict[str, Any]:
+        """Every setting, resolved once and then cached until reset."""
+        # one read, kept local: a reset() between two reads would return None
+        cache = self._cache
+        if cache is None:
+            cache = self._cache = self._resolve()
+        return cache
+
+    def reset(self) -> None:
+        """Drop the cache, so the next read picks up changed settings."""
+        self._cache = None
+
+    def __getitem__(self, key: str) -> Any:  # noqa: ANN401 - a setting holds whatever the project put there
+        """Return one resolved setting, resolving them all on the first ask."""
+        return self.resolved[key]
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over the resolved setting names."""
+        return iter(self.resolved)
+
+    def __len__(self) -> int:
+        """Return how many settings are resolved."""
+        return len(self.resolved)
+
+    def __repr__(self) -> str:
+        """Describe the cache without resolving it: repr() must stay cheap."""
+        state = 'unresolved' if self._cache is None else f'{len(self._cache)} keys'
+        return f'<{type(self).__name__} {state}>'
+
+
+conf = Settings()
+
+
+@dataclass(frozen=True)
+class PopCeiling:
+    """How long a blocking pop may actually wait, and which settings decided that.
+
+    ``bound_by`` is a tuple because the limits can tie: ``HEARTBEAT_INTERVAL`` at 9
+    beside ``REDIS_TIMEOUT`` at 10 both produce 9, and naming one of them sends an
+    operator to raise it and meet the same warning again, unchanged.
+    """
+
+    seconds: int
+    bound_by: tuple[str, ...]
+
+
+def blpop_ceiling() -> PopCeiling:
+    """Return the real cap on a blocking pop, which is not ``BLPOP_TIMEOUT`` alone.
+
+    Two bounds are weighed here and the smallest wins: the ``HEARTBEAT_INTERVAL`` — a
+    worker that popped for longer than that would let its own heartbeat key expire and
+    look dead — and one second inside ``REDIS_TIMEOUT``, so the pop returns before the
+    read deadline fires. The configured ``BLPOP_TIMEOUT`` is the third, applied by the
+    caller against this ceiling, which is why ``bound_by`` can never name it.
+
+    One second inside ``REDIS_TIMEOUT`` is only possible from 2 upwards, which is what
+    ``E030``'s floor is for: at 1 the subtraction clamps back to 1, the pop's timeout
+    equals the read deadline, and every idle pop raises instead of returning empty.
+
+    Lives here rather than beside the consumer because ``checks.py`` needs it too, and
+    importing :mod:`django_aiogram.consumer.delivery` would pull in aiogram through
+    :mod:`django_aiogram.api` — which is the whole reason ``manage.py check``
+    costs nothing.
+
+    ``bound_by`` is what makes a hint actionable: told only that the pop is capped, an
+    operator raises ``REDIS_TIMEOUT`` when it was the heartbeat that bound it — and
+    when the two tie, raising either one alone changes nothing at all.
+    """
+    limits = {
+        'HEARTBEAT_INTERVAL': max(1, int(conf['HEARTBEAT_INTERVAL'])),
+        'REDIS_TIMEOUT': max(1, max(1, int(conf['REDIS_TIMEOUT'])) - 1),
+    }
+    seconds = min(limits.values())
+    # every setting sitting at the minimum, not the first one found: a tie means both
+    # have to move, and a hint naming one of them is a round trip that achieves nothing
+    return PopCeiling(seconds=seconds, bound_by=tuple(key for key, value in limits.items() if value == seconds))
+
+
+def _reset_on_setting_change(
+    sender: object,  # noqa: ARG001 - Django sends this to every receiver, named
+    setting: str,
+    **kwargs: Any,
+) -> None:
+    """Drop the resolved cache when the setting it was built from changes.
+
+    This is what makes ``override_settings`` work on a lazily cached mapping, and it is
+    a receiver rather than a test helper because a project may legitimately change the
+    setting at runtime. Filtered on the name: every other setting in the project sends
+    this signal too.
+    """
+    if setting == SETTINGS_NAME:
+        conf.reset()
+
+
+# dispatch_uid keeps autoreload from stacking duplicate receivers
+setting_changed.connect(_reset_on_setting_change, dispatch_uid='django_aiogram.config.settings')

django_aiogram/consumer/__init__.py

@@ -0,0 +1,13 @@
+"""The receive side: what turns a queued message or an update into a call.
+
+`delivery` consumes the broker and hands each message to a handler; `webhook` is the view
+an update arrives at; `routers` finds the handler modules a project wrote.
+
+The consumer talks to a transport only through `broker`. That boundary is why 4.0 can add a
+transport without touching this package.
+"""
+
+#: 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, ...] = ()