hjtdev-appkit 2.0.0__py3-none-any.whl

appkit/pagination.py

@@ -0,0 +1,30 @@
+"""The shared default pagination class.
+
+Public surface (docs/CONTRACT.md §2.7), implemented in a later phase:
+
+    class DefaultPagination(PageNumberPagination):
+        page_size = 25
+        page_size_query_param = "page_size"
+        max_page_size = 100
+
+A host wiring appkit needs no REST_FRAMEWORK["PAGE_SIZE"] — DefaultPagination carries its own
+page_size (docs/CONTRACT.md §8).
+"""
+
+from __future__ import annotations
+
+from rest_framework.pagination import PageNumberPagination
+
+__all__ = ["DefaultPagination"]
+
+
+class DefaultPagination(PageNumberPagination):
+    """Shared default so every app avoids re-declaring the same three numbers. A view that can
+    return unbounded data sets this (or its own) `pagination_class` explicitly per
+    `APP-DESIGN.md` §4, rather than relying on a host's `DEFAULT_PAGINATION_CLASS`, which the
+    app can't know.
+    """
+
+    page_size = 25
+    page_size_query_param = "page_size"
+    max_page_size = 100  # caps ?page_size= so a client can't defeat pagination entirely

appkit/permissions.py

@@ -0,0 +1,48 @@
+"""Shared DRF permission classes.
+
+Public surface (docs/CONTRACT.md §2.6), implemented in a later phase:
+
+    class IsAppAdmin(BasePermission):
+        def has_permission(self, request: Request, view: APIView) -> bool: ...
+
+    class IsObjectOwner(BasePermission):
+        owner_field: str = "user"
+
+        def has_object_permission(self, request: Request, view: APIView, obj: Any) -> bool: ...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework.permissions import BasePermission
+from rest_framework.request import Request
+from rest_framework.views import APIView
+
+__all__ = ["IsAppAdmin", "IsObjectOwner"]
+
+
+class IsAppAdmin(BasePermission):
+    """Gates the custom admin-dashboard API surface (`APP-DESIGN.md` §5's second admin
+    surface). Relies only on what Django's user model already guarantees everywhere — never on
+    another app's model. Never raises.
+    """
+
+    def has_permission(self, request: Request, view: APIView) -> bool:
+        return bool(request.user and request.user.is_authenticated and request.user.is_staff)
+
+
+class IsObjectOwner(BasePermission):
+    """Denies access to another user's object — the IDOR case `APP-DESIGN.md` §7.4 and §9's
+    security checklist name explicitly.
+    """
+
+    owner_field: str = "user"
+
+    def has_object_permission(self, request: Request, view: APIView, obj: Any) -> bool:
+        if not (request.user and request.user.is_authenticated):
+            return False
+        # A misconfigured `owner_field` must deny access, never raise `AttributeError`
+        # mid-permission-check — failing closed with a wrong-looking answer is safer than
+        # failing open by accident.
+        return getattr(obj, self.owner_field, None) == request.user

appkit/request_id.py

@@ -0,0 +1,96 @@
+"""Request-ID correlation — ContextVar, ASGI middleware, and logging filter, co-located.
+
+There is deliberately no ``appkit.logging`` module (docs/CONTRACT.md §2 preamble, §4): the
+``RequestIDFilter`` lives here, alongside the ``ContextVar`` and middleware it serves — exactly
+how ``../base-scaffold/backend/config/logging.py`` co-locates all three in one file today. This
+is a **port**, not a reimplementation: that file already worked out this module's sharp edges
+over two phases, and docs/CONTRACT.md §2.4 freezes the behaviour below as contract.
+
+No ``build_logging_config``, no ``structlog`` processor, no ``structlog`` dependency — log
+rendering is host policy (docs/CONTRACT.md §4). Only the three names below are appkit's; a host
+imports them into its own ``config/logging.py`` (docs/CONTRACT.md §8) and keeps everything else
+about how logs are rendered exactly where it already is.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import uuid
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+
+from asgiref.sync import markcoroutinefunction
+from django.http import HttpRequest, HttpResponse
+
+request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
+
+# Caps how much of an inbound X-Request-ID we trust, and restricts it to characters that
+# can't inject newlines or control sequences into a log line.
+_MAX_REQUEST_ID_LEN = 64
+_VALID_REQUEST_ID = re.compile(r"^[A-Za-z0-9-]+$")
+
+
+def _clean_request_id(raw: str | None) -> str:
+    """Accept an inbound X-Request-ID if it looks safe, else mint a new one."""
+    if raw and len(raw) <= _MAX_REQUEST_ID_LEN and _VALID_REQUEST_ID.match(raw):
+        return raw
+    return uuid.uuid4().hex
+
+
+class RequestIDMiddleware:
+    """Assigns/propagates a request ID for log correlation, and echoes it on the response.
+
+    Implemented as an async middleware (``async_capable = True``, ``sync_capable = False``):
+    a sync-only middleware would force Django to run the whole chain through a thread pool,
+    quietly undoing the reason a host is on ASGI in the first place. Belongs near the top of
+    ``MIDDLEWARE`` — after ``SecurityMiddleware``, before anything that logs
+    (docs/CONTRACT.md §8, checked by :func:`appkit.checks.check_middleware_order`).
+    """
+
+    sync_capable = False
+    async_capable = True
+
+    def __init__(self, get_response: Callable[[HttpRequest], Awaitable[HttpResponse]]) -> None:
+        self.get_response = get_response
+        # `sync_capable`/`async_capable` only tell Django's *own* `load_middleware` how to
+        # build this middleware's wrapper — they say nothing to a generic
+        # `inspect.iscoroutinefunction(instance)` check, which is what any middleware
+        # WRAPPING this one (e.g. SecurityMiddleware, via django.utils.deprecation's
+        # MiddlewareMixin) uses to decide whether to `await` it. Without this explicit
+        # mark, an instance's `async def __call__` is invisible to that check — Django's
+        # own `MiddlewareMixin` does this same marking internally; a raw, non-Mixin async
+        # middleware has to do it itself, or every outer sync-style middleware calls this
+        # one without awaiting it, crashing on the returned coroutine. Confirmed to break
+        # every real request (ASGI and WSGI both) without this line.
+        markcoroutinefunction(self)
+
+    async def __call__(self, request: HttpRequest) -> HttpResponse:
+        request_id = _clean_request_id(request.headers.get("X-Request-ID"))
+        # Always reset in `finally` — under ASGI concurrency, a set-without-reset leaks
+        # this request's ID into whatever runs next on the same task (most visibly, a
+        # Celery task enqueued mid-request, or an unrelated request if something goes wrong).
+        # This also covers the view raising: `reset` still runs before the exception
+        # propagates further up the middleware stack.
+        token = request_id_var.set(request_id)
+        try:
+            response = await self.get_response(request)
+        finally:
+            request_id_var.reset(token)
+        response["X-Request-ID"] = request_id
+        return response
+
+
+class RequestIDFilter(logging.Filter):
+    """Stamps `record.request_id` from the contextvar, for any handler/formatter that reads
+    the raw `LogRecord` rather than a structlog event dict (e.g. a plain %-style file handler).
+    Never raises — logging outside a request cycle (management commands, Celery tasks, process
+    startup) must still work, defaulting to "-". This contract is what
+    :func:`appkit.checks.check_logging_filter` (``appkit.W005``) exists to catch a host
+    forgetting to wire up, and what ``appkit.testing``'s ``frozen_request_id`` fixture makes
+    directly assertable from a consuming app's own tests.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.request_id = request_id_var.get()
+        return True

appkit/testing.py

@@ -0,0 +1,259 @@
+"""The opt-in pytest plugin — fixtures and an envelope assertion helper.
+
+Opt-in is explicit: ``-p appkit.testing`` in the consumer's own ``addopts``
+(``tool.pytest.ini_options``), never automatic. This module deliberately registers NO
+``pytest11`` entry point in pyproject.toml — two alternatives were considered and both rejected
+(docs/CONTRACT.md §2.17):
+
+  * A ``pytest11`` entry point would auto-load these fixtures into EVERY host's test suite the
+    moment appkit is merely installed (which is always, transitively) — invisible magic adding
+    fixtures nobody asked for into a namespace they didn't opt into.
+  * ``pytest_plugins = ["appkit.testing"]`` only works from the rootdir conftest in pytest 7+;
+    an app package's own ``testpaths = ["../tests/backend"]`` means the package's own conftest
+    isn't the rootdir conftest, so this wouldn't even work by default for the app packages that
+    need it most.
+
+A consuming app wires this up itself, in its own ``pyproject.toml``::
+
+    [tool.pytest.ini_options]
+    addopts = "-p appkit.testing ..."
+
+**Every name below carries an ``appkit_`` prefix — this is APP-DESIGN.md §1.3's namespacing
+rule applied to pytest's fixture registry, not a stylistic choice.** pytest's fixture registry
+is exactly the "shared, flat namespace" §1.3 is about: any name here can collide with a
+consuming app's own conftest fixture, another plugin's fixture, or a future pytest-django
+release. The concrete evidence this convention exists to prevent, found during this module's
+own implementation and kept here as the rationale a future reader will otherwise wonder about:
+pytest-django ships its OWN built-in fixtures literally named ``admin_user`` and
+``admin_client``, and empirically (verified directly against the installed pytest-django, not
+assumed) pytest-django's versions win that name collision **silently** — requesting
+``admin_user``/``admin_client`` as an ordinary fixture parameter anywhere pytest-django is
+active (which is everywhere ``db``/``django_db`` is used) returns pytest-django's plain
+User/Client, never appkit's reflective ones, with no warning anywhere. ``user`` and
+``api_client`` haven't collided with anything yet — but "hasn't collided yet" is precisely the
+condition §1.3's prefix rule exists to guard against, not a reason two of eight names get a
+prefix and six don't.
+
+Public surface (docs/CONTRACT.md §2.17):
+
+    @pytest.fixture
+    def appkit_api_client() -> APIClient: ...
+        # An unauthenticated DRF APIClient.
+
+    @pytest.fixture
+    def appkit_user(db) -> AbstractBaseUser: ...
+        # Built through get_user_model().USERNAME_FIELD REFLECTIVELY, not a hardcoded
+        # create_user(username=...) call — must work against a host on an email-based custom
+        # user model.
+
+    @pytest.fixture
+    def appkit_admin_user(db) -> AbstractBaseUser: ...
+        # Same reflective construction, staff/admin.
+
+    @pytest.fixture
+    def appkit_auth_client(appkit_api_client, appkit_user) -> APIClient: ...
+
+    @pytest.fixture
+    def appkit_admin_client(appkit_api_client, appkit_admin_user) -> APIClient: ...
+
+    @pytest.fixture
+    def appkit_frozen_request_id() -> Iterator[str]: ...
+        # Yields a fixed request-ID string; asserts it's restored to "-" (or the prior value)
+        # on fixture teardown, making RequestIDMiddleware's reset-in-finally contract directly
+        # assertable from a consuming app's own tests.
+
+    @pytest.fixture
+    def appkit_clear_cache() -> None: ...
+        # Deliberately NOT autouse — under `pytest -n auto` (pytest-xdist) against a shared
+        # Redis instance, an autouse fixture clearing the cache between every test would clear
+        # another xdist worker's in-flight test data too.
+
+    def appkit_assert_error_envelope(response: Response, *, code: str, status: int) -> None: ...
+        # Plain function, not a fixture — prefixed anyway for consistency with the rest of this
+        # module's public surface. Shared assertion for the docs/CONTRACT.md §1 envelope so
+        # nine installed apps don't hand-roll nine slightly different assertions. Raises the
+        # test framework's own AssertionError with a diff-friendly message on mismatch.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from django.contrib.auth import get_user_model
+from django.core.cache import cache
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from django.contrib.auth.base_user import AbstractBaseUser
+    from rest_framework.response import Response
+    from rest_framework.test import APIClient
+
+# Two distinct reasons the imports below are deferred into function bodies rather than living
+# up here at module scope:
+#
+# `rest_framework.test.APIRequestFactory` reads DRF's `api_settings` at class-definition time
+# (import time) — importing it at module scope here would break the moment ANY consumer loads
+# `-p appkit.testing` before Django settings are configured, which is exactly how pytest loads
+# `-p` plugins named in `addopts` (early, during `consider_preparse`, ahead of pytest-django's
+# own settings setup). Imported lazily inside `appkit_api_client()`.
+#
+# `appkit.request_id` imports cleanly at that same early point, but a module-scope import here
+# would make THIS module (also loaded that early, for the same `-p appkit.testing` reason)
+# import `appkit.request_id` before pytest-cov's own tracer attaches — coverage.py can then
+# never see any of that module's lines as executed, because the one-time module-body execution
+# that defines them already happened untraced (verified directly: request_id.py's own coverage
+# drops from 100% to 42% the moment this import moves to module scope, in appkit's own suite,
+# if it also dogfoods `-p appkit.testing` via its own addopts — which is exactly why it
+# deliberately doesn't; see backend/pyproject.toml's addopts comment). Imported lazily inside
+# `appkit_frozen_request_id()` instead — a coverage-measurement concern, not a correctness one,
+# but avoiding it costs nothing.
+
+__all__ = [
+    "appkit_admin_client",
+    "appkit_admin_user",
+    "appkit_api_client",
+    "appkit_assert_error_envelope",
+    "appkit_auth_client",
+    "appkit_clear_cache",
+    "appkit_frozen_request_id",
+    "appkit_user",
+]
+
+_PLACEHOLDER_PASSWORD = "appkit-testing-placeholder"  # noqa: S105
+
+
+def _build_user(*, is_staff: bool = False, is_superuser: bool = False) -> AbstractBaseUser:
+    """Builds a user through `get_user_model().USERNAME_FIELD` **reflectively** — never a
+    hardcoded `create_user(username=...)` call, so this works against a host on an
+    email-based (or any other) custom user model, not just Django's default `username`-keyed
+    one.
+    """
+    user_model = get_user_model()
+    username_field = user_model.USERNAME_FIELD
+    unique = uuid.uuid4().hex[:12]
+    username_value = f"{unique}@example.com" if "email" in username_field else unique
+
+    field_values: dict[str, Any] = {username_field: username_value}
+    for required_field in user_model.REQUIRED_FIELDS:
+        if required_field == username_field:
+            continue
+        field_values[required_field] = (
+            f"{unique}@example.com" if required_field == "email" else unique
+        )
+
+    new_user = user_model._default_manager.create_user(
+        password=_PLACEHOLDER_PASSWORD, **field_values
+    )
+    if is_staff or is_superuser:
+        if is_staff:
+            new_user.is_staff = True
+        if is_superuser:
+            new_user.is_superuser = True
+        new_user.save()
+    return new_user
+
+
+@pytest.fixture
+def appkit_api_client() -> APIClient:
+    """An unauthenticated DRF `APIClient`."""
+    from rest_framework.test import APIClient
+
+    return APIClient()
+
+
+@pytest.fixture
+def appkit_user(db: None) -> AbstractBaseUser:
+    """A plain (non-staff) user, built reflectively through `USERNAME_FIELD`."""
+    return _build_user()
+
+
+@pytest.fixture
+def appkit_admin_user(db: None) -> AbstractBaseUser:
+    """A staff+superuser user, built reflectively through `USERNAME_FIELD`."""
+    return _build_user(is_staff=True, is_superuser=True)
+
+
+@pytest.fixture
+def appkit_auth_client(appkit_api_client: APIClient, appkit_user: AbstractBaseUser) -> APIClient:
+    """`appkit_api_client`, force-authenticated as `appkit_user`."""
+    appkit_api_client.force_authenticate(user=appkit_user)
+    return appkit_api_client
+
+
+@pytest.fixture
+def appkit_admin_client(
+    appkit_api_client: APIClient, appkit_admin_user: AbstractBaseUser
+) -> APIClient:
+    """`appkit_api_client`, force-authenticated as `appkit_admin_user`."""
+    appkit_api_client.force_authenticate(user=appkit_admin_user)
+    return appkit_api_client
+
+
+@pytest.fixture
+def appkit_frozen_request_id() -> Iterator[str]:
+    """Yields a fixed request-ID string, and asserts `request_id_var` is restored to its prior
+    value on teardown — making `RequestIDMiddleware`'s reset-in-`finally` contract directly
+    assertable from a consuming app's own tests, not just appkit's.
+    """
+    from appkit.request_id import request_id_var
+
+    fixed_id = "frozen-test-request-id"
+    prior = request_id_var.get()
+    token = request_id_var.set(fixed_id)
+    try:
+        yield fixed_id
+    finally:
+        request_id_var.reset(token)
+        restored = request_id_var.get()
+        assert restored == prior, (
+            "appkit_frozen_request_id: request_id_var was not restored on teardown "
+            f"(expected {prior!r}, got {restored!r})"
+        )
+
+
+@pytest.fixture
+def appkit_clear_cache() -> None:
+    """Clears Django's default cache. **Deliberately not `autouse`** — under
+    `pytest -n auto` (pytest-xdist) against a single shared Redis instance, an autouse fixture
+    clearing the cache between every test would clear another xdist worker's in-flight test
+    data too. Use `LocMemCache` for test settings (isolated per process) if that isolation is
+    wanted by default instead.
+    """
+    cache.clear()
+
+
+def appkit_assert_error_envelope(response: Response, *, code: str, status: int) -> None:
+    """Asserts `response` carries the docs/CONTRACT.md §1 error envelope with the given `code`
+    and HTTP `status`. Raises a diff-friendly `AssertionError` on mismatch — the shared
+    assertion so N installed apps don't hand-roll N slightly different envelope checks.
+    """
+    if response.status_code != status:
+        raise AssertionError(
+            f"appkit_assert_error_envelope: expected status {status}, got "
+            f"{response.status_code}. response.data={response.data!r}"
+        )
+
+    data = response.data
+    if not isinstance(data, dict) or "error" not in data:
+        raise AssertionError(
+            "appkit_assert_error_envelope: response.data does not contain an 'error' "
+            f"envelope. response.data={data!r}"
+        )
+
+    envelope = data["error"]
+    actual_code = envelope.get("code")
+    if actual_code != code:
+        raise AssertionError(
+            f"appkit_assert_error_envelope: expected error code {code!r}, got "
+            f"{actual_code!r}. envelope={envelope!r}"
+        )
+
+    missing = [key for key in ("message", "details", "request_id") if key not in envelope]
+    if missing:
+        raise AssertionError(
+            f"appkit_assert_error_envelope: envelope is missing required key(s) {missing!r}. "
+            f"envelope={envelope!r}"
+        )

appkit/text.py

@@ -0,0 +1,62 @@
+"""Shared string helpers whose semantics must match the frontend half.
+
+Flagged in docs/CONTRACT.md §11 as one of the contract's two weakest modules — it survives past
+``truncate`` alone (which ``django.utils.text.Truncator`` already provides) only because the
+frontend half ships a matching ``truncate``, and matching client/server truncation is worth one
+small shared function.
+
+Public surface (docs/CONTRACT.md §2.12):
+
+    def truncate(value: str, length: int, *, suffix: str = "…") -> str: ...
+        # Counts len() (codepoints) — the frontend's Array.from-based count must agree; see
+        # tests/fixtures/truncate-vectors.json.
+
+    def to_english_digits(value: str) -> str: ...
+        # Persian ۰۱۲۳۴۵۶۷۸۹ and Arabic-Indic ٠١٢٣٤٥٦٧٨٩ digit sets, normalised to ASCII.
+
+    def to_persian_digits(value: str) -> str: ...
+"""
+
+from __future__ import annotations
+
+__all__ = ["to_english_digits", "to_persian_digits", "truncate"]
+
+# Persian and Arabic-Indic digit blocks, both normalised to ASCII by `to_english_digits` — a
+# Persian-locale keyboard can emit either set depending on the input method, so both are
+# accepted (docs/CONTRACT.md §2.12).
+_PERSIAN_DIGITS = "۰۱۲۳۴۵۶۷۸۹"
+_ARABIC_INDIC_DIGITS = "٠١٢٣٤٥٦٧٨٩"
+_ASCII_DIGITS = "0123456789"
+
+_TO_ENGLISH_TABLE = str.maketrans(_PERSIAN_DIGITS + _ARABIC_INDIC_DIGITS, _ASCII_DIGITS * 2)
+_TO_PERSIAN_TABLE = str.maketrans(_ASCII_DIGITS, _PERSIAN_DIGITS)
+
+
+def truncate(value: str, length: int, *, suffix: str = "…") -> str:
+    """Truncates `value` to `length` characters (codepoints), suffix included in the count.
+
+    `truncate("hello world", 8)` -> `"hello w…"` (8 characters total). Never raises: a
+    `length <= len(suffix)` returns the suffix itself, clamped to `length` characters (a
+    negative `length` clamps to an empty string). Counts `len()` — plain codepoints, not
+    grapheme clusters — matching the frontend's `Array.from`-based count (docs/CONTRACT.md §18),
+    which is also codepoint-based, not grapheme-based.
+    """
+    if length <= len(suffix):
+        return suffix[: max(length, 0)]
+    if len(value) <= length:
+        return value
+    return value[: length - len(suffix)] + suffix
+
+
+def to_english_digits(value: str) -> str:
+    """Normalises Persian and Arabic-Indic digits to ASCII. Never raises; characters outside
+    both digit sets pass through unchanged.
+    """
+    return value.translate(_TO_ENGLISH_TABLE)
+
+
+def to_persian_digits(value: str) -> str:
+    """Converts ASCII digits to Persian digits. Never raises; non-ASCII-digit characters pass
+    through unchanged.
+    """
+    return value.translate(_TO_PERSIAN_TABLE)

appkit/throttling.py

@@ -0,0 +1,41 @@
+"""Mechanical construction of DRF throttle-scope strings from the app-namespace prefix
+convention.
+
+Enforces APP-DESIGN.md §1.3's namespacing rule for throttle scopes — every one is prefixed with
+the app's own name, no exceptions, so two apps don't silently collide in one shared
+REST_FRAMEWORK["DEFAULT_THROTTLE_RATES"] dict.
+
+Public surface (docs/CONTRACT.md §2.15), implemented in a later phase:
+
+    def throttle_scope(app_namespace: str, action: str) -> str: ...
+        # e.g. throttle_scope("notifications", "list") -> "notifications_list"
+        # Raises ValueError if either argument is empty or contains an underscore itself.
+"""
+
+from __future__ import annotations
+
+__all__ = ["throttle_scope"]
+
+
+def throttle_scope(app_namespace: str, action: str) -> str:
+    """`throttle_scope("notifications", "list")` -> `"notifications_list"`.
+
+    Enforces naming at the point of declaration — the opt-in half of the prefix convention.
+    **Not** the same guarantee as `appkit.W004` (`appkit.checks.check_throttle_scopes`), which
+    checks the complementary, orthogonal property: that a declared `throttle_scope`, in whatever
+    format, has a matching `REST_FRAMEWORK["DEFAULT_THROTTLE_RATES"]` entry. Neither check
+    substitutes for the other.
+
+    Raises:
+        ValueError: if either argument is empty, or contains an underscore itself — which
+            would make the resulting scope ambiguous to split back apart, and more practically,
+            usually signals a caller passing an already-prefixed value by mistake.
+    """
+    if not app_namespace or not action:
+        raise ValueError("throttle_scope() requires non-empty app_namespace and action.")
+    if "_" in app_namespace or "_" in action:
+        raise ValueError(
+            "throttle_scope() arguments must not contain an underscore — "
+            f"got app_namespace={app_namespace!r}, action={action!r}."
+        )
+    return f"{app_namespace}_{action}"