fast-version 1.0.0__tar.gz

fast_version-1.0.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.1
+Name: fast-version
+Version: 1.0.0
+Summary: Fastapi versioning package with accept header
+Home-page: https://github.com/modern-python/fast-version
+Author: Artur Shiriev
+Author-email: me@shiriev.ru
+Requires-Python: >=3.8,<=3.12
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastapi (>=0.100)
+Description-Content-Type: text/markdown
+
+FastAPI versioning library
+==
+This package adds versioning by Accept-header into FastAPI
+
+## Quickstart:
+### Defining app and routes
+```python
+import fastapi
+
+from fast_version import VersionedAPIRouter, init_fastapi_versioning
+
+
+VERSION_HEADER: str = "application/vnd.some.name+json"
+ROUTER_OBJ = VersionedAPIRouter()
+
+
+@ROUTER_OBJ.get("/test/")
+async def test_get() -> dict:
+    return {"version": (1, 0)}
+
+
+@ROUTER_OBJ.get("/test/")
+@ROUTER_OBJ.set_api_version((2, 0))
+async def test_get_v2() -> dict:
+    return {"version": (2, 0)}
+
+
+app = fastapi.FastAPI()
+app.include_router(ROUTER_OBJ)
+init_fastapi_versioning(app=app, vendor_media_type=VERSION_HEADER)
+```
+
+### Query Examples
+```bash
+# call 1.0 version
+curl -X 'GET' 'https://test.ru/test/' -H 'accept: application/vnd.some.name+json; version=1.0'
+
+curl -X 'GET' 'https://test.ru/test/' -H 'accept: application/vnd.some.name+json'
+
+curl -X 'GET' 'https://test.ru/test/'
+
+# call 2.0 version
+curl -X 'GET' 'https://test.ru/test/' -H 'accept: application/vnd.some.name+json; version=2.0'
+```

fast_version-1.0.0/README.md

@@ -0,0 +1,44 @@
+FastAPI versioning library
+==
+This package adds versioning by Accept-header into FastAPI
+
+## Quickstart:
+### Defining app and routes
+```python
+import fastapi
+
+from fast_version import VersionedAPIRouter, init_fastapi_versioning
+
+
+VERSION_HEADER: str = "application/vnd.some.name+json"
+ROUTER_OBJ = VersionedAPIRouter()
+
+
+@ROUTER_OBJ.get("/test/")
+async def test_get() -> dict:
+    return {"version": (1, 0)}
+
+
+@ROUTER_OBJ.get("/test/")
+@ROUTER_OBJ.set_api_version((2, 0))
+async def test_get_v2() -> dict:
+    return {"version": (2, 0)}
+
+
+app = fastapi.FastAPI()
+app.include_router(ROUTER_OBJ)
+init_fastapi_versioning(app=app, vendor_media_type=VERSION_HEADER)
+```
+
+### Query Examples
+```bash
+# call 1.0 version
+curl -X 'GET' 'https://test.ru/test/' -H 'accept: application/vnd.some.name+json; version=1.0'
+
+curl -X 'GET' 'https://test.ru/test/' -H 'accept: application/vnd.some.name+json'
+
+curl -X 'GET' 'https://test.ru/test/'
+
+# call 2.0 version
+curl -X 'GET' 'https://test.ru/test/' -H 'accept: application/vnd.some.name+json; version=2.0'
+```

fast_version-1.0.0/fast_version/__init__.py

@@ -0,0 +1,8 @@
+from fast_version.app import init_fastapi_versioning
+from fast_version.router import VersionedAPIRouter
+
+
+__all__ = [
+    "init_fastapi_versioning",
+    "VersionedAPIRouter",
+]

fast_version-1.0.0/fast_version/app.py

@@ -0,0 +1,141 @@
+import contextlib
+import copy
+import re
+import typing
+from types import MethodType
+
+import fastapi
+from fastapi.openapi.utils import get_openapi
+from starlette import types
+from starlette.responses import JSONResponse
+
+from fast_version import helpers
+from fast_version.router import VersionedAPIRoute, VersionedAPIRouter
+
+
+_VERSION_RE: typing.Final = re.compile(r"^\d\.\d$")
+
+
+def _get_vendor_media_type() -> str:
+    return VersionedAPIRouter.VENDOR_MEDIA_TYPE
+
+
+def init_fastapi_versioning(*, app: fastapi.FastAPI, vendor_media_type: str) -> None:
+    VersionedAPIRouter.VENDOR_MEDIA_TYPE = vendor_media_type
+    app.add_middleware(FastAPIVersioningMiddleware)
+    app.openapi = MethodType(_custom_openapi, app)  # type: ignore[method-assign]
+
+
+class FastAPIVersioningMiddleware:
+    def __init__(self, app: fastapi.FastAPI) -> None:
+        self.app = app
+
+    async def __call__(
+        self,
+        scope: types.Scope,
+        receive: types.Receive,
+        send: types.Send,
+    ) -> None:
+        error_response: JSONResponse | None = None
+        while True:
+            if scope["type"] != "http":
+                break
+
+            accept_header_from_request = helpers.get_accept_header_from_scope(scope)
+            if not accept_header_from_request or accept_header_from_request == "*/*":
+                break
+
+            media_type: str
+            version_str: str
+            try:
+                media_type, version_str = accept_header_from_request.split(";")
+            except ValueError:
+                break
+
+            if media_type.strip() != _get_vendor_media_type():
+                error_response = JSONResponse(
+                    {"detail": "Wrong media type"},
+                    status_code=406,
+                )
+                break
+
+            version = ""
+            version_key = ""
+            with contextlib.suppress(ValueError):
+                version_key, version = version_str.strip().split("=")
+
+            if version_key.lower().strip() != "version":
+                error_response = JSONResponse(
+                    {"detail": "No version in Accept header"},
+                    status_code=400,
+                )
+                break
+
+            if not _VERSION_RE.match(version):
+                error_response = JSONResponse(
+                    {"detail": "Version should be in <major>.<minor> format"},
+                    status_code=400,
+                )
+                break
+
+            scope["version"] = tuple(
+                int(version_part) for version_part in version.split(".")
+            )
+            break
+        if error_response:
+            return await error_response(scope, receive, send)
+        return await self.app(scope, receive, send)
+
+
+def _custom_openapi(self: fastapi.FastAPI) -> dict[str, typing.Any]:
+    if self.openapi_schema:
+        return self.openapi_schema
+
+    routes = []
+    for route_item in self.routes:
+        if not isinstance(route_item, VersionedAPIRoute):
+            routes.append(route_item)
+            continue
+
+        # trick to avoid merging routes
+        route_copy: VersionedAPIRoute = copy.copy(route_item)
+        route_copy.path_format = f"{route_copy.path_format}:{route_copy.version_str}"
+        routes.append(route_copy)
+
+    self.openapi_schema = get_openapi(
+        title=self.title,
+        version=self.version,
+        openapi_version=self.openapi_version,
+        summary=self.summary,
+        description=self.description,
+        terms_of_service=self.terms_of_service,
+        contact=self.contact,
+        license_info=self.license_info,
+        routes=routes,
+        webhooks=self.webhooks.routes,
+        tags=self.openapi_tags,
+        servers=self.servers,
+    )
+    paths_dict = {}
+    raw_path: str
+    methods: dict[str, typing.Any]
+    for raw_path, methods in self.openapi_schema["paths"].items():
+        if ":" not in raw_path:
+            paths_dict[raw_path] = methods
+            continue
+        clean_path, version = raw_path.split(":")
+        for payload in methods.values():
+            if "requestBody" not in payload:
+                continue
+            payload["requestBody"]["content"] = {
+                f"{_get_vendor_media_type()}; version={version}": v
+                for k, v in payload["requestBody"]["content"].items()
+            }
+
+        if clean_path not in paths_dict:
+            paths_dict[clean_path] = methods
+            continue
+
+        helpers.dict_merge(paths_dict[clean_path], methods)
+    self.openapi_schema["paths"] = paths_dict
+    return self.openapi_schema

fast_version-1.0.0/fast_version/helpers.py

@@ -0,0 +1,26 @@
+import typing
+
+from starlette import datastructures, types
+
+
+def dict_merge(dict1: dict[str, typing.Any], dict2: dict[str, typing.Any]) -> None:
+    for key in dict2:
+        if key in dict1:
+            if isinstance(dict1[key], dict) and isinstance(dict2[key], dict):
+                dict_merge(dict1[key], dict2[key])
+        else:
+            dict1[key] = dict2[key]
+
+
+def get_accept_header_from_scope(scope: types.Scope) -> str:
+    headers = datastructures.Headers(scope=scope)
+    return headers.get("Accept", "").strip().lower()
+
+
+class ClassProperty:
+    # ruff: noqa: ANN401
+    def __init__(self, function: typing.Any) -> None:
+        self.function: typing.Any = classmethod(function)
+
+    def __get__(self, *args: typing.Any) -> typing.Any:
+        return self.function.__get__(*args)()

fast_version-1.0.0/fast_version/router.py

@@ -0,0 +1,73 @@
+import typing
+
+from fastapi.routing import APIRoute, APIRouter
+from fastapi.types import DecoratedCallable
+from starlette import types
+from starlette.responses import JSONResponse
+from starlette.routing import Match
+
+from fast_version.helpers import ClassProperty
+
+
+DEFAULT_VERSION: typing.Final = (1, 0)
+
+
+# ruff: noqa: B009, B010
+# allow getattr, setattr with const
+class VersionedAPIRoute(APIRoute):
+    @property
+    def version(self) -> tuple[int, int]:
+        return typing.cast(tuple[int, int], getattr(self.endpoint, "version"))
+
+    @property
+    def version_str(self) -> str:
+        return ".".join(str(x) for x in self.version)
+
+    def matches(self, scope: types.Scope) -> tuple[Match, types.Scope]:
+        match, child_scope = super().matches(scope)
+        if match != Match.FULL:
+            return match, child_scope
+
+        request_version: tuple[int, int] = scope.get("version", DEFAULT_VERSION)
+        if request_version == self.version:
+            return Match.FULL, child_scope
+        return Match.NONE, {}
+
+
+class VersionedAPIRouter(APIRouter):
+    VENDOR_MEDIA_TYPE = ""
+
+    def api_route(
+        self,
+        path: str,
+        **kwargs: typing.Any,  # noqa: ANN401
+    ) -> typing.Callable[[DecoratedCallable], DecoratedCallable]:
+        def decorator(func: DecoratedCallable) -> DecoratedCallable:
+            if not hasattr(func, "version"):
+                setattr(func, "version", DEFAULT_VERSION)
+            version_str = ".".join([str(x) for x in getattr(func, "version")])
+
+            class VersionedJSONResponse(JSONResponse):
+                @ClassProperty
+                def media_type(self) -> str:  # type: ignore[override]
+                    """Media type for docs."""
+                    return (
+                        f"{VersionedAPIRouter.VENDOR_MEDIA_TYPE}; version={version_str}"
+                    )
+
+            kwargs["response_class"] = VersionedJSONResponse
+            kwargs["route_class_override"] = VersionedAPIRoute
+            self.add_api_route(path, func, **kwargs)
+            return func
+
+        return decorator
+
+    @staticmethod
+    def set_api_version(
+        version: tuple[int, int],
+    ) -> typing.Callable[[DecoratedCallable], DecoratedCallable]:
+        def decorator(func: DecoratedCallable) -> DecoratedCallable:
+            setattr(func, "version", version)
+            return func
+
+        return decorator

fast_version-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "fast-version"
+version = "1.0.0"
+description = "Fastapi versioning package with accept header"
+authors = ["Artur Shiriev <me@shiriev.ru>"]
+readme = "README.md"
+classifiers = ["Programming Language :: Python :: 3.11", "Framework :: Pytest"]
+homepage = "https://github.com/modern-python/fast-version"
+packages = [
+    { include = "fast_version" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.8,<=3.12"
+fastapi = ">=0.100"
+
+[tool.poetry.dev-dependencies]
+pytest = "*"
+pytest-asyncio = "*"
+pytest-cov = "*"
+httpx = "*"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+select = ["ALL"]
+ignore = [
+    "D1", # allow missing docstrings
+    "S101", # allow asserts
+    "TCH", # ignore flake8-type-checking
+    "FBT", # allow boolean args
+    "ANN101", # missing-type-self
+]
+
+[tool.ruff.isort]
+lines-after-imports = 2
+no-lines-before = ["standard-library", "local-folder"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=. --cov-report term-missing"
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"