{
  "module": "mongo_ops.populate",
  "content": {
    "path": "mongo_ops.populate",
    "docstring": "# Summary\n\nDocument populating rules and population engine.",
    "objects": {
      "PopulationEngine": {
        "name": "PopulationEngine",
        "kind": "class",
        "path": "mongo_ops.populate.PopulationEngine",
        "signature": "PopulationEngine(repos: dict[str, Any], global_max_depth: int = 10)",
        "docstring": "Resolves FK references across collections with cycle detection.\n\nThe engine holds a registry of repositories keyed by collection name and\nwalks documents according to PopulateRules, resolving ObjectId references\ninto model instances. A visited-path set guards against circular graphs.\n\nNotes:\n    **Guarantees:**\n\n        - 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.",
        "members": {
          "register_repo": {
            "name": "register_repo",
            "kind": "function",
            "path": "mongo_ops.populate.PopulationEngine.register_repo",
            "signature": "register_repo(collection_name: str, repo: Any)",
            "docstring": "Register or replace the repository for a collection.\n\nArgs:\n    collection_name (str):\n        Collection the repository manages.\n    repo (Any):\n        Repository exposing get_by_id() used to resolve references."
          },
          "populate": {
            "name": "populate",
            "kind": "function",
            "path": "mongo_ops.populate.PopulationEngine.populate",
            "signature": "populate(document: T, rules: list[PopulateRule], depth: int = 0, _visited: set[tuple[str, str]] | None = None, _path: list[str] | None = None)",
            "docstring": "Resolve FK fields on a document according to the given rules.\n\nArgs:\n    document (T):\n        The document to populate in place.\n    rules (list[PopulateRule]):\n        Rules describing which fields to resolve and how deep.\n    depth (int):\n        Current recursion depth. Defaults to 0.\n    _visited (Optional[set[tuple[str, str]]]):\n        Internal set of (class, id) pairs on the active path.\n    _path (Optional[list[str]]):\n        Internal path labels used for cycle reporting.\n\nReturns:\n    T: The populated document.\n\nRaises:\n    CircularReferenceError: If a cycle is detected on the active path."
          },
          "depopulate": {
            "name": "depopulate",
            "kind": "function",
            "path": "mongo_ops.populate.PopulationEngine.depopulate",
            "signature": "depopulate(document: T, rules: list[PopulateRule])",
            "docstring": "Collapse populated model references back to their ObjectIds.\n\nThis is the inverse of populate(): model-valued FK fields are reduced\nto stored identifiers before the document is written to MongoDB.\n\nArgs:\n    document (T):\n        The document to depopulate in place.\n    rules (list[PopulateRule]):\n        Rules describing which fields to collapse.\n\nReturns:\n    T: The depopulated document.\n\nRaises:\n    AttributeError: If a list entry is not a BaseDocument where\n        expected."
          }
        }
      },
      "PopulateRule": {
        "name": "PopulateRule",
        "kind": "class",
        "path": "mongo_ops.populate.PopulateRule",
        "signature": "PopulateRule(field_name: str, collection_name: str, nested_rules: list[PopulateRule] | None = None, max_depth: int = 1, filter: dict[str, Any] | None = None, projection: dict[str, Any] | None = None)",
        "docstring": "Describes how a foreign-key field resolves to another collection.\n\nA rule declares the field to resolve, the collection its references\npoint at, and optional nested rules applied to the referenced document\nitself. It also bounds how deep the resolution may recurse.\n\nAttributes:\n    field_name (str):\n        Name of the FK field on the source document.\n    collection_name (str):\n        Collection the reference points into.\n    nested_rules (Optional[list[PopulateRule]]):\n        Sub-rules applied to the referenced document. Defaults to None.\n    max_depth (int):\n        Maximum recursion depth for this rule. Defaults to 1.\n    filter (Optional[dict[str, Any]]):\n        Optional Mongo filter applied when fetching the reference.\n        Defaults to None.\n    projection (Optional[dict[str, Any]]):\n        Optional Mongo projection applied when fetching the reference.\n        Defaults to None.",
        "members": {
          "field_name": {
            "name": "field_name",
            "kind": "attribute",
            "path": "mongo_ops.populate.PopulateRule.field_name",
            "signature": null,
            "docstring": null
          },
          "collection_name": {
            "name": "collection_name",
            "kind": "attribute",
            "path": "mongo_ops.populate.PopulateRule.collection_name",
            "signature": null,
            "docstring": null
          },
          "nested_rules": {
            "name": "nested_rules",
            "kind": "attribute",
            "path": "mongo_ops.populate.PopulateRule.nested_rules",
            "signature": null,
            "docstring": null
          },
          "max_depth": {
            "name": "max_depth",
            "kind": "attribute",
            "path": "mongo_ops.populate.PopulateRule.max_depth",
            "signature": null,
            "docstring": null
          },
          "filter": {
            "name": "filter",
            "kind": "attribute",
            "path": "mongo_ops.populate.PopulateRule.filter",
            "signature": null,
            "docstring": null
          },
          "projection": {
            "name": "projection",
            "kind": "attribute",
            "path": "mongo_ops.populate.PopulateRule.projection",
            "signature": null,
            "docstring": null
          }
        }
      },
      "engine": {
        "name": "engine",
        "kind": "module",
        "path": "mongo_ops.populate.engine",
        "signature": null,
        "docstring": "# Summary\n\nRecursive document population engine with cycle detection.",
        "members": {
          "CircularReferenceError": {
            "name": "CircularReferenceError",
            "kind": "class",
            "path": "mongo_ops.populate.engine.CircularReferenceError",
            "signature": "CircularReferenceError(collection: str, doc_id: ObjectId, path: list[str])",
            "docstring": "Raised when population detects a cycle in the reference graph.\n\nAttributes:\n    collection (str):\n        Collection where the cycle was detected.\n    doc_id (ObjectId):\n        Document ID where the cycle was detected.\n    path (list[str]):\n        Ordered labels describing the visited reference path.",
            "members": {
              "collection": {
                "name": "collection",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.CircularReferenceError.collection",
                "signature": null,
                "docstring": null
              },
              "doc_id": {
                "name": "doc_id",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.CircularReferenceError.doc_id",
                "signature": null,
                "docstring": null
              },
              "path": {
                "name": "path",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.CircularReferenceError.path",
                "signature": null,
                "docstring": null
              }
            }
          },
          "BaseDocument": {
            "name": "BaseDocument",
            "kind": "class",
            "path": "mongo_ops.populate.engine.BaseDocument",
            "signature": null,
            "docstring": "Base document class with common MongoDB fields.\n\nInherit from this class to create Pydantic models that represent\nMongoDB documents. It includes automatic handling of the `_id` field\nand timestamps.\n\nAttributes:\n    id: The MongoDB document ID (aliased to `_id`).\n    created_at: Timestamp when the document was created.\n    updated_at: Timestamp when the document was last updated.",
            "members": {
              "id": {
                "name": "id",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.BaseDocument.id",
                "signature": null,
                "docstring": null
              },
              "created_at": {
                "name": "created_at",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.BaseDocument.created_at",
                "signature": null,
                "docstring": null
              },
              "updated_at": {
                "name": "updated_at",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.BaseDocument.updated_at",
                "signature": null,
                "docstring": null
              },
              "Config": {
                "name": "Config",
                "kind": "class",
                "path": "mongo_ops.populate.engine.BaseDocument.Config",
                "signature": null,
                "docstring": null,
                "members": {
                  "populate_by_name": {
                    "name": "populate_by_name",
                    "kind": "attribute",
                    "path": "mongo_ops.populate.engine.BaseDocument.Config.populate_by_name",
                    "signature": null,
                    "docstring": null
                  },
                  "arbitrary_types_allowed": {
                    "name": "arbitrary_types_allowed",
                    "kind": "attribute",
                    "path": "mongo_ops.populate.engine.BaseDocument.Config.arbitrary_types_allowed",
                    "signature": null,
                    "docstring": null
                  },
                  "json_encoders": {
                    "name": "json_encoders",
                    "kind": "attribute",
                    "path": "mongo_ops.populate.engine.BaseDocument.Config.json_encoders",
                    "signature": null,
                    "docstring": null
                  },
                  "json_schema_extra": {
                    "name": "json_schema_extra",
                    "kind": "attribute",
                    "path": "mongo_ops.populate.engine.BaseDocument.Config.json_schema_extra",
                    "signature": null,
                    "docstring": null
                  }
                }
              }
            }
          },
          "PopulateRule": {
            "name": "PopulateRule",
            "kind": "class",
            "path": "mongo_ops.populate.engine.PopulateRule",
            "signature": "PopulateRule(field_name: str, collection_name: str, nested_rules: list[PopulateRule] | None = None, max_depth: int = 1, filter: dict[str, Any] | None = None, projection: dict[str, Any] | None = None)",
            "docstring": "Describes how a foreign-key field resolves to another collection.\n\nA rule declares the field to resolve, the collection its references\npoint at, and optional nested rules applied to the referenced document\nitself. It also bounds how deep the resolution may recurse.\n\nAttributes:\n    field_name (str):\n        Name of the FK field on the source document.\n    collection_name (str):\n        Collection the reference points into.\n    nested_rules (Optional[list[PopulateRule]]):\n        Sub-rules applied to the referenced document. Defaults to None.\n    max_depth (int):\n        Maximum recursion depth for this rule. Defaults to 1.\n    filter (Optional[dict[str, Any]]):\n        Optional Mongo filter applied when fetching the reference.\n        Defaults to None.\n    projection (Optional[dict[str, Any]]):\n        Optional Mongo projection applied when fetching the reference.\n        Defaults to None.",
            "members": {
              "field_name": {
                "name": "field_name",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.PopulateRule.field_name",
                "signature": null,
                "docstring": null
              },
              "collection_name": {
                "name": "collection_name",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.PopulateRule.collection_name",
                "signature": null,
                "docstring": null
              },
              "nested_rules": {
                "name": "nested_rules",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.PopulateRule.nested_rules",
                "signature": null,
                "docstring": null
              },
              "max_depth": {
                "name": "max_depth",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.PopulateRule.max_depth",
                "signature": null,
                "docstring": null
              },
              "filter": {
                "name": "filter",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.PopulateRule.filter",
                "signature": null,
                "docstring": null
              },
              "projection": {
                "name": "projection",
                "kind": "attribute",
                "path": "mongo_ops.populate.engine.PopulateRule.projection",
                "signature": null,
                "docstring": null
              }
            }
          },
          "T": {
            "name": "T",
            "kind": "attribute",
            "path": "mongo_ops.populate.engine.T",
            "signature": null,
            "docstring": null
          },
          "PopulationEngine": {
            "name": "PopulationEngine",
            "kind": "class",
            "path": "mongo_ops.populate.engine.PopulationEngine",
            "signature": "PopulationEngine(repos: dict[str, Any], global_max_depth: int = 10)",
            "docstring": "Resolves FK references across collections with cycle detection.\n\nThe engine holds a registry of repositories keyed by collection name and\nwalks documents according to PopulateRules, resolving ObjectId references\ninto model instances. A visited-path set guards against circular graphs.\n\nNotes:\n    **Guarantees:**\n\n        - 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.",
            "members": {
              "register_repo": {
                "name": "register_repo",
                "kind": "function",
                "path": "mongo_ops.populate.engine.PopulationEngine.register_repo",
                "signature": "register_repo(collection_name: str, repo: Any) -> None",
                "docstring": "Register or replace the repository for a collection.\n\nArgs:\n    collection_name (str):\n        Collection the repository manages.\n    repo (Any):\n        Repository exposing get_by_id() used to resolve references."
              },
              "populate": {
                "name": "populate",
                "kind": "function",
                "path": "mongo_ops.populate.engine.PopulationEngine.populate",
                "signature": "populate(document: T, rules: list[PopulateRule], depth: int = 0, _visited: set[tuple[str, str]] | None = None, _path: list[str] | None = None) -> T",
                "docstring": "Resolve FK fields on a document according to the given rules.\n\nArgs:\n    document (T):\n        The document to populate in place.\n    rules (list[PopulateRule]):\n        Rules describing which fields to resolve and how deep.\n    depth (int):\n        Current recursion depth. Defaults to 0.\n    _visited (Optional[set[tuple[str, str]]]):\n        Internal set of (class, id) pairs on the active path.\n    _path (Optional[list[str]]):\n        Internal path labels used for cycle reporting.\n\nReturns:\n    T: The populated document.\n\nRaises:\n    CircularReferenceError: If a cycle is detected on the active path."
              },
              "depopulate": {
                "name": "depopulate",
                "kind": "function",
                "path": "mongo_ops.populate.engine.PopulationEngine.depopulate",
                "signature": "depopulate(document: T, rules: list[PopulateRule]) -> T",
                "docstring": "Collapse populated model references back to their ObjectIds.\n\nThis is the inverse of populate(): model-valued FK fields are reduced\nto stored identifiers before the document is written to MongoDB.\n\nArgs:\n    document (T):\n        The document to depopulate in place.\n    rules (list[PopulateRule]):\n        Rules describing which fields to collapse.\n\nReturns:\n    T: The depopulated document.\n\nRaises:\n    AttributeError: If a list entry is not a BaseDocument where\n        expected."
              }
            }
          }
        }
      },
      "rules": {
        "name": "rules",
        "kind": "module",
        "path": "mongo_ops.populate.rules",
        "signature": null,
        "docstring": "# Summary\n\nPopulate rules describing which foreign-key fields to resolve.",
        "members": {
          "PopulateRule": {
            "name": "PopulateRule",
            "kind": "class",
            "path": "mongo_ops.populate.rules.PopulateRule",
            "signature": "PopulateRule(field_name: str, collection_name: str, nested_rules: list[PopulateRule] | None = None, max_depth: int = 1, filter: dict[str, Any] | None = None, projection: dict[str, Any] | None = None)",
            "docstring": "Describes how a foreign-key field resolves to another collection.\n\nA rule declares the field to resolve, the collection its references\npoint at, and optional nested rules applied to the referenced document\nitself. It also bounds how deep the resolution may recurse.\n\nAttributes:\n    field_name (str):\n        Name of the FK field on the source document.\n    collection_name (str):\n        Collection the reference points into.\n    nested_rules (Optional[list[PopulateRule]]):\n        Sub-rules applied to the referenced document. Defaults to None.\n    max_depth (int):\n        Maximum recursion depth for this rule. Defaults to 1.\n    filter (Optional[dict[str, Any]]):\n        Optional Mongo filter applied when fetching the reference.\n        Defaults to None.\n    projection (Optional[dict[str, Any]]):\n        Optional Mongo projection applied when fetching the reference.\n        Defaults to None.",
            "members": {
              "field_name": {
                "name": "field_name",
                "kind": "attribute",
                "path": "mongo_ops.populate.rules.PopulateRule.field_name",
                "signature": null,
                "docstring": null
              },
              "collection_name": {
                "name": "collection_name",
                "kind": "attribute",
                "path": "mongo_ops.populate.rules.PopulateRule.collection_name",
                "signature": null,
                "docstring": null
              },
              "nested_rules": {
                "name": "nested_rules",
                "kind": "attribute",
                "path": "mongo_ops.populate.rules.PopulateRule.nested_rules",
                "signature": null,
                "docstring": null
              },
              "max_depth": {
                "name": "max_depth",
                "kind": "attribute",
                "path": "mongo_ops.populate.rules.PopulateRule.max_depth",
                "signature": null,
                "docstring": null
              },
              "filter": {
                "name": "filter",
                "kind": "attribute",
                "path": "mongo_ops.populate.rules.PopulateRule.filter",
                "signature": null,
                "docstring": null
              },
              "projection": {
                "name": "projection",
                "kind": "attribute",
                "path": "mongo_ops.populate.rules.PopulateRule.projection",
                "signature": null,
                "docstring": null
              }
            }
          }
        }
      }
    }
  }
}