xtquant.xtbson.bson36.dbref

  1# Copyright 2009-2015 MongoDB, Inc.
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7# http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15"""Tools for manipulating DBRefs (references to MongoDB documents)."""
 16
 17from copy import deepcopy
 18
 19from ._helpers import _getstate_slots, _setstate_slots
 20from .son import SON
 21
 22
 23class DBRef(object):
 24    """A reference to a document stored in MongoDB."""
 25
 26    __slots__ = "__collection", "__id", "__database", "__kwargs"
 27    __getstate__ = _getstate_slots
 28    __setstate__ = _setstate_slots
 29    # DBRef isn't actually a BSON "type" so this number was arbitrarily chosen.
 30    _type_marker = 100
 31
 32    def __init__(self, collection, id, database=None, _extra={}, **kwargs):
 33        """Initialize a new :class:`DBRef`.
 34
 35        Raises :class:`TypeError` if `collection` or `database` is not
 36        an instance of :class:`basestring` (:class:`str` in python 3).
 37        `database` is optional and allows references to documents to work
 38        across databases. Any additional keyword arguments will create
 39        additional fields in the resultant embedded document.
 40
 41        :Parameters:
 42          - `collection`: name of the collection the document is stored in
 43          - `id`: the value of the document's ``"_id"`` field
 44          - `database` (optional): name of the database to reference
 45          - `**kwargs` (optional): additional keyword arguments will
 46            create additional, custom fields
 47
 48        .. seealso:: The MongoDB documentation on `dbrefs <https://dochub.mongodb.org/core/dbrefs>`_.
 49        """
 50        if not isinstance(collection, str):
 51            raise TypeError("collection must be an instance of str")
 52        if database is not None and not isinstance(database, str):
 53            raise TypeError("database must be an instance of str")
 54
 55        self.__collection = collection
 56        self.__id = id
 57        self.__database = database
 58        kwargs.update(_extra)
 59        self.__kwargs = kwargs
 60
 61    @property
 62    def collection(self):
 63        """Get the name of this DBRef's collection."""
 64        return self.__collection
 65
 66    @property
 67    def id(self):
 68        """Get this DBRef's _id."""
 69        return self.__id
 70
 71    @property
 72    def database(self):
 73        """Get the name of this DBRef's database.
 74
 75        Returns None if this DBRef doesn't specify a database.
 76        """
 77        return self.__database
 78
 79    def __getattr__(self, key):
 80        try:
 81            return self.__kwargs[key]
 82        except KeyError:
 83            raise AttributeError(key)
 84
 85    def as_doc(self):
 86        """Get the SON document representation of this DBRef.
 87
 88        Generally not needed by application developers
 89        """
 90        doc = SON([("$ref", self.collection), ("$id", self.id)])
 91        if self.database is not None:
 92            doc["$db"] = self.database
 93        doc.update(self.__kwargs)
 94        return doc
 95
 96    def __repr__(self):
 97        extra = "".join([", %s=%r" % (k, v) for k, v in self.__kwargs.items()])
 98        if self.database is None:
 99            return "DBRef(%r, %r%s)" % (self.collection, self.id, extra)
100        return "DBRef(%r, %r, %r%s)" % (self.collection, self.id, self.database, extra)
101
102    def __eq__(self, other):
103        if isinstance(other, DBRef):
104            us = (self.__database, self.__collection, self.__id, self.__kwargs)
105            them = (other.__database, other.__collection, other.__id, other.__kwargs)
106            return us == them
107        return NotImplemented
108
109    def __ne__(self, other):
110        return not self == other
111
112    def __hash__(self):
113        """Get a hash value for this :class:`DBRef`."""
114        return hash(
115            (self.__collection, self.__id, self.__database, tuple(sorted(self.__kwargs.items())))
116        )
117
118    def __deepcopy__(self, memo):
119        """Support function for `copy.deepcopy()`."""
120        return DBRef(
121            deepcopy(self.__collection, memo),
122            deepcopy(self.__id, memo),
123            deepcopy(self.__database, memo),
124            deepcopy(self.__kwargs, memo),
125        )