django-api-versioning 0.3.7__tar.gz → 1.0.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-0.3.7 → django_api_versioning-1.0.0}/CHANGELOG.md +54 -0
- django_api_versioning-1.0.0/MANIFEST.in +27 -0
- {django_api_versioning-0.3.7/django_api_versioning.egg-info → django_api_versioning-1.0.0}/PKG-INFO +38 -23
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/README.md +33 -19
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/channels.py +18 -21
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/decorators.py +6 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/lifecycle.py +71 -28
- django_api_versioning-1.0.0/django_api_versioning/management/commands/migrate_endpoints.py +249 -0
- django_api_versioning-1.0.0/django_api_versioning/py.typed +1 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/registry.py +18 -17
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/reverse.py +32 -3
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/settings.py +61 -6
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/testing.py +18 -2
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0/django_api_versioning.egg-info}/PKG-INFO +38 -23
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/SOURCES.txt +2 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/requires.txt +6 -1
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/top_level.txt +0 -2
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/pyproject.toml +16 -6
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/requirements-dev.txt +3 -2
- django_api_versioning-1.0.0/tests/test_channels_extra.py +69 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_decorators.py +30 -0
- django_api_versioning-1.0.0/tests/test_distribution_contents.py +160 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_lifecycle.py +119 -12
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_management_commands.py +269 -14
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_registry.py +5 -4
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_reverse.py +64 -2
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_settings.py +62 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_testing_utils.py +26 -1
- django_api_versioning-0.3.7/MANIFEST.in +0 -9
- django_api_versioning-0.3.7/django_api_versioning/management/commands/migrate_endpoints.py +0 -78
- django_api_versioning-0.3.7/tests/test_channels_extra.py +0 -33
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/LICENSE +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/__init__.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/exceptions.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/management/__init__.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/__init__.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/check_versions.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/urls.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/pytest.ini +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/requirements.txt +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/setup.cfg +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/__init__.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/conftest.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/settings.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_channels.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_exceptions.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_segment_model.py +0 -0
- {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_urls.py +0 -0
|
@@ -8,6 +8,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [1.0.0] - 2026-11-16
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- Emit the RFC 9745 date-valued `Deprecation` Structured Field from `API_VERSION_LIFECYCLE[*].deprecated_at`.
|
|
16
|
+
- Add Windows and macOS smoke coverage for Python 3.12 / Django 5.2 alongside the existing 15-environment Linux compatibility matrix.
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- Validate lifecycle status values and ISO 8601 lifecycle dates during settings initialization. Deprecated versions require `deprecated_at`; retired versions require `sunset`; supported statuses are `active`, `deprecated`, and `retired`.
|
|
21
|
+
- Replace the legacy `Deprecation: true` header with the RFC 9745 date value `Deprecation: @<unix-timestamp>`. The `Sunset` header continues to use the HTTP-date format defined by RFC 8594.
|
|
22
|
+
|
|
23
|
+
### Migration from 0.3.8
|
|
24
|
+
|
|
25
|
+
Update every `API_VERSION_LIFECYCLE` entry before upgrading:
|
|
26
|
+
|
|
27
|
+
- Set `status` to `active`, `deprecated`, or `retired`. Previously omitted or unrecognized values are now configuration errors.
|
|
28
|
+
- Add `deprecated_at` (an ISO 8601 date or datetime) to every deprecated version. This is the actual deprecation date, not the sunset deadline.
|
|
29
|
+
- Keep or add `sunset` (an ISO 8601 date or datetime) for every retired version.
|
|
30
|
+
- Update clients or tests that expect the non-standard `Deprecation: true` value to parse the RFC 9745 Structured Field Date instead.
|
|
31
|
+
|
|
32
|
+
Example:
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
API_VERSION_LIFECYCLE = {
|
|
36
|
+
1: {
|
|
37
|
+
"status": "deprecated",
|
|
38
|
+
"deprecated_at": "2026-01-01T00:00:00+00:00",
|
|
39
|
+
"sunset": "2027-06-30",
|
|
40
|
+
},
|
|
41
|
+
2: {"status": "active"},
|
|
42
|
+
3: {
|
|
43
|
+
"status": "retired",
|
|
44
|
+
"sunset": "2026-06-30",
|
|
45
|
+
},
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The package runtime minimum remains Python 3.10 and Django 4.2. Django REST Framework remains optional and is not a runtime dependency.
|
|
50
|
+
|
|
51
|
+
## [0.3.8] - 2026-11-16
|
|
52
|
+
|
|
53
|
+
### Fixed
|
|
54
|
+
|
|
55
|
+
- Ignore invalid lifecycle sunset values instead of emitting invalid `Sunset` headers; normalize timezone-aware sunset timestamps to UTC before enforcement and formatting.
|
|
56
|
+
- Return a class-specific actionable error when a DRF ViewSet class is registered without its required action map.
|
|
57
|
+
- Validate `API_BASE_PATH` as exactly one plain `{version}` format field, and reject malformed templates, non-string `ROOT_URLCONF` values, and non-string versioning-channel entries with configuration errors.
|
|
58
|
+
- Avoid emitting no-op or unsafe `migrate_endpoints` rewrites when legacy flags are missing a literal value or use dynamic expressions; make the command preview-only by default and require `--write` before modifying source files.
|
|
59
|
+
- Make the standalone channel extraction helper fall back from an invalid path match to `request.version` and reject repeated `v` prefixes.
|
|
60
|
+
|
|
61
|
+
### Verified
|
|
62
|
+
|
|
63
|
+
- All 15 Python/Django tox environments passed: 247 unit tests and 260 integration tests in each environment. The lint environment and tox/workflow matrix validator also passed.
|
|
64
|
+
|
|
11
65
|
## [0.3.7] - 2026-11-14
|
|
12
66
|
|
|
13
67
|
### Changed
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
include LICENSE
|
|
3
|
+
include CHANGELOG.md
|
|
4
|
+
include requirements.txt
|
|
5
|
+
include requirements-dev.txt
|
|
6
|
+
include pytest.ini
|
|
7
|
+
|
|
8
|
+
recursive-include django_api_versioning *.py
|
|
9
|
+
recursive-include django_api_versioning py.typed
|
|
10
|
+
recursive-include tests *.py
|
|
11
|
+
|
|
12
|
+
# Repository-only assets: never ship the docs corpus, integration lab, or website.
|
|
13
|
+
prune docs
|
|
14
|
+
prune integration_test_project
|
|
15
|
+
prune website
|
|
16
|
+
prune .github
|
|
17
|
+
prune .claude
|
|
18
|
+
|
|
19
|
+
# Generated frontend and local tooling artifacts.
|
|
20
|
+
prune node_modules
|
|
21
|
+
prune dist
|
|
22
|
+
prune build
|
|
23
|
+
prune .astro
|
|
24
|
+
prune .netlify
|
|
25
|
+
global-exclude __pycache__/*
|
|
26
|
+
global-exclude *.py[cod]
|
|
27
|
+
global-exclude .DS_Store
|
{django_api_versioning-0.3.7/django_api_versioning.egg-info → django_api_versioning-1.0.0}/PKG-INFO
RENAMED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: django-api-versioning
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 1.0.0
|
|
4
4
|
Summary: API versioning for Django and Django REST Framework (DRF), with decorator-based endpoint registration, automatic URL routing, version-specific views, and forward inheritance for backward-compatible API evolution.
|
|
5
5
|
Author-email: Mojtaba Arvin <ArvinDevDay@gmail.com>
|
|
6
|
-
License: MIT
|
|
6
|
+
License-Expression: MIT
|
|
7
7
|
Project-URL: Source, https://github.com/mojtaba-arvin/django-api-versioning
|
|
8
8
|
Project-URL: Issues, https://github.com/mojtaba-arvin/django-api-versioning/issues
|
|
9
9
|
Project-URL: Documentation, https://github.com/mojtaba-arvin/django-api-versioning#readme
|
|
@@ -21,7 +21,7 @@ Classifier: Framework :: Django :: 4.2
|
|
|
21
21
|
Classifier: Framework :: Django :: 5.2
|
|
22
22
|
Classifier: Framework :: Django :: 6.0
|
|
23
23
|
Classifier: Framework :: Django :: 6.1
|
|
24
|
-
Classifier: Development Status ::
|
|
24
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
25
25
|
Classifier: Intended Audience :: Developers
|
|
26
26
|
Classifier: Operating System :: OS Independent
|
|
27
27
|
Classifier: Topic :: Internet :: WWW/HTTP
|
|
@@ -39,10 +39,11 @@ Requires-Dist: mypy>=2.4.0; extra == "dev"
|
|
|
39
39
|
Requires-Dist: pytest>=9.2.0; extra == "dev"
|
|
40
40
|
Requires-Dist: pytest-django>=4.14.0; extra == "dev"
|
|
41
41
|
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
|
|
42
|
-
Requires-Dist: pre-commit>=4.
|
|
42
|
+
Requires-Dist: pre-commit>=4.7.0; python_version >= "3.11" and extra == "dev"
|
|
43
43
|
Requires-Dist: twine>=7.0.0; extra == "dev"
|
|
44
44
|
Requires-Dist: build>=1.6.1; extra == "dev"
|
|
45
45
|
Requires-Dist: djangorestframework>=3.18; extra == "dev"
|
|
46
|
+
Requires-Dist: tomli>=2.0.1; python_version < "3.11" and extra == "dev"
|
|
46
47
|
Dynamic: license-file
|
|
47
48
|
|
|
48
49
|
# Django API Versioning
|
|
@@ -50,7 +51,7 @@ Dynamic: license-file
|
|
|
50
51
|
[](https://badge.fury.io/py/django-api-versioning)
|
|
51
52
|
[](https://pypi.org/project/django-api-versioning/)
|
|
52
53
|
[](https://github.com/mojtaba-arvin/django-api-versioning/actions)
|
|
53
|
-
[](https://www.djangoproject.com/)
|
|
54
55
|
[](https://pypi.org/project/django-api-versioning/)
|
|
55
56
|
[](https://opensource.org/licenses/MIT)
|
|
56
57
|
|
|
@@ -193,6 +194,8 @@ Requirements:
|
|
|
193
194
|
- Python >= 3.10
|
|
194
195
|
- Django >= 4.2
|
|
195
196
|
|
|
197
|
+
The automated compatibility matrix currently verifies Django 4.2, 5.2, 6.0, and 6.1 across the Python combinations listed in [`COMPATIBILITY_REPORT.md`](COMPATIBILITY_REPORT.md). Django 5.0 and 5.1 are not part of the verified matrix.
|
|
198
|
+
|
|
196
199
|
Django REST Framework is optional. The package can be used with Django-native function-based and class-based views without installing DRF.
|
|
197
200
|
|
|
198
201
|
## Quick Start
|
|
@@ -214,7 +217,7 @@ API_MIN_VERSION = 1
|
|
|
214
217
|
API_MAX_VERSION = 3
|
|
215
218
|
```
|
|
216
219
|
|
|
217
|
-
`API_BASE_PATH` must contain
|
|
220
|
+
`API_BASE_PATH` must contain exactly one plain `{version}` format field. Additional format fields, conversions, and format specifications are rejected.
|
|
218
221
|
|
|
219
222
|
The default values for `API_MIN_VERSION` and `API_MAX_VERSION` are both `1`. Set `API_MAX_VERSION` to the highest route version your project intends to register.
|
|
220
223
|
|
|
@@ -742,7 +745,11 @@ Configure lifecycle metadata in Django settings:
|
|
|
742
745
|
|
|
743
746
|
API_VERSION_LIFECYCLE = {
|
|
744
747
|
1: {"status": "retired", "sunset": "2025-01-01"},
|
|
745
|
-
2: {
|
|
748
|
+
2: {
|
|
749
|
+
"status": "deprecated",
|
|
750
|
+
"deprecated_at": "2026-01-01T00:00:00+00:00",
|
|
751
|
+
"sunset": "2027-06-01",
|
|
752
|
+
},
|
|
746
753
|
3: {"status": "active"},
|
|
747
754
|
}
|
|
748
755
|
|
|
@@ -755,7 +762,7 @@ MIDDLEWARE = [
|
|
|
755
762
|
For a version configured as deprecated with a future sunset date, the middleware adds:
|
|
756
763
|
|
|
757
764
|
```http
|
|
758
|
-
Deprecation:
|
|
765
|
+
Deprecation: @1767225600
|
|
759
766
|
Sunset: Tue, 01 Jun 2027 00:00:00 GMT
|
|
760
767
|
```
|
|
761
768
|
|
|
@@ -775,7 +782,7 @@ The middleware attempts to identify the request version in this order:
|
|
|
775
782
|
|
|
776
783
|
This allows the middleware to identify versions from the package's static versioned URL paths even when `request.version` is not set.
|
|
777
784
|
|
|
778
|
-
**Standards note:**
|
|
785
|
+
**Standards note:** Configure `deprecated_at` as an ISO 8601 date or datetime for deprecated versions. The middleware emits the date-valued Structured Field required by [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745), using `@` followed by the Unix timestamp. A deprecated lifecycle entry without a valid `deprecated_at` is rejected during settings validation. If the value is changed after initialization, the middleware logs a warning and omits `Deprecation` rather than emitting a non-standard value. `Sunset` follows the HTTP-date format specified by [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594).
|
|
779
786
|
|
|
780
787
|
## Configuration reference
|
|
781
788
|
|
|
@@ -783,7 +790,7 @@ This allows the middleware to identify versions from the package's static versio
|
|
|
783
790
|
|
|
784
791
|
| Setting | Default | Description |
|
|
785
792
|
| --- | --- | --- |
|
|
786
|
-
| `API_BASE_PATH` | `"api/v{version}/"` | Base path template for versioned routes. Must contain `{version}
|
|
793
|
+
| `API_BASE_PATH` | `"api/v{version}/"` | Base path template for versioned routes. Must contain exactly one plain `{version}` format field and no other format fields. |
|
|
787
794
|
| `API_MIN_VERSION` | `1` | Lowest valid route version. |
|
|
788
795
|
| `API_MAX_VERSION` | `1` | Highest valid route version. |
|
|
789
796
|
| `API_VERSION_LIFECYCLE` | `{}` | Per-version lifecycle metadata. |
|
|
@@ -984,9 +991,9 @@ python manage.py migrate_endpoints --dry-run
|
|
|
984
991
|
python manage.py migrate_endpoints
|
|
985
992
|
```
|
|
986
993
|
|
|
987
|
-
The command
|
|
994
|
+
The command parses Python source into an AST and uses tokenizer-aware checks to identify supported `@endpoint` declarations containing legacy `forward` or `backward` arguments. It rewrites only literal integer `version` values and literal boolean flags. Dynamic expressions, comments inside a decorator, unsupported forms, and files with syntax errors are left unchanged for manual migration.
|
|
988
995
|
|
|
989
|
-
**Review
|
|
996
|
+
**Review every proposed change before applying it.** This syntax-aware rewrite is not a proof of semantic equivalence: confirm the intended version coverage, inspect the generated route matrix with `check_versions`, and test request behavior for every affected API version.
|
|
990
997
|
|
|
991
998
|
After migration:
|
|
992
999
|
|
|
@@ -1009,7 +1016,7 @@ For the current compatibility and CI verification status, see the [GitHub Action
|
|
|
1009
1016
|
|
|
1010
1017
|
## Contributing
|
|
1011
1018
|
|
|
1012
|
-
Contributions, bug reports, and documentation improvements are welcome.
|
|
1019
|
+
Contributions, bug reports, and documentation improvements are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch, commit, pull-request, and release workflow.
|
|
1013
1020
|
|
|
1014
1021
|
### Setup
|
|
1015
1022
|
|
|
@@ -1073,18 +1080,26 @@ docker run --rm dapi:py315
|
|
|
1073
1080
|
|
|
1074
1081
|
### Releasing
|
|
1075
1082
|
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1083
|
+
Releases are maintainer operations. Prepare the version bump and changelog
|
|
1084
|
+
on a temporary release branch created from the latest `main`, then submit
|
|
1085
|
+
them through a reviewed pull request. The pull request must pass the
|
|
1086
|
+
compatibility and artifact checks for its latest commit. Do not push directly
|
|
1087
|
+
to `main` or tag an unmerged release branch.
|
|
1088
|
+
|
|
1089
|
+
After the reviewed release commit is present on the default branch, create
|
|
1090
|
+
and push the matching version tag:
|
|
1079
1091
|
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1092
|
+
```bash
|
|
1093
|
+
git tag -a vX.Y.Z -m "Release vX.Y.Z"
|
|
1094
|
+
git push origin vX.Y.Z
|
|
1095
|
+
```
|
|
1084
1096
|
|
|
1085
|
-
Pushing a `v*` tag triggers GitHub Actions to
|
|
1086
|
-
the distribution with `twine check --strict`,
|
|
1087
|
-
|
|
1097
|
+
Pushing a `v*` tag triggers GitHub Actions to run the compatibility matrix,
|
|
1098
|
+
build and validate the exact distribution with `twine check --strict`,
|
|
1099
|
+
smoke-test the wheel, and publish it to PyPI using Trusted Publishing
|
|
1100
|
+
(GitHub Actions OIDC). A successful tag push alone does not prove that
|
|
1101
|
+
publication completed; verify the workflow and the version-specific PyPI
|
|
1102
|
+
release page before announcing the release.
|
|
1088
1103
|
|
|
1089
1104
|
### Reporting issues
|
|
1090
1105
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
[](https://badge.fury.io/py/django-api-versioning)
|
|
4
4
|
[](https://pypi.org/project/django-api-versioning/)
|
|
5
5
|
[](https://github.com/mojtaba-arvin/django-api-versioning/actions)
|
|
6
|
-
[](https://www.djangoproject.com/)
|
|
7
7
|
[](https://pypi.org/project/django-api-versioning/)
|
|
8
8
|
[](https://opensource.org/licenses/MIT)
|
|
9
9
|
|
|
@@ -146,6 +146,8 @@ Requirements:
|
|
|
146
146
|
- Python >= 3.10
|
|
147
147
|
- Django >= 4.2
|
|
148
148
|
|
|
149
|
+
The automated compatibility matrix currently verifies Django 4.2, 5.2, 6.0, and 6.1 across the Python combinations listed in [`COMPATIBILITY_REPORT.md`](COMPATIBILITY_REPORT.md). Django 5.0 and 5.1 are not part of the verified matrix.
|
|
150
|
+
|
|
149
151
|
Django REST Framework is optional. The package can be used with Django-native function-based and class-based views without installing DRF.
|
|
150
152
|
|
|
151
153
|
## Quick Start
|
|
@@ -167,7 +169,7 @@ API_MIN_VERSION = 1
|
|
|
167
169
|
API_MAX_VERSION = 3
|
|
168
170
|
```
|
|
169
171
|
|
|
170
|
-
`API_BASE_PATH` must contain
|
|
172
|
+
`API_BASE_PATH` must contain exactly one plain `{version}` format field. Additional format fields, conversions, and format specifications are rejected.
|
|
171
173
|
|
|
172
174
|
The default values for `API_MIN_VERSION` and `API_MAX_VERSION` are both `1`. Set `API_MAX_VERSION` to the highest route version your project intends to register.
|
|
173
175
|
|
|
@@ -695,7 +697,11 @@ Configure lifecycle metadata in Django settings:
|
|
|
695
697
|
|
|
696
698
|
API_VERSION_LIFECYCLE = {
|
|
697
699
|
1: {"status": "retired", "sunset": "2025-01-01"},
|
|
698
|
-
2: {
|
|
700
|
+
2: {
|
|
701
|
+
"status": "deprecated",
|
|
702
|
+
"deprecated_at": "2026-01-01T00:00:00+00:00",
|
|
703
|
+
"sunset": "2027-06-01",
|
|
704
|
+
},
|
|
699
705
|
3: {"status": "active"},
|
|
700
706
|
}
|
|
701
707
|
|
|
@@ -708,7 +714,7 @@ MIDDLEWARE = [
|
|
|
708
714
|
For a version configured as deprecated with a future sunset date, the middleware adds:
|
|
709
715
|
|
|
710
716
|
```http
|
|
711
|
-
Deprecation:
|
|
717
|
+
Deprecation: @1767225600
|
|
712
718
|
Sunset: Tue, 01 Jun 2027 00:00:00 GMT
|
|
713
719
|
```
|
|
714
720
|
|
|
@@ -728,7 +734,7 @@ The middleware attempts to identify the request version in this order:
|
|
|
728
734
|
|
|
729
735
|
This allows the middleware to identify versions from the package's static versioned URL paths even when `request.version` is not set.
|
|
730
736
|
|
|
731
|
-
**Standards note:**
|
|
737
|
+
**Standards note:** Configure `deprecated_at` as an ISO 8601 date or datetime for deprecated versions. The middleware emits the date-valued Structured Field required by [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745), using `@` followed by the Unix timestamp. A deprecated lifecycle entry without a valid `deprecated_at` is rejected during settings validation. If the value is changed after initialization, the middleware logs a warning and omits `Deprecation` rather than emitting a non-standard value. `Sunset` follows the HTTP-date format specified by [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594).
|
|
732
738
|
|
|
733
739
|
## Configuration reference
|
|
734
740
|
|
|
@@ -736,7 +742,7 @@ This allows the middleware to identify versions from the package's static versio
|
|
|
736
742
|
|
|
737
743
|
| Setting | Default | Description |
|
|
738
744
|
| --- | --- | --- |
|
|
739
|
-
| `API_BASE_PATH` | `"api/v{version}/"` | Base path template for versioned routes. Must contain `{version}
|
|
745
|
+
| `API_BASE_PATH` | `"api/v{version}/"` | Base path template for versioned routes. Must contain exactly one plain `{version}` format field and no other format fields. |
|
|
740
746
|
| `API_MIN_VERSION` | `1` | Lowest valid route version. |
|
|
741
747
|
| `API_MAX_VERSION` | `1` | Highest valid route version. |
|
|
742
748
|
| `API_VERSION_LIFECYCLE` | `{}` | Per-version lifecycle metadata. |
|
|
@@ -937,9 +943,9 @@ python manage.py migrate_endpoints --dry-run
|
|
|
937
943
|
python manage.py migrate_endpoints
|
|
938
944
|
```
|
|
939
945
|
|
|
940
|
-
The command
|
|
946
|
+
The command parses Python source into an AST and uses tokenizer-aware checks to identify supported `@endpoint` declarations containing legacy `forward` or `backward` arguments. It rewrites only literal integer `version` values and literal boolean flags. Dynamic expressions, comments inside a decorator, unsupported forms, and files with syntax errors are left unchanged for manual migration.
|
|
941
947
|
|
|
942
|
-
**Review
|
|
948
|
+
**Review every proposed change before applying it.** This syntax-aware rewrite is not a proof of semantic equivalence: confirm the intended version coverage, inspect the generated route matrix with `check_versions`, and test request behavior for every affected API version.
|
|
943
949
|
|
|
944
950
|
After migration:
|
|
945
951
|
|
|
@@ -962,7 +968,7 @@ For the current compatibility and CI verification status, see the [GitHub Action
|
|
|
962
968
|
|
|
963
969
|
## Contributing
|
|
964
970
|
|
|
965
|
-
Contributions, bug reports, and documentation improvements are welcome.
|
|
971
|
+
Contributions, bug reports, and documentation improvements are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch, commit, pull-request, and release workflow.
|
|
966
972
|
|
|
967
973
|
### Setup
|
|
968
974
|
|
|
@@ -1026,18 +1032,26 @@ docker run --rm dapi:py315
|
|
|
1026
1032
|
|
|
1027
1033
|
### Releasing
|
|
1028
1034
|
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1035
|
+
Releases are maintainer operations. Prepare the version bump and changelog
|
|
1036
|
+
on a temporary release branch created from the latest `main`, then submit
|
|
1037
|
+
them through a reviewed pull request. The pull request must pass the
|
|
1038
|
+
compatibility and artifact checks for its latest commit. Do not push directly
|
|
1039
|
+
to `main` or tag an unmerged release branch.
|
|
1040
|
+
|
|
1041
|
+
After the reviewed release commit is present on the default branch, create
|
|
1042
|
+
and push the matching version tag:
|
|
1032
1043
|
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1044
|
+
```bash
|
|
1045
|
+
git tag -a vX.Y.Z -m "Release vX.Y.Z"
|
|
1046
|
+
git push origin vX.Y.Z
|
|
1047
|
+
```
|
|
1037
1048
|
|
|
1038
|
-
Pushing a `v*` tag triggers GitHub Actions to
|
|
1039
|
-
the distribution with `twine check --strict`,
|
|
1040
|
-
|
|
1049
|
+
Pushing a `v*` tag triggers GitHub Actions to run the compatibility matrix,
|
|
1050
|
+
build and validate the exact distribution with `twine check --strict`,
|
|
1051
|
+
smoke-test the wheel, and publish it to PyPI using Trusted Publishing
|
|
1052
|
+
(GitHub Actions OIDC). A successful tag push alone does not prove that
|
|
1053
|
+
publication completed; verify the workflow and the version-specific PyPI
|
|
1054
|
+
release page before announcing the release.
|
|
1041
1055
|
|
|
1042
1056
|
### Reporting issues
|
|
1043
1057
|
|
{django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/channels.py
RENAMED
|
@@ -26,35 +26,32 @@ def extract_version(request: HttpRequest, channels: list[str]) -> int | None:
|
|
|
26
26
|
|
|
27
27
|
def _from_path(request: HttpRequest) -> int | None:
|
|
28
28
|
match = getattr(request, "resolver_match", None)
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
return
|
|
34
|
-
|
|
35
|
-
try:
|
|
36
|
-
return int(request.version)
|
|
37
|
-
except (TypeError, ValueError):
|
|
38
|
-
return None
|
|
39
|
-
return None
|
|
29
|
+
kwargs = getattr(match, "kwargs", {}) if match else {}
|
|
30
|
+
if "version" in kwargs:
|
|
31
|
+
version = _parse_version(kwargs["version"])
|
|
32
|
+
if version is not None:
|
|
33
|
+
return version
|
|
34
|
+
return _parse_version(getattr(request, "version", None))
|
|
40
35
|
|
|
41
36
|
|
|
42
37
|
def _from_header(request: HttpRequest) -> int | None:
|
|
43
|
-
|
|
44
|
-
if not raw:
|
|
45
|
-
return None
|
|
46
|
-
raw = raw.strip().lower().lstrip("v")
|
|
47
|
-
try:
|
|
48
|
-
return int(raw)
|
|
49
|
-
except ValueError:
|
|
50
|
-
return None
|
|
38
|
+
return _parse_version(request.headers.get("Accept-Version"))
|
|
51
39
|
|
|
52
40
|
|
|
53
41
|
def _from_query(request: HttpRequest) -> int | None:
|
|
54
|
-
|
|
42
|
+
return _parse_version(request.GET.get("version"))
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _parse_version(value: object) -> int | None:
|
|
46
|
+
if value is None or isinstance(value, bool):
|
|
47
|
+
return None
|
|
48
|
+
|
|
49
|
+
raw = str(value).strip().lower()
|
|
50
|
+
if raw.startswith("v"):
|
|
51
|
+
raw = raw[1:]
|
|
55
52
|
if not raw:
|
|
56
53
|
return None
|
|
57
|
-
|
|
54
|
+
|
|
58
55
|
try:
|
|
59
56
|
return int(raw)
|
|
60
57
|
except ValueError:
|
{django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/decorators.py
RENAMED
|
@@ -3,6 +3,7 @@ from typing import Callable, TypeVar
|
|
|
3
3
|
|
|
4
4
|
from .exceptions import (
|
|
5
5
|
InvalidVersionError,
|
|
6
|
+
VersioningError,
|
|
6
7
|
VersionRangeError,
|
|
7
8
|
VersionTypeError,
|
|
8
9
|
)
|
|
@@ -55,8 +56,13 @@ def endpoint(
|
|
|
55
56
|
VersionRangeError: If both ``version`` and ``versions`` are given, or
|
|
56
57
|
settings are invalid, or ``ver_range`` receives an invalid range.
|
|
57
58
|
VersionTypeError: If a version is not an integer.
|
|
59
|
+
VersioningError: If the route postfix is absolute.
|
|
58
60
|
InvalidVersionError: If a version exceeds ``API_MAX_VERSION``.
|
|
59
61
|
"""
|
|
62
|
+
if not isinstance(postfix, str):
|
|
63
|
+
raise TypeError("postfix must be a string.")
|
|
64
|
+
if postfix.startswith("/"):
|
|
65
|
+
raise VersioningError("postfix must be relative and must not start with '/'.")
|
|
60
66
|
if version is not None and versions is not None:
|
|
61
67
|
raise VersionRangeError("Use either 'version' or 'versions', not both.")
|
|
62
68
|
|
{django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/lifecycle.py
RENAMED
|
@@ -42,7 +42,11 @@ class LifecycleMiddleware:
|
|
|
42
42
|
|
|
43
43
|
API_VERSION_LIFECYCLE = {
|
|
44
44
|
1: {"status": "retired", "sunset": "2024-01-01"},
|
|
45
|
-
2: {
|
|
45
|
+
2: {
|
|
46
|
+
"status": "deprecated",
|
|
47
|
+
"deprecated_at": "2026-01-01T00:00:00+00:00",
|
|
48
|
+
"sunset": "2026-06-01",
|
|
49
|
+
},
|
|
46
50
|
3: {"status": "active"},
|
|
47
51
|
}
|
|
48
52
|
"""
|
|
@@ -60,39 +64,60 @@ class LifecycleMiddleware:
|
|
|
60
64
|
if not meta:
|
|
61
65
|
return self.get_response(request)
|
|
62
66
|
|
|
67
|
+
deprecated_at = meta.get("deprecated_at")
|
|
68
|
+
deprecation_date = (
|
|
69
|
+
_parse_lifecycle_date(deprecated_at, "deprecation")
|
|
70
|
+
if deprecated_at
|
|
71
|
+
else None
|
|
72
|
+
)
|
|
63
73
|
sunset = meta.get("sunset")
|
|
64
|
-
if sunset
|
|
74
|
+
sunset_date = _parse_sunset(sunset) if sunset else None
|
|
75
|
+
if sunset_date and _is_past(sunset_date):
|
|
65
76
|
return HttpResponseGone(
|
|
66
77
|
f"API version {version} has been retired as of {sunset}."
|
|
67
78
|
)
|
|
68
79
|
|
|
69
80
|
response = self.get_response(request)
|
|
70
81
|
if meta.get("status") == "deprecated":
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
82
|
+
if deprecation_date is not None:
|
|
83
|
+
response["Deprecation"] = _to_structured_field_date(deprecation_date)
|
|
84
|
+
else:
|
|
85
|
+
logger.warning(
|
|
86
|
+
"Deprecated API version %s has no valid deprecated_at date; "
|
|
87
|
+
"omitting the Deprecation header.",
|
|
88
|
+
version,
|
|
89
|
+
)
|
|
90
|
+
if sunset_date:
|
|
91
|
+
response["Sunset"] = _to_http_date(sunset_date)
|
|
74
92
|
return response
|
|
75
93
|
|
|
76
94
|
|
|
95
|
+
def _coerce_version(value: Any) -> int | None:
|
|
96
|
+
"""Accept integer versions without truncating booleans or other numeric types."""
|
|
97
|
+
if isinstance(value, bool):
|
|
98
|
+
return None
|
|
99
|
+
if isinstance(value, int):
|
|
100
|
+
return value
|
|
101
|
+
if isinstance(value, str) and value.isdecimal():
|
|
102
|
+
return int(value)
|
|
103
|
+
return None
|
|
104
|
+
|
|
105
|
+
|
|
77
106
|
def _extract_version(request: HttpRequest) -> int | None:
|
|
78
107
|
# Path-based: request.version is set by DRF or by URLPathVersioning.
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
pass
|
|
108
|
+
version = _coerce_version(getattr(request, "version", None))
|
|
109
|
+
if version is not None:
|
|
110
|
+
return version
|
|
111
|
+
|
|
84
112
|
# Fallback: parse from resolver_match kwargs.
|
|
85
113
|
match = getattr(request, "resolver_match", None)
|
|
86
|
-
if match
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
114
|
+
if match:
|
|
115
|
+
version = _coerce_version(match.kwargs.get("version"))
|
|
116
|
+
if version is not None:
|
|
117
|
+
return version
|
|
118
|
+
|
|
91
119
|
# Fallback: extract from static URL path using API_BASE_PATH pattern.
|
|
92
|
-
|
|
93
|
-
if version is not None:
|
|
94
|
-
return version
|
|
95
|
-
return None
|
|
120
|
+
return _extract_version_from_path(request)
|
|
96
121
|
|
|
97
122
|
|
|
98
123
|
def _extract_version_from_path(request: HttpRequest) -> int | None:
|
|
@@ -137,18 +162,36 @@ def _extract_version_from_path(request: HttpRequest) -> int | None:
|
|
|
137
162
|
return None
|
|
138
163
|
|
|
139
164
|
|
|
140
|
-
def
|
|
165
|
+
def _parse_sunset(value: Any) -> datetime | None:
|
|
166
|
+
"""Parse a configured sunset value and normalize it to UTC."""
|
|
167
|
+
return _parse_lifecycle_date(value, "sunset")
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _parse_lifecycle_date(value: Any, field_name: str) -> datetime | None:
|
|
171
|
+
"""Parse an ISO 8601 lifecycle date and normalize it to UTC."""
|
|
172
|
+
if not isinstance(value, str):
|
|
173
|
+
logger.warning("Invalid %s date %r; ignoring.", field_name, value)
|
|
174
|
+
return None
|
|
175
|
+
|
|
141
176
|
try:
|
|
142
|
-
|
|
177
|
+
parsed = datetime.fromisoformat(value)
|
|
143
178
|
except ValueError:
|
|
144
|
-
logger.warning("Invalid
|
|
145
|
-
return
|
|
179
|
+
logger.warning("Invalid %s date %r; ignoring.", field_name, value)
|
|
180
|
+
return None
|
|
181
|
+
|
|
182
|
+
if parsed.tzinfo is None:
|
|
183
|
+
return parsed.replace(tzinfo=timezone.utc)
|
|
184
|
+
return parsed.astimezone(timezone.utc)
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def _is_past(date: datetime) -> bool:
|
|
146
188
|
return date < datetime.now(timezone.utc)
|
|
147
189
|
|
|
148
190
|
|
|
149
|
-
def _to_http_date(
|
|
150
|
-
try:
|
|
151
|
-
date = datetime.fromisoformat(date_str).replace(tzinfo=timezone.utc)
|
|
152
|
-
except ValueError:
|
|
153
|
-
return date_str
|
|
191
|
+
def _to_http_date(date: datetime) -> str:
|
|
154
192
|
return date.strftime("%a, %d %b %Y %H:%M:%S GMT")
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def _to_structured_field_date(date: datetime) -> str:
|
|
196
|
+
"""Serialize an RFC 9745 Date as an RFC 9651 Structured Field Date."""
|
|
197
|
+
return f"@{int(date.timestamp())}"
|