o 'h?@sdZddlmZddlZddlZddlmZddlmZm Z m Z m Z m Z m Z mZmZmZmZmZmZddlmZmZddlmZddlmZdd lmZmZdd lmZdd l m!Z!m"Z"dd l#m$Z$m%Z%m&Z&m'Z'm(Z(dd l)m*Z*m+Z+m,Z,ddl-m.Z.ddl/m0Z0m1Z1m2Z2m3Z3m4Z4m5Z5m6Z6ddl7m8Z8ddl9m:Z:ddl;mZ>m?Z?ddl@mAZAerddlBmCZCddlDmEZEddlFmGZGddlHmIZIddlJmKZKddlLmMZMdZNGdddZOGddde e?ZPGdd d ePe e?ZQdS)!z1Cursor class to iterate over Mongo query results.) annotationsN)deque) TYPE_CHECKINGAnyGenericIterableListMappingNoReturnOptionalSequenceUnioncastoverload)RE_TYPE&_convert_raw_document_lists_to_streams)Code)SON)_csothelpers_shared)validate_collation_or_none)validate_is_document_typevalidate_is_mapping)_CURSOR_CLOSED_ERRORS_QUERY_OPTIONS CursorType_Hint_Sort)ConnectionFailureInvalidOperationOperationFailure) _create_lock)_CursorAddress_GetMore_OpMsg_OpReply_Query_RawBatchGetMore_RawBatchQuery)PinnedResponsenext)_Address _CollationIn _DocumentOut _DocumentType)validate_boolean) SupportsItems) CodecOptions) _ServerMode) ClientSession) Collection) ConnectionTc@s.eZdZdZdddZdd d Zdd d ZdS)_ConnectionManagerz?Used with exhaust cursors to ensure the connection is returned.connr6 more_to_comeboolcCs||_||_t|_dSN)r8r9r!_lock)selfr8r9r>V/var/www/html/olx_land/venv/lib/python3.10/site-packages/pymongo/synchronous/cursor.py__init__Ms z_ConnectionManager.__init__returnNonecCs ||_dSr;)r9)r=r9r>r>r?update_exhaustRs z!_ConnectionManager.update_exhaustcCs|jr |jd|_dSdS)z9Return this instance's connection to the connection pool.N)r8unpinr=r>r>r?closeUs  z_ConnectionManager.closeN)r8r6r9r:)r9r:rArBrArB)__name__ __module__ __qualname____doc__r@rCrFr>r>r>r?r7Js   r7c@seZdZeZeZdddddejdddddddddddddddddfdd*d+Z dd,d-Z e dd.d/Z e dd0d1Z dd2d3Zdd5d6Zddd;d<Zdd=d>Zdd@dAZddBdCZddEdFZddGdHZddIdJZddKdLZddMdNZddOdPZddQdRZddTdUZeddXdYZedd[dYZdd^dYZdd_d`ZddcddZddedfZ dddkdlZ!ddmdnZ"ddodpZ#ddqdrZ$ddtduZ%ddxdyZ&ddzd{Z'  ddddZ(dddZ)e dddZ*e dddZ+e dddZ,e dddZ-dddZ.dddZ/eddddZ0e ddddZ0 ddddZ0dddZ1dddZ2dddZ3dddZ4dddZ5dddZ6dddZ7dddZ8dddZ9ddddZ:dddZ;ddd„Ze?j@dddd̈́ZAdS)CursorNrF collectionCollection[_DocumentType]filterOptional[Mapping[str, Any]] projection1Optional[Union[Mapping[str, Any], Iterable[str]]]skipintlimitno_cursor_timeoutr: cursor_typesortOptional[_Sort]allow_partial_results oplog_replay batch_size collationOptional[_CollationIn]hintOptional[_Hint]max_scan Optional[int] max_time_msmaxmin return_keyOptional[bool]show_record_idsnapshotcomment Optional[Any]sessionOptional[ClientSession]allow_disk_useletrArBcCs||_d|_d|_d|_d|_||r||_d|_nd|_d|_|p#i}td|t|t s7t dt |t|t sEt dt |t d||rW|jsWt jdtd d |tjtjtjtjfvrgtd t d | t d | t| t st dt | | dkrtd|durt d|}|durt|d}|durtd|||_||_|du|_||_||_||_| |_|rt |pd|_!||_"d|_#||_$||_%|jj&j'j(j)|_*d|_+||_,||_-t.| |_/||_0||_1||_2||_3||4| d|_5t6|_7d|_8d|_9|j:|_;d|_<|j=|_>||_?||_@|r#|j?tAdO_?| r/|j?tAdO_?| r;|j?tAd O_?|j&jB|_C|jB|_DtErPd|_F|GdS|tjk|_d|_FdS)a 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 `_. NFTrOz%skip must be an instance of int, not z&limit must be an instance of int, not rVzuse 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) stacklevelz!not a valid value for cursor_typerZr[#batch_size must be an integer, not rbatch_size must be >= 0rnrQro no_timeoutpartial)H _collection_id_exhaust _sock_mgr_killed_session_explicit_sessionr isinstancerT TypeErrortyper0warningswarn UserWarningr NON_TAILABLETAILABLETAILABLE_AWAITEXHAUST ValueErrorr_fields_list_to_dictr_let_spec _has_filter _projection_skip_limit _batch_size_index_document _ordering _max_scan_explain_comment _max_time_msdatabaseclientoptionstimeout_timeout_max_await_time_ms_max_minr _collation _return_key_show_record_id_allow_disk_use _snapshot _set_hint_emptyr_data_address _retrieved codec_options_codec_options_read_preference read_concern _read_concern _query_flags _cursor_typername_dbname _collname_IS_SYNC_exhaust_checked_supports_exhaust)r=rMrOrQrSrUrVrWrXrZr[r\r]r_rarcrdrerfrhrirjrlrnrospecr>r>r?r@`s$                   zCursor.__init__cCs<|jtjkr|jjjjrtd|jrtdd|_ dSdS)N+Exhaust cursors are not supported by mongos%Can't use limit and exhaust together.T) rrrrvrr is_mongosrrrxrEr>r>r?rs   zCursor._supports_exhaustcC|jS)zdThe :class:`~pymongo.collection.Collection` that this :class:`Cursor` is iterating. )rvrEr>r>r?rMszCursor.collectioncCr)z)The number of documents retrieved so far.)rrEr>r>r? retrieved szCursor.retrievedcC |dSr;) _die_no_lockrEr>r>r?__del__ zCursor.__del__Cursor[_DocumentType]cCs |dS)aGet 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. T_clonerEr>r>r?clones z Cursor.cloneTdeepcopybaseOptional[Cursor]cs\|s|jr ||j}n|d}dfdd|jD}|r&||}|j||S)zInternal clone helper.N)rrQrSrUrcmax_await_time_msrjrdreorderingexplainr_r\ra query_flagsr]emptyrhrfrnriexhaust has_filterrWcs0i|]\}}|dr|ddvr||qS)_N) startswith).0kvvalues_to_cloner>r? =sz!Cursor._clone..)r| _clone_baser{__dict__items _deepcopyupdate)r=rrdatar>rr?rs    z Cursor._clonecCs|j|j|dS)zACreates an empty Cursor object for information to be copied into.)rl) __class__rv)r=rlr>r>r?rEszCursor._clone_baseMapping[str, Any]cCs8i}|jr |j|d<|jrd|d<|jr|j|d<|jr!|j|d<|jr)|j|d<|jr1|j|d<|jdur;|j|d <|jrC|j|d <|jrK|j|d <|j durU|j |d <|j dur_|j |d <|j duri|j |d<|rt |j }d|vrxd|i}|||Sd|j vrt|j dkstt|j dkrd|j iS|j S)z Get the spec to use for a query.z$orderbyTz$explainz$hintroz$commentz$maxScanNz $maxTimeMSz$maxz$minz $returnKeyz $showDiskLocz $snapshotz$queryqueryr)rr_hintrrrrrrrrrdictrrlenr+iter)r= operatorsrr>r>r? _query_specIsD                 * zCursor._query_speccCs|js|jdur tddS)z;Check if it is okay to chain more options onto this cursor.Nz(cannot set options after executing query)rrwrrEr>r>r?_check_okay_to_chain{szCursor._check_okay_to_chainmaskcCsjt|tstdt|||td@r,|jrtd|jj j j r)tdd|_ |j |O_ |S)zsSet arbitrary query flags using a bitmask. To set the tailable flag: cursor.add_option(2) mask must be an int, not rrrT)r}rTr~rrrrrrvrrrrxrr=rr>r>r? add_options   zCursor.add_optioncCsJt|tstdt|||td@rd|_|j|M_|S)zzUnset arbitrary query flags using a bitmask. To unset the tailable flag: cursor.remove_option(2) rrF)r}rTr~rrrrxrrr>r>r? remove_options  zCursor.remove_optioncCs.t|tstdt||||_|S)aSpecifies 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** :param 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 z#allow_disk_use must be a bool, not )r}r:r~rrr)r=rnr>r>r?rns zCursor.allow_disk_usecCsBt|tstdt||jrtd|d|_||_|S)aLimits 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. :param limit: the number of results to return .. seealso:: The MongoDB documentation on `limit `_. zlimit must be an integer, not rF) r}rTr~rrxrrrr)r=rUr>r>r?rUs z Cursor.limitcC>t|tstdt||dkrtd|||_|S)afLimits 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. :param batch_size: The size of each batch of results requested. rrrrs)r}rTr~rrrr)r=r\r>r>r?r\s zCursor.batch_sizecCr)aSkips 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. :param skip: the number of results to skip zskip must be an integer, not rzskip must be >= 0)r}rTr~rrrr)r=rSr>r>r?rSs z Cursor.skipcCs6t|ts|durtdt||||_|S)aSpecifies 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. :param max_time_ms: the time limit after which the operation is aborted Nz,max_time_ms must be an integer or None, not )r}rTr~rrr)r=rcr>r>r?rcs  zCursor.max_time_msrcCsBt|ts|durtdt|||jtj@r||_|S)aSSpecifies 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** :param max_await_time_ms: the time limit after which the operation is aborted .. versionadded:: 3.2 Nz2max_await_time_ms must be an integer or None, not ) r}rTr~rrrrrr)r=rr>r>r?rs  zCursor.max_await_time_msindexr/cCdSr;r>r=rr>r>r? __getitem__-zCursor.__getitem__slicecCrr;r>rr>r>r?r1rUnion[int, slice]+Union[_DocumentType, Cursor[_DocumentType]]cCstr|d|_t|trP|jdurtdd}|jdur*|jdkr'td|j}|jdurF|j|}|dkr>td||dkrEd|_nd}||_ ||_ |St|t r|dkr]td| }| ||j |d|jtjM_|D]}|Std td |td ) aIGet 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. :param index: An integer or slice index to be applied to this cursor FNz+Cursor instances do not support slice stepsrz0Cursor instances do not support negative indicesz8stop index must be greater than start index for slice %rTz no such item for Cursor instancez.index %r cannot be applied to Cursor instancesz Cursor does not support indexing)rrrr}rstep IndexErrorstartstoprrrTrrSrUrrrr~)r=rrSrUrdocr>r>r?r5sH(         cC|||_|S)a1**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. :param 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. )rr)r=rar>r>r?raszCursor.max_scanrrcC6t|ttfstdt||t||_|S)a!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. :param 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 /spec must be an instance of list or tuple, not )r}listtupler~rrrrr=rr>r>r?rd  z Cursor.maxcCr)a!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. :param 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 r)r}rrr~rrrrrr>r>r?rerz Cursor.min key_or_listr directionOptional[Union[int, str]]cCs$|t||}t||_|S)aSorts 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. If just a name is given, :data:`~pymongo.ASCENDING` will be inferred:: for doc in collection.find().sort([ 'field1', ('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 `_. Raises :class:`~pymongo.errors.InvalidOperation` if this cursor has already been used. Only the last :meth:`sort` applied to this cursor has any effect. :param key_or_list: a single key or a list of (key, direction) pairs specifying the keys to sort on :param direction: only used if `key_or_list` is a single key, if not given :data:`~pymongo.ASCENDING` is assumed )rr _index_listrr)r=rrkeysr>r>r?rXs+  z Cursor.sortcCs*|}d|_|jrt|j |_t|S)aReturns an explain plan record for this cursor. .. note:: This method uses the default verbosity mode of the `explain command `_, ``allPlansExecution``. To use a different verbosity use :meth:`~pymongo.database.Database.command` to run the explain command directly. .. seealso:: The MongoDB documentation on `explain `_. T)rrrabsr+)r=cr>r>r?rs  zCursor.explaincCs6|dur d|_dSt|tr||_dSt||_dSr;)rr}strrrrr>r>r?r s   zCursor._set_hintcCs||||S)aAdds 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. :param index: index to hint on (as an index specifier) )rrrr>r>r?r_s z Cursor.hintrcCr)a"Adds a 'comment' to the cursor. http://mongodb.com/docs/manual/reference/operator/comment/ :param 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 )rr)r=rjr>r>r?rj,s zCursor.commentcodeUnion[str, Code]cCsJ|t|ts t|}|jrt|j}ntt|j}||d<||_|S)aAdds a `$where`_ clause to this query. The `code` argument must be an instance of :class:`str` 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:`str`. 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. :param 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/ z$where)rr}rrrrr)r=r rr>r>r?where:s   z Cursor.wherecCs|t||_|S)aAdds 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. :param collation: An instance of :class:`~pymongo.collation.Collation`. )rrr)r=r]r>r>r?r]ds zCursor.collationresponseUnion[_OpReply, _OpMsg] cursor_idrr2 user_fieldslegacy_responseSequence[_DocumentOut]cCs|||||Sr;)unpack_response)r=r rrrrr>r>r?_unpack_responsesszCursor._unpack_responser3cCs |jdur |j|j|_|jSr;)rrv_read_preference_forrlrEr>r>r?_get_read_preference}s zCursor._get_read_preferencecCstt|jp |j S)aDoes this cursor have the potential to return more data? This is mostly useful with `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. )r:rrrzrEr>r>r?alivesz Cursor.alivecCr)zDReturns the id of the cursor .. versionadded:: 2.2 )rwrEr>r>r?rszCursor.cursor_idOptional[tuple[str, Any]]cCr)zzThe (host, port) of the server used, or None. .. versionchanged:: 3.0 Renamed from "conn_id". )rrEr>r>r?addressszCursor.addresscCs|jr|jSdS)zmThe cursor's :class:`~pymongo.client_session.ClientSession`, or None. .. versionadded:: 3.6 N)r|r{rEr>r>r?rlszCursor.sessioncC |jddS)zKSupport function for `copy.copy()`. .. versionadded:: 2.4 FrrrEr>r>r?__copy__ zCursor.__copy__memocCr)zOSupport function for `copy.deepcopy()`. .. versionadded:: 2.4 Trr)r=rr>r>r? __deepcopy__rzCursor.__deepcopy__xr&Optional[dict[int, Union[list, dict]]]rcCrr;r>r=rrr>r>r?rrzCursor._deepcopyr1rcCrr;r>r!r>r>r?rsUnion[Iterable, SupportsItems]Union[list, dict]c Cst|dsgdt|}}}n idtd|}}}|dur#i}t|}||vr/||S|||<|D]9\}}t|ttfrLt|tsL| ||}n t|t sWt ||}|r_| |q5t|t sjt ||}|||<q5|S)zDeepcopy 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. rTFr1N)hasattr enumeraterridr}rrrrrcopyrappend) r=rryis_listiteratorval_idkeyvaluer>r>r?rs(        already_killed$tuple[int, Optional[_CursorAddress]]cCsVd|_|jr#|s#|j}|jdusJt|j|jd|j}||fSd}d}||fS)NT.r)rzrwrr"rrr=r/rrr>r>r?_prepare_to_dies zCursor._prepare_to_diecCbz|j}Wn tyYdSw||\}}|jjj|||j|j|j |j s,d|_d|_dS)z,Closes this cursor without acquiring a lock.N) rzAttributeErrorr3rvrr_cleanup_cursor_no_lockryr{r|r2r>r>r?rs    zCursor._die_no_lockcCr4)zCloses this cursor.N) rzr5r3rvrr_cleanup_cursor_lockryr{r|r2r>r>r? _die_lock s     zCursor._die_lockcCs |dS)z$Explicitly close / kill this cursor.N)r8rEr>r>r?rFs z Cursor.closer-rcCsfi}|jr |j|d<|jdur|j|d<|jr|j|d<|jdur&|j|d<|jj|fd|ji|S)aOGet 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:`str`. 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. :param key: name of key for which we want to get the distinct values .. seealso:: :meth:`pymongo.collection.Collection.distinct` rN maxTimeMSrjr]rl)rrrrrvdistinctr{)r=r-rr>r>r?r:#s      zCursor.distinct operationUnion[_Query, _GetMore]c Cs,|jjj}|jr|jrtdz |j||j|jd}WnPt yR}z+|j t vs+|jr.d|_ |j r6|n||j t vrM|jtd@rMWYd}~dSd}~wty`d|_ |tyk|w|j|_t|tr|jst|j|j|_|j}|j}|jr|dkr|dd}|d |_|d kr|d }|d } | r| d d\|_!|_"n|d}t#||_$|j%t&|7_%n-d|_t#||_$|j%t&|7_%nt|j't(sJ|j'j)|_t#||_$|j%|j'j*7_%|jdkr||j+r|jr|j+|j%kr|dSdSdSdS)a#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. z.exhaust cursors do not support auto encryption)rTtailable_cursorNrrcursorr&find firstBatchnsr1r nextBatch),rvrr _encrypterrxr_run_operationrrr r rrzrrrFrrr BaseExceptionrr}r)ryr7r8r9rdocs from_commandrwgetsplitrrrrrrrr%rnumber_returnedr) r=r;rr exccmd_namerFr> documentsrAr>r>r? _send_message?st                   zCursor._send_messagecCs8t|js|jr t|jS|js|jjj|_|jdur[|j s#|j r*|j s*t d| |j|jjj|jj|j||j|j||j|j|j|j|j|jjj|j|j}||n<|jr|jrq|j|j}|jrpt||j}n|j}||j|j ||j|j||j|jjj|j!|j"|j|j# }||t|jS)aRefreshes 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. NzoPassing a 'hint' is required when using the min/max query option to ensure the query utilizes the correct index)$rrrzr{rvrr_ensure_sessionrwrrrr _query_classrrrrrrrrrrrrrxrNrre_getmore_classrrrryr)r=qrUgr>r>r?_refreshsf       zCursor._refreshcCs,|t|_d|_d|_d|_d|_|S)aRewind 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. NrF)rFrrrwrrrzrEr>r>r?rewinds z Cursor.rewindcCs>|js d|_||jrtt|js|r|jSt)zAdvance the cursor.T)rrr StopIterationrrrTpopleftrEr>r>r?r+s z Cursor.nextresulttotalcCs|js d|_||jrdSt|js|r@|dur)||j|jdStt t|j|D] }| |j q3dSdS)z*Get all or some documents from the cursor.TFN) rrrrrrTextendclearrangerer(rW)r=rXrYrr>r>r? _next_batchs  zCursor._next_batchcCs|Sr;r*rEr>r>r?__next__zCursor.__next__cC|Sr;r>rEr>r>r?__iter__zCursor.__iter__cCr`r;r>rEr>r>r? __enter__ rbzCursor.__enter__exc_typeexc_valexc_tbcCrr;)rF)r=rdrerfr>r>r?__exit__ rzCursor.__exit__lengthlist[_DocumentType]cCsfg}|}t|tr|dkrtd|jr1|||s |S|dur.|t|}|dkr. |S|js|S)akConverts the contents of this cursor to a list more efficiently than ``[doc for doc in cursor]``. To use:: >>> cursor.to_list() Or, to read at most n items from the cursor:: >>> cursor.to_list(n) If the cursor is empty or has no more results, an empty list will be returned. .. versionadded:: 4.9 rz'to_list() length must be greater than 0Nr)r}rTrrr]r)r=rhres remainingr>r>r?to_lists  zCursor.to_list)2rMrNrOrPrQrRrSrTrUrTrVr:rWrTrXrYrZr:r[r:r\rTr]r^r_r`rarbrcrbrdrYrerYrfrgrhrgrirgrjrkrlrmrnrgrorgrArBrG)rArN)rArT)rAr)TN)rr:rrrArL)rlrmrArL)rAr)rrTrAr)rnr:rAr)rUrTrAr)r\rTrAr)rSrTrAr)rcrbrAr)rrbrAr)rrTrAr/)rrrAr)rrrAr)rarbrAr)rrrArr;)rrrrrArrAr/)rr`rArB)rr`rAr)rjrrAr)r r rAr)r]r^rArNF) r r rrbrr2rrPrr:rAr)rAr3)rAr:)rArb)rAr)rArm)rrrAr)rrrr rAr)rr1rr rAr)rr"rr rAr#)r/r:rAr0)r-rrAr)r;r<rArB)rXrrYrbrAr:)rdrrerrfrrArB)rhrbrAri)BrHrIrJr&rPr#rQrrr@rpropertyrMrrrrrrrrrrnrUr\rSrcrrrrardrerXrrr_rjr r]rrrrrrlrrrr3rr8rFr:rNrTrUr+r]r^rarcrgrapplyrlr>r>r>r?rL\s       *  2            R   0    *       #     T @     rLcsNeZdZdZeZeZd!fd d Z d"d#ddZ d$ddZ d%dd Z Z S)&RawBatchCursorzFA cursor / iterator over raw batches of BSON data from a query result.rMrNargsrkwargsrArBcstj|g|Ri|dS)aGCreate 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 `_. N)superr@)r=rMrrrsrr>r?r@3s zRawBatchCursor.__init__NFr r rrbrCodecOptions[Mapping[str, Any]]rrPrr:list[_DocumentOut]cCs,|j||d}|st|dttd|S)N)rrr.) raw_responserrr)r=r rrrrrxr>r>r?r>s zRawBatchCursor._unpack_responser/cCs|jdt|jd}|S)zReturns an explain plan record for this cursor. .. seealso:: The MongoDB documentation on `explain `_. T)rr)rrLrMr)r=rr>r>r?rMszRawBatchCursor.explainrr cCstd)Nz)Cannot call __getitem__ on RawBatchCursor)rrr>r>r?rUr_zRawBatchCursor.__getitem__)rMrNrrrrsrrArBrn) r r rrbrrvrrPrr:rArwrm)rrrAr ) rHrIrJrKr(rPr'rQr@rrr __classcell__r>r>rur?rq-s rq)RrK __future__rr'r collectionsrtypingrrrrrr r r r r rrbsonrr bson.coderbson.sonrpymongorrpymongo.collationrpymongo.commonrrpymongo.cursor_sharedrrrrrpymongo.errorsrrr pymongo.lockr!pymongo.messager"r#r$r%r&r'r(pymongo.responser)pymongo.synchronous.helpersr+pymongo.typingsr,r-r.r/pymongo.write_concernr0 _typeshedr1bson.codec_optionsr2pymongo.read_preferencesr3"pymongo.synchronous.client_sessionr4pymongo.synchronous.collectionr5pymongo.synchronous.poolr6rr7rLrqr>r>r>r?sP  8    $        Z