django-api-versioning 0.1.0__py3-none-any.whl

django_api_versioning/decorators.py

@@ -0,0 +1,88 @@
+from functools import wraps
+from typing import Callable, Optional, List
+from .settings import api_settings as settings
+from .registry import registry
+from .exceptions import InvalidVersionError, VersionRangeError, VersionTypeError
+
+
+def endpoint(
+    postfix: str,
+    version: Optional[int] = None,
+    backward: bool = True,
+    app_name: Optional[str] = None,
+    view_name: Optional[str] = None,
+) -> Callable:
+    """
+    Decorator to register API views with versioning support.
+
+    - Uses `API_MIN_VERSION` and `API_MAX_VERSION` from Django settings.
+    - Supports backward compatibility by registering multiple versions if needed.
+    - Ensures that no version lower than `API_MIN_VERSION` is registered.
+    
+    Args:
+        postfix (str): The endpoint suffix (e.g., "users" → "api/v1/users").
+        version (Optional[int]): The version of the API. Defaults to None (unversioned).
+        backward (bool): If True, registers routes for all versions from `API_MIN_VERSION` up to the current version, which is less than or equal to `API_MAX_VERSION`. Defaults to True.
+        app_name (Optional[str]): The app name to be prefixed to the route.
+        view_name (Optional[str]): The custom view name for Django.
+
+    Returns:
+        Callable: The decorated view function.
+
+    Raises:
+        VersionTypeError: If the provided `version` is not an integer.
+        VersionRangeError: If `API_MIN_VERSION` or `API_MAX_VERSION` are not properly set.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def view(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Read API versioning settings
+        min_version: int = getattr(settings, "API_MIN_VERSION", 1)
+        max_version: int = getattr(settings, "API_MAX_VERSION", 1)
+
+        if not isinstance(min_version, int) or not isinstance(max_version, int):
+            raise VersionRangeError("API_MIN_VERSION and API_MAX_VERSION must be integers.")
+        
+        if min_version > max_version:
+            raise VersionRangeError("API_MIN_VERSION cannot be greater than API_MAX_VERSION.")
+        
+        if version is not None and not isinstance(version, int):
+            raise VersionTypeError("Version must be an integer or None.")
+        
+        if version is not None and version > max_version:
+            raise InvalidVersionError(f"Version {version} is above the maximum allowed version {max_version}.")
+
+        app_name_part: str = f"{app_name}/" if app_name else ""
+
+        def _register_route(ver: Optional[int]) -> None:
+            """Helper function to register a route in the registry."""
+            if ver is None:
+                base_path = ""  # No version prefix
+            else:
+                base_path = settings.API_BASE_PATH.format(version=ver)
+            route = f"{base_path}{app_name_part}{postfix}"
+            registry.register(route, view, view_name)
+
+        def _get_valid_versions() -> List[Optional[int]]:
+            """Returns a list of valid versions to register."""
+            if version is None:
+                # If no version is given, register only the unversioned route
+                return [None]  # Just register the unversioned route
+            if version < min_version:
+                return []  # Ignore versions below min_version
+            if backward:
+                return list(range(min_version, version + 1))  # Register all versions up to the given version
+            return [version]  # Only register the specified version when backward is False
+
+        # Register valid versions
+        valid_versions = _get_valid_versions()
+
+        for ver in valid_versions:
+            _register_route(ver)
+
+        return view
+
+    return decorator

django_api_versioning/exceptions.py

@@ -0,0 +1,18 @@
+class VersioningError(Exception):
+    """Raised when there is a general error in API versioning."""
+    pass
+
+
+class InvalidVersionError(VersioningError):
+    """Raised when an invalid API version is used."""
+    pass
+
+
+class VersionRangeError(VersioningError):
+    """Raised when the version range is not valid (e.g., min_version > max_version)."""
+    pass
+
+
+class VersionTypeError(VersioningError):
+    """Raised when the version type is invalid (e.g., not an integer)."""
+    pass

django_api_versioning/registry.py

@@ -0,0 +1,33 @@
+from typing import Callable, List, Optional
+from django.urls import path
+from django.http import HttpRequest, HttpResponse
+
+
+class UrlRegistry:
+    """Registry for managing API versioning URLs."""
+
+    def __init__(self):
+        self.urlpatterns: List[path] = []
+    
+    def register(self, route: str, view: Callable[[HttpRequest], HttpResponse], name: Optional[str] = None) -> None:
+        """Register a new API endpoint."""
+        if self._is_duplicate(route):
+            self._remove_duplicate(route)
+        
+        if not callable(view) and hasattr(view, "as_view"):
+            view = view.as_view()
+
+        path_dict = {"name": name} if name else {}
+        self.urlpatterns.append(path(route, view, **path_dict))
+    
+    def _is_duplicate(self, full_path):
+        """Check if the route is already registered."""
+        return any(str(pattern.pattern) == full_path for pattern in self.urlpatterns)
+    
+    def _remove_duplicate(self, full_path):
+        """Remove any existing route with the same path."""
+        self.urlpatterns = [p for p in self.urlpatterns if str(p.pattern) != full_path]
+
+
+registry = UrlRegistry()
+

django_api_versioning/settings.py

@@ -0,0 +1,77 @@
+import logging
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from dataclasses import dataclass
+from typing import Optional
+from .exceptions import VersionTypeError, VersionRangeError, VersioningError
+
+# Initialize logger
+logger = logging.getLogger(__name__)
+
+@dataclass
+class APISettings:
+
+    API_BASE_PATH: str = "api/v{version}/"
+    API_MAX_VERSION: int = 1
+    API_MIN_VERSION: int = 1
+    ROOT_URLCONF: str = 'django_api_versioning.urls'
+
+    @staticmethod
+    def get_setting(name: str, default: Optional[any] = None) -> Optional[any]:
+        """
+        Reads the setting from Django settings and provides a default if not found.
+        """
+        return getattr(settings, name, default)
+    
+    def __post_init__(self):
+        # Ensure API_BASE_PATH contains "{version}"
+        if "{version}" not in self.API_BASE_PATH:
+            raise VersioningError("API_BASE_PATH must contain '{version}' like 'api/v{version}/' to support API versioning.")
+        
+        # Ensure that API_BASE_PATH ends with a "/"
+        if not self.API_BASE_PATH.endswith("/"):
+            logger.warning(
+                "API_BASE_PATH should end with a '/'. Adding '/' automatically."
+            )
+            self.API_BASE_PATH += "/"
+
+        # Validate version settings
+        self.validate_version_settings()
+
+        if not self.ROOT_URLCONF:
+            raise ImproperlyConfigured("ROOT_URLCONF is required in settings.")
+
+    def validate_version_settings(self) -> None:
+        """
+        Validates that the API_MIN_VERSION and API_MAX_VERSION are integers
+        and that API_MIN_VERSION is not greater than API_MAX_VERSION.
+        """
+        if not isinstance(self.API_MIN_VERSION, int):
+            raise VersionTypeError(f"API_MIN_VERSION must be an integer, got {type(self.API_MIN_VERSION).__name__}.")
+        
+        if not isinstance(self.API_MAX_VERSION, int):
+            raise VersionTypeError(f"API_MAX_VERSION must be an integer, got {type(self.API_MAX_VERSION).__name__}.")
+        
+        if self.API_MIN_VERSION > self.API_MAX_VERSION:
+            raise VersionRangeError("API_MIN_VERSION cannot be greater than API_MAX_VERSION.")
+
+
+# Adding default settings if not defined in Django settings
+default_settings = {
+    'API_BASE_PATH': "api/v{version}/",
+    'API_MAX_VERSION': 1,
+    'API_MIN_VERSION': 1,
+    'ROOT_URLCONF': 'django_api_versioning.urls',
+}
+
+# Override default settings with actual Django settings if they exist
+for setting, default_value in default_settings.items():
+    setattr(settings, setting, getattr(settings, setting, default_value))
+
+# Initialize APISettings from Django settings
+api_settings = APISettings(
+    API_BASE_PATH=APISettings.get_setting("API_BASE_PATH", "api/v{version}/"),
+    API_MAX_VERSION=APISettings.get_setting("API_MAX_VERSION", 1),
+    API_MIN_VERSION=APISettings.get_setting("API_MIN_VERSION", 1),
+    ROOT_URLCONF=APISettings.get_setting("ROOT_URLCONF", 'django_api_versioning.urls')
+)

django_api_versioning/urls.py

@@ -0,0 +1,5 @@
+from typing import List
+from django.urls import URLPattern
+from .registry import registry
+
+urlpatterns: List[URLPattern] = registry.urlpatterns

django_api_versioning-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [Full name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_api_versioning-0.1.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.1
+Name: django-api-versioning
+Version: 0.1.0
+Summary: A powerful and flexible library for managing API versioning in Django projects.
+Home-page: https://github.com/mojtaba-arvin/django-api-versioning
+Author: Mojtaba Arvin
+Author-email: ArvinDevDay@gmail.com
+License: UNKNOWN
+Platform: UNKNOWN
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=3.2
+Provides-Extra: dev
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=0.900; extra == "dev"
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-django>=4.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: pre-commit>=2.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+
+
+# Django API Versioning
+
+[![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
+[![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)
+[![codecov](https://codecov.io/gh/mojtaba-arvin/django-api-versioning/branch/main/graph/badge.svg)](https://codecov.io/gh/mojtaba-arvin/django-api-versioning)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Django API Versioning** is a powerful and flexible library for managing API versioning in Django projects. It allows you to easily define and manage different versions of your API endpoints using decorators, ensuring backward compatibility and clean code organization.
+
+## Features
+
+- **Easy Versioning**: Define API versions using simple decorators.
+- **Backward Compatibility**: Automatically register routes for all versions up to the specified version.
+- **Automatic Registration:** Views are **automatically** registered for each version specified, so there is no need to manually register each version in your `urls.py`.
+- **Customizable Settings**: Configure API base path, minimum and maximum versions, and more.
+- **Type Checking**: Full support for type hints and static type checking with `mypy`.
+- **Testing Ready**: Includes comprehensive test suite and pre-commit hooks for code quality.
+
+## Installation
+
+You can install Django API Versioning via pip:
+
+```bash
+pip install django-api-versioning
+```
+
+## Quick Start
+
+1. ### Add to Django Settings:
+
+```python
+INSTALLED_APPS = [
+    ...
+    'django_api_versioning',
+    ...
+]
+```
+
+2. ### Define API Settings:
+
+```python
+
+API_BASE_PATH = "api/v{version}/"
+API_MIN_VERSION = 1
+API_MAX_VERSION = 3
+```
+
+3. ### Register API urls:
+
+if you don't use any `ROOT_URLCONF` in settings you can use this:
+
+```python
+ROOT_URLCONF = 'django_api_versioning.urls'
+```
+
+or you have already have a `ROOT_URLCONF` in settings, you only need to import them into your root `urls.py`:
+
+```python
+   from django.urls import path, include
+   from django_api_versioning.urls import urlpatterns as api_urlpatterns
+
+   urlpatterns = [
+       # other paths here
+
+       # use empty `route` param and use `API_BASE_PATH` in settings as prefix
+       path('', include(api_urlpatterns)),
+   ]
+
+```
+
+3. ### Use the Decorator:
+
+The `endpoint` decorator can be used in both function-based views (FBVs) and class-based views (CBVs). It's also fully compatible with `Django Rest Framework (DRF)`. The decorator allows you to define versioning for your API views and supports backward compatibility by default and you don't need to pass `backward=True` flag to the `endpoint` decorator.
+
+
+#### Example for Function-Based Views (FBVs):
+
+```python
+from django_api_versioning.decorators import endpoint
+from django.http import HttpResponse
+
+@endpoint("users", version=2, app_name='account_app', view_name="users_list_api")
+def users_view(request):
+    return HttpResponse("API Version 2 Users")
+```
+
+In this example, the `users_view` function is decorated with the endpoint decorator. This specifies that the view is accessible under version `2` of the API and **supports backward compatibility**. The `backward=True` flag as default ensures that users can also access the previous version (version `1`) at `/api/v1/account_app/users`.
+
+#### Example for Class-Based Views (CBVs):
+For class-based views, you can apply the decorator to methods such as `get`, `post`, or any other HTTP method you need to handle. Here’s an example:
+
+```python
+
+from django_api_versioning.decorators import endpoint
+from django.http import JsonResponse
+from django.views import View
+
+@endpoint("users", version=2, app_name='account_app', view_name="users_list_api")
+class UsersView(View):
+
+    def get(self, request):
+        return JsonResponse({"message": "API Version 2 Users"})
+
+```
+
+#### Integration with Django Rest Framework (DRF):
+
+If you have already installed [Django Rest Framework](https://www.django-rest-framework.org/#installation), the `endpoint` decorator can be easily applied to APIView or viewsets. Here’s an example with a DRF APIView:
+
+
+```python
+from rest_framework.views import APIView
+from rest_framework.response import Response
+from django_api_versioning.decorators import endpoint
+
+@endpoint("users", version=2, app_name='account_app', view_name="users_list_api")
+class UsersAPIView(APIView):
+
+    def get(self, request):
+        return Response({"message": "API Version 2 Users"})
+```
+
+#### URL Generation Based on Versioning:
+Once the decorator is applied, the URLs for your API will be generated based on the version specified in the decorator. For example, if the `API_MIN_VERSION` in your settings.py is set to `1` and the version in the decorator is set to `2`, the following URLs will be available:
+
+* `/api/v1/account_app/users`
+* `/api/v2/account_app/users`
+
+The `API_MIN_VERSION` setting ensures that users can access the API using different versions, providing backward compatibility. You can adjust which versions are considered valid by modifying the `API_MIN_VERSION` and `version` numbers in the decorators.
+
+#### Additional Configuration Options:
+
+**Without `app_name`:** If you don't pass `app_name` in the decorator, like this:
+```python
+@endpoint("users", version=2, view_name="users_list_api")
+```
+
+The generated URLs will be:
+
+* `/api/v1/users`
+* `/api/v2/users`
+
+
+**Without `version`:** If you don't pass `version` in the decorator, like this:
+
+```python
+@endpoint("users", view_name="users_list_api")
+```
+
+API versioning will be disabled (`API_BASE_PATH` as prefix will be removed) for that view. The only URL generated will be:
+
+* `/users`
+
+**Setting `backward=False`:** By default, the `backward` parameter is set to `True`, which ensures backward compatibility. If you explicitly set `backward=False`, like this:
+
+```python
+@endpoint("users", version=2, backward=False, view_name="users_list_api")
+```
+
+The generated URL will be only version 2:
+
+* `api/v2/users`
+
+4. Run the Server:
+
+```bash
+python manage.py runserver
+```
+
+## Notes
+### 1. `API_BASE_PATH` in settings Must Include ‍‍`{version}`:
+The `API_BASE_PATH` should always include `{version}` to ensure proper API versioning. This is important for correctly mapping API routes to different versions.
+
+### 2. Using `app_name` in the `endpoint` decorator:
+It's recommended to fill in the `app_name` in the `endpoint` decorator to make the API URLs **more unique and organized**. This ensures that the routes are scoped under the correct app, avoiding potential conflicts and making them easier to manage.
+
+### 3. Views with Version Less Than `API_MIN_VERSION` Are Automatically Ignored:
+Any view whose `version` is less than the `API_MIN_VERSION` will be automatically ignored. This means clients will no longer have access to these older versions, **without the need to manually edit or remove code**. This is handled automatically by the package.
+
+### 4. URLs for Versions Between `API_MIN_VERSION` <= `version` <= `API_MAX_VERSION`:
+Endpoints that have versions within the range defined by `API_MIN_VERSION` <= `version` <= `API_MAX_VERSION` will always have a corresponding URL generated. This ensures that only valid versions will be accessible, providing flexibility in version management.
+
+### `endpoint` Decorator Function Definition
+
+The `endpoint` decorator is designed to register API views with versioning support in a Django application. It provides flexibility in managing versioned endpoints and ensures backward compatibility with previous versions of the API.
+
+```python
+def endpoint(
+    postfix: str,
+    version: Optional[int] = None,
+    backward: bool = True,
+    app_name: Optional[str] = None,
+    view_name: Optional[str] = None,
+) -> Callable:
+    """
+    Decorator to register API views with versioning support.
+
+    - Uses `API_MIN_VERSION` and `API_MAX_VERSION` from Django settings.
+    - Supports backward compatibility by registering multiple versions if needed.
+    - Ensures that no version lower than `API_MIN_VERSION` is registered.
+    
+    Args:
+        postfix (str): The endpoint suffix (e.g., "users" → "api/v1/users").
+        version (Optional[int]): The version of the API. Defaults to None (unversioned).
+        backward (bool): If True, registers routes for all versions from `API_MIN_VERSION` up to the current version, which is less than or equal to `API_MAX_VERSION`. Defaults to True.
+        app_name (Optional[str]): The app name to be prefixed to the route.
+        view_name (Optional[str]): The custom view name for Django.
+
+    Returns:
+        Callable: The decorated view function.
+
+    Raises:
+        VersionTypeError: If the provided `version` is not an integer.
+        VersionRangeError: If `API_MIN_VERSION` or `API_MAX_VERSION` are not properly set.
+    """
+```
+
+
+## Contributing
+
+Feel free to open an issue or submit a pull request with any improvements or bug fixes. We appreciate contributions to enhance this package!
+
+## License
+
+This package is open-source and available under the MIT license.
+
+

django_api_versioning-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+django_api_versioning/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_api_versioning/decorators.py,sha256=BC_7ZQwCDq3BjPdcNw-Efdh09kHv3uDjZEW1nGgcNog,3732
+django_api_versioning/exceptions.py,sha256=MgCpaNBsD8laQoVIVK823_t1liQ82K_uqguuA60PxXQ,485
+django_api_versioning/registry.py,sha256=FCRTHGyl995U1kLlxtIBp3lb62v-6AbSK9k3orzZxWA,1140
+django_api_versioning/settings.py,sha256=rasiYFuKM0EUYqzrpIphHGPEYb209uz56pEKR59R8w4,3006
+django_api_versioning/urls.py,sha256=B8UBYSXdyq_xTpWeN5zzH2SQzKiqZQMx3WFBrsu93X0,144
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_decorators.py,sha256=G2G3PR_QAPNyJuaw7H9BMARSOK8C6GJlHRAL3KmTuCY,3587
+tests/test_exceptions.py,sha256=fsyfA7ouIMqz6Emexqo_oB7oVEZlhqptNmwH8KX37s8,863
+tests/test_registry.py,sha256=KQT6yWkfKZmcLShFkidHwfJfPi8yHN5i9xuzC3vqDso,2634
+tests/test_settings.py,sha256=SjieOTnwHdU0E6A2-qLE3iXG5osY3qacbAzJJ7tqD-0,5213
+tests/test_urls.py,sha256=DA8DbIEAYX812Re2PlTkL1OpkwCO2IZ1vW_QMh2d9nI,1207
+django_api_versioning-0.1.0.dist-info/LICENSE,sha256=iDPJdze6sBlBBSoB-BIyT2iHfHDGUAaZG3nTFd6m2FQ,1070
+django_api_versioning-0.1.0.dist-info/METADATA,sha256=B5McJrgZzySQghhKtqCvLMfBABI_TjgIFX8zHAnidS4,10436
+django_api_versioning-0.1.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+django_api_versioning-0.1.0.dist-info/top_level.txt,sha256=F4n1zaE6P--9OytuMrvCD50vn7NvIVWkIl6ie9fsFck,28
+django_api_versioning-0.1.0.dist-info/RECORD,,

django_api_versioning-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_api_versioning-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+django_api_versioning
+tests

tests/test_decorators.py

@@ -0,0 +1,88 @@
+import pytest
+from unittest.mock import patch
+from django_api_versioning.settings import api_settings as settings
+from django_api_versioning.registry import registry
+from django_api_versioning.decorators import endpoint
+from django_api_versioning.exceptions import InvalidVersionError, VersionTypeError, VersionRangeError
+
+@pytest.fixture(autouse=True)
+def clear_registered_routes():
+    """Clear the registry before each test to ensure isolation."""
+    registry.urlpatterns.clear()  # Clear the previous routes before the test
+    yield  # Run the test
+    registry.urlpatterns.clear()  # Clean up after the test to ensure isolation
+
+@pytest.fixture
+def mock_settings():
+    """Fixture to mock settings for API versioning."""
+    with patch.object(settings, 'API_MIN_VERSION', 1), patch.object(settings, 'API_MAX_VERSION', 3):
+        yield settings
+
+def test_version_below_minimum(mock_settings):
+    @endpoint("users", version=0)
+    def test_view():
+        pass
+
+    registered_routes = [str(p.pattern) for p in registry.urlpatterns]
+    assert "api/v0/users" not in registered_routes, f"Unexpected registered routes: {registered_routes}"
+
+def test_version_above_maximum(mock_settings):
+    with pytest.raises(InvalidVersionError):
+        @endpoint("users", version=4)
+        def test_view():
+            pass
+
+def test_invalid_version_type(mock_settings):
+    with pytest.raises(VersionTypeError):
+        @endpoint("users", version="invalid")
+        def test_view():
+            pass
+
+def test_register_unversioned_route(mock_settings):
+    @endpoint("users")
+    def test_view():
+        pass
+
+    registered_routes = [str(p.pattern) for p in registry.urlpatterns]
+    # Assert that no versioned route (e.g., api/v1/users) is registered
+    for version in range(1, 4):
+        assert f"api/v{version}/users" not in registered_routes, f"Unexpected versioned route: api/v{version}/users"
+    # Assert that the unversioned route is registered
+    assert "users" in registered_routes, f"Missing unversioned route: {registered_routes}"
+
+def test_backward_compatibility_enabled(mock_settings):
+    @endpoint("users", version=3)
+    def test_view():
+        pass
+
+    registered_routes = [str(p.pattern) for p in registry.urlpatterns]
+    # Assert that versions 1, 2, and 3 are registered for backward compatibility
+    for version in range(1, 4):
+        assert f"api/v{version}/users" in registered_routes, f"Missing route for v{version}: {registered_routes}"
+
+def test_backward_compatibility_disabled(mock_settings):
+    @endpoint("users", version=2, backward=False)
+    def test_view():
+        pass
+
+    registered_routes = [str(p.pattern) for p in registry.urlpatterns]
+    # Assert that only version 2 is registered, and versions 1 and 3 are not
+    assert "api/v2/users" in registered_routes
+    assert "api/v1/users" not in registered_routes
+    assert "api/v3/users" not in registered_routes
+
+def test_invalid_version_range(mock_settings):
+    # Set an invalid version range (min > max)
+    with patch.object(settings, 'API_MIN_VERSION', 4), patch.object(settings, 'API_MAX_VERSION', 3):
+        with pytest.raises(VersionRangeError):
+            @endpoint("users", version=2)
+            def test_view():
+                pass
+
+def test_missing_api_version_settings():
+    # Remove API version settings to test for missing settings scenario
+    with patch.dict(settings.__dict__, {'API_MIN_VERSION': None, 'API_MAX_VERSION': None}):
+        with pytest.raises(VersionRangeError):
+            @endpoint("users", version=2)
+            def test_view():
+                pass

tests/test_exceptions.py

@@ -0,0 +1,19 @@
+import pytest
+from django_api_versioning.exceptions import VersioningError, InvalidVersionError, VersionRangeError, VersionTypeError
+
+def test_versioning_error():
+    with pytest.raises(VersioningError, match="General versioning error"):
+        raise VersioningError("General versioning error")
+
+
+def test_invalid_version_error():
+    with pytest.raises(InvalidVersionError, match="Invalid version specified"):
+        raise InvalidVersionError("Invalid version specified")
+
+def test_version_range_error():
+    with pytest.raises(VersionRangeError, match="Invalid version range: min_version > max_version"):
+        raise VersionRangeError("Invalid version range: min_version > max_version")
+
+def test_version_type_error():
+    with pytest.raises(VersionTypeError, match="Version must be an integer"):
+        raise VersionTypeError("Version must be an integer")

tests/test_registry.py

@@ -0,0 +1,83 @@
+import pytest
+from django_api_versioning.registry import registry  
+
+
+@pytest.fixture
+def clear_registry():
+    """Clears the registry before each test to ensure isolation."""
+    registry.urlpatterns.clear()
+    yield
+    registry.urlpatterns.clear()
+
+
+def test_register_new_route(clear_registry):
+    """Test that a new route is correctly registered."""
+    def sample_view():
+        pass
+    
+    route = "api/v1/users"
+    registry.register(route, sample_view)
+
+    assert len(registry.urlpatterns) == 1
+    assert str(registry.urlpatterns[0].pattern) == route
+
+
+def test_register_duplicate_route(clear_registry):
+    """Test that a duplicate route is detected and removed."""
+    def sample_view():
+        pass
+    
+    route = "api/v1/users"
+    registry.register(route, sample_view)
+    registry.register(route, sample_view)  # Registering the same route again
+
+    assert len(registry.urlpatterns) == 1  # Only one instance of the route should be registered
+    assert str(registry.urlpatterns[0].pattern) == route
+
+
+def test_register_route_with_name(clear_registry):
+    """Test that a route is registered with a custom name."""
+    def sample_view():
+        pass
+    
+    route = "api/v1/users"
+    route_name = "user-list"
+    registry.register(route, sample_view, name=route_name)
+
+    # Check if the route has the correct name
+    assert len(registry.urlpatterns) == 1
+    assert registry.urlpatterns[0].name == route_name
+    assert str(registry.urlpatterns[0].pattern) == route
+
+
+def test_register_route_with_view_conversion(clear_registry):
+    """Test that a view is correctly converted to an 'as_view' callable if needed."""
+    class SampleView:
+        def as_view(self):
+            return lambda: None  # Simulate view conversion
+
+    route = "api/v1/items"
+    view = SampleView()
+    
+    registry.register(route, view)
+
+    # Check if the route is registered with the converted view
+    assert len(registry.urlpatterns) == 1
+    assert callable(registry.urlpatterns[0].callback)  # Should be callable as a view
+    assert str(registry.urlpatterns[0].pattern) == route
+
+
+def test_duplicate_route_removal(clear_registry):
+    """Test that duplicate routes are correctly removed."""
+    def sample_view():
+        pass
+    
+    route1 = "api/v1/posts"
+    route2 = "api/v1/posts"  # Duplicate route
+    
+    registry.register(route1, sample_view)
+    registry.register(route2, sample_view)  # Registering the same route again
+
+    # Check that only one route exists after attempting to register the duplicate
+    assert len(registry.urlpatterns) == 1
+    assert str(registry.urlpatterns[0].pattern) == route1

tests/test_settings.py

@@ -0,0 +1,147 @@
+import pytest
+from typing import Iterator
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.test import override_settings
+from django_api_versioning.settings import APISettings 
+from django_api_versioning.exceptions import VersioningError, VersionTypeError
+
+@pytest.fixture(autouse=True)
+def reset_settings() -> Iterator[None]:
+    """
+    Automatically resets Django settings to their default values after each test.
+    This prevents state leakage between tests.
+    """
+    settings.API_BASE_PATH = "api/v{version}/"
+    settings.API_MAX_VERSION = 1
+    settings.API_MIN_VERSION = 1
+    settings.ROOT_URLCONF = "django_api_versioning.urls"
+    yield  # Run the test
+    # Reset settings after test execution
+    settings.API_BASE_PATH = "api/v{version}/"
+    settings.API_MAX_VERSION = 1
+    settings.API_MIN_VERSION = 1
+    settings.ROOT_URLCONF = "django_api_versioning.urls"
+
+@override_settings(
+    API_BASE_PATH="api/v{version}/",
+    API_MAX_VERSION=1,
+    API_MIN_VERSION=1,
+    ROOT_URLCONF="django_api_versioning.urls",
+)
+def test_default_settings() -> None:
+    """
+    Verifies that default settings are correctly applied when using APISettings.
+    """
+    api_settings = APISettings(
+        API_BASE_PATH=settings.API_BASE_PATH,
+        API_MAX_VERSION=settings.API_MAX_VERSION,
+        API_MIN_VERSION=settings.API_MIN_VERSION,
+        ROOT_URLCONF=settings.ROOT_URLCONF,
+    )
+
+    assert api_settings.API_BASE_PATH == "api/v{version}/"
+    assert api_settings.API_MAX_VERSION == 1
+    assert api_settings.API_MIN_VERSION == 1
+    assert api_settings.ROOT_URLCONF == "django_api_versioning.urls"
+
+@override_settings(
+    API_BASE_PATH="api/v{version}/custom/",
+    API_MAX_VERSION=2,
+    API_MIN_VERSION=1,
+    ROOT_URLCONF="my_custom_urls",
+)
+def test_custom_settings() -> None:
+    """
+    Ensures that custom settings override the default values.
+    """
+    api_settings = APISettings(
+        API_BASE_PATH=settings.API_BASE_PATH,
+        API_MAX_VERSION=settings.API_MAX_VERSION,
+        API_MIN_VERSION=settings.API_MIN_VERSION,
+        ROOT_URLCONF=settings.ROOT_URLCONF,
+    )
+
+    assert api_settings.API_BASE_PATH == "api/v{version}/custom/"
+    assert api_settings.API_MAX_VERSION == 2
+    assert api_settings.API_MIN_VERSION == 1
+    assert api_settings.ROOT_URLCONF == "my_custom_urls"
+
+@override_settings(API_BASE_PATH="api/v1/")
+def test_invalid_api_base_path() -> None:
+    """
+    Ensures that API_BASE_PATH without '{version}' raises a ValueError.
+    """
+    with pytest.raises(VersioningError, match="API_BASE_PATH must contain '{version}'"):
+        APISettings(
+            API_BASE_PATH=settings.API_BASE_PATH,
+            API_MAX_VERSION=1,
+            API_MIN_VERSION=1,
+            ROOT_URLCONF="django_api_versioning.urls",
+        )
+
+@override_settings(API_MIN_VERSION=2, API_MAX_VERSION=1)
+def test_invalid_version_range() -> None:
+    """
+    Ensures that API_MIN_VERSION > API_MAX_VERSION raises a ValueError.
+    """
+    with pytest.raises(VersioningError, match="API_MIN_VERSION cannot be greater than API_MAX_VERSION"):
+        APISettings(
+            API_BASE_PATH="api/v{version}/",
+            API_MAX_VERSION=settings.API_MAX_VERSION,
+            API_MIN_VERSION=settings.API_MIN_VERSION,
+            ROOT_URLCONF="django_api_versioning.urls",
+        )
+
+@override_settings(API_MIN_VERSION="one")
+def test_api_min_version_is_not_integer() -> None:
+    """
+    Ensures that API_MIN_VERSION is validated as an integer.
+    """
+    with pytest.raises(VersionTypeError, match="API_MIN_VERSION must be an integer"):
+        APISettings(
+            API_BASE_PATH="api/v{version}/",
+            API_MAX_VERSION=1,
+            API_MIN_VERSION=settings.API_MIN_VERSION,
+            ROOT_URLCONF="django_api_versioning.urls",
+        )
+
+@override_settings(API_MAX_VERSION="two")
+def test_api_max_version_is_not_integer() -> None:
+    """
+    Ensures that API_MAX_VERSION is validated as an integer.
+    """
+    with pytest.raises(VersionTypeError, match="API_MAX_VERSION must be an integer"):
+        APISettings(
+            API_BASE_PATH="api/v{version}/",
+            API_MAX_VERSION=settings.API_MAX_VERSION,
+            API_MIN_VERSION=1,
+            ROOT_URLCONF="django_api_versioning.urls",
+        )
+
+@override_settings(API_BASE_PATH="api/v{version}")
+def test_validate_version_path_format() -> None:
+    """
+    Ensures that API_BASE_PATH automatically ends with '/' if not already present.
+    """
+    api_settings = APISettings(
+        API_BASE_PATH=settings.API_BASE_PATH,
+        API_MAX_VERSION=1,
+        API_MIN_VERSION=1,
+        ROOT_URLCONF="django_api_versioning.urls",
+    )
+
+    assert api_settings.API_BASE_PATH == "api/v{version}/"
+
+@override_settings(ROOT_URLCONF=None)
+def test_missing_root_urlconf() -> None:
+    """
+    Ensures that missing ROOT_URLCONF raises an ImproperlyConfigured exception.
+    """    
+    with pytest.raises(ImproperlyConfigured, match="ROOT_URLCONF is required"):
+        APISettings(
+            API_BASE_PATH="api/v{version}/",
+            API_MAX_VERSION=1,
+            API_MIN_VERSION=1,
+            ROOT_URLCONF=settings.ROOT_URLCONF,  # None
+        )

tests/test_urls.py

@@ -0,0 +1,33 @@
+import pytest
+from django.urls import URLPattern, resolve
+
+
+@pytest.fixture(scope="module", autouse=True)
+def clear_urlpatterns():
+    """Ensure urlpatterns is cleared before each test."""
+    from django_api_versioning.urls import urlpatterns
+    urlpatterns.clear()  # Clear any existing patterns
+    yield
+
+@pytest.fixture(scope="module")
+def register_routes():
+    from django_api_versioning.decorators import endpoint
+
+    # Registering the accounts route with the endpoint decorator
+    @endpoint("accounts" , view_name="accounts_view")
+    def test_accounts():
+        pass
+
+    yield
+
+def test_urlpatterns_type():
+    """Test to check that urlpatterns is a list of URLPattern."""
+    from django_api_versioning.urls import urlpatterns
+
+    assert isinstance(urlpatterns, list), "urlpatterns should be a list."
+    assert all(isinstance(pattern, URLPattern) for pattern in urlpatterns), "All elements in urlpatterns should be of type URLPattern."
+
+def test_registry_urlpatterns(register_routes):
+    """Test to check that the 'accounts' route resolves correctly."""
+    match = resolve('/accounts')
+    assert match.view_name == 'accounts_view', f"Expected 'accounts_view', but got {match.view_name}"