django-api-versioning 1.0.0__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.
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/CHANGELOG.md +46 -2
- django_api_versioning-1.1.0/PKG-INFO +266 -0
- django_api_versioning-1.1.0/README.md +216 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/lifecycle.py +16 -8
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/management/commands/check_versions.py +22 -2
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/registry.py +49 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/reverse.py +15 -8
- django_api_versioning-1.1.0/django_api_versioning/routers.py +293 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/settings.py +39 -2
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/testing.py +48 -16
- django_api_versioning-1.1.0/django_api_versioning.egg-info/PKG-INFO +266 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/SOURCES.txt +2 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/pyproject.toml +11 -15
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_lifecycle.py +91 -7
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_management_commands.py +10 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_registry.py +160 -1
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_reverse.py +46 -1
- django_api_versioning-1.1.0/tests/test_routers.py +303 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_settings.py +71 -1
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_testing_utils.py +45 -0
- django_api_versioning-1.0.0/PKG-INFO +0 -1116
- django_api_versioning-1.0.0/README.md +0 -1068
- django_api_versioning-1.0.0/django_api_versioning.egg-info/PKG-INFO +0 -1116
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/LICENSE +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/MANIFEST.in +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/__init__.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/channels.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/decorators.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/exceptions.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/management/__init__.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/management/commands/__init__.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/management/commands/migrate_endpoints.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/py.typed +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/urls.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/requires.txt +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning.egg-info/top_level.txt +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/pytest.ini +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/requirements-dev.txt +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/requirements.txt +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/setup.cfg +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/__init__.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/conftest.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/settings.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_channels.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_channels_extra.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_decorators.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_distribution_contents.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_exceptions.py +0 -0
- {django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/tests/test_segment_model.py +0 -0
- {django_api_versioning-1.0.0 → 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,51 @@ 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
|
+
|
|
40
|
+
## [1.0.1] - 2026-11-17
|
|
41
|
+
|
|
42
|
+
### Documentation
|
|
43
|
+
|
|
44
|
+
- Rework the README onboarding flow to show a working DRF example and generated version routes before the detailed explanation.
|
|
45
|
+
- Add descriptive links to the official documentation site and PyPI, plus the website logo and current PyPI version badge.
|
|
46
|
+
- Use absolute repository links in the README so the PyPI long description retains working source links.
|
|
47
|
+
- Expand and reconcile the canonical API reference, routing contract, article index, and documentation ownership guidance.
|
|
48
|
+
- Correct lifecycle documentation and examples to match the released 1.0.0 behavior.
|
|
49
|
+
- Add and refine Homepage, Documentation, Source, Issues, Changelog, and Security project URLs in package metadata.
|
|
50
|
+
|
|
51
|
+
### Packaging
|
|
52
|
+
|
|
53
|
+
- Publish updated project metadata and documentation only; no runtime code or dependency changes.
|
|
54
|
+
|
|
11
55
|
## [1.0.0] - 2026-11-16
|
|
12
56
|
|
|
13
57
|
### Added
|
|
@@ -160,7 +204,7 @@ The package runtime minimum remains Python 3.10 and Django 4.2. Django REST Fram
|
|
|
160
204
|
- **Comprehensive Integration Testing:** 222+ integration tests covering DRF APIView, GenericAPIView, ViewSets, routers, custom actions, authentication, permissions, and Django-native views.
|
|
161
205
|
- **Enhanced Testing Infrastructure:** Management command tests for `check_versions` and version matrix validation.
|
|
162
206
|
- **Feature Verification Matrix:** Complete traceability matrix documenting 90+ features verified against implementation.
|
|
163
|
-
- **
|
|
207
|
+
- **Historical compatibility report:** [v0.3.8 compatibility evidence](docs/reports/compatibility-0.3.8.md), covering the Python 3.10+, Django 4.2–6.1, and DRF 3.14+ matrix at that release.
|
|
164
208
|
|
|
165
209
|
### Changed
|
|
166
210
|
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: django-api-versioning
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: URL-path API versioning for Django and Django REST Framework with decorator-based endpoint registration and forward route inheritance.
|
|
5
|
+
Author-email: Mojtaba Arvin <ArvinDevDay@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://mojtaba-arvin.github.io/django-api-versioning/
|
|
8
|
+
Project-URL: Documentation, https://mojtaba-arvin.github.io/django-api-versioning/reference/
|
|
9
|
+
Project-URL: Source, https://github.com/mojtaba-arvin/django-api-versioning
|
|
10
|
+
Project-URL: Issues, https://github.com/mojtaba-arvin/django-api-versioning/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CHANGELOG.md
|
|
12
|
+
Project-URL: Security, https://github.com/mojtaba-arvin/django-api-versioning/blob/main/SECURITY.md
|
|
13
|
+
Keywords: django api versioning,django rest framework api versioning,drf versioning,url path api versioning,versioned url routing,endpoint registration,version-specific django views,django-api-versioning
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
21
|
+
Classifier: Framework :: Django
|
|
22
|
+
Classifier: Framework :: Django :: 4.2
|
|
23
|
+
Classifier: Framework :: Django :: 5.2
|
|
24
|
+
Classifier: Framework :: Django :: 6.0
|
|
25
|
+
Classifier: Framework :: Django :: 6.1
|
|
26
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
27
|
+
Classifier: Intended Audience :: Developers
|
|
28
|
+
Classifier: Operating System :: OS Independent
|
|
29
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
30
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
31
|
+
Classifier: Typing :: Typed
|
|
32
|
+
Requires-Python: >=3.10
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
License-File: LICENSE
|
|
35
|
+
Requires-Dist: Django>=4.2
|
|
36
|
+
Provides-Extra: dev
|
|
37
|
+
Requires-Dist: black>=26.10.1; extra == "dev"
|
|
38
|
+
Requires-Dist: flake8>=7.4.1; extra == "dev"
|
|
39
|
+
Requires-Dist: isort>=9.0.2; extra == "dev"
|
|
40
|
+
Requires-Dist: mypy>=2.4.0; extra == "dev"
|
|
41
|
+
Requires-Dist: pytest>=9.2.0; extra == "dev"
|
|
42
|
+
Requires-Dist: pytest-django>=4.14.0; extra == "dev"
|
|
43
|
+
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
|
|
44
|
+
Requires-Dist: pre-commit>=4.7.0; python_version >= "3.11" and extra == "dev"
|
|
45
|
+
Requires-Dist: twine>=7.0.0; extra == "dev"
|
|
46
|
+
Requires-Dist: build>=1.6.1; extra == "dev"
|
|
47
|
+
Requires-Dist: djangorestframework>=3.18; extra == "dev"
|
|
48
|
+
Requires-Dist: tomli>=2.0.1; python_version < "3.11" and extra == "dev"
|
|
49
|
+
Dynamic: license-file
|
|
50
|
+
|
|
51
|
+
<p align="center">
|
|
52
|
+
<a href="https://mojtaba-arvin.github.io/django-api-versioning/">
|
|
53
|
+
<img src="https://raw.githubusercontent.com/mojtaba-arvin/django-api-versioning/main/website/public/favicon.svg" alt="Django API Versioning logo" width="64" height="64">
|
|
54
|
+
</a>
|
|
55
|
+
</p>
|
|
56
|
+
|
|
57
|
+
# Django API Versioning
|
|
58
|
+
|
|
59
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
60
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
61
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini)
|
|
62
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml)
|
|
63
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE)
|
|
64
|
+
|
|
65
|
+
**Version your Django API by endpoint, not by duplicating URL patterns.** Register a view once; unchanged routes carry forward to later API versions, and a newer declaration replaces the implementation from that version onward.
|
|
66
|
+
|
|
67
|
+
[Explore Django API Versioning — documentation, examples, and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) · [Install django-api-versioning from PyPI](https://pypi.org/project/django-api-versioning/)
|
|
68
|
+
|
|
69
|
+
## See how it works
|
|
70
|
+
|
|
71
|
+
Install the package and Django REST Framework:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install django-api-versioning djangorestframework
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Declare only the versions where an endpoint's behavior changes:
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from rest_framework.response import Response
|
|
81
|
+
from rest_framework.views import APIView
|
|
82
|
+
|
|
83
|
+
from django_api_versioning import endpoint
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
@endpoint("orders/", version=1, view_name="order-list")
|
|
87
|
+
class OrderListV1(APIView):
|
|
88
|
+
def get(self, request):
|
|
89
|
+
return Response({"total": "19.99"})
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
@endpoint("orders/", version=2, view_name="order-list")
|
|
93
|
+
class OrderListV2(APIView):
|
|
94
|
+
def get(self, request):
|
|
95
|
+
return Response({"total": 1999, "currency": "USD"})
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
With `API_MAX_VERSION = 3`, the generated routes are:
|
|
99
|
+
|
|
100
|
+
| Request | View |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| `GET /api/v1/orders/` | `OrderListV1` |
|
|
103
|
+
| `GET /api/v2/orders/` | `OrderListV2` |
|
|
104
|
+
| `GET /api/v3/orders/` | `OrderListV2` |
|
|
105
|
+
|
|
106
|
+
The v1 view serves v1 until another declaration replaces it. The v2 view then serves v2 and v3. **You write a new view when the endpoint changes—not another copy of every unchanged route.**
|
|
107
|
+
|
|
108
|
+
For the complete setup, including Django settings and URL configuration, see the [Django API Versioning getting-started guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/022-django-api-versioning-how-does-it-work/).
|
|
109
|
+
|
|
110
|
+
## What problem does it solve?
|
|
111
|
+
|
|
112
|
+
In a growing API, only some endpoints change between releases. Manually maintaining a separate URL configuration for every version can repeat registrations and obscure which implementation handles each version.
|
|
113
|
+
|
|
114
|
+
Django API Versioning makes that mapping explicit with `@endpoint`:
|
|
115
|
+
|
|
116
|
+
- **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
|
|
117
|
+
- **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
|
|
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 `python manage.py check_versions --fail-on-empty` and guard it with `assert_version_matrix(snapshot=".version_matrix.json", strict=True)`.
|
|
120
|
+
|
|
121
|
+
This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
|
|
122
|
+
|
|
123
|
+
## Why use it with Django REST Framework?
|
|
124
|
+
|
|
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
|
+
|
|
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
|
+
|
|
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
|
+
|
|
131
|
+
```bash
|
|
132
|
+
pip install django-api-versioning
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Quick configuration
|
|
136
|
+
|
|
137
|
+
Add the package (and DRF, if used) to `INSTALLED_APPS` and configure the supported version range:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
# settings.py
|
|
141
|
+
INSTALLED_APPS = [
|
|
142
|
+
"rest_framework", # omit when using Django-native views only
|
|
143
|
+
"django_api_versioning",
|
|
144
|
+
]
|
|
145
|
+
|
|
146
|
+
API_MIN_VERSION = 1
|
|
147
|
+
API_MAX_VERSION = 3
|
|
148
|
+
# API_BASE_PATH defaults to "api/v{version}/"
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Import modules containing endpoint declarations before including the generated patterns:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
# project/urls.py
|
|
155
|
+
from django.urls import include, path
|
|
156
|
+
|
|
157
|
+
from orders import views as _order_views # noqa: F401
|
|
158
|
+
from django_api_versioning.urls import urlpatterns as api_urlpatterns
|
|
159
|
+
|
|
160
|
+
urlpatterns = [
|
|
161
|
+
path("", include(api_urlpatterns)),
|
|
162
|
+
]
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Run the route-matrix check:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
python manage.py check_versions
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Registration options
|
|
172
|
+
|
|
173
|
+
| Declaration | Routes created |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| `@endpoint("orders/", version=2)` | v2 through `API_MAX_VERSION` |
|
|
176
|
+
| `@endpoint("orders/", versions=[1, 3, 5])` | Only v1, v3, and v5 |
|
|
177
|
+
| `@endpoint("health/")` | One unversioned route |
|
|
178
|
+
|
|
179
|
+
For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()` for version-aware URL reversal and `assert_version_matrix()` for regression tests.
|
|
180
|
+
|
|
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
|
+
|
|
183
|
+
## Versioned DRF ViewSets
|
|
184
|
+
|
|
185
|
+
Use `VersionedRouter` when you want DRF's normal ViewSet workflow with version-aware implementation dispatch:
|
|
186
|
+
|
|
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.
|
|
226
|
+
|
|
227
|
+
## Requirements
|
|
228
|
+
|
|
229
|
+
- Python 3.10+
|
|
230
|
+
- Django 4.2+ (retained for compatibility with existing 1.x installations)
|
|
231
|
+
- Django REST Framework is optional.
|
|
232
|
+
|
|
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.
|
|
238
|
+
|
|
239
|
+
## Upgrading to 1.0.0
|
|
240
|
+
|
|
241
|
+
Version 1.0.0 tightened API lifecycle configuration and changed the `Deprecation` response header format. If you use `API_VERSION_LIFECYCLE`:
|
|
242
|
+
|
|
243
|
+
- Every entry must have a `status` of `active`, `deprecated`, or `retired`.
|
|
244
|
+
- A deprecated version must define `deprecated_at` as an ISO 8601 date or datetime.
|
|
245
|
+
- A retired version must define a `sunset` date.
|
|
246
|
+
- The `Deprecation` header now uses the RFC 9745 date-valued Structured Field (for example, `Deprecation: @1767225600`), not the legacy `Deprecation: true` value.
|
|
247
|
+
|
|
248
|
+
For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CHANGELOG.md#100---2026-11-16).
|
|
249
|
+
|
|
250
|
+
## Documentation
|
|
251
|
+
|
|
252
|
+
- [Django API Versioning documentation and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) — overview, examples, lifecycle demonstration, and guides.
|
|
253
|
+
- [API reference](https://mojtaba-arvin.github.io/django-api-versioning/reference/) — settings, decorators, URL reversal, validation, and management commands.
|
|
254
|
+
- [Routing contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) — implementation-backed behavior and limitations.
|
|
255
|
+
- [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
|
|
256
|
+
- [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
|
|
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.
|
|
259
|
+
|
|
260
|
+
## Contributing
|
|
261
|
+
|
|
262
|
+
Bug reports, corrections, and pull requests are welcome. Read the [contribution guidelines](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/SECURITY.md).
|
|
263
|
+
|
|
264
|
+
## License
|
|
265
|
+
|
|
266
|
+
Released under the [MIT License](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE).
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://mojtaba-arvin.github.io/django-api-versioning/">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/mojtaba-arvin/django-api-versioning/main/website/public/favicon.svg" alt="Django API Versioning logo" width="64" height="64">
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
# Django API Versioning
|
|
8
|
+
|
|
9
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
10
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
11
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini)
|
|
12
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml)
|
|
13
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE)
|
|
14
|
+
|
|
15
|
+
**Version your Django API by endpoint, not by duplicating URL patterns.** Register a view once; unchanged routes carry forward to later API versions, and a newer declaration replaces the implementation from that version onward.
|
|
16
|
+
|
|
17
|
+
[Explore Django API Versioning — documentation, examples, and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) · [Install django-api-versioning from PyPI](https://pypi.org/project/django-api-versioning/)
|
|
18
|
+
|
|
19
|
+
## See how it works
|
|
20
|
+
|
|
21
|
+
Install the package and Django REST Framework:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install django-api-versioning djangorestframework
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Declare only the versions where an endpoint's behavior changes:
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from rest_framework.response import Response
|
|
31
|
+
from rest_framework.views import APIView
|
|
32
|
+
|
|
33
|
+
from django_api_versioning import endpoint
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@endpoint("orders/", version=1, view_name="order-list")
|
|
37
|
+
class OrderListV1(APIView):
|
|
38
|
+
def get(self, request):
|
|
39
|
+
return Response({"total": "19.99"})
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@endpoint("orders/", version=2, view_name="order-list")
|
|
43
|
+
class OrderListV2(APIView):
|
|
44
|
+
def get(self, request):
|
|
45
|
+
return Response({"total": 1999, "currency": "USD"})
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
With `API_MAX_VERSION = 3`, the generated routes are:
|
|
49
|
+
|
|
50
|
+
| Request | View |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| `GET /api/v1/orders/` | `OrderListV1` |
|
|
53
|
+
| `GET /api/v2/orders/` | `OrderListV2` |
|
|
54
|
+
| `GET /api/v3/orders/` | `OrderListV2` |
|
|
55
|
+
|
|
56
|
+
The v1 view serves v1 until another declaration replaces it. The v2 view then serves v2 and v3. **You write a new view when the endpoint changes—not another copy of every unchanged route.**
|
|
57
|
+
|
|
58
|
+
For the complete setup, including Django settings and URL configuration, see the [Django API Versioning getting-started guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/022-django-api-versioning-how-does-it-work/).
|
|
59
|
+
|
|
60
|
+
## What problem does it solve?
|
|
61
|
+
|
|
62
|
+
In a growing API, only some endpoints change between releases. Manually maintaining a separate URL configuration for every version can repeat registrations and obscure which implementation handles each version.
|
|
63
|
+
|
|
64
|
+
Django API Versioning makes that mapping explicit with `@endpoint`:
|
|
65
|
+
|
|
66
|
+
- **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
|
|
67
|
+
- **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
|
|
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 `python manage.py check_versions --fail-on-empty` and guard it with `assert_version_matrix(snapshot=".version_matrix.json", strict=True)`.
|
|
70
|
+
|
|
71
|
+
This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
|
|
72
|
+
|
|
73
|
+
## Why use it with Django REST Framework?
|
|
74
|
+
|
|
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
|
+
|
|
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
|
+
|
|
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
|
+
|
|
81
|
+
```bash
|
|
82
|
+
pip install django-api-versioning
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Quick configuration
|
|
86
|
+
|
|
87
|
+
Add the package (and DRF, if used) to `INSTALLED_APPS` and configure the supported version range:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
# settings.py
|
|
91
|
+
INSTALLED_APPS = [
|
|
92
|
+
"rest_framework", # omit when using Django-native views only
|
|
93
|
+
"django_api_versioning",
|
|
94
|
+
]
|
|
95
|
+
|
|
96
|
+
API_MIN_VERSION = 1
|
|
97
|
+
API_MAX_VERSION = 3
|
|
98
|
+
# API_BASE_PATH defaults to "api/v{version}/"
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Import modules containing endpoint declarations before including the generated patterns:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
# project/urls.py
|
|
105
|
+
from django.urls import include, path
|
|
106
|
+
|
|
107
|
+
from orders import views as _order_views # noqa: F401
|
|
108
|
+
from django_api_versioning.urls import urlpatterns as api_urlpatterns
|
|
109
|
+
|
|
110
|
+
urlpatterns = [
|
|
111
|
+
path("", include(api_urlpatterns)),
|
|
112
|
+
]
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Run the route-matrix check:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
python manage.py check_versions
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Registration options
|
|
122
|
+
|
|
123
|
+
| Declaration | Routes created |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| `@endpoint("orders/", version=2)` | v2 through `API_MAX_VERSION` |
|
|
126
|
+
| `@endpoint("orders/", versions=[1, 3, 5])` | Only v1, v3, and v5 |
|
|
127
|
+
| `@endpoint("health/")` | One unversioned route |
|
|
128
|
+
|
|
129
|
+
For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()` for version-aware URL reversal and `assert_version_matrix()` for regression tests.
|
|
130
|
+
|
|
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
|
+
|
|
133
|
+
## Versioned DRF ViewSets
|
|
134
|
+
|
|
135
|
+
Use `VersionedRouter` when you want DRF's normal ViewSet workflow with version-aware implementation dispatch:
|
|
136
|
+
|
|
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.
|
|
176
|
+
|
|
177
|
+
## Requirements
|
|
178
|
+
|
|
179
|
+
- Python 3.10+
|
|
180
|
+
- Django 4.2+ (retained for compatibility with existing 1.x installations)
|
|
181
|
+
- Django REST Framework is optional.
|
|
182
|
+
|
|
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.
|
|
188
|
+
|
|
189
|
+
## Upgrading to 1.0.0
|
|
190
|
+
|
|
191
|
+
Version 1.0.0 tightened API lifecycle configuration and changed the `Deprecation` response header format. If you use `API_VERSION_LIFECYCLE`:
|
|
192
|
+
|
|
193
|
+
- Every entry must have a `status` of `active`, `deprecated`, or `retired`.
|
|
194
|
+
- A deprecated version must define `deprecated_at` as an ISO 8601 date or datetime.
|
|
195
|
+
- A retired version must define a `sunset` date.
|
|
196
|
+
- The `Deprecation` header now uses the RFC 9745 date-valued Structured Field (for example, `Deprecation: @1767225600`), not the legacy `Deprecation: true` value.
|
|
197
|
+
|
|
198
|
+
For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CHANGELOG.md#100---2026-11-16).
|
|
199
|
+
|
|
200
|
+
## Documentation
|
|
201
|
+
|
|
202
|
+
- [Django API Versioning documentation and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) — overview, examples, lifecycle demonstration, and guides.
|
|
203
|
+
- [API reference](https://mojtaba-arvin.github.io/django-api-versioning/reference/) — settings, decorators, URL reversal, validation, and management commands.
|
|
204
|
+
- [Routing contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) — implementation-backed behavior and limitations.
|
|
205
|
+
- [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
|
|
206
|
+
- [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
|
|
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.
|
|
209
|
+
|
|
210
|
+
## Contributing
|
|
211
|
+
|
|
212
|
+
Bug reports, corrections, and pull requests are welcome. Read the [contribution guidelines](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/SECURITY.md).
|
|
213
|
+
|
|
214
|
+
## License
|
|
215
|
+
|
|
216
|
+
Released under the [MIT License](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE).
|
{django_api_versioning-1.0.0 → django_api_versioning-1.1.0}/django_api_versioning/lifecycle.py
RENAMED
|
@@ -78,10 +78,14 @@ class LifecycleMiddleware:
|
|
|
78
78
|
)
|
|
79
79
|
|
|
80
80
|
response = self.get_response(request)
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
150
|
-
#
|
|
151
|
-
#
|
|
152
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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):
|