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.
Files changed (49) hide show
  1. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/CHANGELOG.md +54 -0
  2. django_api_versioning-1.0.0/MANIFEST.in +27 -0
  3. {django_api_versioning-0.3.7/django_api_versioning.egg-info → django_api_versioning-1.0.0}/PKG-INFO +38 -23
  4. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/README.md +33 -19
  5. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/channels.py +18 -21
  6. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/decorators.py +6 -0
  7. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/lifecycle.py +71 -28
  8. django_api_versioning-1.0.0/django_api_versioning/management/commands/migrate_endpoints.py +249 -0
  9. django_api_versioning-1.0.0/django_api_versioning/py.typed +1 -0
  10. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/registry.py +18 -17
  11. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/reverse.py +32 -3
  12. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/settings.py +61 -6
  13. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/testing.py +18 -2
  14. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0/django_api_versioning.egg-info}/PKG-INFO +38 -23
  15. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/SOURCES.txt +2 -0
  16. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/requires.txt +6 -1
  17. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/top_level.txt +0 -2
  18. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/pyproject.toml +16 -6
  19. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/requirements-dev.txt +3 -2
  20. django_api_versioning-1.0.0/tests/test_channels_extra.py +69 -0
  21. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_decorators.py +30 -0
  22. django_api_versioning-1.0.0/tests/test_distribution_contents.py +160 -0
  23. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_lifecycle.py +119 -12
  24. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_management_commands.py +269 -14
  25. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_registry.py +5 -4
  26. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_reverse.py +64 -2
  27. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_settings.py +62 -0
  28. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_testing_utils.py +26 -1
  29. django_api_versioning-0.3.7/MANIFEST.in +0 -9
  30. django_api_versioning-0.3.7/django_api_versioning/management/commands/migrate_endpoints.py +0 -78
  31. django_api_versioning-0.3.7/tests/test_channels_extra.py +0 -33
  32. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/LICENSE +0 -0
  33. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/__init__.py +0 -0
  34. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/exceptions.py +0 -0
  35. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/management/__init__.py +0 -0
  36. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/__init__.py +0 -0
  37. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/check_versions.py +0 -0
  38. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning/urls.py +0 -0
  39. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
  40. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/pytest.ini +0 -0
  41. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/requirements.txt +0 -0
  42. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/setup.cfg +0 -0
  43. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/__init__.py +0 -0
  44. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/conftest.py +0 -0
  45. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/settings.py +0 -0
  46. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_channels.py +0 -0
  47. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_exceptions.py +0 -0
  48. {django_api_versioning-0.3.7 → django_api_versioning-1.0.0}/tests/test_segment_model.py +0 -0
  49. {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
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: django-api-versioning
3
- Version: 0.3.7
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 :: 4 - Beta
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.6.2; extra == "dev"
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
  [![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
51
52
  [![PyPI Downloads](https://img.shields.io/pypi/dm/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
52
53
  [![Build Status](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml/badge.svg)](https://github.com/mojtaba-arvin/django-api-versioning/actions)
53
- [![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.2%2B%20%7C%206.x-blue)](https://www.djangoproject.com/)
54
+ [![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.2%20%7C%206.0%20%7C%206.1-blue)](https://www.djangoproject.com/)
54
55
  [![Python versions](https://img.shields.io/pypi/pyversions/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
55
56
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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 the `{version}` placeholder.
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: {"status": "deprecated", "sunset": "2027-06-01"},
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: true
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:** The current implementation emits the legacy boolean value `Deprecation: true`. It does not implement the date-valued structured field defined by [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745). The `Sunset` header follows the HTTP-date format specified by [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594).
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 scans Python files for `@endpoint` declarations containing legacy `forward` or `backward` arguments and suggests or applies textual replacements.
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 the output before accepting it.** The command uses source-text matching and rewriting; it is not an AST-based semantic migration tool. It cannot guarantee that every rewritten declaration preserves the application's intended routing behavior.
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
- 1. Update the `version` in `pyproject.toml` and document the release in `CHANGELOG.md`.
1077
- 2. Commit and push the release commit to `main`.
1078
- 3. Create and push a matching version tag:
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
- ```bash
1081
- git tag vX.Y.Z
1082
- git push origin vX.Y.Z
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 build the package, validate
1086
- the distribution with `twine check --strict`, and publish it to PyPI
1087
- using PyPI Trusted Publishing (GitHub Actions OIDC).
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
  [![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
4
4
  [![PyPI Downloads](https://img.shields.io/pypi/dm/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
5
5
  [![Build Status](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml/badge.svg)](https://github.com/mojtaba-arvin/django-api-versioning/actions)
6
- [![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.2%2B%20%7C%206.x-blue)](https://www.djangoproject.com/)
6
+ [![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.2%20%7C%206.0%20%7C%206.1-blue)](https://www.djangoproject.com/)
7
7
  [![Python versions](https://img.shields.io/pypi/pyversions/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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 the `{version}` placeholder.
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: {"status": "deprecated", "sunset": "2027-06-01"},
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: true
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:** The current implementation emits the legacy boolean value `Deprecation: true`. It does not implement the date-valued structured field defined by [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745). The `Sunset` header follows the HTTP-date format specified by [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594).
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 scans Python files for `@endpoint` declarations containing legacy `forward` or `backward` arguments and suggests or applies textual replacements.
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 the output before accepting it.** The command uses source-text matching and rewriting; it is not an AST-based semantic migration tool. It cannot guarantee that every rewritten declaration preserves the application's intended routing behavior.
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
- 1. Update the `version` in `pyproject.toml` and document the release in `CHANGELOG.md`.
1030
- 2. Commit and push the release commit to `main`.
1031
- 3. Create and push a matching version tag:
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
- ```bash
1034
- git tag vX.Y.Z
1035
- git push origin vX.Y.Z
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 build the package, validate
1039
- the distribution with `twine check --strict`, and publish it to PyPI
1040
- using PyPI Trusted Publishing (GitHub Actions OIDC).
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
 
@@ -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
- if match and "version" in match.kwargs:
30
- try:
31
- return int(match.kwargs["version"])
32
- except (TypeError, ValueError):
33
- return None
34
- if hasattr(request, "version") and request.version is not None:
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
- raw = request.headers.get("Accept-Version")
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
- raw = request.GET.get("version")
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
- raw = raw.strip().lower().lstrip("v")
54
+
58
55
  try:
59
56
  return int(raw)
60
57
  except ValueError:
@@ -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
 
@@ -42,7 +42,11 @@ class LifecycleMiddleware:
42
42
 
43
43
  API_VERSION_LIFECYCLE = {
44
44
  1: {"status": "retired", "sunset": "2024-01-01"},
45
- 2: {"status": "deprecated", "sunset": "2026-06-01"},
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 and _is_past(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
- response["Deprecation"] = "true"
72
- if sunset:
73
- response["Sunset"] = _to_http_date(sunset)
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
- if hasattr(request, "version") and request.version is not None:
80
- try:
81
- return int(request.version)
82
- except (TypeError, ValueError):
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 and "version" in match.kwargs:
87
- try:
88
- return int(match.kwargs["version"])
89
- except (TypeError, ValueError):
90
- pass
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
- version = _extract_version_from_path(request)
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 _is_past(date_str: str) -> bool:
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
- date = datetime.fromisoformat(date_str).replace(tzinfo=timezone.utc)
177
+ parsed = datetime.fromisoformat(value)
143
178
  except ValueError:
144
- logger.warning("Invalid sunset date %r; ignoring.", date_str)
145
- return False
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(date_str: str) -> str:
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())}"