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

svc_infra/db/nosql/repository.py

@@ -1,8 +1,22 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+import builtins
+from collections.abc import Iterable, Sequence
+from datetime import UTC
+from typing import Any, cast
 
-from bson import ObjectId
+try:
+    from bson import ObjectId
+
+    _HAS_BSON = True
+except ModuleNotFoundError:
+    # `bson` is provided by the optional `pymongo` dependency.
+    # Keep imports working for non-mongo users/tests; runtime Mongo usage still
+    # requires installing pymongo.
+    _HAS_BSON = False
+
+    class ObjectId:  # type: ignore[no-redef]
+        pass
 
 
 class NoSqlRepository:
@@ -24,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
@@ -35,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
@@ -73,16 +87,18 @@ 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 {}
         if len(parts) == 1:
-            return parts[0]  # type: ignore[return-value]
+            return parts[0]
         return {"$and": parts}
 
     def _normalize_id_value(self, val: Any) -> Any:
         """If we use Mongo’s _id and a string is passed, coerce to ObjectId when possible."""
+        if not _HAS_BSON:
+            return val
         if self.id_field == "_id" and isinstance(val, str):
             try:
                 return ObjectId(val)
@@ -91,13 +107,14 @@ class NoSqlRepository:
         return val
 
     @staticmethod
-    def _public_doc(doc: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
-        if not doc:
-            return doc
+    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)
-            d["id"] = str(_id) if isinstance(_id, ObjectId) else _id
+            if _HAS_BSON and isinstance(_id, ObjectId):
+                d["id"] = str(_id)
+            else:
+                d["id"] = _id
         return d
 
     async def list(
@@ -106,26 +123,28 @@ class NoSqlRepository:
         *,
         limit: int,
         offset: int,
-        sort: Optional[List[Tuple[str, int]]] = None,
-        filter: Optional[Dict[str, Any]] = None,
-    ) -> List[Dict]:
+        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 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)
+        if doc is None:
+            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)
@@ -134,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)
@@ -146,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 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 res.deleted_count > 0
+        return cast("int", res.deleted_count) > 0
 
     async def search(
         self,
@@ -168,8 +187,8 @@ class NoSqlRepository:
         fields: Sequence[str],
         limit: int,
         offset: int,
-        sort: Optional[List[Tuple[str, int]]] = None,
-    ) -> List[Dict]:
+        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 = (
@@ -184,9 +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 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})
         return doc is not None

svc_infra/db/nosql/resource.py

@@ -1,9 +1,21 @@
 from __future__ import annotations
 
+from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass
-from typing import Any, Callable, Iterable, Optional, Sequence, Type, Union
-
-from pymongo import IndexModel
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+if TYPE_CHECKING:
+    from pymongo import IndexModel
+else:
+    try:
+        from pymongo import IndexModel
+    except ModuleNotFoundError:
+        # Minimal runtime stub so importing svc_infra works without optional Mongo deps.
+        class IndexModel:  # type: ignore[no-redef]
+            pass
 
 
 def _snake(name: str) -> str:
@@ -39,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,7 +1,7 @@
 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
@@ -10,7 +10,7 @@ _INIT_CONTENT_PAIRED = 'from . import documents, schemas\n\n__all__ = ["document
 _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)
 
@@ -27,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)
@@ -76,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)
@@ -98,12 +98,14 @@ 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(
-        tmpl_dir="svc_infra.db.nosql.mongo.templates", name="schemas.py.tmpl", subs={"Entity": ent}
+        tmpl_dir="svc_infra.db.nosql.mongo.templates",
+        name="schemas.py.tmpl",
+        subs={"Entity": ent},
     )
     filename = schemas_filename or f"{snake(entity_name)}.py"
     res = write(dest / filename, txt, overwrite)
@@ -115,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
 

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/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: