django-api-versioning 1.0.1__tar.gz → 1.1.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 (48) hide show
  1. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/CHANGELOG.md +30 -1
  2. {django_api_versioning-1.0.1/django_api_versioning.egg-info → django_api_versioning-1.1.0}/PKG-INFO +53 -10
  3. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/README.md +52 -9
  4. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/lifecycle.py +16 -8
  5. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/management/commands/check_versions.py +22 -2
  6. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/registry.py +49 -0
  7. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/reverse.py +15 -8
  8. django_api_versioning-1.1.0/django_api_versioning/routers.py +293 -0
  9. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/settings.py +39 -2
  10. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/testing.py +48 -16
  11. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0/django_api_versioning.egg-info}/PKG-INFO +53 -10
  12. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/SOURCES.txt +2 -0
  13. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/pyproject.toml +1 -1
  14. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_lifecycle.py +91 -7
  15. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_management_commands.py +10 -0
  16. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_registry.py +160 -1
  17. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_reverse.py +46 -1
  18. django_api_versioning-1.1.0/tests/test_routers.py +303 -0
  19. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_settings.py +71 -1
  20. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_testing_utils.py +45 -0
  21. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/LICENSE +0 -0
  22. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/MANIFEST.in +0 -0
  23. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/__init__.py +0 -0
  24. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/channels.py +0 -0
  25. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/decorators.py +0 -0
  26. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/exceptions.py +0 -0
  27. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/management/__init__.py +0 -0
  28. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/management/commands/__init__.py +0 -0
  29. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/management/commands/migrate_endpoints.py +0 -0
  30. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/py.typed +0 -0
  31. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning/urls.py +0 -0
  32. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
  33. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/requires.txt +0 -0
  34. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/top_level.txt +0 -0
  35. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/pytest.ini +0 -0
  36. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/requirements-dev.txt +0 -0
  37. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/requirements.txt +0 -0
  38. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/setup.cfg +0 -0
  39. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/__init__.py +0 -0
  40. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/conftest.py +0 -0
  41. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/settings.py +0 -0
  42. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_channels.py +0 -0
  43. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_channels_extra.py +0 -0
  44. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_decorators.py +0 -0
  45. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_distribution_contents.py +0 -0
  46. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_exceptions.py +0 -0
  47. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_segment_model.py +0 -0
  48. {django_api_versioning-1.0.1 → django_api_versioning-1.1.0}/tests/test_urls.py +0 -0
@@ -1,4 +1,3 @@
1
-
2
1
  # Changelog
3
2
 
4
3
  All notable changes to this project will be documented in this file.
@@ -8,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8
7
 
9
8
  ## [Unreleased]
10
9
 
10
+ ## [1.1.0] - 2026-11-18
11
+
12
+ ### Added
13
+
14
+ - Add the optional `VersionedRouter` integration for DRF `SimpleRouter` ViewSets, preserving standard routes, custom actions, callback metadata, and per-route version inheritance.
15
+ - Add `VersionedRouterVersioning` to expose the concrete router namespace as DRF's `request.version` and keep `reverse_action()` and hyperlinked serializer URLs within the active version.
16
+ - Preserve regex-backed and path-converter URLPatterns in the registry; extend `api_reverse()` to reverse DRF regex routes through Django's URL resolver and reject duplicate names within one concrete version.
17
+
18
+ ### Changed
19
+
20
+ - Extend lifecycle version extraction to recognize the configured API base path below parent URL prefixes, so nested URL includes retain deprecation and sunset behavior.
21
+ - Clarify that `API_VERSIONING_CHANNELS` and `API_EFFECTIVE_VERSION_RESOLVER` are reserved settings with no runtime effect; log a warning when non-default values are configured.
22
+
23
+ ### Fixed
24
+
25
+ - Add opt-in strict route-matrix assertions that reject empty registries and missing committed snapshots while preserving existing default behavior; add `check_versions --fail-on-empty` and resolve root and included URLconfs before inspecting registered endpoints.
26
+ - Reject deprecated or retired lifecycle configurations where `sunset` is earlier than `deprecated_at`, comparing dates as UTC instants and interpreting timezone-naive ISO 8601 values as UTC.
27
+ - `LifecycleMiddleware` now sends the `Sunset` header (and `Deprecation`, when `deprecated_at` is configured) for `retired` versions whose `sunset` date is still in the future. Previously these responses carried no lifecycle headers even though the version was about to be removed. Retired versions with a past `sunset` still return `410 Gone`, and `active` and unknown versions are unchanged.
28
+
29
+ ### Testing
30
+
31
+ - Pin Django REST Framework independently in tox for each Django compatibility line: DRF 3.17.2 for Django 4.2 and DRF 3.18.x for Django 5.2, 6.0, and 6.1. The compatibility matrix verifies these tested Django/DRF combinations.
32
+ - Verify the built wheel in isolation, distribution contents, and website artifacts as part of the release workflow.
33
+
34
+ ### Documentation
35
+
36
+ - Add a request-version-resolution architecture decision that documents the current path-only contract, research findings, and implementation gates for any future negotiation support.
37
+ - Clarify that Django 4.2 remains in the 1.x compatibility matrix for existing installations but is no longer a supported Django security-release line; recommend a currently supported Django version for new deployments.
38
+ - Document the VersionedRouter setup, per-route inheritance, namespace-aware reversal, and the explicit boundaries of the initial SimpleRouter integration.
39
+
11
40
  ## [1.0.1] - 2026-11-17
12
41
 
13
42
  ### Documentation
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: django-api-versioning
3
- Version: 1.0.1
3
+ Version: 1.1.0
4
4
  Summary: URL-path API versioning for Django and Django REST Framework with decorator-based endpoint registration and forward route inheritance.
5
5
  Author-email: Mojtaba Arvin <ArvinDevDay@gmail.com>
6
6
  License-Expression: MIT
@@ -116,17 +116,17 @@ Django API Versioning makes that mapping explicit with `@endpoint`:
116
116
  - **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
117
117
  - **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
118
118
  - **Explicit registration:** use `versions=[...]` or `ver_range(...)` when an endpoint should exist only in selected versions.
119
- - **Visibility:** inspect the generated route matrix with `check_versions` and test it with `assert_version_matrix()`.
119
+ - **Visibility:** inspect the generated route matrix with `python manage.py check_versions --fail-on-empty` and guard it with `assert_version_matrix(snapshot=".version_matrix.json", strict=True)`.
120
120
 
121
121
  This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
122
122
 
123
123
  ## Why use it with Django REST Framework?
124
124
 
125
- DRF already provides versioning schemes to identify the requested API version, for example through `request.version`. This package solves a related but different problem: **mapping versioned URL paths to specific view implementations and carrying unchanged registrations forward**.
125
+ DRF already provides request-version identification and ViewSet route generation. Django API Versioning adds the missing connection between those capabilities: **mapping each concrete API version to the correct ViewSet implementation while inheriting unchanged routes independently**.
126
126
 
127
- Use DRF's built-in versioning when request-version identification is all you need. Use this package when you want declarative version-to-view routing and an inspectable route matrix. They can be used together; this package does not automatically populate `request.version`.
127
+ For Django-native function-based and class-based views, use `@endpoint`. For DRF `ViewSet` and `ModelViewSet` classes, use the optional `VersionedRouter`. It delegates route generation to DRF's `SimpleRouter`, preserving standard actions, custom `@action` routes, lookup behavior, and action-level configuration.
128
128
 
129
- DRF is optional. The package also supports Django function-based and class-based views. For a Django-only project, install just:
129
+ The optional `VersionedRouterVersioning` adapter exposes the selected version as DRF's `request.version` and keeps `reverse_action()` and hyperlinked serializers version-aware. DRF remains optional for projects that use only Django-native views. For those projects, install just:
130
130
 
131
131
  ```bash
132
132
  pip install django-api-versioning
@@ -180,19 +180,61 @@ For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()
180
180
 
181
181
  See the [versioning contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) for exact URL construction, import order, collision precedence, validation, and edge cases.
182
182
 
183
- ## DRF ViewSet boundary
183
+ ## Versioned DRF ViewSets
184
184
 
185
- A DRF `ViewSet` or `ModelViewSet` cannot be passed directly to `@endpoint`, because `as_view()` requires an action mapping. You can register a configured callable for an individual route, but this does not create the full router-managed set of list, detail, and custom-action routes. Use DRF's `DefaultRouter` or `SimpleRouter` when you need standard ViewSet routing.
185
+ Use `VersionedRouter` when you want DRF's normal ViewSet workflow with version-aware implementation dispatch:
186
186
 
187
- See [ViewSet support and limitations](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/).
187
+ ```python
188
+ # settings.py — configure before importing ViewSet modules
189
+ REST_FRAMEWORK = {
190
+ "DEFAULT_VERSIONING_CLASS": (
191
+ "django_api_versioning.routers.VersionedRouterVersioning"
192
+ ),
193
+ }
194
+ ```
195
+
196
+ ```python
197
+ # project/urls.py
198
+ from django_api_versioning.routers import VersionedRouter
199
+ from orders.views import OrderViewSetV1, OrderViewSetV2
200
+
201
+ router = VersionedRouter()
202
+ router.register("orders", OrderViewSetV1, version=1, basename="order")
203
+ router.register("orders", OrderViewSetV2, version=2, basename="order")
204
+
205
+ urlpatterns = router.urls
206
+ ```
207
+
208
+ With `API_MAX_VERSION = 3`, the routes are served at `/api/v1/orders/`, `/api/v2/orders/`, and `/api/v3/orders/`. V2 replaces only the generated routes it declares. If a custom action exists in V1 but is not redeclared in V2, that action remains inherited in v2 and v3 while list/detail can use V2.
209
+
210
+ For endpoints that should exist only in selected versions, pass `versions=[1, 3]`; v2 remains a 404. The router also supports `trailing_slash=False` and `use_regex_path=False` for Django path converters.
211
+
212
+ The adapter is required when ViewSets need `request.version`, `reverse_action()`, or hyperlinked serializer support. You can configure it globally through `REST_FRAMEWORK` as shown above, or set `versioning_class = VersionedRouterVersioning` on selected ViewSets.
213
+
214
+ **Scope:** the initial integration supports DRF `SimpleRouter`; it does not claim `DefaultRouter` API-root or format-suffix parity. It does not transform serializers or response payloads. A route omitted from a later ViewSet remains inherited; explicit route removal is tracked separately in [Issue #39](https://github.com/mojtaba-arvin/django-api-versioning/issues/39). Header/query/tenant negotiation is not enabled by the reserved settings and remains a separate design decision.
215
+
216
+ For DRF installation, use a version compatible with your Django release:
217
+ ```bash
218
+ # Django 4.2 compatibility
219
+ pip install "djangorestframework>=3.17.2,<3.18"
220
+
221
+ # Django 5.2, 6.0, or 6.1
222
+ pip install "djangorestframework>=3.18.3,<3.19"
223
+ ```
224
+
225
+ See the [Versioned DRF ViewSet guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/) for route inheritance, reversal, namespaces, and the exact integration boundary.
188
226
 
189
227
  ## Requirements
190
228
 
191
229
  - Python 3.10+
192
- - Django 4.2+
230
+ - Django 4.2+ (retained for compatibility with existing 1.x installations)
193
231
  - Django REST Framework is optional.
194
232
 
195
- The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. See [tox.ini](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini) for configured environments and [GitHub Actions](https://github.com/mojtaba-arvin/django-api-versioning/actions) for results tied to a specific commit.
233
+ **For new deployments, use a currently supported Django release, preferably Django 5.2 LTS or later.** Django 4.2 reached the end of extended support on 7 April 2026. It remains in this package's compatibility matrix for existing projects, but no longer receives Django security fixes. See [Django's supported versions](https://www.djangoproject.com/download/#supported-versions).
234
+
235
+ The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. DRF is tested against versions supported by each upstream combination: DRF 3.17.2 on Django 4.2, and DRF 3.18.x on Django 5.2, 6.0, and 6.1. DRF 3.18 dropped Django 4.2, so these lines are deliberately pinned separately rather than relying on an unbounded latest version.
236
+
237
+ See [tox.ini](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini) for configured environments and [GitHub Actions](https://github.com/mojtaba-arvin/django-api-versioning/actions) for results tied to a specific commit.
196
238
 
197
239
  ## Upgrading to 1.0.0
198
240
 
@@ -213,6 +255,7 @@ For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/
213
255
  - [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
214
256
  - [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
215
257
  - [Documentation source map](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/README.md).
258
+ - [Request version resolution decision](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/request-version-resolution.md) — why path-based handler selection remains the current contract and what a safe future negotiation design requires.
216
259
 
217
260
  ## Contributing
218
261
 
@@ -66,17 +66,17 @@ Django API Versioning makes that mapping explicit with `@endpoint`:
66
66
  - **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
67
67
  - **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
68
68
  - **Explicit registration:** use `versions=[...]` or `ver_range(...)` when an endpoint should exist only in selected versions.
69
- - **Visibility:** inspect the generated route matrix with `check_versions` and test it with `assert_version_matrix()`.
69
+ - **Visibility:** inspect the generated route matrix with `python manage.py check_versions --fail-on-empty` and guard it with `assert_version_matrix(snapshot=".version_matrix.json", strict=True)`.
70
70
 
71
71
  This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
72
72
 
73
73
  ## Why use it with Django REST Framework?
74
74
 
75
- DRF already provides versioning schemes to identify the requested API version, for example through `request.version`. This package solves a related but different problem: **mapping versioned URL paths to specific view implementations and carrying unchanged registrations forward**.
75
+ DRF already provides request-version identification and ViewSet route generation. Django API Versioning adds the missing connection between those capabilities: **mapping each concrete API version to the correct ViewSet implementation while inheriting unchanged routes independently**.
76
76
 
77
- Use DRF's built-in versioning when request-version identification is all you need. Use this package when you want declarative version-to-view routing and an inspectable route matrix. They can be used together; this package does not automatically populate `request.version`.
77
+ For Django-native function-based and class-based views, use `@endpoint`. For DRF `ViewSet` and `ModelViewSet` classes, use the optional `VersionedRouter`. It delegates route generation to DRF's `SimpleRouter`, preserving standard actions, custom `@action` routes, lookup behavior, and action-level configuration.
78
78
 
79
- DRF is optional. The package also supports Django function-based and class-based views. For a Django-only project, install just:
79
+ The optional `VersionedRouterVersioning` adapter exposes the selected version as DRF's `request.version` and keeps `reverse_action()` and hyperlinked serializers version-aware. DRF remains optional for projects that use only Django-native views. For those projects, install just:
80
80
 
81
81
  ```bash
82
82
  pip install django-api-versioning
@@ -130,19 +130,61 @@ For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()
130
130
 
131
131
  See the [versioning contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) for exact URL construction, import order, collision precedence, validation, and edge cases.
132
132
 
133
- ## DRF ViewSet boundary
133
+ ## Versioned DRF ViewSets
134
134
 
135
- A DRF `ViewSet` or `ModelViewSet` cannot be passed directly to `@endpoint`, because `as_view()` requires an action mapping. You can register a configured callable for an individual route, but this does not create the full router-managed set of list, detail, and custom-action routes. Use DRF's `DefaultRouter` or `SimpleRouter` when you need standard ViewSet routing.
135
+ Use `VersionedRouter` when you want DRF's normal ViewSet workflow with version-aware implementation dispatch:
136
136
 
137
- See [ViewSet support and limitations](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/).
137
+ ```python
138
+ # settings.py — configure before importing ViewSet modules
139
+ REST_FRAMEWORK = {
140
+ "DEFAULT_VERSIONING_CLASS": (
141
+ "django_api_versioning.routers.VersionedRouterVersioning"
142
+ ),
143
+ }
144
+ ```
145
+
146
+ ```python
147
+ # project/urls.py
148
+ from django_api_versioning.routers import VersionedRouter
149
+ from orders.views import OrderViewSetV1, OrderViewSetV2
150
+
151
+ router = VersionedRouter()
152
+ router.register("orders", OrderViewSetV1, version=1, basename="order")
153
+ router.register("orders", OrderViewSetV2, version=2, basename="order")
154
+
155
+ urlpatterns = router.urls
156
+ ```
157
+
158
+ With `API_MAX_VERSION = 3`, the routes are served at `/api/v1/orders/`, `/api/v2/orders/`, and `/api/v3/orders/`. V2 replaces only the generated routes it declares. If a custom action exists in V1 but is not redeclared in V2, that action remains inherited in v2 and v3 while list/detail can use V2.
159
+
160
+ For endpoints that should exist only in selected versions, pass `versions=[1, 3]`; v2 remains a 404. The router also supports `trailing_slash=False` and `use_regex_path=False` for Django path converters.
161
+
162
+ The adapter is required when ViewSets need `request.version`, `reverse_action()`, or hyperlinked serializer support. You can configure it globally through `REST_FRAMEWORK` as shown above, or set `versioning_class = VersionedRouterVersioning` on selected ViewSets.
163
+
164
+ **Scope:** the initial integration supports DRF `SimpleRouter`; it does not claim `DefaultRouter` API-root or format-suffix parity. It does not transform serializers or response payloads. A route omitted from a later ViewSet remains inherited; explicit route removal is tracked separately in [Issue #39](https://github.com/mojtaba-arvin/django-api-versioning/issues/39). Header/query/tenant negotiation is not enabled by the reserved settings and remains a separate design decision.
165
+
166
+ For DRF installation, use a version compatible with your Django release:
167
+ ```bash
168
+ # Django 4.2 compatibility
169
+ pip install "djangorestframework>=3.17.2,<3.18"
170
+
171
+ # Django 5.2, 6.0, or 6.1
172
+ pip install "djangorestframework>=3.18.3,<3.19"
173
+ ```
174
+
175
+ See the [Versioned DRF ViewSet guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/) for route inheritance, reversal, namespaces, and the exact integration boundary.
138
176
 
139
177
  ## Requirements
140
178
 
141
179
  - Python 3.10+
142
- - Django 4.2+
180
+ - Django 4.2+ (retained for compatibility with existing 1.x installations)
143
181
  - Django REST Framework is optional.
144
182
 
145
- The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. See [tox.ini](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini) for configured environments and [GitHub Actions](https://github.com/mojtaba-arvin/django-api-versioning/actions) for results tied to a specific commit.
183
+ **For new deployments, use a currently supported Django release, preferably Django 5.2 LTS or later.** Django 4.2 reached the end of extended support on 7 April 2026. It remains in this package's compatibility matrix for existing projects, but no longer receives Django security fixes. See [Django's supported versions](https://www.djangoproject.com/download/#supported-versions).
184
+
185
+ The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. DRF is tested against versions supported by each upstream combination: DRF 3.17.2 on Django 4.2, and DRF 3.18.x on Django 5.2, 6.0, and 6.1. DRF 3.18 dropped Django 4.2, so these lines are deliberately pinned separately rather than relying on an unbounded latest version.
186
+
187
+ See [tox.ini](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini) for configured environments and [GitHub Actions](https://github.com/mojtaba-arvin/django-api-versioning/actions) for results tied to a specific commit.
146
188
 
147
189
  ## Upgrading to 1.0.0
148
190
 
@@ -163,6 +205,7 @@ For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/
163
205
  - [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
164
206
  - [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
165
207
  - [Documentation source map](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/README.md).
208
+ - [Request version resolution decision](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/request-version-resolution.md) — why path-based handler selection remains the current contract and what a safe future negotiation design requires.
166
209
 
167
210
  ## Contributing
168
211
 
@@ -78,10 +78,14 @@ class LifecycleMiddleware:
78
78
  )
79
79
 
80
80
  response = self.get_response(request)
81
- if meta.get("status") == "deprecated":
81
+ status = meta.get("status")
82
+ # A retired version whose sunset is still in the future is still served
83
+ # (past sunsets returned 410 above), so clients must be warned about the
84
+ # upcoming removal exactly like for a deprecated version.
85
+ if status in ("deprecated", "retired"):
82
86
  if deprecation_date is not None:
83
87
  response["Deprecation"] = _to_structured_field_date(deprecation_date)
84
- else:
88
+ elif status == "deprecated":
85
89
  logger.warning(
86
90
  "Deprecated API version %s has no valid deprecated_at date; "
87
91
  "omitting the Deprecation header.",
@@ -146,13 +150,14 @@ def _extract_version_from_path(request: HttpRequest) -> int | None:
146
150
  prefix = re.escape(parts[0])
147
151
  suffix = re.escape(parts[1])
148
152
 
149
- # Create anchored pattern to match only at the beginning of the relevant path.
150
- # The pattern may have a leading slash (from request.path_info), but API_BASE_PATH
151
- # typically doesn't, so we allow an optional leading slash.
152
- pattern = f"^/?{prefix}(\\d+){suffix}"
153
+ # The API may be mounted below a parent URL prefix via include(). Match
154
+ # API_BASE_PATH at a path-segment boundary rather than only at path start.
155
+ # This still avoids false positives such as "notapi/v2/".
156
+ prefix = prefix.lstrip("/")
157
+ pattern = f"(?:^|/){prefix}(\\d+){suffix}"
153
158
 
154
159
  try:
155
- regex_match = re.match(pattern, path)
160
+ regex_match = re.search(pattern, path)
156
161
  if regex_match:
157
162
  version_str = regex_match.group(1)
158
163
  return int(version_str)
@@ -174,7 +179,10 @@ def _parse_lifecycle_date(value: Any, field_name: str) -> datetime | None:
174
179
  return None
175
180
 
176
181
  try:
177
- parsed = datetime.fromisoformat(value)
182
+ # datetime.fromisoformat() only accepted the ISO 8601 UTC "Z" suffix
183
+ # starting with Python 3.11; normalize it for the Python 3.10 floor.
184
+ normalized_value = value[:-1] + "+00:00" if value.endswith("Z") else value
185
+ parsed = datetime.fromisoformat(normalized_value)
178
186
  except ValueError:
179
187
  logger.warning("Invalid %s date %r; ignoring.", field_name, value)
180
188
  return None
@@ -1,14 +1,28 @@
1
1
  from collections import defaultdict
2
2
 
3
- from django.core.management.base import BaseCommand
3
+ from django.core.management.base import BaseCommand, CommandError
4
4
 
5
5
  from ...registry import registry
6
+ from ...testing import _load_root_urlconf
6
7
 
7
8
 
8
9
  class Command(BaseCommand):
9
10
  help = "Print the API version matrix and warn about gaps."
10
11
 
12
+ def add_arguments(self, parser):
13
+ parser.add_argument(
14
+ "--fail-on-empty",
15
+ action="store_true",
16
+ help=(
17
+ "Exit with an error when no @endpoint declarations are registered. "
18
+ "The project's root URLconf is loaded first."
19
+ ),
20
+ )
21
+
11
22
  def handle(self, *args, **options):
23
+ # Resolve the root URLconf so imports of endpoint modules execute.
24
+ _load_root_urlconf()
25
+
12
26
  # Use logical version matrix to group by logical endpoint, not physical URL
13
27
  matrix = registry.get_logical_version_matrix()
14
28
  grouped = defaultdict(dict)
@@ -16,7 +30,13 @@ class Command(BaseCommand):
16
30
  grouped[endpoint] = versions
17
31
 
18
32
  if not grouped:
19
- self.stdout.write("No endpoints registered.")
33
+ message = (
34
+ "No endpoints registered. Check that the project's root URLconf "
35
+ "imports the modules containing @endpoint declarations."
36
+ )
37
+ self.stdout.write(message)
38
+ if options.get("fail_on_empty"):
39
+ raise CommandError(message)
20
40
  return
21
41
 
22
42
  for endpoint in sorted(grouped):
@@ -48,6 +48,55 @@ class UrlRegistry:
48
48
 
49
49
  self._sort_urlpatterns()
50
50
 
51
+ def register_urlpattern(
52
+ self,
53
+ pattern: URLPattern,
54
+ source_version: int | None = None,
55
+ route_version: int | None = None,
56
+ logical_endpoint: str | None = None,
57
+ ) -> None:
58
+ """Register an existing Django URLPattern without rebuilding it.
59
+
60
+ This is the lossless insertion path for integrations that generate
61
+ URLPatterns themselves (for example, DRF routers). The original
62
+ pattern, callback, converters, defaults, name, and callback metadata
63
+ are retained. Collision precedence is identical to ``register()``.
64
+ """
65
+ if not isinstance(pattern, URLPattern):
66
+ raise TypeError("pattern must be a django.urls.URLPattern instance.")
67
+
68
+ route_key = str(pattern.pattern)
69
+ route_index = self._find_route_index(route_key)
70
+
71
+ if route_index is not None:
72
+ existing_pattern = self.urlpatterns[route_index]
73
+ if not self._should_replace(existing_pattern, source_version):
74
+ return
75
+
76
+ setattr(pattern, self._SOURCE_VERSION_ATTR, source_version)
77
+ setattr(pattern, self._ROUTE_VERSION_ATTR, route_version)
78
+ if logical_endpoint is not None:
79
+ setattr(pattern, self._LOGICAL_ENDPOINT_ATTR, logical_endpoint)
80
+
81
+ if route_index is None:
82
+ self.urlpatterns.append(pattern)
83
+ else:
84
+ self.urlpatterns[route_index] = pattern
85
+
86
+ self._sort_urlpatterns()
87
+
88
+ def get_route_version(self, route: str) -> int | None:
89
+ """Return the concrete version registered for a resolved route."""
90
+ route_index = self._find_route_index(route)
91
+ if route_index is None:
92
+ return None
93
+
94
+ return getattr(
95
+ self.urlpatterns[route_index],
96
+ self._ROUTE_VERSION_ATTR,
97
+ None,
98
+ )
99
+
51
100
  def get_version_matrix(self) -> dict[str, dict[int | None, Callable]]:
52
101
  """
53
102
  Return ``{route: {route_version: callback}}``.
@@ -1,7 +1,8 @@
1
1
  import re
2
2
  from typing import Any
3
3
 
4
- from django.urls import NoReverseMatch
4
+ from django.urls import NoReverseMatch, get_script_prefix
5
+ from django.urls.resolvers import RegexPattern, URLResolver
5
6
 
6
7
  from .exceptions import AmbiguousVersionError, VersionTypeError
7
8
  from .registry import registry
@@ -43,18 +44,24 @@ def api_reverse(
43
44
  if version is None and len(matches) > 1:
44
45
  versions = sorted(v for v, _ in matches if v is not None)
45
46
  raise AmbiguousVersionError(
46
- f"View name {view_name!r} is registered for multiple versions "
47
- f"{versions}. Pass an explicit ``version``."
47
+ f"View name {view_name!r} is registered more than once for "
48
+ f"versions {versions}. Pass an explicit version."
49
+ )
50
+ if version is not None and len(matches) > 1:
51
+ raise NoReverseMatch(
52
+ f"View name {view_name!r} is registered more than once "
53
+ f"for version {version!r}."
48
54
  )
49
55
 
50
56
  _, target_pattern = matches[0]
51
57
  route_pattern = target_pattern.pattern
52
58
 
53
59
  if not hasattr(route_pattern, "_route"):
54
- raise NoReverseMatch(
55
- f"Pattern {route_pattern!r} does not support reverse by route; "
56
- f"only path()-based routes are supported."
57
- )
60
+ # DRF's default SimpleRouter generates RegexPattern instances. Delegate
61
+ # their reversal to Django's URLResolver rather than parsing regex
62
+ # groups or interpolating user-provided values ourselves.
63
+ resolver = URLResolver(RegexPattern(r"^"), [target_pattern])
64
+ return get_script_prefix() + resolver.reverse(view_name, **kwargs)
58
65
 
59
66
  route = route_pattern._route
60
67
  parameter_names = {match.group(1) for match in _CONVERTER_RE.finditer(route)}
@@ -91,4 +98,4 @@ def api_reverse(
91
98
  f"the generated path does not match {route_pattern!r}."
92
99
  )
93
100
 
94
- return "/" + route.lstrip("/")
101
+ return get_script_prefix() + route.lstrip("/")