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

svc_infra/db/nosql/repository.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, cast
+import builtins
+from collections.abc import Iterable, Sequence
+from datetime import UTC
+from typing import Any, cast
 
 try:
     from bson import ObjectId
@@ -35,7 +38,7 @@ class NoSqlRepository:
         soft_delete: bool = False,
         soft_delete_field: str = "deleted_at",
         soft_delete_flag_field: str | None = None,
-        immutable_fields: Optional[set[str]] = None,
+        immutable_fields: set[str] | None = None,
     ):
         self.collection_name = collection_name
         self.id_field = id_field
@@ -46,7 +49,7 @@ class NoSqlRepository:
             immutable_fields or {self.id_field, "created_at", "updated_at"}
         )
 
-    def _alive_filter(self) -> Dict[str, Any]:
+    def _alive_filter(self) -> dict[str, Any]:
         """
         Build a filter that returns 'alive' docs when soft_delete is enabled.
         - deleted_at is either null or absent
@@ -84,7 +87,7 @@ class NoSqlRepository:
 
         return clauses[0] if len(clauses) == 1 else {"$and": clauses}
 
-    def _merge_and(self, *filters: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    def _merge_and(self, *filters: dict[str, Any] | None) -> dict[str, Any]:
         parts = [f for f in filters if f]
         if not parts:
             return {}
@@ -104,7 +107,7 @@ class NoSqlRepository:
         return val
 
     @staticmethod
-    def _public_doc(doc: Dict[str, Any]) -> Dict[str, Any]:
+    def _public_doc(doc: dict[str, Any]) -> dict[str, Any]:
         d = dict(doc)
         if "_id" in d and "id" not in d:
             _id = d.pop("_id", None)
@@ -120,20 +123,20 @@ class NoSqlRepository:
         *,
         limit: int,
         offset: int,
-        sort: Optional[List[Tuple[str, int]]] = None,
-        filter: Optional[Dict[str, Any]] = None,
-    ) -> List[Dict[str, Any]]:
+        sort: builtins.list[tuple[str, int]] | None = None,
+        filter: dict[str, Any] | None = None,
+    ) -> builtins.list[dict[str, Any]]:
         filt = self._merge_and(self._alive_filter(), filter)
         cursor = db[self.collection_name].find(filt).skip(offset).limit(limit)
         if sort:
             cursor = cursor.sort(sort)
         return [self._public_doc(doc) async for doc in cursor]
 
-    async def count(self, db, *, filter: Optional[Dict[str, Any]] = None) -> int:
+    async def count(self, db, *, filter: dict[str, Any] | None = None) -> int:
         filt = self._merge_and(self._alive_filter(), filter)
-        return cast(int, await db[self.collection_name].count_documents(filt or {}))
+        return cast("int", await db[self.collection_name].count_documents(filt or {}))
 
-    async def get(self, db, id_value: Any) -> Dict | None:
+    async def get(self, db, id_value: Any) -> dict | None:
         id_value = self._normalize_id_value(id_value)
         filt = self._merge_and(self._alive_filter(), {self.id_field: id_value})
         doc = await db[self.collection_name].find_one(filt)
@@ -141,7 +144,7 @@ class NoSqlRepository:
             return None
         return self._public_doc(doc)
 
-    async def create(self, db, data: Dict[str, Any]) -> Dict[str, Any]:
+    async def create(self, db, data: dict[str, Any]) -> dict[str, Any]:
         # don't let clients supply soft-delete artifacts on create
         if self.soft_delete:
             data.pop(self.soft_delete_field, None)
@@ -150,7 +153,7 @@ class NoSqlRepository:
         res = await db[self.collection_name].insert_one(data)
         return self._public_doc({**data, "_id": res.inserted_id})
 
-    async def update(self, db, id_value: Any, data: Dict[str, Any]) -> Dict | None:
+    async def update(self, db, id_value: Any, data: dict[str, Any]) -> dict | None:
         for k in list(data.keys()):
             if k in self.immutable_fields:
                 data.pop(k, None)
@@ -162,19 +165,19 @@ class NoSqlRepository:
     async def delete(self, db, id_value: Any) -> bool:
         id_value = self._normalize_id_value(id_value)
         if self.soft_delete:
-            set_ops: Dict[str, Any] = {}
+            set_ops: dict[str, Any] = {}
             if self.soft_delete_flag_field:
                 set_ops[self.soft_delete_flag_field] = False
-            from datetime import datetime, timezone
+            from datetime import datetime
 
-            set_ops[self.soft_delete_field] = datetime.now(timezone.utc)
+            set_ops[self.soft_delete_field] = datetime.now(UTC)
             res = await db[self.collection_name].update_one(
                 {self.id_field: id_value}, {"$set": set_ops}
             )
-            return cast(int, res.modified_count) > 0
+            return cast("int", res.modified_count) > 0
 
         res = await db[self.collection_name].delete_one({self.id_field: id_value})
-        return cast(int, res.deleted_count) > 0
+        return cast("int", res.deleted_count) > 0
 
     async def search(
         self,
@@ -184,14 +187,12 @@ class NoSqlRepository:
         fields: Sequence[str],
         limit: int,
         offset: int,
-        sort: Optional[List[Tuple[str, int]]] = None,
-    ) -> List[Dict[str, Any]]:
+        sort: builtins.list[tuple[str, int]] | None = None,
+    ) -> builtins.list[dict[str, Any]]:
         regex = {"$regex": q, "$options": "i"}
         or_filter = [{"$or": [{f: regex} for f in fields]}] if fields else []
         filt = (
-            self._merge_and(self._alive_filter(), *or_filter)
-            if or_filter
-            else self._alive_filter()
+            self._merge_and(self._alive_filter(), *or_filter) if or_filter else self._alive_filter()
         )
         cursor = db[self.collection_name].find(filt).skip(offset).limit(limit)
         if sort:
@@ -202,11 +203,9 @@ class NoSqlRepository:
         regex = {"$regex": q, "$options": "i"}
         or_filter = {"$or": [{f: regex} for f in fields]} if fields else {}
         filt = self._merge_and(self._alive_filter(), or_filter)
-        return cast(int, await db[self.collection_name].count_documents(filt or {}))
+        return cast("int", await db[self.collection_name].count_documents(filt or {}))
 
-    async def exists(self, db, *, where: Iterable[Dict[str, Any]]) -> bool:
+    async def exists(self, db, *, where: Iterable[dict[str, Any]]) -> bool:
         filt = self._merge_and(self._alive_filter(), *list(where))
-        doc = await db[self.collection_name].find_one(
-            filt, projection={self.id_field: 1}
-        )
+        doc = await db[self.collection_name].find_one(filt, projection={self.id_field: 1})
         return doc is not None

svc_infra/db/nosql/resource.py

@@ -1,15 +1,10 @@
 from __future__ import annotations
 
+from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass
 from typing import (
-    Any,
-    Callable,
-    Iterable,
-    Optional,
-    Sequence,
     TYPE_CHECKING,
-    Type,
-    Union,
+    Any,
 )
 
 if TYPE_CHECKING:
@@ -56,36 +51,36 @@ class NoSqlResource:
     """
 
     # API mounting
-    collection: Optional[str] = None
+    collection: str | None = None
     prefix: str = ""
-    document_model: Optional[Type[Any]] = None
+    document_model: type[Any] | None = None
 
     # optional Pydantic schemas (auto-derived if omitted)
-    read_schema: Optional[Type[Any]] = None
-    create_schema: Optional[Type[Any]] = None
-    update_schema: Optional[Type[Any]] = None
+    read_schema: type[Any] | None = None
+    create_schema: type[Any] | None = None
+    update_schema: type[Any] | None = None
 
     # behavior
-    search_fields: Optional[Sequence[str]] = None
-    tags: Optional[list[str]] = None
+    search_fields: Sequence[str] | None = None
+    tags: list[str] | None = None
     id_field: str = "_id"
     soft_delete: bool = False
     soft_delete_field: str = "deleted_at"
-    soft_delete_flag_field: Optional[str] = None
+    soft_delete_flag_field: str | None = None
 
     # custom wiring
-    service_factory: Optional[Callable[[Any], Any]] = None
+    service_factory: Callable[[Any], Any] | None = None
 
     # generated schema naming and exclusions
-    read_name: Optional[str] = None
-    create_name: Optional[str] = None
-    update_name: Optional[str] = None
+    read_name: str | None = None
+    create_name: str | None = None
+    update_name: str | None = None
     create_exclude: tuple[str, ...] = ("_id",)
     read_exclude: tuple[str, ...] = ()
     update_exclude: tuple[str, ...] = ()
 
     # NEW: indexes defined per collection (normalized to IndexModel at prepare time)
-    indexes: Optional[Iterable[Union[IndexModel, IndexAlias]]] = None
+    indexes: Iterable[IndexModel | IndexAlias] | None = None
 
     def __post_init__(self):
         if not self.collection and self.document_model:

svc_infra/db/nosql/scaffold.py

@@ -1,18 +1,16 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Literal
 
 from svc_infra.db.utils import normalize_dir, pascal, plural_snake, snake
 from svc_infra.utils import ensure_init_py, render_template, write
 
-_INIT_CONTENT_PAIRED = (
-    'from . import documents, schemas\n\n__all__ = ["documents", "schemas"]\n'
-)
+_INIT_CONTENT_PAIRED = 'from . import documents, schemas\n\n__all__ = ["documents", "schemas"]\n'
 _INIT_CONTENT_MINIMAL = "# package marker; add explicit exports here if desired\n"
 
 
-def _ensure_init_py(dir_path: Path, overwrite: bool, paired: bool) -> Dict[str, Any]:
+def _ensure_init_py(dir_path: Path, overwrite: bool, paired: bool) -> dict[str, Any]:
     content = _INIT_CONTENT_PAIRED if paired else _INIT_CONTENT_MINIMAL
     return ensure_init_py(dir_path, overwrite, paired, content)
 
@@ -29,9 +27,9 @@ def scaffold_core(
     entity_name: str = "Item",
     overwrite: bool = False,
     same_dir: bool = False,
-    documents_filename: Optional[str] = None,
-    schemas_filename: Optional[str] = None,
-) -> Dict[str, Any]:
+    documents_filename: str | None = None,
+    schemas_filename: str | None = None,
+) -> dict[str, Any]:
     """Create starter Mongo document model + CRUD schemas."""
 
     documents_dir = normalize_dir(documents_dir)
@@ -48,9 +46,7 @@ def scaffold_core(
     schemas_txt = render_template(
         tmpl_dir="svc_infra.db.nosql.mongo.templates",
         name="schemas.py.tmpl",
-        subs={
-            "Entity": ent
-        },  # (only if your schemas.tmpl doesn't need collection_name)
+        subs={"Entity": ent},  # (only if your schemas.tmpl doesn't need collection_name)
     )
 
     if same_dir:
@@ -80,8 +76,8 @@ def scaffold_documents_core(
     dest_dir: Path | str,
     entity_name: str = "Item",
     overwrite: bool = False,
-    documents_filename: Optional[str] = None,
-) -> Dict[str, Any]:
+    documents_filename: str | None = None,
+) -> dict[str, Any]:
     dest = normalize_dir(dest_dir)
     ent = pascal(entity_name)
     coll = plural_snake(ent)
@@ -102,8 +98,8 @@ def scaffold_schemas_core(
     dest_dir: Path | str,
     entity_name: str = "Item",
     overwrite: bool = False,
-    schemas_filename: Optional[str] = None,
-) -> Dict[str, Any]:
+    schemas_filename: str | None = None,
+) -> dict[str, Any]:
     dest = normalize_dir(dest_dir)
     ent = pascal(entity_name)
     txt = render_template(
@@ -121,9 +117,9 @@ def scaffold_resources_core(
     *,
     dest_dir: Path | str,
     entity_name: str = "Item",
-    filename: Optional[str] = None,  # defaults to "resources.py"
+    filename: str | None = None,  # defaults to "resources.py"
     overwrite: bool = False,
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
     """
     Create a starter resources.py with:
       - empty RESOURCES list

svc_infra/db/nosql/service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Sequence
+from collections.abc import Sequence
+from typing import Any
 
 from .repository import NoSqlRepository
 
@@ -43,9 +44,7 @@ class NoSqlService:
     async def search(
         self, db, *, q: str, fields: Sequence[str], limit: int, offset: int, sort=None
     ):
-        return await self.repo.search(
-            db, q=q, fields=fields, limit=limit, offset=offset, sort=sort
-        )
+        return await self.repo.search(db, q=q, fields=fields, limit=limit, offset=offset, sort=sort)
 
     async def count_filtered(self, db, *, q: str, fields: Sequence[str]) -> int:
         return await self.repo.count_filtered(db, q=q, fields=fields)

svc_infra/db/nosql/service_with_hooks.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Optional
+from collections.abc import Callable
+from typing import Any
 
 from .service import NoSqlService
 
@@ -11,8 +12,8 @@ class NoSqlServiceWithHooks(NoSqlService):
     def __init__(
         self,
         repo,
-        pre_create: Optional[PreHook] = None,
-        pre_update: Optional[PreHook] = None,
+        pre_create: PreHook | None = None,
+        pre_update: PreHook | None = None,
     ):
         super().__init__(repo)
         self._pre_create = pre_create

svc_infra/db/nosql/types.py

@@ -11,9 +11,7 @@ class PyObjectId(ObjectId):
     """Pydantic v2-compatible ObjectId type."""
 
     @classmethod
-    def __get_pydantic_core_schema__(
-        cls, _source_type: Any, _handler: GetCoreSchemaHandler
-    ):
+    def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: GetCoreSchemaHandler):
         def validate(v: Any) -> ObjectId:
             if isinstance(v, ObjectId):
                 return v
@@ -24,6 +22,4 @@ class PyObjectId(ObjectId):
                     raise ValueError(f"Invalid ObjectId: {v}") from e
             raise ValueError("ObjectId required")
 
-        return core_schema.no_info_after_validator_function(
-            validate, core_schema.any_schema()
-        )
+        return core_schema.no_info_after_validator_function(validate, core_schema.any_schema())

svc_infra/db/nosql/utils.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Optional, Sequence
 
 from dotenv import load_dotenv
 
@@ -27,7 +27,7 @@ def prepare_process_env(project_root: Path | str) -> Path:
     return root
 
 
-def _read_secret_from_file(path: str) -> Optional[str]:
+def _read_secret_from_file(path: str) -> str | None:
     try:
         p = Path(path)
         if p.exists():
@@ -40,7 +40,7 @@ def _read_secret_from_file(path: str) -> Optional[str]:
 def get_mongo_url_from_env(
     required: bool = True,
     env_vars: Sequence[str] = DEFAULT_MONGO_ENV_VARS,
-) -> Optional[str]:
+) -> str | None:
     """
     Resolve the Mongo connection string with support for:
       - Primary env vars (DEFAULT_MONGO_ENV_VARS).
@@ -99,7 +99,7 @@ def get_mongo_dbname_from_env(
     required: bool = False,
     env_vars: Sequence[str] = DEFAULT_MONGO_DB_ENV_VARS,
     default: str = "app",
-) -> Optional[str]:
+) -> str | None:
     """Return a database name from env; optional (Motor can connect without it)."""
     load_dotenv(override=False)
     for key in env_vars:

svc_infra/db/ops.py

@@ -25,7 +25,8 @@ from __future__ import annotations
 import logging
 import sys
 import time
-from typing import Any, Optional, Sequence, cast
+from collections.abc import Sequence
+from typing import Any, cast
 
 from .sql.utils import get_database_url_from_env
 
@@ -45,7 +46,7 @@ def _flush() -> None:
     sys.stderr.flush()
 
 
-def _get_connection(url: Optional[str] = None, connect_timeout: int = 10) -> Any:
+def _get_connection(url: str | None = None, connect_timeout: int = 10) -> Any:
     """
     Get a psycopg2 connection.
 
@@ -64,8 +65,7 @@ def _get_connection(url: Optional[str] = None, connect_timeout: int = 10) -> Any
         import psycopg2
     except ImportError as e:
         raise ImportError(
-            "psycopg2 is required for db.ops utilities. "
-            "Install with: pip install psycopg2-binary"
+            "psycopg2 is required for db.ops utilities. Install with: pip install psycopg2-binary"
         ) from e
 
     if url is None:
@@ -76,7 +76,7 @@ def _get_connection(url: Optional[str] = None, connect_timeout: int = 10) -> Any
 
 
 def wait_for_database(
-    url: Optional[str] = None,
+    url: str | None = None,
     timeout: float = DEFAULT_WAIT_TIMEOUT,
     interval: float = DEFAULT_WAIT_INTERVAL,
     verbose: bool = True,
@@ -114,9 +114,7 @@ def wait_for_database(
 
         if elapsed >= timeout:
             if verbose:
-                logger.error(
-                    f"Database not ready after {timeout}s ({attempt} attempts)"
-                )
+                logger.error(f"Database not ready after {timeout}s ({attempt} attempts)")
                 _flush()
             return False
 
@@ -130,20 +128,18 @@ def wait_for_database(
         except Exception as e:
             if verbose:
                 remaining = timeout - elapsed
-                logger.debug(
-                    f"Database not ready ({e}), retrying... ({remaining:.0f}s remaining)"
-                )
+                logger.debug(f"Database not ready ({e}), retrying... ({remaining:.0f}s remaining)")
                 _flush()
             time.sleep(interval)
 
 
 def run_sync_sql(
     sql: str,
-    params: Optional[Sequence[Any]] = None,
-    url: Optional[str] = None,
+    params: Sequence[Any] | None = None,
+    url: str | None = None,
     timeout: int = DEFAULT_STATEMENT_TIMEOUT,
     fetch: bool = False,
-) -> Optional[list[tuple[Any, ...]]]:
+) -> list[tuple[Any, ...]] | None:
     """
     Execute SQL synchronously with a statement timeout.
 
@@ -188,7 +184,7 @@ def run_sync_sql(
                 cur.execute(sql)
 
             if fetch:
-                return cast(list[tuple[Any, ...]], cur.fetchall())
+                return cast("list[tuple[Any, ...]]", cur.fetchall())
 
             conn.commit()
             return None
@@ -198,7 +194,7 @@ def run_sync_sql(
 
 def kill_blocking_queries(
     table_name: str,
-    url: Optional[str] = None,
+    url: str | None = None,
     timeout: int = DEFAULT_STATEMENT_TIMEOUT,
     dry_run: bool = False,
 ) -> list[dict[str, Any]]:
@@ -286,7 +282,7 @@ def kill_blocking_queries(
 
 def drop_table_safe(
     table_name: str,
-    url: Optional[str] = None,
+    url: str | None = None,
     timeout: int = DEFAULT_STATEMENT_TIMEOUT,
     kill_blocking: bool = True,
     if_exists: bool = True,
@@ -353,7 +349,7 @@ def drop_table_safe(
 def get_database_url(
     required: bool = True,
     normalize: bool = True,
-) -> Optional[str]:
+) -> str | None:
     """
     Convenience wrapper for get_database_url_from_env().
 

svc_infra/db/outbox.py

@@ -1,27 +1,26 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Any, Dict, Iterable, List, Optional, Protocol
+from datetime import UTC, datetime
+from typing import Any, Protocol
 
 
 @dataclass
 class OutboxMessage:
     id: int
     topic: str
-    payload: Dict[str, Any]
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    payload: dict[str, Any]
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
     attempts: int = 0
-    processed_at: Optional[datetime] = None
+    processed_at: datetime | None = None
 
 
 class OutboxStore(Protocol):
-    def enqueue(self, topic: str, payload: Dict[str, Any]) -> OutboxMessage:
+    def enqueue(self, topic: str, payload: dict[str, Any]) -> OutboxMessage:
         pass
 
-    def fetch_next(
-        self, *, topics: Optional[Iterable[str]] = None
-    ) -> Optional[OutboxMessage]:
+    def fetch_next(self, *, topics: Iterable[str] | None = None) -> OutboxMessage | None:
         """Return the next undispatched, unprocessed message (FIFO per-topic), or None.
 
         Notes:
@@ -42,17 +41,15 @@ class InMemoryOutboxStore:
 
     def __init__(self):
         self._seq = 0
-        self._messages: List[OutboxMessage] = []
+        self._messages: list[OutboxMessage] = []
 
-    def enqueue(self, topic: str, payload: Dict[str, Any]) -> OutboxMessage:
+    def enqueue(self, topic: str, payload: dict[str, Any]) -> OutboxMessage:
         self._seq += 1
         msg = OutboxMessage(id=self._seq, topic=topic, payload=dict(payload))
         self._messages.append(msg)
         return msg
 
-    def fetch_next(
-        self, *, topics: Optional[Iterable[str]] = None
-    ) -> Optional[OutboxMessage]:
+    def fetch_next(self, *, topics: Iterable[str] | None = None) -> OutboxMessage | None:
         allowed = set(topics) if topics else None
         for msg in self._messages:
             if msg.processed_at is not None:
@@ -68,7 +65,7 @@ class InMemoryOutboxStore:
     def mark_processed(self, msg_id: int) -> None:
         for msg in self._messages:
             if msg.id == msg_id:
-                msg.processed_at = datetime.now(timezone.utc)
+                msg.processed_at = datetime.now(UTC)
                 return
 
     def mark_failed(self, msg_id: int) -> None:
@@ -92,13 +89,13 @@ class SqlOutboxStore:
 
     # Placeholders to outline the API; not implemented here.
     def enqueue(
-        self, topic: str, payload: Dict[str, Any]
+        self, topic: str, payload: dict[str, Any]
     ) -> OutboxMessage:  # pragma: no cover - skeleton
         raise NotImplementedError
 
     def fetch_next(
-        self, *, topics: Optional[Iterable[str]] = None
-    ) -> Optional[OutboxMessage]:  # pragma: no cover - skeleton
+        self, *, topics: Iterable[str] | None = None
+    ) -> OutboxMessage | None:  # pragma: no cover - skeleton
         raise NotImplementedError
 
     def mark_processed(self, msg_id: int) -> None:  # pragma: no cover - skeleton