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.
Files changed (47) hide show
  1. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/CHANGELOG.md +30 -0
  2. {django_api_versioning-0.3.5/django_api_versioning.egg-info → django_api_versioning-0.3.7}/PKG-INFO +137 -14
  3. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/README.md +136 -11
  4. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/decorators.py +8 -0
  5. django_api_versioning-0.3.7/django_api_versioning/management/commands/check_versions.py +62 -0
  6. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/registry.py +53 -1
  7. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7/django_api_versioning.egg-info}/PKG-INFO +137 -14
  8. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/pyproject.toml +1 -3
  9. django_api_versioning-0.3.7/tests/test_decorators.py +429 -0
  10. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_lifecycle.py +9 -3
  11. django_api_versioning-0.3.7/tests/test_management_commands.py +358 -0
  12. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_registry.py +60 -0
  13. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_reverse.py +3 -0
  14. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_testing_utils.py +1 -1
  15. django_api_versioning-0.3.5/django_api_versioning/management/commands/check_versions.py +0 -39
  16. django_api_versioning-0.3.5/tests/test_decorators.py +0 -160
  17. django_api_versioning-0.3.5/tests/test_management_commands.py +0 -42
  18. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/LICENSE +0 -0
  19. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/MANIFEST.in +0 -0
  20. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/__init__.py +0 -0
  21. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/channels.py +0 -0
  22. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/exceptions.py +0 -0
  23. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/lifecycle.py +0 -0
  24. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/management/__init__.py +0 -0
  25. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/management/commands/__init__.py +0 -0
  26. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/management/commands/migrate_endpoints.py +0 -0
  27. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/reverse.py +0 -0
  28. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/settings.py +0 -0
  29. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/testing.py +0 -0
  30. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning/urls.py +0 -0
  31. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/SOURCES.txt +0 -0
  32. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/dependency_links.txt +0 -0
  33. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/requires.txt +0 -0
  34. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/django_api_versioning.egg-info/top_level.txt +0 -0
  35. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/pytest.ini +0 -0
  36. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/requirements-dev.txt +0 -0
  37. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/requirements.txt +0 -0
  38. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/setup.cfg +0 -0
  39. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/__init__.py +0 -0
  40. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/conftest.py +0 -0
  41. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/settings.py +0 -0
  42. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_channels.py +0 -0
  43. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_channels_extra.py +0 -0
  44. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_exceptions.py +0 -0
  45. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_segment_model.py +0 -0
  46. {django_api_versioning-0.3.5 → django_api_versioning-0.3.7}/tests/test_settings.py +0 -0
  47. {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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: django-api-versioning
3
- Version: 0.3.5
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
  [![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
53
51
  [![PyPI Downloads](https://img.shields.io/pypi/dm/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
54
52
  [![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/)
53
+ [![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.2%2B%20%7C%206.x-blue)](https://www.djangoproject.com/)
56
54
  [![Python versions](https://img.shields.io/pypi/pyversions/django-api-versioning.svg)](https://pypi.org/project/django-api-versioning/)
57
55
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
- Use DRF routers for standard ViewSet resource routing.
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 suite
1063
+ # Run the default test command (unit tests)
941
1064
  docker run --rm dapi
942
1065
 
943
- # Run pre-commit checks followed by the test suite
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 using
964
- the `PYPI_API_TOKEN` repository secret.
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
  [![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
 
@@ -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
- Use DRF routers for standard ViewSet resource routing.
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 suite
1016
+ # Run the default test command (unit tests)
892
1017
  docker run --rm dapi
893
1018
 
894
- # Run pre-commit checks followed by the test suite
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 using
915
- the `PYPI_API_TOKEN` repository secret.
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
 
@@ -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
+ )
@@ -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
- view = view.as_view()
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: