django-spec-html 0.1.2__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. django_spec_html-0.2.0/CHANGELOG.md +176 -0
  2. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/CLAUDE.md +8 -6
  3. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/PKG-INFO +8 -7
  4. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/README.md +6 -5
  5. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/__init__.py +5 -2
  6. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/adispatch_request.py +21 -4
  7. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/async_spec_view.py +12 -1
  8. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/dispatch_request.py +28 -5
  9. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/request_arguments.py +38 -9
  10. django_spec_html-0.2.0/django_spec_html/http/route_arguments.py +127 -0
  11. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/spec_view.py +32 -6
  12. django_spec_html-0.2.0/django_spec_html/http/utils.py +574 -0
  13. django_spec_html-0.2.0/django_spec_html/types/__init__.py +5 -0
  14. django_spec_html-0.2.0/django_spec_html/types/outcome.py +35 -0
  15. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/version.py +1 -1
  16. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/views/spec_form_view.py +453 -40
  17. django_spec_html-0.2.0/docs/examples/htmx.py +95 -0
  18. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/examples/http.py +44 -1
  19. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/examples/spec_form.py +47 -0
  20. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/http.md +88 -9
  21. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/index.md +3 -3
  22. django_spec_html-0.2.0/docs/pages.md +407 -0
  23. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/reference.md +1 -0
  24. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/pyproject.toml +16 -10
  25. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/conftest_settings.py +9 -5
  26. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/docs/test_http_examples.py +65 -2
  27. django_spec_html-0.2.0/tests/docs/test_spec_form_examples.py +474 -0
  28. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_adispatch_request.py +27 -1
  29. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_async_spec_view.py +136 -2
  30. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_dispatch_request.py +40 -0
  31. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_request_arguments.py +92 -0
  32. django_spec_html-0.2.0/tests/http/test_route_arguments.py +123 -0
  33. django_spec_html-0.2.0/tests/http/test_spec_view.py +620 -0
  34. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_utils.py +48 -3
  35. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/utils.py +49 -0
  36. django_spec_html-0.2.0/tests/templates/spec_form_available.html +5 -0
  37. django_spec_html-0.2.0/tests/templates/spec_form_htmx.html +13 -0
  38. django_spec_html-0.2.0/tests/templates/spec_fragment.html +1 -0
  39. django_spec_html-0.2.0/tests/templates/spec_page.html +1 -0
  40. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/test_init.py +2 -0
  41. django_spec_html-0.2.0/tests/types/test_outcome.py +33 -0
  42. django_spec_html-0.2.0/tests/views/__init__.py +0 -0
  43. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/views/test_spec_form_view.py +1092 -24
  44. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/uv.lock +19 -4
  45. django_spec_html-0.1.2/CHANGELOG.md +0 -75
  46. django_spec_html-0.1.2/django_spec_html/http/route_arguments.py +0 -44
  47. django_spec_html-0.1.2/django_spec_html/http/utils.py +0 -266
  48. django_spec_html-0.1.2/docs/pages.md +0 -186
  49. django_spec_html-0.1.2/tests/docs/test_spec_form_examples.py +0 -245
  50. django_spec_html-0.1.2/tests/http/test_route_arguments.py +0 -49
  51. django_spec_html-0.1.2/tests/http/test_spec_view.py +0 -216
  52. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.github/CODEOWNERS +0 -0
  53. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.github/SECURITY.md +0 -0
  54. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.github/dependabot.yml +0 -0
  55. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.github/workflows/release.yml +0 -0
  56. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.github/workflows/tests.yml +0 -0
  57. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.github/workflows/upstream-drift.yml +0 -0
  58. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.gitignore +0 -0
  59. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/.pre-commit-config.yaml +0 -0
  60. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/LICENSE +0 -0
  61. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/Makefile +0 -0
  62. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/__init__.py +0 -0
  63. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/add_argument_errors.py +0 -0
  64. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/error_response.py +0 -0
  65. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/request_principal.py +0 -0
  66. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/http/unsupported_media_type.py +0 -0
  67. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/py.typed +0 -0
  68. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/django_spec_html/views/__init__.py +0 -0
  69. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/__init__.py +0 -0
  70. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/docs/examples/__init__.py +0 -0
  71. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/mkdocs.yml +0 -0
  72. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/scripts/check-changelog +0 -0
  73. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/scripts/release-publish.sh +0 -0
  74. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/__init__.py +0 -0
  75. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/adapter_app/__init__.py +0 -0
  76. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/adapter_app/apps.py +0 -0
  77. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/adapter_app/models.py +0 -0
  78. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/conftest.py +0 -0
  79. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/dispatch/__init__.py +0 -0
  80. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/dispatch/utils.py +0 -0
  81. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/dispatch_app/__init__.py +0 -0
  82. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/dispatch_app/apps.py +0 -0
  83. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/dispatch_app/models.py +0 -0
  84. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/docs/__init__.py +0 -0
  85. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/__init__.py +0 -0
  86. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_add_argument_errors.py +0 -0
  87. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_error_response.py +0 -0
  88. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_request_principal.py +0 -0
  89. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/http/test_unsupported_media_type.py +0 -0
  90. {django_spec_html-0.1.2 → django_spec_html-0.2.0}/tests/templates/spec_form.html +0 -0
  91. {django_spec_html-0.1.2/tests/views → django_spec_html-0.2.0/tests/types}/__init__.py +0 -0
@@ -0,0 +1,176 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.2.0] — 2026-10-26
11
+
12
+ ### Added
13
+ - **An htmx request to `SpecFormView` is answered with a fragment of the page.**
14
+ The view decides a request's outcome once and then chooses the answer: the
15
+ page, unless `wants_fragment(request)` says htmx asked for less, which it does
16
+ for an `HX-Request` that is neither boosted nor a history restore, read from
17
+ django-htmx's `request.htmx` where its middleware set it and from the headers
18
+ where it did not. The fragment renders `get_fragment_template_names()`,
19
+ which is `fragment_template_name` or, by default, the page's own
20
+ `<template_name>#spec-form`, a `{% partialdef %}` that Django 6.0 resolves;
21
+ below 6.0, django-template-partials 23.3 or later does, with its tag named as
22
+ a `TEMPLATES` builtin and its loader around the project's own. GET answers
23
+ the form fragment, and every refusal the page re-renders answers it at 200
24
+ rather than the page's 4xx, since htmx swaps no 4xx by default. A success is
25
+ `fragment_success(result)`: `HX-Redirect` to `get_success_url(result)`, never
26
+ a 302, encoded and checked as the page's redirect is, so an unsafe scheme
27
+ raises `DisallowedRedirect` in both modes; or the template's `spec-result`
28
+ fragment rendered in place, with `result` in its context, and
29
+ `HX-Trigger: spec-succeeded`. A denial is raised in both modes, for the
30
+ host's handlers. A template with no fragment at the address is Django's
31
+ `TemplateDoesNotExist` naming it, never the page. Every answer varies on
32
+ `HX-Request`, `HX-Boosted` and `HX-History-Restore-Request`, and no htmx
33
+ header reaches dispatch.
34
+ - **`Outcome`**, the five ways a page's post ends (`ok`, `invalid`,
35
+ `needs_input`, `denied`, `failed`), exported from the root. The one status
36
+ map gains each refusal's outcome as its third column, so the page and the
37
+ JSON views still read a single table.
38
+ - **The request reaches the spec on the JSON views.** `SpecView` and
39
+ `AsyncSpecView` gain two hooks, each defaulting to the attribute of its name:
40
+ `get_pool_seeds(request)`, so a tenant, a locale or a team the request
41
+ carries reaches a permission check, a selector or a Validator; and
42
+ `get_server_arguments(request)`, the kernel's `ServerArguments` the server
43
+ answers for, whose values outrank whatever the client sent. The declared
44
+ `server_arguments` is checked by `check_server_arguments` at `as_view()`,
45
+ against the declared `pool_seeds`; a per-call binding may vary the values,
46
+ and one that binds or withholds other names raises `ImproperlyConfigured`,
47
+ as does a seed `get_pool_seeds` adds per request under a name the binding
48
+ binds or withholds. Every name the server answers for is dropped from what
49
+ the client sent before the request is coerced, so a client's malformed value
50
+ for it is never refused. Both hooks are plain `def`, and `as_view()` refuses
51
+ an `async def` one; `AsyncSpecView` runs them off the event loop. No
52
+ `request` seed is registered: a spec callable requiring one raises
53
+ `TypeError` on every reader that has no request.
54
+ - **`route_kwargs` serves a route whose kwargs are not all the spec's**, as an
55
+ `include()` prefix such as `teams/<team>/` is. On both JSON views, and as a
56
+ keyword of `route_arguments`, `request_arguments`, `dispatch_request` and
57
+ `adispatch_request`: a mapping from a captured kwarg to the parameter it
58
+ fills, or to `None` to drop it, or a tuple of names as an allow-list. The
59
+ default is the strict rule, unchanged, and a kwarg a mapping does not name
60
+ is still held to it. On a view, `as_view()` refuses a bare string, and a
61
+ target or allowed name the spec does not declare or the server binding
62
+ answers for, when the URLconf is imported. Two kwargs filling one parameter
63
+ are refused on the request that captures both.
64
+ - **A route kwarg that fills a name the server answers for is refused** as
65
+ `ImproperlyConfigured`, naming the captured kwarg and pointing at
66
+ `route_kwargs={name: None}`, which drops it explicitly: the route is the
67
+ host's, and may not contradict the host's own binding.
68
+ - `dispatch_request` and `adispatch_request` take `server_arguments=` and apply
69
+ it with `apply_server_arguments` before dispatch; `request_arguments` takes
70
+ it to drop those names from what the client sent before coercion.
71
+ - **`SpecFormView` takes the same attributes and hooks as the JSON views**:
72
+ `route_kwargs`, `get_pool_seeds(request)`, `server_arguments` and
73
+ `get_server_arguments(request)`, checked by the same code as `SpecView`'s at
74
+ `as_view()` and on each request. The binding applies wherever the page reads
75
+ arguments: a field of the page's form the binding binds renders disabled with
76
+ the server's value, one it withholds disabled and empty, on GET and on a
77
+ refused post, and neither is read from the post; the server's values are
78
+ laid over the route's before the target is found and over the post's before
79
+ dispatch, so the page's form, the target's lookup and dispatch read the
80
+ server's value. The per-call seeds reach the target's lookup, its
81
+ object-level and scope checks, the affordances and dispatch. The page's
82
+ class-level permission check is still asked with no seed, its own
83
+ `pool_seeds` included, so one naming a seed raises `TypeError` on the page,
84
+ where the JSON views hand it the call's seeds.
85
+ - **The page asks a spec's affordances on GET.** Once the target is found, the
86
+ callable conditions are asked through the kernel's
87
+ `unmet_operation_affordance`, on a pool built from the call's seeds, and,
88
+ with none of those unmet and a row to ask about, the conditions on the row
89
+ as dispatch asks them. On a GET with a row, each callable condition is
90
+ therefore asked, and each seed resolved, twice. The first unmet `Affordance`
91
+ is in the context as `unavailable`, in the page and the fragment alike; it
92
+ is absent when every condition is met. The post is unchanged, and
93
+ dispatch's 409 stays the authority.
94
+ - **A refused post's context carries the refusal's `code`**, for an
95
+ `ActionUnavailable`, as `error_response` puts it in the JSON body.
96
+
97
+ ### Changed
98
+ - **An htmx post to the page is no longer answered as any other.** A success
99
+ is `HX-Redirect` rather than a 302, and a refusal is the form fragment at 200
100
+ rather than the whole page at its 4xx; a request with no htmx header is
101
+ answered as before.
102
+ - **The kernel floor is now `django-service-specs>=0.15.0`.** The request
103
+ hooks need a permission check offered a registered seed by name, which
104
+ 0.14.0 added, and a top-level Validator field named like a seed staying the
105
+ caller's, which 0.15.0 did.
106
+ - The request-hook checks `SpecViewBase` made are shared helpers in
107
+ `http/utils.py`, which `SpecFormView` calls too; `SpecView` and
108
+ `AsyncSpecView` answer exactly as before.
109
+
110
+ ## [0.1.2] — 2026-10-21
111
+
112
+ ### Fixed
113
+ - **The documentation and the package summary no longer claim htmx support
114
+ the page does not have.** `SpecFormView` reads no htmx header, so an htmx
115
+ post is answered as any other: a success is the redirect, which the request
116
+ follows itself, and a refusal is the whole page at its 4xx status, which htmx
117
+ does not swap by default. The PyPI summary called the page htmx-capable and
118
+ listed htmx among its keywords, the README and the documentation site named
119
+ htmx as a client of the JSON views, and the page's documentation and the
120
+ view's docstring named htmx as a client that reads a refused post's status.
121
+ They now say what the page does, and that a fragment answer for htmx is
122
+ planned for 0.2.0. The JSON views are described as serving a script or a
123
+ `fetch()`, since htmx swaps HTML. Two tests hold the page's answer to an htmx
124
+ post. No behaviour changed.
125
+
126
+ ## [0.1.1] — 2026-10-21
127
+
128
+ ### Changed
129
+ - **The kernel floor is now `django-service-specs>=0.12.0`, the first release
130
+ without its own copy of these views.** Until then the kernel's root still
131
+ exported the ten JSON names as classes and functions of its own, so
132
+ `from django_service_specs import SpecView` resolved to a second, different
133
+ class beside this package's, and an `isinstance` check against either missed
134
+ the other. From 0.12.0 those names are imported from `django_spec_html`
135
+ alone.
136
+
137
+ ## [0.1.0] — 2026-10-21
138
+
139
+ ### Added
140
+ - **`django-spec-html`: a `django-service-specs` spec served over plain Django,
141
+ as a page and as JSON, the kernel's two HTTP halves moved out.** The JSON
142
+ views are the kernel's `http/` subpackage as it shipped in
143
+ `django-service-specs` 0.11.0, and `SpecFormView` is the page the kernel last
144
+ shipped in 0.5.1, each moved with its history, tests and documentation so
145
+ the kernel can carry no transport. `SpecFormView` serves a spec whose
146
+ Validator is a `FormValidator` as the page that form is: GET renders it,
147
+ showing the row an update targets; a valid POST dispatches and redirects;
148
+ a refused one re-renders the form with the refusal placed on it. `SpecView`,
149
+ `AsyncSpecView`, `dispatch_request` and `adispatch_request` serve a spec as
150
+ JSON, and `error_response`, `request_arguments`, `route_arguments`,
151
+ `request_principal`, `add_argument_errors` and `UnsupportedMediaType` come
152
+ with them. The behaviour is unchanged but for the one change below; the
153
+ import paths are this package's,
154
+ `django_spec_html` at the root, with `django_spec_html.http` and
155
+ `django_spec_html.views` where each name is defined. `UnsupportedMediaType`
156
+ is this package's own refusal, answered 415 by its own `error_response`,
157
+ and the array cap keeps the kernel's `SERVICE_SPECS_MAX_ARRAY_LENGTH` key.
158
+ Until the kernel removes its own copy of the JSON views, the kernel's root
159
+ still exports those ten names as the kernel's own classes and functions,
160
+ not this package's: import them from `django_spec_html`. Neither
161
+ package needs an entry in `INSTALLED_APPS`. Floors: Python 3.10, Django 4.2
162
+ and `django-service-specs>=0.10.0`, the first kernel release with every
163
+ name these views read at its root.
164
+
165
+ ### Changed
166
+ - **`SpecFormView` answers an `UnsupportedMediaType` an operation raises at
167
+ 415**, re-rendering the form, where the kernel's page answered it 400. The
168
+ page and the JSON views now read one map from each refusal to its status,
169
+ so a refused post answers at the status a JSON client reads for the same
170
+ refusal.
171
+
172
+ [Unreleased]: https://github.com/Artui/django-spec-html/compare/v0.2.0...HEAD
173
+ [0.2.0]: https://github.com/Artui/django-spec-html/compare/v0.1.2...v0.2.0
174
+ [0.1.2]: https://github.com/Artui/django-spec-html/compare/v0.1.1...v0.1.2
175
+ [0.1.1]: https://github.com/Artui/django-spec-html/compare/v0.1.0...v0.1.1
176
+ [0.1.0]: https://github.com/Artui/django-spec-html/compare/v0.0.0...v0.1.0
@@ -7,9 +7,10 @@ Guidance for working in this repository.
7
7
  A `django-service-specs` spec served as a server-rendered page. `SpecFormView`
8
8
  renders a spec's form, validates a post through it, runs the kernel's
9
9
  `dispatch`, and answers as a plain form post: a redirect on a success, and the
10
- page again with the refusal on its form. It reads no htmx header, so an htmx
11
- request is answered the same way; a fragment for one is planned for 0.2.0 and
12
- not built.
10
+ page again with the refusal on its form. An htmx request decides the same
11
+ outcome and is answered with a fragment of the page instead: the form at 200 for
12
+ a refusal the page re-renders, `HX-Redirect` or a result fragment for a success,
13
+ and a denial raised in both modes.
13
14
  Beside the pages, `http/` serves a spec as plain-Django JSON (`SpecView`,
14
15
  `AsyncSpecView`, `dispatch_request`, `error_response`, `request_arguments`), for
15
16
  a client that wants JSON with no API framework.
@@ -74,7 +75,8 @@ Non-negotiable. They keep the package navigable, and they are the kernel's.
74
75
  | Subpackage | Holds |
75
76
  | --- | --- |
76
77
  | `views/` | `SpecFormView`, a spec served as the page its form is, and the private readers it alone uses (the form's widgets, the target, the refused render) |
77
- | `http/` | the JSON views (`SpecView`, `AsyncSpecView`, `dispatch_request`, `adispatch_request`), `error_response`, and the request readers both halves use: `request_arguments`, `route_arguments`, `request_principal`, `add_argument_errors`; `UnsupportedMediaType`, beside its raiser; `utils.py` for `SpecViewBase`, the helpers the entry points share, and `REFUSAL_STATUSES`, the status map the page reads too |
78
+ | `types/` | `Outcome`, the ways a page's post ends; it imports nothing else in the package (rule 8) |
79
+ | `http/` | the JSON views (`SpecView`, `AsyncSpecView`, `dispatch_request`, `adispatch_request`), `error_response`, and the request readers both halves use: `request_arguments`, `route_arguments`, `request_principal`, `add_argument_errors`; `UnsupportedMediaType`, beside its raiser; `utils.py` for `SpecViewBase`, the helpers the entry points share, and `REFUSAL_STATUSES`, the status map the page reads too, with each refusal's `Outcome` |
78
80
 
79
81
  `views/` imports `http/`, never the reverse. The root re-exports both
80
82
  subpackages' `__all__` and `__version__`, and `tests/test_init.py` holds that.
@@ -94,7 +96,7 @@ Each of these reads as an oversight and is not.
94
96
  - **The test settings list no kernel app.** The package needs nothing of the
95
97
  kernel switched on, and the suite shows it.
96
98
  - **The kernel no longer ships these names.** `django_service_specs.http` and
97
- its ten root names are gone from kernel 0.12.0, which is the floor, so an
99
+ its ten root names are gone from kernel 0.12.0, below the floor, so an
98
100
  import left pointing at the kernel fails at import rather than resolving to
99
101
  a second copy. `tests/test_init.py` holds that absence, and would fail on a
100
102
  floor lowered past the removal.
@@ -171,7 +173,7 @@ configured and enforced. isort order is stdlib, third party, first party.
171
173
  | --- | --- | --- |
172
174
  | Python | 3.10 | 3.10 through 3.14 |
173
175
  | Django | 4.2 | 4.2, 5.0, 5.1, 5.2, 6.0, 6.1 |
174
- | django-service-specs | 0.12.0 | the newest release, and the floor in the `floor` job |
176
+ | django-service-specs | 0.15.0 | the newest release, and the floor in the `floor` job |
175
177
 
176
178
  The Python and Django floors are the kernel's, and cannot sit below them.
177
179
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: django-spec-html
3
- Version: 0.1.2
3
+ Version: 0.2.0
4
4
  Summary: A django-service-specs spec as a server-rendered page, served as a plain form post, plus the plain-Django JSON views.
5
5
  Project-URL: Homepage, https://github.com/Artui/django-spec-html
6
6
  Project-URL: Repository, https://github.com/Artui/django-spec-html
@@ -30,7 +30,7 @@ Classifier: Programming Language :: Python :: 3.13
30
30
  Classifier: Programming Language :: Python :: 3.14
31
31
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
32
32
  Requires-Python: >=3.10
33
- Requires-Dist: django-service-specs>=0.12.0
33
+ Requires-Dist: django-service-specs>=0.15.0
34
34
  Requires-Dist: django>=4.2
35
35
  Description-Content-Type: text/markdown
36
36
 
@@ -50,10 +50,11 @@ A [`django-service-specs`](https://github.com/Artui/django-service-specs) spec
50
50
  served over plain Django, with no API framework between the request and the
51
51
  kernel's `dispatch`. `SpecFormView` serves a spec whose Validator is a Django
52
52
  form as the page a person fills that form in on, and a refused post comes back
53
- as the page again with the refusal placed on its form. The page reads no htmx
54
- header: an htmx post is answered as any other, so a success is a redirect the
55
- request follows and a refusal is the whole page at a 4xx status, which htmx
56
- does not swap by default. A fragment answer for htmx is planned for 0.2.0.
53
+ as the page again with the refusal placed on its form. An htmx request is
54
+ answered with a fragment of the same page at the same URL: a refusal the page
55
+ re-renders is the form at 200, since htmx swaps no 4xx by default, a denial is
56
+ raised for the host's handlers as on the page, and a success is `HX-Redirect`
57
+ or a result fragment rendered in place.
57
58
  Beside the pages, `SpecView`, `AsyncSpecView` and `dispatch_request` serve a
58
59
  spec as JSON, for a script or a `fetch()`.
59
60
 
@@ -70,7 +71,7 @@ longer ships these names: import them from `django_spec_html`.
70
71
  pip install django-spec-html
71
72
  ```
72
73
 
73
- Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.12.0 or
74
+ Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.15.0 or
74
75
  later, which it installs. Neither package needs an entry in `INSTALLED_APPS`.
75
76
 
76
77
  ## Quickstart
@@ -14,10 +14,11 @@ A [`django-service-specs`](https://github.com/Artui/django-service-specs) spec
14
14
  served over plain Django, with no API framework between the request and the
15
15
  kernel's `dispatch`. `SpecFormView` serves a spec whose Validator is a Django
16
16
  form as the page a person fills that form in on, and a refused post comes back
17
- as the page again with the refusal placed on its form. The page reads no htmx
18
- header: an htmx post is answered as any other, so a success is a redirect the
19
- request follows and a refusal is the whole page at a 4xx status, which htmx
20
- does not swap by default. A fragment answer for htmx is planned for 0.2.0.
17
+ as the page again with the refusal placed on its form. An htmx request is
18
+ answered with a fragment of the same page at the same URL: a refusal the page
19
+ re-renders is the form at 200, since htmx swaps no 4xx by default, a denial is
20
+ raised for the host's handlers as on the page, and a success is `HX-Redirect`
21
+ or a result fragment rendered in place.
21
22
  Beside the pages, `SpecView`, `AsyncSpecView` and `dispatch_request` serve a
22
23
  spec as JSON, for a script or a `fetch()`.
23
24
 
@@ -34,7 +35,7 @@ longer ships these names: import them from `django_spec_html`.
34
35
  pip install django-spec-html
35
36
  ```
36
37
 
37
- Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.12.0 or
38
+ Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.15.0 or
38
39
  later, which it installs. Neither package needs an entry in `INSTALLED_APPS`.
39
40
 
40
41
  ## Quickstart
@@ -1,8 +1,9 @@
1
1
  """A django-service-specs spec as a server-rendered page, plus the plain-Django JSON views.
2
2
 
3
3
  ``views`` serves a spec as the page its form is, and ``http`` serves one as
4
- JSON with nothing between the request and the kernel's ``dispatch``. Every
5
- public name of both is here; read them from the root.
4
+ JSON with nothing between the request and the kernel's ``dispatch``. ``types``
5
+ holds ``Outcome``, the vocabulary a page's post ends in. Every public name of
6
+ the three is here; read them from the root.
6
7
  """
7
8
 
8
9
  from django_spec_html.http.add_argument_errors import add_argument_errors
@@ -15,11 +16,13 @@ from django_spec_html.http.request_principal import request_principal
15
16
  from django_spec_html.http.route_arguments import route_arguments
16
17
  from django_spec_html.http.spec_view import SpecView
17
18
  from django_spec_html.http.unsupported_media_type import UnsupportedMediaType
19
+ from django_spec_html.types.outcome import Outcome
18
20
  from django_spec_html.version import __version__
19
21
  from django_spec_html.views.spec_form_view import SpecFormView
20
22
 
21
23
  __all__ = [
22
24
  "AsyncSpecView",
25
+ "Outcome",
23
26
  "SpecFormView",
24
27
  "SpecView",
25
28
  "UnsupportedMediaType",
@@ -13,11 +13,13 @@ from django_service_specs import (
13
13
  Grant,
14
14
  PoolSeeds,
15
15
  SelectorSpec,
16
+ ServerArguments,
16
17
  ServiceError,
17
18
  ServiceSpec,
18
19
  SpecSource,
19
20
  UnknownArguments,
20
21
  adispatch,
22
+ apply_server_arguments,
21
23
  apresent,
22
24
  kernel_spec,
23
25
  )
@@ -37,6 +39,8 @@ async def adispatch_request(
37
39
  request: HttpRequest,
38
40
  *,
39
41
  url_kwargs: Mapping[str, Any] | None = None,
42
+ route_kwargs: Mapping[str, str | None] | tuple[str, ...] | None = None,
43
+ server_arguments: ServerArguments | None = None,
40
44
  success_status: int | None = None,
41
45
  grant: Grant | None = None,
42
46
  pool_seeds: PoolSeeds = DEFAULT_POOL_SEEDS,
@@ -54,7 +58,8 @@ async def adispatch_request(
54
58
  AuthenticationMiddleware leaves, and its first read is a session query,
55
59
  which Django refuses on the loop; Django 4.2, the floor, has no
56
60
  ``request.auser()`` to await instead. ``spec.parameters()`` goes in the
57
- same hop, because a Validator may read a model to declare what it takes.
61
+ same hop, because a Validator may read a model to declare what it takes,
62
+ and so does applying ``server_arguments``, which reads it again.
58
63
  Building the response does not query and stays on the loop.
59
64
  """
60
65
  # Compiled once, before anything is read, so the arguments, the answer's
@@ -62,7 +67,7 @@ async def adispatch_request(
62
67
  spec = kernel_spec(spec)
63
68
  try:
64
69
  principal, arguments = await sync_to_async(_read_request, thread_sensitive=True)(
65
- spec, request, url_kwargs
70
+ spec, request, url_kwargs, route_kwargs, server_arguments
66
71
  )
67
72
  result = await adispatch(
68
73
  spec,
@@ -84,6 +89,8 @@ def _read_request(
84
89
  spec: ServiceSpec | SelectorSpec,
85
90
  request: HttpRequest,
86
91
  url_kwargs: Mapping[str, Any] | None,
92
+ route_kwargs: Mapping[str, str | None] | tuple[str, ...] | None,
93
+ server_arguments: ServerArguments | None,
87
94
  ) -> tuple[Any, dict[str, Any]]:
88
95
  """The principal, then the arguments, in the one executor hop they share.
89
96
 
@@ -91,7 +98,17 @@ def _read_request(
91
98
  its shape check, so a deactivated account is refused without learning
92
99
  anything about its request. Both off the loop: the principal may be a
93
100
  session query, and ``spec.parameters()`` may be one too, since a
94
- Validator may read a model to declare what it takes.
101
+ Validator may read a model to declare what it takes. Applying the server's
102
+ values reads ``spec.parameters()`` again, so it is in the same hop.
95
103
  """
96
104
  principal = request_principal(request)
97
- return principal, request_arguments(request, spec.parameters(), url_kwargs=url_kwargs)
105
+ arguments = request_arguments(
106
+ request,
107
+ spec.parameters(),
108
+ url_kwargs=url_kwargs,
109
+ route_kwargs=route_kwargs,
110
+ server_arguments=server_arguments,
111
+ )
112
+ if server_arguments is not None:
113
+ arguments = apply_server_arguments(spec, arguments, server_arguments)
114
+ return principal, arguments
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from typing import Any
6
6
 
7
+ from asgiref.sync import sync_to_async
7
8
  from django.http import HttpRequest, HttpResponse
8
9
 
9
10
  from django_spec_html.http.adispatch_request import adispatch_request
@@ -22,18 +23,28 @@ class AsyncSpecView(SpecViewBase):
22
23
  kernel needs one; under WSGI Django runs it in an event loop of its own,
23
24
  which costs more than ``SpecView`` and buys nothing.
24
25
 
26
+ ``get_pool_seeds`` and ``get_server_arguments`` stay sync methods, run
27
+ in an executor hop of their own before dispatch, so an override reading
28
+ ``request.user`` or a model is never a query on the event loop.
29
+ ``as_view()`` refuses an ``async def`` one, which would never be awaited.
30
+
25
31
  Not a subclass of ``SpecView``, for the same reason: an async handler
26
32
  cannot stand in for a sync one.
27
33
  """
28
34
 
29
35
  async def answer(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
30
36
  """Dispatch the spec from async code, the route's kwargs as ``url_kwargs``."""
37
+ # The hooks off the loop: a host's override may read ``request.user``,
38
+ # which is a session query the first time it is read.
39
+ server, pool_seeds = await sync_to_async(self.served_hooks, thread_sensitive=True)(request)
31
40
  return await adispatch_request(
32
41
  self.served_spec(),
33
42
  request,
34
43
  url_kwargs=kwargs,
44
+ route_kwargs=self.route_kwargs,
45
+ server_arguments=server,
35
46
  success_status=self.success_status,
36
- pool_seeds=self.pool_seeds,
47
+ pool_seeds=pool_seeds,
37
48
  unknown_arguments=self.unknown_arguments,
38
49
  )
39
50
 
@@ -12,10 +12,12 @@ from django_service_specs import (
12
12
  Grant,
13
13
  PoolSeeds,
14
14
  SelectorSpec,
15
+ ServerArguments,
15
16
  ServiceError,
16
17
  ServiceSpec,
17
18
  SpecSource,
18
19
  UnknownArguments,
20
+ apply_server_arguments,
19
21
  dispatch,
20
22
  kernel_spec,
21
23
  present,
@@ -36,6 +38,8 @@ def dispatch_request(
36
38
  request: HttpRequest,
37
39
  *,
38
40
  url_kwargs: Mapping[str, Any] | None = None,
41
+ route_kwargs: Mapping[str, str | None] | tuple[str, ...] | None = None,
42
+ server_arguments: ServerArguments | None = None,
39
43
  success_status: int | None = None,
40
44
  grant: Grant | None = None,
41
45
  pool_seeds: PoolSeeds = DEFAULT_POOL_SEEDS,
@@ -51,7 +55,16 @@ def dispatch_request(
51
55
  the same rule; refusing here as well keeps the request unread for it.
52
56
  2. **The arguments** are
53
57
  [`request_arguments`][django_spec_html.http.request_arguments.request_arguments]
54
- for ``spec.parameters()``, with ``url_kwargs`` merged last.
58
+ for ``spec.parameters()``, with ``url_kwargs`` merged last under the
59
+ names ``route_kwargs`` maps them to, and ``server_arguments`` applied
60
+ over them by the kernel's
61
+ [`apply_server_arguments`][django_service_specs.dispatch.apply_server_arguments.apply_server_arguments]:
62
+ its bound values outrank whatever the client sent, and its withheld
63
+ names are dropped. A URL kwarg filling one of its names is refused,
64
+ as the host's misconfiguration. The binding is not checked here:
65
+ a host's own view calls
66
+ [`check_server_arguments`][django_service_specs.dispatch.check_server_arguments.check_server_arguments]
67
+ once, when it is built, as ``SpecView.as_view()`` does.
55
68
  3. [`dispatch`][django_service_specs.dispatch.dispatch.dispatch], with
56
69
  ``grant``, ``pool_seeds`` and ``unknown_arguments`` as given.
57
70
  4. **The answer.** A not-found result is 404 with a ``detail``. Otherwise
@@ -63,9 +76,11 @@ def dispatch_request(
63
76
  [`error_response`][django_spec_html.http.error_response.error_response].
64
77
  Anything else propagates, a configuration error included: it is wrong for
65
78
  every caller, so it belongs to the host's error handling rather than to one
66
- client's response. A URL kwarg ``spec`` does not declare is one, raised
67
- as ``ImproperlyConfigured``: every URL kwarg is an argument, and the route
68
- is the host's.
79
+ client's response. A URL kwarg ``spec`` does not declare, and that
80
+ ``route_kwargs`` neither renames nor drops, is one, raised as
81
+ ``ImproperlyConfigured``: every URL kwarg is an argument, and the route
82
+ is the host's. So is a bound value its parameter refuses: the client
83
+ neither sent it nor can see it.
69
84
 
70
85
  ``spec`` may be a
71
86
  [`SpecSource`][django_service_specs.specs.spec_source.SpecSource]: it is
@@ -81,7 +96,15 @@ def dispatch_request(
81
96
  # check: a deactivated account is refused without learning anything
82
97
  # about its request.
83
98
  principal = request_principal(request)
84
- arguments = request_arguments(request, spec.parameters(), url_kwargs=url_kwargs)
99
+ arguments = request_arguments(
100
+ request,
101
+ spec.parameters(),
102
+ url_kwargs=url_kwargs,
103
+ route_kwargs=route_kwargs,
104
+ server_arguments=server_arguments,
105
+ )
106
+ if server_arguments is not None:
107
+ arguments = apply_server_arguments(spec, arguments, server_arguments)
85
108
  result = dispatch(
86
109
  spec,
87
110
  principal=principal,
@@ -17,6 +17,7 @@ from django_service_specs import (
17
17
  InvalidArguments,
18
18
  Parameter,
19
19
  Parameters,
20
+ ServerArguments,
20
21
  coerce_flat,
21
22
  expected_type_refusal,
22
23
  max_length_in_force,
@@ -24,6 +25,7 @@ from django_service_specs import (
24
25
 
25
26
  from django_spec_html.http.route_arguments import route_arguments
26
27
  from django_spec_html.http.unsupported_media_type import UnsupportedMediaType
28
+ from django_spec_html.http.utils import refuse_server_owned, server_names, without
27
29
 
28
30
  _CSRF_FIELD = "csrfmiddlewaretoken"
29
31
  """The field ``{% csrf_token %}`` renders into a form: Django's, and never an argument."""
@@ -40,7 +42,12 @@ _MULTIPART = "multipart/form-data"
40
42
 
41
43
 
42
44
  def request_arguments(
43
- request: HttpRequest, parameters: Parameters, *, url_kwargs: Mapping[str, Any] | None = None
45
+ request: HttpRequest,
46
+ parameters: Parameters,
47
+ *,
48
+ url_kwargs: Mapping[str, Any] | None = None,
49
+ route_kwargs: Mapping[str, str | None] | tuple[str, ...] | None = None,
50
+ server_arguments: ServerArguments | None = None,
44
51
  ) -> dict[str, Any]:
45
52
  """The arguments a request carries for ``parameters``, typed as a JSON caller would send them.
46
53
 
@@ -109,7 +116,22 @@ def request_arguments(
109
116
  move the route's scope, so ``/notes/4/`` with ``pk=9`` in its body is about
110
117
  note 4. On a flat request the two are coerced together, so every refusal
111
118
  comes back at once and a clashing client value the route replaced is
112
- never refused.
119
+ never refused. ``route_kwargs`` says which URL kwargs fill which
120
+ parameters, renaming or dropping the rest, as
121
+ [`route_arguments`][django_spec_html.http.route_arguments.route_arguments]
122
+ reads it.
123
+
124
+ **Every name** ``server_arguments`` **answers for is dropped** from what
125
+ the client sent, before anything is coerced, so a client's ``?owner=abc``
126
+ for a bound integer is never refused as the client's 400 for a name it was
127
+ never offered. **A URL kwarg filling one is refused** instead, as the
128
+ host's misconfiguration: the route is the host's, and it may not
129
+ contradict the host's own binding, so a capture the spec should not read
130
+ is dropped explicitly, with ``route_kwargs={name: None}``. Only the names are read
131
+ here: the values are laid by the kernel's
132
+ [`apply_server_arguments`][django_service_specs.dispatch.apply_server_arguments.apply_server_arguments],
133
+ which needs the spec to check them, so a host's own view passes the result
134
+ through it, as ``dispatch_request`` does.
113
135
 
114
136
  Raises:
115
137
  InvalidArguments: a JSON body that does not parse or is not an object,
@@ -117,18 +139,25 @@ def request_arguments(
117
139
  its parameter's name.
118
140
  UnsupportedMediaType: a body that is neither JSON nor a form.
119
141
  ImproperlyConfigured: a URL kwarg ``parameters`` does not declare,
120
- which is the host's route rather than the client's request; see
142
+ a ``route_kwargs`` naming a parameter they do not, or a URL
143
+ kwarg filling a name ``server_arguments`` answers for, which is
144
+ the host's route rather than the client's request; see
121
145
  [`route_arguments`][django_spec_html.http.route_arguments.route_arguments].
122
146
  """
123
- route = route_arguments(parameters, url_kwargs)
147
+ route = route_arguments(parameters, url_kwargs, route_kwargs=route_kwargs)
148
+ owned = server_names(server_arguments)
149
+ refuse_server_owned(url_kwargs, route_kwargs, owned)
124
150
  if request.method in ("GET", "HEAD"):
125
- return coerce_flat(parameters, {**_flat(parameters, request.GET), **route})
151
+ read = {**_flat(parameters, request.GET), **route}
152
+ return coerce_flat(parameters, without(read, owned))
126
153
  if request.content_type == "application/json":
127
- return {**_json_object(request), **coerce_flat(parameters, route)}
154
+ return {
155
+ **without(_json_object(request), owned),
156
+ **coerce_flat(parameters, route),
157
+ }
128
158
  fields, uploads = _form(request)
129
- return coerce_flat(
130
- parameters, {**_flat(parameters, fields), **_uploads(parameters, uploads), **route}
131
- )
159
+ read = {**_flat(parameters, fields), **_uploads(parameters, uploads), **route}
160
+ return coerce_flat(parameters, without(read, owned))
132
161
 
133
162
 
134
163
  def _flat(parameters: Parameters, source: QueryDict) -> dict[str, Any]: