muscles-data-mongodb 0.1.0__tar.gz

muscles_data_mongodb-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: muscles-data-mongodb
+Version: 0.1.0
+Summary: MongoDB DocumentStorePort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: pymongo<5.0,>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-mongodb
+
+MongoDB adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports and runtime, while this package owns the PyMongo-backed
+`DocumentStorePort` adapter.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- SQLAlchemy direct SQL resource adapter:
+  [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
+- Executable example:
+  [`example_data_mongodb_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_mongodb_1)
+
+## Install
+
+```bash
+python -m pip install muscles-data-mongodb
+```
+
+For local framework development:
+
+```bash
+PYTHONPATH=../muscles-data/src:src python3 -m pytest -q
+```
+
+## Configuration
+
+```yaml
+data:
+  resources:
+    mongo.content:
+      type: mongodb
+      url: ${MONGO_URL}
+      database: content
+      timeout: 3
+      max_limit: 100
+```
+
+## Usage
+
+Register the external factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.ports import DocumentStorePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_mongodb import MongoDocumentStoreFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(MongoDocumentStoreFactory())
+
+runtime = DataRuntime(config=DataConfig.from_raw(config), catalog=catalog)
+store = runtime.require_port("mongo.content", DocumentStorePort)
+```
+
+Then use the narrow port:
+
+```python
+store.upsert_document("profiles", "denis", {"name": "Denis"})
+document = store.get_document("profiles", "denis")
+documents = store.find_documents("profiles", filters={"role": "developer"}, limit=20)
+store.delete_document("profiles", "denis")
+```
+
+The adapter maps `document_id` to MongoDB `_id` internally and returns public
+documents without `_id` to keep the port backend-neutral.
+
+## Capabilities
+
+`MongoDocumentStoreFactory` provides:
+
+- `document_store`;
+- `healthcheck`;
+- `native_client` only when the resource declares `native_client: true`.
+
+Native access is an advanced project escape hatch:
+
+```python
+from muscles_data import DataCapability
+
+client = runtime.require_resource("mongo.content", DataCapability.NATIVE_CLIENT).native_client()
+```
+
+Use the native client for backend-specific aggregations, indexes or operations
+that do not belong in `DocumentStorePort`.
+
+## Boundaries
+
+This package owns:
+
+- lazy PyMongo client creation;
+- database binding;
+- simple document get/find/upsert/delete;
+- safe `inspect()` and `doctor()`;
+- bounded `find_documents()` limits.
+
+It does not own:
+
+- ORM/document model layers;
+- schema validation;
+- migrations;
+- complex aggregation abstraction;
+- business repository APIs.
+
+`data.doctor` performs a MongoDB `ping`. `data.resources.list` and package
+initialization do not open a MongoDB connection.

muscles_data_mongodb-0.1.0/README.md

@@ -0,0 +1,121 @@
+# muscles-data-mongodb
+
+MongoDB adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports and runtime, while this package owns the PyMongo-backed
+`DocumentStorePort` adapter.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- SQLAlchemy direct SQL resource adapter:
+  [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
+- Executable example:
+  [`example_data_mongodb_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_mongodb_1)
+
+## Install
+
+```bash
+python -m pip install muscles-data-mongodb
+```
+
+For local framework development:
+
+```bash
+PYTHONPATH=../muscles-data/src:src python3 -m pytest -q
+```
+
+## Configuration
+
+```yaml
+data:
+  resources:
+    mongo.content:
+      type: mongodb
+      url: ${MONGO_URL}
+      database: content
+      timeout: 3
+      max_limit: 100
+```
+
+## Usage
+
+Register the external factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.ports import DocumentStorePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_mongodb import MongoDocumentStoreFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(MongoDocumentStoreFactory())
+
+runtime = DataRuntime(config=DataConfig.from_raw(config), catalog=catalog)
+store = runtime.require_port("mongo.content", DocumentStorePort)
+```
+
+Then use the narrow port:
+
+```python
+store.upsert_document("profiles", "denis", {"name": "Denis"})
+document = store.get_document("profiles", "denis")
+documents = store.find_documents("profiles", filters={"role": "developer"}, limit=20)
+store.delete_document("profiles", "denis")
+```
+
+The adapter maps `document_id` to MongoDB `_id` internally and returns public
+documents without `_id` to keep the port backend-neutral.
+
+## Capabilities
+
+`MongoDocumentStoreFactory` provides:
+
+- `document_store`;
+- `healthcheck`;
+- `native_client` only when the resource declares `native_client: true`.
+
+Native access is an advanced project escape hatch:
+
+```python
+from muscles_data import DataCapability
+
+client = runtime.require_resource("mongo.content", DataCapability.NATIVE_CLIENT).native_client()
+```
+
+Use the native client for backend-specific aggregations, indexes or operations
+that do not belong in `DocumentStorePort`.
+
+## Boundaries
+
+This package owns:
+
+- lazy PyMongo client creation;
+- database binding;
+- simple document get/find/upsert/delete;
+- safe `inspect()` and `doctor()`;
+- bounded `find_documents()` limits.
+
+It does not own:
+
+- ORM/document model layers;
+- schema validation;
+- migrations;
+- complex aggregation abstraction;
+- business repository APIs.
+
+`data.doctor` performs a MongoDB `ping`. `data.resources.list` and package
+initialization do not open a MongoDB connection.

muscles_data_mongodb-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "muscles-data-mongodb"
+version = "0.1.0"
+description = "MongoDB DocumentStorePort adapter for muscles-data"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Denis B.", email = "denis@butko.info" }]
+dependencies = [
+  "muscles-data>=0.1.0,<1.0.0",
+  "pymongo>=4.0,<5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "integration: tests that require the local backend integration stack",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

muscles_data_mongodb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .adapter import (
+    MongoDBAdapterError,
+    MongoDBClientMissingError,
+    MongoDBConfigError,
+    MongoDBConnectionError,
+    MongoDocumentStoreAdapter,
+    MongoDocumentStoreFactory,
+)
+
+
+__all__ = [
+    "MongoDBAdapterError",
+    "MongoDBClientMissingError",
+    "MongoDBConfigError",
+    "MongoDBConnectionError",
+    "MongoDocumentStoreAdapter",
+    "MongoDocumentStoreFactory",
+]

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb/adapter.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import importlib
+import threading
+from collections.abc import Callable
+from dataclasses import asdict
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+
+from muscles_data.config import DataResourceConfig
+from muscles_data.errors import DataError
+from muscles_data.models import DataCapability, HealthResult, InspectResult, WriteResult
+
+
+_CLIENT_UNSET = object()
+_ALLOWED_OPTIONS = {
+    "url",
+    "url_env",
+    "database",
+    "username",
+    "password",
+    "auth_source",
+    "timeout",
+    "timeout_ms",
+    "server_selection_timeout_ms",
+    "max_limit",
+    "native_client",
+    "tls",
+}
+
+
+class MongoDBAdapterError(DataError):
+    """Base error for MongoDB document-store adapter failures."""
+
+
+class MongoDBConfigError(ValueError, MongoDBAdapterError):
+    """Raised when a MongoDB resource config cannot be mapped safely."""
+
+
+class MongoDBClientMissingError(MongoDBAdapterError):
+    """Raised when MongoDB adapter is used without an available client."""
+
+
+class MongoDBConnectionError(MongoDBAdapterError):
+    """Raised when a MongoDB operation cannot reach or use the backend."""
+
+
+class MongoDocumentStoreAdapter:
+    resource_type = "mongodb"
+
+    def __init__(
+        self,
+        config: DataResourceConfig,
+        *,
+        client_factory: Callable[[DataResourceConfig], Any] | None = None,
+    ) -> None:
+        self.config = config
+        self._client_factory = client_factory
+        self._client: Any = _CLIENT_UNSET
+        self._lock = threading.RLock()
+        self.closed = False
+
+    def get_document(self, collection: str, document_id: str) -> Mapping[str, Any] | None:
+        try:
+            raw = self._collection(collection).find_one({"_id": str(document_id)})
+        except (MongoDBClientMissingError, MongoDBConfigError):
+            raise
+        except Exception as exc:
+            raise MongoDBConnectionError(self._safe_error(exc)) from exc
+        return _public_document(raw)
+
+    def upsert_document(self, collection: str, document_id: str, document: Mapping[str, Any]) -> WriteResult:
+        stored = _storage_document(document, document_id)
+        try:
+            result = self._collection(collection).replace_one({"_id": str(document_id)}, stored, upsert=True)
+        except (MongoDBClientMissingError, MongoDBConfigError):
+            raise
+        except Exception as exc:
+            raise MongoDBConnectionError(self._safe_error(exc)) from exc
+        matched = int(getattr(result, "matched_count", 0) or 0)
+        return WriteResult(written=1, matched=1 if matched else 0)
+
+    def find_documents(
+        self,
+        collection: str,
+        filters: Mapping[str, Any] | None = None,
+        limit: int = 100,
+        options: Mapping[str, Any] | None = None,
+    ) -> list[Mapping[str, Any]]:
+        options = dict(options or {})
+        query = dict(filters or {})
+        bounded_limit = self._bounded_limit(limit)
+        try:
+            cursor = self._collection(collection).find(query)
+            if "sort" in options:
+                cursor = cursor.sort(options["sort"])
+            if "skip" in options:
+                cursor = cursor.skip(max(0, int(options["skip"])))
+            cursor = cursor.limit(bounded_limit)
+            return [document for document in (_public_document(item) for item in cursor) if document is not None]
+        except (MongoDBClientMissingError, MongoDBConfigError):
+            raise
+        except Exception as exc:
+            raise MongoDBConnectionError(self._safe_error(exc)) from exc
+
+    def delete_document(self, collection: str, document_id: str) -> WriteResult:
+        try:
+            result = self._collection(collection).delete_one({"_id": str(document_id)})
+        except (MongoDBClientMissingError, MongoDBConfigError):
+            raise
+        except Exception as exc:
+            raise MongoDBConnectionError(self._safe_error(exc)) from exc
+        deleted = int(getattr(result, "deleted_count", 0) or 0)
+        return WriteResult(deleted=deleted, matched=deleted)
+
+    def inspect(self) -> dict[str, Any]:
+        return asdict(
+            InspectResult(
+                name=self.config.name,
+                type=self.config.type,
+                capabilities=[],
+                initialized=self._client is not _CLIENT_UNSET,
+                status="ok",
+                options=self.config.safe_options(),
+                details={"backend": "mongodb", "database": self.database_name(), "max_limit": self.max_limit()},
+            )
+        )
+
+    def health(self) -> HealthResult:
+        try:
+            self._client_instance().admin.command("ping")
+        except Exception as exc:
+            return HealthResult(status="failed", message=self._safe_error(exc), details={"database": self.database_name()})
+        return HealthResult(status="ok", message="MongoDB connection is available", details={"database": self.database_name()})
+
+    def close(self) -> None:
+        if self._client is _CLIENT_UNSET:
+            self.closed = True
+            return
+        close = getattr(self._client, "close", None)
+        if callable(close):
+            close()
+        self.closed = True
+
+    def native_client(self):
+        return self._client_instance()
+
+    def database_name(self) -> str:
+        database = str(self.config.options.get("database", "")).strip()
+        if not database:
+            raise MongoDBConfigError("MongoDB resource requires database")
+        return database
+
+    def max_limit(self) -> int:
+        value = int(self.config.options.get("max_limit", 100))
+        if value <= 0:
+            raise MongoDBConfigError("MongoDB max_limit must be positive")
+        return value
+
+    def _bounded_limit(self, limit: int) -> int:
+        return min(max(0, int(limit)), self.max_limit())
+
+    def _collection(self, collection: str):
+        name = _collection_name(collection)
+        return self._client_instance()[self.database_name()][name]
+
+    def _client_instance(self):
+        if self._client is _CLIENT_UNSET:
+            with self._lock:
+                if self._client is _CLIENT_UNSET:
+                    self._validate_options()
+                    client = (
+                        self._client_factory(self.config)
+                        if self._client_factory
+                        else _default_mongo_client(self.config)
+                    )
+                    if client is None:
+                        raise MongoDBClientMissingError("MongoDB client is not available")
+                    self._client = client
+        return self._client
+
+    def _validate_options(self) -> None:
+        unknown = sorted(set(self.config.options) - _ALLOWED_OPTIONS)
+        if unknown:
+            names = ", ".join(unknown)
+            raise MongoDBConfigError(f"Unsupported MongoDB resource options: {names}")
+        if not self.config.options.get("url") and not self.config.options.get("url_env"):
+            raise MongoDBConfigError("MongoDB resource requires url or url_env")
+        self.database_name()
+        self.max_limit()
+
+    def _safe_error(self, exc: Exception) -> str:
+        message = str(exc)
+        try:
+            options = self.config.resolved_options()
+        except Exception:
+            options = self.config.options
+        sensitive_values = {
+            str(options.get("url", "")),
+            str(options.get("username", "")),
+            str(options.get("password", "")),
+        }
+        try:
+            parsed = urlsplit(str(options.get("url", "")))
+            if parsed.username:
+                sensitive_values.add(parsed.username)
+            if parsed.password:
+                sensitive_values.add(parsed.password)
+        except Exception:  # pragma: no cover
+            pass
+        for value in sorted((item for item in sensitive_values if item), key=len, reverse=True):
+            message = message.replace(value, "***")
+        return message
+
+
+class MongoDocumentStoreFactory:
+    resource_type = "mongodb"
+
+    def __init__(self, *, client_factory: Callable[[DataResourceConfig], Any] | None = None) -> None:
+        self._client_factory = client_factory
+
+    def capabilities(self, config: DataResourceConfig) -> set[DataCapability]:
+        native = {DataCapability.NATIVE_CLIENT} if bool(config.options.get("native_client")) else set()
+        return {DataCapability.DOCUMENT_STORE, DataCapability.HEALTHCHECK} | native
+
+    def create(self, config: DataResourceConfig) -> MongoDocumentStoreAdapter:
+        return MongoDocumentStoreAdapter(config, client_factory=self._client_factory)
+
+
+def _default_mongo_client(config: DataResourceConfig):
+    try:
+        pymongo = importlib.import_module("pymongo")
+    except ImportError as exc:
+        raise MongoDBClientMissingError("pymongo package is not installed") from exc
+    client_cls = getattr(pymongo, "MongoClient", None)
+    if client_cls is None:
+        raise MongoDBClientMissingError("pymongo does not expose MongoClient")
+
+    try:
+        options = config.resolved_options()
+    except Exception as exc:
+        raise MongoDBConfigError(str(exc)) from exc
+
+    kwargs: dict[str, Any] = {}
+    if "timeout" in options:
+        timeout_ms = int(float(options["timeout"]) * 1000)
+        kwargs["timeoutMS"] = timeout_ms
+        kwargs["serverSelectionTimeoutMS"] = timeout_ms
+    if "timeout_ms" in options:
+        kwargs["timeoutMS"] = int(options["timeout_ms"])
+    if "server_selection_timeout_ms" in options:
+        kwargs["serverSelectionTimeoutMS"] = int(options["server_selection_timeout_ms"])
+    if "username" in options:
+        kwargs["username"] = options["username"]
+    if "password" in options:
+        kwargs["password"] = options["password"]
+    if "auth_source" in options:
+        kwargs["authSource"] = options["auth_source"]
+    if "tls" in options:
+        kwargs["tls"] = bool(options["tls"])
+    return client_cls(str(options["url"]), **kwargs)
+
+
+def _collection_name(value: str) -> str:
+    name = str(value).strip()
+    if not name:
+        raise MongoDBConfigError("MongoDB collection name must not be empty")
+    if "\x00" in name:
+        raise MongoDBConfigError("MongoDB collection name must not contain null bytes")
+    return name
+
+
+def _storage_document(document: Mapping[str, Any], document_id: str) -> dict[str, Any]:
+    stored = dict(document)
+    existing_id = stored.get("_id")
+    if existing_id is not None and str(existing_id) != str(document_id):
+        raise MongoDBConfigError("MongoDB document _id must match document_id")
+    stored["_id"] = str(document_id)
+    return stored
+
+
+def _public_document(raw: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if raw is None:
+        return None
+    document = dict(raw)
+    document.pop("_id", None)
+    return document

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: muscles-data-mongodb
+Version: 0.1.0
+Summary: MongoDB DocumentStorePort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: pymongo<5.0,>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-mongodb
+
+MongoDB adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports and runtime, while this package owns the PyMongo-backed
+`DocumentStorePort` adapter.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- SQLAlchemy direct SQL resource adapter:
+  [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
+- Executable example:
+  [`example_data_mongodb_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_mongodb_1)
+
+## Install
+
+```bash
+python -m pip install muscles-data-mongodb
+```
+
+For local framework development:
+
+```bash
+PYTHONPATH=../muscles-data/src:src python3 -m pytest -q
+```
+
+## Configuration
+
+```yaml
+data:
+  resources:
+    mongo.content:
+      type: mongodb
+      url: ${MONGO_URL}
+      database: content
+      timeout: 3
+      max_limit: 100
+```
+
+## Usage
+
+Register the external factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.ports import DocumentStorePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_mongodb import MongoDocumentStoreFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(MongoDocumentStoreFactory())
+
+runtime = DataRuntime(config=DataConfig.from_raw(config), catalog=catalog)
+store = runtime.require_port("mongo.content", DocumentStorePort)
+```
+
+Then use the narrow port:
+
+```python
+store.upsert_document("profiles", "denis", {"name": "Denis"})
+document = store.get_document("profiles", "denis")
+documents = store.find_documents("profiles", filters={"role": "developer"}, limit=20)
+store.delete_document("profiles", "denis")
+```
+
+The adapter maps `document_id` to MongoDB `_id` internally and returns public
+documents without `_id` to keep the port backend-neutral.
+
+## Capabilities
+
+`MongoDocumentStoreFactory` provides:
+
+- `document_store`;
+- `healthcheck`;
+- `native_client` only when the resource declares `native_client: true`.
+
+Native access is an advanced project escape hatch:
+
+```python
+from muscles_data import DataCapability
+
+client = runtime.require_resource("mongo.content", DataCapability.NATIVE_CLIENT).native_client()
+```
+
+Use the native client for backend-specific aggregations, indexes or operations
+that do not belong in `DocumentStorePort`.
+
+## Boundaries
+
+This package owns:
+
+- lazy PyMongo client creation;
+- database binding;
+- simple document get/find/upsert/delete;
+- safe `inspect()` and `doctor()`;
+- bounded `find_documents()` limits.
+
+It does not own:
+
+- ORM/document model layers;
+- schema validation;
+- migrations;
+- complex aggregation abstraction;
+- business repository APIs.
+
+`data.doctor` performs a MongoDB `ping`. `data.resources.list` and package
+initialization do not open a MongoDB connection.

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/muscles_data_mongodb/__init__.py
+src/muscles_data_mongodb/adapter.py
+src/muscles_data_mongodb.egg-info/PKG-INFO
+src/muscles_data_mongodb.egg-info/SOURCES.txt
+src/muscles_data_mongodb.egg-info/dependency_links.txt
+src/muscles_data_mongodb.egg-info/requires.txt
+src/muscles_data_mongodb.egg-info/top_level.txt
+tests/test_integration.py
+tests/test_mongodb_adapter.py

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb.egg-info/requires.txt

@@ -0,0 +1,5 @@
+muscles-data<1.0.0,>=0.1.0
+pymongo<5.0,>=4.0
+
+[dev]
+pytest<9.0,>=8.0

muscles_data_mongodb-0.1.0/src/muscles_data_mongodb.egg-info/top_level.txt

@@ -0,0 +1 @@
+muscles_data_mongodb

muscles_data_mongodb-0.1.0/tests/test_integration.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+from uuid import uuid4
+
+import pytest
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.models import DataCapability
+from muscles_data.ports import DocumentStorePort
+from muscles_data.runtime import DataRuntime
+
+from muscles_data_mongodb import MongoDocumentStoreFactory
+
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(not os.getenv("MUSCLES_DATA_INTEGRATION"), reason="backend integration is disabled"),
+]
+
+
+def test_mongodb_real_document_lifecycle():
+    database = f"muscles_data_it_{uuid4().hex[:12]}"
+    config = DataConfig.from_raw(
+        {
+            "data": {
+                "resources": {
+                    "mongo.content": {
+                        "type": "mongodb",
+                        "url_env": "MONGODB_URL",
+                        "database": database,
+                        "timeout": 3,
+                        "native_client": True,
+                    }
+                }
+            }
+        }
+    )
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(MongoDocumentStoreFactory())
+    runtime = DataRuntime(config=config, catalog=catalog)
+
+    client = None
+    try:
+        store = runtime.require_port("mongo.content", DocumentStorePort)
+        contracts = pytest.importorskip("muscles_data.contracts")
+        contract = getattr(contracts, "assert_document_store_contract", None)
+        if contract is not None:
+            contract(lambda: store)
+        assert runtime.doctor()["status"] == "ok"
+    finally:
+        try:
+            if client is None:
+                try:
+                    client = runtime.require_resource("mongo.content", DataCapability.NATIVE_CLIENT).native_client()
+                except Exception:
+                    client = None
+            if client is not None:
+                client.drop_database(database)
+        finally:
+            runtime.close()

muscles_data_mongodb-0.1.0/tests/test_mongodb_adapter.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.models import DataCapability
+from muscles_data.ports import DocumentStorePort
+from muscles_data.runtime import DataRuntime
+
+from muscles_data_mongodb import (
+    MongoDBClientMissingError,
+    MongoDBConfigError,
+    MongoDBConnectionError,
+    MongoDocumentStoreFactory,
+)
+
+
+class FakeMongoAdmin:
+    def __init__(self, client: "FakeMongoClient") -> None:
+        self.client = client
+
+    def command(self, name: str):
+        self.client.admin_commands.append(name)
+        if self.client.fail_ping:
+            raise TimeoutError("mongodb password=mongo-secret timed out")
+        return {"ok": 1}
+
+
+class FakeMongoCursor:
+    def __init__(self, docs: list[dict[str, Any]]) -> None:
+        self.docs = docs
+        self.limits: list[int] = []
+
+    def limit(self, value: int):
+        self.limits.append(value)
+        return self
+
+    def __iter__(self):
+        limit = self.limits[-1] if self.limits else len(self.docs)
+        return iter(self.docs[:limit])
+
+
+class FakeMongoCollection:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.docs: dict[str, dict[str, Any]] = {}
+        self.find_one_calls: list[dict[str, Any]] = []
+        self.replace_one_calls: list[dict[str, Any]] = []
+        self.find_calls: list[dict[str, Any]] = []
+        self.delete_one_calls: list[dict[str, Any]] = []
+        self.last_cursor: FakeMongoCursor | None = None
+
+    def find_one(self, filter):
+        self.find_one_calls.append(dict(filter))
+        document_id = str(filter.get("_id"))
+        doc = self.docs.get(document_id)
+        return dict(doc) if doc is not None else None
+
+    def replace_one(self, filter, replacement, upsert: bool = False):
+        self.replace_one_calls.append({"filter": dict(filter), "replacement": dict(replacement), "upsert": upsert})
+        document_id = str(filter["_id"])
+        matched = 1 if document_id in self.docs else 0
+        self.docs[document_id] = dict(replacement)
+        return SimpleNamespace(matched_count=matched, modified_count=1 if matched else 0, upserted_id=None if matched else document_id)
+
+    def find(self, filter):
+        self.find_calls.append(dict(filter))
+        docs = [
+            dict(doc)
+            for doc in self.docs.values()
+            if all(doc.get(key) == value for key, value in dict(filter).items())
+        ]
+        self.last_cursor = FakeMongoCursor(docs)
+        return self.last_cursor
+
+    def delete_one(self, filter):
+        self.delete_one_calls.append(dict(filter))
+        document_id = str(filter.get("_id"))
+        deleted = 1 if self.docs.pop(document_id, None) is not None else 0
+        return SimpleNamespace(deleted_count=deleted)
+
+
+class FakeMongoDatabase:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.collections: dict[str, FakeMongoCollection] = {}
+
+    def __getitem__(self, name: str) -> FakeMongoCollection:
+        return self.collections.setdefault(name, FakeMongoCollection(name))
+
+
+class FakeMongoClient:
+    def __init__(self, *, fail_ping: bool = False) -> None:
+        self.fail_ping = fail_ping
+        self.admin = FakeMongoAdmin(self)
+        self.databases: dict[str, FakeMongoDatabase] = {}
+        self.admin_commands: list[str] = []
+        self.closed = False
+
+    def __getitem__(self, name: str) -> FakeMongoDatabase:
+        return self.databases.setdefault(name, FakeMongoDatabase(name))
+
+    def close(self) -> None:
+        self.closed = True
+
+
+def _mongodb_config(url: str = "mongodb://user:mongo-secret@localhost:27017") -> dict[str, Any]:
+    return {
+        "data": {
+            "resources": {
+                "mongo.content": {
+                    "type": "mongodb",
+                    "url": url,
+                    "database": "content",
+                    "timeout": 1.5,
+                    "max_limit": 2,
+                    "native_client": True,
+                }
+            }
+        }
+    }
+
+
+def _runtime(client: FakeMongoClient | None):
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(MongoDocumentStoreFactory(client_factory=lambda _config: client))
+    return DataRuntime(
+        config=DataConfig.from_raw(_mongodb_config()),
+        catalog=catalog,
+    )
+
+
+def test_mongodb_document_store_is_registered_lazy_and_maps_operations():
+    client = FakeMongoClient()
+    runtime = _runtime(client)
+
+    listed = runtime.list_resources()
+    mongo = next(item for item in listed if item["name"] == "mongo.content")
+    inspected_before = runtime.inspect_resource("mongo.content")
+
+    assert mongo["type"] == "mongodb"
+    assert "document_store" in mongo["capabilities"]
+    assert "native_client" not in mongo["capabilities"]
+    assert mongo["initialized"] is False
+    assert inspected_before["initialized"] is False
+    assert inspected_before["options"]["url"] == "***"
+
+    store = runtime.require_port("mongo.content", DocumentStorePort)
+    write = store.upsert_document("profiles", "denis", {"name": "Denis", "role": "developer"})
+    found = store.get_document("profiles", "denis")
+    store.upsert_document("profiles", "reader", {"name": "Reader", "role": "developer"})
+    store.upsert_document("profiles", "other", {"name": "Other", "role": "developer"})
+    docs = store.find_documents("profiles", filters={"role": "developer"}, limit=10)
+    deleted = store.delete_document("profiles", "reader")
+
+    collection = client["content"]["profiles"]
+    assert write.written == 1
+    assert collection.replace_one_calls[0] == {
+        "filter": {"_id": "denis"},
+        "replacement": {"name": "Denis", "role": "developer", "_id": "denis"},
+        "upsert": True,
+    }
+    assert found == {"name": "Denis", "role": "developer"}
+    assert collection.find_one_calls[0] == {"_id": "denis"}
+    assert [doc["name"] for doc in docs] == ["Denis", "Reader"]
+    assert collection.last_cursor is not None
+    assert collection.last_cursor.limits == [2]
+    assert deleted.deleted == 1
+    assert collection.delete_one_calls[-1] == {"_id": "reader"}
+
+    native = runtime.require_resource("mongo.content", DataCapability.NATIVE_CLIENT).native_client()
+    assert native is client
+    assert client.admin_commands == []
+
+
+def test_mongodb_inspect_doctor_close_and_safe_failures():
+    client = FakeMongoClient()
+    runtime = _runtime(client)
+
+    doctor = runtime.doctor()
+    mongo_checks = [check for check in doctor["checks"] if check["resource"] == "mongo.content"]
+
+    assert mongo_checks[0]["status"] == "ok"
+    assert client.admin_commands == ["ping"]
+    assert "mongo-secret" not in repr(doctor)
+    assert runtime.close()["status"] == "ok"
+    assert client.closed is True
+
+    missing_client_runtime = _runtime(None)
+    with pytest.raises(MongoDBClientMissingError):
+        missing_client_runtime.require_port("mongo.content", DocumentStorePort).get_document("profiles", "denis")
+
+    failing_runtime = DataRuntime(
+        config=DataConfig.from_raw(_mongodb_config("mongodb://user:mongo-secret@localhost:27017")),
+        catalog=_catalog(MongoDocumentStoreFactory(client_factory=lambda _config: FakeMongoClient(fail_ping=True))),
+    )
+    failing_doctor = failing_runtime.doctor()
+    assert failing_doctor["status"] == "failed"
+    assert [check for check in failing_doctor["checks"] if check["resource"] == "mongo.content"][0]["status"] == "failed"
+    assert "mongo-secret" not in repr(failing_doctor)
+
+    bad_client = FakeMongoClient()
+    bad_client["content"]["profiles"].find_one = lambda _filter: (_ for _ in ()).throw(RuntimeError("mongodb://user:mongo-secret@localhost unavailable"))
+    bad_runtime = DataRuntime(
+        config=DataConfig.from_raw(_mongodb_config()),
+        catalog=_catalog(MongoDocumentStoreFactory(client_factory=lambda _config: bad_client)),
+    )
+    with pytest.raises(MongoDBConnectionError):
+        bad_runtime.require_port("mongo.content", DocumentStorePort).get_document("profiles", "denis")
+
+    unsupported_runtime = DataRuntime(
+        config=DataConfig.from_raw(
+            {
+                "data": {
+                    "resources": {
+                        "mongo.content": {
+                            "type": "mongodb",
+                            "url": "mongodb://localhost",
+                            "database": "content",
+                            "unsafe": True,
+                        }
+                    }
+                }
+            }
+        ),
+        catalog=_catalog(MongoDocumentStoreFactory(client_factory=lambda _config: FakeMongoClient())),
+    )
+    with pytest.raises(MongoDBConfigError, match="Unsupported MongoDB resource options"):
+        unsupported_runtime.require_port("mongo.content", DocumentStorePort).get_document("profiles", "denis")
+
+
+def test_mongodb_resource_requires_url_and_database():
+    assert DataConfig.from_raw(_mongodb_config()).resources["mongo.content"].type == "mongodb"
+
+    with pytest.raises(MongoDBConfigError, match="requires database"):
+        MongoDocumentStoreFactory(client_factory=lambda _config: FakeMongoClient()).create(
+            DataConfig.from_raw(
+                {
+                    "data": {
+                        "resources": {
+                            "mongo.content": {"type": "mongodb", "url": "mongodb://localhost"}
+                        }
+                    }
+                }
+            ).resources["mongo.content"]
+        ).get_document("profiles", "denis")
+
+
+def _catalog(factory: MongoDocumentStoreFactory) -> DataAdapterCatalog:
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(factory)
+    return catalog