django-admin-react 0.1.0a1__py3-none-any.whl

django_admin_react/api/views/README.md

@@ -0,0 +1,21 @@
+# django_admin_react/api/views/
+
+One module per endpoint, mirroring [`/docs/api-contract.md`](../../../docs/api-contract.md).
+
+| Module         | Endpoint                                          | Lands in PR |
+| -------------- | ------------------------------------------------- | ----------- |
+| `registry.py`  | `GET    /api/v1/registry/`                        | #3          |
+| `list.py`      | `GET    /api/v1/<app>/<model>/`                   | #4          |
+| `detail.py`    | `GET    /api/v1/<app>/<model>/<pk>/`              | #4          |
+| `create.py`    | `POST   /api/v1/<app>/<model>/`                   | #5          |
+| `update.py`    | `PATCH  /api/v1/<app>/<model>/<pk>/`              | #5          |
+| `delete.py`    | `DELETE /api/v1/<app>/<model>/<pk>/`              | #5          |
+
+Each view must:
+
+1. Authenticate via the package's default permission helper
+   (staff + `AdminSite.has_permission`).
+2. Resolve the target `ModelAdmin` via `admin.site._registry`.
+3. Delegate to the appropriate `ModelAdmin.*` method (see
+   `ARCHITECTURE.md` §4.1).
+4. Serialize through `api/serializers.py` only.

django_admin_react/api/views/__init__.py

@@ -0,0 +1,6 @@
+"""API view modules.
+
+One file per endpoint group. See ``docs/api-contract.md`` for the wire
+contracts and ``ARCHITECTURE.md`` §4.1 for the ModelAdmin methods each
+view must delegate to.
+"""

django_admin_react/api/views/create.py

@@ -0,0 +1,141 @@
+"""``POST /api/v1/<app>/<model>/`` — create endpoint.
+
+Wire contract: ``docs/api-contract.md`` §5.1.
+
+Hard rules (`SECURITY.md` §3, `ACCEPTANCE.md` §3.1):
+
+- Rule 1:  Staff + ``AdminSite.has_permission`` gate.
+- Rule 3:  Model resolved through ``admin.site._registry`` (B-7).
+- Rule 6:  Writes go through ``ModelAdmin.get_form()`` then
+           ``save_model(..., change=False)`` (B-3).
+- Rule 12: Unknown / readonly / excluded / sensitive payload keys → 400,
+           never a silent drop.
+- CSRF:    No ``@csrf_exempt`` — Django's middleware enforces.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db import transaction
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django.http import JsonResponse
+from django.views.generic import View
+
+from django_admin_react.api.permissions import forbidden_response
+from django_admin_react.api.permissions import is_admin_user
+from django_admin_react.api.registry import get_admin_site
+from django_admin_react.api.registry import resolve_model
+from django_admin_react.api.serializers import label_for
+from django_admin_react.api.writes import coerce_fk_values
+from django_admin_react.api.writes import form_errors_to_envelope
+from django_admin_react.api.writes import not_found_response
+from django_admin_react.api.writes import parse_json_body
+from django_admin_react.api.writes import readonly_or_excluded_names
+from django_admin_react.api.writes import reject_forbidden_keys
+from django_admin_react.api.writes import validation_failed
+from django_admin_react.api.writes import writable_field_names
+
+
+class CreateView(View):
+    """``POST /api/v1/<app_label>/<model_name>/``."""
+
+    http_method_names = ["post"]
+
+    def post(
+        self,
+        request: HttpRequest,
+        app_label: str,
+        model_name: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> HttpResponse:
+        """Create a new instance (contract §5.1).
+
+        Gates: ``is_admin_user`` → ``resolve_model`` →
+        ``has_add_permission(request)``. CSRF enforcement is Django's
+        ``CsrfViewMiddleware`` — no ``@csrf_exempt`` (rule 4 /
+        ACCEPTANCE §4.6 S-26).
+
+        Payload validation runs **before** the form is built:
+
+        - Unknown keys → 400 ``bad_request``.
+        - Keys matching ``get_readonly_fields`` or ``get_exclude`` →
+          400 (rule 12 / S-22, S-23).
+        - Keys matching the sensitive-name denylist → 400 (S-31).
+
+        The actual write goes through ``ModelAdmin.get_form()`` →
+        ``form.save(commit=False)`` → ``model_admin.save_model(...)``
+        — never ``setattr`` (rule 6 / B-3). Wrapped in
+        ``transaction.atomic()``.
+        """
+        admin_site = get_admin_site()
+        if not is_admin_user(request, admin_site=admin_site):
+            return forbidden_response()
+
+        resolved = resolve_model(admin_site, request, app_label, model_name)
+        if resolved is None:
+            return not_found_response()
+        model, model_admin = resolved
+
+        if not model_admin.has_add_permission(request):
+            return forbidden_response()
+
+        parsed = parse_json_body(request)
+        if isinstance(parsed, HttpResponse):
+            return parsed
+        payload: dict[str, Any] = parsed
+
+        writable = writable_field_names(model, model_admin, request, obj=None)
+        forbidden = readonly_or_excluded_names(model_admin, request, obj=None)
+        rejection = reject_forbidden_keys(payload, writable, forbidden)
+        if rejection is not None:
+            return rejection
+
+        form = model_admin.get_form(request, obj=None)(
+            data=coerce_fk_values(payload, model),
+            files=None,
+        )
+        if not form.is_valid():
+            return validation_failed(form_errors_to_envelope(form))
+
+        with transaction.atomic():
+            instance = form.save(commit=False)
+            model_admin.save_model(request, instance, form, change=False)
+            form.save_m2m()
+
+        body = {
+            "pk": instance.pk,
+            "label": label_for(instance),
+            "redirect": _redirect_for(
+                request,
+                model._meta.app_label,
+                model._meta.model_name,
+                instance.pk,
+            ),
+        }
+        response = JsonResponse(body, status=201)
+        response["Cache-Control"] = "no-store"
+        return response
+
+
+def _redirect_for(
+    request: HttpRequest,
+    app_label: str,
+    model_name: str,
+    pk: Any,
+) -> str:
+    """Construct a SPA-relative redirect (``<mount>/<app>/<model>/<pk>/``).
+
+    The mount is reconstructed from the request path. The URL pattern
+    is fixed inside this package, so everything in front of
+    ``api/v1/`` is the consumer-chosen prefix
+    (``ARCHITECTURE.md`` §4.5). Falls back to ``/`` if the pattern is
+    not present (should not happen — the URL router routed us here).
+    """
+    suffix = "api/v1/"
+    path = request.path
+    idx = path.rfind(suffix)
+    mount = path[:idx] if idx != -1 else "/"
+    return f"{mount}{app_label}/{model_name}/{pk}/"

django_admin_react/api/views/destroy.py

@@ -0,0 +1,89 @@
+"""``DELETE /api/v1/<app>/<model>/<pk>/`` — destroy endpoint.
+
+Wire contract: ``docs/api-contract.md`` §5.3.
+
+Hard rules (`SECURITY.md` §3, `ACCEPTANCE.md` §3.1):
+
+- Rule 3:  Model resolved through ``admin.site._registry`` (B-7).
+- Rule 5:  ``has_delete_permission(request, obj)`` per-object gate.
+- Rule 7:  Calls ``ModelAdmin.delete_model(request, obj)`` — **never**
+           ``obj.delete()`` directly (B-4).
+- Rule 10: Queryset starts at ``ModelAdmin.get_queryset(request)`` —
+           never ``Model.objects.all()`` (B-2).
+- CSRF:    No ``@csrf_exempt`` — Django's middleware enforces.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db import transaction
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django.views.generic import View
+
+from django_admin_react.api.permissions import forbidden_response
+from django_admin_react.api.permissions import is_admin_user
+from django_admin_react.api.registry import get_admin_site
+from django_admin_react.api.registry import resolve_model
+from django_admin_react.api.writes import load_object_or_none
+from django_admin_react.api.writes import not_found_response
+
+
+class DestroyView(View):
+    """``DELETE /api/v1/<app_label>/<model_name>/<pk>/``.
+
+    The class name follows DRF's verb convention (``destroy``) to
+    avoid overloading the module surface — ``del`` is a Python
+    keyword and ``.delete()`` is a Django QuerySet/Model method, so
+    a *class* named ``DeleteView`` muddies imports. The HTTP-method
+    handler must still be named ``delete`` per Django's CBV
+    contract.
+    """
+
+    http_method_names = ["delete"]
+
+    def delete(
+        self,
+        request: HttpRequest,
+        app_label: str,
+        model_name: str,
+        pk: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> HttpResponse:
+        """Delete an instance (contract §5.3).
+
+        Gates: ``is_admin_user`` → ``resolve_model`` →
+        ``load_object_or_none`` (the admin's queryset is the only
+        lookup path — rule 10 / B-2) → ``has_delete_permission(request,
+        obj)`` per-object gate.
+
+        The actual delete goes through ``ModelAdmin.delete_model(request,
+        obj)`` — **never** ``obj.delete()`` — so any admin-side
+        cascade / hook logic is honored (rule 7 / B-4). Wrapped in
+        ``transaction.atomic()``. Returns a 204 (No Content) with
+        ``Cache-Control: no-store``.
+        """
+        admin_site = get_admin_site()
+        if not is_admin_user(request, admin_site=admin_site):
+            return forbidden_response()
+
+        resolved = resolve_model(admin_site, request, app_label, model_name)
+        if resolved is None:
+            return not_found_response()
+        model, model_admin = resolved
+
+        obj = load_object_or_none(model, model_admin, request, pk)
+        if obj is None:
+            return not_found_response()
+
+        if not model_admin.has_delete_permission(request, obj):
+            return forbidden_response()
+
+        with transaction.atomic():
+            model_admin.delete_model(request, obj)
+
+        response = HttpResponse(status=204)
+        response["Cache-Control"] = "no-store"
+        return response

django_admin_react/api/views/detail.py

@@ -0,0 +1,283 @@
+"""``GET /api/v1/<app>/<model>/<pk>/`` — single-object detail view.
+
+Wire contract: ``docs/api-contract.md`` §4.
+
+Hard rules (`SECURITY.md` §3, `ACCEPTANCE.md` §3.1):
+
+- Rule 1:  Staff + ``AdminSite.has_permission`` gate.
+- Rule 3:  Model resolved through ``admin.site._registry`` (B-7).
+- Rule 5:  ``has_view_permission(request, obj)`` per-object gate.
+- Rule 6:  Fields come from ``ModelAdmin.get_form(request, obj)`` /
+           ``get_fields`` / ``get_readonly_fields`` / ``get_exclude``.
+           Sensitive-name denylist applied on top
+           (``ACCEPTANCE.md`` §4.7 S-31).
+- Rule 10: Queryset starts at ``ModelAdmin.get_queryset(request)`` —
+           never ``Model.objects.all()`` (B-2).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.admin.options import ModelAdmin
+from django.contrib.admin.utils import label_for_field
+from django.db.models import ForeignKey
+from django.db.models import Model
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django.http import JsonResponse
+from django.views.generic import View
+
+from django_admin_react.api.permissions import forbidden_response
+from django_admin_react.api.permissions import is_admin_user
+from django_admin_react.api.registry import get_admin_site
+from django_admin_react.api.registry import model_permissions
+from django_admin_react.api.registry import resolve_model
+from django_admin_react.api.serializers import field_metadata
+from django_admin_react.api.serializers import filter_sensitive
+from django_admin_react.api.serializers import is_sensitive_field_name
+from django_admin_react.api.serializers import label_for
+from django_admin_react.api.serializers import serialize_fk_value
+from django_admin_react.api.serializers import serialize_value
+from django_admin_react.api.writes import load_object_or_none
+from django_admin_react.api.writes import not_found_response
+
+
+class DetailView(View):
+    """``GET /api/v1/<app_label>/<model_name>/<pk>/`` — single object."""
+
+    http_method_names = ["get"]
+
+    def get(
+        self,
+        request: HttpRequest,
+        app_label: str,
+        model_name: str,
+        pk: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> HttpResponse:
+        """Return the full descriptor for one object (contract §4).
+
+        Gates, in order:
+
+        1. ``is_admin_user`` — 403 if not authenticated active staff.
+        2. ``resolve_model`` — 404 if model unknown or unviewable.
+        3. ``load_object_or_none`` — 404 if pk doesn't resolve under
+           the admin's queryset (rule 10) or parse-fails.
+        4. ``has_view_permission(request, obj)`` — per-object gate
+           (rule 5); 403 once we know the object exists but the user
+           may not see *this* row.
+
+        The payload includes the visible field set, fieldsets, the
+        four ``has_*_permission`` booleans, and a friendly label.
+        Excluded / readonly / sensitive-named fields are dropped by
+        the visibility filter (defense in depth on top of the admin
+        form).
+        """
+        admin_site = get_admin_site()
+        if not is_admin_user(request, admin_site=admin_site):
+            return forbidden_response()
+
+        resolved = resolve_model(admin_site, request, app_label, model_name)
+        if resolved is None:
+            return not_found_response()
+        model, model_admin = resolved
+
+        obj = load_object_or_none(model, model_admin, request, pk)
+        if obj is None:
+            return not_found_response()
+
+        if not model_admin.has_view_permission(request, obj):
+            return forbidden_response()
+
+        payload = _build_payload(model, model_admin, obj, request)
+        response = JsonResponse(payload, status=200)
+        # No-store: per-user, permission-gated payload must never be
+        # cached by intermediate proxies or the browser. Extends
+        # ACCEPTANCE.md §4.6 S-30 (defined for 4xx) to 200 responses.
+        response["Cache-Control"] = "no-store"
+        return response
+
+
+# --------------------------------------------------------------------------- #
+# Payload assembly                                                            #
+# --------------------------------------------------------------------------- #
+def _build_payload(
+    model: type[Model],
+    model_admin: ModelAdmin,
+    obj: Model,
+    request: HttpRequest,
+) -> dict[str, Any]:
+    """Compose the full detail response body (contract §4)."""
+    visible_names = _visible_field_names(model_admin, request, obj)
+    return {
+        "app_label": model._meta.app_label,
+        "model_name": model._meta.model_name,
+        "pk": obj.pk,
+        "label": label_for(obj),
+        "permissions": model_permissions(model_admin, request),
+        "fieldsets": _fieldsets_payload(model_admin, request, obj, visible_names),
+        "fields": _fields_payload(model, model_admin, obj, request, visible_names),
+    }
+
+
+def _visible_field_names(
+    model_admin: ModelAdmin,
+    request: HttpRequest,
+    obj: Model,
+) -> list[str]:
+    """Field names the detail response may surface for this object.
+
+    This is the *read*-visible set: it includes readonly fields (so
+    the UI can render them) but drops admin-excluded fields and any
+    name matching the sensitive denylist. The *writable* set (for
+    POST/PATCH) lives in ``writes.writable_field_names`` and is
+    narrower.
+    """
+    declared = list(model_admin.get_fields(request, obj) or ())
+    excluded = set(model_admin.get_exclude(request, obj) or ())
+    visible = [
+        name for name in declared if name not in excluded and not is_sensitive_field_name(name)
+    ]
+    return filter_sensitive(visible)
+
+
+def _fieldsets_payload(
+    model_admin: ModelAdmin,
+    request: HttpRequest,
+    obj: Model,
+    visible_names: list[str],
+) -> list[dict[str, Any]]:
+    """Honour ``ModelAdmin.get_fieldsets`` (with a flat fallback).
+
+    Fieldset entries that the admin lists but the visibility filter
+    drops are silently removed from the group. An empty result is
+    returned as the single "default" group so the SPA always has at
+    least one section to render.
+    """
+    try:
+        raw = model_admin.get_fieldsets(request, obj) or ()
+    except Exception:
+        raw = ()
+    if not raw:
+        return [{"title": None, "fields": visible_names}]
+
+    visible_set = set(visible_names)
+    payload: list[dict[str, Any]] = []
+    for title, opts in raw:
+        fields = [
+            sub
+            for entry in opts.get("fields", ())
+            for sub in (entry if isinstance(entry, list | tuple) else (entry,))
+            if sub in visible_set
+        ]
+        if fields:
+            payload.append({"title": title, "fields": fields})
+    return payload or [{"title": None, "fields": visible_names}]
+
+
+def _fields_payload(
+    model: type[Model],
+    model_admin: ModelAdmin,
+    obj: Model,
+    request: HttpRequest,
+    visible_names: list[str],
+) -> dict[str, dict[str, Any]]:
+    """Build the per-field descriptor mapping (contract §4 ``fields``)."""
+    readonly = set(model_admin.get_readonly_fields(request, obj) or ())
+    form = model_admin.get_form(request, obj=obj)(instance=obj)
+
+    out: dict[str, dict[str, Any]] = {}
+    for name in visible_names:
+        out[name] = _descriptor_for(
+            model=model,
+            model_admin=model_admin,
+            obj=obj,
+            name=name,
+            form=form,
+            is_readonly=name in readonly,
+        )
+    return out
+
+
+def _descriptor_for(
+    *,
+    model: type[Model],
+    model_admin: ModelAdmin,
+    obj: Model,
+    name: str,
+    form: Any,
+    is_readonly: bool,
+) -> dict[str, Any]:
+    """Per-field descriptor for one ``visible_names`` entry."""
+    model_field = _safe_get_field(model, name)
+    if model_field is None:
+        return _readonly_callable_descriptor(model_admin, model, obj, name)
+
+    if isinstance(model_field, ForeignKey):
+        value: Any = serialize_fk_value(getattr(obj, name, None))
+    else:
+        value = serialize_value(getattr(obj, name, None))
+
+    form_field = form.fields.get(name)
+    required = bool(form_field.required) if form_field is not None else False
+    help_text = getattr(model_field, "help_text", "") or (
+        form_field.help_text if form_field is not None else ""
+    )
+
+    return field_metadata(
+        model_field,
+        label=_field_label(model_admin, model, name),
+        required=required,
+        readonly=is_readonly,
+        help_text=str(help_text),
+        value=value,
+    )
+
+
+def _readonly_callable_descriptor(
+    model_admin: ModelAdmin,
+    model: type[Model],
+    obj: Model,
+    name: str,
+) -> dict[str, Any]:
+    """Descriptor for a readonly callable / method (no underlying field).
+
+    ``ModelAdmin.get_fields`` may include method names or
+    ``@admin.display`` callables; those have no model field, so they
+    are surfaced as ``type=unsupported`` and ``readonly=True``.
+    """
+    value = getattr(obj, name, None)
+    if callable(value):
+        try:
+            value = value()
+        except Exception:
+            value = None
+    return {
+        "type": "unsupported",
+        "label": _field_label(model_admin, model, name),
+        "required": False,
+        "readonly": True,
+        "help_text": "",
+        "value": serialize_value(value),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Internals                                                                   #
+# --------------------------------------------------------------------------- #
+def _safe_get_field(model: type[Model], name: str):
+    """Return ``model._meta.get_field(name)`` or ``None`` if not found."""
+    try:
+        return model._meta.get_field(name)
+    except Exception:
+        return None
+
+
+def _field_label(model_admin: ModelAdmin, model: type[Model], name: str) -> str:
+    """Human-readable label for a field (Django's own helper, with fallback)."""
+    try:
+        return str(label_for_field(name, model, model_admin))
+    except Exception:
+        return name