Vishesh 'ironeagle' Bangotra
49a00351bb
- mongo-ops now serves /mongo-ops/wiki/ and /mongo-ops/lib/ independently - add mongo-ops MCP bundle under mcp/mongo-ops - fix copy-paste mcp server (jwtlib -> mongo_ops) in config.yml - .drone.yml/Dockerfile: publish port 8007 for mongo-ops MCP
1 line
121 KiB
JSON
1 line
121 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"mongo_ops","text":""},{"location":"#mongo_ops","title":"mongo_ops","text":""},{"location":"#mongo_ops--summary","title":"Summary","text":"<p>mongo-ops: A modular MongoDB operations layer for FastAPI microservices.</p> <p>This package provide a standardized way to interact with MongoDB in async Python applications, particularly optimized for FastAPI. It includes:</p> <ul> <li>Connection Management: Async lifecycle management for Motor clients.</li> <li>Base Models: Pydantic v2 models for MongoDB documents.</li> <li>Repository Pattern: Generic CRUD operations and base repository classes.</li> <li>Caching: In-memory and Redis cache backends with ID-based caching.</li> <li>Population: Recursive document populating with cycle detection.</li> <li>Transactions: Helpers for multi-document ACID transactions.</li> <li>Registry: Centralized model, index, and cache lifecycle management.</li> </ul> Example <pre><code>from mongo_ops import BaseDocument, BaseRepository, CachedBaseRepository\nfrom mongo_ops.cache import InMemoryCacheBackend, CacheConfig\n\nclass User(BaseDocument):\n username: str\n\nclass UserRepository(BaseRepository[User]):\n def __init__(self):\n super().__init__(\"users\", User)\n\n# With caching:\ncache = InMemoryCacheBackend()\nclass CachedUserRepo(CachedBaseRepository[User]):\n def __init__(self):\n super().__init__(\"users\", User, cache)\n</code></pre>"},{"location":"#mongo_ops-classes","title":"Classes","text":""},{"location":"#mongo_ops.BaseDocument","title":"BaseDocument","text":"<p> Bases: <code>BaseModel</code></p> <p>Base document class with common MongoDB fields.</p> <p>Inherit from this class to create Pydantic models that represent MongoDB documents. It includes automatic handling of the <code>_id</code> field and timestamps.</p> <p>Attributes:</p> Name Type Description <code>id</code> <code>PyObjectId | None</code> <p>The MongoDB document ID (aliased to <code>_id</code>).</p> <code>created_at</code> <code>datetime</code> <p>Timestamp when the document was created.</p> <code>updated_at</code> <code>datetime</code> <p>Timestamp when the document was last updated.</p>"},{"location":"#mongo_ops.BaseRepository","title":"BaseRepository","text":"<pre><code>BaseRepository(collection_name: str, model: type[T])\n</code></pre> <p> Bases: <code>CRUDMixin[T]</code>, <code>Generic[T]</code></p> <p>Base repository class combining CRUD operations and collection management.</p> <p>This class simplifies repository creation by automatically obtaining the database connection and collection instance.</p> <p>Attributes:</p> Name Type Description <code>collection_name</code> <code>str</code> <p>The name of the collection managed by this repository.</p> <p>Initialize the repository.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>The name of the MongoDB collection.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class.</p> required"},{"location":"#mongo_ops.BaseRepository-functions","title":"Functions","text":""},{"location":"#mongo_ops.BaseRepository.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"#mongo_ops.BaseRepository.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Create a new document in the collection.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The Pydantic model instance to insert.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created Pydantic model instance, including the assigned ID.</p>"},{"location":"#mongo_ops.BaseRepository.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"#mongo_ops.BaseRepository.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Retrieve a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The Pydantic model instance if found, else None.</p>"},{"location":"#mongo_ops.BaseRepository.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"#mongo_ops.BaseRepository.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document using $set (REST PATCH semantics).</p> <p>Unlike update(), patch() takes a partial dict and applies only those fields. PopulatingRepository overrides this to prevent patching FK fields.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A partial dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p>"},{"location":"#mongo_ops.BaseRepository.update","title":"update <code>async</code>","text":"<pre><code>update(\n id: str | ObjectId, data: dict[str, Any]\n) -> T | None\n</code></pre> <p>Update a document by its ID using the $set operator.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p> Example <pre><code>updated_user = await repo.update(user_id, {\"email\": \"new@example.com\"})\n</code></pre>"},{"location":"#mongo_ops.CRUDMixin","title":"CRUDMixin","text":"<pre><code>CRUDMixin(\n collection: AsyncIOMotorCollection, model: type[T]\n)\n</code></pre> <p> Bases: <code>Generic[T]</code></p> <p>Generic CRUD operations mixin for MongoDB collections.</p> <p>This mixin provides standard Create, Read, Update, and Delete operations that work with Pydantic models.</p> <p>Attributes:</p> Name Type Description <code>collection</code> <code>AsyncIOMotorCollection</code> <p>The Motor collection instance.</p> <code>model</code> <code>type[T]</code> <p>The Pydantic model class representing the document.</p> <p>Initialize the CRUD mixin.</p> <p>Parameters:</p> Name Type Description Default <code>collection</code> <code>AsyncIOMotorCollection</code> <p>The Motor collection to operate on.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class (subclass of BaseDocument).</p> required"},{"location":"#mongo_ops.CRUDMixin-functions","title":"Functions","text":""},{"location":"#mongo_ops.CRUDMixin.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"#mongo_ops.CRUDMixin.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Create a new document in the collection.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The Pydantic model instance to insert.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created Pydantic model instance, including the assigned ID.</p>"},{"location":"#mongo_ops.CRUDMixin.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"#mongo_ops.CRUDMixin.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Retrieve a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The Pydantic model instance if found, else None.</p>"},{"location":"#mongo_ops.CRUDMixin.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"#mongo_ops.CRUDMixin.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document using $set (REST PATCH semantics).</p> <p>Unlike update(), patch() takes a partial dict and applies only those fields. PopulatingRepository overrides this to prevent patching FK fields.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A partial dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p>"},{"location":"#mongo_ops.CRUDMixin.update","title":"update <code>async</code>","text":"<pre><code>update(\n id: str | ObjectId, data: dict[str, Any]\n) -> T | None\n</code></pre> <p>Update a document by its ID using the $set operator.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p> Example <pre><code>updated_user = await repo.update(user_id, {\"email\": \"new@example.com\"})\n</code></pre>"},{"location":"#mongo_ops.CachedBaseRepository","title":"CachedBaseRepository","text":"<pre><code>CachedBaseRepository(\n collection_name: str,\n model: type[T],\n cache_backend: CacheBackend,\n config: CacheConfig | None = None,\n)\n</code></pre> <p> Bases: <code>BaseRepository[T]</code>, <code>Generic[T]</code></p> <p>Repository that reads and writes through a cache backend.</p> <p>Wraps an existing BaseRepository with an ID-keyed cache. Reads consult the backend first and fall through to MongoDB on a miss, populating the cache on success. Writes invalidate or refresh the affected key.</p> Notes <p>Guarantees:</p> <pre><code>- The cache holds the raw document shape (``model_dump``), so FK\n references round-trip as hex strings, not populated models.\n- When ``config.enabled`` is False the repository behaves exactly\n like its parent with no cache access.\n</code></pre> <p>Initialize the cached repository.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Name of the MongoDB collection.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class.</p> required <code>cache_backend</code> <code>CacheBackend</code> <p>Backend used to store and fetch entries.</p> required <code>config</code> <code>Optional[CacheConfig]</code> <p>Cache configuration; a default CacheConfig is used when None.</p> <code>None</code>"},{"location":"#mongo_ops.CachedBaseRepository-functions","title":"Functions","text":""},{"location":"#mongo_ops.CachedBaseRepository.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"#mongo_ops.CachedBaseRepository.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Insert a document and cache the raw snapshot.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The model instance to insert.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created model instance, including its ID.</p>"},{"location":"#mongo_ops.CachedBaseRepository.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document and remove its cache entry.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"#mongo_ops.CachedBaseRepository.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Fetch a document, reading through the cache when enabled.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The model instance, or None when not found.</p>"},{"location":"#mongo_ops.CachedBaseRepository.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"#mongo_ops.CachedBaseRepository.invalidate_cache","title":"invalidate_cache <code>async</code>","text":"<pre><code>invalidate_cache(id: str | ObjectId) -> None\n</code></pre> <p>Remove a single document's cache entry.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID to invalidate.</p> required"},{"location":"#mongo_ops.CachedBaseRepository.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document using $set (REST PATCH semantics).</p> <p>Unlike update(), patch() takes a partial dict and applies only those fields. PopulatingRepository overrides this to prevent patching FK fields.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A partial dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p>"},{"location":"#mongo_ops.CachedBaseRepository.update","title":"update <code>async</code>","text":"<pre><code>update(id: str | ObjectId, data: dict) -> T | None\n</code></pre> <p>Update a document and refresh its cache entry.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <code>data</code> <code>dict</code> <p>Fields to set via $set.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated model instance, or None when not found.</p>"},{"location":"#mongo_ops.CachedBaseRepository.warm_cache","title":"warm_cache <code>async</code>","text":"<pre><code>warm_cache(ids: list[str | ObjectId]) -> int\n</code></pre> <p>Pre-populate the cache for a set of document IDs.</p> <p>Docs already present in the cache are skipped.</p> <p>Parameters:</p> Name Type Description Default <code>ids</code> <code>list[Union[str, ObjectId]]</code> <p>Document IDs to warm.</p> required <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Number of entries added to the cache.</p>"},{"location":"#mongo_ops.ModelRegistry","title":"ModelRegistry","text":"<p>Registry for managing multiple models and their collections.</p> <p>This registry allows central management of collections and their associated indexes, making it easier to perform mass initialization at application startup.</p>"},{"location":"#mongo_ops.ModelRegistry-functions","title":"Functions","text":""},{"location":"#mongo_ops.ModelRegistry.get_cache_backend","title":"get_cache_backend <code>classmethod</code>","text":"<pre><code>get_cache_backend() -> CacheBackend | None\n</code></pre> <p>Get the registered cache backend instance.</p> <p>Returns:</p> Type Description <code>CacheBackend | None</code> <p>Optional[CacheBackend]: The cache backend, if registered.</p>"},{"location":"#mongo_ops.ModelRegistry.get_model","title":"get_model <code>classmethod</code>","text":"<pre><code>get_model(collection_name: str) -> type[BaseDocument]\n</code></pre> <p>Retrieve a registered model by its collection name.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>The name of the collection.</p> required <p>Returns:</p> Type Description <code>type[BaseDocument]</code> <p>type[BaseDocument]: The registered model class.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the model for the given collection is not registered.</p>"},{"location":"#mongo_ops.ModelRegistry.initialize_all","title":"initialize_all <code>async</code> <code>classmethod</code>","text":"<pre><code>initialize_all(\n db: AsyncIOMotorDatabase | None = None,\n) -> None\n</code></pre> <p>Initialize all registered collections and create indexes.</p> <p>This method should be called during application startup to ensure all necessary indexes exist in the database.</p> <p>Parameters:</p> Name Type Description Default <code>db</code> <code>Optional[AsyncIOMotorDatabase]</code> <p>Database instance. If not provided, uses the global database from MongoConnectionManager.</p> <code>None</code>"},{"location":"#mongo_ops.ModelRegistry.initialize_cache","title":"initialize_cache <code>async</code> <code>classmethod</code>","text":"<pre><code>initialize_cache() -> None\n</code></pre> <p>Initialize the registered cache backend.</p> <p>Must be called after set_cache_backend() and before any cache-backed repository operations. Typically called right after MongoDB connection is established.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If no cache backend has been registered.</p>"},{"location":"#mongo_ops.ModelRegistry.list_collections","title":"list_collections <code>classmethod</code>","text":"<pre><code>list_collections() -> list[str]\n</code></pre> <p>List all registered collection names.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list of collection names.</p>"},{"location":"#mongo_ops.ModelRegistry.register","title":"register <code>classmethod</code>","text":"<pre><code>register(\n collection_name: str,\n model: type[BaseDocument],\n indexes: list[tuple] | None = None,\n) -> None\n</code></pre> <p>Register a model with its collection and indexes.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Name of the MongoDB collection.</p> required <code>model</code> <code>type[BaseDocument]</code> <p>Document model class (subclass of BaseDocument).</p> required <code>indexes</code> <code>list[Any]</code> <p>List of index specifications. Each spec is passed directly to pymongo's create_index. Supported forms: - single field: (\"email\", 1) - compound: [(\"author_id\", 1), (\"created_at\", -1)] - with options: {\"keys\": [(\"username\", 1)], \"options\": {\"unique\": True}}</p> <code>None</code> Example <p>ModelRegistry.register(\"users\", UserDocument, indexes=[(\"email\", 1)]) ModelRegistry.register( \"posts\", PostDocument, indexes=[[(\"author_id\", 1), (\"created_at\", -1)]], )</p>"},{"location":"#mongo_ops.ModelRegistry.set_cache_backend","title":"set_cache_backend <code>classmethod</code>","text":"<pre><code>set_cache_backend(backend: CacheBackend) -> None\n</code></pre> <p>Register a cache backend for all cache-enabled repositories.</p> <p>Should be called after MongoDB connection is established, before cache-backed repositories are used.</p> <p>Parameters:</p> Name Type Description Default <code>backend</code> <code>CacheBackend</code> <p>A CacheBackend instance (InMemoryCacheBackend or RedisCacheBackend).</p> required"},{"location":"#mongo_ops.ModelRegistry.shutdown_cache","title":"shutdown_cache <code>async</code> <code>classmethod</code>","text":"<pre><code>shutdown_cache() -> None\n</code></pre> <p>Shutdown the registered cache backend gracefully.</p> <p>Should be called during application shutdown to clean up background tasks (e.g., in-memory TTL cleanup).</p>"},{"location":"#mongo_ops.MongoConnectionManager","title":"MongoConnectionManager","text":"<p>Manages MongoDB connections with async lifecycle.</p> <p>This class provides a singleton-like manager for the MongoDB client and database instances, ensuring they are properly initialized and closed across the application lifecycle.</p>"},{"location":"#mongo_ops.MongoConnectionManager-functions","title":"Functions","text":""},{"location":"#mongo_ops.MongoConnectionManager.connect","title":"connect <code>async</code> <code>classmethod</code>","text":"<pre><code>connect(\n uri: str, db_name: str, **kwargs: Any\n) -> AsyncIOMotorDatabase\n</code></pre> <p>Connect to MongoDB and initialize the shared client.</p> <p>Parameters:</p> Name Type Description Default <code>uri</code> <code>str</code> <p>MongoDB connection URI (e.g., \"mongodb://localhost:27017\").</p> required <code>db_name</code> <code>str</code> <p>Name of the database to use.</p> required <code>**kwargs</code> <code>Any</code> <p>Additional Motor client options (e.g., maxPoolSize).</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>AsyncIOMotorDatabase</code> <code>AsyncIOMotorDatabase</code> <p>The initialized database instance.</p>"},{"location":"#mongo_ops.MongoConnectionManager.disconnect","title":"disconnect <code>async</code> <code>classmethod</code>","text":"<pre><code>disconnect() -> None\n</code></pre> <p>Close the active MongoDB connection and cleanup resources.</p>"},{"location":"#mongo_ops.MongoConnectionManager.get_client","title":"get_client <code>classmethod</code>","text":"<pre><code>get_client() -> AsyncIOMotorClient\n</code></pre> <p>Retrieve the current client instance.</p> <p>Returns:</p> Name Type Description <code>AsyncIOMotorClient</code> <code>AsyncIOMotorClient</code> <p>The active Motor client instance.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If connect() has not been called yet.</p>"},{"location":"#mongo_ops.MongoConnectionManager.get_database","title":"get_database <code>classmethod</code>","text":"<pre><code>get_database() -> AsyncIOMotorDatabase\n</code></pre> <p>Retrieve the current database instance.</p> <p>Returns:</p> Name Type Description <code>AsyncIOMotorDatabase</code> <code>AsyncIOMotorDatabase</code> <p>The active database instance.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If connect() has not been called yet.</p>"},{"location":"#mongo_ops.MongoConnectionManager.lifespan","title":"lifespan <code>async</code> <code>classmethod</code>","text":"<pre><code>lifespan(\n uri: str, db_name: str, **kwargs: Any\n) -> AbstractAsyncContextManager[AsyncIOMotorDatabase]\n</code></pre> <p>Async context manager for managing connection lifecycle.</p> <p>Designed for use with FastAPI or other frameworks supporting lifespan management.</p> Notes <p>Connects to MongoDB on entry, yields the active database instance to the context body, and disconnects on exit.</p> Usage <p>@asynccontextmanager async def lifespan(app: FastAPI): async with MongoConnectionManager.lifespan(uri, db_name): yield</p>"},{"location":"#mongo_ops.PopulatingRepository","title":"PopulatingRepository","text":"<pre><code>PopulatingRepository(\n collection_name: str,\n model: type[T],\n population_engine: PopulationEngine | None = None,\n populate_rules: list[PopulateRule] | None = None,\n)\n</code></pre> <p> Bases: <code>BaseRepository[T]</code>, <code>Generic[T]</code></p> <p>Repository that auto-populates and depopulates FK references.</p> <p>On read, ObjectId FK fields are resolved to model instances according to the configured PopulateRules. On write, populated model references are collapsed back to ObjectIds before hitting MongoDB.</p> Notes <p>Guarantees:</p> <pre><code>- Populate rules apply on both read (data_to_model) and write\n (create/update) paths.\n- Patching FK fields via patch() is rejected.\n- Class attributes `population_engine` and `_populate_rules` must\n be set (see set_population_engine/set_populate_rules) for any\n population to occur.\n</code></pre> <p>Initialize the repository.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Name of the MongoDB collection.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class.</p> required <code>population_engine</code> <code>Optional[PopulationEngine]</code> <p>Engine used to resolve references. Defaults to None.</p> <code>None</code> <code>populate_rules</code> <code>Optional[list[PopulateRule]]</code> <p>Rules describing FK resolution. Defaults to None (no rules).</p> <code>None</code>"},{"location":"#mongo_ops.PopulatingRepository-functions","title":"Functions","text":""},{"location":"#mongo_ops.PopulatingRepository.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"#mongo_ops.PopulatingRepository.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Depopulate, insert, and re-populate a new document.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The model instance to insert (FK fields may hold models).</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created model instance, including its ID.</p>"},{"location":"#mongo_ops.PopulatingRepository.data_to_model","title":"data_to_model <code>async</code>","text":"<pre><code>data_to_model(data: dict) -> T\n</code></pre> <p>Convert a raw dict to a model, resolving FK references first.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>dict</code> <p>Raw document dictionary.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The populated model instance.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If a FK field holds an embedded dict instead of an ObjectId.</p>"},{"location":"#mongo_ops.PopulatingRepository.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"#mongo_ops.PopulatingRepository.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Retrieve a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The Pydantic model instance if found, else None.</p>"},{"location":"#mongo_ops.PopulatingRepository.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"#mongo_ops.PopulatingRepository.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document, rejecting FK field changes.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <code>data</code> <code>dict[str, Any]</code> <p>Partial dictionary of fields to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated model instance, or None when not found.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If any FK field is present in the patch payload.</p>"},{"location":"#mongo_ops.PopulatingRepository.set_populate_rules","title":"set_populate_rules","text":"<pre><code>set_populate_rules(rules: list[PopulateRule]) -> None\n</code></pre> <p>Set the FK resolution rules.</p> <p>Parameters:</p> Name Type Description Default <code>rules</code> <code>list[PopulateRule]</code> <p>Rules describing which fields resolve and how deep.</p> required"},{"location":"#mongo_ops.PopulatingRepository.set_population_engine","title":"set_population_engine","text":"<pre><code>set_population_engine(engine: PopulationEngine) -> None\n</code></pre> <p>Attach (or replace) the population engine.</p> <p>Parameters:</p> Name Type Description Default <code>engine</code> <code>PopulationEngine</code> <p>Engine used to resolve references.</p> required"},{"location":"#mongo_ops.PopulatingRepository.update","title":"update <code>async</code>","text":"<pre><code>update(id: str | ObjectId, data: T) -> T | None\n</code></pre> <p>Depopulate and update a document by ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <code>data</code> <code>T</code> <p>The model instance holding the updated fields.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated model instance, or None when not found.</p>"},{"location":"#mongo_ops.TransactionManager","title":"TransactionManager","text":"<p>Simplified multi-document transaction handling.</p> <p>This class provides helpers for executing operations within a MongoDB transaction, ensuring ACID compliance for multi-document updates.</p>"},{"location":"#mongo_ops.TransactionManager-functions","title":"Functions","text":""},{"location":"#mongo_ops.TransactionManager.execute_transaction","title":"execute_transaction <code>async</code> <code>classmethod</code>","text":"<pre><code>execute_transaction(\n operations: list[\n Callable[\n [AsyncIOMotorClientSession], Awaitable[Any]\n ]\n ],\n **kwargs: Any\n) -> list[Any]\n</code></pre> <p>Execute multiple operations within a single transaction.</p> <p>Parameters:</p> Name Type Description Default <code>operations</code> <code>List[Callable[[AsyncIOMotorClientSession], Awaitable[Any]]]</code> <p>A list of async callables that accept a session parameter and return a result.</p> required <code>**kwargs</code> <code>Any</code> <p>Transaction options.</p> <code>{}</code> <p>Returns:</p> Type Description <code>list[Any]</code> <p>List[Any]: A list containing the results of each operation.</p> Example <p>results = await TransactionManager.execute_transaction([ lambda s: repo1.create(data1, session=s), lambda s: repo2.update(id, data2, session=s), ])</p>"},{"location":"#mongo_ops.TransactionManager.start_session","title":"start_session <code>async</code> <code>classmethod</code>","text":"<pre><code>start_session(\n **kwargs: Any,\n) -> AbstractAsyncContextManager[AsyncIOMotorClientSession]\n</code></pre> <p>Start a transaction session as an async context manager.</p> Notes <p>Yields the active session with a started transaction; callers run their operations against the session inside the with-block.</p> Usage <p>async with TransactionManager.start_session() as session: await collection.insert_one(doc, session=session) await other_collection.update_one(filter, update, session=session)</p>"},{"location":"connection/","title":"Connection","text":""},{"location":"connection/#mongo_ops.connection","title":"mongo_ops.connection","text":""},{"location":"connection/#mongo_ops.connection--summary","title":"Summary","text":"<p>MongoDB connection management.</p>"},{"location":"connection/#mongo_ops.connection-classes","title":"Classes","text":""},{"location":"connection/#mongo_ops.connection.MongoConnectionManager","title":"MongoConnectionManager","text":"<p>Manages MongoDB connections with async lifecycle.</p> <p>This class provides a singleton-like manager for the MongoDB client and database instances, ensuring they are properly initialized and closed across the application lifecycle.</p>"},{"location":"connection/#mongo_ops.connection.MongoConnectionManager-functions","title":"Functions","text":""},{"location":"connection/#mongo_ops.connection.MongoConnectionManager.connect","title":"connect <code>async</code> <code>classmethod</code>","text":"<pre><code>connect(\n uri: str, db_name: str, **kwargs: Any\n) -> AsyncIOMotorDatabase\n</code></pre> <p>Connect to MongoDB and initialize the shared client.</p> <p>Parameters:</p> Name Type Description Default <code>uri</code> <code>str</code> <p>MongoDB connection URI (e.g., \"mongodb://localhost:27017\").</p> required <code>db_name</code> <code>str</code> <p>Name of the database to use.</p> required <code>**kwargs</code> <code>Any</code> <p>Additional Motor client options (e.g., maxPoolSize).</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>AsyncIOMotorDatabase</code> <code>AsyncIOMotorDatabase</code> <p>The initialized database instance.</p>"},{"location":"connection/#mongo_ops.connection.MongoConnectionManager.disconnect","title":"disconnect <code>async</code> <code>classmethod</code>","text":"<pre><code>disconnect() -> None\n</code></pre> <p>Close the active MongoDB connection and cleanup resources.</p>"},{"location":"connection/#mongo_ops.connection.MongoConnectionManager.get_client","title":"get_client <code>classmethod</code>","text":"<pre><code>get_client() -> AsyncIOMotorClient\n</code></pre> <p>Retrieve the current client instance.</p> <p>Returns:</p> Name Type Description <code>AsyncIOMotorClient</code> <code>AsyncIOMotorClient</code> <p>The active Motor client instance.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If connect() has not been called yet.</p>"},{"location":"connection/#mongo_ops.connection.MongoConnectionManager.get_database","title":"get_database <code>classmethod</code>","text":"<pre><code>get_database() -> AsyncIOMotorDatabase\n</code></pre> <p>Retrieve the current database instance.</p> <p>Returns:</p> Name Type Description <code>AsyncIOMotorDatabase</code> <code>AsyncIOMotorDatabase</code> <p>The active database instance.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If connect() has not been called yet.</p>"},{"location":"connection/#mongo_ops.connection.MongoConnectionManager.lifespan","title":"lifespan <code>async</code> <code>classmethod</code>","text":"<pre><code>lifespan(\n uri: str, db_name: str, **kwargs: Any\n) -> AbstractAsyncContextManager[AsyncIOMotorDatabase]\n</code></pre> <p>Async context manager for managing connection lifecycle.</p> <p>Designed for use with FastAPI or other frameworks supporting lifespan management.</p> Notes <p>Connects to MongoDB on entry, yields the active database instance to the context body, and disconnects on exit.</p> Usage <p>@asynccontextmanager async def lifespan(app: FastAPI): async with MongoConnectionManager.lifespan(uri, db_name): yield</p>"},{"location":"models/","title":"Models","text":""},{"location":"models/#mongo_ops.models","title":"mongo_ops.models","text":""},{"location":"models/#mongo_ops.models--summary","title":"Summary","text":"<p>Base document models for MongoDB.</p>"},{"location":"models/#mongo_ops.models-classes","title":"Classes","text":""},{"location":"models/#mongo_ops.models.BaseDocument","title":"BaseDocument","text":"<p> Bases: <code>BaseModel</code></p> <p>Base document class with common MongoDB fields.</p> <p>Inherit from this class to create Pydantic models that represent MongoDB documents. It includes automatic handling of the <code>_id</code> field and timestamps.</p> <p>Attributes:</p> Name Type Description <code>id</code> <code>PyObjectId | None</code> <p>The MongoDB document ID (aliased to <code>_id</code>).</p> <code>created_at</code> <code>datetime</code> <p>Timestamp when the document was created.</p> <code>updated_at</code> <code>datetime</code> <p>Timestamp when the document was last updated.</p>"},{"location":"models/#mongo_ops.models.PyObjectId","title":"PyObjectId","text":"<p> Bases: <code>ObjectId</code></p> <p>Custom ObjectId type compatible with Pydantic v2.</p> <p>This class extends the standard BSON ObjectId to provide validation and serialization support within Pydantic models.</p>"},{"location":"models/#mongo_ops.models.PyObjectId-functions","title":"Functions","text":""},{"location":"models/#mongo_ops.models.PyObjectId.__get_pydantic_core_schema__","title":"__get_pydantic_core_schema__ <code>classmethod</code>","text":"<pre><code>__get_pydantic_core_schema__(\n source_type: Any, handler: GetCoreSchemaHandler\n) -> Any\n</code></pre> <p>Define the core schema for Pydantic v2 validation and serialization.</p>"},{"location":"models/#mongo_ops.models.PyObjectId.__get_pydantic_json_schema__","title":"__get_pydantic_json_schema__ <code>classmethod</code>","text":"<pre><code>__get_pydantic_json_schema__(\n schema: Any, handler: Any\n) -> Any\n</code></pre> <p>Update the JSON schema for OpenAPI/Swagger documentation.</p>"},{"location":"models/#mongo_ops.models.PyObjectId.validate","title":"validate <code>classmethod</code>","text":"<pre><code>validate(v: Any) -> ObjectId\n</code></pre> <p>Validate the input value and convert it to an ObjectId if possible.</p> <p>Parameters:</p> Name Type Description Default <code>v</code> <code>Any</code> <p>The value to validate (can be str or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>ObjectId</code> <code>ObjectId</code> <p>The validated ObjectId instance.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the value is not a valid ObjectId.</p>"},{"location":"registry/","title":"Registry","text":""},{"location":"registry/#mongo_ops.registry","title":"mongo_ops.registry","text":""},{"location":"registry/#mongo_ops.registry--summary","title":"Summary","text":"<p>Model registration for multi-service initialization.</p>"},{"location":"registry/#mongo_ops.registry-classes","title":"Classes","text":""},{"location":"registry/#mongo_ops.registry.ModelRegistry","title":"ModelRegistry","text":"<p>Registry for managing multiple models and their collections.</p> <p>This registry allows central management of collections and their associated indexes, making it easier to perform mass initialization at application startup.</p>"},{"location":"registry/#mongo_ops.registry.ModelRegistry-functions","title":"Functions","text":""},{"location":"registry/#mongo_ops.registry.ModelRegistry.get_cache_backend","title":"get_cache_backend <code>classmethod</code>","text":"<pre><code>get_cache_backend() -> CacheBackend | None\n</code></pre> <p>Get the registered cache backend instance.</p> <p>Returns:</p> Type Description <code>CacheBackend | None</code> <p>Optional[CacheBackend]: The cache backend, if registered.</p>"},{"location":"registry/#mongo_ops.registry.ModelRegistry.get_model","title":"get_model <code>classmethod</code>","text":"<pre><code>get_model(collection_name: str) -> type[BaseDocument]\n</code></pre> <p>Retrieve a registered model by its collection name.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>The name of the collection.</p> required <p>Returns:</p> Type Description <code>type[BaseDocument]</code> <p>type[BaseDocument]: The registered model class.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the model for the given collection is not registered.</p>"},{"location":"registry/#mongo_ops.registry.ModelRegistry.initialize_all","title":"initialize_all <code>async</code> <code>classmethod</code>","text":"<pre><code>initialize_all(\n db: AsyncIOMotorDatabase | None = None,\n) -> None\n</code></pre> <p>Initialize all registered collections and create indexes.</p> <p>This method should be called during application startup to ensure all necessary indexes exist in the database.</p> <p>Parameters:</p> Name Type Description Default <code>db</code> <code>Optional[AsyncIOMotorDatabase]</code> <p>Database instance. If not provided, uses the global database from MongoConnectionManager.</p> <code>None</code>"},{"location":"registry/#mongo_ops.registry.ModelRegistry.initialize_cache","title":"initialize_cache <code>async</code> <code>classmethod</code>","text":"<pre><code>initialize_cache() -> None\n</code></pre> <p>Initialize the registered cache backend.</p> <p>Must be called after set_cache_backend() and before any cache-backed repository operations. Typically called right after MongoDB connection is established.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If no cache backend has been registered.</p>"},{"location":"registry/#mongo_ops.registry.ModelRegistry.list_collections","title":"list_collections <code>classmethod</code>","text":"<pre><code>list_collections() -> list[str]\n</code></pre> <p>List all registered collection names.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list of collection names.</p>"},{"location":"registry/#mongo_ops.registry.ModelRegistry.register","title":"register <code>classmethod</code>","text":"<pre><code>register(\n collection_name: str,\n model: type[BaseDocument],\n indexes: list[tuple] | None = None,\n) -> None\n</code></pre> <p>Register a model with its collection and indexes.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Name of the MongoDB collection.</p> required <code>model</code> <code>type[BaseDocument]</code> <p>Document model class (subclass of BaseDocument).</p> required <code>indexes</code> <code>list[Any]</code> <p>List of index specifications. Each spec is passed directly to pymongo's create_index. Supported forms: - single field: (\"email\", 1) - compound: [(\"author_id\", 1), (\"created_at\", -1)] - with options: {\"keys\": [(\"username\", 1)], \"options\": {\"unique\": True}}</p> <code>None</code> Example <p>ModelRegistry.register(\"users\", UserDocument, indexes=[(\"email\", 1)]) ModelRegistry.register( \"posts\", PostDocument, indexes=[[(\"author_id\", 1), (\"created_at\", -1)]], )</p>"},{"location":"registry/#mongo_ops.registry.ModelRegistry.set_cache_backend","title":"set_cache_backend <code>classmethod</code>","text":"<pre><code>set_cache_backend(backend: CacheBackend) -> None\n</code></pre> <p>Register a cache backend for all cache-enabled repositories.</p> <p>Should be called after MongoDB connection is established, before cache-backed repositories are used.</p> <p>Parameters:</p> Name Type Description Default <code>backend</code> <code>CacheBackend</code> <p>A CacheBackend instance (InMemoryCacheBackend or RedisCacheBackend).</p> required"},{"location":"registry/#mongo_ops.registry.ModelRegistry.shutdown_cache","title":"shutdown_cache <code>async</code> <code>classmethod</code>","text":"<pre><code>shutdown_cache() -> None\n</code></pre> <p>Shutdown the registered cache backend gracefully.</p> <p>Should be called during application shutdown to clean up background tasks (e.g., in-memory TTL cleanup).</p>"},{"location":"repository/","title":"Repository","text":""},{"location":"repository/#mongo_ops.repository","title":"mongo_ops.repository","text":""},{"location":"repository/#mongo_ops.repository--summary","title":"Summary","text":"<p>Repository patterns and CRUD mixins for MongoDB.</p>"},{"location":"repository/#mongo_ops.repository-classes","title":"Classes","text":""},{"location":"repository/#mongo_ops.repository.BaseRepository","title":"BaseRepository","text":"<pre><code>BaseRepository(collection_name: str, model: type[T])\n</code></pre> <p> Bases: <code>CRUDMixin[T]</code>, <code>Generic[T]</code></p> <p>Base repository class combining CRUD operations and collection management.</p> <p>This class simplifies repository creation by automatically obtaining the database connection and collection instance.</p> <p>Attributes:</p> Name Type Description <code>collection_name</code> <code>str</code> <p>The name of the collection managed by this repository.</p> <p>Initialize the repository.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>The name of the MongoDB collection.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class.</p> required"},{"location":"repository/#mongo_ops.repository.BaseRepository-functions","title":"Functions","text":""},{"location":"repository/#mongo_ops.repository.BaseRepository.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"repository/#mongo_ops.repository.BaseRepository.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Create a new document in the collection.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The Pydantic model instance to insert.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created Pydantic model instance, including the assigned ID.</p>"},{"location":"repository/#mongo_ops.repository.BaseRepository.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"repository/#mongo_ops.repository.BaseRepository.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Retrieve a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The Pydantic model instance if found, else None.</p>"},{"location":"repository/#mongo_ops.repository.BaseRepository.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"repository/#mongo_ops.repository.BaseRepository.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document using $set (REST PATCH semantics).</p> <p>Unlike update(), patch() takes a partial dict and applies only those fields. PopulatingRepository overrides this to prevent patching FK fields.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A partial dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p>"},{"location":"repository/#mongo_ops.repository.BaseRepository.update","title":"update <code>async</code>","text":"<pre><code>update(\n id: str | ObjectId, data: dict[str, Any]\n) -> T | None\n</code></pre> <p>Update a document by its ID using the $set operator.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p> Example <pre><code>updated_user = await repo.update(user_id, {\"email\": \"new@example.com\"})\n</code></pre>"},{"location":"repository/#mongo_ops.repository.CRUDMixin","title":"CRUDMixin","text":"<pre><code>CRUDMixin(\n collection: AsyncIOMotorCollection, model: type[T]\n)\n</code></pre> <p> Bases: <code>Generic[T]</code></p> <p>Generic CRUD operations mixin for MongoDB collections.</p> <p>This mixin provides standard Create, Read, Update, and Delete operations that work with Pydantic models.</p> <p>Attributes:</p> Name Type Description <code>collection</code> <code>AsyncIOMotorCollection</code> <p>The Motor collection instance.</p> <code>model</code> <code>type[T]</code> <p>The Pydantic model class representing the document.</p> <p>Initialize the CRUD mixin.</p> <p>Parameters:</p> Name Type Description Default <code>collection</code> <code>AsyncIOMotorCollection</code> <p>The Motor collection to operate on.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class (subclass of BaseDocument).</p> required"},{"location":"repository/#mongo_ops.repository.CRUDMixin-functions","title":"Functions","text":""},{"location":"repository/#mongo_ops.repository.CRUDMixin.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"repository/#mongo_ops.repository.CRUDMixin.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Create a new document in the collection.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The Pydantic model instance to insert.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created Pydantic model instance, including the assigned ID.</p>"},{"location":"repository/#mongo_ops.repository.CRUDMixin.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"repository/#mongo_ops.repository.CRUDMixin.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Retrieve a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The Pydantic model instance if found, else None.</p>"},{"location":"repository/#mongo_ops.repository.CRUDMixin.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"repository/#mongo_ops.repository.CRUDMixin.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document using $set (REST PATCH semantics).</p> <p>Unlike update(), patch() takes a partial dict and applies only those fields. PopulatingRepository overrides this to prevent patching FK fields.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A partial dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p>"},{"location":"repository/#mongo_ops.repository.CRUDMixin.update","title":"update <code>async</code>","text":"<pre><code>update(\n id: str | ObjectId, data: dict[str, Any]\n) -> T | None\n</code></pre> <p>Update a document by its ID using the $set operator.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p> Example <pre><code>updated_user = await repo.update(user_id, {\"email\": \"new@example.com\"})\n</code></pre>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository","title":"PopulatingRepository","text":"<pre><code>PopulatingRepository(\n collection_name: str,\n model: type[T],\n population_engine: PopulationEngine | None = None,\n populate_rules: list[PopulateRule] | None = None,\n)\n</code></pre> <p> Bases: <code>BaseRepository[T]</code>, <code>Generic[T]</code></p> <p>Repository that auto-populates and depopulates FK references.</p> <p>On read, ObjectId FK fields are resolved to model instances according to the configured PopulateRules. On write, populated model references are collapsed back to ObjectIds before hitting MongoDB.</p> Notes <p>Guarantees:</p> <pre><code>- Populate rules apply on both read (data_to_model) and write\n (create/update) paths.\n- Patching FK fields via patch() is rejected.\n- Class attributes `population_engine` and `_populate_rules` must\n be set (see set_population_engine/set_populate_rules) for any\n population to occur.\n</code></pre> <p>Initialize the repository.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Name of the MongoDB collection.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class.</p> required <code>population_engine</code> <code>Optional[PopulationEngine]</code> <p>Engine used to resolve references. Defaults to None.</p> <code>None</code> <code>populate_rules</code> <code>Optional[list[PopulateRule]]</code> <p>Rules describing FK resolution. Defaults to None (no rules).</p> <code>None</code>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository-functions","title":"Functions","text":""},{"location":"repository/#mongo_ops.repository.PopulatingRepository.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Depopulate, insert, and re-populate a new document.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The model instance to insert (FK fields may hold models).</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created model instance, including its ID.</p>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.data_to_model","title":"data_to_model <code>async</code>","text":"<pre><code>data_to_model(data: dict) -> T\n</code></pre> <p>Convert a raw dict to a model, resolving FK references first.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>dict</code> <p>Raw document dictionary.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The populated model instance.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If a FK field holds an embedded dict instead of an ObjectId.</p>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Retrieve a document by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The Pydantic model instance if found, else None.</p>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document, rejecting FK field changes.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <code>data</code> <code>dict[str, Any]</code> <p>Partial dictionary of fields to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated model instance, or None when not found.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If any FK field is present in the patch payload.</p>"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.set_populate_rules","title":"set_populate_rules","text":"<pre><code>set_populate_rules(rules: list[PopulateRule]) -> None\n</code></pre> <p>Set the FK resolution rules.</p> <p>Parameters:</p> Name Type Description Default <code>rules</code> <code>list[PopulateRule]</code> <p>Rules describing which fields resolve and how deep.</p> required"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.set_population_engine","title":"set_population_engine","text":"<pre><code>set_population_engine(engine: PopulationEngine) -> None\n</code></pre> <p>Attach (or replace) the population engine.</p> <p>Parameters:</p> Name Type Description Default <code>engine</code> <code>PopulationEngine</code> <p>Engine used to resolve references.</p> required"},{"location":"repository/#mongo_ops.repository.PopulatingRepository.update","title":"update <code>async</code>","text":"<pre><code>update(id: str | ObjectId, data: T) -> T | None\n</code></pre> <p>Depopulate and update a document by ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <code>data</code> <code>T</code> <p>The model instance holding the updated fields.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated model instance, or None when not found.</p>"},{"location":"transactions/","title":"Transactions","text":""},{"location":"transactions/#mongo_ops.transactions","title":"mongo_ops.transactions","text":""},{"location":"transactions/#mongo_ops.transactions--summary","title":"Summary","text":"<p>Transaction management helpers for MongoDB.</p>"},{"location":"transactions/#mongo_ops.transactions-classes","title":"Classes","text":""},{"location":"transactions/#mongo_ops.transactions.TransactionManager","title":"TransactionManager","text":"<p>Simplified multi-document transaction handling.</p> <p>This class provides helpers for executing operations within a MongoDB transaction, ensuring ACID compliance for multi-document updates.</p>"},{"location":"transactions/#mongo_ops.transactions.TransactionManager-functions","title":"Functions","text":""},{"location":"transactions/#mongo_ops.transactions.TransactionManager.execute_transaction","title":"execute_transaction <code>async</code> <code>classmethod</code>","text":"<pre><code>execute_transaction(\n operations: list[\n Callable[\n [AsyncIOMotorClientSession], Awaitable[Any]\n ]\n ],\n **kwargs: Any\n) -> list[Any]\n</code></pre> <p>Execute multiple operations within a single transaction.</p> <p>Parameters:</p> Name Type Description Default <code>operations</code> <code>List[Callable[[AsyncIOMotorClientSession], Awaitable[Any]]]</code> <p>A list of async callables that accept a session parameter and return a result.</p> required <code>**kwargs</code> <code>Any</code> <p>Transaction options.</p> <code>{}</code> <p>Returns:</p> Type Description <code>list[Any]</code> <p>List[Any]: A list containing the results of each operation.</p> Example <p>results = await TransactionManager.execute_transaction([ lambda s: repo1.create(data1, session=s), lambda s: repo2.update(id, data2, session=s), ])</p>"},{"location":"transactions/#mongo_ops.transactions.TransactionManager.start_session","title":"start_session <code>async</code> <code>classmethod</code>","text":"<pre><code>start_session(\n **kwargs: Any,\n) -> AbstractAsyncContextManager[AsyncIOMotorClientSession]\n</code></pre> <p>Start a transaction session as an async context manager.</p> Notes <p>Yields the active session with a started transaction; callers run their operations against the session inside the with-block.</p> Usage <p>async with TransactionManager.start_session() as session: await collection.insert_one(doc, session=session) await other_collection.update_one(filter, update, session=session)</p>"},{"location":"cache/","title":"Cache","text":""},{"location":"cache/#mongo_ops.cache","title":"mongo_ops.cache","text":""},{"location":"cache/#mongo_ops.cache--summary","title":"Summary","text":"<p>Cache backends and configuration for mongo-ops.</p>"},{"location":"cache/#mongo_ops.cache-classes","title":"Classes","text":""},{"location":"cache/#mongo_ops.cache.CacheBackend","title":"CacheBackend","text":"<p> Bases: <code>ABC</code></p> <p>Abstract interface for cache backends.</p> <p>Implementations store byte-encoded values keyed by string, track usage statistics, and manage their own lifecycle. The in-memory and Redis backends both implement this contract.</p>"},{"location":"cache/#mongo_ops.cache.CacheBackend-functions","title":"Functions","text":""},{"location":"cache/#mongo_ops.cache.CacheBackend.clear_pattern","title":"clear_pattern <code>abstractmethod</code> <code>async</code>","text":"<pre><code>clear_pattern(pattern: str) -> None\n</code></pre> <p>Remove all keys matching a glob pattern.</p> <p>Parameters:</p> Name Type Description Default <code>pattern</code> <code>str</code> <p>Glob-style pattern; a trailing <code>*</code> matches prefixes.</p> required"},{"location":"cache/#mongo_ops.cache.CacheBackend.delete","title":"delete <code>abstractmethod</code> <code>async</code>","text":"<pre><code>delete(key: str) -> None\n</code></pre> <p>Remove a key from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required"},{"location":"cache/#mongo_ops.cache.CacheBackend.exists","title":"exists <code>abstractmethod</code> <code>async</code>","text":"<pre><code>exists(key: str) -> bool\n</code></pre> <p>Check whether a key is present.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the key exists, False otherwise.</p>"},{"location":"cache/#mongo_ops.cache.CacheBackend.get","title":"get <code>abstractmethod</code> <code>async</code>","text":"<pre><code>get(key: str) -> bytes | None\n</code></pre> <p>Fetch a value from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Type Description <code>bytes | None</code> <p>Optional[bytes]: The cached bytes, or None on a miss.</p>"},{"location":"cache/#mongo_ops.cache.CacheBackend.get_stats","title":"get_stats <code>abstractmethod</code> <code>async</code>","text":"<pre><code>get_stats() -> CacheStats\n</code></pre> <p>Return a snapshot of cache statistics.</p> <p>Returns:</p> Name Type Description <code>CacheStats</code> <code>CacheStats</code> <p>A copy of the current stats counters.</p>"},{"location":"cache/#mongo_ops.cache.CacheBackend.initialize","title":"initialize <code>abstractmethod</code> <code>async</code>","text":"<pre><code>initialize() -> None\n</code></pre> <p>Start background resources owned by the backend.</p> <p>Should be called once during application startup, after the repositories are connected.</p>"},{"location":"cache/#mongo_ops.cache.CacheBackend.set","title":"set <code>abstractmethod</code> <code>async</code>","text":"<pre><code>set(key: str, value: bytes, ttl: int | None = None) -> None\n</code></pre> <p>Store a value in the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <code>value</code> <code>bytes</code> <p>The byte-encoded value to store.</p> required <code>ttl</code> <code>Optional[int]</code> <p>Time-to-live in seconds. When None, the backend default applies.</p> <code>None</code>"},{"location":"cache/#mongo_ops.cache.CacheBackend.shutdown","title":"shutdown <code>abstractmethod</code> <code>async</code>","text":"<pre><code>shutdown() -> None\n</code></pre> <p>Stop and release background resources.</p> <p>Should be called once during application shutdown.</p>"},{"location":"cache/#mongo_ops.cache.CacheConfig","title":"CacheConfig <code>dataclass</code>","text":"<pre><code>CacheConfig(\n enabled: bool = True,\n backend: Literal[\"memory\", \"redis\"] = \"memory\",\n redis_client: Redis | None = None,\n default_ttl: int = 300,\n max_entries: int = 10000,\n key_prefix: str = \"\",\n cleanup_interval: int = 60,\n)\n</code></pre> <p>Configuration for the cached repository layer.</p> <p>Attributes:</p> Name Type Description <code>enabled</code> <code>bool</code> <p>Whether caching is active for the repository.</p> <code>backend</code> <code>Literal['memory', 'redis']</code> <p>Which backend to use. Defaults to \"memory\".</p> <code>redis_client</code> <code>Optional[Redis]</code> <p>Redis client required when backend is \"redis\".</p> <code>default_ttl</code> <code>int</code> <p>Default time-to-live for cached entries, in seconds.</p> <code>max_entries</code> <code>int</code> <p>Maximum entries for the in-memory backend.</p> <code>key_prefix</code> <code>str</code> <p>Prefix applied to cache keys; defaults to the collection name when empty.</p> <code>cleanup_interval</code> <code>int</code> <p>Interval (seconds) for the in-memory expiry sweep.</p>"},{"location":"cache/#mongo_ops.cache.CacheConfig-functions","title":"Functions","text":""},{"location":"cache/#mongo_ops.cache.CacheConfig.__post_init__","title":"__post_init__","text":"<pre><code>__post_init__() -> None\n</code></pre> <p>Validate backend/redis consistency.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the backend is \"redis\" and no client is given.</p> <code>ImportError</code> <p>If the redis package is not installed.</p>"},{"location":"cache/#mongo_ops.cache.CacheStats","title":"CacheStats <code>dataclass</code>","text":"<pre><code>CacheStats(\n hits: int = 0,\n misses: int = 0,\n sets: int = 0,\n deletes: int = 0,\n current_size: int = 0,\n max_size: int = 0,\n)\n</code></pre> <p>Snapshot of cache usage and activity counters.</p> <p>Attributes:</p> Name Type Description <code>hits</code> <code>int</code> <p>Number of get() calls that found a value.</p> <code>misses</code> <code>int</code> <p>Number of get() calls that returned None.</p> <code>sets</code> <code>int</code> <p>Number of values written to the cache.</p> <code>deletes</code> <code>int</code> <p>Number of keys removed.</p> <code>current_size</code> <code>int</code> <p>Number of entries currently held.</p> <code>max_size</code> <code>int</code> <p>Maximum number of entries the cache allows (0 = unbounded).</p>"},{"location":"cache/#mongo_ops.cache.CircularReferenceError","title":"CircularReferenceError","text":"<pre><code>CircularReferenceError(\n collection: str, doc_id: ObjectId, path: list[str]\n)\n</code></pre> <p> Bases: <code>ValueError</code></p> <p>Raised when population detects a cycle in the reference graph.</p> <p>Attributes:</p> Name Type Description <code>collection</code> <code>str</code> <p>Collection where the cycle was detected.</p> <code>doc_id</code> <code>ObjectId</code> <p>Document ID where the cycle was detected.</p> <code>path</code> <code>list[str]</code> <p>Ordered labels describing the visited reference path.</p> <p>Initialize the error with cycle metadata.</p> <p>Parameters:</p> Name Type Description Default <code>collection</code> <code>str</code> <p>Collection where the cycle was detected.</p> required <code>doc_id</code> <code>ObjectId</code> <p>Document ID where the cycle was detected.</p> required <code>path</code> <code>list[str]</code> <p>Ordered labels describing the visited reference path.</p> required"},{"location":"cache/#mongo_ops.cache.CircularReferenceError-functions","title":"Functions","text":""},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend","title":"InMemoryCacheBackend","text":"<pre><code>InMemoryCacheBackend(\n max_entries: int = 10000,\n default_ttl: int = 300,\n cleanup_interval: int = 60,\n)\n</code></pre> <p> Bases: <code>CacheBackend</code></p> <p>Cache backend backed by an in-memory dict with TTL expiry.</p> <p>Entries are stored in an OrderedDict for LRU-compatible eviction and a min-heap of expiry timestamps drives periodic removal of stale entries.</p> Notes <p>Thread safety:</p> <pre><code>All operations take an asyncio lock; the backend is safe for\nconcurrent use within a single event loop.\n</code></pre> <p>Initialize the backend.</p> <p>Parameters:</p> Name Type Description Default <code>max_entries</code> <code>int</code> <p>Maximum number of entries before LRU eviction kicks in.</p> <code>10000</code> <code>default_ttl</code> <code>int</code> <p>Default time-to-live for entries, in seconds.</p> <code>300</code> <code>cleanup_interval</code> <code>int</code> <p>Seconds between periodic expired-entry sweeps.</p> <code>60</code>"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend-functions","title":"Functions","text":""},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.clear_pattern","title":"clear_pattern <code>async</code>","text":"<pre><code>clear_pattern(pattern: str) -> None\n</code></pre> <p>Remove all keys matching a glob pattern.</p> <p>Parameters:</p> Name Type Description Default <code>pattern</code> <code>str</code> <p>Glob-style pattern; a trailing <code>*</code> matches prefixes.</p> required"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.delete","title":"delete <code>async</code>","text":"<pre><code>delete(key: str) -> None\n</code></pre> <p>Remove a key from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.exists","title":"exists <code>async</code>","text":"<pre><code>exists(key: str) -> bool\n</code></pre> <p>Check whether a key is present.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the key exists, False otherwise.</p>"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.get","title":"get <code>async</code>","text":"<pre><code>get(key: str) -> bytes | None\n</code></pre> <p>Fetch a value from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Type Description <code>bytes | None</code> <p>Optional[bytes]: The cached bytes, or None on a miss.</p>"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.get_stats","title":"get_stats <code>async</code>","text":"<pre><code>get_stats() -> CacheStats\n</code></pre> <p>Return a snapshot of cache statistics.</p> <p>Returns:</p> Name Type Description <code>CacheStats</code> <code>CacheStats</code> <p>A copy of the current stats counters.</p>"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.initialize","title":"initialize <code>async</code>","text":"<pre><code>initialize() -> None\n</code></pre> <p>Start the periodic expired-entry cleanup task.</p>"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.set","title":"set <code>async</code>","text":"<pre><code>set(key: str, value: bytes, ttl: int | None = None) -> None\n</code></pre> <p>Store a value in the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <code>value</code> <code>bytes</code> <p>The byte-encoded value to store.</p> required <code>ttl</code> <code>Optional[int]</code> <p>Time-to-live in seconds; defaults to the backend default.</p> <code>None</code>"},{"location":"cache/#mongo_ops.cache.InMemoryCacheBackend.shutdown","title":"shutdown <code>async</code>","text":"<pre><code>shutdown() -> None\n</code></pre> <p>Cancel and await the cleanup task.</p>"},{"location":"cache/backend/","title":"Backend","text":""},{"location":"cache/backend/#mongo_ops.cache.backend","title":"mongo_ops.cache.backend","text":""},{"location":"cache/backend/#mongo_ops.cache.backend--summary","title":"Summary","text":"<p>Cache backend abstraction.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend-classes","title":"Classes","text":""},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend","title":"CacheBackend","text":"<p> Bases: <code>ABC</code></p> <p>Abstract interface for cache backends.</p> <p>Implementations store byte-encoded values keyed by string, track usage statistics, and manage their own lifecycle. The in-memory and Redis backends both implement this contract.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend-functions","title":"Functions","text":""},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.clear_pattern","title":"clear_pattern <code>abstractmethod</code> <code>async</code>","text":"<pre><code>clear_pattern(pattern: str) -> None\n</code></pre> <p>Remove all keys matching a glob pattern.</p> <p>Parameters:</p> Name Type Description Default <code>pattern</code> <code>str</code> <p>Glob-style pattern; a trailing <code>*</code> matches prefixes.</p> required"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.delete","title":"delete <code>abstractmethod</code> <code>async</code>","text":"<pre><code>delete(key: str) -> None\n</code></pre> <p>Remove a key from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.exists","title":"exists <code>abstractmethod</code> <code>async</code>","text":"<pre><code>exists(key: str) -> bool\n</code></pre> <p>Check whether a key is present.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the key exists, False otherwise.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.get","title":"get <code>abstractmethod</code> <code>async</code>","text":"<pre><code>get(key: str) -> bytes | None\n</code></pre> <p>Fetch a value from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Type Description <code>bytes | None</code> <p>Optional[bytes]: The cached bytes, or None on a miss.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.get_stats","title":"get_stats <code>abstractmethod</code> <code>async</code>","text":"<pre><code>get_stats() -> CacheStats\n</code></pre> <p>Return a snapshot of cache statistics.</p> <p>Returns:</p> Name Type Description <code>CacheStats</code> <code>CacheStats</code> <p>A copy of the current stats counters.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.initialize","title":"initialize <code>abstractmethod</code> <code>async</code>","text":"<pre><code>initialize() -> None\n</code></pre> <p>Start background resources owned by the backend.</p> <p>Should be called once during application startup, after the repositories are connected.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.set","title":"set <code>abstractmethod</code> <code>async</code>","text":"<pre><code>set(key: str, value: bytes, ttl: int | None = None) -> None\n</code></pre> <p>Store a value in the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <code>value</code> <code>bytes</code> <p>The byte-encoded value to store.</p> required <code>ttl</code> <code>Optional[int]</code> <p>Time-to-live in seconds. When None, the backend default applies.</p> <code>None</code>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheBackend.shutdown","title":"shutdown <code>abstractmethod</code> <code>async</code>","text":"<pre><code>shutdown() -> None\n</code></pre> <p>Stop and release background resources.</p> <p>Should be called once during application shutdown.</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CacheStats","title":"CacheStats <code>dataclass</code>","text":"<pre><code>CacheStats(\n hits: int = 0,\n misses: int = 0,\n sets: int = 0,\n deletes: int = 0,\n current_size: int = 0,\n max_size: int = 0,\n)\n</code></pre> <p>Snapshot of cache usage and activity counters.</p> <p>Attributes:</p> Name Type Description <code>hits</code> <code>int</code> <p>Number of get() calls that found a value.</p> <code>misses</code> <code>int</code> <p>Number of get() calls that returned None.</p> <code>sets</code> <code>int</code> <p>Number of values written to the cache.</p> <code>deletes</code> <code>int</code> <p>Number of keys removed.</p> <code>current_size</code> <code>int</code> <p>Number of entries currently held.</p> <code>max_size</code> <code>int</code> <p>Maximum number of entries the cache allows (0 = unbounded).</p>"},{"location":"cache/backend/#mongo_ops.cache.backend.CircularReferenceError","title":"CircularReferenceError","text":"<pre><code>CircularReferenceError(\n collection: str, doc_id: ObjectId, path: list[str]\n)\n</code></pre> <p> Bases: <code>ValueError</code></p> <p>Raised when population detects a cycle in the reference graph.</p> <p>Attributes:</p> Name Type Description <code>collection</code> <code>str</code> <p>Collection where the cycle was detected.</p> <code>doc_id</code> <code>ObjectId</code> <p>Document ID where the cycle was detected.</p> <code>path</code> <code>list[str]</code> <p>Ordered labels describing the visited reference path.</p> <p>Initialize the error with cycle metadata.</p> <p>Parameters:</p> Name Type Description Default <code>collection</code> <code>str</code> <p>Collection where the cycle was detected.</p> required <code>doc_id</code> <code>ObjectId</code> <p>Document ID where the cycle was detected.</p> required <code>path</code> <code>list[str]</code> <p>Ordered labels describing the visited reference path.</p> required"},{"location":"cache/backend/#mongo_ops.cache.backend.CircularReferenceError-functions","title":"Functions","text":""},{"location":"cache/config/","title":"Config","text":""},{"location":"cache/config/#mongo_ops.cache.config","title":"mongo_ops.cache.config","text":""},{"location":"cache/config/#mongo_ops.cache.config--summary","title":"Summary","text":"<p>Cache configuration.</p>"},{"location":"cache/config/#mongo_ops.cache.config-classes","title":"Classes","text":""},{"location":"cache/config/#mongo_ops.cache.config.CacheConfig","title":"CacheConfig <code>dataclass</code>","text":"<pre><code>CacheConfig(\n enabled: bool = True,\n backend: Literal[\"memory\", \"redis\"] = \"memory\",\n redis_client: Redis | None = None,\n default_ttl: int = 300,\n max_entries: int = 10000,\n key_prefix: str = \"\",\n cleanup_interval: int = 60,\n)\n</code></pre> <p>Configuration for the cached repository layer.</p> <p>Attributes:</p> Name Type Description <code>enabled</code> <code>bool</code> <p>Whether caching is active for the repository.</p> <code>backend</code> <code>Literal['memory', 'redis']</code> <p>Which backend to use. Defaults to \"memory\".</p> <code>redis_client</code> <code>Optional[Redis]</code> <p>Redis client required when backend is \"redis\".</p> <code>default_ttl</code> <code>int</code> <p>Default time-to-live for cached entries, in seconds.</p> <code>max_entries</code> <code>int</code> <p>Maximum entries for the in-memory backend.</p> <code>key_prefix</code> <code>str</code> <p>Prefix applied to cache keys; defaults to the collection name when empty.</p> <code>cleanup_interval</code> <code>int</code> <p>Interval (seconds) for the in-memory expiry sweep.</p>"},{"location":"cache/config/#mongo_ops.cache.config.CacheConfig-functions","title":"Functions","text":""},{"location":"cache/config/#mongo_ops.cache.config.CacheConfig.__post_init__","title":"__post_init__","text":"<pre><code>__post_init__() -> None\n</code></pre> <p>Validate backend/redis consistency.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the backend is \"redis\" and no client is given.</p> <code>ImportError</code> <p>If the redis package is not installed.</p>"},{"location":"cache/in_memory/","title":"In Memory","text":""},{"location":"cache/in_memory/#mongo_ops.cache.in_memory","title":"mongo_ops.cache.in_memory","text":""},{"location":"cache/in_memory/#mongo_ops.cache.in_memory--summary","title":"Summary","text":"<p>In-memory cache backend with TTL-based eviction and encode/decode helpers.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory-classes","title":"Classes","text":""},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend","title":"InMemoryCacheBackend","text":"<pre><code>InMemoryCacheBackend(\n max_entries: int = 10000,\n default_ttl: int = 300,\n cleanup_interval: int = 60,\n)\n</code></pre> <p> Bases: <code>CacheBackend</code></p> <p>Cache backend backed by an in-memory dict with TTL expiry.</p> <p>Entries are stored in an OrderedDict for LRU-compatible eviction and a min-heap of expiry timestamps drives periodic removal of stale entries.</p> Notes <p>Thread safety:</p> <pre><code>All operations take an asyncio lock; the backend is safe for\nconcurrent use within a single event loop.\n</code></pre> <p>Initialize the backend.</p> <p>Parameters:</p> Name Type Description Default <code>max_entries</code> <code>int</code> <p>Maximum number of entries before LRU eviction kicks in.</p> <code>10000</code> <code>default_ttl</code> <code>int</code> <p>Default time-to-live for entries, in seconds.</p> <code>300</code> <code>cleanup_interval</code> <code>int</code> <p>Seconds between periodic expired-entry sweeps.</p> <code>60</code>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend-functions","title":"Functions","text":""},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.clear_pattern","title":"clear_pattern <code>async</code>","text":"<pre><code>clear_pattern(pattern: str) -> None\n</code></pre> <p>Remove all keys matching a glob pattern.</p> <p>Parameters:</p> Name Type Description Default <code>pattern</code> <code>str</code> <p>Glob-style pattern; a trailing <code>*</code> matches prefixes.</p> required"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.delete","title":"delete <code>async</code>","text":"<pre><code>delete(key: str) -> None\n</code></pre> <p>Remove a key from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.exists","title":"exists <code>async</code>","text":"<pre><code>exists(key: str) -> bool\n</code></pre> <p>Check whether a key is present.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the key exists, False otherwise.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.get","title":"get <code>async</code>","text":"<pre><code>get(key: str) -> bytes | None\n</code></pre> <p>Fetch a value from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Type Description <code>bytes | None</code> <p>Optional[bytes]: The cached bytes, or None on a miss.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.get_stats","title":"get_stats <code>async</code>","text":"<pre><code>get_stats() -> CacheStats\n</code></pre> <p>Return a snapshot of cache statistics.</p> <p>Returns:</p> Name Type Description <code>CacheStats</code> <code>CacheStats</code> <p>A copy of the current stats counters.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.initialize","title":"initialize <code>async</code>","text":"<pre><code>initialize() -> None\n</code></pre> <p>Start the periodic expired-entry cleanup task.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.set","title":"set <code>async</code>","text":"<pre><code>set(key: str, value: bytes, ttl: int | None = None) -> None\n</code></pre> <p>Store a value in the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <code>value</code> <code>bytes</code> <p>The byte-encoded value to store.</p> required <code>ttl</code> <code>Optional[int]</code> <p>Time-to-live in seconds; defaults to the backend default.</p> <code>None</code>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.InMemoryCacheBackend.shutdown","title":"shutdown <code>async</code>","text":"<pre><code>shutdown() -> None\n</code></pre> <p>Cancel and await the cleanup task.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory-functions","title":"Functions","text":""},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.decode_value","title":"decode_value","text":"<pre><code>decode_value(data: bytes) -> dict\n</code></pre> <p>Decode cache bytes back into a dict.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>bytes</code> <p>UTF-8 JSON bytes produced by encode_value().</p> required <p>Returns:</p> Name Type Description <code>dict</code> <code>dict</code> <p>The decoded dictionary.</p>"},{"location":"cache/in_memory/#mongo_ops.cache.in_memory.encode_value","title":"encode_value","text":"<pre><code>encode_value(value: dict) -> bytes\n</code></pre> <p>Encode a dict into cache-ready bytes.</p> <p>Non-serializable values (e.g., ObjectId) are coerced with str().</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>dict</code> <p>The dictionary to encode.</p> required <p>Returns:</p> Name Type Description <code>bytes</code> <code>bytes</code> <p>UTF-8 JSON bytes.</p>"},{"location":"cache/redis_backend/","title":"Redis Backend","text":""},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend","title":"mongo_ops.cache.redis_backend","text":""},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend--summary","title":"Summary","text":"<p>Redis cache backend with key prefixing and pub/sub invalidation.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend-classes","title":"Classes","text":""},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend","title":"RedisCacheBackend","text":"<pre><code>RedisCacheBackend(\n redis_client: Redis,\n key_prefix: str = \"\",\n default_ttl: int = 300,\n)\n</code></pre> <p> Bases: <code>CacheBackend</code></p> <p>Cache backend backed by Redis with key prefixing.</p> <p>Values are stored with a configurable key prefix, and deletions publish on a shared invalidation channel so other processes can react.</p> Notes <p>Lifecycle:</p> <pre><code>Requires ``pip install mongo-ops[redis]`` and a live Redis\nconnection supplied by the caller.\n</code></pre> <p>Initialize the backend.</p> <p>Parameters:</p> Name Type Description Default <code>redis_client</code> <code>Redis</code> <p>Asynchronous Redis client.</p> required <code>key_prefix</code> <code>str</code> <p>Prefix applied to all keys. Defaults to \"\".</p> <code>''</code> <code>default_ttl</code> <code>int</code> <p>Default time-to-live for entries, in seconds.</p> <code>300</code> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the redis package is not installed.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend-functions","title":"Functions","text":""},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.clear_pattern","title":"clear_pattern <code>async</code>","text":"<pre><code>clear_pattern(pattern: str) -> None\n</code></pre> <p>Remove all keys matching a glob pattern via SCAN/DEL.</p> <p>Parameters:</p> Name Type Description Default <code>pattern</code> <code>str</code> <p>Glob-style pattern; a trailing <code>*</code> matches prefixes.</p> required"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.delete","title":"delete <code>async</code>","text":"<pre><code>delete(key: str) -> None\n</code></pre> <p>Remove a key and publish an invalidation notice.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.exists","title":"exists <code>async</code>","text":"<pre><code>exists(key: str) -> bool\n</code></pre> <p>Check whether a key is present.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the key exists, False otherwise.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.get","title":"get <code>async</code>","text":"<pre><code>get(key: str) -> bytes | None\n</code></pre> <p>Fetch a value from the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <p>Returns:</p> Type Description <code>bytes | None</code> <p>Optional[bytes]: The cached bytes, or None on a miss.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.get_stats","title":"get_stats <code>async</code>","text":"<pre><code>get_stats() -> CacheStats\n</code></pre> <p>Return a snapshot of cache statistics.</p> <p>Returns:</p> Name Type Description <code>CacheStats</code> <code>CacheStats</code> <p>Stats with current_size taken from Redis dbsize.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.initialize","title":"initialize <code>async</code>","text":"<pre><code>initialize() -> None\n</code></pre> <p>Open the pub/sub subscription used for invalidation.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.publish_invalidate","title":"publish_invalidate <code>async</code>","text":"<pre><code>publish_invalidate(key: str) -> None\n</code></pre> <p>Publish an invalidation notice for a key.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key to broadcast.</p> required"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.set","title":"set <code>async</code>","text":"<pre><code>set(key: str, value: bytes, ttl: int | None = None) -> None\n</code></pre> <p>Store a value in the cache.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The cache key.</p> required <code>value</code> <code>bytes</code> <p>The byte-encoded value to store.</p> required <code>ttl</code> <code>Optional[int]</code> <p>Time-to-live in seconds; defaults to the backend default.</p> <code>None</code>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.RedisCacheBackend.shutdown","title":"shutdown <code>async</code>","text":"<pre><code>shutdown() -> None\n</code></pre> <p>Close the pub/sub subscription.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend-functions","title":"Functions","text":""},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.decode_value","title":"decode_value","text":"<pre><code>decode_value(data: bytes) -> dict\n</code></pre> <p>Decode cache bytes back into a dict.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>bytes</code> <p>UTF-8 JSON bytes produced by encode_value().</p> required <p>Returns:</p> Name Type Description <code>dict</code> <code>dict</code> <p>The decoded dictionary.</p>"},{"location":"cache/redis_backend/#mongo_ops.cache.redis_backend.encode_value","title":"encode_value","text":"<pre><code>encode_value(value: dict) -> bytes\n</code></pre> <p>Encode a dict into cache-ready bytes.</p> <p>Non-serializable values (e.g., ObjectId) are coerced with str().</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>dict</code> <p>The dictionary to encode.</p> required <p>Returns:</p> Name Type Description <code>bytes</code> <code>bytes</code> <p>UTF-8 JSON bytes.</p>"},{"location":"cache/repository/","title":"Repository","text":""},{"location":"cache/repository/#mongo_ops.cache.repository","title":"mongo_ops.cache.repository","text":""},{"location":"cache/repository/#mongo_ops.cache.repository--summary","title":"Summary","text":"<p>Cached repository layer that combines a repository with a cache backend.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository-classes","title":"Classes","text":""},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository","title":"CachedBaseRepository","text":"<pre><code>CachedBaseRepository(\n collection_name: str,\n model: type[T],\n cache_backend: CacheBackend,\n config: CacheConfig | None = None,\n)\n</code></pre> <p> Bases: <code>BaseRepository[T]</code>, <code>Generic[T]</code></p> <p>Repository that reads and writes through a cache backend.</p> <p>Wraps an existing BaseRepository with an ID-keyed cache. Reads consult the backend first and fall through to MongoDB on a miss, populating the cache on success. Writes invalidate or refresh the affected key.</p> Notes <p>Guarantees:</p> <pre><code>- The cache holds the raw document shape (``model_dump``), so FK\n references round-trip as hex strings, not populated models.\n- When ``config.enabled`` is False the repository behaves exactly\n like its parent with no cache access.\n</code></pre> <p>Initialize the cached repository.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Name of the MongoDB collection.</p> required <code>model</code> <code>type[T]</code> <p>The Pydantic model class.</p> required <code>cache_backend</code> <code>CacheBackend</code> <p>Backend used to store and fetch entries.</p> required <code>config</code> <code>Optional[CacheConfig]</code> <p>Cache configuration; a default CacheConfig is used when None.</p> <code>None</code>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository-functions","title":"Functions","text":""},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.count","title":"count <code>async</code>","text":"<pre><code>count(filter: dict[str, Any] | None = None) -> int\n</code></pre> <p>Count documents matching a filter.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of matching documents.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.create","title":"create <code>async</code>","text":"<pre><code>create(data: T) -> T\n</code></pre> <p>Insert a document and cache the raw snapshot.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>T</code> <p>The model instance to insert.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The created model instance, including its ID.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.delete","title":"delete <code>async</code>","text":"<pre><code>delete(id: str | ObjectId) -> bool\n</code></pre> <p>Delete a document and remove its cache entry.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a document was deleted, False otherwise.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.get_by_id","title":"get_by_id <code>async</code>","text":"<pre><code>get_by_id(id: str | ObjectId) -> T | None\n</code></pre> <p>Fetch a document, reading through the cache when enabled.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The model instance, or None when not found.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.get_many","title":"get_many <code>async</code>","text":"<pre><code>get_many(\n filter: dict[str, Any] | None = None,\n skip: int = 0,\n limit: int = 100,\n sort: list[tuple] | None = None,\n) -> list[T]\n</code></pre> <p>Retrieve multiple documents with filtering, pagination, and sorting.</p> <p>Parameters:</p> Name Type Description Default <code>filter</code> <code>Optional[Dict[str, Any]]</code> <p>MongoDB filter dictionary (e.g., {\"is_active\": True}).</p> <code>None</code> <code>skip</code> <code>int</code> <p>Number of documents to skip for pagination.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of documents to return (default 100).</p> <code>100</code> <code>sort</code> <code>Optional[List[tuple]]</code> <p>List of sort specifications [(field, direction), ...]. E.g., [(\"created_at\", -1)] for descending.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[T]</code> <p>List[T]: A list of Pydantic model instances.</p> Example <pre><code>users = await repo.get_many(\n filter={\"role\": \"admin\"},\n limit=10,\n sort=[(\"username\", 1)]\n)\n</code></pre>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.invalidate_cache","title":"invalidate_cache <code>async</code>","text":"<pre><code>invalidate_cache(id: str | ObjectId) -> None\n</code></pre> <p>Remove a single document's cache entry.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID to invalidate.</p> required"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.patch","title":"patch <code>async</code>","text":"<pre><code>patch(id: str | ObjectId, data: dict[str, Any]) -> T | None\n</code></pre> <p>Partially update a document using $set (REST PATCH semantics).</p> <p>Unlike update(), patch() takes a partial dict and applies only those fields. PopulatingRepository overrides this to prevent patching FK fields.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID (string or ObjectId).</p> required <code>data</code> <code>Dict[str, Any]</code> <p>A partial dictionary of fields and values to update.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated Pydantic model instance if found, else None.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.update","title":"update <code>async</code>","text":"<pre><code>update(id: str | ObjectId, data: dict) -> T | None\n</code></pre> <p>Update a document and refresh its cache entry.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>Union[str, ObjectId]</code> <p>The document ID.</p> required <code>data</code> <code>dict</code> <p>Fields to set via $set.</p> required <p>Returns:</p> Type Description <code>T | None</code> <p>Optional[T]: The updated model instance, or None when not found.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository.CachedBaseRepository.warm_cache","title":"warm_cache <code>async</code>","text":"<pre><code>warm_cache(ids: list[str | ObjectId]) -> int\n</code></pre> <p>Pre-populate the cache for a set of document IDs.</p> <p>Docs already present in the cache are skipped.</p> <p>Parameters:</p> Name Type Description Default <code>ids</code> <code>list[Union[str, ObjectId]]</code> <p>Document IDs to warm.</p> required <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Number of entries added to the cache.</p>"},{"location":"cache/repository/#mongo_ops.cache.repository-functions","title":"Functions","text":""},{"location":"populate/","title":"Populate","text":""},{"location":"populate/#mongo_ops.populate","title":"mongo_ops.populate","text":""},{"location":"populate/#mongo_ops.populate--summary","title":"Summary","text":"<p>Document populating rules and population engine.</p>"},{"location":"populate/#mongo_ops.populate-classes","title":"Classes","text":""},{"location":"populate/#mongo_ops.populate.PopulateRule","title":"PopulateRule <code>dataclass</code>","text":"<pre><code>PopulateRule(\n field_name: str,\n collection_name: str,\n nested_rules: list[PopulateRule] | None = None,\n max_depth: int = 1,\n filter: dict[str, Any] | None = None,\n projection: dict[str, Any] | None = None,\n)\n</code></pre> <p>Describes how a foreign-key field resolves to another collection.</p> <p>A rule declares the field to resolve, the collection its references point at, and optional nested rules applied to the referenced document itself. It also bounds how deep the resolution may recurse.</p> <p>Attributes:</p> Name Type Description <code>field_name</code> <code>str</code> <p>Name of the FK field on the source document.</p> <code>collection_name</code> <code>str</code> <p>Collection the reference points into.</p> <code>nested_rules</code> <code>Optional[list[PopulateRule]]</code> <p>Sub-rules applied to the referenced document. Defaults to None.</p> <code>max_depth</code> <code>int</code> <p>Maximum recursion depth for this rule. Defaults to 1.</p> <code>filter</code> <code>Optional[dict[str, Any]]</code> <p>Optional Mongo filter applied when fetching the reference. Defaults to None.</p> <code>projection</code> <code>Optional[dict[str, Any]]</code> <p>Optional Mongo projection applied when fetching the reference. Defaults to None.</p>"},{"location":"populate/#mongo_ops.populate.PopulationEngine","title":"PopulationEngine","text":"<pre><code>PopulationEngine(\n repos: dict[str, Any], global_max_depth: int = 10\n)\n</code></pre> <p>Resolves FK references across collections with cycle detection.</p> <p>The engine holds a registry of repositories keyed by collection name and walks documents according to PopulateRules, resolving ObjectId references into model instances. A visited-path set guards against circular graphs.</p> Notes <p>Guarantees:</p> <pre><code>- A reference that cannot be resolved becomes None (scalar) or a\n None entry (list) rather than raising.\n- Depth is capped by both per-rule max_depth and a global\n global_max_depth.\n</code></pre> <p>Initialize the engine.</p> <p>Parameters:</p> Name Type Description Default <code>repos</code> <code>dict[str, Any]</code> <p>Mapping of collection name to repository, used to fetch referenced documents.</p> required <code>global_max_depth</code> <code>int</code> <p>Hard cap on overall population recursion depth. Defaults to 10.</p> <code>10</code>"},{"location":"populate/#mongo_ops.populate.PopulationEngine-functions","title":"Functions","text":""},{"location":"populate/#mongo_ops.populate.PopulationEngine.depopulate","title":"depopulate <code>async</code>","text":"<pre><code>depopulate(document: T, rules: list[PopulateRule]) -> T\n</code></pre> <p>Collapse populated model references back to their ObjectIds.</p> <p>This is the inverse of populate(): model-valued FK fields are reduced to stored identifiers before the document is written to MongoDB.</p> <p>Parameters:</p> Name Type Description Default <code>document</code> <code>T</code> <p>The document to depopulate in place.</p> required <code>rules</code> <code>list[PopulateRule]</code> <p>Rules describing which fields to collapse.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The depopulated document.</p> <p>Raises:</p> Type Description <code>AttributeError</code> <p>If a list entry is not a BaseDocument where expected.</p>"},{"location":"populate/#mongo_ops.populate.PopulationEngine.populate","title":"populate <code>async</code>","text":"<pre><code>populate(\n document: T,\n rules: list[PopulateRule],\n depth: int = 0,\n _visited: set[tuple[str, str]] | None = None,\n _path: list[str] | None = None,\n) -> T\n</code></pre> <p>Resolve FK fields on a document according to the given rules.</p> <p>Parameters:</p> Name Type Description Default <code>document</code> <code>T</code> <p>The document to populate in place.</p> required <code>rules</code> <code>list[PopulateRule]</code> <p>Rules describing which fields to resolve and how deep.</p> required <code>depth</code> <code>int</code> <p>Current recursion depth. Defaults to 0.</p> <code>0</code> <code>_visited</code> <code>Optional[set[tuple[str, str]]]</code> <p>Internal set of (class, id) pairs on the active path.</p> <code>None</code> <code>_path</code> <code>Optional[list[str]]</code> <p>Internal path labels used for cycle reporting.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The populated document.</p> <p>Raises:</p> Type Description <code>CircularReferenceError</code> <p>If a cycle is detected on the active path.</p>"},{"location":"populate/#mongo_ops.populate.PopulationEngine.register_repo","title":"register_repo","text":"<pre><code>register_repo(collection_name: str, repo: Any) -> None\n</code></pre> <p>Register or replace the repository for a collection.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Collection the repository manages.</p> required <code>repo</code> <code>Any</code> <p>Repository exposing get_by_id() used to resolve references.</p> required"},{"location":"populate/engine/","title":"Engine","text":""},{"location":"populate/engine/#mongo_ops.populate.engine","title":"mongo_ops.populate.engine","text":""},{"location":"populate/engine/#mongo_ops.populate.engine--summary","title":"Summary","text":"<p>Recursive document population engine with cycle detection.</p>"},{"location":"populate/engine/#mongo_ops.populate.engine-classes","title":"Classes","text":""},{"location":"populate/engine/#mongo_ops.populate.engine.PopulationEngine","title":"PopulationEngine","text":"<pre><code>PopulationEngine(\n repos: dict[str, Any], global_max_depth: int = 10\n)\n</code></pre> <p>Resolves FK references across collections with cycle detection.</p> <p>The engine holds a registry of repositories keyed by collection name and walks documents according to PopulateRules, resolving ObjectId references into model instances. A visited-path set guards against circular graphs.</p> Notes <p>Guarantees:</p> <pre><code>- A reference that cannot be resolved becomes None (scalar) or a\n None entry (list) rather than raising.\n- Depth is capped by both per-rule max_depth and a global\n global_max_depth.\n</code></pre> <p>Initialize the engine.</p> <p>Parameters:</p> Name Type Description Default <code>repos</code> <code>dict[str, Any]</code> <p>Mapping of collection name to repository, used to fetch referenced documents.</p> required <code>global_max_depth</code> <code>int</code> <p>Hard cap on overall population recursion depth. Defaults to 10.</p> <code>10</code>"},{"location":"populate/engine/#mongo_ops.populate.engine.PopulationEngine-functions","title":"Functions","text":""},{"location":"populate/engine/#mongo_ops.populate.engine.PopulationEngine.depopulate","title":"depopulate <code>async</code>","text":"<pre><code>depopulate(document: T, rules: list[PopulateRule]) -> T\n</code></pre> <p>Collapse populated model references back to their ObjectIds.</p> <p>This is the inverse of populate(): model-valued FK fields are reduced to stored identifiers before the document is written to MongoDB.</p> <p>Parameters:</p> Name Type Description Default <code>document</code> <code>T</code> <p>The document to depopulate in place.</p> required <code>rules</code> <code>list[PopulateRule]</code> <p>Rules describing which fields to collapse.</p> required <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The depopulated document.</p> <p>Raises:</p> Type Description <code>AttributeError</code> <p>If a list entry is not a BaseDocument where expected.</p>"},{"location":"populate/engine/#mongo_ops.populate.engine.PopulationEngine.populate","title":"populate <code>async</code>","text":"<pre><code>populate(\n document: T,\n rules: list[PopulateRule],\n depth: int = 0,\n _visited: set[tuple[str, str]] | None = None,\n _path: list[str] | None = None,\n) -> T\n</code></pre> <p>Resolve FK fields on a document according to the given rules.</p> <p>Parameters:</p> Name Type Description Default <code>document</code> <code>T</code> <p>The document to populate in place.</p> required <code>rules</code> <code>list[PopulateRule]</code> <p>Rules describing which fields to resolve and how deep.</p> required <code>depth</code> <code>int</code> <p>Current recursion depth. Defaults to 0.</p> <code>0</code> <code>_visited</code> <code>Optional[set[tuple[str, str]]]</code> <p>Internal set of (class, id) pairs on the active path.</p> <code>None</code> <code>_path</code> <code>Optional[list[str]]</code> <p>Internal path labels used for cycle reporting.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>T</code> <code>T</code> <p>The populated document.</p> <p>Raises:</p> Type Description <code>CircularReferenceError</code> <p>If a cycle is detected on the active path.</p>"},{"location":"populate/engine/#mongo_ops.populate.engine.PopulationEngine.register_repo","title":"register_repo","text":"<pre><code>register_repo(collection_name: str, repo: Any) -> None\n</code></pre> <p>Register or replace the repository for a collection.</p> <p>Parameters:</p> Name Type Description Default <code>collection_name</code> <code>str</code> <p>Collection the repository manages.</p> required <code>repo</code> <code>Any</code> <p>Repository exposing get_by_id() used to resolve references.</p> required"},{"location":"populate/rules/","title":"Rules","text":""},{"location":"populate/rules/#mongo_ops.populate.rules","title":"mongo_ops.populate.rules","text":""},{"location":"populate/rules/#mongo_ops.populate.rules--summary","title":"Summary","text":"<p>Populate rules describing which foreign-key fields to resolve.</p>"},{"location":"populate/rules/#mongo_ops.populate.rules-classes","title":"Classes","text":""},{"location":"populate/rules/#mongo_ops.populate.rules.PopulateRule","title":"PopulateRule <code>dataclass</code>","text":"<pre><code>PopulateRule(\n field_name: str,\n collection_name: str,\n nested_rules: list[PopulateRule] | None = None,\n max_depth: int = 1,\n filter: dict[str, Any] | None = None,\n projection: dict[str, Any] | None = None,\n)\n</code></pre> <p>Describes how a foreign-key field resolves to another collection.</p> <p>A rule declares the field to resolve, the collection its references point at, and optional nested rules applied to the referenced document itself. It also bounds how deep the resolution may recurse.</p> <p>Attributes:</p> Name Type Description <code>field_name</code> <code>str</code> <p>Name of the FK field on the source document.</p> <code>collection_name</code> <code>str</code> <p>Collection the reference points into.</p> <code>nested_rules</code> <code>Optional[list[PopulateRule]]</code> <p>Sub-rules applied to the referenced document. Defaults to None.</p> <code>max_depth</code> <code>int</code> <p>Maximum recursion depth for this rule. Defaults to 1.</p> <code>filter</code> <code>Optional[dict[str, Any]]</code> <p>Optional Mongo filter applied when fetching the reference. Defaults to None.</p> <code>projection</code> <code>Optional[dict[str, Any]]</code> <p>Optional Mongo projection applied when fetching the reference. Defaults to None.</p>"}]} |