django-common-kit 0.11.0__py3-none-any.whl

django_common_kit/__init__.py

@@ -0,0 +1,37 @@
+"""django-common-kit — the shared Django foundation.
+
+The foundation a Django REST backend starts from: a UUID ``BaseModel``,
+a change-history trail, a parameter table with a cache in front of it, request
+and IP tracking, a generic file attachment, and one REST response envelope.
+
+The dividing line is vocabulary: **if it has no business meaning, this package
+owns it; the moment it names a lead, a job, an order, a crew or a role, it does
+not.** A scope helper that filters by crew membership, a status enum for quotes,
+an email template — all project, however much they currently sit in ``common/``.
+
+See PRD.md §2 for the boundary in full.
+"""
+
+__version__ = "0.11.0"
+
+default_app_config = "django_common_kit.apps.CommonKitConfig"
+
+#: Attribute name -> module it lives in. Both are imported lazily so that
+#: ``import django_common_kit`` does not pull models in before the app registry is
+#: ready — the package is imported by ``INSTALLED_APPS`` itself.
+_LAZY_EXPORTS = {
+    "ApiResponse": "django_common_kit.api.response",
+    "BaseModel": "django_common_kit.models",
+    "ParameterCache": "django_common_kit.parameters.cache",
+}
+
+
+def __getattr__(name):
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = __import__(module_path, fromlist=[name])
+    return getattr(module, name)
+
+
+__all__ = ["ApiResponse", "BaseModel", "ParameterCache", "__version__"]

django_common_kit/admin.py

@@ -0,0 +1,187 @@
+"""Admin for the package's own tables (PRD §12).
+
+Registered here, unconditionally. A project that wants a different admin for
+either model unregisters and re-registers in its own ``admin.py``; that is the
+Django idiom and it is cheaper than a setting.
+"""
+
+from django.contrib import admin
+
+from django_common_kit.models import ModelHistory, ParameterModel
+
+
+def _secret_column(field):
+    """A changelist column for an encrypted field: the masked secret, and a
+    word instead of an error for a row no key opens (§17.6)."""
+    from django_common_kit.crypto.keys import DecryptionError, EncryptionNotConfigured, mask
+
+    def column(obj):
+        try:
+            value = getattr(obj, field.attname)
+        except (DecryptionError, EncryptionNotConfigured):
+            return "(unreadable)"
+        return mask(value) or "-"
+
+    column.short_description = field.verbose_name
+    column.__name__ = f"{field.name}_masked"
+    return column
+
+
+class BaseModelAdmin(admin.ModelAdmin):
+    """Audit columns read-only, soft-deleted rows filterable, actor stamped.
+
+    The base for a project's admin classes, so ``readonly_fields`` is declared
+    once and ``created_by`` is never forgotten. An encrypted field named in
+    ``list_display`` shows its mask, never the secret.
+    """
+
+    readonly_fields = ("id", "created_at", "updated_at", "created_by", "updated_by")
+    list_filter = ("is_active", "is_deleted")
+
+    def get_list_display(self, request):
+        from django_common_kit.crypto.fields import encrypted_fields
+
+        secrets = {field.name: field for field in encrypted_fields(self.model)}
+        return [
+            _secret_column(secrets[name]) if isinstance(name, str) and name in secrets else name
+            for name in super().get_list_display(request)
+        ]
+
+    def save_model(self, request, obj, form, change):
+        if not change and hasattr(obj, "created_by_id") and obj.created_by_id is None:
+            obj.created_by = request.user
+        if hasattr(obj, "updated_by_id"):
+            obj.updated_by = request.user
+        super().save_model(request, obj, form, change)
+
+
+@admin.register(ParameterModel)
+class ParameterAdmin(BaseModelAdmin):
+    list_display = ("key", "parameter_type", "value", "category", "is_system", "is_active")
+    list_filter = ("parameter_type", "category", "is_system", "is_active")
+    search_fields = ("key", "description", "category")
+    ordering = ("category", "key")
+    fieldsets = (
+        (None, {"fields": ("key", "parameter_type", "category", "description", "is_system")}),
+        ("Value", {"fields": ("value_text", "value_integer", "value_float", "value_boolean", "value_json")}),
+        ("Status", {"fields": ("is_active", "is_deleted")}),
+        ("Audit", {"fields": ("id", "created_at", "created_by", "updated_at", "updated_by")}),
+    )
+
+
+@admin.register(ModelHistory)
+class ModelHistoryAdmin(BaseModelAdmin):
+    """Read-only. A trail that can be edited is not a trail."""
+
+    list_display = ("created_at", "content_type", "object_id", "action", "changed_by", "ip_address")
+    list_filter = ("action", "content_type")
+    search_fields = ("object_id", "change_reason", "changed_by__email")
+    date_hierarchy = "created_at"
+    readonly_fields = tuple(
+        field.name for field in ModelHistory._meta.get_fields() if hasattr(field, "column")
+    )
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+
+from django_common_kit.models import (  # noqa: E402
+    BlockedIPModel,
+    CommonFileModel,
+    ContactUsModel,
+    IPTrackingModel,
+    PlatformNoticeDismissalModel,
+    PlatformNoticeModel,
+    RequestLog,
+    ShortLinkModel,
+    StatusTransitionModel,
+)
+
+
+class ReadOnlyAdmin(BaseModelAdmin):
+    """Telemetry is read, never edited."""
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(RequestLog)
+class RequestLogAdmin(ReadOnlyAdmin):
+    list_display = ("created_at", "method", "endpoint", "status_code", "user", "ip_address", "response_time")
+    list_filter = ("method", "status_code")
+    search_fields = ("endpoint", "trace_id", "ip_address", "user__email")
+    date_hierarchy = "created_at"
+
+
+@admin.register(IPTrackingModel)
+class IPTrackingAdmin(ReadOnlyAdmin):
+    list_display = ("created_at", "ip_address", "endpoint", "country", "city", "device_type", "browser")
+    list_filter = ("country", "device_type", "is_mobile")
+    search_fields = ("ip_address", "endpoint", "city", "isp")
+    date_hierarchy = "created_at"
+
+
+@admin.register(BlockedIPModel)
+class BlockedIPAdmin(BaseModelAdmin):
+    """Editable: unticking ``is_active`` here is how an operator lifts a ban,
+    and the blocker re-reads the table every TTL so it takes effect without a
+    deploy."""
+
+    list_display = ("ip_address", "is_active", "attempts", "reason", "first_attempt", "last_attempt", "blocked_at")
+    list_filter = ("is_active",)
+    search_fields = ("ip_address", "reason")
+    readonly_fields = BaseModelAdmin.readonly_fields + ("first_attempt", "last_attempt")
+
+
+@admin.register(ContactUsModel)
+class ContactUsAdmin(BaseModelAdmin):
+    list_display = ("created_at", "name", "email", "subject", "is_checked")
+    list_filter = ("is_checked",)
+    search_fields = ("name", "email", "subject", "message")
+
+
+@admin.register(StatusTransitionModel)
+class StatusTransitionAdmin(ReadOnlyAdmin):
+    list_display = ("timestamp", "content_type", "object_id", "previous_status", "new_status", "transition_source", "changed_by")
+    list_filter = ("transition_source", "content_type", "new_status")
+    search_fields = ("object_id", "transition_reason", "notes")
+    date_hierarchy = "timestamp"
+
+
+@admin.register(CommonFileModel)
+class CommonFileAdmin(BaseModelAdmin):
+    list_display = ("created_at", "title", "original_filename", "tag", "mime_type", "file_size", "uploaded_by")
+    list_filter = ("tag", "mime_type")
+    search_fields = ("title", "original_filename", "description")
+
+
+@admin.register(ShortLinkModel)
+class ShortLinkAdmin(BaseModelAdmin):
+    list_display = ("slug", "target_url", "purpose", "click_count", "last_clicked_at", "expires_at", "is_active")
+    list_filter = ("purpose", "is_active")
+    search_fields = ("slug", "target_url")
+    readonly_fields = BaseModelAdmin.readonly_fields + ("click_count", "last_clicked_at")
+
+
+@admin.register(PlatformNoticeModel)
+class PlatformNoticeAdmin(BaseModelAdmin):
+    """Leave ``tenant_id`` empty for a notice every tenant sees."""
+
+    list_display = ("title", "severity", "audience", "surface", "starts_at", "ends_at", "priority", "is_dismissible", "is_active")
+    list_filter = ("severity", "audience", "surface", "is_dismissible", "is_active", "is_deleted")
+    search_fields = ("title", "body")
+
+
+@admin.register(PlatformNoticeDismissalModel)
+class PlatformNoticeDismissalAdmin(ReadOnlyAdmin):
+    """Deleting a row here shows the notice to that user again."""
+
+    list_display = ("created_at", "notice", "user")
+    search_fields = ("notice__title",)
+    date_hierarchy = "created_at"

django_common_kit/api/__init__.py

@@ -0,0 +1,6 @@
+"""The REST surface (PRD §5).
+
+Nothing in here is imported at package import time — ``django_common_kit.api`` is a
+namespace, and pulling ``response`` in from this module would drag DRF's settings
+machinery into ``INSTALLED_APPS`` evaluation. Import the module you want.
+"""

django_common_kit/api/errors.py

@@ -0,0 +1,190 @@
+"""Turning a validation failure into something a person can read (PRD §5.3).
+
+DRF hands you ``serializer.errors``: nested dicts, lists, integer keys from
+``ListField`` children, ``__all__`` for model-level constraints. This flattener
+has met all of those shapes.
+
+Two functions, two jobs, and they are not the same job:
+
+- ``normalize_field_errors`` produces the ``errors`` payload: ``{field: message}``
+  so a frontend can attach each message to its input.
+- ``extract_first_error_message`` produces the top-level ``message``: one
+  sentence naming the field, because "Validation failed" tells a user nothing.
+"""
+
+import logging
+from typing import Any, Dict
+
+from django.http import Http404
+from rest_framework.exceptions import APIException
+from rest_framework.settings import api_settings
+
+logger = logging.getLogger(__name__)
+
+_FALLBACK = "Validation failed"
+
+
+def reraise_handled(exc: Exception) -> None:
+    """Re-raise exceptions the exception handler already renders correctly.
+
+    A view's broad ``except Exception`` block otherwise flattens a 404 or a
+    throttle into a generic 400. Covers ``Http404`` (from ``get_object()``), DRF
+    ``NotFound`` — raised by the paginator for an out-of-range page, and an
+    ``APIException``, *not* an ``Http404`` — and every other DRF exception type.
+
+    Call it as the first statement of the ``except Exception`` block::
+
+        except Exception as exc:
+            reraise_handled(exc)
+            logger.error(...)
+            return ApiResponse.bad_request(...)
+    """
+    if isinstance(exc, (Http404, APIException)):
+        raise exc
+
+
+def _humanise(field_name: str) -> str:
+    return field_name.replace("_", " ").title()
+
+
+def _is_authored_prose(message: str) -> bool:
+    """True for a message written as sentences rather than a one-line field check.
+
+    A validator that raises "Quotes cannot be accepted after the expiry date.
+    Ask the customer to request a new one."
+    should not come back as "Expires At: Quotes cannot be accepted…" — the
+    author already wrote a whole message and naming the field on the front of it
+    makes it read like a bug.
+    """
+    body = message.strip()
+    return ". " in body or "\n" in body
+
+
+def extract_first_error_message(error_detail: Any) -> str:
+    """The first error, as one sentence naming its field.
+
+    Used as the envelope's top-level ``message``. Recurses into nested details
+    and keeps the field name unless the message already carries it, so a caller
+    never gets "Start Time: Start time is required."
+    """
+    if not error_detail:
+        return _FALLBACK
+
+    if isinstance(error_detail, str):
+        return error_detail
+
+    if isinstance(error_detail, (list, tuple)):
+        entry = _first_failure(error_detail)
+        if entry is None:
+            return _FALLBACK
+        if isinstance(entry, (dict, list, tuple)):
+            return extract_first_error_message(entry)
+        return str(entry)
+
+    if isinstance(error_detail, dict):
+        if not error_detail:
+            return _FALLBACK
+
+        first_field = next(iter(error_detail))
+        first_field_errors = error_detail[first_field]
+        # ListField / ManyRelated child errors are keyed by *index* (an int),
+        # e.g. {"to": {0: ["Enter a valid email address."]}} — coerce so the
+        # string handling below cannot crash the handler into a 500.
+        field_name = str(first_field)
+
+        # __all__ is Django's non-field key (unique_together, clean()). There is
+        # no field to name, so the message stands alone.
+        if field_name == "__all__":
+            if isinstance(first_field_errors, (list, tuple)) and first_field_errors:
+                return str(first_field_errors[0])
+            if isinstance(first_field_errors, str):
+                return first_field_errors
+
+        if isinstance(first_field_errors, dict):
+            nested = extract_first_error_message(first_field_errors)
+            if field_name.lower() not in nested.lower():
+                return f"{_humanise(field_name)}: {nested}"
+            return nested
+
+        if isinstance(first_field_errors, (list, tuple)) and _is_structured(first_field_errors):
+            nested = extract_first_error_message(first_field_errors)
+            if field_name.lower() not in nested.lower():
+                return f"{_humanise(field_name)}: {nested}"
+            return nested
+
+        if isinstance(first_field_errors, (list, tuple)):
+            if not first_field_errors:
+                return f"Field '{field_name}' has validation errors"
+            message = str(first_field_errors[0])
+            if "is required" in message:
+                return f"{_humanise(field_name)} is required."
+            if field_name.replace("_", " ").lower() in message.lower():
+                return message
+            if _is_authored_prose(message):
+                return message
+            return f"{_humanise(field_name)}: {message}"
+
+        message = str(first_field_errors)
+        if "is required" in message:
+            return f"{_humanise(field_name)} is required."
+        return message
+
+    return str(error_detail)
+
+
+def normalize_field_errors(error_detail: Any) -> Dict[str, str]:
+    """Flatten a validation detail into ``{field: message}``.
+
+    - a list of messages collapses to its first message
+    - nested dicts flatten with dotted keys (``"address.postcode"``)
+    - a list of nested details — what a ``many=True`` child or a root
+      ``ListSerializer`` raises, one entry per item and ``{}`` for each item
+      that passed — flattens with the item's index (``"areas.1.city"``), the
+      same path a frontend walks to find the input
+    - a bare string or list is keyed under DRF's ``NON_FIELD_ERRORS_KEY``
+
+    Read through ``api_settings`` rather than captured at import: a project that
+    sets ``NON_FIELD_ERRORS_KEY`` in ``REST_FRAMEWORK`` gets its key, and a test
+    that overrides it is not served a stale one.
+    """
+    result: Dict[str, str] = {}
+    _flatten(error_detail, "", result)
+    return result
+
+
+def _is_structured(value) -> bool:
+    """True for a list that holds per-item details rather than messages."""
+    return any(isinstance(entry, (dict, list, tuple)) for entry in value)
+
+
+def _first_failure(entries):
+    """The first entry that carries an error; ``{}`` marks an item that passed."""
+    for entry in entries:
+        if entry or entry == 0:
+            return entry
+    return None
+
+
+def _flatten(value: Any, path: str, result: Dict[str, str]) -> None:
+    if isinstance(value, dict):
+        for key, inner in value.items():
+            _flatten(inner, f"{path}.{key}" if path else str(key), result)
+        return
+
+    key = path or api_settings.NON_FIELD_ERRORS_KEY
+
+    if isinstance(value, (list, tuple)):
+        if _is_structured(value):
+            for index, entry in enumerate(value):
+                if isinstance(entry, (dict, list, tuple)):
+                    _flatten(entry, f"{path}.{index}" if path else str(index), result)
+                elif entry:
+                    result.setdefault(key, str(entry))
+        elif value:
+            result[key] = str(value[0])
+        elif path:
+            result[key] = "Invalid value."
+        return
+
+    if value or path:
+        result[key] = str(value)

django_common_kit/api/exceptions.py

@@ -0,0 +1,192 @@
+"""The DRF exception handler and the package's own exception types (PRD §5.3).
+
+Every error leaving a view renders into the envelope, including the ones that
+are easy to forget: ``Http404``, ``PermissionDenied``,
+``ValidationError`` with its field errors preserved, ``Throttled`` with its wait,
+and ``IntegrityError`` with the offending column named.
+
+Install it::
+
+    REST_FRAMEWORK = {
+        "EXCEPTION_HANDLER": "django_common_kit.api.exceptions.custom_exception_handler",
+    }
+"""
+
+import logging
+import re
+from typing import Any, Dict
+
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.db import IntegrityError
+from rest_framework import serializers
+from rest_framework.exceptions import PermissionDenied, Throttled
+from rest_framework.exceptions import ValidationError as DRFValidationError
+from rest_framework.views import exception_handler as drf_exception_handler
+
+from django_common_kit.api.errors import (  # noqa: F401  (re-exported)
+    extract_first_error_message,
+    normalize_field_errors,
+    reraise_handled,
+)
+from django_common_kit.api.response import ApiResponse
+
+logger = logging.getLogger(__name__)
+
+
+# -- the package's own exception types --------------------------------------
+# Deliberately plain ``Exception`` subclasses, not ``APIException``. They are
+# raised by service-layer code that has no business importing DRF, and the
+# handler below is what gives them a status code.
+
+class BusinessLogicException(Exception):
+    """A rule the domain enforces was broken. Rendered as 400."""
+
+
+class ValidationException(Exception):
+    """A validation failure raised outside a serializer. Rendered as 400."""
+
+
+class ResourceNotFoundException(Exception):
+    """Rendered as 404. Distinct from ``Http404`` so a service can raise it
+    without importing ``django.http``."""
+
+
+class PermissionDeniedException(Exception):
+    """Rendered as 403."""
+
+
+_LOCAL_EXCEPTION_STATUS = {
+    BusinessLogicException: 400,
+    ValidationException: 400,
+    ResourceNotFoundException: 404,
+    PermissionDeniedException: 403,
+}
+
+#: Headers DRF derives from the exception itself, which the envelope must carry
+#: through: ``Retry-After`` says how long a 429'd client should back off, and
+#: ``WWW-Authenticate`` is the 401 challenge. Every other header on DRF's
+#: response is renderer-owned (Content-Type and friends) and is regenerated when
+#: this handler builds its own Response, so only these two are copied.
+EXCEPTION_HEADERS = ("Retry-After", "WWW-Authenticate")
+
+
+def passthrough_exception_headers(response: Any) -> Dict[str, str]:
+    """Pull the exception-derived headers off DRF's response so that rebuilding
+    the body as an envelope does not drop them."""
+    headers = getattr(response, "headers", None) or {}
+    return {name: headers[name] for name in EXCEPTION_HEADERS if name in headers}
+
+
+def log_throttled(exc: Throttled, context: Dict[str, Any]) -> None:
+    """Record the request a throttle just rejected, so 429s are not invisible.
+
+    ``Throttled`` carries only ``wait`` — not the scope, the rate, or the key it
+    was counted against — so this pairs with ``LoggedThrottleFailureMixin`` in
+    ``django_common_kit.api.throttling``, which logs that half from inside the
+    throttle. Together they answer both halves of "we keep getting rate limited":
+    which budget ran out, and which endpoint and caller drained it.
+
+    Best-effort and never raises: a failure here must not turn a 429 into a 500.
+    """
+    try:
+        request = context.get("request")
+        view = context.get("view")
+        user = getattr(request, "user", None)
+        logger.warning(
+            "[throttling] 429 %s %s view=%s user=%s retry_after=%ss",
+            getattr(request, "method", "?"),
+            getattr(request, "path", "?"),
+            type(view).__name__ if view is not None else "?",
+            getattr(user, "pk", None) if getattr(user, "is_authenticated", False) else "anonymous",
+            int(exc.wait or 0),
+        )
+    except Exception as exc_logging:  # noqa: BLE001 - logging must never break the response
+        logger.warning("[throttling] 429 (could not describe request): %s", exc_logging)
+
+
+def handle_validation_error(exc, context) -> Any:
+    """Render any flavour of validation error as one consistent response:
+    a readable top-level ``message`` plus per-field ``{field: message}``."""
+    logger.warning("Validation failed: %s", type(exc).__name__, exc_info=True)
+
+    # DRFValidationError and serializers.ValidationError are the same class,
+    # both exposing ``.detail``. Django's has ``message_dict`` only when the
+    # error was raised against fields.
+    if isinstance(exc, DjangoValidationError):
+        detail = exc.message_dict if hasattr(exc, "message_dict") else exc.messages
+    else:
+        detail = getattr(exc, "detail", None)
+
+    return ApiResponse.validation_error(errors=detail)
+
+
+def custom_exception_handler(exc: Exception, context: Dict[str, Any]):
+    """Centralised exception handler for every API error."""
+    # Validation errors are handled *before* DRF's handler. DRF renders them as
+    # a bare detail dict, which loses the readable top-level message.
+    if isinstance(exc, (DRFValidationError, DjangoValidationError, serializers.ValidationError)):
+        return handle_validation_error(exc, context)
+
+    for exc_type, status_code in _LOCAL_EXCEPTION_STATUS.items():
+        if isinstance(exc, exc_type):
+            logger.info("%s: %s", type(exc).__name__, exc)
+            return ApiResponse.error(message=str(exc) or None, status_code=status_code)
+
+    if isinstance(exc, Throttled):
+        log_throttled(exc, context)
+
+    response = drf_exception_handler(exc, context)
+
+    if response is not None:
+        if hasattr(exc, "detail"):
+            detail = exc.detail
+            # PermissionDenied with a dict detail (code + message): prefer the
+            # message for display but return the whole thing, because a frontend
+            # that branches on the code needs the code.
+            if isinstance(exc, PermissionDenied) and isinstance(detail, dict) and "message" in detail:
+                error_message = detail["message"]
+                errors = detail
+            else:
+                error_message = extract_first_error_message(detail)
+                errors = None
+        else:
+            error_message = str(exc)
+            errors = None
+
+        # ``Retry-After`` only reaches a browser client if CORS exposes it, so
+        # the wait is mirrored into ``meta.retry_after`` — clients read the
+        # header first and fall back to this.
+        meta = None
+        if isinstance(exc, Throttled) and exc.wait is not None:
+            meta = {"retry_after": int(exc.wait)}
+
+        return ApiResponse.error(
+            message=error_message,
+            status_code=response.status_code,
+            errors=errors,
+            meta=meta,
+            headers=passthrough_exception_headers(response),
+        )
+
+    if isinstance(exc, IntegrityError):
+        logger.error("Database integrity error", exc_info=True)
+        # Postgres spells a unique violation as
+        # ``Key (email)=(a@b.com) already exists``. Naming the column turns an
+        # opaque 400 into something a form can highlight. The value itself is
+        # deliberately not echoed back.
+        match = re.search(r"Key \((.*?)\)=\((.*?)\)", str(exc))
+        if match:
+            field, _value = match.groups()
+            return ApiResponse.bad_request(
+                message=f"A record with this {field} already exists."
+            )
+        return ApiResponse.bad_request(message="A data integrity error occurred.")
+
+    logger.critical("Unhandled server error: %s", type(exc).__name__, exc_info=True)
+    return ApiResponse.server_error()
+
+
+def format_serializer_errors(serializer_errors: Dict[str, Any]) -> str:
+    """The first error message from ``serializer.errors``, for a view that
+    validates by hand rather than with ``raise_exception=True``."""
+    return extract_first_error_message(serializer_errors)