"tailable_cursor": 2,

"slave_okay": 4,

"oplog_replay": 8,

"no_timeout": 16,

"await_data": 32,

"exhaust": 64,

NON_TAILABLE = 0

"""The standard cursor type."""

TAILABLE = _QUERY_OPTIONS["tailable_cursor"]

"""The tailable cursor type.

TAILABLE_AWAIT = TAILABLE | _QUERY_OPTIONS["await_data"]

"""A tailable cursor with the await option set.

EXHAUST = _QUERY_OPTIONS["exhaust"]

"""An exhaust cursor.

"""Used with exhaust cursors to ensure the socket is returned.

def __init__(self, sock, pool):

self.sock = sock

self.pool = pool

self.__closed = False

def __del__(self):

self.close()

def close(self):

"""Return this instance's socket to the connection pool.

if not self.__closed:

self.__closed = True

self.pool.return_socket(self.sock)

"""A cursor / iterator over Mongo query results.

_query_class = _Query

_getmore_class = _GetMore

def __init__(self, collection, filter=None, projection=None, skip=0,

limit=0, no_cursor_timeout=False,

cursor_type=CursorType.NON_TAILABLE,

sort=None, allow_partial_results=False, oplog_replay=False,

modifiers=None, batch_size=0, manipulate=True,

collation=None, hint=None, max_scan=None, max_time_ms=None,

max=None, min=None, return_key=False, show_record_id=False,

snapshot=False, comment=None, session=None):

"""Create a new cursor.

# Initialize all attributes used in __del__ before possibly raising

# an error to avoid attribute errors during garbage collection.

self.__id = None

self.__exhaust = False

self.__exhaust_mgr = None

self.__killed = False

if session:

self.__session = session

self.__explicit_session = True

else:

self.__session = None

self.__explicit_session = False

spec = filter

if spec is None:

spec = {}

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 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 modifiers is not None:

warnings.warn("the 'modifiers' parameter is deprecated",

DeprecationWarning, stacklevel=2)

validate_is_mapping("modifiers", modifiers)

if not isinstance(batch_size, integer_types):

raise TypeError("batch_size must be an integer")

if batch_size < 0:

raise ValueError("batch_size must be >= 0")

if projection is not None:

if not projection:

projection = {"_id": 1}

projection = helpers._fields_list_to_dict(projection, "projection")

self.__collection = collection

self.__spec = spec

self.__projection = projection

self.__skip = skip

self.__limit = limit

self.__batch_size = batch_size

self.__modifiers = modifiers and modifiers.copy() or {}

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 = None

self.__max = max

self.__min = min

self.__manipulate = manipulate

self.__collation = validate_collation_or_none(collation)

self.__return_key = return_key

self.__show_record_id = show_record_id

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()

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"]

@property

def collection(self):

"""The :class:`~pymongo.collection.Collection` that this

return self.__collection

@property

def retrieved(self):

"""The number of documents retrieved so far.

return self.__retrieved

def __del__(self):

self.__die()

def rewind(self):

"""Rewind this cursor to its unevaluated state.

self.__data = deque()

self.__id = None

self.__address = None

self.__retrieved = 0

self.__killed = False

return self

def clone(self):

"""Get a clone of this cursor.

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", "manipulate",

"query_flags", "modifiers", "collation")

data = dict((k, v) for k, v in iteritems(self.__dict__)

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:

if self.__exhaust and self.__exhaust_mgr:

# If this is an exhaust cursor and we haven't completely

# exhausted the result set we *must* close the socket

# to stop the server from sending more data.

self.__exhaust_mgr.sock.close_socket(

ConnectionClosedReason.ERROR)

else:

address = _CursorAddress(

self.__address, self.__collection.full_name)

if synchronous:

self.__collection.database.client._close_cursor_now(

self.__id, address, session=self.__session)

else:

# The cursor will be closed later in a different session.

self.__collection.database.client._close_cursor(

self.__id, address)

if self.__exhaust and self.__exhaust_mgr:

self.__exhaust_mgr.close()

if self.__session and not self.__explicit_session:

self.__session._end_session(lock=synchronous)

self.__session = None

def close(self):

"""Explicitly close / kill this cursor.

self.__die(True)

def __query_spec(self):

"""Get the spec to use for a query.

operators = self.__modifiers.copy()

if self.__ordering:

operators["$orderby"] = self.__ordering

if self.__explain:

operators["$explain"] = True

if self.__hint:

operators["$hint"] = self.__hint

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:

operators["$returnKey"] = self.__return_key

if self.__show_record_id:

# This is upgraded to showRecordId for MongoDB 3.2+ "find" command.

operators["$showDiskLoc"] = self.__show_record_id

if self.__snapshot:

operators["$snapshot"] = self.__snapshot

if operators:

# Make a shallow copy so we can cleanly rewind or clone.

spec = self.__spec.copy()

# White-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):

"""Set arbitrary query flags using a bitmask.

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):

"""Unset arbitrary query flags using a bitmask.

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 limit(self, limit):

"""Limits the number of results to be returned by this cursor.

if not isinstance(limit, integer_types):

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):

"""Limits the number of documents returned in one batch. Each batch

if not isinstance(batch_size, integer_types):

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):

"""Skips the first `skip` results of this cursor.

if not isinstance(skip, integer_types):

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):

"""Specifies a time limit for a query operation. If the specified

if (not isinstance(max_time_ms, integer_types)

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):

"""Specifies a time limit for a getMore operation on a

if (not isinstance(max_await_time_ms, integer_types)

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

def __getitem__(self, index):

"""Get a single document or a slice of documents from 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, integer_types):

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):

"""**DEPRECATED** - Limit the number of documents to scan when

self.__check_okay_to_chain()

self.__max_scan = max_scan

return self

def max(self, spec):

"""Adds ``max`` operator that specifies upper bound for specific index.

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):

"""Adds ``min`` operator that specifies lower bound for specific index.

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, direction=None):

"""Sorts this cursor's results.

self.__check_okay_to_chain()

keys = helpers._index_list(key_or_list, direction)

self.__ordering = helpers._index_document(keys)

return self

def count(self, with_limit_and_skip=False):

"""**DEPRECATED** - Get the size of the results set for this query.

warnings.warn("count is deprecated. Use Collection.count_documents "

"instead.", DeprecationWarning, stacklevel=2)

validate_boolean("with_limit_and_skip", with_limit_and_skip)

cmd = SON([("count", self.__collection.name),

("query", self.__spec)])

if self.__max_time_ms is not None:

cmd["maxTimeMS"] = self.__max_time_ms

if self.__comment:

cmd["comment"] = self.__comment

if self.__hint is not None:

cmd["hint"] = self.__hint

if with_limit_and_skip:

if self.__limit:

cmd["limit"] = self.__limit

if self.__skip:

cmd["skip"] = self.__skip

return self.__collection._count(

cmd, self.__collation, session=self.__session)

def distinct(self, key):

"""Get a list of distinct values for `key` among all documents

options = {}

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):

"""Returns an explain plan record for this cursor.

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, string_type):

self.__hint = index

else:

self.__hint = helpers._index_document(index)

def hint(self, index):

"""Adds a 'hint', telling Mongo the proper index to use for the query.

self.__check_okay_to_chain()

self.__set_hint(index)

return self

def comment(self, comment):

"""Adds a 'comment' to the cursor.

self.__check_okay_to_chain()

self.__comment = comment

return self

def where(self, code):

"""Adds a $where clause to this query.

self.__check_okay_to_chain()

if not isinstance(code, Code):

code = Code(code)

self.__spec["$where"] = code

return self

def collation(self, collation):

"""Adds a :class:`~pymongo.collation.Collation` to this query.

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.

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_with_response(

operation, self._unpack_response, exhaust=self.__exhaust,

address=self.__address)

except OperationFailure:

self.__killed = True

# Make sure exhaust socket is returned immediately, if necessary.

self.__die()

# 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 self.__query_flags & _QUERY_OPTIONS["tailable_cursor"]:

return

raise

except NotMasterError:

# Don't send kill cursors to another server after a "not master"

# error. It's completely pointless.

self.__killed = True

# Make sure exhaust socket is returned immediately, if necessary.

self.__die()

raise

except ConnectionFailure:

# Don't try to send kill cursors on another socket

# or to another server. It can cause a _pinValue

# assertion on some server releases if we get here

# due to a socket timeout.

self.__killed = True

self.__die()

raise

except Exception:

# Close the cursor

self.__die()

raise

self.__address = response.address

if self.__exhaust and not self.__exhaust_mgr:

# 'response' is an ExhaustResponse.

self.__exhaust_mgr = _SocketManager(response.socket_info,

response.pool)

cmd_name = operation.name

docs = response.docs

if response.from_command:

if cmd_name != "explain":