drf-pollable 0.1.0__py3-none-any.whl

drf_pollable/__init__.py

@@ -0,0 +1,82 @@
+"""drf-pollable -- auto-generate polling (status) APIs for Django REST Framework.
+
+Point it at a model field and you get a ready-to-poll endpoint::
+
+    from drf_pollable import register_poll
+
+    register_poll(
+        "order-status",
+        source="shop.Order.status",
+        min_poll_interval=5,
+        done_when={"delivered", "cancelled"},
+    )
+
+    # GET /poll/order-status/42/
+    # 200  ETag: "a1b2"  Retry-After: 5
+    # {"value": "shipped", "done": false, "next_poll_in": 5, ...}
+
+See the README for the other declaration styles, the interval-negotiation rules,
+and the rate-limiting layers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "CallableSource",
+    "FieldSource",
+    "InstanceSource",
+    "PollEndpoint",
+    "PollRegistration",
+    "PollResult",
+    "PollRouter",
+    "PollSource",
+    "PollView",
+    "PollableConfigurationError",
+    "PollingMixin",
+    "QuerySetSource",
+    "poll_urls",
+    "register_poll",
+    "registry",
+]
+
+#: Import lazily so that merely importing this package (which Django does while
+#: populating INSTALLED_APPS) never pulls in DRF before settings are ready.
+_LAZY: dict[str, tuple[str, str]] = {
+    "CallableSource": (".sources", "CallableSource"),
+    "FieldSource": (".sources", "FieldSource"),
+    "InstanceSource": (".sources", "InstanceSource"),
+    "PollResult": (".sources", "PollResult"),
+    "PollSource": (".sources", "PollSource"),
+    "QuerySetSource": (".sources", "QuerySetSource"),
+    "PollEndpoint": (".registration", "PollEndpoint"),
+    "PollRegistration": (".registration", "PollRegistration"),
+    "register_poll": (".registration", "register_poll"),
+    "registry": (".registration", "registry"),
+    "PollRouter": (".routers", "PollRouter"),
+    "poll_urls": (".routers", "poll_urls"),
+    "PollingMixin": (".mixins", "PollingMixin"),
+    "PollView": (".views", "PollView"),
+    "PollableConfigurationError": (".exceptions", "PollableConfigurationError"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_path, attribute = _LAZY[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+    from importlib import import_module
+
+    value = getattr(import_module(module_path, __name__), attribute)
+    globals()[name] = value  # cache so later lookups skip this path
+    return value
+
+
+def __dir__() -> list[str]:  # pragma: no cover - REPL nicety
+    return sorted(__all__)

drf_pollable/apps.py

@@ -0,0 +1,31 @@
+"""App config -- discovers every declaration style once the registry is ready."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+from django.utils.module_loading import autodiscover_modules
+
+
+class DrfPollableConfig(AppConfig):
+    name = "drf_pollable"
+    verbose_name = "DRF Pollable"
+    default_auto_field = "django.db.models.AutoField"
+
+    #: ``ready()`` can run more than once (notably under the test runner);
+    #: discovery is idempotent but we skip the repeat work anyway.
+    _discovered = False
+
+    def ready(self):
+        if self.__class__._discovered:
+            return
+        self.__class__._discovered = True
+
+        from .registration import registry
+
+        # Order matters, and later sources win:
+        #   1. polls.py in each app  -- the common case
+        #   2. model PollingMeta     -- declared next to the data
+        #   3. settings ENDPOINTS    -- central, so ops can override the above
+        autodiscover_modules("polls")
+        registry.load_from_models()
+        registry.load_from_settings()

drf_pollable/conf.py

@@ -0,0 +1,154 @@
+"""Two-layer configuration for drf-pollable.
+
+Effective value for any option resolves as::
+
+    per-endpoint value  ->  settings.DRF_POLLABLE["DEFAULTS"]  ->  BUILTIN_DEFAULTS
+
+Projects configure globals in ``settings.py``::
+
+    DRF_POLLABLE = {
+        "DEFAULTS": {"min_poll_interval": 5, "jitter": 0.1},
+        "ENDPOINTS": {
+            "order-status": {"source": "shop.Order.status"},
+        },
+    }
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.conf import settings as django_settings
+from django.core.signals import setting_changed
+from django.dispatch import receiver
+
+#: Built-in fallbacks. Every option a registration understands appears here so
+#: that ``resolve_config()`` always returns a fully-populated mapping and call
+#: sites never need ``.get(key, fallback)``.
+BUILTIN_DEFAULTS: dict[str, Any] = {
+    # --- kill switch -------------------------------------------------------
+    "enabled": True,
+    # --- interval negotiation (see README "Who decides the interval?") -----
+    # Hard floor the server is willing to be polled at.
+    "min_poll_interval": 5,
+    # What we advertise via Retry-After. ``None`` -> falls back to the floor.
+    "suggested_poll_interval": None,
+    # Ceiling used when clamping a client-requested interval / backoff growth.
+    "max_poll_interval": 3600,
+    # When True a too-early poll is rejected with 429 instead of merely hinted.
+    "enforce_interval": False,
+    # Query param a client may use to request its own cadence. None disables.
+    "client_interval_param": "interval",
+    # "fixed" | "exponential" -- how the *suggested* interval grows while the
+    # value keeps coming back unchanged.
+    "backoff": "fixed",
+    "backoff_factor": 2.0,
+    # Ceiling for backoff growth. ``None`` -> max_poll_interval.
+    "backoff_max": None,
+    # Random spread applied to the advertised interval, as a fraction (0.1 =
+    # +/-10%). Prevents synchronised clients re-polling in lockstep.
+    "jitter": 0.0,
+    # --- response shape ----------------------------------------------------
+    # True  -> {"value": ..., "done": ..., "next_poll_in": ...}
+    # False -> the bare serialized value, with the metadata in headers only.
+    "envelope": True,
+    "send_etag": True,
+    "send_last_modified": True,
+    # --- performance -------------------------------------------------------
+    # Seconds to cache the computed value+version. 0 disables.
+    "cache_timeout": 0,
+    # Keep each user's cached value separate. Only set False when the data is
+    # genuinely identical for every caller -- otherwise one user's value would
+    # be served to another.
+    "cache_vary_on_user": True,
+    # --- hints -------------------------------------------------------------
+    # After this many consecutive *changed* polls, add an X-Poll-Upgrade-Hint
+    # header suggesting websockets/SSE would suit this data better. 0 disables.
+    "upgrade_hint_after": 0,
+    # --- DRF plumbing ------------------------------------------------------
+    "throttle_scope": None,
+    "throttle_classes": None,
+    "permission_classes": None,
+    "authentication_classes": None,
+    # --- lifecycle ---------------------------------------------------------
+    # RFC 8594 Sunset header, e.g. "2027-01-01" or a date/datetime.
+    "sunset": None,
+    "deprecation_message": None,
+    # --- routing -----------------------------------------------------------
+    "url_prefix": "poll",
+    "lookup_field": "pk",
+    "lookup_url_kwarg": None,
+}
+
+_cache: dict[str, Any] = {}
+
+
+def _source_keys() -> frozenset[str]:
+    """Keys that describe *what* to poll rather than *how*.
+
+    Imported lazily so ``conf`` stays importable before the app registry is up.
+    """
+    from .sources import SOURCE_ARG_NAMES
+
+    return SOURCE_ARG_NAMES | {"as_list"}
+
+
+def _raw() -> dict[str, Any]:
+    return getattr(django_settings, "DRF_POLLABLE", None) or {}
+
+
+def global_defaults() -> dict[str, Any]:
+    """BUILTIN_DEFAULTS overlaid with ``DRF_POLLABLE["DEFAULTS"]``."""
+    if "defaults" not in _cache:
+        merged = dict(BUILTIN_DEFAULTS)
+        merged.update(_raw().get("DEFAULTS") or {})
+        unknown = set(merged) - set(BUILTIN_DEFAULTS)
+        if unknown:
+            raise ImproperlyConfiguredDefaults(sorted(unknown))
+        _cache["defaults"] = merged
+    return _cache["defaults"]
+
+
+def settings_endpoints() -> dict[str, dict[str, Any]]:
+    """Endpoints declared centrally via ``DRF_POLLABLE["ENDPOINTS"]``."""
+    return dict(_raw().get("ENDPOINTS") or {})
+
+
+def resolve_config(overrides: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Merge per-endpoint ``overrides`` over the global defaults.
+
+    Unknown keys are rejected loudly: a silently-ignored typo in
+    ``min_poll_intervall`` would otherwise look like the option simply had no
+    effect.
+    """
+    config = dict(global_defaults())
+    source_keys = _source_keys()
+    for key, value in (overrides or {}).items():
+        if key in source_keys:
+            continue
+        if key not in BUILTIN_DEFAULTS:
+            raise ImproperlyConfiguredDefaults([key])
+        config[key] = value
+
+    # Derived fallbacks, applied once so the view layer can read them directly.
+    if config["suggested_poll_interval"] is None:
+        config["suggested_poll_interval"] = config["min_poll_interval"]
+    if config["backoff_max"] is None:
+        config["backoff_max"] = config["max_poll_interval"]
+    return config
+
+
+class ImproperlyConfiguredDefaults(Exception):
+    """Raised when DRF_POLLABLE contains options drf-pollable does not know."""
+
+    def __init__(self, keys: list[str]):
+        known = ", ".join(sorted(BUILTIN_DEFAULTS))
+        super().__init__(
+            f"Unknown drf-pollable option(s): {', '.join(keys)}. Valid options are: {known}"
+        )
+
+
+@receiver(setting_changed)
+def _reset_cache(sender, setting, **kwargs):  # pragma: no cover - test plumbing
+    if setting == "DRF_POLLABLE":
+        _cache.clear()

drf_pollable/envelope.py

@@ -0,0 +1,52 @@
+"""The JSON body a polling endpoint returns.
+
+By default responses are *enveloped* so the client gets the polling metadata it
+needs to pace itself alongside the value::
+
+    {
+      "value": "shipped",
+      "version": "9f2c...",
+      "done": false,
+      "next_poll_in": 5,
+      "polled_at": "2026-09-28T10:12:03.114Z"
+    }
+
+Set ``envelope=False`` to return the bare value instead; the same metadata is
+still available in the ``ETag`` and ``Retry-After`` headers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.utils import timezone
+
+#: Envelope keys the package owns. A source's ``extra`` may not overwrite these.
+RESERVED_KEYS = frozenset({"value", "version", "done", "next_poll_in", "polled_at"})
+
+
+def build_envelope(result, *, version: str, next_poll_in: int, config: dict[str, Any]) -> Any:
+    """Build the response body for ``result``."""
+    if not config["envelope"]:
+        return result.value
+
+    body: dict[str, Any] = {
+        "value": result.value,
+        "version": version,
+        "done": bool(result.done),
+        "next_poll_in": next_poll_in,
+        "polled_at": timezone.now().isoformat(),
+    }
+
+    if result.progress is not None:
+        body["progress"] = result.progress
+    if result.eta_seconds is not None:
+        body["eta_seconds"] = result.eta_seconds
+
+    # Source-supplied extras (display label, count, cursor, ...). Reserved keys
+    # are dropped rather than silently shadowing the envelope contract.
+    for key, value in (result.extra or {}).items():
+        if key not in RESERVED_KEYS:
+            body[key] = value
+
+    return body

drf_pollable/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by drf-pollable."""
+
+from __future__ import annotations
+
+
+class PollableConfigurationError(Exception):
+    """Raised when a polling endpoint is declared with an invalid configuration.
+
+    This is a programming error (bad ``source`` string, unknown model, duplicate
+    endpoint name, missing field allow-list), so it deliberately is *not* a DRF
+    ``APIException`` -- it should blow up loudly at registration or first use
+    rather than quietly becoming a 500 for end users.
+    """

drf_pollable/headers.py

@@ -0,0 +1,101 @@
+"""HTTP conditional-request helpers.
+
+Polling is only cheap if an unchanged poll is cheap. These helpers implement the
+``ETag`` / ``If-None-Match`` and ``Last-Modified`` / ``If-Modified-Since``
+handshake that lets an unchanged poll return a bodyless ``304``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from datetime import date, datetime, timezone
+from typing import Any
+
+from django.utils.http import http_date, parse_etags, parse_http_date_safe, quote_etag
+
+
+def make_version(payload: Any) -> str:
+    """Derive a short, stable version token by hashing ``payload``.
+
+    Deliberately hashes the *value* rather than trusting a timestamp field. An
+    ``auto_now`` column does not fire on ``QuerySet.update()``, so a
+    timestamp-derived token would miss real changes and hand the client a stale
+    ``304``. Hashing costs almost nothing here -- the value is already loaded.
+    """
+    blob = json.dumps(payload, sort_keys=True, default=str, separators=(",", ":"))
+    return hashlib.blake2b(blob.encode("utf-8"), digest_size=10).hexdigest()
+
+
+def etag_for(version: str) -> str:
+    """Return a correctly quoted strong ETag for ``version``."""
+    return quote_etag(str(version))
+
+
+def if_none_match_matches(request, etag: str) -> bool:
+    """True when the client's ``If-None-Match`` already holds ``etag``."""
+    header = request.META.get("HTTP_IF_NONE_MATCH")
+    if not header:
+        return False
+    header = header.strip()
+    if header == "*":
+        return True
+    try:
+        client_etags = parse_etags(header)
+    except (ValueError, TypeError):
+        return False
+    # Compare weak-insensitively: W/"x" and "x" refer to the same version here.
+    target = _strip_weak(etag)
+    return any(_strip_weak(candidate) == target for candidate in client_etags)
+
+
+def if_modified_since_satisfied(
+    request, last_modified: datetime | None, now: float | None = None
+) -> bool:
+    """True when the resource provably has not changed since the client's copy.
+
+    ``Last-Modified`` is a *weak* validator: HTTP dates carry only one-second
+    resolution, so a value that changes in the same second the client fetched
+    it is indistinguishable from one that did not. Requiring the modification
+    to sit in a strictly earlier second than this request closes that window --
+    the cost is a single full response for a value that just changed, instead
+    of a ``304`` that strands the client on a stale copy.
+    """
+    if last_modified is None:
+        return False
+    header = request.META.get("HTTP_IF_MODIFIED_SINCE")
+    if not header:
+        return False
+    since = parse_http_date_safe(header)
+    if since is None:
+        return False
+    modified_at = int(last_modified.timestamp())
+    if modified_at > since:
+        return False
+    # Within the current second the timestamp cannot be trusted yet.
+    return modified_at < int(time.time() if now is None else now)
+
+
+def format_last_modified(value: datetime) -> str:
+    return http_date(value.timestamp())
+
+
+def format_sunset(value: date | datetime | str) -> str:
+    """Format a ``Sunset`` header value (RFC 8594 -- an HTTP date)."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, datetime):
+        moment = value
+    else:
+        moment = datetime(value.year, value.month, value.day, tzinfo=timezone.utc)
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    return http_date(moment.timestamp())
+
+
+def _strip_weak(etag: str) -> str:
+    etag = etag.strip()
+    if etag.startswith(("W/", "w/")):
+        etag = etag[2:]
+    return etag.strip('"')

drf_pollable/intervals.py

@@ -0,0 +1,76 @@
+"""Interval negotiation between client and server.
+
+The rule, in one line: **the client may always ask to poll more slowly, never
+faster than the server allows.**
+
+* ``min_poll_interval`` is the server's hard floor (self-protection).
+* ``suggested_poll_interval`` is what we advertise via ``Retry-After``.
+* Exponential backoff grows the suggestion while the value keeps coming back
+  unchanged, so idle clients quiet down on their own.
+* Jitter spreads synchronised clients so they do not re-poll in lockstep.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any
+
+
+def parse_requested_interval(request, config: dict[str, Any]) -> float | None:
+    """Read the client's preferred cadence from the query string.
+
+    Garbage input is ignored rather than raising -- a malformed ``?interval=``
+    should not break a status poll.
+    """
+    param = config.get("client_interval_param")
+    if not param:
+        return None
+    raw = request.query_params.get(param) if hasattr(request, "query_params") else None
+    if raw in (None, ""):
+        return None
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return None
+    return value if value > 0 else None
+
+
+def compute_next_interval(
+    config: dict[str, Any],
+    *,
+    unchanged_streak: int = 0,
+    requested: float | None = None,
+    apply_jitter: bool = True,
+) -> int:
+    """Return the interval (seconds) to advertise to the client.
+
+    ``unchanged_streak`` is how many consecutive polls have returned the same
+    version; it drives exponential backoff.
+    """
+    base = float(config["suggested_poll_interval"])
+
+    if config["backoff"] == "exponential" and unchanged_streak > 0:
+        factor = float(config["backoff_factor"]) ** unchanged_streak
+        base = min(base * factor, float(config["backoff_max"]))
+
+    # The client may request a *slower* cadence; we take the larger of the two
+    # so a client request can never undercut the server's current suggestion.
+    if requested is not None:
+        base = max(base, float(requested))
+
+    floor = float(config["min_poll_interval"])
+    ceiling = float(config["max_poll_interval"])
+    base = max(floor, min(base, ceiling))
+
+    if apply_jitter:
+        base = _jitter(base, float(config.get("jitter") or 0.0), floor=floor)
+
+    return max(1, int(round(base)))
+
+
+def _jitter(value: float, fraction: float, *, floor: float) -> float:
+    """Spread ``value`` by +/- ``fraction`` without dropping below ``floor``."""
+    if fraction <= 0:
+        return value
+    spread = value * fraction
+    return max(floor, value + random.uniform(-spread, spread))

drf_pollable/management/commands/list_polls.py

@@ -0,0 +1,73 @@
+"""``python manage.py list_polls`` -- show every registered polling endpoint.
+
+Answers "what is pollable, at what URL, and with which limits?" without
+grepping the codebase -- useful because endpoints can be declared five
+different ways.
+"""
+
+from __future__ import annotations
+
+from django.core.management.base import BaseCommand
+
+from ...registration import registry
+
+#: Options worth showing by default. ``--verbose`` prints the full config.
+HIGHLIGHT_KEYS = (
+    "min_poll_interval",
+    "suggested_poll_interval",
+    "max_poll_interval",
+    "enforce_interval",
+    "backoff",
+    "jitter",
+    "throttle_scope",
+    "cache_timeout",
+    "enabled",
+)
+
+
+class Command(BaseCommand):
+    help = "List every registered drf-pollable endpoint and its effective configuration."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--verbose",
+            action="store_true",
+            help="Show every configuration option, not just the notable ones.",
+        )
+        parser.add_argument(
+            "--name",
+            help="Show only the endpoint with this name.",
+        )
+
+    def handle(self, *args, **options):
+        registrations = sorted(registry, key=lambda item: item.name)
+        if options.get("name"):
+            registrations = [r for r in registrations if r.name == options["name"]]
+
+        if not registrations:
+            self.stdout.write(self.style.WARNING("No polling endpoints are registered."))
+            return
+
+        for registration in registrations:
+            self._print(registration, verbose=options.get("verbose", False))
+
+        self.stdout.write("")
+        self.stdout.write(self.style.SUCCESS(f"{len(registrations)} polling endpoint(s)."))
+
+    def _print(self, registration, *, verbose: bool):
+        config = registration.config
+        prefix = (config["url_prefix"] or "").strip("/")
+        url = f"/{prefix}/{registration.url_path}" if prefix else f"/{registration.url_path}"
+
+        self.stdout.write("")
+        self.stdout.write(self.style.MIGRATE_HEADING(registration.name))
+        self.stdout.write(f"  source   {registration.source.describe()}")
+        # Relative to wherever poll_urls() is mounted in the root URLconf.
+        self.stdout.write(f"  path     {url}")
+        self.stdout.write(f"  declared {registration.origin}")
+
+        keys = sorted(config) if verbose else HIGHLIGHT_KEYS
+        shown = [(key, config[key]) for key in keys if key in config]
+        width = max((len(key) for key, _ in shown), default=0)
+        for key, value in shown:
+            self.stdout.write(f"  {key.ljust(width)}  {value!r}")