sensu-plugins-mongodb-mrtrotl 1.4.0

data/lib/pymongo/cursor.py

@@ -0,0 +1,1345 @@
+# 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.
+
+"""Cursor class to iterate over Mongo query results."""
+import copy
+import threading
+import warnings
+from collections import deque
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Generic,
+    Iterable,
+    List,
+    Mapping,
+    NoReturn,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+    cast,
+    overload,
+)
+
+from bson import RE_TYPE, _convert_raw_document_lists_to_streams
+from bson.code import Code
+from bson.son import SON
+from pymongo import helpers
+from pymongo.collation import validate_collation_or_none
+from pymongo.common import (
+    validate_boolean,
+    validate_is_document_type,
+    validate_is_mapping,
+)
+from pymongo.errors import ConnectionFailure, InvalidOperation, OperationFailure
+from pymongo.message import (
+    _CursorAddress,
+    _GetMore,
+    _Query,
+    _RawBatchGetMore,
+    _RawBatchQuery,
+)
+from pymongo.response import PinnedResponse
+from pymongo.typings import _CollationIn, _DocumentType
+
+# These errors mean that the server has already killed the cursor so there is
+# no need to send killCursors.
+_CURSOR_CLOSED_ERRORS = frozenset(
+    [
+        43,  # CursorNotFound
+        50,  # MaxTimeMSExpired
+        175,  # QueryPlanKilled
+        237,  # CursorKilled
+        # On a tailable cursor, the following errors mean the capped collection
+        # rolled over.
+        # MongoDB 2.6:
+        # {'$err': 'Runner killed during getMore', 'code': 28617, 'ok': 0}
+        28617,
+        # MongoDB 3.0:
+        # {'$err': 'getMore executor error: UnknownError no details available',
+        #  'code': 17406, 'ok': 0}
+        17406,
+        # MongoDB 3.2 + 3.4:
+        # {'ok': 0.0, 'errmsg': 'GetMore command executor error:
+        #  CappedPositionLost: CollectionScan died due to failure to restore
+        #  tailable cursor position. Last seen record id: RecordId(3)',
+        #  'code': 96}
+        96,
+        # MongoDB 3.6+:
+        # {'ok': 0.0, 'errmsg': 'errmsg: "CollectionScan died due to failure to
+        #  restore tailable cursor position. Last seen record id: RecordId(3)"',
+        #  'code': 136, 'codeName': 'CappedPositionLost'}
+        136,
+    ]
+)
+
+_QUERY_OPTIONS = {
+    "tailable_cursor": 2,
+    "secondary_okay": 4,
+    "oplog_replay": 8,
+    "no_timeout": 16,
+    "await_data": 32,
+    "exhaust": 64,
+    "partial": 128,
+}
+
+
+class CursorType(object):
+    NON_TAILABLE = 0
+    """The standard cursor type."""
+
+    TAILABLE = _QUERY_OPTIONS["tailable_cursor"]
+    """The tailable cursor type.
+
+    Tailable cursors are only for use with capped collections. They are not
+    closed when the last data is retrieved but are kept open and the cursor
+    location marks the final document position. If more data is received
+    iteration of the cursor will continue from the last document received.
+    """
+
+    TAILABLE_AWAIT = TAILABLE | _QUERY_OPTIONS["await_data"]
+    """A tailable cursor with the await option set.
+
+    Creates a tailable cursor that will wait for a few seconds after returning
+    the full result set so that it can capture and return additional data added
+    during the query.
+    """
+
+    EXHAUST = _QUERY_OPTIONS["exhaust"]
+    """An exhaust cursor.
+
+    MongoDB will stream batched results to the client without waiting for the
+    client to request each batch, reducing latency.
+    """
+
+
+class _SocketManager(object):
+    """Used with exhaust cursors to ensure the socket is returned."""
+
+    def __init__(self, sock, more_to_come):
+        self.sock = sock
+        self.more_to_come = more_to_come
+        self.closed = False
+        self.lock = threading.Lock()
+
+    def update_exhaust(self, more_to_come):
+        self.more_to_come = more_to_come
+
+    def close(self):
+        """Return this instance's socket to the connection pool."""
+        if not self.closed:
+            self.closed = True
+            self.sock.unpin()
+            self.sock = None
+
+
+_Sort = Sequence[Tuple[str, Union[int, str, Mapping[str, Any]]]]
+_Hint = Union[str, _Sort]
+
+
+if TYPE_CHECKING:
+    from pymongo.client_session import ClientSession
+    from pymongo.collection import Collection
+
+
+class Cursor(Generic[_DocumentType]):
+    """A cursor / iterator over Mongo query results."""
+
+    _query_class = _Query
+    _getmore_class = _GetMore
+
+    def __init__(
+        self,
+        collection: "Collection[_DocumentType]",
+        filter: Optional[Mapping[str, Any]] = None,
+        projection: Optional[Union[Mapping[str, Any], Iterable[str]]] = None,
+        skip: int = 0,
+        limit: int = 0,
+        no_cursor_timeout: bool = False,
+        cursor_type: int = CursorType.NON_TAILABLE,
+        sort: Optional[_Sort] = None,
+        allow_partial_results: bool = False,
+        oplog_replay: bool = False,
+        batch_size: int = 0,
+        collation: Optional[_CollationIn] = None,
+        hint: Optional[_Hint] = None,
+        max_scan: Optional[int] = None,
+        max_time_ms: Optional[int] = None,
+        max: Optional[_Sort] = None,
+        min: Optional[_Sort] = None,
+        return_key: Optional[bool] = None,
+        show_record_id: Optional[bool] = None,
+        snapshot: Optional[bool] = None,
+        comment: Optional[Any] = None,
+        session: Optional["ClientSession"] = None,
+        allow_disk_use: Optional[bool] = None,
+        let: Optional[bool] = None,
+    ) -> None:
+        """Create a new cursor.
+
+        Should not be called directly by application developers - see
+        :meth:`~pymongo.collection.Collection.find` instead.
+
+        .. seealso:: The MongoDB documentation on `cursors <https://dochub.mongodb.org/core/cursors>`_.
+        """
+        # Initialize all attributes used in __del__ before possibly raising
+        # an error to avoid attribute errors during garbage collection.
+        self.__collection: Collection[_DocumentType] = collection
+        self.__id: Any = None
+        self.__exhaust = False
+        self.__sock_mgr: Any = None
+        self.__killed = False
+        self.__session: Optional["ClientSession"]
+
+        if session:
+            self.__session = session
+            self.__explicit_session = True
+        else:
+            self.__session = None
+            self.__explicit_session = False
+
+        spec: Mapping[str, Any] = filter or {}
+        validate_is_mapping("filter", spec)
+        if not isinstance(skip, int):
+            raise TypeError("skip must be an instance of int")
+        if not isinstance(limit, int):
+            raise TypeError("limit must be an instance of int")
+        validate_boolean("no_cursor_timeout", no_cursor_timeout)
+        if no_cursor_timeout and not self.__explicit_session:
+            warnings.warn(
+                "use an explicit session with no_cursor_timeout=True "
+                "otherwise the cursor may still timeout after "
+                "30 minutes, for more info see "
+                "https://mongodb.com/docs/v4.4/reference/method/"
+                "cursor.noCursorTimeout/"
+                "#session-idle-timeout-overrides-nocursortimeout",
+                UserWarning,
+                stacklevel=2,
+            )
+        if cursor_type not in (
+            CursorType.NON_TAILABLE,
+            CursorType.TAILABLE,
+            CursorType.TAILABLE_AWAIT,
+            CursorType.EXHAUST,
+        ):
+            raise ValueError("not a valid value for cursor_type")
+        validate_boolean("allow_partial_results", allow_partial_results)
+        validate_boolean("oplog_replay", oplog_replay)
+        if not isinstance(batch_size, int):
+            raise TypeError("batch_size must be an integer")
+        if batch_size < 0:
+            raise ValueError("batch_size must be >= 0")
+        # Only set if allow_disk_use is provided by the user, else None.
+        if allow_disk_use is not None:
+            allow_disk_use = validate_boolean("allow_disk_use", allow_disk_use)
+
+        if projection is not None:
+            projection = helpers._fields_list_to_dict(projection, "projection")
+
+        if let is not None:
+            validate_is_document_type("let", let)
+
+        self.__let = let
+        self.__spec = spec
+        self.__has_filter = filter is not None
+        self.__projection = projection
+        self.__skip = skip
+        self.__limit = limit
+        self.__batch_size = batch_size
+        self.__ordering = sort and helpers._index_document(sort) or None
+        self.__max_scan = max_scan
+        self.__explain = False
+        self.__comment = comment
+        self.__max_time_ms = max_time_ms
+        self.__max_await_time_ms: Optional[int] = None
+        self.__max: Optional[Union[SON[Any, Any], _Sort]] = max
+        self.__min: Optional[Union[SON[Any, Any], _Sort]] = min
+        self.__collation = validate_collation_or_none(collation)
+        self.__return_key = return_key
+        self.__show_record_id = show_record_id
+        self.__allow_disk_use = allow_disk_use
+        self.__snapshot = snapshot
+        self.__set_hint(hint)
+
+        # Exhaust cursor support
+        if cursor_type == CursorType.EXHAUST:
+            if self.__collection.database.client.is_mongos:
+                raise InvalidOperation("Exhaust cursors are not supported by mongos")
+            if limit:
+                raise InvalidOperation("Can't use limit and exhaust together.")
+            self.__exhaust = True
+
+        # This is ugly. People want to be able to do cursor[5:5] and
+        # get an empty result set (old behavior was an
+        # exception). It's hard to do that right, though, because the
+        # server uses limit(0) to mean 'no limit'. So we set __empty
+        # in that case and check for it when iterating. We also unset
+        # it anytime we change __limit.
+        self.__empty = False
+
+        self.__data: deque = deque()
+        self.__address = None
+        self.__retrieved = 0
+
+        self.__codec_options = collection.codec_options
+        # Read preference is set when the initial find is sent.
+        self.__read_preference = None
+        self.__read_concern = collection.read_concern
+
+        self.__query_flags = cursor_type
+        if no_cursor_timeout:
+            self.__query_flags |= _QUERY_OPTIONS["no_timeout"]
+        if allow_partial_results:
+            self.__query_flags |= _QUERY_OPTIONS["partial"]
+        if oplog_replay:
+            self.__query_flags |= _QUERY_OPTIONS["oplog_replay"]
+
+        # The namespace to use for find/getMore commands.
+        self.__dbname = collection.database.name
+        self.__collname = collection.name
+
+    @property
+    def collection(self) -> "Collection[_DocumentType]":
+        """The :class:`~pymongo.collection.Collection` that this
+        :class:`Cursor` is iterating.
+        """
+        return self.__collection
+
+    @property
+    def retrieved(self) -> int:
+        """The number of documents retrieved so far."""
+        return self.__retrieved
+
+    def __del__(self) -> None:
+        self.__die()
+
+    def rewind(self) -> "Cursor[_DocumentType]":
+        """Rewind this cursor to its unevaluated state.
+
+        Reset this cursor if it has been partially or completely evaluated.
+        Any options that are present on the cursor will remain in effect.
+        Future iterating performed on this cursor will cause new queries to
+        be sent to the server, even if the resultant data has already been
+        retrieved by this cursor.
+        """
+        self.close()
+        self.__data = deque()
+        self.__id = None
+        self.__address = None
+        self.__retrieved = 0
+        self.__killed = False
+
+        return self
+
+    def clone(self) -> "Cursor[_DocumentType]":
+        """Get a clone of this cursor.
+
+        Returns a new Cursor instance with options matching those that have
+        been set on the current instance. The clone will be completely
+        unevaluated, even if the current instance has been partially or
+        completely evaluated.
+        """
+        return self._clone(True)
+
+    def _clone(self, deepcopy=True, base=None):
+        """Internal clone helper."""
+        if not base:
+            if self.__explicit_session:
+                base = self._clone_base(self.__session)
+            else:
+                base = self._clone_base(None)
+
+        values_to_clone = (
+            "spec",
+            "projection",
+            "skip",
+            "limit",
+            "max_time_ms",
+            "max_await_time_ms",
+            "comment",
+            "max",
+            "min",
+            "ordering",
+            "explain",
+            "hint",
+            "batch_size",
+            "max_scan",
+            "query_flags",
+            "collation",
+            "empty",
+            "show_record_id",
+            "return_key",
+            "allow_disk_use",
+            "snapshot",
+            "exhaust",
+            "has_filter",
+        )
+        data = dict(
+            (k, v)
+            for k, v in self.__dict__.items()
+            if k.startswith("_Cursor__") and k[9:] in values_to_clone
+        )
+        if deepcopy:
+            data = self._deepcopy(data)
+        base.__dict__.update(data)
+        return base
+
+    def _clone_base(self, session):
+        """Creates an empty Cursor object for information to be copied into."""
+        return self.__class__(self.__collection, session=session)
+
+    def __die(self, synchronous=False):
+        """Closes this cursor."""
+        try:
+            already_killed = self.__killed
+        except AttributeError:
+            # __init__ did not run to completion (or at all).
+            return
+
+        self.__killed = True
+        if self.__id and not already_killed:
+            cursor_id = self.__id
+            address = _CursorAddress(self.__address, "%s.%s" % (self.__dbname, self.__collname))
+        else:
+            # Skip killCursors.
+            cursor_id = 0
+            address = None
+        self.__collection.database.client._cleanup_cursor(
+            synchronous,
+            cursor_id,
+            address,
+            self.__sock_mgr,
+            self.__session,
+            self.__explicit_session,
+        )
+        if not self.__explicit_session:
+            self.__session = None
+        self.__sock_mgr = None
+
+    def close(self) -> None:
+        """Explicitly close / kill this cursor."""
+        self.__die(True)
+
+    def __query_spec(self):
+        """Get the spec to use for a query."""
+        operators = {}
+        if self.__ordering:
+            operators["$orderby"] = self.__ordering
+        if self.__explain:
+            operators["$explain"] = True
+        if self.__hint:
+            operators["$hint"] = self.__hint
+        if self.__let:
+            operators["let"] = self.__let
+        if self.__comment:
+            operators["$comment"] = self.__comment
+        if self.__max_scan:
+            operators["$maxScan"] = self.__max_scan
+        if self.__max_time_ms is not None:
+            operators["$maxTimeMS"] = self.__max_time_ms
+        if self.__max:
+            operators["$max"] = self.__max
+        if self.__min:
+            operators["$min"] = self.__min
+        if self.__return_key is not None:
+            operators["$returnKey"] = self.__return_key
+        if self.__show_record_id is not None:
+            # This is upgraded to showRecordId for MongoDB 3.2+ "find" command.
+            operators["$showDiskLoc"] = self.__show_record_id
+        if self.__snapshot is not None:
+            operators["$snapshot"] = self.__snapshot
+
+        if operators:
+            # Make a shallow copy so we can cleanly rewind or clone.
+            spec = copy.copy(self.__spec)
+
+            # Allow-listed commands must be wrapped in $query.
+            if "$query" not in spec:
+                # $query has to come first
+                spec = SON([("$query", spec)])
+
+            if not isinstance(spec, SON):
+                # Ensure the spec is SON. As order is important this will
+                # ensure its set before merging in any extra operators.
+                spec = SON(spec)
+
+            spec.update(operators)
+            return spec
+        # Have to wrap with $query if "query" is the first key.
+        # We can't just use $query anytime "query" is a key as
+        # that breaks commands like count and find_and_modify.
+        # Checking spec.keys()[0] covers the case that the spec
+        # was passed as an instance of SON or OrderedDict.
+        elif "query" in self.__spec and (
+            len(self.__spec) == 1 or next(iter(self.__spec)) == "query"
+        ):
+            return SON({"$query": self.__spec})
+
+        return self.__spec
+
+    def __check_okay_to_chain(self):
+        """Check if it is okay to chain more options onto this cursor."""
+        if self.__retrieved or self.__id is not None:
+            raise InvalidOperation("cannot set options after executing query")
+
+    def add_option(self, mask: int) -> "Cursor[_DocumentType]":
+        """Set arbitrary query flags using a bitmask.
+
+        To set the tailable flag:
+        cursor.add_option(2)
+        """
+        if not isinstance(mask, int):
+            raise TypeError("mask must be an int")
+        self.__check_okay_to_chain()
+
+        if mask & _QUERY_OPTIONS["exhaust"]:
+            if self.__limit:
+                raise InvalidOperation("Can't use limit and exhaust together.")
+            if self.__collection.database.client.is_mongos:
+                raise InvalidOperation("Exhaust cursors are not supported by mongos")
+            self.__exhaust = True
+
+        self.__query_flags |= mask
+        return self
+
+    def remove_option(self, mask: int) -> "Cursor[_DocumentType]":
+        """Unset arbitrary query flags using a bitmask.
+
+        To unset the tailable flag:
+        cursor.remove_option(2)
+        """
+        if not isinstance(mask, int):
+            raise TypeError("mask must be an int")
+        self.__check_okay_to_chain()
+
+        if mask & _QUERY_OPTIONS["exhaust"]:
+            self.__exhaust = False
+
+        self.__query_flags &= ~mask
+        return self
+
+    def allow_disk_use(self, allow_disk_use: bool) -> "Cursor[_DocumentType]":
+        """Specifies whether MongoDB can use temporary disk files while
+        processing a blocking sort operation.
+
+        Raises :exc:`TypeError` if `allow_disk_use` is not a boolean.
+
+        .. note:: `allow_disk_use` requires server version **>= 4.4**
+
+        :Parameters:
+          - `allow_disk_use`: if True, MongoDB may use temporary
+            disk files to store data exceeding the system memory limit while
+            processing a blocking sort operation.
+
+        .. versionadded:: 3.11
+        """
+        if not isinstance(allow_disk_use, bool):
+            raise TypeError("allow_disk_use must be a bool")
+        self.__check_okay_to_chain()
+
+        self.__allow_disk_use = allow_disk_use
+        return self
+
+    def limit(self, limit: int) -> "Cursor[_DocumentType]":
+        """Limits the number of results to be returned by this cursor.
+
+        Raises :exc:`TypeError` if `limit` is not an integer. Raises
+        :exc:`~pymongo.errors.InvalidOperation` if this :class:`Cursor`
+        has already been used. The last `limit` applied to this cursor
+        takes precedence. A limit of ``0`` is equivalent to no limit.
+
+        :Parameters:
+          - `limit`: the number of results to return
+
+        .. seealso:: The MongoDB documentation on `limit <https://dochub.mongodb.org/core/limit>`_.
+        """
+        if not isinstance(limit, int):
+            raise TypeError("limit must be an integer")
+        if self.__exhaust:
+            raise InvalidOperation("Can't use limit and exhaust together.")
+        self.__check_okay_to_chain()
+
+        self.__empty = False
+        self.__limit = limit
+        return self
+
+    def batch_size(self, batch_size: int) -> "Cursor[_DocumentType]":
+        """Limits the number of documents returned in one batch. Each batch
+        requires a round trip to the server. It can be adjusted to optimize
+        performance and limit data transfer.
+
+        .. note:: batch_size can not override MongoDB's internal limits on the
+           amount of data it will return to the client in a single batch (i.e
+           if you set batch size to 1,000,000,000, MongoDB will currently only
+           return 4-16MB of results per batch).
+
+        Raises :exc:`TypeError` if `batch_size` is not an integer.
+        Raises :exc:`ValueError` if `batch_size` is less than ``0``.
+        Raises :exc:`~pymongo.errors.InvalidOperation` if this
+        :class:`Cursor` has already been used. The last `batch_size`
+        applied to this cursor takes precedence.
+
+        :Parameters:
+          - `batch_size`: The size of each batch of results requested.
+        """
+        if not isinstance(batch_size, int):
+            raise TypeError("batch_size must be an integer")
+        if batch_size < 0:
+            raise ValueError("batch_size must be >= 0")
+        self.__check_okay_to_chain()
+
+        self.__batch_size = batch_size
+        return self
+
+    def skip(self, skip: int) -> "Cursor[_DocumentType]":
+        """Skips the first `skip` results of this cursor.
+
+        Raises :exc:`TypeError` if `skip` is not an integer. Raises
+        :exc:`ValueError` if `skip` is less than ``0``. Raises
+        :exc:`~pymongo.errors.InvalidOperation` if this :class:`Cursor` has
+        already been used. The last `skip` applied to this cursor takes
+        precedence.
+
+        :Parameters:
+          - `skip`: the number of results to skip
+        """
+        if not isinstance(skip, int):
+            raise TypeError("skip must be an integer")
+        if skip < 0:
+            raise ValueError("skip must be >= 0")
+        self.__check_okay_to_chain()
+
+        self.__skip = skip
+        return self
+
+    def max_time_ms(self, max_time_ms: Optional[int]) -> "Cursor[_DocumentType]":
+        """Specifies a time limit for a query operation. If the specified
+        time is exceeded, the operation will be aborted and
+        :exc:`~pymongo.errors.ExecutionTimeout` is raised. If `max_time_ms`
+        is ``None`` no limit is applied.
+
+        Raises :exc:`TypeError` if `max_time_ms` is not an integer or ``None``.
+        Raises :exc:`~pymongo.errors.InvalidOperation` if this :class:`Cursor`
+        has already been used.
+
+        :Parameters:
+          - `max_time_ms`: the time limit after which the operation is aborted
+        """
+        if not isinstance(max_time_ms, int) and max_time_ms is not None:
+            raise TypeError("max_time_ms must be an integer or None")
+        self.__check_okay_to_chain()
+
+        self.__max_time_ms = max_time_ms
+        return self
+
+    def max_await_time_ms(self, max_await_time_ms: Optional[int]) -> "Cursor[_DocumentType]":
+        """Specifies a time limit for a getMore operation on a
+        :attr:`~pymongo.cursor.CursorType.TAILABLE_AWAIT` cursor. For all other
+        types of cursor max_await_time_ms is ignored.
+
+        Raises :exc:`TypeError` if `max_await_time_ms` is not an integer or
+        ``None``. Raises :exc:`~pymongo.errors.InvalidOperation` if this
+        :class:`Cursor` has already been used.
+
+        .. note:: `max_await_time_ms` requires server version **>= 3.2**
+
+        :Parameters:
+          - `max_await_time_ms`: the time limit after which the operation is
+            aborted
+
+        .. versionadded:: 3.2
+        """
+        if not isinstance(max_await_time_ms, int) and max_await_time_ms is not None:
+            raise TypeError("max_await_time_ms must be an integer or None")
+        self.__check_okay_to_chain()
+
+        # Ignore max_await_time_ms if not tailable or await_data is False.
+        if self.__query_flags & CursorType.TAILABLE_AWAIT:
+            self.__max_await_time_ms = max_await_time_ms
+
+        return self
+
+    @overload
+    def __getitem__(self, index: int) -> _DocumentType:
+        ...
+
+    @overload
+    def __getitem__(self, index: slice) -> "Cursor[_DocumentType]":
+        ...
+
+    def __getitem__(self, index):
+        """Get a single document or a slice of documents from this cursor.
+
+        .. warning:: A :class:`~Cursor` is not a Python :class:`list`. Each
+          index access or slice requires that a new query be run using skip
+          and limit. Do not iterate the cursor using index accesses.
+          The following example is **extremely inefficient** and may return
+          surprising results::
+
+            cursor = db.collection.find()
+            # Warning: This runs a new query for each document.
+            # Don't do this!
+            for idx in range(10):
+                print(cursor[idx])
+
+        Raises :class:`~pymongo.errors.InvalidOperation` if this
+        cursor has already been used.
+
+        To get a single document use an integral index, e.g.::
+
+          >>> db.test.find()[50]
+
+        An :class:`IndexError` will be raised if the index is negative
+        or greater than the amount of documents in this cursor. Any
+        limit previously applied to this cursor will be ignored.
+
+        To get a slice of documents use a slice index, e.g.::
+
+          >>> db.test.find()[20:25]
+
+        This will return this cursor with a limit of ``5`` and skip of
+        ``20`` applied.  Using a slice index will override any prior
+        limits or skips applied to this cursor (including those
+        applied through previous calls to this method). Raises
+        :class:`IndexError` when the slice has a step, a negative
+        start value, or a stop value less than or equal to the start
+        value.
+
+        :Parameters:
+          - `index`: An integer or slice index to be applied to this cursor
+        """
+        self.__check_okay_to_chain()
+        self.__empty = False
+        if isinstance(index, slice):
+            if index.step is not None:
+                raise IndexError("Cursor instances do not support slice steps")
+
+            skip = 0
+            if index.start is not None:
+                if index.start < 0:
+                    raise IndexError("Cursor instances do not support negative indices")
+                skip = index.start
+
+            if index.stop is not None:
+                limit = index.stop - skip
+                if limit < 0:
+                    raise IndexError(
+                        "stop index must be greater than start index for slice %r" % index
+                    )
+                if limit == 0:
+                    self.__empty = True
+            else:
+                limit = 0
+
+            self.__skip = skip
+            self.__limit = limit
+            return self
+
+        if isinstance(index, int):
+            if index < 0:
+                raise IndexError("Cursor instances do not support negative indices")
+            clone = self.clone()
+            clone.skip(index + self.__skip)
+            clone.limit(-1)  # use a hard limit
+            clone.__query_flags &= ~CursorType.TAILABLE_AWAIT  # PYTHON-1371
+            for doc in clone:
+                return doc
+            raise IndexError("no such item for Cursor instance")
+        raise TypeError("index %r cannot be applied to Cursor instances" % index)
+
+    def max_scan(self, max_scan: Optional[int]) -> "Cursor[_DocumentType]":
+        """**DEPRECATED** - Limit the number of documents to scan when
+        performing the query.
+
+        Raises :class:`~pymongo.errors.InvalidOperation` if this
+        cursor has already been used. Only the last :meth:`max_scan`
+        applied to this cursor has any effect.
+
+        :Parameters:
+          - `max_scan`: the maximum number of documents to scan
+
+        .. versionchanged:: 3.7
+          Deprecated :meth:`max_scan`. Support for this option is deprecated in
+          MongoDB 4.0. Use :meth:`max_time_ms` instead to limit server side
+          execution time.
+        """
+        self.__check_okay_to_chain()
+        self.__max_scan = max_scan
+        return self
+
+    def max(self, spec: _Sort) -> "Cursor[_DocumentType]":
+        """Adds ``max`` operator that specifies upper bound for specific index.
+
+        When using ``max``, :meth:`~hint` should also be configured to ensure
+        the query uses the expected index and starting in MongoDB 4.2
+        :meth:`~hint` will be required.
+
+        :Parameters:
+          - `spec`: a list of field, limit pairs specifying the exclusive
+            upper bound for all keys of a specific index in order.
+
+        .. versionchanged:: 3.8
+           Deprecated cursors that use ``max`` without a :meth:`~hint`.
+
+        .. versionadded:: 2.7
+        """
+        if not isinstance(spec, (list, tuple)):
+            raise TypeError("spec must be an instance of list or tuple")
+
+        self.__check_okay_to_chain()
+        self.__max = SON(spec)
+        return self
+
+    def min(self, spec: _Sort) -> "Cursor[_DocumentType]":
+        """Adds ``min`` operator that specifies lower bound for specific index.
+
+        When using ``min``, :meth:`~hint` should also be configured to ensure
+        the query uses the expected index and starting in MongoDB 4.2
+        :meth:`~hint` will be required.
+
+        :Parameters:
+          - `spec`: a list of field, limit pairs specifying the inclusive
+            lower bound for all keys of a specific index in order.
+
+        .. versionchanged:: 3.8
+           Deprecated cursors that use ``min`` without a :meth:`~hint`.
+
+        .. versionadded:: 2.7
+        """
+        if not isinstance(spec, (list, tuple)):
+            raise TypeError("spec must be an instance of list or tuple")
+
+        self.__check_okay_to_chain()
+        self.__min = SON(spec)
+        return self
+
+    def sort(
+        self, key_or_list: _Hint, direction: Optional[Union[int, str]] = None
+    ) -> "Cursor[_DocumentType]":
+        """Sorts this cursor's results.
+
+        Pass a field name and a direction, either
+        :data:`~pymongo.ASCENDING` or :data:`~pymongo.DESCENDING`::
+
+            for doc in collection.find().sort('field', pymongo.ASCENDING):
+                print(doc)
+
+        To sort by multiple fields, pass a list of (key, direction) pairs::
+
+            for doc in collection.find().sort([
+                    ('field1', pymongo.ASCENDING),
+                    ('field2', pymongo.DESCENDING)]):
+                print(doc)
+
+        Text search results can be sorted by relevance::
+
+            cursor = db.test.find(
+                {'$text': {'$search': 'some words'}},
+                {'score': {'$meta': 'textScore'}})
+
+            # Sort by 'score' field.
+            cursor.sort([('score', {'$meta': 'textScore'})])
+
+            for doc in cursor:
+                print(doc)
+
+        For more advanced text search functionality, see MongoDB's
+        `Atlas Search <https://docs.atlas.mongodb.com/atlas-search/>`_.
+
+        Raises :class:`~pymongo.errors.InvalidOperation` if this cursor has
+        already been used. Only the last :meth:`sort` applied to this
+        cursor has any effect.
+
+        :Parameters:
+          - `key_or_list`: a single key or a list of (key, direction)
+            pairs specifying the keys to sort on
+          - `direction` (optional): only used if `key_or_list` is a single
+            key, if not given :data:`~pymongo.ASCENDING` is assumed
+        """
+        self.__check_okay_to_chain()
+        keys = helpers._index_list(key_or_list, direction)
+        self.__ordering = helpers._index_document(keys)
+        return self
+
+    def distinct(self, key: str) -> List:
+        """Get a list of distinct values for `key` among all documents
+        in the result set of this query.
+
+        Raises :class:`TypeError` if `key` is not an instance of
+        :class:`basestring` (:class:`str` in python 3).
+
+        The :meth:`distinct` method obeys the
+        :attr:`~pymongo.collection.Collection.read_preference` of the
+        :class:`~pymongo.collection.Collection` instance on which
+        :meth:`~pymongo.collection.Collection.find` was called.
+
+        :Parameters:
+          - `key`: name of key for which we want to get the distinct values
+
+        .. seealso:: :meth:`pymongo.collection.Collection.distinct`
+        """
+        options: Dict[str, Any] = {}
+        if self.__spec:
+            options["query"] = self.__spec
+        if self.__max_time_ms is not None:
+            options["maxTimeMS"] = self.__max_time_ms
+        if self.__comment:
+            options["comment"] = self.__comment
+        if self.__collation is not None:
+            options["collation"] = self.__collation
+
+        return self.__collection.distinct(key, session=self.__session, **options)
+
+    def explain(self) -> _DocumentType:
+        """Returns an explain plan record for this cursor.
+
+        .. note:: This method uses the default verbosity mode of the
+          `explain command
+          <https://mongodb.com/docs/manual/reference/command/explain/>`_,
+          ``allPlansExecution``. To use a different verbosity use
+          :meth:`~pymongo.database.Database.command` to run the explain
+          command directly.
+
+        .. seealso:: The MongoDB documentation on `explain <https://dochub.mongodb.org/core/explain>`_.
+        """
+        c = self.clone()
+        c.__explain = True
+
+        # always use a hard limit for explains
+        if c.__limit:
+            c.__limit = -abs(c.__limit)
+        return next(c)
+
+    def __set_hint(self, index):
+        if index is None:
+            self.__hint = None
+            return
+
+        if isinstance(index, str):
+            self.__hint = index
+        else:
+            self.__hint = helpers._index_document(index)
+
+    def hint(self, index: Optional[_Hint]) -> "Cursor[_DocumentType]":
+        """Adds a 'hint', telling Mongo the proper index to use for the query.
+
+        Judicious use of hints can greatly improve query
+        performance. When doing a query on multiple fields (at least
+        one of which is indexed) pass the indexed field as a hint to
+        the query. Raises :class:`~pymongo.errors.OperationFailure` if the
+        provided hint requires an index that does not exist on this collection,
+        and raises :class:`~pymongo.errors.InvalidOperation` if this cursor has
+        already been used.
+
+        `index` should be an index as passed to
+        :meth:`~pymongo.collection.Collection.create_index`
+        (e.g. ``[('field', ASCENDING)]``) or the name of the index.
+        If `index` is ``None`` any existing hint for this query is
+        cleared. The last hint applied to this cursor takes precedence
+        over all others.
+
+        :Parameters:
+          - `index`: index to hint on (as an index specifier)
+        """
+        self.__check_okay_to_chain()
+        self.__set_hint(index)
+        return self
+
+    def comment(self, comment: Any) -> "Cursor[_DocumentType]":
+        """Adds a 'comment' to the cursor.
+
+        http://mongodb.com/docs/manual/reference/operator/comment/
+
+        :Parameters:
+          - `comment`: A string to attach to the query to help interpret and
+            trace the operation in the server logs and in profile data.
+
+        .. versionadded:: 2.7
+        """
+        self.__check_okay_to_chain()
+        self.__comment = comment
+        return self
+
+    def where(self, code: Union[str, Code]) -> "Cursor[_DocumentType]":
+        """Adds a `$where`_ clause to this query.
+
+        The `code` argument must be an instance of :class:`basestring`
+        (:class:`str` in python 3) or :class:`~bson.code.Code`
+        containing a JavaScript expression. This expression will be
+        evaluated for each document scanned. Only those documents
+        for which the expression evaluates to *true* will be returned
+        as results. The keyword *this* refers to the object currently
+        being scanned. For example::
+
+            # Find all documents where field "a" is less than "b" plus "c".
+            for doc in db.test.find().where('this.a < (this.b + this.c)'):
+                print(doc)
+
+        Raises :class:`TypeError` if `code` is not an instance of
+        :class:`basestring` (:class:`str` in python 3). Raises
+        :class:`~pymongo.errors.InvalidOperation` if this
+        :class:`Cursor` has already been used. Only the last call to
+        :meth:`where` applied to a :class:`Cursor` has any effect.
+
+        .. note:: MongoDB 4.4 drops support for :class:`~bson.code.Code`
+          with scope variables. Consider using `$expr`_ instead.
+
+        :Parameters:
+          - `code`: JavaScript expression to use as a filter
+
+        .. _$expr: https://mongodb.com/docs/manual/reference/operator/query/expr/
+        .. _$where: https://mongodb.com/docs/manual/reference/operator/query/where/
+        """
+        self.__check_okay_to_chain()
+        if not isinstance(code, Code):
+            code = Code(code)
+
+        # Avoid overwriting a filter argument that was given by the user
+        # when updating the spec.
+        spec: Dict[str, Any]
+        if self.__has_filter:
+            spec = dict(self.__spec)
+        else:
+            spec = cast(Dict, self.__spec)
+        spec["$where"] = code
+        self.__spec = spec
+        return self
+
+    def collation(self, collation: Optional[_CollationIn]) -> "Cursor[_DocumentType]":
+        """Adds a :class:`~pymongo.collation.Collation` to this query.
+
+        Raises :exc:`TypeError` if `collation` is not an instance of
+        :class:`~pymongo.collation.Collation` or a ``dict``. Raises
+        :exc:`~pymongo.errors.InvalidOperation` if this :class:`Cursor` has
+        already been used. Only the last collation applied to this cursor has
+        any effect.
+
+        :Parameters:
+          - `collation`: An instance of :class:`~pymongo.collation.Collation`.
+        """
+        self.__check_okay_to_chain()
+        self.__collation = validate_collation_or_none(collation)
+        return self
+
+    def __send_message(self, operation):
+        """Send a query or getmore operation and handles the response.
+
+        If operation is ``None`` this is an exhaust cursor, which reads
+        the next result batch off the exhaust socket instead of
+        sending getMore messages to the server.
+
+        Can raise ConnectionFailure.
+        """
+        client = self.__collection.database.client
+        # OP_MSG is required to support exhaust cursors with encryption.
+        if client._encrypter and self.__exhaust:
+            raise InvalidOperation("exhaust cursors do not support auto encryption")
+
+        try:
+            response = client._run_operation(
+                operation, self._unpack_response, address=self.__address
+            )
+        except OperationFailure as exc:
+            if exc.code in _CURSOR_CLOSED_ERRORS or self.__exhaust:
+                # Don't send killCursors because the cursor is already closed.
+                self.__killed = True
+            self.close()
+            # If this is a tailable cursor the error is likely
+            # due to capped collection roll over. Setting
+            # self.__killed to True ensures Cursor.alive will be
+            # False. No need to re-raise.
+            if (
+                exc.code in _CURSOR_CLOSED_ERRORS
+                and self.__query_flags & _QUERY_OPTIONS["tailable_cursor"]
+            ):
+                return
+            raise
+        except ConnectionFailure:
+            # Don't send killCursors because the cursor is already closed.
+            self.__killed = True
+            self.close()
+            raise
+        except Exception:
+            self.close()
+            raise
+
+        self.__address = response.address
+        if isinstance(response, PinnedResponse):
+            if not self.__sock_mgr:
+                self.__sock_mgr = _SocketManager(response.socket_info, response.more_to_come)
+
+        cmd_name = operation.name
+        docs = response.docs
+        if response.from_command:
+            if cmd_name != "explain":
+                cursor = docs[0]["cursor"]
+                self.__id = cursor["id"]
+                if cmd_name == "find":
+                    documents = cursor["firstBatch"]
+                    # Update the namespace used for future getMore commands.
+                    ns = cursor.get("ns")
+                    if ns:
+                        self.__dbname, self.__collname = ns.split(".", 1)
+                else:
+                    documents = cursor["nextBatch"]
+                self.__data = deque(documents)
+                self.__retrieved += len(documents)
+            else:
+                self.__id = 0
+                self.__data = deque(docs)
+                self.__retrieved += len(docs)
+        else:
+            self.__id = response.data.cursor_id
+            self.__data = deque(docs)
+            self.__retrieved += response.data.number_returned
+
+        if self.__id == 0:
+            # Don't wait for garbage collection to call __del__, return the
+            # socket and the session to the pool now.
+            self.close()
+
+        if self.__limit and self.__id and self.__limit <= self.__retrieved:
+            self.close()
+
+    def _unpack_response(
+        self, response, cursor_id, codec_options, user_fields=None, legacy_response=False
+    ):
+        return response.unpack_response(cursor_id, codec_options, user_fields, legacy_response)
+
+    def _read_preference(self):
+        if self.__read_preference is None:
+            # Save the read preference for getMore commands.
+            self.__read_preference = self.__collection._read_preference_for(self.session)
+        return self.__read_preference
+
+    def _refresh(self):
+        """Refreshes the cursor with more data from Mongo.
+
+        Returns the length of self.__data after refresh. Will exit early if
+        self.__data is already non-empty. Raises OperationFailure when the
+        cursor cannot be refreshed due to an error on the query.
+        """
+        if len(self.__data) or self.__killed:
+            return len(self.__data)
+
+        if not self.__session:
+            self.__session = self.__collection.database.client._ensure_session()
+
+        if self.__id is None:  # Query
+            if (self.__min or self.__max) and not self.__hint:
+                raise InvalidOperation(
+                    "Passing a 'hint' is required when using the min/max query"
+                    " option to ensure the query utilizes the correct index"
+                )
+            q = self._query_class(
+                self.__query_flags,
+                self.__collection.database.name,
+                self.__collection.name,
+                self.__skip,
+                self.__query_spec(),
+                self.__projection,
+                self.__codec_options,
+                self._read_preference(),
+                self.__limit,
+                self.__batch_size,
+                self.__read_concern,
+                self.__collation,
+                self.__session,
+                self.__collection.database.client,
+                self.__allow_disk_use,
+                self.__exhaust,
+            )
+            self.__send_message(q)
+        elif self.__id:  # Get More
+            if self.__limit:
+                limit = self.__limit - self.__retrieved
+                if self.__batch_size:
+                    limit = min(limit, self.__batch_size)
+            else:
+                limit = self.__batch_size
+            # Exhaust cursors don't send getMore messages.
+            g = self._getmore_class(
+                self.__dbname,
+                self.__collname,
+                limit,
+                self.__id,
+                self.__codec_options,
+                self._read_preference(),
+                self.__session,
+                self.__collection.database.client,
+                self.__max_await_time_ms,
+                self.__sock_mgr,
+                self.__exhaust,
+                self.__comment,
+            )
+            self.__send_message(g)
+
+        return len(self.__data)
+
+    @property
+    def alive(self) -> bool:
+        """Does this cursor have the potential to return more data?
+
+        This is mostly useful with `tailable cursors
+        <https://www.mongodb.com/docs/manual/core/tailable-cursors/>`_
+        since they will stop iterating even though they *may* return more
+        results in the future.
+
+        With regular cursors, simply use a for loop instead of :attr:`alive`::
+
+            for doc in collection.find():
+                print(doc)
+
+        .. note:: Even if :attr:`alive` is True, :meth:`next` can raise
+          :exc:`StopIteration`. :attr:`alive` can also be True while iterating
+          a cursor from a failed server. In this case :attr:`alive` will
+          return False after :meth:`next` fails to retrieve the next batch
+          of results from the server.
+        """
+        return bool(len(self.__data) or (not self.__killed))
+
+    @property
+    def cursor_id(self) -> Optional[int]:
+        """Returns the id of the cursor
+
+        .. versionadded:: 2.2
+        """
+        return self.__id
+
+    @property
+    def address(self) -> Optional[Tuple[str, Any]]:
+        """The (host, port) of the server used, or None.
+
+        .. versionchanged:: 3.0
+           Renamed from "conn_id".
+        """
+        return self.__address
+
+    @property
+    def session(self) -> Optional["ClientSession"]:
+        """The cursor's :class:`~pymongo.client_session.ClientSession`, or None.
+
+        .. versionadded:: 3.6
+        """
+        if self.__explicit_session:
+            return self.__session
+        return None
+
+    def __iter__(self) -> "Cursor[_DocumentType]":
+        return self
+
+    def next(self) -> _DocumentType:
+        """Advance the cursor."""
+        if self.__empty:
+            raise StopIteration
+        if len(self.__data) or self._refresh():
+            return self.__data.popleft()
+        else:
+            raise StopIteration
+
+    __next__ = next
+
+    def __enter__(self) -> "Cursor[_DocumentType]":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def __copy__(self) -> "Cursor[_DocumentType]":
+        """Support function for `copy.copy()`.
+
+        .. versionadded:: 2.4
+        """
+        return self._clone(deepcopy=False)
+
+    def __deepcopy__(self, memo: Any) -> Any:
+        """Support function for `copy.deepcopy()`.
+
+        .. versionadded:: 2.4
+        """
+        return self._clone(deepcopy=True)
+
+    def _deepcopy(self, x, memo=None):
+        """Deepcopy helper for the data dictionary or list.
+
+        Regular expressions cannot be deep copied but as they are immutable we
+        don't have to copy them when cloning.
+        """
+        y: Any
+        if not hasattr(x, "items"):
+            y, is_list, iterator = [], True, enumerate(x)
+        else:
+            y, is_list, iterator = {}, False, x.items()
+
+        if memo is None:
+            memo = {}
+        val_id = id(x)
+        if val_id in memo:
+            return memo.get(val_id)
+        memo[val_id] = y
+
+        for key, value in iterator:
+            if isinstance(value, (dict, list)) and not isinstance(value, SON):
+                value = self._deepcopy(value, memo)
+            elif not isinstance(value, RE_TYPE):
+                value = copy.deepcopy(value, memo)
+
+            if is_list:
+                y.append(value)
+            else:
+                if not isinstance(key, RE_TYPE):
+                    key = copy.deepcopy(key, memo)
+                y[key] = value
+        return y
+
+
+class RawBatchCursor(Cursor, Generic[_DocumentType]):
+    """A cursor / iterator over raw batches of BSON data from a query result."""
+
+    _query_class = _RawBatchQuery
+    _getmore_class = _RawBatchGetMore
+
+    def __init__(self, collection: "Collection[_DocumentType]", *args: Any, **kwargs: Any) -> None:
+        """Create a new cursor / iterator over raw batches of BSON data.
+
+        Should not be called directly by application developers -
+        see :meth:`~pymongo.collection.Collection.find_raw_batches`
+        instead.
+
+        .. seealso:: The MongoDB documentation on `cursors <https://dochub.mongodb.org/core/cursors>`_.
+        """
+        super(RawBatchCursor, self).__init__(collection, *args, **kwargs)
+
+    def _unpack_response(
+        self, response, cursor_id, codec_options, user_fields=None, legacy_response=False
+    ):
+        raw_response = response.raw_response(cursor_id, user_fields=user_fields)
+        if not legacy_response:
+            # OP_MSG returns firstBatch/nextBatch documents as a BSON array
+            # Re-assemble the array of documents into a document stream
+            _convert_raw_document_lists_to_streams(raw_response[0])
+        return raw_response
+
+    def explain(self) -> _DocumentType:
+        """Returns an explain plan record for this cursor.
+
+        .. seealso:: The MongoDB documentation on `explain <https://dochub.mongodb.org/core/explain>`_.
+        """
+        clone = self._clone(deepcopy=True, base=Cursor(self.collection))
+        return clone.explain()
+
+    def __getitem__(self, index: Any) -> NoReturn:
+        raise InvalidOperation("Cannot call __getitem__ on RawBatchCursor")