sensu-plugins-mongodb-mrtrotl 1.4.0

data/lib/bson/codec_options.py

@@ -0,0 +1,414 @@
+# Copyright 2014-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tools for specifying BSON codec options."""
+
+import abc
+import datetime
+from collections.abc import MutableMapping as _MutableMapping
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Mapping,
+    NamedTuple,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from bson.binary import (
+    ALL_UUID_REPRESENTATIONS,
+    UUID_REPRESENTATION_NAMES,
+    UuidRepresentation,
+)
+
+
+def _abstractproperty(func: Callable[..., Any]) -> property:
+    return property(abc.abstractmethod(func))
+
+
+_RAW_BSON_DOCUMENT_MARKER = 101
+
+
+def _raw_document_class(document_class: Any) -> bool:
+    """Determine if a document_class is a RawBSONDocument class."""
+    marker = getattr(document_class, "_type_marker", None)
+    return marker == _RAW_BSON_DOCUMENT_MARKER
+
+
+class TypeEncoder(abc.ABC):
+    """Base class for defining type codec classes which describe how a
+    custom type can be transformed to one of the types BSON understands.
+
+    Codec classes must implement the ``python_type`` attribute, and the
+    ``transform_python`` method to support encoding.
+
+    See :ref:`custom-type-type-codec` documentation for an example.
+    """
+
+    @_abstractproperty
+    def python_type(self) -> Any:
+        """The Python type to be converted into something serializable."""
+        pass
+
+    @abc.abstractmethod
+    def transform_python(self, value: Any) -> Any:
+        """Convert the given Python object into something serializable."""
+        pass
+
+
+class TypeDecoder(abc.ABC):
+    """Base class for defining type codec classes which describe how a
+    BSON type can be transformed to a custom type.
+
+    Codec classes must implement the ``bson_type`` attribute, and the
+    ``transform_bson`` method to support decoding.
+
+    See :ref:`custom-type-type-codec` documentation for an example.
+    """
+
+    @_abstractproperty
+    def bson_type(self) -> Any:
+        """The BSON type to be converted into our own type."""
+        pass
+
+    @abc.abstractmethod
+    def transform_bson(self, value: Any) -> Any:
+        """Convert the given BSON value into our own type."""
+        pass
+
+
+class TypeCodec(TypeEncoder, TypeDecoder):
+    """Base class for defining type codec classes which describe how a
+    custom type can be transformed to/from one of the types :mod:`bson`
+    can already encode/decode.
+
+    Codec classes must implement the ``python_type`` attribute, and the
+    ``transform_python`` method to support encoding, as well as the
+    ``bson_type`` attribute, and the ``transform_bson`` method to support
+    decoding.
+
+    See :ref:`custom-type-type-codec` documentation for an example.
+    """
+
+    pass
+
+
+_Codec = Union[TypeEncoder, TypeDecoder, TypeCodec]
+_Fallback = Callable[[Any], Any]
+_DocumentType = TypeVar("_DocumentType", bound=Mapping[str, Any])
+
+
+class TypeRegistry(object):
+    """Encapsulates type codecs used in encoding and / or decoding BSON, as
+    well as the fallback encoder. Type registries cannot be modified after
+    instantiation.
+
+    ``TypeRegistry`` can be initialized with an iterable of type codecs, and
+    a callable for the fallback encoder::
+
+      >>> from bson.codec_options import TypeRegistry
+      >>> type_registry = TypeRegistry([Codec1, Codec2, Codec3, ...],
+      ...                              fallback_encoder)
+
+    See :ref:`custom-type-type-registry` documentation for an example.
+
+    :Parameters:
+      - `type_codecs` (optional): iterable of type codec instances. If
+        ``type_codecs`` contains multiple codecs that transform a single
+        python or BSON type, the transformation specified by the type codec
+        occurring last prevails. A TypeError will be raised if one or more
+        type codecs modify the encoding behavior of a built-in :mod:`bson`
+        type.
+      - `fallback_encoder` (optional): callable that accepts a single,
+        unencodable python value and transforms it into a type that
+        :mod:`bson` can encode. See :ref:`fallback-encoder-callable`
+        documentation for an example.
+    """
+
+    def __init__(
+        self,
+        type_codecs: Optional[Iterable[_Codec]] = None,
+        fallback_encoder: Optional[_Fallback] = None,
+    ) -> None:
+        self.__type_codecs = list(type_codecs or [])
+        self._fallback_encoder = fallback_encoder
+        self._encoder_map: Dict[Any, Any] = {}
+        self._decoder_map: Dict[Any, Any] = {}
+
+        if self._fallback_encoder is not None:
+            if not callable(fallback_encoder):
+                raise TypeError("fallback_encoder %r is not a callable" % (fallback_encoder))
+
+        for codec in self.__type_codecs:
+            is_valid_codec = False
+            if isinstance(codec, TypeEncoder):
+                self._validate_type_encoder(codec)
+                is_valid_codec = True
+                self._encoder_map[codec.python_type] = codec.transform_python
+            if isinstance(codec, TypeDecoder):
+                is_valid_codec = True
+                self._decoder_map[codec.bson_type] = codec.transform_bson
+            if not is_valid_codec:
+                raise TypeError(
+                    "Expected an instance of %s, %s, or %s, got %r instead"
+                    % (TypeEncoder.__name__, TypeDecoder.__name__, TypeCodec.__name__, codec)
+                )
+
+    def _validate_type_encoder(self, codec: _Codec) -> None:
+        from bson import _BUILT_IN_TYPES
+
+        for pytype in _BUILT_IN_TYPES:
+            if issubclass(cast(TypeCodec, codec).python_type, pytype):
+                err_msg = (
+                    "TypeEncoders cannot change how built-in types are "
+                    "encoded (encoder %s transforms type %s)" % (codec, pytype)
+                )
+                raise TypeError(err_msg)
+
+    def __repr__(self):
+        return "%s(type_codecs=%r, fallback_encoder=%r)" % (
+            self.__class__.__name__,
+            self.__type_codecs,
+            self._fallback_encoder,
+        )
+
+    def __eq__(self, other: Any) -> Any:
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return (
+            (self._decoder_map == other._decoder_map)
+            and (self._encoder_map == other._encoder_map)
+            and (self._fallback_encoder == other._fallback_encoder)
+        )
+
+
+class _BaseCodecOptions(NamedTuple):
+    document_class: Type[Mapping[str, Any]]
+    tz_aware: bool
+    uuid_representation: int
+    unicode_decode_error_handler: str
+    tzinfo: Optional[datetime.tzinfo]
+    type_registry: TypeRegistry
+
+
+class CodecOptions(_BaseCodecOptions):
+    """Encapsulates options used encoding and / or decoding BSON.
+
+    The `document_class` option is used to define a custom type for use
+    decoding BSON documents. Access to the underlying raw BSON bytes for
+    a document is available using the :class:`~bson.raw_bson.RawBSONDocument`
+    type::
+
+      >>> from bson.raw_bson import RawBSONDocument
+      >>> from bson.codec_options import CodecOptions
+      >>> codec_options = CodecOptions(document_class=RawBSONDocument)
+      >>> coll = db.get_collection('test', codec_options=codec_options)
+      >>> doc = coll.find_one()
+      >>> doc.raw
+      '\\x16\\x00\\x00\\x00\\x07_id\\x00[0\\x165\\x91\\x10\\xea\\x14\\xe8\\xc5\\x8b\\x93\\x00'
+
+    The document class can be any type that inherits from
+    :class:`~collections.abc.MutableMapping`::
+
+      >>> class AttributeDict(dict):
+      ...     # A dict that supports attribute access.
+      ...     def __getattr__(self, key):
+      ...         return self[key]
+      ...     def __setattr__(self, key, value):
+      ...         self[key] = value
+      ...
+      >>> codec_options = CodecOptions(document_class=AttributeDict)
+      >>> coll = db.get_collection('test', codec_options=codec_options)
+      >>> doc = coll.find_one()
+      >>> doc._id
+      ObjectId('5b3016359110ea14e8c58b93')
+
+    See :doc:`/examples/datetimes` for examples using the `tz_aware` and
+    `tzinfo` options.
+
+    See :doc:`/examples/uuid` for examples using the `uuid_representation`
+    option.
+
+    :Parameters:
+      - `document_class`: BSON documents returned in queries will be decoded
+        to an instance of this class. Must be a subclass of
+        :class:`~collections.abc.MutableMapping`. Defaults to :class:`dict`.
+      - `tz_aware`: If ``True``, BSON datetimes will be decoded to timezone
+        aware instances of :class:`~datetime.datetime`. Otherwise they will be
+        naive. Defaults to ``False``.
+      - `uuid_representation`: The BSON representation to use when encoding
+        and decoding instances of :class:`~uuid.UUID`. Defaults to
+        :data:`~bson.binary.UuidRepresentation.UNSPECIFIED`. New
+        applications should consider setting this to
+        :data:`~bson.binary.UuidRepresentation.STANDARD` for cross language
+        compatibility. See :ref:`handling-uuid-data-example` for details.
+      - `unicode_decode_error_handler`: The error handler to apply when
+        a Unicode-related error occurs during BSON decoding that would
+        otherwise raise :exc:`UnicodeDecodeError`. Valid options include
+        'strict', 'replace', 'backslashreplace', 'surrogateescape', and
+        'ignore'. Defaults to 'strict'.
+      - `tzinfo`: A :class:`~datetime.tzinfo` subclass that specifies the
+        timezone to/from which :class:`~datetime.datetime` objects should be
+        encoded/decoded.
+      - `type_registry`: Instance of :class:`TypeRegistry` used to customize
+        encoding and decoding behavior.
+
+    .. versionchanged:: 4.0
+       The default for `uuid_representation` was changed from
+       :const:`~bson.binary.UuidRepresentation.PYTHON_LEGACY` to
+       :const:`~bson.binary.UuidRepresentation.UNSPECIFIED`.
+
+    .. versionadded:: 3.8
+       `type_registry` attribute.
+
+    .. warning:: Care must be taken when changing
+       `unicode_decode_error_handler` from its default value ('strict').
+       The 'replace' and 'ignore' modes should not be used when documents
+       retrieved from the server will be modified in the client application
+       and stored back to the server.
+    """
+
+    def __new__(
+        cls: Type["CodecOptions"],
+        document_class: Optional[Type[Mapping[str, Any]]] = None,
+        tz_aware: bool = False,
+        uuid_representation: Optional[int] = UuidRepresentation.UNSPECIFIED,
+        unicode_decode_error_handler: str = "strict",
+        tzinfo: Optional[datetime.tzinfo] = None,
+        type_registry: Optional[TypeRegistry] = None,
+    ) -> "CodecOptions":
+        doc_class = document_class or dict
+        # issubclass can raise TypeError for generic aliases like SON[str, Any].
+        # In that case we can use the base class for the comparison.
+        is_mapping = False
+        try:
+            is_mapping = issubclass(doc_class, _MutableMapping)
+        except TypeError:
+            if hasattr(doc_class, "__origin__"):
+                is_mapping = issubclass(doc_class.__origin__, _MutableMapping)  # type: ignore[union-attr]
+        if not (is_mapping or _raw_document_class(doc_class)):
+            raise TypeError(
+                "document_class must be dict, bson.son.SON, "
+                "bson.raw_bson.RawBSONDocument, or a "
+                "subclass of collections.abc.MutableMapping"
+            )
+        if not isinstance(tz_aware, bool):
+            raise TypeError("tz_aware must be True or False")
+        if uuid_representation not in ALL_UUID_REPRESENTATIONS:
+            raise ValueError(
+                "uuid_representation must be a value from bson.binary.UuidRepresentation"
+            )
+        if not isinstance(unicode_decode_error_handler, str):
+            raise ValueError("unicode_decode_error_handler must be a string")
+        if tzinfo is not None:
+            if not isinstance(tzinfo, datetime.tzinfo):
+                raise TypeError("tzinfo must be an instance of datetime.tzinfo")
+            if not tz_aware:
+                raise ValueError("cannot specify tzinfo without also setting tz_aware=True")
+
+        type_registry = type_registry or TypeRegistry()
+
+        if not isinstance(type_registry, TypeRegistry):
+            raise TypeError("type_registry must be an instance of TypeRegistry")
+
+        return tuple.__new__(
+            cls,
+            (
+                doc_class,
+                tz_aware,
+                uuid_representation,
+                unicode_decode_error_handler,
+                tzinfo,
+                type_registry,
+            ),
+        )
+
+    def _arguments_repr(self) -> str:
+        """Representation of the arguments used to create this object."""
+        document_class_repr = "dict" if self.document_class is dict else repr(self.document_class)
+
+        uuid_rep_repr = UUID_REPRESENTATION_NAMES.get(
+            self.uuid_representation, self.uuid_representation
+        )
+
+        return (
+            "document_class=%s, tz_aware=%r, uuid_representation=%s, "
+            "unicode_decode_error_handler=%r, tzinfo=%r, "
+            "type_registry=%r"
+            % (
+                document_class_repr,
+                self.tz_aware,
+                uuid_rep_repr,
+                self.unicode_decode_error_handler,
+                self.tzinfo,
+                self.type_registry,
+            )
+        )
+
+    def _options_dict(self) -> Dict[str, Any]:
+        """Dictionary of the arguments used to create this object."""
+        # TODO: PYTHON-2442 use _asdict() instead
+        return {
+            "document_class": self.document_class,
+            "tz_aware": self.tz_aware,
+            "uuid_representation": self.uuid_representation,
+            "unicode_decode_error_handler": self.unicode_decode_error_handler,
+            "tzinfo": self.tzinfo,
+            "type_registry": self.type_registry,
+        }
+
+    def __repr__(self):
+        return "%s(%s)" % (self.__class__.__name__, self._arguments_repr())
+
+    def with_options(self, **kwargs: Any) -> "CodecOptions":
+        """Make a copy of this CodecOptions, overriding some options::
+
+            >>> from bson.codec_options import DEFAULT_CODEC_OPTIONS
+            >>> DEFAULT_CODEC_OPTIONS.tz_aware
+            False
+            >>> options = DEFAULT_CODEC_OPTIONS.with_options(tz_aware=True)
+            >>> options.tz_aware
+            True
+
+        .. versionadded:: 3.5
+        """
+        opts = self._options_dict()
+        opts.update(kwargs)
+        return CodecOptions(**opts)
+
+
+DEFAULT_CODEC_OPTIONS = CodecOptions()
+
+
+def _parse_codec_options(options: Any) -> CodecOptions:
+    """Parse BSON codec options."""
+    kwargs = {}
+    for k in set(options) & {
+        "document_class",
+        "tz_aware",
+        "uuidrepresentation",
+        "unicode_decode_error_handler",
+        "tzinfo",
+        "type_registry",
+    }:
+        if k == "uuidrepresentation":
+            kwargs["uuid_representation"] = options[k]
+        else:
+            kwargs[k] = options[k]
+    return CodecOptions(**kwargs)

data/lib/bson/codec_options.pyi

@@ -0,0 +1,100 @@
+# Copyright 2022-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Workaround for https://bugs.python.org/issue43923.
+Ideally we would have done this with a single class, but
+generic subclasses *must* take a parameter, and prior to Python 3.9
+or in Python 3.7 and 3.8 with `from __future__ import annotations`,
+you get the error: "TypeError: 'type' object is not subscriptable".
+"""
+
+import datetime
+import abc
+from typing import Tuple, Generic, Optional, Mapping, Any, TypeVar, Type, Dict, Iterable, Tuple, MutableMapping, Callable, Union
+
+
+class TypeEncoder(abc.ABC, metaclass=abc.ABCMeta):
+    @property
+    @abc.abstractmethod
+    def python_type(self) -> Any: ...
+    @abc.abstractmethod
+    def transform_python(self, value: Any) -> Any: ...
+
+class TypeDecoder(abc.ABC, metaclass=abc.ABCMeta):
+    @property
+    @abc.abstractmethod
+    def bson_type(self) -> Any: ...
+    @abc.abstractmethod
+    def transform_bson(self, value: Any) -> Any: ...
+
+class TypeCodec(TypeEncoder, TypeDecoder, metaclass=abc.ABCMeta): ...
+
+Codec = Union[TypeEncoder, TypeDecoder, TypeCodec]
+Fallback = Callable[[Any], Any]
+
+class TypeRegistry:
+    _decoder_map: Dict[Any, Any]
+    _encoder_map: Dict[Any, Any]
+    _fallback_encoder: Optional[Fallback]
+
+    def __init__(self, type_codecs: Optional[Iterable[Codec]] = ..., fallback_encoder: Optional[Fallback] = ...) -> None: ...
+    def __eq__(self, other: Any) -> Any: ...
+
+
+_DocumentType = TypeVar("_DocumentType", bound=Mapping[str, Any])
+
+
+class CodecOptions(Tuple, Generic[_DocumentType]):
+    document_class: Type[_DocumentType]
+    tz_aware: bool
+    uuid_representation: int
+    unicode_decode_error_handler: Optional[str]
+    tzinfo: Optional[datetime.tzinfo]
+    type_registry: TypeRegistry
+
+    def __new__(
+        cls: Type[CodecOptions],
+        document_class: Optional[Type[_DocumentType]] = ...,
+        tz_aware: bool = ...,
+        uuid_representation: Optional[int] = ...,
+        unicode_decode_error_handler: Optional[str] = ...,
+        tzinfo: Optional[datetime.tzinfo] = ...,
+        type_registry: Optional[TypeRegistry] = ...,
+    ) -> CodecOptions[_DocumentType]: ...
+
+    # CodecOptions API
+    def with_options(self, **kwargs: Any) -> CodecOptions[_DocumentType]: ...
+
+    def _arguments_repr(self) -> str: ...
+
+    def _options_dict(self) -> Dict[Any, Any]: ...
+
+    # NamedTuple API
+    @classmethod
+    def _make(cls, obj: Iterable) -> CodecOptions[_DocumentType]: ...
+
+    def _asdict(self) -> Dict[str, Any]: ...
+
+    def _replace(self, **kwargs: Any) -> CodecOptions[_DocumentType]: ...
+
+    _source: str
+    _fields: Tuple[str]
+
+
+DEFAULT_CODEC_OPTIONS: CodecOptions[MutableMapping[str, Any]]
+_RAW_BSON_DOCUMENT_MARKER: int
+
+def _raw_document_class(document_class: Any) -> bool: ...
+
+def _parse_codec_options(options: Any) -> CodecOptions: ...

data/lib/bson/dbref.py

@@ -0,0 +1,133 @@
+# Copyright 2009-2015 MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tools for manipulating DBRefs (references to MongoDB documents)."""
+
+from copy import deepcopy
+from typing import Any, Mapping, Optional
+
+from bson._helpers import _getstate_slots, _setstate_slots
+from bson.son import SON
+
+
+class DBRef(object):
+    """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:`basestring` (:class:`str` in python 3).
+        `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.
+
+        :Parameters:
+          - `collection`: name of the collection the document is stored in
+          - `id`: the value of the document's ``"_id"`` field
+          - `database` (optional): name of the database to reference
+          - `**kwargs` (optional): 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("collection must be an instance of str")
+        if database is not None and not isinstance(database, str):
+            raise TypeError("database must be an instance of str")
+
+        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's database.
+
+        Returns None if this DBRef doesn't specify a database.
+        """
+        return self.__database
+
+    def __getattr__(self, key: Any) -> Any:
+        try:
+            return self.__kwargs[key]
+        except KeyError:
+            raise AttributeError(key)
+
+    def as_doc(self) -> SON[str, Any]:
+        """Get the SON document representation of this DBRef.
+
+        Generally not needed by application developers
+        """
+        doc = SON([("$ref", self.collection), ("$id", self.id)])
+        if self.database is not None:
+            doc["$db"] = self.database
+        doc.update(self.__kwargs)
+        return doc
+
+    def __repr__(self):
+        extra = "".join([", %s=%r" % (k, v) for k, v in self.__kwargs.items()])
+        if self.database is None:
+            return "DBRef(%r, %r%s)" % (self.collection, self.id, extra)
+        return "DBRef(%r, %r, %r%s)" % (self.collection, self.id, self.database, extra)
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, DBRef):
+            us = (self.__database, self.__collection, self.__id, self.__kwargs)
+            them = (other.__database, other.__collection, other.__id, other.__kwargs)
+            return us == them
+        return NotImplemented
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+    def __hash__(self) -> int:
+        """Get a hash value for this :class:`DBRef`."""
+        return hash(
+            (self.__collection, self.__id, self.__database, tuple(sorted(self.__kwargs.items())))
+        )
+
+    def __deepcopy__(self, memo: Any) -> "DBRef":
+        """Support function for `copy.deepcopy()`."""
+        return DBRef(
+            deepcopy(self.__collection, memo),
+            deepcopy(self.__id, memo),
+            deepcopy(self.__database, memo),
+            deepcopy(self.__kwargs, memo),
+        )