hjtdev-appkit 2.0.0__py3-none-any.whl

appkit/crypto.py

@@ -0,0 +1,102 @@
+"""Fernet symmetric encryption primitive taking its key at construction time.
+
+Requires the ``crypto`` extra (``hjtdev-appkit[crypto]``). A missing extra must fail with an
+actionable message, never a bare ImportError — import ``cryptography`` lazily inside the
+function/method that needs it, wrapped in try/except ImportError, re-raised naming the exact
+fix (``Install with: uv add "hjtdev-appkit[crypto]"`` / ``pip install "hjtdev-appkit[crypto]"``).
+This error path is itself unit-tested (docs/CONTRACT.md §9).
+
+appkit never reads ``settings.FERNET_KEY`` or any other Django setting for this — the key is
+always a call-time argument. This is the resolution to the tools/-vs-appkit tension
+(docs/CONTRACT.md §3): field-level crypto stays in ``tools/crypto.py`` permanently, wrapping the
+HOST's ``FERNET_KEY``; an app declaring ``hjtdev-appkit[crypto]`` builds a ``Cipher`` from its OWN
+documented ``.env`` key. appkit therefore requires no ``.env`` key and no settings key for
+encryption, under any install combination.
+
+Public surface (docs/CONTRACT.md §2.5):
+
+    class Cipher:
+        def __init__(self, key: str | bytes) -> None: ...   # raises ImproperlyConfigured on a
+                                                              # bad key
+        def encrypt(self, value: str) -> str: ...
+        def decrypt(self, token: str) -> str: ...            # raises
+                                                              # cryptography.fernet.InvalidToken
+
+    def generate_key() -> str: ...
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.core.exceptions import ImproperlyConfigured
+
+if TYPE_CHECKING:
+    from cryptography.fernet import Fernet
+
+__all__ = ["Cipher", "generate_key"]
+
+_INSTALL_HINT = (
+    'Install with: uv add "hjtdev-appkit[crypto]" (or: pip install "hjtdev-appkit[crypto]")'
+)
+
+
+def _fernet_class() -> type[Fernet]:
+    """Lazily imports `cryptography.fernet.Fernet`, behind the `crypto` extra.
+
+    A missing extra must fail with an actionable message, never a bare `ImportError` three
+    frames deep — this path is unit-tested by simulating the import failure.
+    """
+    try:
+        from cryptography.fernet import Fernet
+    except ImportError as exc:
+        raise ImportError(
+            f"appkit.crypto requires the 'cryptography' package. {_INSTALL_HINT}"
+        ) from exc
+    return Fernet
+
+
+class Cipher:
+    """Fernet symmetric encryption, keyed at construction — never from Django settings.
+
+    A host's own encryption key is its own documented `.env` key; this class only ever wraps
+    whatever key its caller passes in.
+    """
+
+    def __init__(self, key: str | bytes) -> None:
+        """Builds the underlying `Fernet` cipher from `key`.
+
+        Raises:
+            ImportError: if the `crypto` extra isn't installed.
+            ImproperlyConfigured: if `key` isn't a valid Fernet key (44-byte urlsafe-base64) —
+                never the raw `cryptography` `ValueError`/`TypeError`/`binascii.Error` — naming
+                `generate_key()` as the fix.
+        """
+        fernet_cls = _fernet_class()
+        try:
+            self._fernet = fernet_cls(key)
+        except (TypeError, ValueError) as exc:
+            raise ImproperlyConfigured(
+                "appkit.crypto.Cipher() was given a key that is not a valid Fernet key. "
+                "Generate one with appkit.crypto.generate_key()."
+            ) from exc
+
+    def encrypt(self, value: str) -> str:
+        """Returns a URL-safe token string. Never raises for any `str` input."""
+        return self._fernet.encrypt(value.encode()).decode()
+
+    def decrypt(self, token: str) -> str:
+        """Decrypts a token produced by `encrypt`.
+
+        Raises `cryptography.fernet.InvalidToken` for a tampered, expired (if a TTL was used),
+        or wrong-key token — never silently returns garbage.
+        """
+        return self._fernet.decrypt(token.encode()).decode()
+
+
+def generate_key() -> str:
+    """Thin wrapper over `Fernet.generate_key().decode()` — provisions a key for `Cipher`
+    without a caller needing to `import cryptography` directly.
+    """
+    fernet_cls = _fernet_class()
+    return fernet_cls.generate_key().decode()

appkit/dates.py

@@ -0,0 +1,183 @@
+"""Gregorian <-> Jalali conversion, formatting, and parsing using stdlib types only.
+
+No third-party type in any public signature — ``jdatetime``/``jalali-core`` stay internal
+(docs/CONTRACT.md §9). A major-version bump in either can never force an appkit major bump on
+its own.
+
+Public surface (docs/CONTRACT.md §2.13):
+
+    def to_jalali(value: date | datetime) -> tuple[int, int, int]: ...
+    def from_jalali(year: int, month: int, day: int) -> date: ...   # raises ValueError
+    def format_jalali(value: date | datetime, fmt: str = "%Y/%m/%d") -> str: ...
+    def parse_jalali(value: str, fmt: str = "%Y/%m/%d") -> date: ...   # raises ValueError
+
+Golden vectors verified against tests/fixtures/jalali-vectors.json (docs/CONTRACT.md §19):
+every leap year in the 33-year Jalali cycle plus adjacent non-leap years, Esfand 29 vs. 30 in
+both leap and non-leap years, Nowruz across several years, the 31-day/30-day month-length
+boundary, Gregorian leap years including century years, and dates well outside the near present
+— every vector round-tripped in both directions.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from typing import Final
+
+import jdatetime
+from django.utils import timezone
+
+from appkit.text import to_english_digits
+
+__all__ = ["format_jalali", "from_jalali", "parse_jalali", "to_jalali"]
+
+# docs/CONTRACT.md §18: format_jalali/parseJalali support only the numeric directives below —
+# no month names ship in v1.0.0 (removes an entire Persian-spelling-drift divergence class
+# between the two halves). An unrecognised directive raises, mirroring strftime's own failure
+# mode, which stdlib strftime itself does NOT do for %B/%A-style directives it doesn't
+# recognise — this is why format_jalali/parse_jalali can't simply delegate to strftime/strptime.
+_SUPPORTED_DIRECTIVES: Final[frozenset[str]] = frozenset("YmdHMS%")
+
+_DIRECTIVE_REGEX: Final[dict[str, str]] = {
+    "Y": r"\d{1,4}",
+    "m": r"\d{1,2}",
+    "d": r"\d{1,2}",
+    "H": r"\d{1,2}",
+    "M": r"\d{1,2}",
+    "S": r"\d{1,2}",
+}
+
+
+def to_jalali(value: dt.date | dt.datetime) -> tuple[int, int, int]:
+    """Returns `(year, month, day)` for the Jalali calendar date corresponding to `value`.
+
+    **The timezone rule (docs/CONTRACT.md §18), implemented exactly as stated, not re-decided:**
+    an *aware* `datetime` is localised via `django.utils.timezone.localtime()` (Django's own
+    `TIME_ZONE` setting) before the Jalali date is extracted — a datetime at `23:30 UTC` may
+    already be tomorrow in `Asia/Tehran`. A *naive* `datetime` is treated as already-local
+    (`localtime()` itself raises on a naive value, so it's simply not called). A plain `date`
+    has no timezone component and is converted directly.
+
+    `datetime` is checked before `date` — `datetime` is a subclass of `date`, so the reverse
+    order would silently treat every `datetime` as a plain, timezone-naive date. Never raises
+    for any valid `date`/`datetime`.
+    """
+    if isinstance(value, dt.datetime):
+        localized = timezone.localtime(value) if timezone.is_aware(value) else value
+        gregorian_date = localized.date()
+    else:
+        gregorian_date = value
+    jalali_date = jdatetime.date.fromgregorian(date=gregorian_date)
+    return jalali_date.year, jalali_date.month, jalali_date.day
+
+
+def from_jalali(year: int, month: int, day: int) -> dt.date:
+    """The inverse of `to_jalali`.
+
+    Raises `ValueError` for an invalid Jalali calendar date (day 31 in a 30-day Jalali month,
+    an invalid Esfand 30) — the same exception shape `datetime.date(...)` itself raises for an
+    invalid Gregorian date, so callers don't need a Jalali-specific except clause.
+    """
+    jalali_date = jdatetime.date(year, month, day)  # raises ValueError on an invalid date
+    result: dt.date = jalali_date.togregorian()
+    return result
+
+
+def _time_components(value: dt.date | dt.datetime) -> tuple[int, int, int]:
+    if not isinstance(value, dt.datetime):
+        return 0, 0, 0
+    localized = timezone.localtime(value) if timezone.is_aware(value) else value
+    return localized.hour, localized.minute, localized.second
+
+
+def format_jalali(value: dt.date | dt.datetime, fmt: str = "%Y/%m/%d") -> str:
+    """`strftime`-style formatting of `value`'s Jalali representation.
+
+    Supports only `%Y %m %d %H %M %S %%` (docs/CONTRACT.md §18 — no month names in v1.0.0).
+    Never raises for a valid `date`/`datetime` input; an unsupported directive raises
+    `ValueError`, mirroring stdlib `strftime`'s own failure mode for a malformed format string.
+    """
+    year, month, day = to_jalali(value)
+    hour, minute, second = _time_components(value)
+    substitutions = {
+        "Y": f"{year:04d}",
+        "m": f"{month:02d}",
+        "d": f"{day:02d}",
+        "H": f"{hour:02d}",
+        "M": f"{minute:02d}",
+        "S": f"{second:02d}",
+        "%": "%",
+    }
+
+    result: list[str] = []
+    i = 0
+    while i < len(fmt):
+        char = fmt[i]
+        if char != "%":
+            result.append(char)
+            i += 1
+            continue
+        if i + 1 >= len(fmt):
+            raise ValueError(f"appkit.dates.format_jalali: dangling '%' at end of format {fmt!r}")
+        directive = fmt[i + 1]
+        if directive not in _SUPPORTED_DIRECTIVES:
+            raise ValueError(
+                f"appkit.dates.format_jalali: unsupported format directive '%{directive}' in "
+                f"{fmt!r}"
+            )
+        result.append(substitutions[directive])
+        i += 2
+    return "".join(result)
+
+
+def _compile_format(fmt: str) -> re.Pattern[str]:
+    """Builds a matching regex for `fmt`, one named group per first occurrence of a directive.
+
+    A directive repeated in `fmt` gets a non-capturing group on its second+ occurrence — Python
+    regex forbids duplicate group names, and there's no meaningful way to prefer one occurrence
+    over another for parsing anyway.
+    """
+    parts: list[str] = []
+    seen: set[str] = set()
+    i = 0
+    while i < len(fmt):
+        char = fmt[i]
+        if char != "%":
+            parts.append(re.escape(char))
+            i += 1
+            continue
+        if i + 1 >= len(fmt):
+            raise ValueError(f"appkit.dates.parse_jalali: dangling '%' at end of format {fmt!r}")
+        directive = fmt[i + 1]
+        if directive == "%":
+            parts.append(re.escape("%"))
+        elif directive in _DIRECTIVE_REGEX:
+            body = _DIRECTIVE_REGEX[directive]
+            parts.append(f"(?:{body})" if directive in seen else f"(?P<{directive}>{body})")
+            seen.add(directive)
+        else:
+            raise ValueError(
+                f"appkit.dates.parse_jalali: unsupported format directive '%{directive}' in {fmt!r}"
+            )
+        i += 2
+    return re.compile("".join(parts))
+
+
+def parse_jalali(value: str, fmt: str = "%Y/%m/%d") -> dt.date:
+    """The inverse of `format_jalali`.
+
+    Runs `to_english_digits` internally first — Persian-keyboard input is the common real-world
+    case for a date typed by a user, not pasted. Raises `ValueError` for a string that doesn't
+    match `fmt`, or that names an invalid Jalali date — never returns a best-guess/partial
+    result. A directive omitted from `fmt` (e.g. `fmt="%Y"` alone) defaults to `1` for month/day.
+    """
+    pattern = _compile_format(fmt)
+    match = pattern.fullmatch(to_english_digits(value))
+    if match is None:
+        raise ValueError(f"appkit.dates.parse_jalali: {value!r} does not match format {fmt!r}")
+
+    groups = match.groupdict()
+    year = int(groups["Y"]) if groups.get("Y") is not None else 1
+    month = int(groups["m"]) if groups.get("m") is not None else 1
+    day = int(groups["d"]) if groups.get("d") is not None else 1
+    return from_jalali(year, month, day)  # raises ValueError for an invalid Jalali date

appkit/exceptions.py

@@ -0,0 +1,158 @@
+"""The single DRF exception handler producing the standard error envelope.
+
+Envelope shape, verbatim (docs/CONTRACT.md §1)::
+
+    {"error": {"code": "validation_error", "message": "...", "details": {}, "request_id": "..."}}
+
+``details`` is always present (``{}`` when nothing is field-level). ``request_id`` is the same
+correlation ID :data:`appkit.request_id.request_id_var` carries. Headers DRF already sets
+(``Retry-After`` on ``throttled``, ``WWW-Authenticate`` on ``not_authenticated``/
+``authentication_failed``) are untouched — the handler only ever rewrites ``response.data``.
+
+The code set is TEN, not nine (docs/CONTRACT.md §1's documented drift correction) — ``"error"``
+is the documented catch-all for any ``APIException`` DRF resolved to a response but that isn't
+one of the other nine specific types. For ``"error"``, the HTTP status is authoritative, not the
+code.
+
+Public surface, implemented in a later phase:
+
+    ERROR_CODES: Final[tuple[str, ...]]
+        The ten codes, in this exact order:
+        validation_error, parse_error, not_authenticated, authentication_failed,
+        permission_denied, not_found, method_not_allowed, throttled, server_error, error.
+        Pinned against tests/fixtures/error-codes.json (docs/CONTRACT.md §19), not hand-verified
+        against the frontend's ApiErrorCode union directly.
+
+    standard_exception_handler(exc: Exception, context: dict[str, Any]) -> Response | None
+        A plain Django Http404/PermissionDenied is converted to its DRF equivalent before code
+        lookup. An unhandled exception (DRF's handler returns None) is logged via
+        logger.exception before being turned into a server_error envelope. Three own
+        user-facing strings — "Validation failed.", "Request failed.", "Internal server
+        error." — are wrapped in gettext_lazy.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Final
+
+from django.conf import settings
+from django.core.exceptions import PermissionDenied as DjangoPermissionDenied
+from django.http import Http404
+from django.utils.translation import gettext_lazy as _
+from rest_framework import exceptions as drf_exceptions
+from rest_framework.response import Response
+from rest_framework.views import exception_handler as drf_exception_handler
+
+from appkit.request_id import request_id_var
+
+__all__ = ["ERROR_CODES", "standard_exception_handler"]
+
+logger = logging.getLogger(__name__)
+
+#: The ten codes, in the exact order given in docs/CONTRACT.md §1 — pinned against
+#: tests/fixtures/error-codes.json rather than hand-verified against the frontend's
+#: ApiErrorCode union directly (docs/CONTRACT.md §19).
+ERROR_CODES: Final[tuple[str, ...]] = (
+    "validation_error",
+    "parse_error",
+    "not_authenticated",
+    "authentication_failed",
+    "permission_denied",
+    "not_found",
+    "method_not_allowed",
+    "throttled",
+    "server_error",
+    "error",
+)
+
+# Ordered most-specific-first: several of these subclass one another, so isinstance order
+# matters — this is a straight port of the scaffold's list (docs/CONTRACT.md §1, §2.3).
+_CODE_BY_EXCEPTION: list[tuple[type[Exception], str]] = [
+    (drf_exceptions.ValidationError, "validation_error"),
+    (drf_exceptions.ParseError, "parse_error"),
+    (drf_exceptions.NotAuthenticated, "not_authenticated"),
+    (drf_exceptions.AuthenticationFailed, "authentication_failed"),
+    (drf_exceptions.PermissionDenied, "permission_denied"),
+    (drf_exceptions.NotFound, "not_found"),
+    (drf_exceptions.MethodNotAllowed, "method_not_allowed"),
+    (drf_exceptions.Throttled, "throttled"),
+]
+
+
+def _code_for(exc: Exception) -> str:
+    for exc_type, code in _CODE_BY_EXCEPTION:
+        if isinstance(exc, exc_type):
+            return code
+    return "error"  # the documented catch-all — some other APIException DRF already resolved
+
+
+def _message_and_details(data: Any, *, code: str) -> tuple[str, dict[str, Any]]:
+    """Splits DRF's raw `response.data` into a flat message plus a details dict.
+
+    A nested per-field dict (a serializer's validation errors) is passed through as `details`
+    intact — the naive flat-message collapse used below must not fire for this case, or which
+    field each message belongs to is lost.
+    """
+    if isinstance(data, dict) and set(data) == {"detail"}:
+        return str(data["detail"]), {}
+    if isinstance(data, list):
+        return "; ".join(str(item) for item in data), {"non_field_errors": data}
+    if isinstance(data, dict):
+        message = (
+            str(_("Validation failed."))
+            if code == "validation_error"
+            else str(_("Request failed."))
+        )
+        return message, data
+    return str(data), {}
+
+
+def standard_exception_handler(exc: Exception, context: dict[str, Any]) -> Response | None:
+    """DRF `EXCEPTION_HANDLER` producing the envelope described in this module's docstring.
+
+    Delegates to DRF's own `exception_handler` first and rewrites only `response.data` —
+    never rebuilds the `Response` from scratch — so headers DRF already set (`Retry-After`
+    on a throttled response, `WWW-Authenticate` on a 401) survive untouched.
+    """
+    # DRF's own exception_handler converts a plain Django Http404/PermissionDenied into its
+    # DRF equivalent internally, on a *new* exception object it builds and discards — it never
+    # hands that conversion back to us. Without redoing it here, _code_for(exc) below would see
+    # the original Http404/PermissionDenied, match nothing, and fall through to "error".
+    if isinstance(exc, Http404):
+        exc = drf_exceptions.NotFound(*exc.args)
+    elif isinstance(exc, DjangoPermissionDenied):
+        exc = drf_exceptions.PermissionDenied(*exc.args)
+
+    response = drf_exception_handler(exc, context)
+
+    if response is None:
+        # DRF returns None for anything that isn't an APIException/Http404/PermissionDenied —
+        # a genuinely unhandled exception. That would otherwise propagate to Django's own error
+        # handling (which is what triggers `django.request` logging and Sentry capture) —
+        # returning a 500 envelope here instead swallows that unless we log explicitly first.
+        logger.exception("Unhandled exception in view", exc_info=exc)
+        message = str(exc) if settings.DEBUG else str(_("Internal server error."))
+        return Response(
+            {
+                "error": {
+                    "code": "server_error",
+                    "message": message,
+                    "details": {},
+                    "request_id": request_id_var.get(),
+                }
+            },
+            status=500,
+        )
+
+    code = _code_for(exc)
+    message, details = _message_and_details(response.data, code=code)
+    response.data = {
+        "error": {
+            "code": code,
+            "message": message,
+            "details": details,
+            "request_id": request_id_var.get(),
+        }
+    }
+    return response