django-spec-html 0.1.0__py3-none-any.whl

django_spec_html/__init__.py

@@ -0,0 +1,34 @@
+"""A django-service-specs spec as a server-rendered page, plus the plain-Django JSON views.
+
+``views`` serves a spec as the page its form is, and ``http`` serves one as
+JSON with nothing between the request and the kernel's ``dispatch``. Every
+public name of both is here; read them from the root.
+"""
+
+from django_spec_html.http.add_argument_errors import add_argument_errors
+from django_spec_html.http.adispatch_request import adispatch_request
+from django_spec_html.http.async_spec_view import AsyncSpecView
+from django_spec_html.http.dispatch_request import dispatch_request
+from django_spec_html.http.error_response import error_response
+from django_spec_html.http.request_arguments import request_arguments
+from django_spec_html.http.request_principal import request_principal
+from django_spec_html.http.route_arguments import route_arguments
+from django_spec_html.http.spec_view import SpecView
+from django_spec_html.http.unsupported_media_type import UnsupportedMediaType
+from django_spec_html.version import __version__
+from django_spec_html.views.spec_form_view import SpecFormView
+
+__all__ = [
+    "AsyncSpecView",
+    "SpecFormView",
+    "SpecView",
+    "UnsupportedMediaType",
+    "__version__",
+    "add_argument_errors",
+    "adispatch_request",
+    "dispatch_request",
+    "error_response",
+    "request_arguments",
+    "request_principal",
+    "route_arguments",
+]

django_spec_html/http/__init__.py

@@ -0,0 +1,25 @@
+"""Serving an operation from a Django view, with nothing between the request and dispatch."""
+
+from django_spec_html.http.add_argument_errors import add_argument_errors
+from django_spec_html.http.adispatch_request import adispatch_request
+from django_spec_html.http.async_spec_view import AsyncSpecView
+from django_spec_html.http.dispatch_request import dispatch_request
+from django_spec_html.http.error_response import error_response
+from django_spec_html.http.request_arguments import request_arguments
+from django_spec_html.http.request_principal import request_principal
+from django_spec_html.http.route_arguments import route_arguments
+from django_spec_html.http.spec_view import SpecView
+from django_spec_html.http.unsupported_media_type import UnsupportedMediaType
+
+__all__ = [
+    "AsyncSpecView",
+    "SpecView",
+    "UnsupportedMediaType",
+    "add_argument_errors",
+    "adispatch_request",
+    "dispatch_request",
+    "error_response",
+    "request_arguments",
+    "request_principal",
+    "route_arguments",
+]

django_spec_html/http/add_argument_errors.py

@@ -0,0 +1,80 @@
+"""``add_argument_errors`` - a refusal tree placed on a bound form, beside the form's own errors."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from django.core.exceptions import NON_FIELD_ERRORS as FORM_NON_FIELD_ERRORS
+from django.forms import BaseForm
+from django_service_specs import NON_FIELD_KEYS, clean_held_to_their_columns, refusal_messages
+
+
+def add_argument_errors(form: BaseForm, detail: Mapping[Any, Any]) -> None:
+    """Place a refusal tree on a bound ``form``, beside the form's own errors, never twice.
+
+    ``detail`` is an
+    [`InvalidArguments`][django_service_specs.parameters.invalid_arguments.InvalidArguments]
+    tree, or a ``ServiceValidationError``'s mapping. Each message goes where a
+    person reading the form looks for it, through Django's public
+    ``form.add_error``:
+
+    - **A key naming one of the form's fields** puts its messages on that
+      field. A form is flat, so the only tree below a field is an array's
+      element indices, which mean nothing to a person reading one control: the
+      messages go on the field without them.
+    - ``non_field_errors``, and Django's own ``"__all__"``, go to the form's
+      non-field errors as they are.
+    - **Any other key** - a URL kwarg such as ``pk``, or a key a service chose -
+      goes to the non-field errors prefixed with its path, ``"pk: ..."``, so the
+      reader knows what it is about. A nested tree is flattened to its leaves
+      with the path joined by dots, ``"books.1.title: ..."``, a row's own
+      ``non_field_errors`` adding nothing to the path.
+
+    **Never a duplicate.** A message the form already carries at the same place
+    is not added again. The form validating the same data says the same thing
+    the kernel does - a ``FormValidator``'s refusal *is* the form's errors, and
+    the shape check spells its messages as Django's fields do - so without this
+    most refusals would show twice. A form not yet validated is validated
+    first, as reading ``form.errors`` would, so the form's own errors are
+    always the ones compared against; but with the guards a
+    ``FormValidator``'s form is validated with, since the form's own
+    validation would hand the database driver a number no integer column
+    holds, which SQLite's refuses with ``OverflowError``. A model choice
+    field's key past its column's range is refused as ``invalid_choice`` and
+    a ``ModelForm``'s value past its integer column's range as ``max_value``
+    or ``min_value``, in the words a ``FormValidator`` refuses them with, so
+    the refusal of one is placed once
+    (test_a_list_s_key_past_its_column_is_refused_once,
+    test_a_model_form_s_integer_past_its_column_is_refused_once). A form
+    already validated is compared as it stands.
+
+    A leaf is a message whatever its type: a string, a lazy translation (which
+    is not a ``str``, and is never taken apart into characters), or a list of
+    either. The form must be bound, as Django's ``add_error`` requires.
+    """
+    # Django's own marker of a form not yet validated, which the stubs declare
+    # on no form, hence ``Any``. Each way is held by its own test:
+    # test_a_list_s_key_past_its_column_is_refused_once (not yet validated,
+    # so validated here with the guards) and
+    # test_a_form_already_validated_is_compared_as_it_stands (an error state
+    # the caller already holds, which validating here would start over).
+    bound: Any = form
+    if bound._errors is None:
+        clean_held_to_their_columns(form)
+    for key, value in detail.items():
+        field = key if key in form.fields else None
+        for path, message in refusal_messages(value):
+            if field is not None:
+                _add_once(form, field, message)
+                continue
+            where = path if key in NON_FIELD_KEYS else (str(key), *path)
+            _add_once(form, None, f"{'.'.join(where)}: {message}" if where else message)
+
+
+def _add_once(form: BaseForm, field: str | None, message: str) -> None:
+    """``form.add_error``, unless the place already carries ``message``."""
+    # An ErrorList yields its messages as strings, so ``in`` compares a string
+    # with each, and a missing key reads as a place carrying nothing yet.
+    if message not in form.errors.get(FORM_NON_FIELD_ERRORS if field is None else field, ()):
+        form.add_error(field, message)

django_spec_html/http/adispatch_request.py

@@ -0,0 +1,97 @@
+"""``adispatch_request`` - ``dispatch_request``, from an async view."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from asgiref.sync import sync_to_async
+from django.http import HttpRequest, HttpResponse
+from django_service_specs import (
+    DEFAULT_POOL_SEEDS,
+    DispatchError,
+    Grant,
+    PoolSeeds,
+    SelectorSpec,
+    ServiceError,
+    ServiceSpec,
+    SpecSource,
+    UnknownArguments,
+    adispatch,
+    apresent,
+    kernel_spec,
+)
+
+from django_spec_html.http.error_response import error_response
+from django_spec_html.http.request_arguments import request_arguments
+from django_spec_html.http.request_principal import request_principal
+from django_spec_html.http.utils import (
+    check_asked_input,
+    not_found_response,
+    success_response,
+)
+
+
+async def adispatch_request(
+    spec: ServiceSpec | SelectorSpec | SpecSource,
+    request: HttpRequest,
+    *,
+    url_kwargs: Mapping[str, Any] | None = None,
+    success_status: int | None = None,
+    grant: Grant | None = None,
+    pool_seeds: PoolSeeds = DEFAULT_POOL_SEEDS,
+    unknown_arguments: UnknownArguments = UnknownArguments.REJECT,
+) -> HttpResponse:
+    """[`dispatch_request`][django_spec_html.http.dispatch_request.dispatch_request], from async code.
+
+    The same principal, arguments, statuses and refusals, reached through
+    [`adispatch`][django_service_specs.dispatch.adispatch.adispatch] and
+    [`apresent`][django_service_specs.dispatch.apresent.apresent], so the
+    kernel's async rule holds: nothing that may query runs on the event loop.
+
+    That includes **reading the request**, which is one executor hop of its
+    own before ``adispatch``'s. ``request.user`` is the lazy object
+    AuthenticationMiddleware leaves, and its first read is a session query,
+    which Django refuses on the loop; Django 4.2, the floor, has no
+    ``request.auser()`` to await instead. ``spec.parameters()`` goes in the
+    same hop, because a Validator may read a model to declare what it takes.
+    Building the response does not query and stays on the loop.
+    """
+    # Compiled once, before anything is read, so the arguments, the answer's
+    # status and the asked-input check all read the one compiled spec.
+    spec = kernel_spec(spec)
+    try:
+        principal, arguments = await sync_to_async(_read_request, thread_sensitive=True)(
+            spec, request, url_kwargs
+        )
+        result = await adispatch(
+            spec,
+            principal=principal,
+            arguments=arguments,
+            grant=grant,
+            pool_seeds=pool_seeds,
+            unknown_arguments=unknown_arguments,
+        )
+        if result.kind == "not_found":
+            return not_found_response()
+        return success_response(spec, await apresent(spec, result), success_status)
+    except (DispatchError, ServiceError) as refused:
+        check_asked_input(spec, refused)
+        return error_response(refused)
+
+
+def _read_request(
+    spec: ServiceSpec | SelectorSpec,
+    request: HttpRequest,
+    url_kwargs: Mapping[str, Any] | None,
+) -> tuple[Any, dict[str, Any]]:
+    """The principal, then the arguments, in the one executor hop they share.
+
+    The principal first, as ``adispatch`` resolves a ``principal_id`` before
+    its shape check, so a deactivated account is refused without learning
+    anything about its request. Both off the loop: the principal may be a
+    session query, and ``spec.parameters()`` may be one too, since a
+    Validator may read a model to declare what it takes.
+    """
+    principal = request_principal(request)
+    return principal, request_arguments(request, spec.parameters(), url_kwargs=url_kwargs)

django_spec_html/http/async_spec_view.py

@@ -0,0 +1,40 @@
+"""``AsyncSpecView`` - ``SpecView``, served from async code."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.http import HttpRequest, HttpResponse
+
+from django_spec_html.http.adispatch_request import adispatch_request
+from django_spec_html.http.utils import SpecViewBase
+
+
+class AsyncSpecView(SpecViewBase):
+    """[`SpecView`][django_spec_html.http.spec_view.SpecView], with every handler async.
+
+    The same attributes, methods, checks and answers, through
+    [`adispatch_request`][django_spec_html.http.adispatch_request.adispatch_request].
+    Django serves a class-based view async only when every handler it defines
+    is ``async def``, and refuses a class that mixes the two, so every method
+    a spec may be served on is async here, not only the ones it answers by
+    default. Under ASGI this keeps the request off a worker thread until the
+    kernel needs one; under WSGI Django runs it in an event loop of its own,
+    which costs more than ``SpecView`` and buys nothing.
+
+    Not a subclass of ``SpecView``, for the same reason: an async handler
+    cannot stand in for a sync one.
+    """
+
+    async def answer(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+        """Dispatch the spec from async code, the route's kwargs as ``url_kwargs``."""
+        return await adispatch_request(
+            self.served_spec(),
+            request,
+            url_kwargs=kwargs,
+            success_status=self.success_status,
+            pool_seeds=self.pool_seeds,
+            unknown_arguments=self.unknown_arguments,
+        )
+
+    get = head = post = put = patch = delete = answer

django_spec_html/http/dispatch_request.py

@@ -0,0 +1,98 @@
+"""``dispatch_request`` - one request, dispatched and answered, from a hand-written view."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from django.http import HttpRequest, HttpResponse
+from django_service_specs import (
+    DEFAULT_POOL_SEEDS,
+    DispatchError,
+    Grant,
+    PoolSeeds,
+    SelectorSpec,
+    ServiceError,
+    ServiceSpec,
+    SpecSource,
+    UnknownArguments,
+    dispatch,
+    kernel_spec,
+    present,
+)
+
+from django_spec_html.http.error_response import error_response
+from django_spec_html.http.request_arguments import request_arguments
+from django_spec_html.http.request_principal import request_principal
+from django_spec_html.http.utils import (
+    check_asked_input,
+    not_found_response,
+    success_response,
+)
+
+
+def dispatch_request(
+    spec: ServiceSpec | SelectorSpec | SpecSource,
+    request: HttpRequest,
+    *,
+    url_kwargs: Mapping[str, Any] | None = None,
+    success_status: int | None = None,
+    grant: Grant | None = None,
+    pool_seeds: PoolSeeds = DEFAULT_POOL_SEEDS,
+    unknown_arguments: UnknownArguments = UnknownArguments.REJECT,
+) -> HttpResponse:
+    """Dispatch ``spec`` for ``request`` and answer it as JSON: the function a view calls.
+
+    1. **The principal is** ``request.user``, anonymous included, since the
+       spec's permission check is what decides whether anonymous may act. An
+       authenticated user whose ``is_active`` is false is refused as
+       ``PrincipalUnavailable``: a backend other than ``ModelBackend`` can log
+       one in, and a deactivated principal never acts. Dispatch refuses one by
+       the same rule; refusing here as well keeps the request unread for it.
+    2. **The arguments** are
+       [`request_arguments`][django_spec_html.http.request_arguments.request_arguments]
+       for ``spec.parameters()``, with ``url_kwargs`` merged last.
+    3. [`dispatch`][django_service_specs.dispatch.dispatch.dispatch], with
+       ``grant``, ``pool_seeds`` and ``unknown_arguments`` as given.
+    4. **The answer.** A not-found result is 404 with a ``detail``. Otherwise
+       the presented value, bare, at ``success_status`` if given, else 204 for
+       a service with nothing to present and 200 for everything else - the
+       defaults djangorestframework-services answers with. A 204 has no body.
+
+    A refusal of either family, from any of the four steps, is answered by
+    [`error_response`][django_spec_html.http.error_response.error_response].
+    Anything else propagates, a configuration error included: it is wrong for
+    every caller, so it belongs to the host's error handling rather than to one
+    client's response. A URL kwarg ``spec`` does not declare is one, raised
+    as ``ImproperlyConfigured``: every URL kwarg is an argument, and the route
+    is the host's.
+
+    ``spec`` may be a
+    [`SpecSource`][django_service_specs.specs.spec_source.SpecSource]: it is
+    compiled once, first, and every step reads the spec it compiles to.
+
+    **CSRF is the host's middleware**, as for any Django view: nothing here
+    exempts a view, and ``csrf_exempt`` is one line for a host that wants it.
+    """
+    spec = kernel_spec(spec)
+    try:
+        # The principal first, as ``adispatch`` resolves a ``principal_id``
+        # and ``dispatch`` refuses a deactivated principal before its shape
+        # check: a deactivated account is refused without learning anything
+        # about its request.
+        principal = request_principal(request)
+        arguments = request_arguments(request, spec.parameters(), url_kwargs=url_kwargs)
+        result = dispatch(
+            spec,
+            principal=principal,
+            arguments=arguments,
+            grant=grant,
+            pool_seeds=pool_seeds,
+            unknown_arguments=unknown_arguments,
+        )
+        if result.kind == "not_found":
+            return not_found_response()
+        return success_response(spec, present(spec, result), success_status)
+    except (DispatchError, ServiceError) as refused:
+        check_asked_input(spec, refused)
+        return error_response(refused)

django_spec_html/http/error_response.py

@@ -0,0 +1,104 @@
+"""``error_response`` - a refusal of either family, as the JSON an HTTP client reads."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from django.http import JsonResponse
+from django_service_specs import (
+    ActionUnavailable,
+    AdditionalInputRequired,
+    DispatchError,
+    InvalidArguments,
+    ServiceError,
+    ServiceValidationError,
+)
+
+from django_spec_html.http.utils import field_map, refusal_status
+
+
+def error_response(exc: DispatchError | ServiceError) -> JsonResponse:
+    """``exc`` as JSON, at the status djangorestframework-services answers it with.
+
+    One map for both families, at djangorestframework-services' statuses, and
+    the one the page reads too.
+    Two bodies differ from its answer. A service's string or list detail, which
+    DRF answers as a bare list and this as a field map under
+    ``non_field_errors``, so every 400 here has one shape. And an
+    ``AdditionalInputRequired`` schema, which DRF reads as an error detail and
+    so writes with every value a string (``"minimum": "1"``), and this writes as
+    the JSON Schema it is:
+
+    | Refusal | Status | Body |
+    | --- | --- | --- |
+    | `InvalidArguments` | 400 | the error tree |
+    | `ServiceValidationError` | 400 | its detail, as a field map |
+    | `NotPermitted`, `PrincipalUnavailable` | 403 | `{"detail": message}` |
+    | `ServiceNotFound` | 404 | `{"detail": message}` |
+    | `ActionUnavailable` | 409 | `{"detail": message, "code": code}` |
+    | any other `ServiceConflict` | 409 | `{"detail": message}` |
+    | `AdditionalInputRequired` with a `schema` | 422 | `{"detail": message, "schema": schema}` |
+    | any other `ServiceError` | 422 | `{"detail": message}` |
+    | `UnsupportedMediaType` | 415 | `{"detail": message}` |
+    | any other `DispatchError` | 400 | `{"detail": message}` |
+
+    **Every 400 body is a field map.** ``InvalidArguments`` is its tree, whose
+    integer row keys JSON writes as strings. A ``ServiceValidationError``'s
+    mapping is its body as it is, and a string or a list goes under
+    ``non_field_errors``, where a message about the input as a whole sits in
+    the tree too. A lazy translation is one message, not a sequence of
+    characters, and renders in the active language: ``JsonResponse``'s
+    encoder renders every lazy string it meets, messages included.
+
+    **Never 401.** A session-authenticated view has no challenge to answer,
+    and a 401 tells a client to start an authentication flow it has no way to
+    finish. An anonymous caller a permission check refuses is a 403, like any
+    other refused principal.
+
+    **Two members add a key beside ``detail``, and keep their base's status.**
+    ``ActionUnavailable`` is a conflict, and its arm exists only to put the
+    affordance's ``code`` in the body beside the ``detail`` a client already
+    reads: the stable code is the whole point of the member, and a client left
+    with only the sentence has nothing to branch on. ``AdditionalInputRequired``
+    is "I need one more value", which is the operation being unprocessable as
+    asked, so it stays a 422 like any other service error; the ``schema`` naming
+    what is missing joins the body, because without it a client is told that
+    something is needed and not what. Only when there is a schema: the error is
+    valid without one, and growing the body unconditionally would change every
+    plain message into an object for no gain.
+
+    A ``DispatchError`` no row names - raised by nobody in this package, or a
+    subclass a later release adds - is still a refusal of the call rather than
+    the operation's own verdict, so it answers 400 rather than 422.
+    """
+    status = refusal_status(exc)
+    if isinstance(exc, InvalidArguments):
+        return JsonResponse(exc.detail, status=status)
+    if isinstance(exc, ServiceValidationError):
+        return JsonResponse(field_map(exc.detail), status=status)
+    if isinstance(exc, ActionUnavailable):
+        return JsonResponse({"detail": exc.message, "code": exc.code}, status=status)
+    # Two conjuncts, each held in tests/http/test_error_response.py:
+    # ``test_without_a_schema_the_body_is_the_plain_detail`` fails without the
+    # second (a missing schema would be written as null), and the ``Postponed``
+    # row of ``test_a_message_refusal_is_its_status_and_a_detail`` without the
+    # first (a plain service error has no schema to read).
+    if isinstance(exc, AdditionalInputRequired) and exc.schema is not None:
+        return JsonResponse({"detail": exc.message, "schema": _plain(exc.schema)}, status=status)
+    return JsonResponse({"detail": exc.message}, status=status)
+
+
+def _plain(value: Any) -> Any:
+    """``value`` with every mapping in it a ``dict``, at any depth.
+
+    The encoder writes only a ``dict`` as an object, and a schema may arrive
+    as any mapping - a frozen one, say - at the top or nested in a property,
+    where it would otherwise be a 500. Both container kinds are held by
+    ``test_a_schema_of_any_mapping_is_written_at_any_depth``.
+    """
+    if isinstance(value, Mapping):
+        return {key: _plain(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_plain(item) for item in value]
+    return value