muscles-data-mongodb 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,20 @@
1
+ from __future__ import annotations
2
+
3
+ from .adapter import (
4
+ MongoDBAdapterError,
5
+ MongoDBClientMissingError,
6
+ MongoDBConfigError,
7
+ MongoDBConnectionError,
8
+ MongoDocumentStoreAdapter,
9
+ MongoDocumentStoreFactory,
10
+ )
11
+
12
+
13
+ __all__ = [
14
+ "MongoDBAdapterError",
15
+ "MongoDBClientMissingError",
16
+ "MongoDBConfigError",
17
+ "MongoDBConnectionError",
18
+ "MongoDocumentStoreAdapter",
19
+ "MongoDocumentStoreFactory",
20
+ ]
@@ -0,0 +1,287 @@
1
+ from __future__ import annotations
2
+
3
+ import importlib
4
+ import threading
5
+ from collections.abc import Callable
6
+ from dataclasses import asdict
7
+ from typing import Any, Mapping
8
+ from urllib.parse import urlsplit
9
+
10
+ from muscles_data.config import DataResourceConfig
11
+ from muscles_data.errors import DataError
12
+ from muscles_data.models import DataCapability, HealthResult, InspectResult, WriteResult
13
+
14
+
15
+ _CLIENT_UNSET = object()
16
+ _ALLOWED_OPTIONS = {
17
+ "url",
18
+ "url_env",
19
+ "database",
20
+ "username",
21
+ "password",
22
+ "auth_source",
23
+ "timeout",
24
+ "timeout_ms",
25
+ "server_selection_timeout_ms",
26
+ "max_limit",
27
+ "native_client",
28
+ "tls",
29
+ }
30
+
31
+
32
+ class MongoDBAdapterError(DataError):
33
+ """Base error for MongoDB document-store adapter failures."""
34
+
35
+
36
+ class MongoDBConfigError(ValueError, MongoDBAdapterError):
37
+ """Raised when a MongoDB resource config cannot be mapped safely."""
38
+
39
+
40
+ class MongoDBClientMissingError(MongoDBAdapterError):
41
+ """Raised when MongoDB adapter is used without an available client."""
42
+
43
+
44
+ class MongoDBConnectionError(MongoDBAdapterError):
45
+ """Raised when a MongoDB operation cannot reach or use the backend."""
46
+
47
+
48
+ class MongoDocumentStoreAdapter:
49
+ resource_type = "mongodb"
50
+
51
+ def __init__(
52
+ self,
53
+ config: DataResourceConfig,
54
+ *,
55
+ client_factory: Callable[[DataResourceConfig], Any] | None = None,
56
+ ) -> None:
57
+ self.config = config
58
+ self._client_factory = client_factory
59
+ self._client: Any = _CLIENT_UNSET
60
+ self._lock = threading.RLock()
61
+ self.closed = False
62
+
63
+ def get_document(self, collection: str, document_id: str) -> Mapping[str, Any] | None:
64
+ try:
65
+ raw = self._collection(collection).find_one({"_id": str(document_id)})
66
+ except (MongoDBClientMissingError, MongoDBConfigError):
67
+ raise
68
+ except Exception as exc:
69
+ raise MongoDBConnectionError(self._safe_error(exc)) from exc
70
+ return _public_document(raw)
71
+
72
+ def upsert_document(self, collection: str, document_id: str, document: Mapping[str, Any]) -> WriteResult:
73
+ stored = _storage_document(document, document_id)
74
+ try:
75
+ result = self._collection(collection).replace_one({"_id": str(document_id)}, stored, upsert=True)
76
+ except (MongoDBClientMissingError, MongoDBConfigError):
77
+ raise
78
+ except Exception as exc:
79
+ raise MongoDBConnectionError(self._safe_error(exc)) from exc
80
+ matched = int(getattr(result, "matched_count", 0) or 0)
81
+ return WriteResult(written=1, matched=1 if matched else 0)
82
+
83
+ def find_documents(
84
+ self,
85
+ collection: str,
86
+ filters: Mapping[str, Any] | None = None,
87
+ limit: int = 100,
88
+ options: Mapping[str, Any] | None = None,
89
+ ) -> list[Mapping[str, Any]]:
90
+ options = dict(options or {})
91
+ query = dict(filters or {})
92
+ bounded_limit = self._bounded_limit(limit)
93
+ try:
94
+ cursor = self._collection(collection).find(query)
95
+ if "sort" in options:
96
+ cursor = cursor.sort(options["sort"])
97
+ if "skip" in options:
98
+ cursor = cursor.skip(max(0, int(options["skip"])))
99
+ cursor = cursor.limit(bounded_limit)
100
+ return [document for document in (_public_document(item) for item in cursor) if document is not None]
101
+ except (MongoDBClientMissingError, MongoDBConfigError):
102
+ raise
103
+ except Exception as exc:
104
+ raise MongoDBConnectionError(self._safe_error(exc)) from exc
105
+
106
+ def delete_document(self, collection: str, document_id: str) -> WriteResult:
107
+ try:
108
+ result = self._collection(collection).delete_one({"_id": str(document_id)})
109
+ except (MongoDBClientMissingError, MongoDBConfigError):
110
+ raise
111
+ except Exception as exc:
112
+ raise MongoDBConnectionError(self._safe_error(exc)) from exc
113
+ deleted = int(getattr(result, "deleted_count", 0) or 0)
114
+ return WriteResult(deleted=deleted, matched=deleted)
115
+
116
+ def inspect(self) -> dict[str, Any]:
117
+ return asdict(
118
+ InspectResult(
119
+ name=self.config.name,
120
+ type=self.config.type,
121
+ capabilities=[],
122
+ initialized=self._client is not _CLIENT_UNSET,
123
+ status="ok",
124
+ options=self.config.safe_options(),
125
+ details={"backend": "mongodb", "database": self.database_name(), "max_limit": self.max_limit()},
126
+ )
127
+ )
128
+
129
+ def health(self) -> HealthResult:
130
+ try:
131
+ self._client_instance().admin.command("ping")
132
+ except Exception as exc:
133
+ return HealthResult(status="failed", message=self._safe_error(exc), details={"database": self.database_name()})
134
+ return HealthResult(status="ok", message="MongoDB connection is available", details={"database": self.database_name()})
135
+
136
+ def close(self) -> None:
137
+ if self._client is _CLIENT_UNSET:
138
+ self.closed = True
139
+ return
140
+ close = getattr(self._client, "close", None)
141
+ if callable(close):
142
+ close()
143
+ self.closed = True
144
+
145
+ def native_client(self):
146
+ return self._client_instance()
147
+
148
+ def database_name(self) -> str:
149
+ database = str(self.config.options.get("database", "")).strip()
150
+ if not database:
151
+ raise MongoDBConfigError("MongoDB resource requires database")
152
+ return database
153
+
154
+ def max_limit(self) -> int:
155
+ value = int(self.config.options.get("max_limit", 100))
156
+ if value <= 0:
157
+ raise MongoDBConfigError("MongoDB max_limit must be positive")
158
+ return value
159
+
160
+ def _bounded_limit(self, limit: int) -> int:
161
+ return min(max(0, int(limit)), self.max_limit())
162
+
163
+ def _collection(self, collection: str):
164
+ name = _collection_name(collection)
165
+ return self._client_instance()[self.database_name()][name]
166
+
167
+ def _client_instance(self):
168
+ if self._client is _CLIENT_UNSET:
169
+ with self._lock:
170
+ if self._client is _CLIENT_UNSET:
171
+ self._validate_options()
172
+ client = (
173
+ self._client_factory(self.config)
174
+ if self._client_factory
175
+ else _default_mongo_client(self.config)
176
+ )
177
+ if client is None:
178
+ raise MongoDBClientMissingError("MongoDB client is not available")
179
+ self._client = client
180
+ return self._client
181
+
182
+ def _validate_options(self) -> None:
183
+ unknown = sorted(set(self.config.options) - _ALLOWED_OPTIONS)
184
+ if unknown:
185
+ names = ", ".join(unknown)
186
+ raise MongoDBConfigError(f"Unsupported MongoDB resource options: {names}")
187
+ if not self.config.options.get("url") and not self.config.options.get("url_env"):
188
+ raise MongoDBConfigError("MongoDB resource requires url or url_env")
189
+ self.database_name()
190
+ self.max_limit()
191
+
192
+ def _safe_error(self, exc: Exception) -> str:
193
+ message = str(exc)
194
+ try:
195
+ options = self.config.resolved_options()
196
+ except Exception:
197
+ options = self.config.options
198
+ sensitive_values = {
199
+ str(options.get("url", "")),
200
+ str(options.get("username", "")),
201
+ str(options.get("password", "")),
202
+ }
203
+ try:
204
+ parsed = urlsplit(str(options.get("url", "")))
205
+ if parsed.username:
206
+ sensitive_values.add(parsed.username)
207
+ if parsed.password:
208
+ sensitive_values.add(parsed.password)
209
+ except Exception: # pragma: no cover
210
+ pass
211
+ for value in sorted((item for item in sensitive_values if item), key=len, reverse=True):
212
+ message = message.replace(value, "***")
213
+ return message
214
+
215
+
216
+ class MongoDocumentStoreFactory:
217
+ resource_type = "mongodb"
218
+
219
+ def __init__(self, *, client_factory: Callable[[DataResourceConfig], Any] | None = None) -> None:
220
+ self._client_factory = client_factory
221
+
222
+ def capabilities(self, config: DataResourceConfig) -> set[DataCapability]:
223
+ native = {DataCapability.NATIVE_CLIENT} if bool(config.options.get("native_client")) else set()
224
+ return {DataCapability.DOCUMENT_STORE, DataCapability.HEALTHCHECK} | native
225
+
226
+ def create(self, config: DataResourceConfig) -> MongoDocumentStoreAdapter:
227
+ return MongoDocumentStoreAdapter(config, client_factory=self._client_factory)
228
+
229
+
230
+ def _default_mongo_client(config: DataResourceConfig):
231
+ try:
232
+ pymongo = importlib.import_module("pymongo")
233
+ except ImportError as exc:
234
+ raise MongoDBClientMissingError("pymongo package is not installed") from exc
235
+ client_cls = getattr(pymongo, "MongoClient", None)
236
+ if client_cls is None:
237
+ raise MongoDBClientMissingError("pymongo does not expose MongoClient")
238
+
239
+ try:
240
+ options = config.resolved_options()
241
+ except Exception as exc:
242
+ raise MongoDBConfigError(str(exc)) from exc
243
+
244
+ kwargs: dict[str, Any] = {}
245
+ if "timeout" in options:
246
+ timeout_ms = int(float(options["timeout"]) * 1000)
247
+ kwargs["timeoutMS"] = timeout_ms
248
+ kwargs["serverSelectionTimeoutMS"] = timeout_ms
249
+ if "timeout_ms" in options:
250
+ kwargs["timeoutMS"] = int(options["timeout_ms"])
251
+ if "server_selection_timeout_ms" in options:
252
+ kwargs["serverSelectionTimeoutMS"] = int(options["server_selection_timeout_ms"])
253
+ if "username" in options:
254
+ kwargs["username"] = options["username"]
255
+ if "password" in options:
256
+ kwargs["password"] = options["password"]
257
+ if "auth_source" in options:
258
+ kwargs["authSource"] = options["auth_source"]
259
+ if "tls" in options:
260
+ kwargs["tls"] = bool(options["tls"])
261
+ return client_cls(str(options["url"]), **kwargs)
262
+
263
+
264
+ def _collection_name(value: str) -> str:
265
+ name = str(value).strip()
266
+ if not name:
267
+ raise MongoDBConfigError("MongoDB collection name must not be empty")
268
+ if "\x00" in name:
269
+ raise MongoDBConfigError("MongoDB collection name must not contain null bytes")
270
+ return name
271
+
272
+
273
+ def _storage_document(document: Mapping[str, Any], document_id: str) -> dict[str, Any]:
274
+ stored = dict(document)
275
+ existing_id = stored.get("_id")
276
+ if existing_id is not None and str(existing_id) != str(document_id):
277
+ raise MongoDBConfigError("MongoDB document _id must match document_id")
278
+ stored["_id"] = str(document_id)
279
+ return stored
280
+
281
+
282
+ def _public_document(raw: Mapping[str, Any] | None) -> dict[str, Any] | None:
283
+ if raw is None:
284
+ return None
285
+ document = dict(raw)
286
+ document.pop("_id", None)
287
+ return document
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: muscles-data-mongodb
3
+ Version: 0.1.0
4
+ Summary: MongoDB DocumentStorePort adapter for muscles-data
5
+ Author-email: "Denis B." <denis@butko.info>
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: muscles-data<1.0.0,>=0.1.0
9
+ Requires-Dist: pymongo<5.0,>=4.0
10
+ Provides-Extra: dev
11
+ Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
12
+
13
+ # muscles-data-mongodb
14
+
15
+ MongoDB adapter package for `muscles-data`.
16
+
17
+ This package is intentionally separate from `muscles-data`: the core package
18
+ owns typed ports and runtime, while this package owns the PyMongo-backed
19
+ `DocumentStorePort` adapter.
20
+
21
+ ## Related packages
22
+
23
+ - Core runtime and port contracts:
24
+ [`muscles-data`](https://github.com/butkoden/muscles-data)
25
+ - Elasticsearch search adapter:
26
+ [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
27
+ - OpenSearch search adapter:
28
+ [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
29
+ - Redis key-value/lock/stream adapter:
30
+ [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
31
+ - Qdrant vector adapter:
32
+ [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
33
+ - S3 object-store adapter:
34
+ [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
35
+ - SQLAlchemy direct SQL resource adapter:
36
+ [`muscles-data-sqlalchemy`](https://github.com/butkoden/muscles-data-sqlalchemy)
37
+ - Executable example:
38
+ [`example_data_mongodb_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_mongodb_1)
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ python -m pip install muscles-data-mongodb
44
+ ```
45
+
46
+ For local framework development:
47
+
48
+ ```bash
49
+ PYTHONPATH=../muscles-data/src:src python3 -m pytest -q
50
+ ```
51
+
52
+ ## Configuration
53
+
54
+ ```yaml
55
+ data:
56
+ resources:
57
+ mongo.content:
58
+ type: mongodb
59
+ url: ${MONGO_URL}
60
+ database: content
61
+ timeout: 3
62
+ max_limit: 100
63
+ ```
64
+
65
+ ## Usage
66
+
67
+ Register the external factory in the project composition root:
68
+
69
+ ```python
70
+ from muscles_data.catalog import DataAdapterCatalog
71
+ from muscles_data.config import DataConfig
72
+ from muscles_data.ports import DocumentStorePort
73
+ from muscles_data.runtime import DataRuntime
74
+ from muscles_data_mongodb import MongoDocumentStoreFactory
75
+
76
+ catalog = DataAdapterCatalog.with_defaults()
77
+ catalog.register(MongoDocumentStoreFactory())
78
+
79
+ runtime = DataRuntime(config=DataConfig.from_raw(config), catalog=catalog)
80
+ store = runtime.require_port("mongo.content", DocumentStorePort)
81
+ ```
82
+
83
+ Then use the narrow port:
84
+
85
+ ```python
86
+ store.upsert_document("profiles", "denis", {"name": "Denis"})
87
+ document = store.get_document("profiles", "denis")
88
+ documents = store.find_documents("profiles", filters={"role": "developer"}, limit=20)
89
+ store.delete_document("profiles", "denis")
90
+ ```
91
+
92
+ The adapter maps `document_id` to MongoDB `_id` internally and returns public
93
+ documents without `_id` to keep the port backend-neutral.
94
+
95
+ ## Capabilities
96
+
97
+ `MongoDocumentStoreFactory` provides:
98
+
99
+ - `document_store`;
100
+ - `healthcheck`;
101
+ - `native_client` only when the resource declares `native_client: true`.
102
+
103
+ Native access is an advanced project escape hatch:
104
+
105
+ ```python
106
+ from muscles_data import DataCapability
107
+
108
+ client = runtime.require_resource("mongo.content", DataCapability.NATIVE_CLIENT).native_client()
109
+ ```
110
+
111
+ Use the native client for backend-specific aggregations, indexes or operations
112
+ that do not belong in `DocumentStorePort`.
113
+
114
+ ## Boundaries
115
+
116
+ This package owns:
117
+
118
+ - lazy PyMongo client creation;
119
+ - database binding;
120
+ - simple document get/find/upsert/delete;
121
+ - safe `inspect()` and `doctor()`;
122
+ - bounded `find_documents()` limits.
123
+
124
+ It does not own:
125
+
126
+ - ORM/document model layers;
127
+ - schema validation;
128
+ - migrations;
129
+ - complex aggregation abstraction;
130
+ - business repository APIs.
131
+
132
+ `data.doctor` performs a MongoDB `ping`. `data.resources.list` and package
133
+ initialization do not open a MongoDB connection.
@@ -0,0 +1,6 @@
1
+ muscles_data_mongodb/__init__.py,sha256=-UTKoJgq1tm5DzYMuJBIVIrRZ6DxtLq_vwpgHWAaWjE,429
2
+ muscles_data_mongodb/adapter.py,sha256=X5co8R1nzI5Ld1bNW25ZCLh0QE_y01dH7iCOFepqhIo,10770
3
+ muscles_data_mongodb-0.1.0.dist-info/METADATA,sha256=re1S3jECoU2DCq7qafXx3zBGt9nRH5jpeB8DynxFZ_0,3843
4
+ muscles_data_mongodb-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
5
+ muscles_data_mongodb-0.1.0.dist-info/top_level.txt,sha256=95a9Q-BdlAvZVwsTOjnFYx3GJxjmfL4T0rFY1OQi0Yg,21
6
+ muscles_data_mongodb-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (83.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ muscles_data_mongodb