sensu-plugins-mongodb-mrtrotl 1.4.0

data/lib/pymongo/database.py

@@ -0,0 +1,1202 @@
+# Copyright 2009-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.
+
+"""Database level operations."""
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Generic,
+    List,
+    Mapping,
+    MutableMapping,
+    NoReturn,
+    Optional,
+    Sequence,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from bson.codec_options import DEFAULT_CODEC_OPTIONS, CodecOptions
+from bson.dbref import DBRef
+from bson.son import SON
+from bson.timestamp import Timestamp
+from pymongo import _csot, common
+from pymongo.aggregation import _DatabaseAggregationCommand
+from pymongo.change_stream import DatabaseChangeStream
+from pymongo.collection import Collection
+from pymongo.command_cursor import CommandCursor
+from pymongo.common import _ecc_coll_name, _ecoc_coll_name, _esc_coll_name
+from pymongo.errors import CollectionInvalid, InvalidName
+from pymongo.read_preferences import ReadPreference, _ServerMode
+from pymongo.typings import _CollationIn, _DocumentType, _Pipeline
+
+
+def _check_name(name):
+    """Check if a database name is valid."""
+    if not name:
+        raise InvalidName("database name cannot be the empty string")
+
+    for invalid_char in [" ", ".", "$", "/", "\\", "\x00", '"']:
+        if invalid_char in name:
+            raise InvalidName("database names cannot contain the character %r" % invalid_char)
+
+
+if TYPE_CHECKING:
+    import bson.codec_options
+    from pymongo.client_session import ClientSession
+    from pymongo.mongo_client import MongoClient
+    from pymongo.read_concern import ReadConcern
+    from pymongo.write_concern import WriteConcern
+
+
+_CodecDocumentType = TypeVar("_CodecDocumentType", bound=Mapping[str, Any])
+
+
+class Database(common.BaseObject, Generic[_DocumentType]):
+    """A Mongo database."""
+
+    def __init__(
+        self,
+        client: "MongoClient[_DocumentType]",
+        name: str,
+        codec_options: Optional[CodecOptions] = None,
+        read_preference: Optional[_ServerMode] = None,
+        write_concern: Optional["WriteConcern"] = None,
+        read_concern: Optional["ReadConcern"] = None,
+    ) -> None:
+        """Get a database by client and name.
+
+        Raises :class:`TypeError` if `name` is not an instance of
+        :class:`basestring` (:class:`str` in python 3). Raises
+        :class:`~pymongo.errors.InvalidName` if `name` is not a valid
+        database name.
+
+        :Parameters:
+          - `client`: A :class:`~pymongo.mongo_client.MongoClient` instance.
+          - `name`: The database name.
+          - `codec_options` (optional): An instance of
+            :class:`~bson.codec_options.CodecOptions`. If ``None`` (the
+            default) client.codec_options is used.
+          - `read_preference` (optional): The read preference to use. If
+            ``None`` (the default) client.read_preference is used.
+          - `write_concern` (optional): An instance of
+            :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
+            default) client.write_concern is used.
+          - `read_concern` (optional): An instance of
+            :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
+            default) client.read_concern is used.
+
+        .. seealso:: The MongoDB documentation on `databases <https://dochub.mongodb.org/core/databases>`_.
+
+        .. versionchanged:: 4.0
+           Removed the eval, system_js, error, last_status, previous_error,
+           reset_error_history, authenticate, logout, collection_names,
+           current_op, add_user, remove_user, profiling_level,
+           set_profiling_level, and profiling_info methods.
+           See the :ref:`pymongo4-migration-guide`.
+
+        .. versionchanged:: 3.2
+           Added the read_concern option.
+
+        .. versionchanged:: 3.0
+           Added the codec_options, read_preference, and write_concern options.
+           :class:`~pymongo.database.Database` no longer returns an instance
+           of :class:`~pymongo.collection.Collection` for attribute names
+           with leading underscores. You must use dict-style lookups instead::
+
+               db['__my_collection__']
+
+           Not:
+
+               db.__my_collection__
+        """
+        super(Database, self).__init__(
+            codec_options or client.codec_options,
+            read_preference or client.read_preference,
+            write_concern or client.write_concern,
+            read_concern or client.read_concern,
+        )
+
+        if not isinstance(name, str):
+            raise TypeError("name must be an instance of str")
+
+        if name != "$external":
+            _check_name(name)
+
+        self.__name = name
+        self.__client: MongoClient[_DocumentType] = client
+        self._timeout = client.options.timeout
+
+    @property
+    def client(self) -> "MongoClient[_DocumentType]":
+        """The client instance for this :class:`Database`."""
+        return self.__client
+
+    @property
+    def name(self) -> str:
+        """The name of this :class:`Database`."""
+        return self.__name
+
+    def with_options(
+        self,
+        codec_options: Optional[CodecOptions] = None,
+        read_preference: Optional[_ServerMode] = None,
+        write_concern: Optional["WriteConcern"] = None,
+        read_concern: Optional["ReadConcern"] = None,
+    ) -> "Database[_DocumentType]":
+        """Get a clone of this database changing the specified settings.
+
+          >>> db1.read_preference
+          Primary()
+          >>> from pymongo import ReadPreference
+          >>> db2 = db1.with_options(read_preference=ReadPreference.SECONDARY)
+          >>> db1.read_preference
+          Primary()
+          >>> db2.read_preference
+          Secondary(tag_sets=None)
+
+        :Parameters:
+          - `codec_options` (optional): An instance of
+            :class:`~bson.codec_options.CodecOptions`. If ``None`` (the
+            default) the :attr:`codec_options` of this :class:`Collection`
+            is used.
+          - `read_preference` (optional): The read preference to use. If
+            ``None`` (the default) the :attr:`read_preference` of this
+            :class:`Collection` is used. See :mod:`~pymongo.read_preferences`
+            for options.
+          - `write_concern` (optional): An instance of
+            :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
+            default) the :attr:`write_concern` of this :class:`Collection`
+            is used.
+          - `read_concern` (optional): An instance of
+            :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
+            default) the :attr:`read_concern` of this :class:`Collection`
+            is used.
+
+        .. versionadded:: 3.8
+        """
+        return Database(
+            self.client,
+            self.__name,
+            codec_options or self.codec_options,
+            read_preference or self.read_preference,
+            write_concern or self.write_concern,
+            read_concern or self.read_concern,
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, Database):
+            return self.__client == other.client and self.__name == other.name
+        return NotImplemented
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+    def __hash__(self) -> int:
+        return hash((self.__client, self.__name))
+
+    def __repr__(self):
+        return "Database(%r, %r)" % (self.__client, self.__name)
+
+    def __getattr__(self, name: str) -> Collection[_DocumentType]:
+        """Get a collection of this database by name.
+
+        Raises InvalidName if an invalid collection name is used.
+
+        :Parameters:
+          - `name`: the name of the collection to get
+        """
+        if name.startswith("_"):
+            raise AttributeError(
+                "Database has no attribute %r. To access the %s"
+                " collection, use database[%r]." % (name, name, name)
+            )
+        return self.__getitem__(name)
+
+    def __getitem__(self, name: str) -> "Collection[_DocumentType]":
+        """Get a collection of this database by name.
+
+        Raises InvalidName if an invalid collection name is used.
+
+        :Parameters:
+          - `name`: the name of the collection to get
+        """
+        return Collection(self, name)
+
+    def get_collection(
+        self,
+        name: str,
+        codec_options: Optional[CodecOptions] = None,
+        read_preference: Optional[_ServerMode] = None,
+        write_concern: Optional["WriteConcern"] = None,
+        read_concern: Optional["ReadConcern"] = None,
+    ) -> Collection[_DocumentType]:
+        """Get a :class:`~pymongo.collection.Collection` with the given name
+        and options.
+
+        Useful for creating a :class:`~pymongo.collection.Collection` with
+        different codec options, read preference, and/or write concern from
+        this :class:`Database`.
+
+          >>> db.read_preference
+          Primary()
+          >>> coll1 = db.test
+          >>> coll1.read_preference
+          Primary()
+          >>> from pymongo import ReadPreference
+          >>> coll2 = db.get_collection(
+          ...     'test', read_preference=ReadPreference.SECONDARY)
+          >>> coll2.read_preference
+          Secondary(tag_sets=None)
+
+        :Parameters:
+          - `name`: The name of the collection - a string.
+          - `codec_options` (optional): An instance of
+            :class:`~bson.codec_options.CodecOptions`. If ``None`` (the
+            default) the :attr:`codec_options` of this :class:`Database` is
+            used.
+          - `read_preference` (optional): The read preference to use. If
+            ``None`` (the default) the :attr:`read_preference` of this
+            :class:`Database` is used. See :mod:`~pymongo.read_preferences`
+            for options.
+          - `write_concern` (optional): An instance of
+            :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
+            default) the :attr:`write_concern` of this :class:`Database` is
+            used.
+          - `read_concern` (optional): An instance of
+            :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
+            default) the :attr:`read_concern` of this :class:`Database` is
+            used.
+        """
+        return Collection(
+            self,
+            name,
+            False,
+            codec_options,
+            read_preference,
+            write_concern,
+            read_concern,
+        )
+
+    @_csot.apply
+    def create_collection(
+        self,
+        name: str,
+        codec_options: Optional[CodecOptions] = None,
+        read_preference: Optional[_ServerMode] = None,
+        write_concern: Optional["WriteConcern"] = None,
+        read_concern: Optional["ReadConcern"] = None,
+        session: Optional["ClientSession"] = None,
+        check_exists: Optional[bool] = True,
+        **kwargs: Any,
+    ) -> Collection[_DocumentType]:
+        """Create a new :class:`~pymongo.collection.Collection` in this
+        database.
+
+        Normally collection creation is automatic. This method should
+        only be used to specify options on
+        creation. :class:`~pymongo.errors.CollectionInvalid` will be
+        raised if the collection already exists.
+
+        :Parameters:
+          - `name`: the name of the collection to create
+          - `codec_options` (optional): An instance of
+            :class:`~bson.codec_options.CodecOptions`. If ``None`` (the
+            default) the :attr:`codec_options` of this :class:`Database` is
+            used.
+          - `read_preference` (optional): The read preference to use. If
+            ``None`` (the default) the :attr:`read_preference` of this
+            :class:`Database` is used.
+          - `write_concern` (optional): An instance of
+            :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
+            default) the :attr:`write_concern` of this :class:`Database` is
+            used.
+          - `read_concern` (optional): An instance of
+            :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
+            default) the :attr:`read_concern` of this :class:`Database` is
+            used.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - ``check_exists`` (optional): if True (the default), send a listCollections command to
+            check if the collection already exists before creation.
+          - `**kwargs` (optional): additional keyword arguments will
+            be passed as options for the `create collection command`_
+
+        All optional `create collection command`_ parameters should be passed
+        as keyword arguments to this method. Valid options include, but are not
+        limited to:
+
+          - ``size`` (int): desired initial size for the collection (in
+            bytes). For capped collections this size is the max
+            size of the collection.
+          - ``capped`` (bool): if True, this is a capped collection
+          - ``max`` (int): maximum number of objects if capped (optional)
+          - ``timeseries`` (dict): a document specifying configuration options for
+            timeseries collections
+          - ``expireAfterSeconds`` (int): the number of seconds after which a
+            document in a timeseries collection expires
+          - ``validator`` (dict): a document specifying validation rules or expressions
+            for the collection
+          - ``validationLevel`` (str): how strictly to apply the
+            validation rules to existing documents during an update.  The default level
+            is "strict"
+          - ``validationAction`` (str): whether to "error" on invalid documents
+            (the default) or just "warn" about the violations but allow invalid
+            documents to be inserted
+          - ``indexOptionDefaults`` (dict): a document specifying a default configuration
+            for indexes when creating a collection
+          - ``viewOn`` (str): the name of the source collection or view from which
+            to create the view
+          - ``pipeline`` (list): a list of aggregation pipeline stages
+          - ``comment`` (str): a user-provided comment to attach to this command.
+            This option is only supported on MongoDB >= 4.4.
+          - ``encryptedFields`` (dict): **(BETA)** Document that describes the encrypted fields for
+            Queryable Encryption. For example::
+
+                {
+                  "escCollection": "enxcol_.encryptedCollection.esc",
+                  "eccCollection": "enxcol_.encryptedCollection.ecc",
+                  "ecocCollection": "enxcol_.encryptedCollection.ecoc",
+                  "fields": [
+                      {
+                          "path": "firstName",
+                          "keyId": Binary.from_uuid(UUID('00000000-0000-0000-0000-000000000000')),
+                          "bsonType": "string",
+                          "queries": {"queryType": "equality"}
+                      },
+                      {
+                          "path": "ssn",
+                          "keyId": Binary.from_uuid(UUID('04104104-1041-0410-4104-104104104104')),
+                          "bsonType": "string"
+                      }
+                    ]
+                }
+          - ``clusteredIndex`` (dict): Document that specifies the clustered index
+            configuration. It must have the following form::
+
+                {
+                    // key pattern must be {_id: 1}
+                    key: <key pattern>, // required
+                    unique: <bool>, // required, must be ‘true’
+                    name: <string>, // optional, otherwise automatically generated
+                    v: <int>, // optional, must be ‘2’ if provided
+                }
+          - ``changeStreamPreAndPostImages`` (dict): a document with a boolean field ``enabled`` for
+            enabling pre- and post-images.
+
+        .. versionchanged:: 4.2
+           Added the ``check_exists``, ``clusteredIndex``, and  ``encryptedFields`` parameters.
+
+        .. versionchanged:: 3.11
+           This method is now supported inside multi-document transactions
+           with MongoDB 4.4+.
+
+        .. versionchanged:: 3.6
+           Added ``session`` parameter.
+
+        .. versionchanged:: 3.4
+           Added the collation option.
+
+        .. versionchanged:: 3.0
+           Added the codec_options, read_preference, and write_concern options.
+
+        .. _create collection command:
+            https://mongodb.com/docs/manual/reference/command/create
+        """
+        encrypted_fields = kwargs.get("encryptedFields")
+        if (
+            not encrypted_fields
+            and self.client.options.auto_encryption_opts
+            and self.client.options.auto_encryption_opts._encrypted_fields_map
+        ):
+            encrypted_fields = self.client.options.auto_encryption_opts._encrypted_fields_map.get(
+                "%s.%s" % (self.name, name)
+            )
+            kwargs["encryptedFields"] = encrypted_fields
+
+        if encrypted_fields:
+            common.validate_is_mapping("encryptedFields", encrypted_fields)
+
+        clustered_index = kwargs.get("clusteredIndex")
+        if clustered_index:
+            common.validate_is_mapping("clusteredIndex", clustered_index)
+
+        with self.__client._tmp_session(session) as s:
+            # Skip this check in a transaction where listCollections is not
+            # supported.
+            if (
+                check_exists
+                and (not s or not s.in_transaction)
+                and name in self.list_collection_names(filter={"name": name}, session=s)
+            ):
+                raise CollectionInvalid("collection %s already exists" % name)
+            return Collection(
+                self,
+                name,
+                True,
+                codec_options,
+                read_preference,
+                write_concern,
+                read_concern,
+                session=s,
+                **kwargs,
+            )
+
+    def aggregate(
+        self, pipeline: _Pipeline, session: Optional["ClientSession"] = None, **kwargs: Any
+    ) -> CommandCursor[_DocumentType]:
+        """Perform a database-level aggregation.
+
+        See the `aggregation pipeline`_ documentation for a list of stages
+        that are supported.
+
+        .. code-block:: python
+
+           # Lists all operations currently running on the server.
+           with client.admin.aggregate([{"$currentOp": {}}]) as cursor:
+               for operation in cursor:
+                   print(operation)
+
+        The :meth:`aggregate` method obeys the :attr:`read_preference` of this
+        :class:`Database`, except when ``$out`` or ``$merge`` are used, in
+        which case  :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`
+        is used.
+
+        .. note:: This method does not support the 'explain' option. Please
+           use :meth:`~pymongo.database.Database.command` instead.
+
+        .. note:: The :attr:`~pymongo.database.Database.write_concern` of
+           this collection is automatically applied to this operation.
+
+        :Parameters:
+          - `pipeline`: a list of aggregation pipeline stages
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `**kwargs` (optional): extra `aggregate command`_ parameters.
+
+        All optional `aggregate command`_ parameters should be passed as
+        keyword arguments to this method. Valid options include, but are not
+        limited to:
+
+          - `allowDiskUse` (bool): Enables writing to temporary files. When set
+            to True, aggregation stages can write data to the _tmp subdirectory
+            of the --dbpath directory. The default is False.
+          - `maxTimeMS` (int): The maximum amount of time to allow the operation
+            to run in milliseconds.
+          - `batchSize` (int): The maximum number of documents to return per
+            batch. Ignored if the connected mongod or mongos does not support
+            returning aggregate results using a cursor.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `let` (dict): A dict of parameter names and values. Values must be
+            constant or closed expressions that do not reference document
+            fields. Parameters can then be accessed as variables in an
+            aggregate expression context (e.g. ``"$$var"``). This option is
+            only supported on MongoDB >= 5.0.
+
+        :Returns:
+          A :class:`~pymongo.command_cursor.CommandCursor` over the result
+          set.
+
+        .. versionadded:: 3.9
+
+        .. _aggregation pipeline:
+            https://mongodb.com/docs/manual/reference/operator/aggregation-pipeline
+
+        .. _aggregate command:
+            https://mongodb.com/docs/manual/reference/command/aggregate
+        """
+        with self.client._tmp_session(session, close=False) as s:
+            cmd = _DatabaseAggregationCommand(
+                self,
+                CommandCursor,
+                pipeline,
+                kwargs,
+                session is not None,
+                user_fields={"cursor": {"firstBatch": 1}},
+            )
+            return self.client._retryable_read(
+                cmd.get_cursor, cmd.get_read_preference(s), s, retryable=not cmd._performs_write
+            )
+
+    def watch(
+        self,
+        pipeline: Optional[_Pipeline] = None,
+        full_document: Optional[str] = None,
+        resume_after: Optional[Mapping[str, Any]] = None,
+        max_await_time_ms: Optional[int] = None,
+        batch_size: Optional[int] = None,
+        collation: Optional[_CollationIn] = None,
+        start_at_operation_time: Optional[Timestamp] = None,
+        session: Optional["ClientSession"] = None,
+        start_after: Optional[Mapping[str, Any]] = None,
+        comment: Optional[Any] = None,
+        full_document_before_change: Optional[str] = None,
+    ) -> DatabaseChangeStream[_DocumentType]:
+        """Watch changes on this database.
+
+        Performs an aggregation with an implicit initial ``$changeStream``
+        stage and returns a
+        :class:`~pymongo.change_stream.DatabaseChangeStream` cursor which
+        iterates over changes on all collections in this database.
+
+        Introduced in MongoDB 4.0.
+
+        .. code-block:: python
+
+           with db.watch() as stream:
+               for change in stream:
+                   print(change)
+
+        The :class:`~pymongo.change_stream.DatabaseChangeStream` iterable
+        blocks until the next change document is returned or an error is
+        raised. If the
+        :meth:`~pymongo.change_stream.DatabaseChangeStream.next` method
+        encounters a network error when retrieving a batch from the server,
+        it will automatically attempt to recreate the cursor such that no
+        change events are missed. Any error encountered during the resume
+        attempt indicates there may be an outage and will be raised.
+
+        .. code-block:: python
+
+            try:
+                with db.watch(
+                        [{'$match': {'operationType': 'insert'}}]) as stream:
+                    for insert_change in stream:
+                        print(insert_change)
+            except pymongo.errors.PyMongoError:
+                # The ChangeStream encountered an unrecoverable error or the
+                # resume attempt failed to recreate the cursor.
+                logging.error('...')
+
+        For a precise description of the resume process see the
+        `change streams specification`_.
+
+        :Parameters:
+          - `pipeline` (optional): A list of aggregation pipeline stages to
+            append to an initial ``$changeStream`` stage. Not all
+            pipeline stages are valid after a ``$changeStream`` stage, see the
+            MongoDB documentation on change streams for the supported stages.
+          - `full_document` (optional): The fullDocument to pass as an option
+            to the ``$changeStream`` stage. Allowed values: 'updateLookup',
+            'whenAvailable', 'required'. When set to 'updateLookup', the
+            change notification for partial updates will include both a delta
+            describing the changes to the document, as well as a copy of the
+            entire document that was changed from some time after the change
+            occurred.
+          - `full_document_before_change`: Allowed values: 'whenAvailable'
+            and 'required'. Change events may now result in a
+            'fullDocumentBeforeChange' response field.
+          - `resume_after` (optional): A resume token. If provided, the
+            change stream will start returning changes that occur directly
+            after the operation specified in the resume token. A resume token
+            is the _id value of a change document.
+          - `max_await_time_ms` (optional): The maximum time in milliseconds
+            for the server to wait for changes before responding to a getMore
+            operation.
+          - `batch_size` (optional): The maximum number of documents to return
+            per batch.
+          - `collation` (optional): The :class:`~pymongo.collation.Collation`
+            to use for the aggregation.
+          - `start_at_operation_time` (optional): If provided, the resulting
+            change stream will only return changes that occurred at or after
+            the specified :class:`~bson.timestamp.Timestamp`. Requires
+            MongoDB >= 4.0.
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `start_after` (optional): The same as `resume_after` except that
+            `start_after` can resume notifications after an invalidate event.
+            This option and `resume_after` are mutually exclusive.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+
+        :Returns:
+          A :class:`~pymongo.change_stream.DatabaseChangeStream` cursor.
+
+        .. versionchanged:: 4.2
+            Added ``full_document_before_change`` parameter.
+
+        .. versionchanged:: 4.1
+           Added ``comment`` parameter.
+
+        .. versionchanged:: 3.9
+           Added the ``start_after`` parameter.
+
+        .. versionadded:: 3.7
+
+        .. seealso:: The MongoDB documentation on `changeStreams <https://mongodb.com/docs/manual/changeStreams/>`_.
+
+        .. _change streams specification:
+            https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst
+        """
+        return DatabaseChangeStream(
+            self,
+            pipeline,
+            full_document,
+            resume_after,
+            max_await_time_ms,
+            batch_size,
+            collation,
+            start_at_operation_time,
+            session,
+            start_after,
+            comment,
+            full_document_before_change,
+        )
+
+    def _command(
+        self,
+        sock_info,
+        command,
+        value=1,
+        check=True,
+        allowable_errors=None,
+        read_preference=ReadPreference.PRIMARY,
+        codec_options=DEFAULT_CODEC_OPTIONS,
+        write_concern=None,
+        parse_write_concern_error=False,
+        session=None,
+        **kwargs,
+    ):
+        """Internal command helper."""
+        if isinstance(command, str):
+            command = SON([(command, value)])
+
+        command.update(kwargs)
+        with self.__client._tmp_session(session) as s:
+            return sock_info.command(
+                self.__name,
+                command,
+                read_preference,
+                codec_options,
+                check,
+                allowable_errors,
+                write_concern=write_concern,
+                parse_write_concern_error=parse_write_concern_error,
+                session=s,
+                client=self.__client,
+            )
+
+    @_csot.apply
+    def command(
+        self,
+        command: Union[str, MutableMapping[str, Any]],
+        value: Any = 1,
+        check: bool = True,
+        allowable_errors: Optional[Sequence[Union[str, int]]] = None,
+        read_preference: Optional[_ServerMode] = None,
+        codec_options: "Optional[bson.codec_options.CodecOptions[_CodecDocumentType]]" = None,
+        session: Optional["ClientSession"] = None,
+        comment: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> _CodecDocumentType:
+        """Issue a MongoDB command.
+
+        Send command `command` to the database and return the
+        response. If `command` is an instance of :class:`basestring`
+        (:class:`str` in python 3) then the command {`command`: `value`}
+        will be sent. Otherwise, `command` must be an instance of
+        :class:`dict` and will be sent as is.
+
+        Any additional keyword arguments will be added to the final
+        command document before it is sent.
+
+        For example, a command like ``{buildinfo: 1}`` can be sent
+        using:
+
+        >>> db.command("buildinfo")
+
+        For a command where the value matters, like ``{collstats:
+        collection_name}`` we can do:
+
+        >>> db.command("collstats", collection_name)
+
+        For commands that take additional arguments we can use
+        kwargs. So ``{filemd5: object_id, root: file_root}`` becomes:
+
+        >>> db.command("filemd5", object_id, root=file_root)
+
+        :Parameters:
+          - `command`: document representing the command to be issued,
+            or the name of the command (for simple commands only).
+
+            .. note:: the order of keys in the `command` document is
+               significant (the "verb" must come first), so commands
+               which require multiple keys (e.g. `findandmodify`)
+               should use an instance of :class:`~bson.son.SON` or
+               a string and kwargs instead of a Python `dict`.
+
+          - `value` (optional): value to use for the command verb when
+            `command` is passed as a string
+          - `check` (optional): check the response for errors, raising
+            :class:`~pymongo.errors.OperationFailure` if there are any
+          - `allowable_errors`: if `check` is ``True``, error messages
+            in this list will be ignored by error-checking
+          - `read_preference` (optional): The read preference for this
+            operation. See :mod:`~pymongo.read_preferences` for options.
+            If the provided `session` is in a transaction, defaults to the
+            read preference configured for the transaction.
+            Otherwise, defaults to
+            :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`.
+          - `codec_options`: A :class:`~bson.codec_options.CodecOptions`
+            instance.
+          - `session` (optional): A
+            :class:`~pymongo.client_session.ClientSession`.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+          - `**kwargs` (optional): additional keyword arguments will
+            be added to the command document before it is sent
+
+
+        .. note:: :meth:`command` does **not** obey this Database's
+           :attr:`read_preference` or :attr:`codec_options`. You must use the
+           ``read_preference`` and ``codec_options`` parameters instead.
+
+        .. note:: :meth:`command` does **not** apply any custom TypeDecoders
+           when decoding the command response.
+
+        .. note:: If this client has been configured to use MongoDB Stable
+           API (see :ref:`versioned-api-ref`), then :meth:`command` will
+           automatically add API versioning options to the given command.
+           Explicitly adding API versioning options in the command and
+           declaring an API version on the client is not supported.
+
+        .. versionchanged:: 3.6
+           Added ``session`` parameter.
+
+        .. versionchanged:: 3.0
+           Removed the `as_class`, `fields`, `uuid_subtype`, `tag_sets`,
+           and `secondary_acceptable_latency_ms` option.
+           Removed `compile_re` option: PyMongo now always represents BSON
+           regular expressions as :class:`~bson.regex.Regex` objects. Use
+           :meth:`~bson.regex.Regex.try_compile` to attempt to convert from a
+           BSON regular expression to a Python regular expression object.
+           Added the ``codec_options`` parameter.
+
+        .. seealso:: The MongoDB documentation on `commands <https://dochub.mongodb.org/core/commands>`_.
+        """
+        opts = codec_options or DEFAULT_CODEC_OPTIONS
+        if comment is not None:
+            kwargs["comment"] = comment
+
+        if read_preference is None:
+            read_preference = (session and session._txn_read_preference()) or ReadPreference.PRIMARY
+        with self.__client._socket_for_reads(read_preference, session) as (
+            sock_info,
+            read_preference,
+        ):
+            return self._command(
+                sock_info,
+                command,
+                value,
+                check,
+                allowable_errors,
+                read_preference,
+                opts,
+                session=session,
+                **kwargs,
+            )
+
+    def _retryable_read_command(
+        self,
+        command,
+        value=1,
+        check=True,
+        allowable_errors=None,
+        read_preference=None,
+        codec_options=DEFAULT_CODEC_OPTIONS,
+        session=None,
+        **kwargs,
+    ):
+        """Same as command but used for retryable read commands."""
+        if read_preference is None:
+            read_preference = (session and session._txn_read_preference()) or ReadPreference.PRIMARY
+
+        def _cmd(session, server, sock_info, read_preference):
+            return self._command(
+                sock_info,
+                command,
+                value,
+                check,
+                allowable_errors,
+                read_preference,
+                codec_options,
+                session=session,
+                **kwargs,
+            )
+
+        return self.__client._retryable_read(_cmd, read_preference, session)
+
+    def _list_collections(self, sock_info, session, read_preference, **kwargs):
+        """Internal listCollections helper."""
+
+        coll = self.get_collection("$cmd", read_preference=read_preference)
+        cmd = SON([("listCollections", 1), ("cursor", {})])
+        cmd.update(kwargs)
+        with self.__client._tmp_session(session, close=False) as tmp_session:
+            cursor = self._command(
+                sock_info, cmd, read_preference=read_preference, session=tmp_session
+            )["cursor"]
+            cmd_cursor = CommandCursor(
+                coll,
+                cursor,
+                sock_info.address,
+                session=tmp_session,
+                explicit_session=session is not None,
+                comment=cmd.get("comment"),
+            )
+        cmd_cursor._maybe_pin_connection(sock_info)
+        return cmd_cursor
+
+    def list_collections(
+        self,
+        session: Optional["ClientSession"] = None,
+        filter: Optional[Mapping[str, Any]] = None,
+        comment: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> CommandCursor[Dict[str, Any]]:
+        """Get a cursor over the collections of this database.
+
+        :Parameters:
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `filter` (optional):  A query document to filter the list of
+            collections returned from the listCollections command.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+          - `**kwargs` (optional): Optional parameters of the
+            `listCollections command
+            <https://mongodb.com/docs/manual/reference/command/listCollections/>`_
+            can be passed as keyword arguments to this method. The supported
+            options differ by server version.
+
+
+        :Returns:
+          An instance of :class:`~pymongo.command_cursor.CommandCursor`.
+
+        .. versionadded:: 3.6
+        """
+        if filter is not None:
+            kwargs["filter"] = filter
+        read_pref = (session and session._txn_read_preference()) or ReadPreference.PRIMARY
+        if comment is not None:
+            kwargs["comment"] = comment
+
+        def _cmd(session, server, sock_info, read_preference):
+            return self._list_collections(
+                sock_info, session, read_preference=read_preference, **kwargs
+            )
+
+        return self.__client._retryable_read(_cmd, read_pref, session)
+
+    def list_collection_names(
+        self,
+        session: Optional["ClientSession"] = None,
+        filter: Optional[Mapping[str, Any]] = None,
+        comment: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> List[str]:
+        """Get a list of all the collection names in this database.
+
+        For example, to list all non-system collections::
+
+            filter = {"name": {"$regex": r"^(?!system\\.)"}}
+            db.list_collection_names(filter=filter)
+
+        :Parameters:
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `filter` (optional):  A query document to filter the list of
+            collections returned from the listCollections command.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+          - `**kwargs` (optional): Optional parameters of the
+            `listCollections command
+            <https://mongodb.com/docs/manual/reference/command/listCollections/>`_
+            can be passed as keyword arguments to this method. The supported
+            options differ by server version.
+
+
+        .. versionchanged:: 3.8
+           Added the ``filter`` and ``**kwargs`` parameters.
+
+        .. versionadded:: 3.6
+        """
+        if comment is not None:
+            kwargs["comment"] = comment
+        if filter is None:
+            kwargs["nameOnly"] = True
+
+        else:
+            # The enumerate collections spec states that "drivers MUST NOT set
+            # nameOnly if a filter specifies any keys other than name."
+            common.validate_is_mapping("filter", filter)
+            kwargs["filter"] = filter
+            if not filter or (len(filter) == 1 and "name" in filter):
+                kwargs["nameOnly"] = True
+
+        return [result["name"] for result in self.list_collections(session=session, **kwargs)]
+
+    def _drop_helper(self, name, session=None, comment=None):
+        command = SON([("drop", name)])
+        if comment is not None:
+            command["comment"] = comment
+
+        with self.__client._socket_for_writes(session) as sock_info:
+            return self._command(
+                sock_info,
+                command,
+                allowable_errors=["ns not found", 26],
+                write_concern=self._write_concern_for(session),
+                parse_write_concern_error=True,
+                session=session,
+            )
+
+    @_csot.apply
+    def drop_collection(
+        self,
+        name_or_collection: Union[str, Collection],
+        session: Optional["ClientSession"] = None,
+        comment: Optional[Any] = None,
+        encrypted_fields: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Drop a collection.
+
+        :Parameters:
+          - `name_or_collection`: the name of a collection to drop or the
+            collection object itself
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+          - `encrypted_fields`: **(BETA)** Document that describes the encrypted fields for
+            Queryable Encryption. For example::
+
+                {
+                  "escCollection": "enxcol_.encryptedCollection.esc",
+                  "eccCollection": "enxcol_.encryptedCollection.ecc",
+                  "ecocCollection": "enxcol_.encryptedCollection.ecoc",
+                  "fields": [
+                      {
+                          "path": "firstName",
+                          "keyId": Binary.from_uuid(UUID('00000000-0000-0000-0000-000000000000')),
+                          "bsonType": "string",
+                          "queries": {"queryType": "equality"}
+                      },
+                      {
+                          "path": "ssn",
+                          "keyId": Binary.from_uuid(UUID('04104104-1041-0410-4104-104104104104')),
+                          "bsonType": "string"
+                      }
+                  ]
+
+                }
+
+
+        .. note:: The :attr:`~pymongo.database.Database.write_concern` of
+           this database is automatically applied to this operation.
+
+        .. versionchanged:: 4.2
+           Added ``encrypted_fields`` parameter.
+
+        .. versionchanged:: 4.1
+           Added ``comment`` parameter.
+
+        .. versionchanged:: 3.6
+           Added ``session`` parameter.
+
+        .. versionchanged:: 3.4
+           Apply this database's write concern automatically to this operation
+           when connected to MongoDB >= 3.4.
+
+        """
+        name = name_or_collection
+        if isinstance(name, Collection):
+            name = name.name
+
+        if not isinstance(name, str):
+            raise TypeError("name_or_collection must be an instance of str")
+        full_name = "%s.%s" % (self.name, name)
+        if (
+            not encrypted_fields
+            and self.client.options.auto_encryption_opts
+            and self.client.options.auto_encryption_opts._encrypted_fields_map
+        ):
+            encrypted_fields = self.client.options.auto_encryption_opts._encrypted_fields_map.get(
+                full_name
+            )
+        if not encrypted_fields and self.client.options.auto_encryption_opts:
+            colls = list(
+                self.list_collections(filter={"name": name}, session=session, comment=comment)
+            )
+            if colls and colls[0]["options"].get("encryptedFields"):
+                encrypted_fields = colls[0]["options"]["encryptedFields"]
+        if encrypted_fields:
+            common.validate_is_mapping("encrypted_fields", encrypted_fields)
+            self._drop_helper(
+                _esc_coll_name(encrypted_fields, name), session=session, comment=comment
+            )
+            self._drop_helper(
+                _ecc_coll_name(encrypted_fields, name), session=session, comment=comment
+            )
+            self._drop_helper(
+                _ecoc_coll_name(encrypted_fields, name), session=session, comment=comment
+            )
+
+        return self._drop_helper(name, session, comment)
+
+    def validate_collection(
+        self,
+        name_or_collection: Union[str, Collection],
+        scandata: bool = False,
+        full: bool = False,
+        session: Optional["ClientSession"] = None,
+        background: Optional[bool] = None,
+        comment: Optional[Any] = None,
+    ) -> Dict[str, Any]:
+        """Validate a collection.
+
+        Returns a dict of validation info. Raises CollectionInvalid if
+        validation fails.
+
+        See also the MongoDB documentation on the `validate command`_.
+
+        :Parameters:
+          - `name_or_collection`: A Collection object or the name of a
+            collection to validate.
+          - `scandata`: Do extra checks beyond checking the overall
+            structure of the collection.
+          - `full`: Have the server do a more thorough scan of the
+            collection. Use with `scandata` for a thorough scan
+            of the structure of the collection and the individual
+            documents.
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `background` (optional): A boolean flag that determines whether
+            the command runs in the background. Requires MongoDB 4.4+.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+
+        .. versionchanged:: 4.1
+           Added ``comment`` parameter.
+
+        .. versionchanged:: 3.11
+           Added ``background`` parameter.
+
+        .. versionchanged:: 3.6
+           Added ``session`` parameter.
+
+        .. _validate command: https://mongodb.com/docs/manual/reference/command/validate/
+        """
+        name = name_or_collection
+        if isinstance(name, Collection):
+            name = name.name
+
+        if not isinstance(name, str):
+            raise TypeError("name_or_collection must be an instance of str or Collection")
+        cmd = SON([("validate", name), ("scandata", scandata), ("full", full)])
+        if comment is not None:
+            cmd["comment"] = comment
+
+        if background is not None:
+            cmd["background"] = background
+
+        result = cast(dict, self.command(cmd, session=session))
+
+        valid = True
+        # Pre 1.9 results
+        if "result" in result:
+            info = result["result"]
+            if info.find("exception") != -1 or info.find("corrupt") != -1:
+                raise CollectionInvalid("%s invalid: %s" % (name, info))
+        # Sharded results
+        elif "raw" in result:
+            for _, res in result["raw"].items():
+                if "result" in res:
+                    info = res["result"]
+                    if info.find("exception") != -1 or info.find("corrupt") != -1:
+                        raise CollectionInvalid("%s invalid: %s" % (name, info))
+                elif not res.get("valid", False):
+                    valid = False
+                    break
+        # Post 1.9 non-sharded results.
+        elif not result.get("valid", False):
+            valid = False
+
+        if not valid:
+            raise CollectionInvalid("%s invalid: %r" % (name, result))
+
+        return result
+
+    # See PYTHON-3084.
+    __iter__ = None
+
+    def __next__(self) -> NoReturn:
+        raise TypeError("'Database' object is not iterable")
+
+    next = __next__
+
+    def __bool__(self) -> NoReturn:
+        raise NotImplementedError(
+            "Database objects do not implement truth "
+            "value testing or bool(). Please compare "
+            "with None instead: database is not None"
+        )
+
+    def dereference(
+        self,
+        dbref: DBRef,
+        session: Optional["ClientSession"] = None,
+        comment: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> Optional[_DocumentType]:
+        """Dereference a :class:`~bson.dbref.DBRef`, getting the
+        document it points to.
+
+        Raises :class:`TypeError` if `dbref` is not an instance of
+        :class:`~bson.dbref.DBRef`. Returns a document, or ``None`` if
+        the reference does not point to a valid document.  Raises
+        :class:`ValueError` if `dbref` has a database specified that
+        is different from the current database.
+
+        :Parameters:
+          - `dbref`: the reference
+          - `session` (optional): a
+            :class:`~pymongo.client_session.ClientSession`.
+          - `comment` (optional): A user-provided comment to attach to this
+            command.
+          - `**kwargs` (optional): any additional keyword arguments
+            are the same as the arguments to
+            :meth:`~pymongo.collection.Collection.find`.
+
+
+        .. versionchanged:: 4.1
+           Added ``comment`` parameter.
+        .. versionchanged:: 3.6
+           Added ``session`` parameter.
+        """
+        if not isinstance(dbref, DBRef):
+            raise TypeError("cannot dereference a %s" % type(dbref))
+        if dbref.database is not None and dbref.database != self.__name:
+            raise ValueError(
+                "trying to dereference a DBRef that points to "
+                "another database (%r not %r)" % (dbref.database, self.__name)
+            )
+        return self[dbref.collection].find_one(
+            {"_id": dbref.id}, session=session, comment=comment, **kwargs
+        )