svc-infra 0.1.706__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/api/fastapi/db/http.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Generic, Iterable, List, Optional, Sequence, TypeVar
+from collections.abc import Iterable, Sequence
+from typing import Any, Generic, TypeVar
 
 from fastapi import Query
 from pydantic import BaseModel
@@ -21,39 +22,37 @@ def dep_limit_offset(
 
 
 class OrderParams(BaseModel):
-    order_by: Optional[str] = None
+    order_by: str | None = None
 
 
 def dep_order(
-    order_by: Optional[str] = Query(
-        None, description="Comma-separated fields; '-' for DESC"
-    ),
+    order_by: str | None = Query(None, description="Comma-separated fields; '-' for DESC"),
 ) -> OrderParams:
     return OrderParams(order_by=order_by)
 
 
 class SearchParams(BaseModel):
-    q: Optional[str] = None
-    fields: Optional[str] = None
+    q: str | None = None
+    fields: str | None = None
 
 
 def dep_search(
-    q: Optional[str] = Query(None, description="Search query"),
-    fields: Optional[str] = Query(None, description="Comma-separated list of fields"),
+    q: str | None = Query(None, description="Search query"),
+    fields: str | None = Query(None, description="Comma-separated list of fields"),
 ) -> SearchParams:
     return SearchParams(q=q, fields=fields)
 
 
 class Page(BaseModel, Generic[T]):
     total: int
-    items: List[T]
+    items: list[T]
     limit: int
     offset: int
 
     @classmethod
     def from_items(
         cls, *, total: int, items: Sequence[T] | Iterable[T], limit: int, offset: int
-    ) -> "Page[T]":
+    ) -> Page[T]:
         return cls(total=total, items=list(items), limit=limit, offset=offset)
 
 

svc_infra/api/fastapi/db/nosql/mongo/add.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Sequence
 from contextlib import asynccontextmanager
-from typing import Sequence
 
 from bson import ObjectId
 from fastapi import FastAPI
@@ -30,9 +30,7 @@ def add_mongo_db_with_url(app: FastAPI, url: str, db_name: str) -> None:
             expected = get_mongo_dbname_from_env(required=False)
             db = await acquire_db()
             if expected and db.name != expected:
-                raise RuntimeError(
-                    f"Connected to Mongo DB '{db.name}', expected '{expected}'."
-                )
+                raise RuntimeError(f"Connected to Mongo DB '{db.name}', expected '{expected}'.")
             yield
         finally:
             await close_mongo()
@@ -49,9 +47,7 @@ def add_mongo_db(app: FastAPI, *, dsn_env: str = "MONGO_URL") -> None:
         expected = get_mongo_dbname_from_env(required=False)
         db = await acquire_db()
         if expected and db.name != expected:
-            raise RuntimeError(
-                f"Connected to Mongo DB '{db.name}', expected '{expected}'."
-            )
+            raise RuntimeError(f"Connected to Mongo DB '{db.name}', expected '{expected}'.")
         try:
             yield
         finally:
@@ -65,9 +61,7 @@ def add_mongo_health(
 ) -> None:
     if include_in_schema is None:
         include_in_schema = CURRENT_ENVIRONMENT == LOCAL_ENV
-    app.include_router(
-        make_mongo_health_router(prefix=prefix, include_in_schema=include_in_schema)
-    )
+    app.include_router(make_mongo_health_router(prefix=prefix, include_in_schema=include_in_schema))
 
 
 def add_mongo_resources(app: FastAPI, resources: Sequence[NoSqlResource]) -> None:
@@ -79,11 +73,7 @@ def add_mongo_resources(app: FastAPI, resources: Sequence[NoSqlResource]) -> Non
             soft_delete_field=resource.soft_delete_field,
             soft_delete_flag_field=resource.soft_delete_flag_field,
         )
-        svc = (
-            resource.service_factory(repo)
-            if resource.service_factory
-            else NoSqlService(repo)
-        )
+        svc = resource.service_factory(repo) if resource.service_factory else NoSqlService(repo)
 
         if resource.read_schema and resource.create_schema and resource.update_schema:
             Read, Create, Update = (

svc_infra/api/fastapi/db/nosql/mongo/crud_router.py

@@ -1,4 +1,5 @@
-from typing import Annotated, Any, Optional, Sequence, Type, cast
+from collections.abc import Sequence
+from typing import Annotated, Any, cast
 
 from fastapi import APIRouter, Body, Depends, HTTPException
 
@@ -27,7 +28,7 @@ DBDep = Annotated[AsyncIOMotorDatabase, Depends(acquire_db)]
 
 
 def _parse_sort(
-    order_spec: Optional[str], allowed_order_fields: Optional[list[str]]
+    order_spec: str | None, allowed_order_fields: list[str] | None
 ) -> list[tuple[str, int]]:
     if not order_spec:
         return []
@@ -43,18 +44,18 @@ def _parse_sort(
 def make_crud_router_plus_mongo(
     *,
     service: NoSqlService,
-    read_schema: Type[Any],
-    create_schema: Type[Any],
-    update_schema: Type[Any],
+    read_schema: type[Any],
+    create_schema: type[Any],
+    update_schema: type[Any],
     prefix: str,
     tags: list[str] | None = None,
-    search_fields: Optional[Sequence[str]] = None,
-    default_ordering: Optional[str] = None,
-    allowed_order_fields: Optional[list[str]] = None,
+    search_fields: Sequence[str] | None = None,
+    default_ordering: str | None = None,
+    allowed_order_fields: list[str] | None = None,
     mount_under_db_prefix: bool = True,
 ) -> APIRouter:
-    read_model = cast(Any, read_schema)
-    page_model = cast(Any, Page[read_schema])  # type: ignore[valid-type]
+    read_model = cast("Any", read_schema)
+    page_model = cast("Any", Page[read_schema])  # type: ignore[valid-type]
 
     router_prefix = ("/_mongo" + prefix) if mount_under_db_prefix else prefix
     router = public_router(
@@ -89,9 +90,7 @@ def make_crud_router_plus_mongo(
         else:
             items = await service.list(db, limit=lp.limit, offset=lp.offset, sort=sort)
             total = await service.count(db)
-        return Page[Any].from_items(
-            total=total, items=items, limit=lp.limit, offset=lp.offset
-        )
+        return Page[Any].from_items(total=total, items=items, limit=lp.limit, offset=lp.offset)
 
     # GET by id
     @router.get(
@@ -113,7 +112,7 @@ def make_crud_router_plus_mongo(
         description=f"Create item in {prefix} collection",
     )
     async def create_item(db: DBDep, payload: create_schema = Body(...)):  # type: ignore[valid-type]
-        data = cast(Any, payload).model_dump(exclude_unset=True)
+        data = cast("Any", payload).model_dump(exclude_unset=True)
         return await service.create(db, data)
 
     # UPDATE
@@ -127,7 +126,7 @@ def make_crud_router_plus_mongo(
         item_id: Any,
         payload: update_schema = Body(...),  # type: ignore[valid-type]
     ):
-        data = cast(Any, payload).model_dump(exclude_unset=True)
+        data = cast("Any", payload).model_dump(exclude_unset=True)
         row = await service.update(db, item_id, data)
         if not row:
             raise HTTPException(404, "Not found")

svc_infra/api/fastapi/db/sql/add.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Sequence
 from contextlib import asynccontextmanager
-from typing import Optional, Sequence
 
 from fastapi import FastAPI
 
@@ -17,9 +17,7 @@ from .session import dispose_session, initialize_session
 
 def add_sql_resources(app: FastAPI, resources: Sequence[SqlResource]) -> None:
     for r in resources:
-        repo = SqlRepository(
-            model=r.model, id_attr=r.id_attr, soft_delete=r.soft_delete
-        )
+        repo = SqlRepository(model=r.model, id_attr=r.id_attr, soft_delete=r.soft_delete)
 
         if r.service_factory:
             svc = r.service_factory(repo)
@@ -73,9 +71,7 @@ def add_sql_resources(app: FastAPI, resources: Sequence[SqlResource]) -> None:
         app.include_router(router)
 
 
-def add_sql_db(
-    app: FastAPI, *, url: Optional[str] = None, dsn_env: str = "SQL_URL"
-) -> None:
+def add_sql_db(app: FastAPI, *, url: str | None = None, dsn_env: str = "SQL_URL") -> None:
     """Configure DB lifecycle for the app (either explicit URL or from env).
 
     This preserves any existing lifespan context (like user-defined lifespans)
@@ -106,9 +102,7 @@ def add_sql_db(
     async def lifespan_from_env(_app: FastAPI):
         env_url = os.getenv(dsn_env)
         if not env_url:
-            raise RuntimeError(
-                f"Missing environment variable {dsn_env} for database URL"
-            )
+            raise RuntimeError(f"Missing environment variable {dsn_env} for database URL")
         initialize_session(env_url)
         try:
             if existing_lifespan is not None:
@@ -125,16 +119,14 @@ def add_sql_db(
 def add_sql_health(
     app: FastAPI, *, prefix: str = "/_sql/health", include_in_schema: bool = False
 ) -> None:
-    app.include_router(
-        _make_db_health_router(prefix=prefix, include_in_schema=include_in_schema)
-    )
+    app.include_router(_make_db_health_router(prefix=prefix, include_in_schema=include_in_schema))
 
 
 def setup_sql(
     app: FastAPI,
     resources: Sequence[SqlResource],
     *,
-    url: Optional[str] = None,
+    url: str | None = None,
     dsn_env: str = "SQL_URL",
     include_health: bool = True,
     health_prefix: str = "/_sql/health",

svc_infra/api/fastapi/db/sql/crud_router.py

@@ -1,4 +1,5 @@
-from typing import Annotated, Any, Callable, Optional, Sequence, Type, TypeVar, cast
+from collections.abc import Callable, Sequence
+from typing import Annotated, Any, TypeVar, cast
 
 from fastapi import APIRouter, Body, Depends, HTTPException
 from pydantic import BaseModel
@@ -29,14 +30,14 @@ def make_crud_router_plus_sql(
     *,
     model: type[Any],
     service: SqlService,
-    read_schema: Type[ReadModel],
-    create_schema: Type[CreateModel],
-    update_schema: Type[UpdateModel],
+    read_schema: type[ReadModel],
+    create_schema: type[CreateModel],
+    update_schema: type[UpdateModel],
     prefix: str,
     tags: list[str] | None = None,
-    search_fields: Optional[Sequence[str]] = None,
-    default_ordering: Optional[str] = None,
-    allowed_order_fields: Optional[list[str]] = None,
+    search_fields: Sequence[str] | None = None,
+    default_ordering: str | None = None,
+    allowed_order_fields: list[str] | None = None,
     mount_under_db_prefix: bool = True,
 ) -> APIRouter:
     router_prefix = ("/_sql" + prefix) if mount_under_db_prefix else prefix
@@ -58,7 +59,7 @@ def make_crud_router_plus_sql(
                 return v
         return v
 
-    def _parse_ordering_to_fields(order_spec: Optional[str]) -> list[str]:
+    def _parse_ordering_to_fields(order_spec: str | None) -> list[str]:
         if not order_spec:
             return []
         pieces = [p.strip() for p in order_spec.split(",") if p.strip()]
@@ -102,13 +103,9 @@ def make_crud_router_plus_sql(
             )
             total = await service.count_filtered(session, q=sp.q, fields=fields)
         else:
-            items = await service.list(
-                session, limit=lp.limit, offset=lp.offset, order_by=order_by
-            )
+            items = await service.list(session, limit=lp.limit, offset=lp.offset, order_by=order_by)
             total = await service.count(session)
-        return Page[Any].from_items(
-            total=total, items=items, limit=lp.limit, offset=lp.offset
-        )
+        return Page[Any].from_items(total=total, items=items, limit=lp.limit, offset=lp.offset)
 
     # -------- GET by id --------
     @router.get(
@@ -134,7 +131,7 @@ def make_crud_router_plus_sql(
         payload: create_schema = Body(...),  # type: ignore[valid-type]
     ):
         if isinstance(payload, BaseModel):
-            data = cast(BaseModel, payload).model_dump(exclude_unset=True)
+            data = cast("BaseModel", payload).model_dump(exclude_unset=True)
         elif isinstance(payload, dict):
             data = payload
         else:
@@ -153,7 +150,7 @@ def make_crud_router_plus_sql(
         payload: update_schema = Body(...),  # type: ignore[valid-type]
     ):
         if isinstance(payload, BaseModel):
-            data = cast(BaseModel, payload).model_dump(exclude_unset=True)
+            data = cast("BaseModel", payload).model_dump(exclude_unset=True)
         elif isinstance(payload, dict):
             data = payload
         else:
@@ -181,18 +178,16 @@ def make_crud_router_plus_sql(
 def make_tenant_crud_router_plus_sql(
     *,
     model: type[Any],
-    service_factory: Callable[
-        [], Any
-    ],  # factory that returns a SqlService (will be wrapped)
-    read_schema: Type[ReadModel],
-    create_schema: Type[CreateModel],
-    update_schema: Type[UpdateModel],
+    service_factory: Callable[[], Any],  # factory that returns a SqlService (will be wrapped)
+    read_schema: type[ReadModel],
+    create_schema: type[CreateModel],
+    update_schema: type[UpdateModel],
     prefix: str,
     tenant_field: str = "tenant_id",
     tags: list[str] | None = None,
-    search_fields: Optional[Sequence[str]] = None,
-    default_ordering: Optional[str] = None,
-    allowed_order_fields: Optional[list[str]] = None,
+    search_fields: Sequence[str] | None = None,
+    default_ordering: str | None = None,
+    allowed_order_fields: list[str] | None = None,
     mount_under_db_prefix: bool = True,
 ) -> APIRouter:
     """Like make_crud_router_plus_sql, but requires TenantId and scopes all operations."""
@@ -206,9 +201,7 @@ def make_tenant_crud_router_plus_sql(
     # Evaluate the base service once to preserve in-memory state across requests in tests/local.
     # Consumers may pass either an instance or a zero-arg factory function.
     try:
-        _base_instance = (
-            service_factory() if callable(service_factory) else service_factory
-        )
+        _base_instance = service_factory() if callable(service_factory) else service_factory
     except TypeError:
         # If the callable requires args, assume it's already an instance
         _base_instance = service_factory
@@ -224,7 +217,7 @@ def make_tenant_crud_router_plus_sql(
                 return v
         return v
 
-    def _parse_ordering_to_fields(order_spec: Optional[str]) -> list[str]:
+    def _parse_ordering_to_fields(order_spec: str | None) -> list[str]:
         if not order_spec:
             return []
         pieces = [p.strip() for p in order_spec.split(",") if p.strip()]
@@ -239,9 +232,7 @@ def make_tenant_crud_router_plus_sql(
     # create per-request service with tenant scoping
     async def _svc(session: SqlSessionDep, tenant_id: TenantId):
         repo_or_service = getattr(_base_instance, "repo", _base_instance)
-        svc: Any = TenantSqlService(
-            repo_or_service, tenant_id=tenant_id, tenant_field=tenant_field
-        )
+        svc: Any = TenantSqlService(repo_or_service, tenant_id=tenant_id, tenant_field=tenant_field)
         return svc
 
     @router.get("", response_model=Page[read_schema])  # type: ignore[valid-type]
@@ -272,13 +263,9 @@ def make_tenant_crud_router_plus_sql(
             )
             total = await svc.count_filtered(session, q=sp.q, fields=fields)
         else:
-            items = await svc.list(
-                session, limit=lp.limit, offset=lp.offset, order_by=order_by
-            )
+            items = await svc.list(session, limit=lp.limit, offset=lp.offset, order_by=order_by)
             total = await svc.count(session)
-        return Page[Any].from_items(
-            total=total, items=items, limit=lp.limit, offset=lp.offset
-        )
+        return Page[Any].from_items(total=total, items=items, limit=lp.limit, offset=lp.offset)
 
     @router.get("/{item_id}", response_model=read_schema)
     async def get_item(item_id: Any, session: SqlSessionDep, tenant_id: TenantId):
@@ -296,7 +283,7 @@ def make_tenant_crud_router_plus_sql(
     ):
         svc = await _svc(session, tenant_id)
         if isinstance(payload, BaseModel):
-            data = cast(BaseModel, payload).model_dump(exclude_unset=True)
+            data = cast("BaseModel", payload).model_dump(exclude_unset=True)
         elif isinstance(payload, dict):
             data = payload
         else:
@@ -312,7 +299,7 @@ def make_tenant_crud_router_plus_sql(
     ):
         svc = await _svc(session, tenant_id)
         if isinstance(payload, BaseModel):
-            data = cast(BaseModel, payload).model_dump(exclude_unset=True)
+            data = cast("BaseModel", payload).model_dump(exclude_unset=True)
         elif isinstance(payload, dict):
             data = payload
         else:

svc_infra/api/fastapi/db/sql/health.py

@@ -14,9 +14,7 @@ def _make_db_health_router(
     include_in_schema: bool = False,
 ) -> APIRouter:
     """Internal factory for the DB health router."""
-    router = public_router(
-        prefix=prefix, tags=["health"], include_in_schema=include_in_schema
-    )
+    router = public_router(prefix=prefix, tags=["health"], include_in_schema=include_in_schema)
 
     @router.get("", status_code=status.HTTP_200_OK)
     async def db_health(session: SqlSessionDep) -> Response:

svc_infra/api/fastapi/db/sql/session.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 import logging
 import os
-from typing import Annotated, AsyncIterator, Tuple
+from collections.abc import AsyncIterator
+from typing import Annotated
 
 from fastapi import Depends
 from sqlalchemy import text
@@ -23,7 +24,7 @@ _SessionLocal: async_sessionmaker[AsyncSession] | None = None
 
 def _init_engine_and_session(
     url: str,
-) -> Tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
+) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
     async_url = _coerce_to_async_url(url)
     if async_url != url:
         logger.info(
@@ -63,9 +64,7 @@ async def get_session() -> AsyncIterator[AsyncSession]:
                 if ms > 0:
                     try:
                         # SET LOCAL applies for the duration of the current transaction only
-                        await session.execute(
-                            text("SET LOCAL statement_timeout = :ms"), {"ms": ms}
-                        )
+                        await session.execute(text("SET LOCAL statement_timeout = :ms"), {"ms": ms})
                     except Exception:
                         # Non-PG dialects (e.g., SQLite) will error; ignore silently
                         pass

svc_infra/api/fastapi/db/sql/users.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, AsyncIterator, Callable, Tuple
+from collections.abc import AsyncIterator, Callable
+from typing import Any
 from uuid import UUID
 
 from fastapi import Depends
@@ -30,7 +31,7 @@ def get_fastapi_users(
     user_schema_update: Any,
     *,
     public_auth_prefix: str = "/auth",
-) -> Tuple[
+) -> tuple[
     FastAPIUsers,
     AuthenticationBackend,
     DualAPIRouter,
@@ -51,9 +52,7 @@ def get_fastapi_users(
 
         async def on_after_register(self, user: Any, request=None):
             st = get_auth_settings()
-            if CURRENT_ENVIRONMENT in (DEV_ENV, LOCAL_ENV) and bool(
-                st.auto_verify_in_dev
-            ):
+            if CURRENT_ENVIRONMENT in (DEV_ENV, LOCAL_ENV) and bool(st.auto_verify_in_dev):
                 await self.user_db.update(user, {"is_verified": True})
                 return
             await self.request_verify(user, request)
@@ -62,10 +61,10 @@ def get_fastapi_users(
             verify_url = f"{public_auth_prefix}/verify?token={token}"
             sender = get_sender()
             sender.send(
-                to=getattr(user, "email"),
+                to=user.email,
                 subject="Verify your account",
                 html_body=f"""
-                    <p>Hi {getattr(user, 'full_name', '') or 'there'},</p>
+                    <p>Hi {getattr(user, "full_name", "") or "there"},</p>
                     <p>Click to verify your account:</p>
                     <p><a href="{verify_url}">{verify_url}</a></p>
                 """,
@@ -75,7 +74,7 @@ def get_fastapi_users(
             reset_url = f"{public_auth_prefix}/reset-password?token={token}"
             sender = get_sender()
             sender.send(
-                to=getattr(user, "email"),
+                to=user.email,
                 subject="Reset your password",
                 html_body=f"""
                     <p>We received a request to reset your password.</p>
@@ -116,9 +115,7 @@ def get_fastapi_users(
                 old_secrets=old,
                 token_audience=audience,
             )
-        return JWTStrategy(
-            secret=secret, lifetime_seconds=lifetime, token_audience=audience
-        )
+        return JWTStrategy(secret=secret, lifetime_seconds=lifetime, token_audience=audience)
 
     bearer_transport = BearerTransport(tokenUrl=auth_login_path)
     auth_backend = AuthenticationBackend(

svc_infra/api/fastapi/dependencies/ratelimit.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 import time
-from typing import Callable, Optional
+from collections.abc import Callable
 
 from fastapi import HTTPException
 from starlette.requests import Request
@@ -30,9 +30,7 @@ class RateLimiter:
         limit: int,
         window: int = 60,
         key_fn: Callable = lambda r: "global",
-        limit_resolver: Optional[
-            Callable[[Request, Optional[str]], Optional[int]]
-        ] = None,
+        limit_resolver: Callable[[Request, str | None], int | None] | None = None,
         scope_by_tenant: bool = False,
         store: RateLimitStore | None = None,
     ):
@@ -65,7 +63,7 @@ class RateLimiter:
             except Exception:
                 eff_limit = self.limit
 
-        count, store_limit, reset = self.store.incr(str(key), self.window)
+        count, _store_limit, reset = self.store.incr(str(key), self.window)
         if count > eff_limit:
             retry = max(0, reset - int(time.time()))
             try:
@@ -87,7 +85,7 @@ def rate_limiter(
     limit: int,
     window: int = 60,
     key_fn: Callable = lambda r: "global",
-    limit_resolver: Optional[Callable[[Request, Optional[str]], Optional[int]]] = None,
+    limit_resolver: Callable[[Request, str | None], int | None] | None = None,
     scope_by_tenant: bool = False,
     store: RateLimitStore | None = None,
 ):

svc_infra/api/fastapi/docs/add.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import json
+from collections.abc import Callable
 from pathlib import Path
-from typing import Callable, Optional
 
 from fastapi import FastAPI, Request
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
@@ -18,7 +18,7 @@ def add_docs(
     redoc_url: str = "/redoc",
     swagger_url: str = "/docs",
     openapi_url: str = "/openapi.json",
-    export_openapi_to: Optional[str] = None,
+    export_openapi_to: str | None = None,
     # Landing page options
     landing_url: str = "/",
     include_landing: bool = True,
@@ -29,15 +29,13 @@ def add_docs(
     """
 
     # OpenAPI JSON route
-    async def openapi_handler() -> JSONResponse:  # noqa: ANN201
+    async def openapi_handler() -> JSONResponse:
         return JSONResponse(app.openapi())
 
-    app.add_api_route(
-        openapi_url, openapi_handler, methods=["GET"], include_in_schema=False
-    )
+    app.add_api_route(openapi_url, openapi_handler, methods=["GET"], include_in_schema=False)
 
     # Swagger UI route
-    async def swagger_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+    async def swagger_ui(request: Request) -> HTMLResponse:
         resp = get_swagger_ui_html(openapi_url=openapi_url, title="API Docs")
         theme = request.query_params.get("theme")
         if theme == "dark":
@@ -47,7 +45,7 @@ def add_docs(
     app.add_api_route(swagger_url, swagger_ui, methods=["GET"], include_in_schema=False)
 
     # Redoc route
-    async def redoc_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+    async def redoc_ui(request: Request) -> HTMLResponse:
         resp = get_redoc_html(openapi_url=openapi_url, title="API ReDoc")
         theme = request.query_params.get("theme")
         if theme == "dark":
@@ -80,15 +78,13 @@ def add_docs(
         if landing_path in existing_paths:
             landing_path = "/_docs"
 
-        async def _landing() -> HTMLResponse:  # noqa: ANN201
+        async def _landing() -> HTMLResponse:
             cards: list[CardSpec] = []
             # Root docs card using the provided paths
             cards.append(
                 CardSpec(
                     tag="",
-                    docs=DocTargets(
-                        swagger=swagger_url, redoc=redoc_url, openapi_json=openapi_url
-                    ),
+                    docs=DocTargets(swagger=swagger_url, redoc=redoc_url, openapi_json=openapi_url),
                 )
             )
             # Scoped docs (if any were registered via add_prefixed_docs)
@@ -96,9 +92,7 @@ def add_docs(
                 cards.append(
                     CardSpec(
                         tag=scope.strip("/"),
-                        docs=DocTargets(
-                            swagger=swagger, redoc=redoc, openapi_json=openapi_json
-                        ),
+                        docs=DocTargets(swagger=swagger, redoc=redoc, openapi_json=openapi_json),
                     )
                 )
             html = render_index_html(
@@ -106,9 +100,7 @@ def add_docs(
             )
             return HTMLResponse(html)
 
-        app.add_api_route(
-            landing_path, _landing, methods=["GET"], include_in_schema=False
-        )
+        app.add_api_route(landing_path, _landing, methods=["GET"], include_in_schema=False)
 
 
 def _with_dark_mode(resp: HTMLResponse) -> HTMLResponse:
@@ -130,9 +122,7 @@ def _with_dark_mode(resp: HTMLResponse) -> HTMLResponse:
         body = body.replace("</head>", f"<style>\n{css}\n</style></head>", 1)
     # add class to body to allow stronger selectors
     body = body.replace("<body>", '<body class="dark">', 1)
-    return HTMLResponse(
-        content=body, status_code=resp.status_code, headers=dict(resp.headers)
-    )
+    return HTMLResponse(content=body, status_code=resp.status_code, headers=dict(resp.headers))
 
 
 _DARK_CSS = """
@@ -147,7 +137,7 @@ a { color: #62aef7; }
 def add_sdk_generation_stub(
     app: FastAPI,
     *,
-    on_generate: Optional[Callable[[], None]] = None,
+    on_generate: Callable[[], None] | None = None,
     openapi_path: str = "/openapi.json",
 ) -> None:
     """Hook to add an SDK generation stub.
@@ -163,7 +153,7 @@ def add_sdk_generation_stub(
     router = public_router(prefix="/_docs", include_in_schema=False)
 
     @router.post("/generate-sdk")
-    async def _generate() -> dict:  # noqa: ANN201
+    async def _generate() -> dict:
         on_generate()
         return {"status": "ok"}