django-api-versioning 0.3.8__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 (46) hide show
  1. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/CHANGELOG.md +40 -0
  2. {django_api_versioning-0.3.8/django_api_versioning.egg-info → django_api_versioning-1.0.0}/PKG-INFO +18 -11
  3. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/README.md +15 -8
  4. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/lifecycle.py +31 -4
  5. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/settings.py +35 -0
  6. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0/django_api_versioning.egg-info}/PKG-INFO +18 -11
  7. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/requires.txt +3 -1
  8. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/pyproject.toml +3 -3
  9. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/requirements-dev.txt +3 -2
  10. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_lifecycle.py +56 -14
  11. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_settings.py +26 -0
  12. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/LICENSE +0 -0
  13. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/MANIFEST.in +0 -0
  14. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/__init__.py +0 -0
  15. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/channels.py +0 -0
  16. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/decorators.py +0 -0
  17. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/exceptions.py +0 -0
  18. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/management/__init__.py +0 -0
  19. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/__init__.py +0 -0
  20. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/check_versions.py +0 -0
  21. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/management/commands/migrate_endpoints.py +0 -0
  22. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/py.typed +0 -0
  23. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/registry.py +0 -0
  24. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/reverse.py +0 -0
  25. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/testing.py +0 -0
  26. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning/urls.py +0 -0
  27. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/SOURCES.txt +0 -0
  28. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
  29. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/django_api_versioning.egg-info/top_level.txt +0 -0
  30. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/pytest.ini +0 -0
  31. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/requirements.txt +0 -0
  32. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/setup.cfg +0 -0
  33. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/__init__.py +0 -0
  34. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/conftest.py +0 -0
  35. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/settings.py +0 -0
  36. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_channels.py +0 -0
  37. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_channels_extra.py +0 -0
  38. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_decorators.py +0 -0
  39. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_distribution_contents.py +0 -0
  40. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_exceptions.py +0 -0
  41. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_management_commands.py +0 -0
  42. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_registry.py +0 -0
  43. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_reverse.py +0 -0
  44. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_segment_model.py +0 -0
  45. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_testing_utils.py +0 -0
  46. {django_api_versioning-0.3.8 → django_api_versioning-1.0.0}/tests/test_urls.py +0 -0
@@ -8,6 +8,46 @@ 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
+
11
51
  ## [0.3.8] - 2026-11-16
12
52
 
13
53
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: django-api-versioning
3
- Version: 0.3.8
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
6
  License-Expression: MIT
@@ -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,7 +39,7 @@ 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"
@@ -51,7 +51,7 @@ Dynamic: license-file
51
51
  [![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
52
52
  [![PyPI Downloads](https://img.shields.io/pypi/dm/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
53
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)
54
- [![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/)
55
55
  [![Python versions](https://img.shields.io/pypi/pyversions/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
56
56
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
57
57
 
@@ -194,6 +194,8 @@ Requirements:
194
194
  - Python >= 3.10
195
195
  - Django >= 4.2
196
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
+
197
199
  Django REST Framework is optional. The package can be used with Django-native function-based and class-based views without installing DRF.
198
200
 
199
201
  ## Quick Start
@@ -743,7 +745,11 @@ Configure lifecycle metadata in Django settings:
743
745
 
744
746
  API_VERSION_LIFECYCLE = {
745
747
  1: {"status": "retired", "sunset": "2025-01-01"},
746
- 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
+ },
747
753
  3: {"status": "active"},
748
754
  }
749
755
 
@@ -756,7 +762,7 @@ MIDDLEWARE = [
756
762
  For a version configured as deprecated with a future sunset date, the middleware adds:
757
763
 
758
764
  ```http
759
- Deprecation: true
765
+ Deprecation: @1767225600
760
766
  Sunset: Tue, 01 Jun 2027 00:00:00 GMT
761
767
  ```
762
768
 
@@ -776,7 +782,7 @@ The middleware attempts to identify the request version in this order:
776
782
 
777
783
  This allows the middleware to identify versions from the package's static versioned URL paths even when `request.version` is not set.
778
784
 
779
- **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).
780
786
 
781
787
  ## Configuration reference
782
788
 
@@ -1010,7 +1016,7 @@ For the current compatibility and CI verification status, see the [GitHub Action
1010
1016
 
1011
1017
  ## Contributing
1012
1018
 
1013
- 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.
1014
1020
 
1015
1021
  ### Setup
1016
1022
 
@@ -1075,9 +1081,10 @@ docker run --rm dapi:py315
1075
1081
  ### Releasing
1076
1082
 
1077
1083
  Releases are maintainer operations. Prepare the version bump and changelog
1078
- on a dedicated release branch, run the complete compatibility and artifact
1079
- checks, and submit the changes through a reviewed pull request to the
1080
- project's protected default branch. Do not push directly to `main`.
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.
1081
1088
 
1082
1089
  After the reviewed release commit is present on the default branch, create
1083
1090
  and push the matching version tag:
@@ -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
@@ -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
 
@@ -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
 
@@ -1027,9 +1033,10 @@ docker run --rm dapi:py315
1027
1033
  ### Releasing
1028
1034
 
1029
1035
  Releases are maintainer operations. Prepare the version bump and changelog
1030
- on a dedicated release branch, run the complete compatibility and artifact
1031
- checks, and submit the changes through a reviewed pull request to the
1032
- project's protected default branch. Do not push directly to `main`.
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.
1033
1040
 
1034
1041
  After the reviewed release commit is present on the default branch, create
1035
1042
  and push the matching version tag:
@@ -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,6 +64,12 @@ 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
74
  sunset_date = _parse_sunset(sunset) if sunset else None
65
75
  if sunset_date and _is_past(sunset_date):
@@ -69,7 +79,14 @@ class LifecycleMiddleware:
69
79
 
70
80
  response = self.get_response(request)
71
81
  if meta.get("status") == "deprecated":
72
- response["Deprecation"] = "true"
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
+ )
73
90
  if sunset_date:
74
91
  response["Sunset"] = _to_http_date(sunset_date)
75
92
  return response
@@ -147,14 +164,19 @@ def _extract_version_from_path(request: HttpRequest) -> int | None:
147
164
 
148
165
  def _parse_sunset(value: Any) -> datetime | None:
149
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."""
150
172
  if not isinstance(value, str):
151
- logger.warning("Invalid sunset date %r; ignoring.", value)
173
+ logger.warning("Invalid %s date %r; ignoring.", field_name, value)
152
174
  return None
153
175
 
154
176
  try:
155
177
  parsed = datetime.fromisoformat(value)
156
178
  except ValueError:
157
- logger.warning("Invalid sunset date %r; ignoring.", value)
179
+ logger.warning("Invalid %s date %r; ignoring.", field_name, value)
158
180
  return None
159
181
 
160
182
  if parsed.tzinfo is None:
@@ -168,3 +190,8 @@ def _is_past(date: datetime) -> bool:
168
190
 
169
191
  def _to_http_date(date: datetime) -> str:
170
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())}"
@@ -1,5 +1,6 @@
1
1
  import logging
2
2
  from dataclasses import dataclass, field
3
+ from datetime import datetime
3
4
  from string import Formatter
4
5
  from typing import Any, Callable
5
6
 
@@ -150,6 +151,40 @@ class APISettings:
150
151
  f"Lifecycle metadata for version {version} must be a dict."
151
152
  )
152
153
 
154
+ status = meta.get("status")
155
+ if status not in {"active", "deprecated", "retired"}:
156
+ raise VersioningError(
157
+ f"Lifecycle status for version {version} must be one of "
158
+ "'active', 'deprecated', or 'retired'."
159
+ )
160
+
161
+ if status == "deprecated" and "deprecated_at" not in meta:
162
+ raise VersioningError(
163
+ f"Deprecated API version {version} requires a "
164
+ "'deprecated_at' ISO 8601 date or datetime."
165
+ )
166
+ if status == "retired" and "sunset" not in meta:
167
+ raise VersioningError(
168
+ f"Retired API version {version} requires a 'sunset' date."
169
+ )
170
+
171
+ for field_name in ("deprecated_at", "sunset"):
172
+ if field_name not in meta:
173
+ continue
174
+ value = meta[field_name]
175
+ if not isinstance(value, str):
176
+ raise VersioningError(
177
+ f"Lifecycle {field_name} for version {version} "
178
+ "must be an ISO 8601 string."
179
+ )
180
+ try:
181
+ datetime.fromisoformat(value)
182
+ except ValueError as exc:
183
+ raise VersioningError(
184
+ f"Lifecycle {field_name} for version {version} "
185
+ "must be a valid ISO 8601 date or datetime."
186
+ ) from exc
187
+
153
188
  def _validate_channels(self) -> None:
154
189
  allowed = {"path", "header", "query"}
155
190
  if not isinstance(self.API_VERSIONING_CHANNELS, list):
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: django-api-versioning
3
- Version: 0.3.8
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
6
  License-Expression: MIT
@@ -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,7 +39,7 @@ 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"
@@ -51,7 +51,7 @@ Dynamic: license-file
51
51
  [![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
52
52
  [![PyPI Downloads](https://img.shields.io/pypi/dm/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
53
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)
54
- [![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/)
55
55
  [![Python versions](https://img.shields.io/pypi/pyversions/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
56
56
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
57
57
 
@@ -194,6 +194,8 @@ Requirements:
194
194
  - Python >= 3.10
195
195
  - Django >= 4.2
196
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
+
197
199
  Django REST Framework is optional. The package can be used with Django-native function-based and class-based views without installing DRF.
198
200
 
199
201
  ## Quick Start
@@ -743,7 +745,11 @@ Configure lifecycle metadata in Django settings:
743
745
 
744
746
  API_VERSION_LIFECYCLE = {
745
747
  1: {"status": "retired", "sunset": "2025-01-01"},
746
- 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
+ },
747
753
  3: {"status": "active"},
748
754
  }
749
755
 
@@ -756,7 +762,7 @@ MIDDLEWARE = [
756
762
  For a version configured as deprecated with a future sunset date, the middleware adds:
757
763
 
758
764
  ```http
759
- Deprecation: true
765
+ Deprecation: @1767225600
760
766
  Sunset: Tue, 01 Jun 2027 00:00:00 GMT
761
767
  ```
762
768
 
@@ -776,7 +782,7 @@ The middleware attempts to identify the request version in this order:
776
782
 
777
783
  This allows the middleware to identify versions from the package's static versioned URL paths even when `request.version` is not set.
778
784
 
779
- **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).
780
786
 
781
787
  ## Configuration reference
782
788
 
@@ -1010,7 +1016,7 @@ For the current compatibility and CI verification status, see the [GitHub Action
1010
1016
 
1011
1017
  ## Contributing
1012
1018
 
1013
- 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.
1014
1020
 
1015
1021
  ### Setup
1016
1022
 
@@ -1075,9 +1081,10 @@ docker run --rm dapi:py315
1075
1081
  ### Releasing
1076
1082
 
1077
1083
  Releases are maintainer operations. Prepare the version bump and changelog
1078
- on a dedicated release branch, run the complete compatibility and artifact
1079
- checks, and submit the changes through a reviewed pull request to the
1080
- project's protected default branch. Do not push directly to `main`.
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.
1081
1088
 
1082
1089
  After the reviewed release commit is present on the default branch, create
1083
1090
  and push the matching version tag:
@@ -8,10 +8,12 @@ mypy>=2.4.0
8
8
  pytest>=9.2.0
9
9
  pytest-django>=4.14.0
10
10
  pytest-cov>=7.1.0
11
- pre-commit>=4.6.2
12
11
  twine>=7.0.0
13
12
  build>=1.6.1
14
13
  djangorestframework>=3.18
15
14
 
16
15
  [dev:python_version < "3.11"]
17
16
  tomli>=2.0.1
17
+
18
+ [dev:python_version >= "3.11"]
19
+ pre-commit>=4.7.0
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "django-api-versioning"
7
- version = "0.3.8"
7
+ version = "1.0.0"
8
8
  description = "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."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -42,7 +42,7 @@ classifiers = [
42
42
  "Framework :: Django :: 5.2",
43
43
  "Framework :: Django :: 6.0",
44
44
  "Framework :: Django :: 6.1",
45
- "Development Status :: 4 - Beta",
45
+ "Development Status :: 5 - Production/Stable",
46
46
  "Intended Audience :: Developers",
47
47
  "Operating System :: OS Independent",
48
48
  "Topic :: Internet :: WWW/HTTP",
@@ -62,7 +62,7 @@ dev = [
62
62
  "pytest>=9.2.0",
63
63
  "pytest-django>=4.14.0",
64
64
  "pytest-cov>=7.1.0",
65
- "pre-commit>=4.6.2",
65
+ "pre-commit>=4.7.0; python_version >= '3.11'",
66
66
  "twine>=7.0.0",
67
67
  "build>=1.6.1",
68
68
  "djangorestframework>=3.18",
@@ -2,7 +2,7 @@
2
2
  pytest>=9.2.0
3
3
  pytest-django>=4.14.0
4
4
  pytest-cov>=7.1.0
5
- pre-commit>=4.6.2
5
+ pre-commit>=4.7.0; python_version >= "3.11"
6
6
  black>=26.10.1
7
7
  flake8>=7.4.1
8
8
  Flake8-pyproject>=1.2.4
@@ -10,4 +10,5 @@ isort>=9.0.2
10
10
  mypy>=2.4.0
11
11
  twine>=7.0.0
12
12
  build>=1.6.1
13
- djangorestframework>=3.18.3tomli>=2.0.1; python_version < "3.11"
13
+ djangorestframework>=3.18.3
14
+ tomli>=2.0.1; python_version < "3.11"
@@ -10,6 +10,7 @@ from django_api_versioning.settings import api_settings as settings
10
10
  # Dates relative to "today" so the tests never depend on the current date.
11
11
  FUTURE = (date.today() + timedelta(days=365)).isoformat()
12
12
  PAST = (date.today() - timedelta(days=365)).isoformat()
13
+ DEPRECATED_AT = "2025-01-01T00:00:00+00:00"
13
14
 
14
15
 
15
16
  def _request(version: str):
@@ -22,12 +23,12 @@ def test_deprecated_version_gets_headers(monkeypatch):
22
23
  monkeypatch.setitem(
23
24
  settings.API_VERSION_LIFECYCLE,
24
25
  2,
25
- {"status": "deprecated", "sunset": FUTURE},
26
+ {"status": "deprecated", "deprecated_at": DEPRECATED_AT, "sunset": FUTURE},
26
27
  )
27
28
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
28
29
  response = middleware(_request("2"))
29
30
 
30
- assert response["Deprecation"] == "true"
31
+ assert response["Deprecation"] == "@1735689600"
31
32
  assert "Sunset" in response
32
33
 
33
34
 
@@ -35,15 +36,29 @@ def test_deprecated_without_sunset_only_deprecation(monkeypatch):
35
36
  monkeypatch.setitem(
36
37
  settings.API_VERSION_LIFECYCLE,
37
38
  2,
38
- {"status": "deprecated"},
39
+ {"status": "deprecated", "deprecated_at": DEPRECATED_AT},
39
40
  )
40
41
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
41
42
  response = middleware(_request("2"))
42
43
 
43
- assert response["Deprecation"] == "true"
44
+ assert response["Deprecation"] == "@1735689600"
44
45
  assert "Sunset" not in response
45
46
 
46
47
 
48
+ def test_deprecated_without_valid_deprecation_date_omits_header(monkeypatch, caplog):
49
+ monkeypatch.setitem(
50
+ settings.API_VERSION_LIFECYCLE,
51
+ 2,
52
+ {"status": "deprecated", "deprecated_at": "not-a-date"},
53
+ )
54
+ middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
55
+ response = middleware(_request("2"))
56
+
57
+ assert response.status_code == 200
58
+ assert "Deprecation" not in response
59
+ assert "no valid deprecated_at date" in caplog.text
60
+
61
+
47
62
  def test_retired_version_returns_410(monkeypatch):
48
63
  monkeypatch.setitem(
49
64
  settings.API_VERSION_LIFECYCLE,
@@ -99,12 +114,16 @@ def test_invalid_sunset_date_is_ignored(monkeypatch, caplog):
99
114
  monkeypatch.setitem(
100
115
  settings.API_VERSION_LIFECYCLE,
101
116
  2,
102
- {"status": "deprecated", "sunset": "not-a-date"},
117
+ {
118
+ "status": "deprecated",
119
+ "deprecated_at": DEPRECATED_AT,
120
+ "sunset": "not-a-date",
121
+ },
103
122
  )
104
123
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
105
124
  response = middleware(_request("2"))
106
125
 
107
- assert response["Deprecation"] == "true"
126
+ assert response["Deprecation"] == "@1735689600"
108
127
  assert "Sunset" not in response
109
128
  assert "Invalid sunset date" in caplog.text
110
129
 
@@ -113,13 +132,17 @@ def test_non_string_sunset_is_ignored(monkeypatch, caplog):
113
132
  monkeypatch.setitem(
114
133
  settings.API_VERSION_LIFECYCLE,
115
134
  2,
116
- {"status": "deprecated", "sunset": 123},
135
+ {
136
+ "status": "deprecated",
137
+ "deprecated_at": DEPRECATED_AT,
138
+ "sunset": 123,
139
+ },
117
140
  )
118
141
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
119
142
  response = middleware(_request("2"))
120
143
 
121
144
  assert response.status_code == 200
122
- assert response["Deprecation"] == "true"
145
+ assert response["Deprecation"] == "@1735689600"
123
146
  assert "Sunset" not in response
124
147
  assert "Invalid sunset date" in caplog.text
125
148
 
@@ -130,12 +153,14 @@ def test_timezone_aware_sunset_is_converted_to_utc(monkeypatch):
130
153
  2,
131
154
  {
132
155
  "status": "deprecated",
156
+ "deprecated_at": "2030-01-01T12:00:00+03:00",
133
157
  "sunset": "2030-01-01T12:00:00+03:00",
134
158
  },
135
159
  )
136
160
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
137
161
  response = middleware(_request("2"))
138
162
 
163
+ assert response["Deprecation"] == "@1893488400"
139
164
  assert response["Sunset"] == "Tue, 01 Jan 2030 09:00:00 GMT"
140
165
 
141
166
 
@@ -354,13 +379,19 @@ class TestOverrideSettingsCompatibility:
354
379
  from django.test import override_settings
355
380
 
356
381
  with override_settings(
357
- API_VERSION_LIFECYCLE={2: {"status": "deprecated", "sunset": FUTURE}}
382
+ API_VERSION_LIFECYCLE={
383
+ 2: {
384
+ "status": "deprecated",
385
+ "deprecated_at": DEPRECATED_AT,
386
+ "sunset": FUTURE,
387
+ }
388
+ }
358
389
  ):
359
390
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
360
391
  response = middleware(_request("2"))
361
392
 
362
393
  assert response.status_code == 200
363
- assert response["Deprecation"] == "true"
394
+ assert response["Deprecation"] == "@1735689600"
364
395
  assert "Sunset" in response
365
396
 
366
397
  def test_override_settings_lifecycle_retired_past_sunset(self):
@@ -467,7 +498,11 @@ class TestOverrideSettingsCompatibility:
467
498
  with override_settings(
468
499
  API_VERSION_LIFECYCLE={
469
500
  1: {"status": "retired", "sunset": PAST},
470
- 2: {"status": "deprecated", "sunset": FUTURE},
501
+ 2: {
502
+ "status": "deprecated",
503
+ "deprecated_at": DEPRECATED_AT,
504
+ "sunset": FUTURE,
505
+ },
471
506
  3: {"status": "active"},
472
507
  }
473
508
  ):
@@ -480,7 +515,7 @@ class TestOverrideSettingsCompatibility:
480
515
  # Version 2: deprecated with future sunset -> 200 with headers
481
516
  response = middleware(_request("2"))
482
517
  assert response.status_code == 200
483
- assert response["Deprecation"] == "true"
518
+ assert response["Deprecation"] == "@1735689600"
484
519
 
485
520
  # Version 3: active -> 200 with no headers
486
521
  response = middleware(_request("3"))
@@ -510,12 +545,19 @@ class TestOverrideSettingsCompatibility:
510
545
  """override_settings with deprecated status but no sunset."""
511
546
  from django.test import override_settings
512
547
 
513
- with override_settings(API_VERSION_LIFECYCLE={2: {"status": "deprecated"}}):
548
+ with override_settings(
549
+ API_VERSION_LIFECYCLE={
550
+ 2: {
551
+ "status": "deprecated",
552
+ "deprecated_at": DEPRECATED_AT,
553
+ }
554
+ }
555
+ ):
514
556
  middleware = LifecycleMiddleware(lambda req: HttpResponse("ok"))
515
557
  response = middleware(_request("2"))
516
558
 
517
559
  assert response.status_code == 200
518
- assert response["Deprecation"] == "true"
560
+ assert response["Deprecation"] == "@1735689600"
519
561
  assert "Sunset" not in response
520
562
 
521
563
  def test_override_settings_lifecycle_and_base_path_together(self):
@@ -104,6 +104,32 @@ class TestLifecycleValidation:
104
104
  with pytest.raises(VersioningError):
105
105
  APISettings(API_VERSION_LIFECYCLE={1: "active"})
106
106
 
107
+ def test_deprecated_status_requires_deprecated_at(self):
108
+ with pytest.raises(VersioningError, match="requires a 'deprecated_at'"):
109
+ APISettings(API_VERSION_LIFECYCLE={1: {"status": "deprecated"}})
110
+
111
+ def test_retired_status_requires_sunset(self):
112
+ with pytest.raises(VersioningError, match="requires a 'sunset'"):
113
+ APISettings(API_VERSION_LIFECYCLE={1: {"status": "retired"}})
114
+
115
+ def test_unknown_lifecycle_status_raises(self):
116
+ with pytest.raises(VersioningError, match="Lifecycle status"):
117
+ APISettings(API_VERSION_LIFECYCLE={1: {"status": "disabled"}})
118
+
119
+ @pytest.mark.parametrize(
120
+ "field_name,value",
121
+ [
122
+ ("deprecated_at", "not-a-date"),
123
+ ("sunset", "not-a-date"),
124
+ ("deprecated_at", 123),
125
+ ("sunset", 123),
126
+ ],
127
+ )
128
+ def test_invalid_lifecycle_dates_raise(self, field_name, value):
129
+ metadata = {"status": "active", field_name: value}
130
+ with pytest.raises(VersioningError, match=field_name):
131
+ APISettings(API_VERSION_LIFECYCLE={1: metadata})
132
+
107
133
 
108
134
  class TestChannelsValidation:
109
135
  def test_unknown_channel_raises(self):