Class DBRef

bson/dbref.py:25–133

A reference to a document stored in MongoDB.

class DBRef:
    """A reference to a document stored in MongoDB."""

    __slots__ = "__collection", "__id", "__database", "__kwargs"
    __getstate__ = _getstate_slots
    __setstate__ = _setstate_slots
    # DBRef isn't actually a BSON "type" so this number was arbitrarily chosen.
    _type_marker = 100

    def __init__(
        self,
        collection: str,
        id: Any,
        database: Optional[str] = None,
        _extra: Optional[Mapping[str, Any]] = None,
        **kwargs: Any,
    ) -> None:
        """Initialize a new :class:`DBRef`.

        Raises :class:`TypeError` if `collection` or `database` is not
        an instance of :class:`str`. `database` is optional and allows
        references to documents to work across databases. Any additional
        keyword arguments will create additional fields in the resultant
        embedded document.

        :param collection: name of the collection the document is stored in
        :param id: the value of the document's ``"_id"`` field
        :param database: name of the database to reference
        :param kwargs: additional keyword arguments will
            create additional, custom fields

        .. seealso:: The MongoDB documentation on `dbrefs <https://dochub.mongodb.org/core/dbrefs>`_.
        """
        if not isinstance(collection, str):
            raise TypeError(f"collection must be an instance of str, not {type(collection)}")
        if database is not None and not isinstance(database, str):
            raise TypeError(f"database must be an instance of str, not {type(database)}")

        self.__collection = collection
        self.__id = id
        self.__database = database
        kwargs.update(_extra or {})
        self.__kwargs = kwargs

    @property
    def collection(self) -> str:
        """Get the name of this DBRef's collection."""
        return self.__collection

    @property
    def id(self) -> Any:
        """Get this DBRef's _id."""
        return self.__id

    @property
    def database(self) -> Optional[str]:
        """Get the name of this DBRef&#x27;s database.