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

svc_infra/db/nosql/core.py

@@ -1,13 +1,25 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Iterable, Sequence
+from typing import Any, Iterable, Sequence, cast
 
-from motor.motor_asyncio import AsyncIOMotorDatabase
-from pymongo import IndexModel
+try:
+    from motor.motor_asyncio import AsyncIOMotorDatabase
+    from pymongo import IndexModel
+
+    HAS_MOTOR = True
+except ImportError:  # pragma: no cover
+    HAS_MOTOR = False
+    AsyncIOMotorDatabase = Any  # type: ignore[assignment, misc]
+    IndexModel = Any  # type: ignore[assignment, misc]
 
 from svc_infra.db.nosql.indexes import normalize_indexes
-from svc_infra.db.nosql.mongo.client import acquire_db, close_mongo, init_mongo, ping_mongo
+from svc_infra.db.nosql.mongo.client import (
+    acquire_db,
+    close_mongo,
+    init_mongo,
+    ping_mongo,
+)
 from svc_infra.db.nosql.resource import NoSqlResource
 from svc_infra.db.nosql.utils import (
     get_mongo_dbname_from_env,
@@ -34,7 +46,8 @@ async def _apply_indexes(
 ) -> list[str]:
     if not indexes:
         return []
-    return await db[collection].create_indexes(list(indexes))
+    result = await db[collection].create_indexes(list(indexes))
+    return cast(list[str], result)
 
 
 # collection + doc used to "lock" the chosen DB name for this app
@@ -48,7 +61,9 @@ async def assert_db_locked(
     registry = db.client.get_database(_REG_DB)
     await registry[_REG_COLL].create_index("service_id", unique=True)
 
-    doc = await registry[_REG_COLL].find_one({"service_id": service_id}, projection={"db_name": 1})
+    doc = await registry[_REG_COLL].find_one(
+        {"service_id": service_id}, projection={"db_name": 1}
+    )
     if doc is None:
         await registry[_REG_COLL].insert_one(
             {"service_id": service_id, "db_name": expected_db_name}
@@ -91,9 +106,13 @@ async def prepare_mongo(
 
     expected_db = get_mongo_dbname_from_env(required=True)
     if db.name != expected_db:
-        raise RuntimeError(f"Connected to Mongo DB '{db.name}', but env says '{expected_db}'.")
+        raise RuntimeError(
+            f"Connected to Mongo DB '{db.name}', but env says '{expected_db}'."
+        )
 
-    await assert_db_locked(db, expected_db, service_id=service_id, allow_rebind=allow_rebind)
+    await assert_db_locked(
+        db, expected_db, service_id=service_id, allow_rebind=allow_rebind
+    )
 
     # collections
     colls = [r.resolved_collection() for r in resources]
@@ -109,7 +128,9 @@ async def prepare_mongo(
             names = await _apply_indexes(db, collection=coll, indexes=idx_models)
             created_idx[coll] = names
 
-    return PrepareResult(ok=True, created_collections=created_colls, created_indexes=created_idx)
+    return PrepareResult(
+        ok=True, created_collections=created_colls, created_indexes=created_idx
+    )
 
 
 def setup_and_prepare(

svc_infra/db/nosql/indexes.py

@@ -66,7 +66,9 @@ def normalize_index(idx: Union[IndexModel, Alias]) -> IndexModel:
     return IndexModel(keys, **kwargs)
 
 
-def normalize_indexes(indexes: Optional[Iterable[Union[IndexModel, Alias]]]) -> List[IndexModel]:
+def normalize_indexes(
+    indexes: Optional[Iterable[Union[IndexModel, Alias]]],
+) -> List[IndexModel]:
     if not indexes:
         return []
     return [normalize_index(i) for i in indexes]

svc_infra/db/nosql/management.py

@@ -83,7 +83,7 @@ def make_document_crud_schemas(
         )
 
     # Backstop encoders in case any exotic types slip through
-    encoders = {ObjectId: str, PyObjectId: str}
+    encoders: dict[type, Any] = {ObjectId: str, PyObjectId: str}
     if json_encoders:
         encoders.update(json_encoders)
 

svc_infra/db/nosql/mongo/README.md

@@ -29,17 +29,17 @@ We provide four CLI commands. You can register them on your Typer app or invoke
 
 ### Commands
 
-- `mongo-scaffold` — create both document **and** CRUD schemas
-- `mongo-scaffold-documents` — create only the **document** model (Pydantic)
-- `mongo-scaffold-schemas` — create only the **CRUD schemas**
-- `mongo-scaffold-resources` — create a starter `resources.py` with a `RESOURCES` list
+- `mongo scaffold` — create both document **and** CRUD schemas
+- `mongo scaffold-documents` — create only the **document** model (Pydantic)
+- `mongo scaffold-schemas` — create only the **CRUD schemas**
+- `mongo scaffold-resources` — create a starter `resources.py` with a `RESOURCES` list
 
 ### Typical usage
 
 #### A) Scaffold documents + schemas together
 
 ```bash
-yourapp mongo-scaffold \
+yourapp mongo scaffold \
   --entity-name Product \
   --documents-dir ./src/your_app/products \
   --schemas-dir ./src/your_app/products \
@@ -57,7 +57,7 @@ src/your_app/products/schemas.py     # ProductRead/ProductCreate/ProductUpdate
 B) Documents only
 
 ```bash
-yourapp mongo-scaffold-documents \
+yourapp mongo scaffold-documents \
   --dest-dir ./src/your_app/products \
   --entity-name Product \
   --documents-filename product_doc.py
@@ -66,7 +66,7 @@ yourapp mongo-scaffold-documents \
 C) Schemas only
 
 ```bash
-yourapp mongo-scaffold-schemas \
+yourapp mongo scaffold-schemas \
   --dest-dir ./src/your_app/products \
   --entity-name Product \
   --schemas-filename product_schemas.py
@@ -75,7 +75,7 @@ yourapp mongo-scaffold-schemas \
 D) Starter resources.py
 
 ```bash
-yourapp mongo-scaffold-resources \
+yourapp mongo scaffold-resources \
   --dest-dir ./src/your_app/mongo \
   --filename resources.py \
   --overwrite
@@ -131,7 +131,7 @@ There are two flavors:
 A) Async, minimal (connect, create collections, apply indexes)
 
 ```bash
-yourapp mongo-prepare \
+yourapp mongo prepare \
   --resources your_app.mongo.resources:RESOURCES \
   --mongo-url "$MONGO_URL" \
   --mongo-db "$MONGO_DB"
@@ -140,7 +140,7 @@ yourapp mongo-prepare \
 B) Synchronous wrapper (end-to-end convenience)
 
 ```bash
-yourapp mongo-setup-and-prepare \
+yourapp mongo setup-and-prepare \
   --resources your_app.mongo.resources:RESOURCES \
   --mongo-url "$MONGO_URL" \
   --mongo-db "$MONGO_DB"
@@ -149,7 +149,7 @@ yourapp mongo-setup-and-prepare \
 You can also ping connectivity:
 
 ```bash
-yourapp mongo-ping --mongo-url "$MONGO_URL" --mongo-db "$MONGO_DB"
+yourapp mongo ping --mongo-url "$MONGO_URL" --mongo-db "$MONGO_DB"
 ```
 
 Behind the scenes, preparation also locks a service ID to a DB name to prevent accidental cross-DB usage. You can pass --allow-rebind if you intentionally move environments.
@@ -430,9 +430,9 @@ NoSqlResource(
 	•	If using explicit schemas with PyObjectId, make sure model_config.json_encoders includes {PyObjectId: str}.
 	•	When using auto-schemas, we expose ObjectId-like fields as str so no custom encoder is needed.
 	•	Connected to wrong DB name
-	•	The system locks a service_id to the DB name once prepared. If you change DBs, run mongo-prepare with --allow-rebind.
+  •	The system locks a service_id to the DB name once prepared. If you change DBs, run `mongo prepare` with --allow-rebind.
 	•	Indexes not created
-	•	Double-check RESOURCES[indexes]. Run mongo-prepare again and inspect the output dictionary of created indexes.
+  •	Double-check RESOURCES[indexes]. Run `mongo prepare` again and inspect the output dictionary of created indexes.
 
 ⸻
 

svc_infra/db/nosql/mongo/client.py

@@ -1,8 +1,15 @@
 from __future__ import annotations
 
-from typing import Optional
+from typing import Any, Optional
 
-from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+try:
+    from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+
+    HAS_MOTOR = True
+except ImportError:  # pragma: no cover
+    HAS_MOTOR = False
+    AsyncIOMotorClient = Any  # type: ignore[assignment, misc]
+    AsyncIOMotorDatabase = Any  # type: ignore[assignment, misc]
 
 from .settings import MongoSettings
 
@@ -10,6 +17,15 @@ _client: Optional[AsyncIOMotorClient] = None
 _db: Optional[AsyncIOMotorDatabase] = None
 
 
+def _require_motor() -> None:
+    """Raise ImportError if motor is not installed."""
+    if not HAS_MOTOR:
+        raise ImportError(
+            "MongoDB support requires the 'motor' package. "
+            "Install with: pip install svc-infra[mongodb]"
+        )
+
+
 def _client_opts(cfg: MongoSettings) -> dict:
     return {
         "appname": cfg.appname,
@@ -20,6 +36,7 @@ def _client_opts(cfg: MongoSettings) -> dict:
 
 
 async def init_mongo(cfg: MongoSettings | None = None) -> AsyncIOMotorDatabase:
+    _require_motor()
     global _client, _db
     cfg = cfg or MongoSettings()
     if _client is None:

svc_infra/db/nosql/mongo/settings.py

@@ -6,8 +6,12 @@ from pydantic import AnyUrl, BaseModel, Field
 
 
 class MongoSettings(BaseModel):
-    url: AnyUrl = Field(default_factory=lambda: os.getenv("MONGO_URL", "mongodb://localhost:27017"))
+    url: AnyUrl = Field(
+        default_factory=lambda: os.getenv("MONGO_URL", "mongodb://localhost:27017")
+    )  # type: ignore[assignment]
     db_name: str = Field(default_factory=lambda: os.getenv("MONGO_DB", ""))
-    appname: str = Field(default_factory=lambda: os.getenv("MONGO_APPNAME", "svc-infra"))
+    appname: str = Field(
+        default_factory=lambda: os.getenv("MONGO_APPNAME", "svc-infra")
+    )
     min_pool_size: int = int(os.getenv("MONGO_MIN_POOL", "0"))
     max_pool_size: int = int(os.getenv("MONGO_MAX_POOL", "100"))

svc_infra/db/nosql/repository.py

@@ -1,8 +1,19 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, 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:
@@ -78,11 +89,13 @@ class NoSqlRepository:
         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 +104,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(
@@ -108,7 +122,7 @@ class NoSqlRepository:
         offset: int,
         sort: Optional[List[Tuple[str, int]]] = None,
         filter: Optional[Dict[str, Any]] = None,
-    ) -> List[Dict]:
+    ) -> 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:
@@ -117,12 +131,14 @@ class NoSqlRepository:
 
     async def count(self, db, *, filter: Optional[Dict[str, Any]] = 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:
         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]:
@@ -155,10 +171,10 @@ class NoSqlRepository:
             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,
@@ -169,11 +185,13 @@ class NoSqlRepository:
         limit: int,
         offset: int,
         sort: Optional[List[Tuple[str, int]]] = None,
-    ) -> List[Dict]:
+    ) -> 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:
@@ -184,9 +202,11 @@ 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:
         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,9 +1,26 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Callable, Iterable, Optional, Sequence, Type, Union
-
-from pymongo import IndexModel
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    Optional,
+    Sequence,
+    TYPE_CHECKING,
+    Type,
+    Union,
+)
+
+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:

svc_infra/db/nosql/scaffold.py

@@ -6,7 +6,9 @@ from typing import Any, Dict, Literal, Optional
 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"
 
 
@@ -46,7 +48,9 @@ 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:
@@ -103,7 +107,9 @@ def scaffold_schemas_core(
     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)

svc_infra/db/nosql/service.py

@@ -43,7 +43,9 @@ 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/types.py

@@ -11,7 +11,9 @@ 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
@@ -22,4 +24,6 @@ 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()
+        )