fastapi-cbv-router 0.1.0__tar.gz

fastapi_cbv_router-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs / tooling
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/

fastapi_cbv_router-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

fastapi_cbv_router-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: fastapi-cbv-router
+Version: 0.1.0
+Summary: Class-based views for FastAPI routers — a maintained, FastAPI 0.137+ compatible drop-in for fastapi_utils.cbv.
+Project-URL: Homepage, https://github.com/Chelovek760/fastapi-cbv
+Project-URL: Repository, https://github.com/Chelovek760/fastapi-cbv
+Project-URL: Issues, https://github.com/Chelovek760/fastapi-cbv/issues
+Author: Vladimir Klychnikov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cbv,class-based-views,dependency-injection,fastapi,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.115
+Description-Content-Type: text/markdown
+
+# fastapi-cbv-router
+
+[![CI](https://github.com/Chelovek760/fastapi-cbv/actions/workflows/ci.yml/badge.svg)](https://github.com/Chelovek760/fastapi-cbv/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-cbv-router.svg)](https://pypi.org/project/fastapi-cbv-router/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-cbv-router.svg)](https://pypi.org/project/fastapi-cbv-router/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Class-based views (CBV) for FastAPI routers — a small, maintained drop-in
+replacement for the unmaintained `fastapi_utils.cbv`. Works on modern FastAPI
+(tested from 0.115), and in particular survives FastAPI 0.137+, where
+`fastapi_utils.cbv` breaks.
+
+## Why
+
+`fastapi_utils.cbv` relied on `APIRouter.include_router` eagerly copying
+`APIRoute` objects into `router.routes`. FastAPI 0.137 made `include_router`
+lazy, which broke `fastapi_utils` whenever two `@cbv` decorators shared one
+router.
+
+`fastapi-cbv-router` rebuilds each endpoint through the router's public
+`add_api_route` / `add_api_websocket_route` API, which stays eager and
+delegates all route-state computation back to FastAPI. Route configuration is
+copied by introspecting `add_api_route`'s own parameters, so the package adapts
+to upstream FastAPI changes instead of hard-coding a kwarg list.
+
+## Features
+
+- One small decorator, `@cbv(router)` — no base classes or metaclasses required.
+- Share a single dependency instance (`self`) across every endpoint on a class.
+- Inject dependencies either as **class-level annotated attributes** or through a
+  **custom `__init__`** — use whichever fits your style.
+- Works with regular HTTP routes **and** WebSocket routes.
+- Preserves all route configuration (`status_code`, `response_model`,
+  `dependencies`, tags, …) and the router `prefix`.
+- Fully typed (`py.typed`), zero dependencies beyond FastAPI.
+
+## Requirements
+
+- **Python:** 3.13+
+- **FastAPI:** 0.115+ — continuously tested against the latest release, currently
+  **0.137.2**. The test suite specifically covers FastAPI 0.137+, where
+  `include_router` became lazy and broke `fastapi_utils.cbv`.
+
+## Install
+
+```bash
+pip install fastapi-cbv-router
+# or
+uv add fastapi-cbv-router
+```
+
+## Quickstart
+
+```python
+from fastapi import APIRouter, Depends, FastAPI
+from fastapi_cbv_router import cbv
+
+router = APIRouter(prefix="/items")
+
+
+def get_db() -> str:
+    return "db-connection"
+
+
+@cbv(router)
+class ItemsView:
+    db: str = Depends(get_db)
+
+    @router.get("/")
+    def list_items(self) -> dict:
+        return {"db": self.db, "items": []}
+
+    @router.post("/")
+    def create_item(self, name: str) -> dict:
+        return {"db": self.db, "created": name}
+
+
+app = FastAPI()
+app.include_router(router)
+```
+
+Class-level annotated attributes become keyword-only dependencies injected via
+`Depends(ItemsView)` and are available as `self.<attr>` in every endpoint.
+`ClassVar`-annotated attributes are treated as plain class constants and are not
+injected.
+
+## Dependency injection via `__init__`
+
+If you prefer constructor injection — for example to keep a clean abstract base
+and wire dependencies explicitly — define a custom `__init__`. Its parameters
+are resolved by FastAPI when the view is constructed, exactly like an endpoint's
+parameters:
+
+```python
+import abc
+from http import HTTPStatus
+
+from fastapi import APIRouter, Depends
+from fastapi_cbv_router import cbv
+
+router = APIRouter(prefix="/items", tags=["items"])
+
+
+def get_service() -> "ItemService":
+    ...
+
+
+class ItemApi(abc.ABC):
+    @abc.abstractmethod
+    async def get_item(self, item_id: int) -> dict: ...
+
+
+@cbv(router)
+class HttpItemApi(ItemApi):
+    def __init__(self, service: "ItemService" = Depends(get_service)) -> None:
+        self.service = service
+
+    @router.get("/{item_id}", status_code=HTTPStatus.OK)
+    async def get_item(self, item_id: int) -> dict:
+        return await self.service.fetch(item_id)
+```
+
+This pairs cleanly with DI containers such as
+[`dependency-injector`](https://python-dependency-injector.ets-labs.org/): use
+`Depends(Provide[...])` defaults on the `@inject`-decorated `__init__`.
+
+## WebSocket routes
+
+WebSocket endpoints are supported the same way as HTTP routes:
+
+```python
+from fastapi import APIRouter, WebSocket
+from fastapi_cbv_router import cbv
+
+router = APIRouter()
+
+
+@cbv(router)
+class ChatView:
+    @router.websocket("/ws")
+    async def chat(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        await websocket.send_text("hello")
+        await websocket.close()
+```
+
+## Scope
+
+Only the plain `@cbv(router)` form is supported (no `*urls` / `set_responses`
+helpers). This is intentional — it covers the common case with the smallest,
+most maintainable surface.
+
+## License
+
+MIT

fastapi_cbv_router-0.1.0/README.md

@@ -0,0 +1,155 @@
+# fastapi-cbv-router
+
+[![CI](https://github.com/Chelovek760/fastapi-cbv/actions/workflows/ci.yml/badge.svg)](https://github.com/Chelovek760/fastapi-cbv/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-cbv-router.svg)](https://pypi.org/project/fastapi-cbv-router/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-cbv-router.svg)](https://pypi.org/project/fastapi-cbv-router/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Class-based views (CBV) for FastAPI routers — a small, maintained drop-in
+replacement for the unmaintained `fastapi_utils.cbv`. Works on modern FastAPI
+(tested from 0.115), and in particular survives FastAPI 0.137+, where
+`fastapi_utils.cbv` breaks.
+
+## Why
+
+`fastapi_utils.cbv` relied on `APIRouter.include_router` eagerly copying
+`APIRoute` objects into `router.routes`. FastAPI 0.137 made `include_router`
+lazy, which broke `fastapi_utils` whenever two `@cbv` decorators shared one
+router.
+
+`fastapi-cbv-router` rebuilds each endpoint through the router's public
+`add_api_route` / `add_api_websocket_route` API, which stays eager and
+delegates all route-state computation back to FastAPI. Route configuration is
+copied by introspecting `add_api_route`'s own parameters, so the package adapts
+to upstream FastAPI changes instead of hard-coding a kwarg list.
+
+## Features
+
+- One small decorator, `@cbv(router)` — no base classes or metaclasses required.
+- Share a single dependency instance (`self`) across every endpoint on a class.
+- Inject dependencies either as **class-level annotated attributes** or through a
+  **custom `__init__`** — use whichever fits your style.
+- Works with regular HTTP routes **and** WebSocket routes.
+- Preserves all route configuration (`status_code`, `response_model`,
+  `dependencies`, tags, …) and the router `prefix`.
+- Fully typed (`py.typed`), zero dependencies beyond FastAPI.
+
+## Requirements
+
+- **Python:** 3.13+
+- **FastAPI:** 0.115+ — continuously tested against the latest release, currently
+  **0.137.2**. The test suite specifically covers FastAPI 0.137+, where
+  `include_router` became lazy and broke `fastapi_utils.cbv`.
+
+## Install
+
+```bash
+pip install fastapi-cbv-router
+# or
+uv add fastapi-cbv-router
+```
+
+## Quickstart
+
+```python
+from fastapi import APIRouter, Depends, FastAPI
+from fastapi_cbv_router import cbv
+
+router = APIRouter(prefix="/items")
+
+
+def get_db() -> str:
+    return "db-connection"
+
+
+@cbv(router)
+class ItemsView:
+    db: str = Depends(get_db)
+
+    @router.get("/")
+    def list_items(self) -> dict:
+        return {"db": self.db, "items": []}
+
+    @router.post("/")
+    def create_item(self, name: str) -> dict:
+        return {"db": self.db, "created": name}
+
+
+app = FastAPI()
+app.include_router(router)
+```
+
+Class-level annotated attributes become keyword-only dependencies injected via
+`Depends(ItemsView)` and are available as `self.<attr>` in every endpoint.
+`ClassVar`-annotated attributes are treated as plain class constants and are not
+injected.
+
+## Dependency injection via `__init__`
+
+If you prefer constructor injection — for example to keep a clean abstract base
+and wire dependencies explicitly — define a custom `__init__`. Its parameters
+are resolved by FastAPI when the view is constructed, exactly like an endpoint's
+parameters:
+
+```python
+import abc
+from http import HTTPStatus
+
+from fastapi import APIRouter, Depends
+from fastapi_cbv_router import cbv
+
+router = APIRouter(prefix="/items", tags=["items"])
+
+
+def get_service() -> "ItemService":
+    ...
+
+
+class ItemApi(abc.ABC):
+    @abc.abstractmethod
+    async def get_item(self, item_id: int) -> dict: ...
+
+
+@cbv(router)
+class HttpItemApi(ItemApi):
+    def __init__(self, service: "ItemService" = Depends(get_service)) -> None:
+        self.service = service
+
+    @router.get("/{item_id}", status_code=HTTPStatus.OK)
+    async def get_item(self, item_id: int) -> dict:
+        return await self.service.fetch(item_id)
+```
+
+This pairs cleanly with DI containers such as
+[`dependency-injector`](https://python-dependency-injector.ets-labs.org/): use
+`Depends(Provide[...])` defaults on the `@inject`-decorated `__init__`.
+
+## WebSocket routes
+
+WebSocket endpoints are supported the same way as HTTP routes:
+
+```python
+from fastapi import APIRouter, WebSocket
+from fastapi_cbv_router import cbv
+
+router = APIRouter()
+
+
+@cbv(router)
+class ChatView:
+    @router.websocket("/ws")
+    async def chat(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        await websocket.send_text("hello")
+        await websocket.close()
+```
+
+## Scope
+
+Only the plain `@cbv(router)` form is supported (no `*urls` / `set_responses`
+helpers). This is intentional — it covers the common case with the smallest,
+most maintainable surface.
+
+## License
+
+MIT

fastapi_cbv_router-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[project]
+name = "fastapi-cbv-router"
+version = "0.1.0"
+description = "Class-based views for FastAPI routers — a maintained, FastAPI 0.137+ compatible drop-in for fastapi_utils.cbv."
+authors = [{ name = "Vladimir Klychnikov" }]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+keywords = ["fastapi", "cbv", "class-based-views", "router", "dependency-injection"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.115",
+]
+
+[project.urls]
+Homepage = "https://github.com/Chelovek760/fastapi-cbv"
+Repository = "https://github.com/Chelovek760/fastapi-cbv"
+Issues = "https://github.com/Chelovek760/fastapi-cbv/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.0",
+    "pytest-asyncio>=1.2.0",
+    "httpx>=0.27",
+    "ruff>=0.14",
+    "mypy>=2.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_cbv_router"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/**/*.py", "src/**/py.typed"]
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+target-version = "py313"
+output-format = "grouped"
+
+lint.task-tags = ["TODO"]
+
+lint.select = [
+    "E", "W", "F", "I", "D", "UP", "N", "YTT", "ANN", "S", "BLE", "FBT",
+    "B", "A", "C4", "T10", "EM", "ISC", "ICN", "T20", "PT", "Q", "RET",
+    "SIM", "TID", "DTZ", "ERA", "PD", "PGH",
+    "PLC", "PLE", "PLR", "PLW", "PIE", "RUF",
+]
+lint.ignore = [
+    "PLR0913", "ERA001", "ANN204", "C408", "B008", "RUF012",
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107",
+    "D200", "D212", "ANN401", "ICN001", "UP035", "BLE001", "S608",
+    "PLC1901", "S311", "S603", "S602", "S301", "A003", "D415",
+]
+
+lint.fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "PLR2004"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+relative-imports-order = "closest-to-furthest"
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["classmethod"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-annotations]
+suppress-dummy-args = true
+
+[tool.mypy]
+python_version = "3.13"
+disallow_untyped_defs = true
+ignore_missing_imports = true
+show_error_codes = true
+warn_unused_ignores = true
+check_untyped_defs = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"

fastapi_cbv_router-0.1.0/src/fastapi_cbv_router/__init__.py

@@ -0,0 +1,9 @@
+"""Class-based views for FastAPI routers.
+
+A maintained, FastAPI 0.137+ compatible drop-in replacement for
+``fastapi_utils.cbv``. Only the plain ``@cbv(router)`` form is supported.
+"""
+
+from fastapi_cbv_router.cbv import CBV_CLASS_KEY, cbv
+
+__all__ = ["CBV_CLASS_KEY", "cbv"]

fastapi_cbv_router-0.1.0/src/fastapi_cbv_router/cbv.py

@@ -0,0 +1,140 @@
+"""Class-based views for FastAPI routers.
+
+Drop-in replacement for the unmaintained ``fastapi_utils.cbv``. The original
+relied on ``APIRouter.include_router`` eagerly copying ``APIRoute`` objects into
+``router.routes``; FastAPI 0.137 made ``include_router`` lazy (it appends an
+internal ``_IncludedRouter`` placeholder), which broke ``fastapi_utils`` whenever
+two ``@cbv`` decorators shared one router.
+
+This implementation rebuilds each endpoint by re-adding it through the router's
+public ``add_api_route`` / ``add_api_websocket_route`` API, which stays eager and
+delegates all route-state computation back to FastAPI. Route configuration is
+copied by introspecting ``add_api_route``'s own parameters, so the helper adapts
+to upstream parameter changes instead of hard-coding a kwarg list.
+
+Only the plain ``@cbv(router)`` form is supported (no ``*urls`` / ``set_responses``
+helpers), which covers every call site in the codebase.
+"""
+
+import inspect
+from collections.abc import Callable
+from typing import Any, ClassVar, TypeVar, get_origin, get_type_hints
+
+from fastapi import APIRouter, Depends
+from fastapi.routing import APIRoute, APIWebSocketRoute
+
+T = TypeVar("T")
+
+CBV_CLASS_KEY = "__cbv_class__"
+
+
+def cbv(router: APIRouter) -> Callable[[type[T]], type[T]]:
+    """Convert the decorated class into a class-based view for ``router``.
+
+    Methods of the class registered as endpoints on ``router`` become router
+    endpoints whose first positional argument (``self``) is populated via
+    FastAPI dependency injection of an instance of the class.
+
+    Args:
+        router: The router whose endpoints defined on the class should be bound.
+
+    Returns:
+        A class decorator.
+    """
+
+    def decorator(cls: type[T]) -> type[T]:
+        _init_cbv(cls)
+        _register_endpoints(router, cls)
+        return cls
+
+    return decorator
+
+
+def _is_classvar(annotation: Any) -> bool:
+    return annotation is ClassVar or get_origin(annotation) is ClassVar
+
+
+def _init_cbv(cls: type[Any]) -> None:
+    """Make class-annotated dependencies injectable.
+
+    Rewrites ``__init__`` so that class-level annotated attributes are accepted as
+    keyword-only dependencies and stored on the instance, and updates
+    ``__signature__`` so FastAPI knows what to pass when resolving ``Depends(cls)``.
+    """
+    if getattr(cls, CBV_CLASS_KEY, False):
+        return  # Already initialized
+    old_init: Callable[..., Any] = cls.__init__
+    old_signature = inspect.signature(old_init)
+    old_parameters = list(old_signature.parameters.values())[1:]  # drop `self`
+    new_parameters = [
+        p for p in old_parameters if p.kind not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+    ]
+
+    dependency_names: list[str] = []
+    for name, hint in get_type_hints(cls).items():
+        if _is_classvar(hint):
+            continue
+        dependency_names.append(name)
+        new_parameters.append(
+            inspect.Parameter(
+                name=name,
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                annotation=hint,
+                default=getattr(cls, name, inspect.Parameter.empty),
+            )
+        )
+    new_signature = old_signature.replace(parameters=new_parameters)
+
+    def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+        for dep_name in dependency_names:
+            setattr(self, dep_name, kwargs.pop(dep_name))
+        old_init(self, *args, **kwargs)
+
+    cls.__signature__ = new_signature
+    cls.__init__ = new_init
+    cls.__cbv_class__ = True
+
+
+def _register_endpoints(router: APIRouter, cls: type[Any]) -> None:
+    functions = {func for _, func in inspect.getmembers(cls, inspect.isfunction)}
+    cbv_routes = [
+        route
+        for route in list(router.routes)
+        if isinstance(route, (APIRoute, APIWebSocketRoute)) and route.endpoint in functions
+    ]
+    prefix_length = len(router.prefix)
+    for route in cbv_routes:
+        _update_endpoint_signature(cls, route)
+        router.routes.remove(route)
+        path = route.path[prefix_length:]
+        name = f"{cls.__name__}.{route.name}"
+        if isinstance(route, APIWebSocketRoute):
+            router.add_api_websocket_route(path, route.endpoint, name=name, dependencies=route.dependencies)
+        else:
+            router.add_api_route(path, route.endpoint, **_copy_route_kwargs(router, route, name))
+
+
+def _copy_route_kwargs(router: APIRouter, route: APIRoute, name: str) -> dict[str, Any]:
+    """Reconstruct ``add_api_route`` kwargs from an existing route.
+
+    Pulls each parameter ``add_api_route`` accepts straight off the route object
+    (attribute names match parameter names), so new/removed FastAPI parameters are
+    handled automatically without editing this helper.
+    """
+    skip = {"self", "path", "endpoint", "name", "methods", "route_class_override"}
+    sig = inspect.signature(router.add_api_route)
+    kwargs: dict[str, Any] = {pname: getattr(route, pname) for pname in sig.parameters if pname not in skip}
+    kwargs["name"] = name
+    kwargs["methods"] = list(route.methods or [])
+    if "route_class_override" in sig.parameters:
+        kwargs["route_class_override"] = type(route)
+    return kwargs
+
+
+def _update_endpoint_signature(cls: type[Any], route: APIRoute | APIWebSocketRoute) -> None:
+    """Inject ``Depends(cls)`` as the default for the endpoint's ``self`` parameter."""
+    old_signature = inspect.signature(route.endpoint)
+    old_parameters = list(old_signature.parameters.values())
+    new_first = old_parameters[0].replace(default=Depends(cls))
+    new_parameters = [new_first] + [p.replace(kind=inspect.Parameter.KEYWORD_ONLY) for p in old_parameters[1:]]
+    route.endpoint.__signature__ = old_signature.replace(parameters=new_parameters)  # type: ignore[attr-defined]