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

svc_infra/db/sql/uniq.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Iterable, List, Optional, Tuple, Type
+from collections.abc import Iterable
+from typing import Any
 
 from sqlalchemy import Index, func
 
@@ -9,13 +10,13 @@ from svc_infra.db.utils import as_tuple as _as_tuple
 
 
 def make_unique_sql_indexes(
-    model: Type[Any],
+    model: type[Any],
     *,
     unique_cs: Iterable[KeySpec] = (),
     unique_ci: Iterable[KeySpec] = (),
-    tenant_field: Optional[str] = None,
+    tenant_field: str | None = None,
     name_prefix: str = "uq",
-) -> List[Index]:
+) -> list[Index]:
     """Return SQLAlchemy Index objects that enforce uniqueness.
 
     - unique_cs: case-sensitive unique specs
@@ -26,12 +27,12 @@ def make_unique_sql_indexes(
 
     Declare right after your model class; Alembic or metadata.create_all will pick them up.
     """
-    idxs: List[Index] = []
+    idxs: list[Index] = []
 
     def _col(name: str):
         return getattr(model, name)
 
-    def _to_sa_cols(spec: Tuple[str, ...], *, ci: bool):
+    def _to_sa_cols(spec: tuple[str, ...], *, ci: bool):
         cols = []
         for cname in spec:
             c = _col(cname)
@@ -40,7 +41,7 @@ def make_unique_sql_indexes(
 
     tenant_col = _col(tenant_field) if tenant_field else None
 
-    def _name(ci: bool, spec: Tuple[str, ...], null_bucket: Optional[str] = None):
+    def _name(ci: bool, spec: tuple[str, ...], null_bucket: str | None = None):
         parts = [name_prefix, model.__tablename__]
         if tenant_field:
             parts.append(tenant_field)

svc_infra/db/sql/uniq_hooks.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any
 
 from fastapi import HTTPException
 from sqlalchemy import func
@@ -11,14 +12,14 @@ from svc_infra.db.sql.service_with_hooks import SqlServiceWithHooks
 
 from .uniq import _as_tuple
 
-ColumnSpec = Union[str, Sequence[str]]
+ColumnSpec = str | Sequence[str]
 
 
-def _all_present(data: Dict[str, Any], fields: Sequence[str]) -> bool:
+def _all_present(data: dict[str, Any], fields: Sequence[str]) -> bool:
     return all(f in data for f in fields)
 
 
-def _nice_label(fields: Sequence[str], data: Dict[str, Any]) -> str:
+def _nice_label(fields: Sequence[str], data: dict[str, Any]) -> str:
     if len(fields) == 1:
         f = fields[0]
         return f"{f}={data.get(f)!r}"
@@ -30,10 +31,10 @@ def dedupe_sql_service(
     *,
     unique_cs: Iterable[ColumnSpec] = (),
     unique_ci: Iterable[ColumnSpec] = (),
-    tenant_field: Optional[str] = None,
-    messages: Optional[dict[Tuple[str, ...], str]] = None,
-    pre_create: Optional[Callable[[dict], dict]] = None,
-    pre_update: Optional[Callable[[dict], dict]] = None,
+    tenant_field: str | None = None,
+    messages: dict[tuple[str, ...], str] | None = None,
+    pre_create: Callable[[dict], dict] | None = None,
+    pre_update: Callable[[dict], dict] | None = None,
 ):
     """
     Build a Service subclass with uniqueness pre-checks:
@@ -46,9 +47,9 @@ def dedupe_sql_service(
     messages = messages or {}
 
     def _build_where(
-        spec: Tuple[str, ...], data: Dict[str, Any], *, ci: bool, exclude_id: Any | None
+        spec: tuple[str, ...], data: dict[str, Any], *, ci: bool, exclude_id: Any | None
     ):
-        clauses: List[Any] = []
+        clauses: list[Any] = []
         for col_name in spec:
             col = getattr(Model, col_name)
             val = data.get(col_name)
@@ -73,9 +74,7 @@ def dedupe_sql_service(
 
         return clauses
 
-    async def _precheck(
-        session, data: Dict[str, Any], *, exclude_id: Any | None
-    ) -> None:
+    async def _precheck(session, data: dict[str, Any], *, exclude_id: Any | None) -> None:
         # Check CI specs first to catch the broadest conflicts, then CS.
         for ci, spec_list in ((True, unique_ci), (False, unique_cs)):
             for spec in spec_list:
@@ -99,9 +98,7 @@ def dedupe_sql_service(
                 return await self.repo.create(session, data)
             except IntegrityError as e:
                 # Race fallback: let DB constraint be the last line of defense.
-                raise HTTPException(
-                    status_code=409, detail="Record already exists."
-                ) from e
+                raise HTTPException(status_code=409, detail="Record already exists.") from e
 
         async def update(self, session, id_value, data):
             data = await self.pre_update(data)
@@ -109,8 +106,6 @@ def dedupe_sql_service(
             try:
                 return await self.repo.update(session, id_value, data)
             except IntegrityError as e:
-                raise HTTPException(
-                    status_code=409, detail="Record already exists."
-                ) from e
+                raise HTTPException(status_code=409, detail="Record already exists.") from e
 
     return _Svc(repo, pre_create=pre_create, pre_update=pre_update)

svc_infra/db/sql/utils.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import asyncio
 import os
+from collections.abc import Sequence
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional, Sequence, Set, Union, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from alembic.config import Config
 from dotenv import load_dotenv
@@ -34,7 +35,7 @@ except Exception:  # pragma: no cover - optional env
 
 def prepare_process_env(
     project_root: Path | str,
-    discover_packages: Optional[Sequence[str]] = None,
+    discover_packages: Sequence[str] | None = None,
 ) -> None:
     """
     Prepare process environment so Alembic can import the project cleanly.
@@ -60,7 +61,7 @@ def prepare_process_env(
         os.environ["ALEMBIC_DISCOVER_PACKAGES"] = ",".join(discover_packages)
 
 
-def _read_secret_from_file(path: str) -> Optional[str]:
+def _read_secret_from_file(path: str) -> str | None:
     """Return file contents if path exists, else None."""
     try:
         p = Path(path)
@@ -71,7 +72,7 @@ def _read_secret_from_file(path: str) -> Optional[str]:
     return None
 
 
-def _compose_url_from_parts() -> Optional[str]:
+def _compose_url_from_parts() -> str | None:
     """
     Compose a SQLAlchemy URL from component env vars.
     Supports private DNS hostnames and Unix sockets.
@@ -83,9 +84,7 @@ def _compose_url_from_parts() -> Optional[str]:
       DB_PARAMS (raw query string like 'sslmode=require&connect_timeout=5')
     """
     dialect = os.getenv("DB_DIALECT", "").strip() or "postgresql"
-    driver = os.getenv(
-        "DB_DRIVER", ""
-    ).strip()  # e.g. asyncpg, psycopg, pymysql, aiosqlite
+    driver = os.getenv("DB_DRIVER", "").strip()  # e.g. asyncpg, psycopg, pymysql, aiosqlite
     host = os.getenv("DB_HOST", "").strip() or None
     port = os.getenv("DB_PORT", "").strip() or None
     db = os.getenv("DB_NAME", "").strip() or None
@@ -151,7 +150,7 @@ def get_database_url_from_env(
     required: bool = True,
     env_vars: Sequence[str] = DEFAULT_DB_ENV_VARS,
     normalize: bool = True,
-) -> Optional[str]:
+) -> str | None:
     """
     Resolve the database connection string, with support for:
       - Primary env vars (in order): DEFAULT_DB_ENV_VARS
@@ -263,7 +262,7 @@ def is_async_url(url: URL | str) -> bool:
     return bool(ASYNC_DRIVER_HINT.search(dn))
 
 
-def with_database(url: URL | str, database: Optional[str]) -> URL:
+def with_database(url: URL | str, database: str | None) -> URL:
     """Return a copy of URL with the database name replaced.
 
     Works for most dialects. For SQLite/DuckDB file URLs, `database` is the file path.
@@ -376,17 +375,11 @@ def _ensure_ssl_default(u: URL) -> URL:
     driver = (u.drivername or "").lower()
 
     # If any SSL hint already present, do nothing
-    if any(
-        k in u.query for k in ("sslmode", "ssl", "sslrootcert", "sslcert", "sslkey")
-    ):
+    if any(k in u.query for k in ("sslmode", "ssl", "sslrootcert", "sslcert", "sslkey")):
         return u
 
     # Allow env override; support both common spellings
-    mode_env = (
-        os.getenv("DB_SSLMODE_DEFAULT")
-        or os.getenv("PGSSLMODE")
-        or os.getenv("PGSSL_MODE")
-    )
+    mode_env = os.getenv("DB_SSLMODE_DEFAULT") or os.getenv("PGSSLMODE") or os.getenv("PGSSL_MODE")
     mode = (mode_env or "").strip()
 
     if "+asyncpg" in driver:
@@ -403,9 +396,7 @@ def _ensure_ssl_default_async(u: URL) -> URL:
     backend = (u.get_backend_name() or "").lower()
     if backend in ("postgresql", "postgres"):
         # asyncpg prefers 'ssl=true' via SQLAlchemy param; if already present, keep it
-        if any(
-            k in u.query for k in ("ssl", "sslmode", "sslrootcert", "sslcert", "sslkey")
-        ):
+        if any(k in u.query for k in ("ssl", "sslmode", "sslrootcert", "sslcert", "sslkey")):
             return u
         return u.set(query={**u.query, "ssl": "true"})
     return u
@@ -420,9 +411,7 @@ def _certifi_ca() -> str | None:
         return None
 
 
-def build_engine(
-    url: URL | str, echo: bool = False
-) -> Union[SyncEngine, AsyncEngineType]:
+def build_engine(url: URL | str, echo: bool = False) -> SyncEngine | AsyncEngineType:
     u = make_url(url) if isinstance(url, str) else url
 
     # Keep your existing PG helpers
@@ -445,9 +434,7 @@ def build_engine(
             # asyncpg doesn't accept sslmode or ssl=true in query params
             # Remove these and set ssl='require' in connect_args
             if "ssl" in u.query or "sslmode" in u.query:
-                new_query = {
-                    k: v for k, v in u.query.items() if k not in ("ssl", "sslmode")
-                }
+                new_query = {k: v for k, v in u.query.items() if k not in ("ssl", "sslmode")}
                 u = u.set(query=new_query)
             # Set ssl in connect_args - 'require' is safest for hosted databases
             connect_args["ssl"] = "require"
@@ -461,11 +448,7 @@ def build_engine(
                 import ssl
 
                 ca = _certifi_ca()
-                ctx = (
-                    ssl.create_default_context(cafile=ca)
-                    if ca
-                    else ssl.create_default_context()
-                )
+                ctx = ssl.create_default_context(cafile=ca) if ca else ssl.create_default_context()
                 # if your host uses a public CA, verification works;
                 # if not, you can relax verification (not recommended):
                 #   ctx.check_hostname = False
@@ -482,9 +465,7 @@ def build_engine(
     # ----------------- SYNC -----------------
     u = _coerce_sync_driver(u)
     if _create_engine is None:
-        raise RuntimeError(
-            "SQLAlchemy create_engine is not available in this environment."
-        )
+        raise RuntimeError("SQLAlchemy create_engine is not available in this environment.")
 
     dn = (u.drivername or "").lower()
 
@@ -617,9 +598,7 @@ async def _mysql_create_database_async(url: URL) -> None:
     engine: AsyncEngineType = build_engine(base_url)  # type: ignore[assignment]
     async with engine.begin() as conn:
         exists = await conn.scalar(
-            text(
-                "SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = :name"
-            ),
+            text("SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = :name"),
             {"name": target_db},
         )
         if not exists:
@@ -636,9 +615,7 @@ def _mysql_create_database_sync(url: URL) -> None:
     engine: SyncEngine = build_engine(base_url)  # type: ignore[assignment]
     with engine.begin() as conn:
         exists = conn.scalar(
-            text(
-                "SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = :name"
-            ),
+            text("SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = :name"),
             {"name": target_db},
         )
         if not exists:
@@ -865,7 +842,7 @@ def ensure_database_exists(url: URL | str) -> None:
     try:
         eng = build_engine(u)
         if is_async_url(u):
-            async_eng = cast(AsyncEngineType, eng)
+            async_eng = cast("AsyncEngineType", eng)
 
             async def _ping_and_dispose():
                 async with async_eng.begin() as conn:
@@ -874,7 +851,7 @@ def ensure_database_exists(url: URL | str) -> None:
 
             asyncio.run(_ping_and_dispose())
         else:
-            sync_eng = cast(SyncEngine, eng)
+            sync_eng = cast("SyncEngine", eng)
             with sync_eng.begin() as conn:
                 conn.execute(text("SELECT 1"))
             sync_eng.dispose()
@@ -894,7 +871,7 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
         return
     script_location = Path(script_location_str)
     versions_dir = script_location / "versions"
-    local_ids: Set[str] = set()
+    local_ids: set[str] = set()
     if versions_dir.exists():
         for p in versions_dir.glob("*.py"):
             try:
@@ -912,7 +889,7 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
     if is_async_url(url_obj):
 
         async def _run() -> None:
-            eng = cast(AsyncEngineType, build_engine(url_obj))
+            eng = cast("AsyncEngineType", build_engine(url_obj))
             try:
                 async with eng.begin() as conn:
                     # Do sync-y inspector / SQL via run_sync
@@ -927,9 +904,7 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
                         )
                         missing = any((ver not in local_ids) for (ver,) in rows)
                         if missing:
-                            sync_conn.execute(
-                                text("DROP TABLE IF EXISTS alembic_version")
-                            )
+                            sync_conn.execute(text("DROP TABLE IF EXISTS alembic_version"))
 
                     await conn.run_sync(_check_and_maybe_drop)
             finally:
@@ -937,17 +912,13 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
 
         asyncio.run(_run())
     else:
-        eng = cast(SyncEngine, build_engine(url_obj))
+        eng = cast("SyncEngine", build_engine(url_obj))
         try:
             with eng.begin() as c:
                 insp = inspect(c)
                 if not insp.has_table("alembic_version"):
                     return
-                rows = list(
-                    c.execute(
-                        text("SELECT version_num FROM alembic_version")
-                    ).fetchall()
-                )
+                rows = list(c.execute(text("SELECT version_num FROM alembic_version")).fetchall())
                 missing = any((ver not in local_ids) for (ver,) in rows)
                 if missing:
                     c.execute(text("DROP TABLE IF EXISTS alembic_version"))

svc_infra/db/utils.py

@@ -1,10 +1,10 @@
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Sequence, Tuple, Union
 
-KeySpec = Union[str, Sequence[str]]
+KeySpec = str | Sequence[str]
 
 
-def as_tuple(spec: KeySpec) -> Tuple[str, ...]:
+def as_tuple(spec: KeySpec) -> tuple[str, ...]:
     return (spec,) if isinstance(spec, str) else tuple(spec)
 
 

svc_infra/deploy/__init__.py

@@ -33,7 +33,6 @@ from __future__ import annotations
 import os
 from enum import StrEnum
 from functools import cache
-from typing import Optional
 
 
 class Platform(StrEnum):
@@ -98,9 +97,7 @@ PLATFORM_SIGNATURES: dict[Platform, tuple[str, ...]] = {
     Platform.AZURE_APP_SERVICE: ("WEBSITE_SITE_NAME", "WEBSITE_INSTANCE_ID"),
     # Generic container/orchestration (check last)
     Platform.KUBERNETES: ("KUBERNETES_SERVICE_HOST", "KUBERNETES_PORT"),
-    Platform.DOCKER: (
-        "DOCKER_CONTAINER",
-    ),  # User must set this; no reliable auto-detect
+    Platform.DOCKER: ("DOCKER_CONTAINER",),  # User must set this; no reliable auto-detect
 }
 
 # Container detection paths (Linux-specific)
@@ -126,7 +123,7 @@ def _is_in_container() -> bool:
 
     # Check cgroup (Linux)
     try:
-        with open("/proc/1/cgroup", "r") as f:
+        with open("/proc/1/cgroup") as f:
             cgroup = f.read()
             if "docker" in cgroup or "kubepods" in cgroup or "containerd" in cgroup:
                 return True
@@ -169,9 +166,7 @@ def get_platform() -> Platform:
 
 
 # Platform category groupings
-AWS_PLATFORMS = frozenset(
-    {Platform.AWS_ECS, Platform.AWS_LAMBDA, Platform.AWS_BEANSTALK}
-)
+AWS_PLATFORMS = frozenset({Platform.AWS_ECS, Platform.AWS_LAMBDA, Platform.AWS_BEANSTALK})
 GCP_PLATFORMS = frozenset({Platform.CLOUD_RUN, Platform.APP_ENGINE, Platform.GCE})
 AZURE_PLATFORMS = frozenset(
     {
@@ -180,9 +175,7 @@ AZURE_PLATFORMS = frozenset(
         Platform.AZURE_APP_SERVICE,
     }
 )
-PAAS_PLATFORMS = frozenset(
-    {Platform.RAILWAY, Platform.RENDER, Platform.FLY, Platform.HEROKU}
-)
+PAAS_PLATFORMS = frozenset({Platform.RAILWAY, Platform.RENDER, Platform.FLY, Platform.HEROKU})
 
 
 def is_aws() -> bool:
@@ -292,7 +285,7 @@ def get_database_url(
     *,
     prefer_private: bool = True,
     normalize: bool = True,
-) -> Optional[str]:
+) -> str | None:
     """
     Get database URL with platform-aware resolution.
 
@@ -336,7 +329,7 @@ def get_database_url(
     return None
 
 
-def get_redis_url(*, prefer_private: bool = True) -> Optional[str]:
+def get_redis_url(*, prefer_private: bool = True) -> str | None:
     """
     Get Redis URL with platform-aware resolution.
 
@@ -388,7 +381,7 @@ def get_service_url(
     *,
     default_port: int = 8000,
     scheme: str = "http",
-) -> Optional[str]:
+) -> str | None:
     """
     Get URL for an internal service by name.
 
@@ -426,7 +419,7 @@ def get_service_url(
     return None
 
 
-def get_public_url() -> Optional[str]:
+def get_public_url() -> str | None:
     """
     Get the public URL of this service.
 

svc_infra/documents/add.py

@@ -20,7 +20,7 @@ Quick Start:
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Optional, cast
+from typing import TYPE_CHECKING, cast
 
 from fastapi import HTTPException, Request, Response
 
@@ -34,7 +34,7 @@ if TYPE_CHECKING:
     from .ease import DocumentManager
 
 
-def get_documents_manager(app: "FastAPI") -> "DocumentManager":
+def get_documents_manager(app: FastAPI) -> DocumentManager:
     """
     Dependency to get document manager from app state.
 
@@ -49,17 +49,16 @@ def get_documents_manager(app: "FastAPI") -> "DocumentManager":
     """
     if not hasattr(app.state, "documents"):
         raise RuntimeError("Documents not configured. Call add_documents(app) first.")
-    from .ease import DocumentManager
 
-    return cast(DocumentManager, app.state.documents)
+    return cast("DocumentManager", app.state.documents)
 
 
 def add_documents(
-    app: "FastAPI",
-    storage_backend: Optional["StorageBackend"] = None,
+    app: FastAPI,
+    storage_backend: StorageBackend | None = None,
     prefix: str = "/documents",
-    tags: Optional[list[str]] = None,
-) -> "DocumentManager":
+    tags: list[str] | None = None,
+) -> DocumentManager:
     """
     Add document management endpoints to FastAPI app.
 

svc_infra/documents/ease.py

@@ -27,7 +27,7 @@ Quick Start:
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict, List, Optional
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from svc_infra.storage.base import StorageBackend
@@ -65,7 +65,7 @@ class DocumentManager:
         >>> manager.delete(doc.id)
     """
 
-    def __init__(self, storage: "StorageBackend"):
+    def __init__(self, storage: StorageBackend):
         """
         Initialize document manager.
 
@@ -79,9 +79,9 @@ class DocumentManager:
         user_id: str,
         file: bytes,
         filename: str,
-        metadata: Optional[Dict] = None,
-        content_type: Optional[str] = None,
-    ) -> "Document":
+        metadata: dict | None = None,
+        content_type: str | None = None,
+    ) -> Document:
         """
         Upload a document.
 
@@ -133,7 +133,7 @@ class DocumentManager:
 
         return await download_document(self.storage, document_id)
 
-    def get(self, document_id: str) -> Optional["Document"]:
+    def get(self, document_id: str) -> Document | None:
         """
         Get document metadata by ID.
 
@@ -174,7 +174,7 @@ class DocumentManager:
         user_id: str,
         limit: int = 100,
         offset: int = 0,
-    ) -> List["Document"]:
+    ) -> list[Document]:
         """
         List user's documents.
 
@@ -198,7 +198,7 @@ class DocumentManager:
         return list_documents(user_id, limit, offset)
 
 
-def easy_documents(storage: Optional["StorageBackend"] = None) -> DocumentManager:
+def easy_documents(storage: StorageBackend | None = None) -> DocumentManager:
     """
     Create a document manager with auto-configured storage.
 

svc_infra/documents/models.py

@@ -22,7 +22,7 @@ Quick Start:
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any, Dict, Optional
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -105,10 +105,10 @@ class Document(BaseModel):
     )
     storage_path: str = Field(..., description="Storage backend path/key")
     content_type: str = Field(..., description="MIME type (e.g., application/pdf)")
-    checksum: Optional[str] = Field(
+    checksum: str | None = Field(
         None, description="File checksum for integrity validation (e.g., sha256:...)"
     )
-    metadata: Dict[str, Any] = Field(
+    metadata: dict[str, Any] = Field(
         default_factory=dict,
         description="Flexible metadata for custom fields (category, tags, dates, etc.)",
     )

svc_infra/documents/storage.py

@@ -26,7 +26,7 @@ import hashlib
 import mimetypes
 import uuid
 from datetime import datetime
-from typing import TYPE_CHECKING, Dict, List, Optional
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from svc_infra.storage.base import StorageBackend
@@ -35,17 +35,17 @@ if TYPE_CHECKING:
 
 # In-memory metadata storage (production: use SQL database)
 # This is a temporary solution until SQL integration is complete
-_documents_metadata: Dict[str, "Document"] = {}
+_documents_metadata: dict[str, Document] = {}
 
 
 async def upload_document(
-    storage: "StorageBackend",
+    storage: StorageBackend,
     user_id: str,
     file: bytes,
     filename: str,
-    metadata: Optional[Dict] = None,
-    content_type: Optional[str] = None,
-) -> "Document":
+    metadata: dict | None = None,
+    content_type: str | None = None,
+) -> Document:
     """
     Upload a document with file content to storage backend.
 
@@ -105,9 +105,7 @@ async def upload_document(
     checksum = f"sha256:{hashlib.sha256(file).hexdigest()}"
 
     # Upload file to storage backend
-    await storage.put(
-        storage_path, file, content_type=content_type, metadata=metadata or {}
-    )
+    await storage.put(storage_path, file, content_type=content_type, metadata=metadata or {})
 
     # Create document metadata
     doc = Document(
@@ -128,7 +126,7 @@ async def upload_document(
     return doc
 
 
-def get_document(document_id: str) -> Optional["Document"]:
+def get_document(document_id: str) -> Document | None:
     """
     Get document metadata by ID.
 
@@ -146,7 +144,7 @@ def get_document(document_id: str) -> Optional["Document"]:
     return _documents_metadata.get(document_id)
 
 
-async def download_document(storage: "StorageBackend", document_id: str) -> bytes:
+async def download_document(storage: StorageBackend, document_id: str) -> bytes:
     """
     Download document file content from storage.
 
@@ -176,7 +174,7 @@ async def download_document(storage: "StorageBackend", document_id: str) -> byte
     return await storage.get(doc.storage_path)
 
 
-async def delete_document(storage: "StorageBackend", document_id: str) -> bool:
+async def delete_document(storage: StorageBackend, document_id: str) -> bool:
     """
     Delete document and its file content.
 
@@ -212,7 +210,7 @@ def list_documents(
     user_id: str,
     limit: int = 100,
     offset: int = 0,
-) -> List["Document"]:
+) -> list[Document]:
     """
     List user's documents with pagination.