django-api-versioning 0.3.6__tar.gz → 0.3.8__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.6 → django_api_versioning-0.3.8}/CHANGELOG.md +25 -0
  2. django_api_versioning-0.3.8/MANIFEST.in +27 -0
  3. {django_api_versioning-0.3.6/django_api_versioning.egg-info → django_api_versioning-0.3.8}/PKG-INFO +56 -26
  4. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/README.md +53 -22
  5. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/channels.py +18 -21
  6. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/decorators.py +6 -0
  7. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/lifecycle.py +42 -26
  8. django_api_versioning-0.3.8/django_api_versioning/management/commands/migrate_endpoints.py +249 -0
  9. django_api_versioning-0.3.8/django_api_versioning/py.typed +1 -0
  10. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/registry.py +18 -17
  11. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/reverse.py +32 -3
  12. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/settings.py +26 -6
  13. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/testing.py +18 -2
  14. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8/django_api_versioning.egg-info}/PKG-INFO +56 -26
  15. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning.egg-info/SOURCES.txt +2 -0
  16. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning.egg-info/requires.txt +3 -0
  17. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning.egg-info/top_level.txt +0 -2
  18. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/pyproject.toml +14 -6
  19. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/requirements-dev.txt +1 -1
  20. django_api_versioning-0.3.8/tests/test_channels_extra.py +69 -0
  21. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_decorators.py +30 -0
  22. django_api_versioning-0.3.8/tests/test_distribution_contents.py +160 -0
  23. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_lifecycle.py +65 -0
  24. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_management_commands.py +269 -14
  25. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_registry.py +5 -4
  26. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_reverse.py +64 -2
  27. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_settings.py +36 -0
  28. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_testing_utils.py +26 -1
  29. django_api_versioning-0.3.6/MANIFEST.in +0 -9
  30. django_api_versioning-0.3.6/django_api_versioning/management/commands/migrate_endpoints.py +0 -78
  31. django_api_versioning-0.3.6/tests/test_channels_extra.py +0 -33
  32. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/LICENSE +0 -0
  33. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/__init__.py +0 -0
  34. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/exceptions.py +0 -0
  35. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/management/__init__.py +0 -0
  36. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/management/commands/__init__.py +0 -0
  37. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/management/commands/check_versions.py +0 -0
  38. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning/urls.py +0 -0
  39. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/django_api_versioning.egg-info/dependency_links.txt +0 -0
  40. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/pytest.ini +0 -0
  41. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/requirements.txt +0 -0
  42. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/setup.cfg +0 -0
  43. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/__init__.py +0 -0
  44. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/conftest.py +0 -0
  45. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/settings.py +0 -0
  46. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_channels.py +0 -0
  47. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_exceptions.py +0 -0
  48. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_segment_model.py +0 -0
  49. {django_api_versioning-0.3.6 → django_api_versioning-0.3.8}/tests/test_urls.py +0 -0
@@ -8,6 +8,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [0.3.8] - 2026-11-16
12
+
13
+ ### Fixed
14
+
15
+ - Ignore invalid lifecycle sunset values instead of emitting invalid `Sunset` headers; normalize timezone-aware sunset timestamps to UTC before enforcement and formatting.
16
+ - Return a class-specific actionable error when a DRF ViewSet class is registered without its required action map.
17
+ - 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.
18
+ - 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.
19
+ - Make the standalone channel extraction helper fall back from an invalid path match to `request.version` and reject repeated `v` prefixes.
20
+
21
+ ### Verified
22
+
23
+ - 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.
24
+
25
+ ## [0.3.7] - 2026-11-14
26
+
27
+ ### Changed
28
+
29
+ - Run the full tox test matrix in parallel by default, with separate coverage data per environment.
30
+
31
+ ### Verified
32
+
33
+ - ✅ All 175 unit tests and 245 integration tests passing in each of the 15 Python/Django environments
34
+ - ✅ Tox lint environment passing
35
+
11
36
  ## [0.3.6] - 2026-11-13
12
37
 
13
38
  ### Fixed
@@ -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.6
3
+ Version: 0.3.8
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
@@ -18,8 +18,6 @@ Classifier: Programming Language :: Python :: 3.14
18
18
  Classifier: Programming Language :: Python :: 3.15
19
19
  Classifier: Framework :: Django
20
20
  Classifier: Framework :: Django :: 4.2
21
- Classifier: Framework :: Django :: 5.0
22
- Classifier: Framework :: Django :: 5.1
23
21
  Classifier: Framework :: Django :: 5.2
24
22
  Classifier: Framework :: Django :: 6.0
25
23
  Classifier: Framework :: Django :: 6.1
@@ -45,6 +43,7 @@ Requires-Dist: pre-commit>=4.6.2; extra == "dev"
45
43
  Requires-Dist: twine>=7.0.0; extra == "dev"
46
44
  Requires-Dist: build>=1.6.1; extra == "dev"
47
45
  Requires-Dist: djangorestframework>=3.18; extra == "dev"
46
+ Requires-Dist: tomli>=2.0.1; python_version < "3.11" and extra == "dev"
48
47
  Dynamic: license-file
49
48
 
50
49
  # Django API Versioning
@@ -52,7 +51,7 @@ Dynamic: license-file
52
51
  [![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
53
52
  [![PyPI Downloads](https://img.shields.io/pypi/dm/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
54
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)
55
- [![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.x%20%7C%206.x-blue)](https://www.djangoproject.com/)
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/)
56
55
  [![Python versions](https://img.shields.io/pypi/pyversions/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
57
56
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
58
57
 
@@ -216,7 +215,7 @@ API_MIN_VERSION = 1
216
215
  API_MAX_VERSION = 3
217
216
  ```
218
217
 
219
- `API_BASE_PATH` must contain the `{version}` placeholder.
218
+ `API_BASE_PATH` must contain exactly one plain `{version}` format field. Additional format fields, conversions, and format specifications are rejected.
220
219
 
221
220
  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.
222
221
 
@@ -263,9 +262,6 @@ In your project's root URL configuration:
263
262
 
264
263
  from django.urls import include, path
265
264
 
266
- from your_app import views # noqa: F401
267
-
268
-
269
265
  from your_app import views # noqa: F401
270
266
 
271
267
  from django_api_versioning.urls import urlpatterns as api_urlpatterns
@@ -788,7 +784,7 @@ This allows the middleware to identify versions from the package's static versio
788
784
 
789
785
  | Setting | Default | Description |
790
786
  | --- | --- | --- |
791
- | `API_BASE_PATH` | `"api/v{version}/"` | Base path template for versioned routes. Must contain `{version}`. |
787
+ | `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. |
792
788
  | `API_MIN_VERSION` | `1` | Lowest valid route version. |
793
789
  | `API_MAX_VERSION` | `1` | Highest valid route version. |
794
790
  | `API_VERSION_LIFECYCLE` | `{}` | Per-version lifecycle metadata. |
@@ -928,7 +924,11 @@ If you need `request.version` populated, consider implementing a custom DRF vers
928
924
 
929
925
  ### Configuration timing
930
926
 
931
- Package settings (`API_MAX_VERSION`, `API_BASE_PATH`, etc.) are validated and loaded at module import time. Using Django's `override_settings` after the package has been imported will NOT affect already-loaded configuration:
927
+ Route-registry settings, such as `API_MAX_VERSION` and `API_BASE_PATH`, are loaded when the package modules and endpoint declarations are imported. Changing these settings with `override_settings` after endpoint registration does not rebuild the existing URL patterns.
928
+
929
+ `LifecycleMiddleware` is different: it reads `API_VERSION_LIFECYCLE` and `API_BASE_PATH` from `django.conf.settings` at request time. This allows lifecycle behavior to respond to runtime setting overrides, but it does not make the already-registered URL patterns dynamic.
930
+
931
+ Configure route-registry settings before importing modules containing `@endpoint` declarations:
932
932
 
933
933
  ```python
934
934
  # ✓ Correct: configure before importing views
@@ -985,9 +985,9 @@ python manage.py migrate_endpoints --dry-run
985
985
  python manage.py migrate_endpoints
986
986
  ```
987
987
 
988
- The command scans Python files for `@endpoint` declarations containing legacy `forward` or `backward` arguments and suggests or applies textual replacements.
988
+ 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.
989
989
 
990
- **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.
990
+ **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.
991
991
 
992
992
  After migration:
993
993
 
@@ -1024,8 +1024,31 @@ pre-commit install
1024
1024
 
1025
1025
  ### Running tests
1026
1026
 
1027
+ Run the unit tests:
1028
+
1029
+ ```bash
1030
+ python -m pytest tests
1031
+ ```
1032
+
1033
+ Run the integration tests:
1034
+
1035
+ ```bash
1036
+ python -m pytest integration_test_project
1037
+ ```
1038
+
1039
+ Run the complete configured Python/Django test matrix:
1040
+
1041
+ ```bash
1042
+ python -m pip install tox
1043
+ tox run-parallel -p auto
1044
+ ```
1045
+
1046
+ The parallel run uses the available CPU count; use `tox run-parallel -p 4`
1047
+ to limit concurrency on memory-constrained machines.
1048
+
1049
+ Run pre-commit checks:
1050
+
1027
1051
  ```bash
1028
- pytest
1029
1052
  pre-commit run --all-files
1030
1053
  ```
1031
1054
 
@@ -1038,10 +1061,10 @@ and delegates execution to `entrypoint.sh`.
1038
1061
  # Build the Docker image
1039
1062
  docker build -t dapi .
1040
1063
 
1041
- # Run the test suite
1064
+ # Run the default test command (unit tests)
1042
1065
  docker run --rm dapi
1043
1066
 
1044
- # Run pre-commit checks followed by the test suite
1067
+ # Run pre-commit checks followed by the unit tests
1045
1068
  docker run --rm -e RUN_PRE_COMMIT=true dapi
1046
1069
 
1047
1070
  # Build and run with a specific Python version
@@ -1051,18 +1074,25 @@ docker run --rm dapi:py315
1051
1074
 
1052
1075
  ### Releasing
1053
1076
 
1054
- 1. Update the `version` in `pyproject.toml` and document the release in `CHANGELOG.md`.
1055
- 2. Commit and push the release commit to `main`.
1056
- 3. Create and push a matching version tag:
1077
+ 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`.
1081
+
1082
+ After the reviewed release commit is present on the default branch, create
1083
+ and push the matching version tag:
1057
1084
 
1058
- ```bash
1059
- git tag vX.Y.Z
1060
- git push origin vX.Y.Z
1061
- ```
1085
+ ```bash
1086
+ git tag -a vX.Y.Z -m "Release vX.Y.Z"
1087
+ git push origin vX.Y.Z
1088
+ ```
1062
1089
 
1063
- Pushing a `v*` tag triggers GitHub Actions to build the package, validate
1064
- the distribution with `twine check`, and publish it to PyPI using
1065
- the `PYPI_API_TOKEN` repository secret.
1090
+ Pushing a `v*` tag triggers GitHub Actions to run the compatibility matrix,
1091
+ build and validate the exact distribution with `twine check --strict`,
1092
+ smoke-test the wheel, and publish it to PyPI using Trusted Publishing
1093
+ (GitHub Actions OIDC). A successful tag push alone does not prove that
1094
+ publication completed; verify the workflow and the version-specific PyPI
1095
+ release page before announcing the release.
1066
1096
 
1067
1097
  ### Reporting issues
1068
1098
 
@@ -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.x%20%7C%206.x-blue)](https://www.djangoproject.com/)
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/)
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
 
@@ -167,7 +167,7 @@ API_MIN_VERSION = 1
167
167
  API_MAX_VERSION = 3
168
168
  ```
169
169
 
170
- `API_BASE_PATH` must contain the `{version}` placeholder.
170
+ `API_BASE_PATH` must contain exactly one plain `{version}` format field. Additional format fields, conversions, and format specifications are rejected.
171
171
 
172
172
  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
173
 
@@ -214,9 +214,6 @@ In your project's root URL configuration:
214
214
 
215
215
  from django.urls import include, path
216
216
 
217
- from your_app import views # noqa: F401
218
-
219
-
220
217
  from your_app import views # noqa: F401
221
218
 
222
219
  from django_api_versioning.urls import urlpatterns as api_urlpatterns
@@ -739,7 +736,7 @@ This allows the middleware to identify versions from the package's static versio
739
736
 
740
737
  | Setting | Default | Description |
741
738
  | --- | --- | --- |
742
- | `API_BASE_PATH` | `"api/v{version}/"` | Base path template for versioned routes. Must contain `{version}`. |
739
+ | `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. |
743
740
  | `API_MIN_VERSION` | `1` | Lowest valid route version. |
744
741
  | `API_MAX_VERSION` | `1` | Highest valid route version. |
745
742
  | `API_VERSION_LIFECYCLE` | `{}` | Per-version lifecycle metadata. |
@@ -879,7 +876,11 @@ If you need `request.version` populated, consider implementing a custom DRF vers
879
876
 
880
877
  ### Configuration timing
881
878
 
882
- Package settings (`API_MAX_VERSION`, `API_BASE_PATH`, etc.) are validated and loaded at module import time. Using Django's `override_settings` after the package has been imported will NOT affect already-loaded configuration:
879
+ Route-registry settings, such as `API_MAX_VERSION` and `API_BASE_PATH`, are loaded when the package modules and endpoint declarations are imported. Changing these settings with `override_settings` after endpoint registration does not rebuild the existing URL patterns.
880
+
881
+ `LifecycleMiddleware` is different: it reads `API_VERSION_LIFECYCLE` and `API_BASE_PATH` from `django.conf.settings` at request time. This allows lifecycle behavior to respond to runtime setting overrides, but it does not make the already-registered URL patterns dynamic.
882
+
883
+ Configure route-registry settings before importing modules containing `@endpoint` declarations:
883
884
 
884
885
  ```python
885
886
  # ✓ Correct: configure before importing views
@@ -936,9 +937,9 @@ python manage.py migrate_endpoints --dry-run
936
937
  python manage.py migrate_endpoints
937
938
  ```
938
939
 
939
- The command scans Python files for `@endpoint` declarations containing legacy `forward` or `backward` arguments and suggests or applies textual replacements.
940
+ 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.
940
941
 
941
- **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.
942
+ **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.
942
943
 
943
944
  After migration:
944
945
 
@@ -975,8 +976,31 @@ pre-commit install
975
976
 
976
977
  ### Running tests
977
978
 
979
+ Run the unit tests:
980
+
981
+ ```bash
982
+ python -m pytest tests
983
+ ```
984
+
985
+ Run the integration tests:
986
+
987
+ ```bash
988
+ python -m pytest integration_test_project
989
+ ```
990
+
991
+ Run the complete configured Python/Django test matrix:
992
+
993
+ ```bash
994
+ python -m pip install tox
995
+ tox run-parallel -p auto
996
+ ```
997
+
998
+ The parallel run uses the available CPU count; use `tox run-parallel -p 4`
999
+ to limit concurrency on memory-constrained machines.
1000
+
1001
+ Run pre-commit checks:
1002
+
978
1003
  ```bash
979
- pytest
980
1004
  pre-commit run --all-files
981
1005
  ```
982
1006
 
@@ -989,10 +1013,10 @@ and delegates execution to `entrypoint.sh`.
989
1013
  # Build the Docker image
990
1014
  docker build -t dapi .
991
1015
 
992
- # Run the test suite
1016
+ # Run the default test command (unit tests)
993
1017
  docker run --rm dapi
994
1018
 
995
- # Run pre-commit checks followed by the test suite
1019
+ # Run pre-commit checks followed by the unit tests
996
1020
  docker run --rm -e RUN_PRE_COMMIT=true dapi
997
1021
 
998
1022
  # Build and run with a specific Python version
@@ -1002,18 +1026,25 @@ docker run --rm dapi:py315
1002
1026
 
1003
1027
  ### Releasing
1004
1028
 
1005
- 1. Update the `version` in `pyproject.toml` and document the release in `CHANGELOG.md`.
1006
- 2. Commit and push the release commit to `main`.
1007
- 3. Create and push a matching version tag:
1029
+ 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`.
1033
+
1034
+ After the reviewed release commit is present on the default branch, create
1035
+ and push the matching version tag:
1008
1036
 
1009
- ```bash
1010
- git tag vX.Y.Z
1011
- git push origin vX.Y.Z
1012
- ```
1037
+ ```bash
1038
+ git tag -a vX.Y.Z -m "Release vX.Y.Z"
1039
+ git push origin vX.Y.Z
1040
+ ```
1013
1041
 
1014
- Pushing a `v*` tag triggers GitHub Actions to build the package, validate
1015
- the distribution with `twine check`, and publish it to PyPI using
1016
- the `PYPI_API_TOKEN` repository secret.
1042
+ Pushing a `v*` tag triggers GitHub Actions to run the compatibility matrix,
1043
+ build and validate the exact distribution with `twine check --strict`,
1044
+ smoke-test the wheel, and publish it to PyPI using Trusted Publishing
1045
+ (GitHub Actions OIDC). A successful tag push alone does not prove that
1046
+ publication completed; verify the workflow and the version-specific PyPI
1047
+ release page before announcing the release.
1017
1048
 
1018
1049
  ### Reporting issues
1019
1050
 
@@ -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
 
@@ -61,7 +61,8 @@ class LifecycleMiddleware:
61
61
  return self.get_response(request)
62
62
 
63
63
  sunset = meta.get("sunset")
64
- if sunset and _is_past(sunset):
64
+ sunset_date = _parse_sunset(sunset) if sunset else None
65
+ if sunset_date and _is_past(sunset_date):
65
66
  return HttpResponseGone(
66
67
  f"API version {version} has been retired as of {sunset}."
67
68
  )
@@ -69,30 +70,37 @@ class LifecycleMiddleware:
69
70
  response = self.get_response(request)
70
71
  if meta.get("status") == "deprecated":
71
72
  response["Deprecation"] = "true"
72
- if sunset:
73
- response["Sunset"] = _to_http_date(sunset)
73
+ if sunset_date:
74
+ response["Sunset"] = _to_http_date(sunset_date)
74
75
  return response
75
76
 
76
77
 
78
+ def _coerce_version(value: Any) -> int | None:
79
+ """Accept integer versions without truncating booleans or other numeric types."""
80
+ if isinstance(value, bool):
81
+ return None
82
+ if isinstance(value, int):
83
+ return value
84
+ if isinstance(value, str) and value.isdecimal():
85
+ return int(value)
86
+ return None
87
+
88
+
77
89
  def _extract_version(request: HttpRequest) -> int | None:
78
90
  # 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
91
+ version = _coerce_version(getattr(request, "version", None))
92
+ if version is not None:
93
+ return version
94
+
84
95
  # Fallback: parse from resolver_match kwargs.
85
96
  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
97
+ if match:
98
+ version = _coerce_version(match.kwargs.get("version"))
99
+ if version is not None:
100
+ return version
101
+
91
102
  # 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
103
+ return _extract_version_from_path(request)
96
104
 
97
105
 
98
106
  def _extract_version_from_path(request: HttpRequest) -> int | None:
@@ -137,18 +145,26 @@ def _extract_version_from_path(request: HttpRequest) -> int | None:
137
145
  return None
138
146
 
139
147
 
140
- def _is_past(date_str: str) -> bool:
148
+ def _parse_sunset(value: Any) -> datetime | None:
149
+ """Parse a configured sunset value and normalize it to UTC."""
150
+ if not isinstance(value, str):
151
+ logger.warning("Invalid sunset date %r; ignoring.", value)
152
+ return None
153
+
141
154
  try:
142
- date = datetime.fromisoformat(date_str).replace(tzinfo=timezone.utc)
155
+ parsed = datetime.fromisoformat(value)
143
156
  except ValueError:
144
- logger.warning("Invalid sunset date %r; ignoring.", date_str)
145
- return False
157
+ logger.warning("Invalid sunset date %r; ignoring.", value)
158
+ return None
159
+
160
+ if parsed.tzinfo is None:
161
+ return parsed.replace(tzinfo=timezone.utc)
162
+ return parsed.astimezone(timezone.utc)
163
+
164
+
165
+ def _is_past(date: datetime) -> bool:
146
166
  return date < datetime.now(timezone.utc)
147
167
 
148
168
 
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
169
+ def _to_http_date(date: datetime) -> str:
154
170
  return date.strftime("%a, %d %b %Y %H:%M:%S GMT")