hjtdev-appkit 2.0.0__tar.gz

hjtdev_appkit-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Hojjat Nikoobakht
+
+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.

hjtdev_appkit-2.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# Ships locale/ in the wheel/sdist — not .py files, so no build backend includes them by
+# default (APP-DESIGN.md §2). Paired with include-package-data = true in pyproject.toml.
+#
+# No templates/, no static/: docs/CONTRACT.md never affirmatively commits appkit to shipping
+# either (it commits only to locale/, §5) — appkit has no views, no rendering, and is
+# explicitly "not a component library" (docs/CONTRACT.md §J).
+recursive-include src/appkit/locale *.po *.mo

hjtdev_appkit-2.0.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: hjtdev-appkit
+Version: 2.0.0
+Summary: Shared Django + DRF foundation every app package and host in this ecosystem depends on — cache, mixins, error envelope, request-ID plumbing, and the HttpClient/provider contract. Not an installable feature; the thing every other app is built on.
+License-Expression: MIT
+Requires-Python: >=3.13
+License-File: LICENSE
+Requires-Dist: django<7.0,>=5.2
+Requires-Dist: djangorestframework<4.0,>=3.15
+Requires-Dist: nh3<1.0,>=0.2
+Requires-Dist: puremagic<3,>=2
+Requires-Dist: jdatetime<7,>=5
+Provides-Extra: crypto
+Requires-Dist: cryptography<51,>=42; extra == "crypto"
+Provides-Extra: images
+Requires-Dist: pillow<13,>=11.3; extra == "images"
+Dynamic: license-file

hjtdev_appkit-2.0.0/pyproject.toml

@@ -0,0 +1,219 @@
+[build-system]
+# setuptools-scm deliberately NOT included here (APP-DESIGN.md §3.1 declares it but never
+# wires it up — no `dynamic = ["version"]`, no [tool.setuptools_scm] table — so it would be
+# dead weight, and it would fight CLAUDE.md's "pyproject.toml/package.json/CHANGELOG.md agree"
+# rule once all three files exist).
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# "hjtdev-appkit", not the bare "appkit" — the unscoped name is an unrelated, already-registered
+# PyPI package (AppKit, a Webkit desktop app framework), so a prefixed name is not a style choice
+# but the only one available. Same situation, same fix, as frontend/package.json's
+# "@hjtdev/appkit" (docs/CONTRACT.md §22). This is the DISTRIBUTION name only — the importable
+# module stays `appkit` everywhere (`import appkit`, `INSTALLED_APPS`, `AppConfig.name`, the
+# appkit.E001-W006 check IDs) exactly like `python-dateutil` ships `import dateutil`.
+name = "hjtdev-appkit"
+# 0.x = no stability guarantee while the public surface (docs/CONTRACT.md) is still being
+# written into code. Bumped to 1.0.0 here, deliberately, at Phase 8 — not incrementally per
+# phase, since nothing consumed the intermediate numbers. Bumped to 2.0.0 for the PyPI
+# publication/rename above: unlike the frontend's 1.0.1 rename, the backend's prior install
+# command (`uv add "git+...#subdirectory=backend"`) actually worked, so changing the
+# requirement string is a real break for an existing consumer, not a fix to something broken.
+# Must match frontend/package.json and CHANGELOG.md; CI's version-lockstep job enforces it.
+version = "2.0.0"
+description = "Shared Django + DRF foundation every app package and host in this ecosystem depends on — cache, mixins, error envelope, request-ID plumbing, and the HttpClient/provider contract. Not an installable feature; the thing every other app is built on."
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+
+# appkit is the single most widely shared dependency in the entire ecosystem (docs/CONTRACT.md
+# §9) — an exact pin here is the worst possible place for one. Every range below is verified
+# against PyPI/OSV.dev in docs/CONTRACT.md §9, not guessed.
+dependencies = [
+    "django>=5.2,<7.0",
+    "djangorestframework>=3.15,<4.0",
+    # nh3 is a HARD dependency, not an extra, on purpose: an optional HTML sanitiser is a
+    # sanitiser some app skips, and skipping it is a stored-XSS bug waiting to happen.
+    "nh3>=0.2,<1.0",
+    # puremagic over python-magic (needs system libmagic, absent from slim/Alpine images —
+    # unacceptable for a dependency installed into an arbitrary host) and over filetype
+    # (effectively unmaintained since 2022).
+    "puremagic>=2,<3",
+    # Pulls in jalali-core>=1.0 transitively (pure Python, ~10 KB, zero further deps) —
+    # named explicitly here per docs/CONTRACT.md §9 so `uv tree` doesn't surprise anyone.
+    "jdatetime>=5,<7",
+]
+
+# Extras = features a CONSUMER opts into, installed with hjtdev-appkit[crypto] /
+# hjtdev-appkit[images]. cryptography (42 lifetime OSV advisories) and pillow (153) are kept
+# optional specifically because of that advisory count — every hard dependency above has zero. A
+# missing extra must fail with an actionable "install with hjtdev-appkit[crypto]" message, never
+# a bare ImportError (docs/CONTRACT.md §9) — enforced by importing them lazily inside
+# appkit.crypto / appkit.files, never at module top level.
+[project.optional-dependencies]
+crypto = ["cryptography>=42,<51"]
+# >=11.3, not just >=10: pillow only started shipping cp314 wheels at 11.3.0, and its sdist
+# fails to build on 3.14 (setup.py's version detection raises KeyError against current
+# setuptools) — found live by Phase 8's resolution-matrix CI job against Python 3.14, the
+# version this package's own tooling standardizes on (.python-version, playground, CI default).
+images = ["pillow>=11.3,<13"]
+
+# PEP 735 groups = tooling for developing appkit ITSELF. Never installed by a consumer, never
+# published, not visible to a host at all.
+#
+# `pytest` is deliberately absent from BOTH `dependencies` and any extra, even though
+# appkit.testing (the pytest plugin, docs/CONTRACT.md §2.17) imports it at module scope: the
+# plugin only ever loads via `-p appkit.testing` from inside an already-running pytest
+# process, where pytest is present by definition. Making it a hard/extra dependency would put
+# a test framework in every host's production image for a module no host imports directly.
+# (Gap in docs/CONTRACT.md §9, which never places pytest — resolved here.)
+#
+# No factory-boy: appkit ships no models, so APP-DESIGN.md §7.3's factories.py surface does
+# not apply (docs/CONTRACT.md §10).
+[dependency-groups]
+dev = [
+    "ruff>=0.12",
+    "mypy>=1.14",
+    "django-stubs[compatible-mypy]>=5.1",
+    "djangorestframework-stubs>=3.15",
+    "pre-commit>=4.0",
+]
+test = [
+    "pytest>=8.3",
+    "pytest-django>=4.9",
+    "pytest-cov>=6.0",
+    "pytest-xdist>=3.6",
+    # >=3.2.10, not just >=3.2: psycopg-binary only started shipping cp314 wheels at 3.2.10 —
+    # found live by Phase 8's resolution-matrix CI job, which resolves this floor for real
+    # against Python 3.14 rather than assuming any 3.2.x satisfies it. tests run on Postgres,
+    # APP-DESIGN.md §7.5.
+    "psycopg[binary]>=3.2.10",
+]
+
+[tool.uv]
+default-groups = ["dev", "test"]     # `uv sync` gives a contributor everything
+
+[tool.setuptools]
+# Package data (locale/) is not .py, so it silently doesn't ship without this — paired with
+# MANIFEST.in. APP-DESIGN.md §2's "Package data must be declared" note.
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Belt and braces alongside MANIFEST.in: package-data is what actually lands package data in the
+# *wheel* (MANIFEST.in governs the sdist). py.typed was previously covered by neither — it
+# appeared in the stale egg-info SOURCES.txt but nothing affirmatively included it in a built
+# wheel, which would have silently stripped every type hint from every consumer. Verified by
+# Phase 8's wheel-smoke-test CI job, not assumed.
+[tool.setuptools.package-data]
+appkit = ["py.typed", "locale/*/LC_MESSAGES/*.po", "locale/*/LC_MESSAGES/*.mo"]
+
+# ---------------------------------------------------------------- ruff
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "../tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",     # pycodestyle
+    "F",          # pyflakes
+    "I",          # isort
+    "UP",         # pyupgrade
+    "B",          # bugbear
+    "DJ",         # flake8-django
+    "S",          # bandit — security
+    "TID",        # tidy-imports (used to enforce the host-boundary rule, see below)
+    "RUF",
+]
+ignore = ["S101"]  # assert is fine in tests
+
+[tool.ruff.lint.per-file-ignores]
+"../tests/**" = ["S", "TID251"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"
+
+# --- Host modules. THE rule that actually bites for this package (CLAUDE.md rule 2). An app
+# package cannot assume a host's internals exist at a stable import path (APP-DESIGN.md §4).
+# Structural for appkit specifically: appkit IS what tools.* moves into (BASE-DESIGN.md §3),
+# so importing back would also be circular.
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"tools".msg = "appkit must never import host modules — APP-DESIGN.md §4. appkit IS what tools.* moves into."
+"core".msg = "appkit must never import host modules — APP-DESIGN.md §4."
+"config".msg = "appkit must never import host modules — APP-DESIGN.md §4."
+
+# --- Sibling app packages: currently an EMPTY SET. appkit is app package #1, so there is no
+# sibling to ban yet. Add one line per app as each is created:
+#   "<app>_app".msg = "App packages must never import each other — see APP-DESIGN.md §6."
+#
+# appkit itself is NEVER added to any app's banned-api list — it is a declared dependency
+# every app is expected to import (APP-DESIGN.md §1.1's named exception), not a sibling the
+# rule exists to keep out.
+#
+# No factories entry either: appkit ships no models, so no factories.py (docs/CONTRACT.md
+# §10) — APP-DESIGN.md §7.3's third public test surface does not apply here.
+
+# ---------------------------------------------------------------- mypy
+[tool.mypy]
+python_version = "3.13"
+strict = true
+plugins = ["mypy_django_plugin.main", "mypy_drf_plugin.main"]
+warn_unreachable = true
+# NOT in APP-DESIGN.md §3.1's example. Without it, [tool.django-stubs]'s
+# django_settings_module = "tests.backend.settings" is unresolvable when mypy runs from
+# backend/ (the settings module lives one level up, outside src/) and `uv run mypy src` fails.
+mypy_path = "..:src"
+
+# jdatetime ships no py.typed marker and no stub package exists on PyPI (verified) — appkit.dates
+# is the only module that imports it, and does so as internal implementation detail only, never
+# in a public signature (docs/CONTRACT.md §2.13), so a blanket ignore here can't leak an Any into
+# any consumer-facing type.
+[[tool.mypy.overrides]]
+module = "jdatetime"
+ignore_missing_imports = true
+
+[tool.django-stubs]
+django_settings_module = "tests.backend.settings"
+
+# ---------------------------------------------------------------- pytest
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.backend.settings"
+pythonpath = ["src", ".."]
+testpaths = ["../tests/backend"]
+python_files = ["test_*.py"]
+# Coverage gate is 95%, not the usual 85% (CLAUDE.md) — appkit ships complete rather than
+# growing under four installed apps, so its own suite stands in for usage feedback.
+#
+# DO NOT add `-p appkit.testing` to the addopts below. It looks like the obviously-correct
+# dogfooding move — appkit.testing IS meant to be used this way — and that's exactly why this
+# comment exists: someone will try it again. Verified directly, not assumed: a plugin loaded via
+# `-p` in addopts is imported during pytest's early `consider_preparse` phase, BEFORE pytest-cov's
+# own tracer attaches. coverage.py then permanently reports that module (and everything it
+# imports at module scope) as "previously imported but not measured" — measured on this exact
+# codebase: appkit.request_id's coverage dropped from 100% to 42%, and appkit.testing's own from
+# ~95% to 63%, purely from this measurement artefact, with no change in what actually ran or
+# passed. Re-adding `-p appkit.testing` here will silently reproduce both drops and can push the
+# 95% gate to fail depending on what else changed.
+#
+# `tests/backend/test_testing_plugin.py` calls each fixture's own `_fixture_function` directly
+# instead (normal import timing, fully measured) to exercise appkit.testing in-process. Its one
+# subprocess test, `test_reflective_user_fixture_against_a_non_username_user_model`, is what
+# actually proves the real `-p appkit.testing` opt-in path works end to end — its own docstring
+# explains exactly what would fail (and how) if `-p` stopped working, so that proof doesn't
+# depend on this module being in addopts at all.
+addopts = """
+  -ra --strict-markers --strict-config
+  --cov=appkit --cov-report=term-missing --cov-fail-under=95
+"""
+markers = [
+    "slow: excluded from the default run, opt in with -m slow",
+    "integration: crosses a real DB boundary rather than mocking it",
+    "requires_extra: needs the crypto and/or images extra installed — deselected on the bare-install leg (-m 'not requires_extra', docs/CONTRACT.md §9's two-leg strategy)",
+]
+filterwarnings = ["error::DeprecationWarning"]
+
+[tool.coverage.run]
+omit = ["*/tests/*"]

hjtdev_appkit-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hjtdev_appkit-2.0.0/src/appkit/__init__.py

@@ -0,0 +1,39 @@
+"""appkit — the shared Django + DRF foundation every app package and host in this ecosystem
+depends on.
+
+Not an installable feature; it is what ``backend/tools/`` (cache, mixins, crypto) and
+``config/logging.py``'s request-ID plumbing move into once this package exists
+(``BASE-DESIGN.md`` §3). Every other app package declares appkit as a dependency and imports
+its helpers instead of reimplementing them.
+
+This module intentionally re-exports nothing. Each submodule below is its own public surface —
+import from ``appkit.<module>`` directly (e.g. ``from appkit.cache import cached_call``), never
+from ``appkit`` itself. ``appkit.conf`` is explicitly *not* re-exported here even internally
+(docs/CONTRACT.md §2.16: "not re-exported from a top-level ``appkit`` namespace").
+
+Public modules (docs/CONTRACT.md §2):
+    ``appkit.cache``        — cache namespace versioning, key building, endpoint caching
+    ``appkit.mixins``       — ``CachedListMixin``, a DRF list-view response caching mixin
+    ``appkit.exceptions``   — the standard DRF exception handler and the ten error codes
+    ``appkit.request_id``   — the request-ID ContextVar, ASGI middleware, and logging filter
+    ``appkit.crypto``       — Fernet encryption taking its key at call time (``crypto`` extra)
+    ``appkit.permissions``  — shared DRF permission classes
+    ``appkit.pagination``   — the shared default pagination class
+    ``appkit.validation``   — query-param validation, HTML sanitisation, an ORM lookup allowlist
+    ``appkit.files``        — upload/image validation via magic-byte sniffing (``images`` extra)
+    ``appkit.net``          — trust-boundary real client IP extraction
+    ``appkit.media``        — media URL absolutisation (never ``appkit.urls`` — see below)
+    ``appkit.text``         — truncation and digit normalisation shared with the frontend half
+    ``appkit.dates``        — Gregorian <-> Jalali conversion using stdlib types only
+    ``appkit.money``        — integer money parsing/formatting shared with the frontend half
+    ``appkit.throttling``   — DRF throttle-scope string construction
+    ``appkit.testing``      — the opt-in pytest plugin (``-p appkit.testing``)
+
+Internal-but-stable (docs/CONTRACT.md §2.16):
+    ``appkit.conf``         — the ``APPKIT`` settings-dict accessor and its ``DEFAULTS``
+
+appkit ships no ``urlpatterns`` and is never ``include()``d anywhere, by any host — there is no
+``appkit.urls``, deliberately (docs/CONTRACT.md §10). appkit ships no models, no migrations, no
+admin, no ``services.py``, no ``signals.py``, and no Celery/``django.tasks`` integration
+(docs/CONTRACT.md §0, §10).
+"""

hjtdev_appkit-2.0.0/src/appkit/apps.py

@@ -0,0 +1,33 @@
+"""appkit's ``AppConfig``.
+
+``INSTALLED_APPS`` membership is confirmed, not merely left standing (docs/CONTRACT.md §5), for
+two reasons: translations become real only when appkit is a genuine ``INSTALLED_APPS`` member
+(``standard_exception_handler``'s user-facing strings are wrapped in ``gettext_lazy`` and
+discovered via a shipped ``locale/`` directory), and the system checks in :mod:`appkit.checks`
+must be registered from ``ready()`` to run at all.
+
+appkit defines no models, so there is no ``default_auto_field`` to set.
+"""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class AppKitConfig(AppConfig):
+    name = "appkit"
+    verbose_name = _("App Kit")
+
+    def ready(self) -> None:
+        from django.core.checks import register
+
+        from appkit import checks
+
+        register(checks.check_request_id_middleware)
+        register(checks.check_exception_handler)
+        register(checks.check_middleware_order)
+        register(checks.check_unknown_settings_keys)
+        register(checks.check_throttle_scopes)
+        register(checks.check_logging_filter)
+        register(checks.check_num_proxies_throttle_agreement)

hjtdev_appkit-2.0.0/src/appkit/cache.py

@@ -0,0 +1,222 @@
+"""Cache namespace versioning, key building, get-or-set, and endpoint-level response caching.
+
+Public surface (docs/CONTRACT.md §2.1), implemented in a later phase:
+
+    namespace_version(namespace: str) -> int
+        Opaque version number for a cache namespace. Seeds from ``int(time.time())``, not the
+        literal ``1`` — the return value must be treated as opaque, never assumed to start at 1.
+
+    invalidate_namespace(namespace: str) -> int
+        Bumps a namespace's version, effectively invalidating every key built against it.
+
+    build_cache_key(namespace: str, *parts: object) -> str
+        Builds a cache key incorporating the namespace's current version.
+
+    cached_call(key: str, timeout: int | None, producer: Callable[[], T]) -> T
+        Get-or-set around an arbitrary producer callable. ``timeout`` accepts appkit.conf.UNSET
+        to mean "use APPKIT['CACHE_TIMEOUT']" — resolved to avoid the ambiguity of a bare
+        ``None`` meaning either "no timeout" or "use the default".
+
+    cache_endpoint(*, namespace: str, timeout: int | None = UNSET, per_user: bool = True,
+                   vary_headers: Sequence[str] = (), cache_statuses: Container[int] = (200,))
+        Decorator for endpoint-level response caching. Raises ImproperlyConfigured at
+        decoration time (import time) if ``namespace`` is empty. ``per_user`` exists
+        specifically to prevent cross-user cache leakage.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Callable, Container, Sequence
+from functools import wraps
+from typing import Any, cast
+
+from django.core.cache import cache
+from django.core.exceptions import ImproperlyConfigured
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from appkit.conf import UNSET, _Unset, get_setting
+
+__all__ = [
+    "build_cache_key",
+    "cache_endpoint",
+    "cached_call",
+    "invalidate_namespace",
+    "namespace_version",
+]
+
+# Keeps generated keys short and free of characters the cache backend (or a log line) might
+# treat specially, once a part gets long or contains something other than
+# alphanumerics/dashes/underscores/periods.
+#
+# **Deviation from the scaffold's `_SAFE_PART`:** the scaffold's version includes `:` as a
+# "safe" character for an individual *part*, which would defeat the segment-smuggling
+# protection below — a part containing `:` (the join delimiter used one line down) would be
+# embedded raw instead of hashed, letting it forge extra `namespace:version:...` segments.
+# Excluding `:` here is what actually satisfies "a delimiter must never smuggle a second
+# segment into the key". docs/CONTRACT.md §2.1's own notation (`[A-Za-z0-9\-_.]`) already
+# excludes it too and states this exclusion explicitly — the two agree.
+_MAX_RAW_PART_LEN = 40
+_SAFE_PART = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.")
+
+
+def _version_key(namespace: str) -> str:
+    return f"{namespace}:version"
+
+
+def namespace_version(namespace: str) -> int:
+    """Returns the current version for `namespace`, seeding it on first use.
+
+    **Changed from the scaffold:** seeds from `int(time.time())`, not the literal `1`
+    (docs/CONTRACT.md §2.1). The scaffold's get-then-increment isn't atomic against Django's
+    cache API; if the version key is evicted under memory pressure and reseeds at `1`, every key
+    built against a *higher* version before the eviction becomes reachable again — silently
+    resurrecting data an earlier `invalidate_namespace` call explicitly invalidated. Seeding from
+    a wall-clock second makes any reseed monotonically ahead of every version that could
+    plausibly have been issued before it. The return value is therefore **opaque** — never
+    assume it starts at `1`. Never raises.
+    """
+    version = cache.get(_version_key(namespace))
+    if version is None:
+        # `add`, not `set`: two processes racing to seed the same namespace must not let the
+        # second clobber the first's (very slightly later, but already-issued) timestamp.
+        cache.add(_version_key(namespace), int(time.time()), timeout=None)
+        version = cache.get(_version_key(namespace))
+    return int(version)
+
+
+def invalidate_namespace(namespace: str) -> int:
+    """Bumps `namespace`'s version, invalidating every key previously built against it.
+
+    Returns the new version — guaranteed strictly greater than what came before it in this
+    process's view. Never raises (calls `namespace_version` first to guarantee the key exists
+    before `cache.incr`).
+    """
+    namespace_version(namespace)  # ensure it exists before incrementing
+    return cache.incr(_version_key(namespace))
+
+
+def _normalize_part(part: object) -> str:
+    raw = str(part)
+    if len(raw) > _MAX_RAW_PART_LEN or not set(raw) <= _SAFE_PART:
+        return hashlib.sha256(raw.encode()).hexdigest()[:16]
+    return raw
+
+
+def build_cache_key(namespace: str, *parts: object) -> str:
+    """Builds a stable, namespace-versioned cache key.
+
+    `namespace:version:part1:part2:...` — long or unsafe parts are hashed rather than embedded
+    raw, so an arbitrary string (a user-supplied search query, say) can't blow up key length or
+    smuggle a delimiter into the key. Never raises.
+    """
+    version = namespace_version(namespace)
+    segments = [namespace, str(version), *(_normalize_part(p) for p in parts)]
+    return ":".join(segments)
+
+
+def cached_call[T](
+    key: str,
+    timeout: int | _Unset | None,
+    producer: Callable[[], T],
+) -> T:
+    """Get-or-set: returns the cached value at `key`, computing and storing it via
+    `producer()` on a miss. `producer` is called at most once per miss.
+
+    `timeout=None` means "cache forever" (Django's own cache semantics) and therefore cannot
+    double as "use the configured default" — pass `appkit.conf.UNSET` for that instead,
+    resolved here to `APPKIT["CACHE_TIMEOUT"]` (docs/CONTRACT.md §2.1). `UNSET` is not part of
+    this function's *documented* public type (`int | None`) — it renders in docs as "omit the
+    argument" — but is accepted and typed here so `appkit.mixins`/`cache_endpoint` passing it
+    through still type-checks.
+
+    A `producer` that returns `None` is never actually cached — Django's cache API can't
+    distinguish "miss" from "cached `None`" through `.get()`'s default. Fine for the typical use
+    (caching a queryset result, a serialized dict), but don't reach for this to cache a value
+    that's legitimately `None`. Never raises on its own; propagates whatever `producer` raises.
+    """
+    resolved_timeout = get_setting("CACHE_TIMEOUT") if timeout is UNSET else timeout
+    value = cache.get(key)
+    if value is None:
+        value = producer()
+        cache.set(key, value, timeout=resolved_timeout)
+    return cast("T", value)
+
+
+def _user_cache_token(request: Request, *, per_user: bool) -> str:
+    """`per_user=False` shares one cache entry across every caller — valid only where the
+    response is byte-identical for everyone, including anonymous. `per_user=True` isolates by
+    the user's `pk`, falling back to a fixed `"anon"` bucket rather than folding an anonymous
+    caller into whatever the *first* unauthenticated request happened to produce a falsy-looking
+    identity for — an explicit `is None` check, not `pk or "anon"`, so a real user whose `pk`
+    happens to be `0` is never treated as anonymous.
+    """
+    if not per_user:
+        return "shared"
+    pk = getattr(request.user, "pk", None)
+    return str(pk) if pk is not None else "anon"
+
+
+def cache_endpoint[F: Callable[..., Response]](
+    *,
+    namespace: str,
+    timeout: int | _Unset | None = UNSET,
+    per_user: bool = True,
+    vary_headers: Sequence[str] = (),
+    cache_statuses: Container[int] = (200,),
+) -> Callable[[F], F]:
+    """Decorator wrapping a DRF view method (`list`/`retrieve`/...) with response caching, the
+    way `appkit.mixins.CachedListMixin` wraps `ListAPIView.list` — for views that aren't plain
+    list views.
+
+    `namespace` is **required, no default** — an unprefixed key is exactly the
+    two-apps-collide scenario `APP-DESIGN.md` §1.3 exists to prevent, so there is no safe
+    default to fall back to. Raises `ImproperlyConfigured` at decoration time (import time) if
+    `namespace` is empty.
+
+    `per_user=True` is the load-bearing default. **Non-obvious failure path:** with
+    `per_user=False` on a permission-gated view, user A's response is served verbatim to user
+    B — an authorization bypass via the cache layer, not a cache bug. `per_user=False` is valid
+    *only* where the response is byte-identical for every caller including anonymous users.
+
+    `vary_headers` folds additional request headers into the cache key (e.g. `Accept-Language`
+    for a bilingual endpoint) beyond user + full path. `cache_statuses` restricts caching to
+    responses whose status is in this set — a 403/404 is never cached by default, since caching
+    an authorization failure can make it outlive the state that caused it. Caches
+    `{"data": ..., "status": ...}`, never the `Response` object itself.
+    """
+    if not namespace:
+        raise ImproperlyConfigured(
+            "cache_endpoint() requires a non-empty `namespace` — an unprefixed cache key is "
+            "exactly the two-apps-collide scenario APP-DESIGN.md §1.3 exists to prevent."
+        )
+
+    def decorator(view_method: F) -> F:
+        @wraps(view_method)
+        def wrapper(self: Any, request: Request, *args: Any, **kwargs: Any) -> Response:
+            key_parts: list[object] = [
+                _user_cache_token(request, per_user=per_user),
+                request.get_full_path(),
+                *(request.headers.get(header, "") for header in vary_headers),
+            ]
+            key = build_cache_key(namespace, *key_parts)
+
+            cached = cache.get(key)
+            if cached is not None:
+                return Response(cached["data"], status=cached["status"])
+
+            response = view_method(self, request, *args, **kwargs)
+            if response.status_code in cache_statuses:
+                resolved_timeout = get_setting("CACHE_TIMEOUT") if timeout is UNSET else timeout
+                cache.set(
+                    key,
+                    {"data": response.data, "status": response.status_code},
+                    timeout=resolved_timeout,
+                )
+            return response
+
+        return cast("F", wrapper)
+
+    return decorator