django-api-versioning 0.3.5__tar.gz → 0.3.7__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/CHANGELOG.md +30 -0
- {django_api_versioning-0.3.5/django_api_versioning.egg-info → django_api_versioning-0.3.7}/PKG-INFO +137 -14
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/README.md +136 -11
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/decorators.py +8 -0
- django_api_versioning-0.3.7/django_api_versioning/management/commands/check_versions.py +62 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/registry.py +53 -1
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7/django_api_versioning.egg-info}/PKG-INFO +137 -14
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/pyproject.toml +1 -3
- django_api_versioning-0.3.7/tests/test_decorators.py +429 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_lifecycle.py +9 -3
- django_api_versioning-0.3.7/tests/test_management_commands.py +358 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_registry.py +60 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_reverse.py +3 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_testing_utils.py +1 -1
- django_api_versioning-0.3.5/django_api_versioning/management/commands/check_versions.py +0 -39
- django_api_versioning-0.3.5/tests/test_decorators.py +0 -160
- django_api_versioning-0.3.5/tests/test_management_commands.py +0 -42
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/LICENSE +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/MANIFEST.in +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/__init__.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/channels.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/exceptions.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/lifecycle.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/management/__init__.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/management/commands/__init__.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/management/commands/migrate_endpoints.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/reverse.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/settings.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/testing.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/urls.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/SOURCES.txt +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/dependency_links.txt +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/requires.txt +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/top_level.txt +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/pytest.ini +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/requirements-dev.txt +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/requirements.txt +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/setup.cfg +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/__init__.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/conftest.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/settings.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_channels.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_channels_extra.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_exceptions.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_segment_model.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_settings.py +0 -0
- {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_urls.py +0 -0
|
@@ -8,6 +8,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [0.3.7] - 2026-11-14
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- Run the full tox test matrix in parallel by default, with separate coverage data per environment.
|
|
16
|
+
|
|
17
|
+
### Verified
|
|
18
|
+
|
|
19
|
+
- ✅ All 175 unit tests and 245 integration tests passing in each of the 15 Python/Django environments
|
|
20
|
+
- ✅ Tox lint environment passing
|
|
21
|
+
|
|
22
|
+
## [0.3.6] - 2026-11-13
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- **Logical endpoint matrix grouping:** Fixed `check_versions` output grouping physical URL patterns by logical endpoint identity instead of individual versioned routes. Multiple versions of the same endpoint (e.g., `/api/v1/users/`, `/api/v2/users/`, `/api/v3/users/`) now appear under a single logical endpoint heading, eliminating false missing-version warnings for inherited routes.
|
|
27
|
+
- **Class-based view callback names:** Fixed `check_versions` display of callback names for Django class-based views, DRF APIViews, and DRF ViewSets. Previously displayed generic "view" for all class-based views; now resolves `view_class.__name__` or `cls.__name__` to show meaningful class names.
|
|
28
|
+
- **ViewSet registration error message:** Improved error handling for DRF ViewSet registration without action configuration. Now raises clear TypeError with actionable guidance (`ViewSet 'MyViewSet' cannot be registered directly. Pass a configured callable like: MyViewSet.as_view({'get': 'list', ...})`) instead of obscure raw DRF exception.
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- **Improved management command tests:** Replaced weak assertions with meaningful test coverage: empty registry produces "No endpoints registered" message, registered endpoints display correctly with versions and callback names, logical endpoint grouping works without false gaps, internal version gaps are detected correctly.
|
|
33
|
+
|
|
34
|
+
### Verified
|
|
35
|
+
|
|
36
|
+
- ✅ All 160 unit tests passing across Python 3.10–3.15
|
|
37
|
+
- ✅ All 236 integration tests passing across Python 3.10–3.15
|
|
38
|
+
- ✅ No DRF runtime dependency (remains dev-only)
|
|
39
|
+
- ✅ Backward compatibility with existing registry API maintained
|
|
40
|
+
|
|
11
41
|
## [0.3.5] - 2026-11-12
|
|
12
42
|
|
|
13
43
|
### Documentation
|
{django_api_versioning-0.3.5/django_api_versioning.egg-info → django_api_versioning-0.3.7}/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: django-api-versioning
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.7
|
|
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: MIT
|
|
@@ -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
|
|
@@ -52,7 +50,7 @@ Dynamic: license-file
|
|
|
52
50
|
[](https://badge.fury.io/py/django-api-versioning)
|
|
53
51
|
[](https://pypi.org/project/django-api-versioning/)
|
|
54
52
|
[](https://github.com/mojtaba-arvin/django-api-versioning/actions)
|
|
55
|
-
[](https://www.djangoproject.com/)
|
|
56
54
|
[](https://pypi.org/project/django-api-versioning/)
|
|
57
55
|
[](https://opensource.org/licenses/MIT)
|
|
58
56
|
|
|
@@ -263,9 +261,6 @@ In your project's root URL configuration:
|
|
|
263
261
|
|
|
264
262
|
from django.urls import include, path
|
|
265
263
|
|
|
266
|
-
from your_app import views # noqa: F401
|
|
267
|
-
|
|
268
|
-
|
|
269
264
|
from your_app import views # noqa: F401
|
|
270
265
|
|
|
271
266
|
from django_api_versioning.urls import urlpatterns as api_urlpatterns
|
|
@@ -631,6 +626,47 @@ Prints registered routes, their route versions, and the associated callback name
|
|
|
631
626
|
|
|
632
627
|
Use it to inspect the routing result after adding or changing endpoint declarations.
|
|
633
628
|
|
|
629
|
+
**Output interpretation:**
|
|
630
|
+
|
|
631
|
+
The command groups routes by their *logical endpoint* (the path without versioning), not by physical URL. This means:
|
|
632
|
+
|
|
633
|
+
```text
|
|
634
|
+
users/:
|
|
635
|
+
v1 → users_list_v1
|
|
636
|
+
v2 → users_list_v2
|
|
637
|
+
v3 → users_list_v2
|
|
638
|
+
v4 → users_list_v2
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
Even though physical URLs are `/api/v1/users/`, `/api/v2/users/`, etc., the command groups them under the logical endpoint `users`.
|
|
642
|
+
|
|
643
|
+
**Callback name resolution:**
|
|
644
|
+
|
|
645
|
+
The command resolves callback names intelligently:
|
|
646
|
+
|
|
647
|
+
- **Function-based views:** Shows the function name (e.g., `my_view`)
|
|
648
|
+
- **Django View classes:** Shows the class name (e.g., `MyView`)
|
|
649
|
+
- **DRF APIView:** Shows the class name (e.g., `MyAPIView`)
|
|
650
|
+
- **DRF ViewSet actions:** Shows the ViewSet class name (e.g., `MyViewSet`)
|
|
651
|
+
|
|
652
|
+
**Gap detection:**
|
|
653
|
+
|
|
654
|
+
The command warns about missing versions within an endpoint's span:
|
|
655
|
+
|
|
656
|
+
```text
|
|
657
|
+
users:
|
|
658
|
+
v1 → users_list_v1
|
|
659
|
+
v3 → users_list_v3
|
|
660
|
+
[users] v2 is not defined.
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
It does NOT warn about versions before an endpoint's introduction or after its final declaration:
|
|
664
|
+
|
|
665
|
+
```text
|
|
666
|
+
# No warning for v1 (starts at v2)
|
|
667
|
+
# No warning for v4 (ends at v3)
|
|
668
|
+
```
|
|
669
|
+
|
|
634
670
|
### `assert_version_matrix` — guard routing changes in CI
|
|
635
671
|
|
|
636
672
|
The package provides a snapshot utility for detecting unintended changes to the registered route matrix.
|
|
@@ -825,7 +861,31 @@ A generic view must implement the HTTP handlers required by its registered route
|
|
|
825
861
|
|
|
826
862
|
A DRF `ViewSet` class cannot be passed directly to `@endpoint` as a normal class-based view. Its `as_view()` method requires an action mapping, while the package invokes `as_view()` without one.
|
|
827
863
|
|
|
828
|
-
|
|
864
|
+
To register a ViewSet action, pass a pre-configured callable:
|
|
865
|
+
|
|
866
|
+
```python
|
|
867
|
+
from rest_framework.viewsets import ViewSet
|
|
868
|
+
from django_api_versioning import endpoint
|
|
869
|
+
|
|
870
|
+
|
|
871
|
+
class MyViewSet(ViewSet):
|
|
872
|
+
def list(self, request):
|
|
873
|
+
return JsonResponse({})
|
|
874
|
+
|
|
875
|
+
def create(self, request):
|
|
876
|
+
return JsonResponse({})
|
|
877
|
+
|
|
878
|
+
|
|
879
|
+
# ✓ Correct: pass a configured callable
|
|
880
|
+
@endpoint("items/", version=1)
|
|
881
|
+
def list_items(request):
|
|
882
|
+
return MyViewSet.as_view({"get": "list"})(request)
|
|
883
|
+
|
|
884
|
+
# ✗ Incorrect: class without action mapping
|
|
885
|
+
# @endpoint("items/", version=1, MyViewSet) # TypeError!
|
|
886
|
+
```
|
|
887
|
+
|
|
888
|
+
For standard ViewSet resource routing (list, create, retrieve, update, destroy), use DRF routers separately.
|
|
829
889
|
|
|
830
890
|
The package does not automatically generate router-style ViewSet routes.
|
|
831
891
|
|
|
@@ -839,13 +899,53 @@ It does not:
|
|
|
839
899
|
- Select serializers based on a request version.
|
|
840
900
|
- Replace DRF authentication or permission classes.
|
|
841
901
|
- Replace DRF routers for ViewSet resource routing.
|
|
842
|
-
- Automatically set `request.version
|
|
902
|
+
- Automatically set `request.version` (DRF's concern).
|
|
843
903
|
- Use `API_VERSIONING_CHANNELS` to select routes.
|
|
844
904
|
- Use `API_EFFECTIVE_VERSION_RESOLVER` for tenant-specific route selection.
|
|
845
905
|
- Validate response payload compatibility through route-matrix checks.
|
|
846
906
|
|
|
847
907
|
Your application remains responsible for API contract design, serializer selection, authentication, permissions, business logic, and request-level compatibility tests.
|
|
848
908
|
|
|
909
|
+
### Package vs. DRF: Division of responsibilities
|
|
910
|
+
|
|
911
|
+
**Package responsibility: Route selection**
|
|
912
|
+
|
|
913
|
+
The package registers literal URL paths (`/api/v1/endpoint`, `/api/v2/endpoint`) and selects the correct handler based on the URL path.
|
|
914
|
+
|
|
915
|
+
**DRF responsibility: request.version**
|
|
916
|
+
|
|
917
|
+
DRF's versioning classes (like `URLPathVersioning`) populate `request.version` if configured. However, DRF's `URLPathVersioning` uses a URL resolver keyword argument named `version`, which the package does not populate. This means:
|
|
918
|
+
|
|
919
|
+
- The package successfully routes requests to version-specific handlers.
|
|
920
|
+
- `request.version` may be `None` unless you configure a custom versioning class.
|
|
921
|
+
|
|
922
|
+
If you need `request.version` populated, consider implementing a custom DRF versioning class that extracts the version from the URL path or adds a custom resolver keyword argument when registering routes.
|
|
923
|
+
|
|
924
|
+
### Configuration timing
|
|
925
|
+
|
|
926
|
+
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.
|
|
927
|
+
|
|
928
|
+
`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.
|
|
929
|
+
|
|
930
|
+
Configure route-registry settings before importing modules containing `@endpoint` declarations:
|
|
931
|
+
|
|
932
|
+
```python
|
|
933
|
+
# ✓ Correct: configure before importing views
|
|
934
|
+
os.environ["DJANGO_SETTINGS_MODULE"] = "myapp.settings"
|
|
935
|
+
from django.conf import settings
|
|
936
|
+
settings.API_MAX_VERSION = 5
|
|
937
|
+
from myapp import views # Package uses the configured API_MAX_VERSION
|
|
938
|
+
|
|
939
|
+
# ✗ Incorrect: configure after importing
|
|
940
|
+
from django_api_versioning import api_settings
|
|
941
|
+
from django.test import override_settings
|
|
942
|
+
with override_settings(API_MAX_VERSION=5):
|
|
943
|
+
# This does NOT affect api_settings (already loaded)
|
|
944
|
+
...
|
|
945
|
+
```
|
|
946
|
+
|
|
947
|
+
Set all configuration in Django settings before importing modules containing `@endpoint` decorators.
|
|
948
|
+
|
|
849
949
|
## Migration from 0.2.0
|
|
850
950
|
|
|
851
951
|
Version 0.3.0 replaced the previous forward/backward inheritance flags model with segment-based registration.
|
|
@@ -923,8 +1023,31 @@ pre-commit install
|
|
|
923
1023
|
|
|
924
1024
|
### Running tests
|
|
925
1025
|
|
|
1026
|
+
Run the unit tests:
|
|
1027
|
+
|
|
1028
|
+
```bash
|
|
1029
|
+
python -m pytest tests
|
|
1030
|
+
```
|
|
1031
|
+
|
|
1032
|
+
Run the integration tests:
|
|
1033
|
+
|
|
1034
|
+
```bash
|
|
1035
|
+
python -m pytest integration_test_project
|
|
1036
|
+
```
|
|
1037
|
+
|
|
1038
|
+
Run the complete configured Python/Django test matrix:
|
|
1039
|
+
|
|
1040
|
+
```bash
|
|
1041
|
+
python -m pip install tox
|
|
1042
|
+
tox run-parallel -p auto
|
|
1043
|
+
```
|
|
1044
|
+
|
|
1045
|
+
The parallel run uses the available CPU count; use `tox run-parallel -p 4`
|
|
1046
|
+
to limit concurrency on memory-constrained machines.
|
|
1047
|
+
|
|
1048
|
+
Run pre-commit checks:
|
|
1049
|
+
|
|
926
1050
|
```bash
|
|
927
|
-
pytest
|
|
928
1051
|
pre-commit run --all-files
|
|
929
1052
|
```
|
|
930
1053
|
|
|
@@ -937,10 +1060,10 @@ and delegates execution to `entrypoint.sh`.
|
|
|
937
1060
|
# Build the Docker image
|
|
938
1061
|
docker build -t dapi .
|
|
939
1062
|
|
|
940
|
-
# Run the test
|
|
1063
|
+
# Run the default test command (unit tests)
|
|
941
1064
|
docker run --rm dapi
|
|
942
1065
|
|
|
943
|
-
# Run pre-commit checks followed by the
|
|
1066
|
+
# Run pre-commit checks followed by the unit tests
|
|
944
1067
|
docker run --rm -e RUN_PRE_COMMIT=true dapi
|
|
945
1068
|
|
|
946
1069
|
# Build and run with a specific Python version
|
|
@@ -960,8 +1083,8 @@ docker run --rm dapi:py315
|
|
|
960
1083
|
```
|
|
961
1084
|
|
|
962
1085
|
Pushing a `v*` tag triggers GitHub Actions to build the package, validate
|
|
963
|
-
the distribution with `twine check`, and publish it to PyPI
|
|
964
|
-
|
|
1086
|
+
the distribution with `twine check --strict`, and publish it to PyPI
|
|
1087
|
+
using PyPI Trusted Publishing (GitHub Actions OIDC).
|
|
965
1088
|
|
|
966
1089
|
### Reporting issues
|
|
967
1090
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
[](https://badge.fury.io/py/django-api-versioning)
|
|
4
4
|
[](https://pypi.org/project/django-api-versioning/)
|
|
5
5
|
[](https://github.com/mojtaba-arvin/django-api-versioning/actions)
|
|
6
|
-
[](https://www.djangoproject.com/)
|
|
7
7
|
[](https://pypi.org/project/django-api-versioning/)
|
|
8
8
|
[](https://opensource.org/licenses/MIT)
|
|
9
9
|
|
|
@@ -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
|
|
@@ -582,6 +579,47 @@ Prints registered routes, their route versions, and the associated callback name
|
|
|
582
579
|
|
|
583
580
|
Use it to inspect the routing result after adding or changing endpoint declarations.
|
|
584
581
|
|
|
582
|
+
**Output interpretation:**
|
|
583
|
+
|
|
584
|
+
The command groups routes by their *logical endpoint* (the path without versioning), not by physical URL. This means:
|
|
585
|
+
|
|
586
|
+
```text
|
|
587
|
+
users/:
|
|
588
|
+
v1 → users_list_v1
|
|
589
|
+
v2 → users_list_v2
|
|
590
|
+
v3 → users_list_v2
|
|
591
|
+
v4 → users_list_v2
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
Even though physical URLs are `/api/v1/users/`, `/api/v2/users/`, etc., the command groups them under the logical endpoint `users`.
|
|
595
|
+
|
|
596
|
+
**Callback name resolution:**
|
|
597
|
+
|
|
598
|
+
The command resolves callback names intelligently:
|
|
599
|
+
|
|
600
|
+
- **Function-based views:** Shows the function name (e.g., `my_view`)
|
|
601
|
+
- **Django View classes:** Shows the class name (e.g., `MyView`)
|
|
602
|
+
- **DRF APIView:** Shows the class name (e.g., `MyAPIView`)
|
|
603
|
+
- **DRF ViewSet actions:** Shows the ViewSet class name (e.g., `MyViewSet`)
|
|
604
|
+
|
|
605
|
+
**Gap detection:**
|
|
606
|
+
|
|
607
|
+
The command warns about missing versions within an endpoint's span:
|
|
608
|
+
|
|
609
|
+
```text
|
|
610
|
+
users:
|
|
611
|
+
v1 → users_list_v1
|
|
612
|
+
v3 → users_list_v3
|
|
613
|
+
[users] v2 is not defined.
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
It does NOT warn about versions before an endpoint's introduction or after its final declaration:
|
|
617
|
+
|
|
618
|
+
```text
|
|
619
|
+
# No warning for v1 (starts at v2)
|
|
620
|
+
# No warning for v4 (ends at v3)
|
|
621
|
+
```
|
|
622
|
+
|
|
585
623
|
### `assert_version_matrix` — guard routing changes in CI
|
|
586
624
|
|
|
587
625
|
The package provides a snapshot utility for detecting unintended changes to the registered route matrix.
|
|
@@ -776,7 +814,31 @@ A generic view must implement the HTTP handlers required by its registered route
|
|
|
776
814
|
|
|
777
815
|
A DRF `ViewSet` class cannot be passed directly to `@endpoint` as a normal class-based view. Its `as_view()` method requires an action mapping, while the package invokes `as_view()` without one.
|
|
778
816
|
|
|
779
|
-
|
|
817
|
+
To register a ViewSet action, pass a pre-configured callable:
|
|
818
|
+
|
|
819
|
+
```python
|
|
820
|
+
from rest_framework.viewsets import ViewSet
|
|
821
|
+
from django_api_versioning import endpoint
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
class MyViewSet(ViewSet):
|
|
825
|
+
def list(self, request):
|
|
826
|
+
return JsonResponse({})
|
|
827
|
+
|
|
828
|
+
def create(self, request):
|
|
829
|
+
return JsonResponse({})
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
# ✓ Correct: pass a configured callable
|
|
833
|
+
@endpoint("items/", version=1)
|
|
834
|
+
def list_items(request):
|
|
835
|
+
return MyViewSet.as_view({"get": "list"})(request)
|
|
836
|
+
|
|
837
|
+
# ✗ Incorrect: class without action mapping
|
|
838
|
+
# @endpoint("items/", version=1, MyViewSet) # TypeError!
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
For standard ViewSet resource routing (list, create, retrieve, update, destroy), use DRF routers separately.
|
|
780
842
|
|
|
781
843
|
The package does not automatically generate router-style ViewSet routes.
|
|
782
844
|
|
|
@@ -790,13 +852,53 @@ It does not:
|
|
|
790
852
|
- Select serializers based on a request version.
|
|
791
853
|
- Replace DRF authentication or permission classes.
|
|
792
854
|
- Replace DRF routers for ViewSet resource routing.
|
|
793
|
-
- Automatically set `request.version
|
|
855
|
+
- Automatically set `request.version` (DRF's concern).
|
|
794
856
|
- Use `API_VERSIONING_CHANNELS` to select routes.
|
|
795
857
|
- Use `API_EFFECTIVE_VERSION_RESOLVER` for tenant-specific route selection.
|
|
796
858
|
- Validate response payload compatibility through route-matrix checks.
|
|
797
859
|
|
|
798
860
|
Your application remains responsible for API contract design, serializer selection, authentication, permissions, business logic, and request-level compatibility tests.
|
|
799
861
|
|
|
862
|
+
### Package vs. DRF: Division of responsibilities
|
|
863
|
+
|
|
864
|
+
**Package responsibility: Route selection**
|
|
865
|
+
|
|
866
|
+
The package registers literal URL paths (`/api/v1/endpoint`, `/api/v2/endpoint`) and selects the correct handler based on the URL path.
|
|
867
|
+
|
|
868
|
+
**DRF responsibility: request.version**
|
|
869
|
+
|
|
870
|
+
DRF's versioning classes (like `URLPathVersioning`) populate `request.version` if configured. However, DRF's `URLPathVersioning` uses a URL resolver keyword argument named `version`, which the package does not populate. This means:
|
|
871
|
+
|
|
872
|
+
- The package successfully routes requests to version-specific handlers.
|
|
873
|
+
- `request.version` may be `None` unless you configure a custom versioning class.
|
|
874
|
+
|
|
875
|
+
If you need `request.version` populated, consider implementing a custom DRF versioning class that extracts the version from the URL path or adds a custom resolver keyword argument when registering routes.
|
|
876
|
+
|
|
877
|
+
### Configuration timing
|
|
878
|
+
|
|
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:
|
|
884
|
+
|
|
885
|
+
```python
|
|
886
|
+
# ✓ Correct: configure before importing views
|
|
887
|
+
os.environ["DJANGO_SETTINGS_MODULE"] = "myapp.settings"
|
|
888
|
+
from django.conf import settings
|
|
889
|
+
settings.API_MAX_VERSION = 5
|
|
890
|
+
from myapp import views # Package uses the configured API_MAX_VERSION
|
|
891
|
+
|
|
892
|
+
# ✗ Incorrect: configure after importing
|
|
893
|
+
from django_api_versioning import api_settings
|
|
894
|
+
from django.test import override_settings
|
|
895
|
+
with override_settings(API_MAX_VERSION=5):
|
|
896
|
+
# This does NOT affect api_settings (already loaded)
|
|
897
|
+
...
|
|
898
|
+
```
|
|
899
|
+
|
|
900
|
+
Set all configuration in Django settings before importing modules containing `@endpoint` decorators.
|
|
901
|
+
|
|
800
902
|
## Migration from 0.2.0
|
|
801
903
|
|
|
802
904
|
Version 0.3.0 replaced the previous forward/backward inheritance flags model with segment-based registration.
|
|
@@ -874,8 +976,31 @@ pre-commit install
|
|
|
874
976
|
|
|
875
977
|
### Running tests
|
|
876
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
|
+
|
|
877
1003
|
```bash
|
|
878
|
-
pytest
|
|
879
1004
|
pre-commit run --all-files
|
|
880
1005
|
```
|
|
881
1006
|
|
|
@@ -888,10 +1013,10 @@ and delegates execution to `entrypoint.sh`.
|
|
|
888
1013
|
# Build the Docker image
|
|
889
1014
|
docker build -t dapi .
|
|
890
1015
|
|
|
891
|
-
# Run the test
|
|
1016
|
+
# Run the default test command (unit tests)
|
|
892
1017
|
docker run --rm dapi
|
|
893
1018
|
|
|
894
|
-
# Run pre-commit checks followed by the
|
|
1019
|
+
# Run pre-commit checks followed by the unit tests
|
|
895
1020
|
docker run --rm -e RUN_PRE_COMMIT=true dapi
|
|
896
1021
|
|
|
897
1022
|
# Build and run with a specific Python version
|
|
@@ -911,8 +1036,8 @@ docker run --rm dapi:py315
|
|
|
911
1036
|
```
|
|
912
1037
|
|
|
913
1038
|
Pushing a `v*` tag triggers GitHub Actions to build the package, validate
|
|
914
|
-
the distribution with `twine check`, and publish it to PyPI
|
|
915
|
-
|
|
1039
|
+
the distribution with `twine check --strict`, and publish it to PyPI
|
|
1040
|
+
using PyPI Trusted Publishing (GitHub Actions OIDC).
|
|
916
1041
|
|
|
917
1042
|
### Reporting issues
|
|
918
1043
|
|
{django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/decorators.py
RENAMED
|
@@ -15,6 +15,10 @@ ViewT = TypeVar("ViewT", bound=Callable)
|
|
|
15
15
|
|
|
16
16
|
def ver_range(start: int, end: int) -> list[int]:
|
|
17
17
|
"""Inclusive range of API versions, e.g. ver_range(1, 3) -> [1, 2, 3]."""
|
|
18
|
+
if isinstance(start, bool) or not isinstance(start, int):
|
|
19
|
+
raise VersionTypeError("ver_range start must be an integer.")
|
|
20
|
+
if isinstance(end, bool) or not isinstance(end, int):
|
|
21
|
+
raise VersionTypeError("ver_range end must be an integer.")
|
|
18
22
|
if start > end:
|
|
19
23
|
raise VersionRangeError(f"ver_range start ({start}) must be <= end ({end}).")
|
|
20
24
|
return list(range(start, end + 1))
|
|
@@ -71,6 +75,9 @@ def endpoint(
|
|
|
71
75
|
|
|
72
76
|
app_name_part: str = f"{app_name}/" if app_name else ""
|
|
73
77
|
|
|
78
|
+
# Calculate logical endpoint ID from unversioned path
|
|
79
|
+
logical_endpoint = f"{app_name_part}{postfix}"
|
|
80
|
+
|
|
74
81
|
def _register_route(ver: int | None, source_version: int | None) -> None:
|
|
75
82
|
"""Helper function to register a route in the registry."""
|
|
76
83
|
if ver is None:
|
|
@@ -84,6 +91,7 @@ def endpoint(
|
|
|
84
91
|
view_name,
|
|
85
92
|
source_version=source_version,
|
|
86
93
|
route_version=ver,
|
|
94
|
+
logical_endpoint=logical_endpoint,
|
|
87
95
|
)
|
|
88
96
|
|
|
89
97
|
if version is not None:
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
from collections import defaultdict
|
|
2
|
+
|
|
3
|
+
from django.core.management.base import BaseCommand
|
|
4
|
+
|
|
5
|
+
from ...registry import registry
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Command(BaseCommand):
|
|
9
|
+
help = "Print the API version matrix and warn about gaps."
|
|
10
|
+
|
|
11
|
+
def handle(self, *args, **options):
|
|
12
|
+
# Use logical version matrix to group by logical endpoint, not physical URL
|
|
13
|
+
matrix = registry.get_logical_version_matrix()
|
|
14
|
+
grouped = defaultdict(dict)
|
|
15
|
+
for endpoint, versions in matrix.items():
|
|
16
|
+
grouped[endpoint] = versions
|
|
17
|
+
|
|
18
|
+
if not grouped:
|
|
19
|
+
self.stdout.write("No endpoints registered.")
|
|
20
|
+
return
|
|
21
|
+
|
|
22
|
+
for endpoint in sorted(grouped):
|
|
23
|
+
self.stdout.write(f"\n{endpoint}:")
|
|
24
|
+
versions = grouped[endpoint]
|
|
25
|
+
for version in sorted(versions, key=lambda v: (v is not None, v)):
|
|
26
|
+
label = "unversioned" if version is None else f"v{version}"
|
|
27
|
+
callback_name = self._get_callback_name(versions[version])
|
|
28
|
+
self.stdout.write(f" {label:12} → {callback_name}")
|
|
29
|
+
|
|
30
|
+
self._warn_gaps(grouped)
|
|
31
|
+
|
|
32
|
+
@staticmethod
|
|
33
|
+
def _get_callback_name(callback):
|
|
34
|
+
"""Resolve callback name, handling both functions and class-based views."""
|
|
35
|
+
# Try to get from class-based view metadata first
|
|
36
|
+
if hasattr(callback, "view_class"):
|
|
37
|
+
return callback.view_class.__name__
|
|
38
|
+
# Try to get from ViewSet action callback
|
|
39
|
+
if hasattr(callback, "cls"):
|
|
40
|
+
return callback.cls.__name__
|
|
41
|
+
# Fallback to __name__ attribute
|
|
42
|
+
if hasattr(callback, "__name__"):
|
|
43
|
+
return callback.__name__
|
|
44
|
+
# Final fallback for callable instances
|
|
45
|
+
return callback.__class__.__name__
|
|
46
|
+
|
|
47
|
+
def _warn_gaps(self, grouped):
|
|
48
|
+
for endpoint, versions in grouped.items():
|
|
49
|
+
numeric = sorted(v for v in versions if v is not None)
|
|
50
|
+
if not numeric:
|
|
51
|
+
# Unversioned endpoints don't have gaps
|
|
52
|
+
continue
|
|
53
|
+
|
|
54
|
+
# Only check for gaps within the endpoint's actual span
|
|
55
|
+
min_registered = min(numeric)
|
|
56
|
+
max_registered = max(numeric)
|
|
57
|
+
|
|
58
|
+
for v in range(min_registered, max_registered + 1):
|
|
59
|
+
if v not in versions:
|
|
60
|
+
self.stdout.write(
|
|
61
|
+
self.style.WARNING(f" [{endpoint}] v{v} is not defined.")
|
|
62
|
+
)
|
{django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/registry.py
RENAMED
|
@@ -12,6 +12,7 @@ class UrlRegistry:
|
|
|
12
12
|
|
|
13
13
|
_SOURCE_VERSION_ATTR = "_django_api_versioning_source_version"
|
|
14
14
|
_ROUTE_VERSION_ATTR = "_django_api_versioning_route_version"
|
|
15
|
+
_LOGICAL_ENDPOINT_ATTR = "_django_api_versioning_logical_endpoint"
|
|
15
16
|
|
|
16
17
|
def __init__(self) -> None:
|
|
17
18
|
self.urlpatterns: list[URLPattern] = []
|
|
@@ -23,6 +24,7 @@ class UrlRegistry:
|
|
|
23
24
|
name: str | None = None,
|
|
24
25
|
source_version: int | None = None,
|
|
25
26
|
route_version: int | None = None,
|
|
27
|
+
logical_endpoint: str | None = None,
|
|
26
28
|
) -> None:
|
|
27
29
|
"""Register a route, preferring definitions from newer source versions."""
|
|
28
30
|
route_index = self._find_route_index(route)
|
|
@@ -36,6 +38,8 @@ class UrlRegistry:
|
|
|
36
38
|
pattern = self._create_pattern(route, view, name)
|
|
37
39
|
setattr(pattern, self._SOURCE_VERSION_ATTR, source_version)
|
|
38
40
|
setattr(pattern, self._ROUTE_VERSION_ATTR, route_version)
|
|
41
|
+
if logical_endpoint is not None:
|
|
42
|
+
setattr(pattern, self._LOGICAL_ENDPOINT_ATTR, logical_endpoint)
|
|
39
43
|
|
|
40
44
|
if route_index is None:
|
|
41
45
|
self.urlpatterns.append(pattern)
|
|
@@ -58,6 +62,24 @@ class UrlRegistry:
|
|
|
58
62
|
matrix.setdefault(route, {})[route_version] = pattern.callback
|
|
59
63
|
return matrix
|
|
60
64
|
|
|
65
|
+
def get_logical_version_matrix(self) -> dict[str, dict[int | None, Callable]]:
|
|
66
|
+
"""
|
|
67
|
+
Return ``{logical_endpoint: {route_version: callback}}``.
|
|
68
|
+
|
|
69
|
+
Groups physical URLs by their logical endpoint identity. This is used
|
|
70
|
+
by check_versions to correctly identify gaps within each logical
|
|
71
|
+
endpoint's version span, avoiding false warnings.
|
|
72
|
+
"""
|
|
73
|
+
matrix: dict[str, dict[int | None, Callable]] = {}
|
|
74
|
+
for pattern in self.urlpatterns:
|
|
75
|
+
# Use logical endpoint if available, else fall back to route pattern
|
|
76
|
+
logical_id = getattr(
|
|
77
|
+
pattern, self._LOGICAL_ENDPOINT_ATTR, str(pattern.pattern)
|
|
78
|
+
)
|
|
79
|
+
route_version = getattr(pattern, self._ROUTE_VERSION_ATTR, None)
|
|
80
|
+
matrix.setdefault(logical_id, {})[route_version] = pattern.callback
|
|
81
|
+
return matrix
|
|
82
|
+
|
|
61
83
|
def _find_route_index(self, route: str) -> int | None:
|
|
62
84
|
"""Return the index of a registered route, or None if absent."""
|
|
63
85
|
for index, pattern in enumerate(self.urlpatterns):
|
|
@@ -109,7 +131,37 @@ class UrlRegistry:
|
|
|
109
131
|
)
|
|
110
132
|
|
|
111
133
|
if isinstance(view, type) and callable(getattr(view, "as_view", None)):
|
|
112
|
-
|
|
134
|
+
# Check if this is a DRF ViewSet (has actions in signature)
|
|
135
|
+
# ViewSets require an action dict to be passed to as_view()
|
|
136
|
+
try:
|
|
137
|
+
import inspect
|
|
138
|
+
|
|
139
|
+
sig = inspect.signature(view.as_view)
|
|
140
|
+
# If as_view has an 'actions' parameter, it's likely a ViewSet
|
|
141
|
+
if "actions" in sig.parameters:
|
|
142
|
+
actions_param = sig.parameters["actions"]
|
|
143
|
+
# If 'actions' has no default, it's required (ViewSet behavior)
|
|
144
|
+
if actions_param.default == inspect.Parameter.empty:
|
|
145
|
+
raise TypeError(
|
|
146
|
+
f"ViewSet '{view.__name__}' cannot be registered directly. "
|
|
147
|
+
f"Pass a configured callable like: "
|
|
148
|
+
f"{view.__name__}.as_view({{'get': 'list', 'post': 'create'}})"
|
|
149
|
+
)
|
|
150
|
+
except Exception:
|
|
151
|
+
# If inspection fails, try calling as_view() anyway
|
|
152
|
+
# to get the original error message if it is indeed a problem
|
|
153
|
+
pass
|
|
154
|
+
|
|
155
|
+
try:
|
|
156
|
+
view = view.as_view()
|
|
157
|
+
except TypeError as e:
|
|
158
|
+
# Re-raise with better context if it's an actions-related error
|
|
159
|
+
if "actions" in str(e):
|
|
160
|
+
raise TypeError(
|
|
161
|
+
"ViewSet requires action configuration. "
|
|
162
|
+
"Use view.as_view({'get': 'list', ...}) with appropriate HTTP methods."
|
|
163
|
+
) from e
|
|
164
|
+
raise
|
|
113
165
|
return path(route, view, name=name)
|
|
114
166
|
|
|
115
167
|
def _sort_urlpatterns(self) -> None:
|