diff --git a/pymongo/asynchronous/aggregation.py b/pymongo/asynchronous/aggregation.py index fa6cefd53..768415189 100644 --- a/pymongo/asynchronous/aggregation.py +++ b/pymongo/asynchronous/aggregation.py @@ -40,8 +40,8 @@ class _AggregationCommand: """The internal abstract base class for aggregation cursors. Should not be called directly by application developers. Use - :meth:`pymongo.collection.AsyncCollection.aggregate`, or - :meth:`pymongo.database.AsyncDatabase.aggregate` instead. + :meth:`pymongo.asynchronous.collection.AsyncCollection.aggregate`, or + :meth:`pymongo.asynchronous.database.AsyncDatabase.aggregate` instead. """ def __init__( diff --git a/pymongo/asynchronous/change_stream.py b/pymongo/asynchronous/change_stream.py index 92cc95cf5..719020c40 100644 --- a/pymongo/asynchronous/change_stream.py +++ b/pymongo/asynchronous/change_stream.py @@ -91,9 +91,9 @@ class AsyncChangeStream(Generic[_DocumentType]): """The internal abstract base class for change stream cursors. Should not be called directly by application developers. Use - :meth:`pymongo.collection.AsyncCollection.watch`, - :meth:`pymongo.database.AsyncDatabase.watch`, or - :meth:`pymongo.mongo_client.AsyncMongoClient.watch` instead. + :meth:`pymongo.asynchronous.collection.AsyncCollection.watch`, + :meth:`pymongo.asynchronous.database.AsyncDatabase.watch`, or + :meth:`pymongo.asynchronous.mongo_client.AsyncMongoClient.watch` instead. .. versionadded:: 3.6 .. seealso:: The MongoDB documentation on `changeStreams `_. @@ -166,7 +166,7 @@ class AsyncChangeStream(Generic[_DocumentType]): @property def _client(self) -> AsyncMongoClient: """The client against which the aggregation commands for - this ChangeStream will be run. + this AsyncChangeStream will be run. """ raise NotImplementedError @@ -204,7 +204,7 @@ class AsyncChangeStream(Generic[_DocumentType]): return options def _aggregation_pipeline(self) -> list[dict[str, Any]]: - """Return the full aggregation pipeline for this ChangeStream.""" + """Return the full aggregation pipeline for this AsyncChangeStream.""" options = self._change_stream_options() full_pipeline: list = [{"$changeStream": options}] full_pipeline.extend(self._pipeline) @@ -238,7 +238,7 @@ class AsyncChangeStream(Generic[_DocumentType]): async def _run_aggregation_cmd( self, session: Optional[AsyncClientSession], explicit_session: bool ) -> AsyncCommandCursor: - """Run the full aggregation pipeline for this ChangeStream and return + """Run the full aggregation pipeline for this AsyncChangeStream and return the corresponding AsyncCommandCursor. """ cmd = self._aggregation_command_class( @@ -272,7 +272,7 @@ class AsyncChangeStream(Generic[_DocumentType]): self._cursor = await self._create_cursor() async def close(self) -> None: - """Close this ChangeStream.""" + """Close this AsyncChangeStream.""" self._closed = True await self._cursor.close() @@ -299,27 +299,27 @@ class AsyncChangeStream(Generic[_DocumentType]): try: resume_token = None pipeline = [{'$match': {'operationType': 'insert'}}] - async with db.collection.watch(pipeline) as stream: + async with await db.collection.watch(pipeline) as stream: async for insert_change in stream: print(insert_change) resume_token = stream.resume_token except pymongo.errors.PyMongoError: - # The ChangeStream encountered an unrecoverable error or the + # The AsyncChangeStream encountered an unrecoverable error or the # resume attempt failed to recreate the cursor. if resume_token is None: # There is no usable resume token because there was a - # failure during ChangeStream initialization. + # failure during AsyncChangeStream initialization. logging.error('...') else: - # Use the interrupted ChangeStream's resume token to create - # a new ChangeStream. The new stream will continue from the + # Use the interrupted AsyncChangeStream's resume token to create + # a new AsyncChangeStream. The new stream will continue from the # last seen insert change without missing any events. - async with db.collection.watch( + async with await db.collection.watch( pipeline, resume_after=resume_token) as stream: async for insert_change in stream: print(insert_change) - Raises :exc:`StopIteration` if this ChangeStream is closed. + Raises :exc:`StopIteration` if this AsyncChangeStream is closed. """ while self.alive: doc = await self.try_next() @@ -348,10 +348,10 @@ class AsyncChangeStream(Generic[_DocumentType]): This method returns the next change document without waiting indefinitely for the next change. For example:: - async with db.collection.watch() as stream: + async with await db.collection.watch() as stream: while stream.alive: change = await stream.try_next() - # Note that the ChangeStream's resume token may be updated + # Note that the AsyncChangeStream's resume token may be updated # even when no changes are returned. print("Current resume token: %r" % (stream.resume_token,)) if change is not None: @@ -447,7 +447,7 @@ class AsyncCollectionChangeStream(AsyncChangeStream[_DocumentType]): """A change stream that watches changes on a single collection. Should not be called directly by application developers. Use - helper method :meth:`pymongo.collection.AsyncCollection.watch` instead. + helper method :meth:`pymongo.asynchronous.collection.AsyncCollection.watch` instead. .. versionadded:: 3.7 """ @@ -467,7 +467,7 @@ class AsyncDatabaseChangeStream(AsyncChangeStream[_DocumentType]): """A change stream that watches changes on all collections in a database. Should not be called directly by application developers. Use - helper method :meth:`pymongo.database.AsyncDatabase.watch` instead. + helper method :meth:`pymongo.asynchronous.database.AsyncDatabase.watch` instead. .. versionadded:: 3.7 """ @@ -487,7 +487,7 @@ class AsyncClusterChangeStream(AsyncDatabaseChangeStream[_DocumentType]): """A change stream that watches changes on all collections in the cluster. Should not be called directly by application developers. Use - helper method :meth:`pymongo.mongo_client.AsyncMongoClient.watch` instead. + helper method :meth:`pymongo.asynchronous.mongo_client.AsyncMongoClient.watch` instead. .. versionadded:: 3.7 """ diff --git a/pymongo/asynchronous/client_session.py b/pymongo/asynchronous/client_session.py index 2aff95ee5..d80495d80 100644 --- a/pymongo/asynchronous/client_session.py +++ b/pymongo/asynchronous/client_session.py @@ -102,7 +102,7 @@ Snapshot Reads MongoDB 5.0 adds support for snapshot reads. Snapshot reads are requested by passing the ``snapshot`` option to -:meth:`~pymongo.mongo_client.AsyncMongoClient.start_session`. +:meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.start_session`. If ``snapshot`` is True, all read operations that use this session read data from the same snapshot timestamp. The server chooses the latest majority-committed snapshot timestamp when executing the first read operation @@ -123,11 +123,11 @@ Snapshot Reads Limitations Snapshot reads sessions are incompatible with ``causal_consistency=True``. Only the following read operations are supported in a snapshot reads session: -- :meth:`~pymongo.collection.AsyncCollection.find` -- :meth:`~pymongo.collection.AsyncCollection.find_one` -- :meth:`~pymongo.collection.AsyncCollection.aggregate` -- :meth:`~pymongo.collection.AsyncCollection.count_documents` -- :meth:`~pymongo.collection.AsyncCollection.distinct` (on unsharded collections) +- :meth:`~pymongo.asynchronous.collection.AsyncCollection.find` +- :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one` +- :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate` +- :meth:`~pymongo.asynchronous.collection.AsyncCollection.count_documents` +- :meth:`~pymongo.asynchronous.collection.AsyncCollection.distinct` (on unsharded collections) Classes ======= @@ -492,7 +492,7 @@ class AsyncClientSession: Should not be initialized directly by application developers - to create a :class:`AsyncClientSession`, call - :meth:`~pymongo.mongo_client.AsyncMongoClient.start_session`. + :meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.start_session`. """ def __init__( @@ -550,7 +550,7 @@ class AsyncClientSession: @property def client(self) -> AsyncMongoClient: - """The :class:`~pymongo.mongo_client.AsyncMongoClient` this session was + """The :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` this session was created from. """ return self._client @@ -898,7 +898,7 @@ class AsyncClientSession: """Update the cluster time for this session. :param cluster_time: The - :data:`~pymongo.client_session.AsyncClientSession.cluster_time` from + :data:`~pymongo.asynchronous.client_session.AsyncClientSession.cluster_time` from another `AsyncClientSession` instance. """ if not isinstance(cluster_time, _Mapping): @@ -919,7 +919,7 @@ class AsyncClientSession: """Update the operation time for this session. :param operation_time: The - :data:`~pymongo.client_session.AsyncClientSession.operation_time` from + :data:`~pymongo.asynchronous.client_session.AsyncClientSession.operation_time` from another `AsyncClientSession` instance. """ if not isinstance(operation_time, Timestamp): @@ -1133,7 +1133,7 @@ class _ServerSessionPool(collections.deque): def get_server_session(self, session_timeout_minutes: Optional[int]) -> _ServerSession: # Although the Driver Sessions Spec says we only clear stale sessions # in return_server_session, PyMongo can't take a lock when returning - # sessions from a __del__ method (like in Cursor.__die), so it can't + # sessions from a __del__ method (like in AsyncCursor.__die), so it can't # clear stale sessions there. In case many sessions were returned via # __del__, check for stale sessions here too. self._clear_stale(session_timeout_minutes) diff --git a/pymongo/asynchronous/collection.py b/pymongo/asynchronous/collection.py index b05a92202..e634b449f 100644 --- a/pymongo/asynchronous/collection.py +++ b/pymongo/asynchronous/collection.py @@ -111,8 +111,8 @@ _WriteOp = Union[ class ReturnDocument: """An enum used with - :meth:`~pymongo.collection.AsyncCollection.find_one_and_replace` and - :meth:`~pymongo.collection.AsyncCollection.find_one_and_update`. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_replace` and + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_update`. """ BEFORE = False @@ -155,7 +155,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :class:`str`. Raises :class:`~pymongo.errors.InvalidName` if `name` is not a valid collection name. Any additional keyword arguments will be used as options passed to the create command. See - :meth:`~pymongo.database.AsyncDatabase.create_collection` for valid + :meth:`~pymongo.asynchronous.database.AsyncDatabase.create_collection` for valid options. If `create` is ``True``, `collation` is specified, or any additional @@ -207,8 +207,8 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): .. versionchanged:: 3.0 Added the codec_options, read_preference, and write_concern options. Removed the uuid_subtype attribute. - :class:`~pymongo.collection.Collection` no longer returns an - instance of :class:`~pymongo.collection.Collection` for attribute + :class:`~pymongo.asynchronous.collection.AsyncCollection` no longer returns an + instance of :class:`~pymongo.asynchronous.collection.AsyncCollection` for attribute names with leading underscores. You must use dict-style lookups instead:: @@ -249,7 +249,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): if create or kwargs: if _IS_SYNC: warnings.warn( - "The `create` and `kwargs` arguments to Collection are deprecated and will be removed in PyMongo 5.0", + "The `create` and `kwargs` arguments to AsyncCollection are deprecated and will be removed in PyMongo 5.0", DeprecationWarning, stacklevel=2, ) @@ -321,7 +321,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): @property def database(self) -> AsyncDatabase[_DocumentType]: - """The :class:`~pymongo.database.AsyncDatabase` that this + """The :class:`~pymongo.asynchronous.database.AsyncDatabase` that this :class:`AsyncCollection` is a part of. """ return self._database @@ -346,19 +346,19 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param codec_options: An instance of :class:`~bson.codec_options.CodecOptions`. If ``None`` (the - default) the :attr:`codec_options` of this :class:`Collection` + default) the :attr:`codec_options` of this :class:`AsyncCollection` is used. :param read_preference: The read preference to use. If ``None`` (the default) the :attr:`read_preference` of this - :class:`Collection` is used. See :mod:`~pymongo.read_preferences` + :class:`AsyncCollection` is used. See :mod:`~pymongo.read_preferences` for options. :param write_concern: An instance of :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the - default) the :attr:`write_concern` of this :class:`Collection` + default) the :attr:`write_concern` of this :class:`AsyncCollection` is used. :param read_concern: An instance of :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the - default) the :attr:`read_concern` of this :class:`Collection` + default) the :attr:`read_concern` of this :class:`AsyncCollection` is used. """ return AsyncCollection( @@ -384,7 +384,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): __iter__ = None def __next__(self) -> NoReturn: - raise TypeError(f"'{type(self).__name__}' object is not iterable") + raise TypeError("'AsyncCollection' object is not iterable") next = __next__ @@ -393,7 +393,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): if "." not in self._name: raise TypeError( f"'{type(self).__name__}' object is not callable. If you " - "meant to call the '%s' method on a 'Database' " + "meant to call the '%s' method on an 'AsyncDatabase' " "object it is failing because no such method " "exists." % self._name ) @@ -427,7 +427,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): .. code-block:: python - async with db.collection.watch() as stream: + async with await db.collection.watch() as stream: async for change in stream: print(change) @@ -443,11 +443,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): .. code-block:: python try: - async with db.collection.watch([{"$match": {"operationType": "insert"}}]) as stream: + async with await db.coll.watch([{"$match": {"operationType": "insert"}}]) as stream: async for insert_change in stream: print(insert_change) except pymongo.errors.PyMongoError: - # The ChangeStream encountered an unrecoverable error or the + # The AsyncChangeStream encountered an unrecoverable error or the # resume attempt failed to recreate the cursor. logging.error("...") @@ -455,7 +455,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): `change streams specification`_. .. note:: Using this helper method is preferred to directly calling - :meth:`~pymongo.collection.AsyncCollection.aggregate` with a + :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate` with a ``$changeStream`` stage, for the purpose of supporting resumability. @@ -493,7 +493,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): the specified :class:`~bson.timestamp.Timestamp`. Requires MongoDB >= 4.0. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param start_after: The same as `resume_after` except that `start_after` can resume notifications after an invalidate event. This option and `resume_after` are mutually exclusive. @@ -580,7 +580,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param collation` (optional) - An instance of :class:`~pymongo.collation.Collation`. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param retryable_write: True if this command is a retryable write. :param user_fields: Response fields that should be decoded @@ -689,7 +689,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :class:`~pymongo.operations.DeleteOne`, or :class:`~pymongo.operations.DeleteMany`). - >>> for doc in db.test.find({}): + >>> async for doc in db.test.find({}): ... print(doc) ... {'x': 1, '_id': ObjectId('54f62e60fba5226811f634ef')} @@ -699,7 +699,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): >>> from pymongo import InsertOne, DeleteOne, ReplaceOne >>> requests = [InsertOne({'y': 1}), DeleteOne({'x': 1}), ... ReplaceOne({'w': 1}, {'z': 1}, upsert=True)] - >>> result = db.test.bulk_write(requests) + >>> result = await db.test.bulk_write(requests) >>> result.inserted_count 1 >>> result.deleted_count @@ -708,7 +708,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): 0 >>> result.upserted_ids {2: ObjectId('54f62ee28891e756a6e1abd5')} - >>> for doc in db.test.find({}): + >>> async for doc in db.test.find({}): ... print(doc) ... {'x': 1, '_id': ObjectId('54f62e60fba5226811f634f0')} @@ -725,7 +725,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): write to opt-out of document level validation. Default is ``False``. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param let: Map of parameter names and values. Values must be @@ -834,7 +834,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): write to opt-out of document level validation. Default is ``False``. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. @@ -903,7 +903,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): write to opt-out of document level validation. Default is ``False``. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. @@ -1138,11 +1138,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.2 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -1247,11 +1247,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.2 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -1347,11 +1347,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.2 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -1407,10 +1407,10 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): comment: Optional[Any] = None, encrypted_fields: Optional[Mapping[str, Any]] = None, ) -> None: - """Alias for :meth:`~pymongo.database.AsyncDatabase.drop_collection`. + """Alias for :meth:`~pymongo.asynchronous.database.AsyncDatabase.drop_collection`. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param encrypted_fields: **(BETA)** Document that describes the encrypted fields for @@ -1565,11 +1565,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.4 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -1630,11 +1630,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.4 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -1722,7 +1722,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): Raises :class:`TypeError` if any of the arguments are of improper type. Returns an instance of - :class:`~pymongo.cursor.AsyncCursor` corresponding to this query. + :class:`~pymongo.asynchronous.cursor.AsyncCursor` corresponding to this query. The :meth:`find` method obeys the :attr:`read_preference` of this :class:`AsyncCollection`. @@ -1736,7 +1736,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): always be returned. Use a dict to exclude fields from the result (e.g. projection={'_id': False}). :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param skip: the number of documents to omit (from the start of the result set) when returning the results :param limit: the maximum number of results to @@ -1772,7 +1772,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param sort: a list of (key, direction) pairs specifying the sort order for this query. See - :meth:`~pymongo.cursor.Cursor.sort` for details. + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.sort` for details. :param allow_partial_results: if True, mongos will return partial results if some shards are down instead of returning an error. @@ -1790,32 +1790,32 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): cursor from returning a document more than once because of an intervening write operation. :param hint: An index, in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). Pass this as an alternative to calling - :meth:`~pymongo.cursor.Cursor.hint` on the cursor to tell Mongo the + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.hint` on the cursor to tell Mongo the proper index to use for the query. :param max_time_ms: 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. Pass this as an alternative to calling - :meth:`~pymongo.cursor.AsyncCursor.max_time_ms` on the cursor. + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.max_time_ms` on the cursor. :param max_scan: **DEPRECATED** - The maximum number of documents to scan. Pass this as an alternative to calling - :meth:`~pymongo.cursor.AsyncCursor.max_scan` on the cursor. + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.max_scan` on the cursor. :param min: A list of field, limit pairs specifying the inclusive lower bound for all keys of a specific index in order. Pass this as an alternative to calling - :meth:`~pymongo.cursor.AsyncCursor.min` on the cursor. ``hint`` must + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.min` on the cursor. ``hint`` must also be passed to ensure the query utilizes the correct index. :param max: A list of field, limit pairs specifying the exclusive upper bound for all keys of a specific index in order. Pass this as an alternative to calling - :meth:`~pymongo.cursor.Cursor.max` on the cursor. ``hint`` must + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.max` on the cursor. ``hint`` must also be passed to ensure the query utilizes the correct index. :param comment: A string to attach to the query to help interpret and trace the operation in the server logs and in profile data. Pass this as an alternative to calling - :meth:`~pymongo.cursor.AsyncCursor.comment` on the cursor. + :meth:`~pymongo.asynchronous.cursor.AsyncCursor.comment` on the cursor. :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. The option has no effect if @@ -1834,7 +1834,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): - A :class:`~pymongo.cursor.AsyncCursor` instance created with the :attr:`~pymongo.cursor.CursorType.EXHAUST` cursor_type requires an exclusive :class:`~socket.socket` connection to MongoDB. If the - :class:`~pymongo.cursor.AsyncCursor` is discarded without being + :class:`~pymongo.asynchronous.cursor.AsyncCursor` is discarded without being completely iterated the underlying :class:`~socket.socket` connection will be closed and discarded without being returned to the connection pool. @@ -1899,7 +1899,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): """Query the database and retrieve batches of raw BSON. Similar to the :meth:`find` method but returns a - :class:`~pymongo.cursor.AsyncRawBatchCursor`. + :class:`~pymongo.asynchronous.cursor.AsyncRawBatchCursor`. This example demonstrates how to work with raw batches, but in practice raw batches should be passed to an external library that can decode @@ -2069,7 +2069,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): to count in the collection. Can be an empty document to count all documents. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: See list of options above. @@ -2144,7 +2144,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param indexes: A list of :class:`~pymongo.operations.IndexModel` instances. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the createIndexes @@ -2153,7 +2153,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): - .. note:: The :attr:`~pymongo.collection.AsyncCollection.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of this collection is automatically applied to this operation. .. versionchanged:: 3.6 @@ -2181,7 +2181,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param indexes: A list of :class:`~pymongo.operations.IndexModel` instances. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param kwargs: optional arguments to the createIndexes command (like maxTimeMS) can be passed as keyword arguments. """ @@ -2290,13 +2290,13 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): option is silently ignored by the server and unique index builds using the option will fail if a duplicate value is detected. - .. note:: The :attr:`~pymongo.collection.Collection.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of this collection is automatically applied to this operation. :param keys: a single key or a list of (key, direction) pairs specifying the index to create :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: any additional index creation @@ -2347,13 +2347,13 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): Raises OperationFailure on an error. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the createIndexes command (like maxTimeMS) can be passed as keyword arguments. - .. note:: The :attr:`~pymongo.collection.AsyncCollection.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of this collection is automatically applied to this operation. .. versionchanged:: 3.6 @@ -2394,7 +2394,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param index_or_name: index (or name of index) to drop :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the createIndexes @@ -2402,7 +2402,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): - .. note:: The :attr:`~pymongo.collection.AsyncCollection.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of this collection is automatically applied to this operation. @@ -2453,17 +2453,17 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): ) -> AsyncCommandCursor[MutableMapping[str, Any]]: """Get a cursor over the index documents for this collection. - >>> async for index in db.test.list_indexes(): + >>> async for index in await db.test.list_indexes(): ... print(index) ... SON([('v', 2), ('key', SON([('_id', 1)])), ('name', '_id_')]) :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. - :return: An instance of :class:`~pymongo.command_cursor.AsyncCommandCursor`. + :return: An instance of :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor`. .. versionchanged:: 4.1 Added ``comment`` parameter. @@ -2541,14 +2541,14 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): ``"name"`` keys, which are cleaned. Example output might look like this: - >>> db.test.create_index("x", unique=True) + >>> await db.test.create_index("x", unique=True) 'x_1' - >>> db.test.index_information() + >>> await db.test.index_information() {'_id_': {'key': [('_id', 1)]}, 'x_1': {'unique': True, 'key': [('x', 1)]}} :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. @@ -2579,11 +2579,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): for. Only indexes with matching index names will be returned. If not given, all search indexes for the current collection will be returned. - :param session: a :class:`~pymongo.client_session.AsyncClientSession`. + :param session: a :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. - :return: A :class:`~pymongo.command_cursor.AsyncCommandCursor` over the result + :return: A :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor` over the result set. .. note:: requires a MongoDB server version 7.0+ Atlas cluster. @@ -2633,7 +2633,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): instance or a dictionary with a model "definition" and optional "name". :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the createSearchIndexes @@ -2659,7 +2659,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): """Create multiple search indexes for the current collection. :param models: A list of :class:`~pymongo.operations.SearchIndexModel` instances. - :param session: a :class:`~pymongo.client_session.AsyncClientSession`. + :param session: a :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the createSearchIndexes @@ -2716,7 +2716,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param name: The name of the search index to be deleted. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the dropSearchIndexes @@ -2752,7 +2752,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param name: The name of the search index to be updated. :param definition: The new search index definition. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: optional arguments to the updateSearchIndexes @@ -2783,12 +2783,12 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): """Get the options set on this collection. Returns a dictionary of options and their values - see - :meth:`~pymongo.database.AsyncDatabase.create_collection` for more + :meth:`~pymongo.asynchronous.database.AsyncDatabase.create_collection` for more information on the possible options. Returns an empty dictionary if the collection has not been created yet. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. @@ -2874,12 +2874,12 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): instead. An example is included in the :ref:`aggregate-examples` documentation. - .. note:: The :attr:`~pymongo.collection.AsyncCollection.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of this collection is automatically applied to this operation. :param pipeline: a list of aggregation pipeline stages :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: A dict of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -2905,7 +2905,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :class:`~pymongo.collation.Collation`. - :return: A :class:`~pymongo.command_cursor.AsyncCommandCursor` over the result + :return: A :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor` over the result set. .. versionchanged:: 4.1 @@ -2928,7 +2928,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): Apply this collection's write concern automatically to this operation when connected to MongoDB >= 3.4. Support the `collation` option. .. versionchanged:: 3.0 - The :meth:`aggregate` method always returns a CommandCursor. The + The :meth:`aggregate` method always returns an AsyncCommandCursor. The pipeline argument must be a list. .. seealso:: :doc:`/examples/aggregation` @@ -2958,7 +2958,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): """Perform an aggregation and retrieve batches of raw BSON. Similar to the :meth:`aggregate` method but returns a - :class:`~pymongo.cursor.AsyncRawBatchCursor`. + :class:`~pymongo.asynchronous.cursor.AsyncRawBatchCursor`. This example demonstrates how to work with raw batches, but in practice raw batches should be passed to an external library that can decode @@ -3014,14 +3014,14 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param new_name: new name for this collection :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: additional arguments to the rename command may be passed as keyword arguments to this helper method (i.e. ``dropTarget=True``) - .. note:: The :attr:`~pymongo.collection.AsyncCollection.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.collection.AsyncCollection.write_concern` of this collection is automatically applied to this operation. .. versionchanged:: 3.6 @@ -3083,14 +3083,14 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :class:`~pymongo.collation.Collation`. The :meth:`distinct` method obeys the :attr:`read_preference` of - this :class:`Collection`. + this :class:`AsyncCollection`. :param key: name of the field for which we want to get the distinct values :param filter: A query document that specifies the documents from which to retrieve the distinct values. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: See list of options above. @@ -3261,11 +3261,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): match the query, they are sorted and the first is deleted. :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as - passed to :meth:`~pymongo.collection.AsyncCollection.create_index` + passed to :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.4 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -3287,7 +3287,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): .. warning:: Starting in PyMongo 3.2, this command uses the :class:`~pymongo.write_concern.WriteConcern` of this - :class:`~pymongo.collection.AsyncCollection` when connected to MongoDB >= + :class:`~pymongo.asynchronous.collection.AsyncCollection` when connected to MongoDB >= 3.2. Note that using an elevated write concern with this command may be slower compared to using the default write concern. @@ -3359,11 +3359,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.4 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -3387,7 +3387,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): .. warning:: Starting in PyMongo 3.2, this command uses the :class:`~pymongo.write_concern.WriteConcern` of this - :class:`~pymongo.collection.AsyncCollection` when connected to MongoDB >= + :class:`~pymongo.asynchronous.collection.AsyncCollection` when connected to MongoDB >= 3.2. Note that using an elevated write concern with this command may be slower compared to using the default write concern. @@ -3461,7 +3461,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): The *upsert* option can be used to create the document if it doesn't already exist. - >>> await db.example.delete_many({}).deleted_count + >>> (await db.example.delete_many({})).deleted_count 1 >>> await db.example.find_one_and_update( ... {'_id': 'userid'}, @@ -3506,11 +3506,11 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): :param hint: An index to use to support the query predicate specified either by its string name, or in the same format as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` (e.g. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` (e.g. ``[('field', ASCENDING)]``). This option is only supported on MongoDB 4.4 and above. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param let: Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an @@ -3534,7 +3534,7 @@ class AsyncCollection(common.BaseObject, Generic[_DocumentType]): .. warning:: Starting in PyMongo 3.2, this command uses the :class:`~pymongo.write_concern.WriteConcern` of this - :class:`~pymongo.collection.AsyncCollection` when connected to MongoDB >= + :class:`~pymongo.asynchronous.collection.AsyncCollection` when connected to MongoDB >= 3.2. Note that using an elevated write concern with this command may be slower compared to using the default write concern. diff --git a/pymongo/asynchronous/command_cursor.py b/pymongo/asynchronous/command_cursor.py index 9816ccaaf..b28f983b1 100644 --- a/pymongo/asynchronous/command_cursor.py +++ b/pymongo/asynchronous/command_cursor.py @@ -189,7 +189,7 @@ class AsyncCommandCursor(Generic[_DocumentType]): @property def session(self) -> Optional[AsyncClientSession]: - """The cursor's :class:`~pymongo.client_session.AsyncClientSession`, or None. + """The cursor's :class:`~pymongo.asynchronous.client_session.AsyncClientSession`, or None. .. versionadded:: 3.6 """ @@ -416,7 +416,7 @@ class AsyncRawBatchCommandCursor(AsyncCommandCursor[_DocumentType]): """Create a new cursor / iterator over raw batches of BSON data. Should not be called directly by application developers - - see :meth:`~pymongo.collection.AsyncCollection.aggregate_raw_batches` + see :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate_raw_batches` instead. .. seealso:: The MongoDB documentation on `cursors `_. diff --git a/pymongo/asynchronous/cursor.py b/pymongo/asynchronous/cursor.py index fa4431622..8421667be 100644 --- a/pymongo/asynchronous/cursor.py +++ b/pymongo/asynchronous/cursor.py @@ -123,7 +123,7 @@ class AsyncCursor(Generic[_DocumentType]): """Create a new cursor. Should not be called directly by application developers - see - :meth:`~pymongo.collection.AsyncCollection.find` instead. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find` instead. .. seealso:: The MongoDB documentation on `cursors `_. """ @@ -256,7 +256,7 @@ class AsyncCursor(Generic[_DocumentType]): @property def collection(self) -> AsyncCollection[_DocumentType]: - """The :class:`~pymongo.collection.AsyncCollection` that this + """The :class:`~pymongo.asynchronous.collection.AsyncCollection` that this :class:`AsyncCursor` is iterating. """ return self._collection @@ -322,7 +322,7 @@ class AsyncCursor(Generic[_DocumentType]): return base def _clone_base(self, session: Optional[AsyncClientSession]) -> AsyncCursor: - """Creates an empty Cursor object for information to be copied into.""" + """Creates an empty AsyncCursor object for information to be copied into.""" return self.__class__(self._collection, session=session) def _query_spec(self) -> Mapping[str, Any]: @@ -527,7 +527,7 @@ class AsyncCursor(Generic[_DocumentType]): def max_await_time_ms(self, max_await_time_ms: Optional[int]) -> AsyncCursor[_DocumentType]: """Specifies a time limit for a getMore operation on a - :attr:`~pymongo.cursor_shared.CursorType.TAILABLE_AWAIT` cursor. For all other + :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 @@ -606,12 +606,12 @@ class AsyncCursor(Generic[_DocumentType]): self._empty = False if isinstance(index, slice): if index.step is not None: - raise IndexError("Cursor instances do not support slice steps") + raise IndexError("AsyncCursor 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") + raise IndexError("AsyncCursor instances do not support negative indices") skip = index.start if index.stop is not None: @@ -631,15 +631,15 @@ class AsyncCursor(Generic[_DocumentType]): if isinstance(index, int): if index < 0: - raise IndexError("Cursor instances do not support negative indices") + raise IndexError("AsyncCursor 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: # type: ignore[attr-defined] return doc - raise IndexError("no such item for Cursor instance") - raise TypeError("index %r cannot be applied to Cursor instances" % index) + raise IndexError("no such item for AsyncCursor instance") + raise TypeError("index %r cannot be applied to AsyncCursor instances" % index) else: raise IndexError("AsyncCursor does not support indexing") @@ -727,7 +727,7 @@ class AsyncCursor(Generic[_DocumentType]): Text search results can be sorted by relevance:: - cursor = await db.test.find( + cursor = db.test.find( {'$text': {'$search': 'some words'}}, {'score': {'$meta': 'textScore'}}) @@ -761,7 +761,7 @@ class AsyncCursor(Generic[_DocumentType]): `explain command `_, ``allPlansExecution``. To use a different verbosity use - :meth:`~pymongo.database.AsyncDatabase.command` to run the explain + :meth:`~pymongo.asynchronous.database.AsyncDatabase.command` to run the explain command directly. .. seealso:: The MongoDB documentation on `explain `_. @@ -796,7 +796,7 @@ class AsyncCursor(Generic[_DocumentType]): already been used. `index` should be an index as passed to - :meth:`~pymongo.collection.AsyncCollection.create_index` + :meth:`~pymongo.asynchronous.collection.AsyncCollection.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 @@ -838,7 +838,7 @@ class AsyncCursor(Generic[_DocumentType]): 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 + :class:`AsyncCursor` has already been used. Only the last call to :meth:`where` applied to a :class:`AsyncCursor` has any effect. .. note:: MongoDB 4.4 drops support for :class:`~bson.code.Code` @@ -936,7 +936,7 @@ class AsyncCursor(Generic[_DocumentType]): @property def session(self) -> Optional[AsyncClientSession]: - """The cursor's :class:`~pymongo.client_session.AsyncClientSession`, or None. + """The cursor's :class:`~pymongo.asynchronous.client_session.AsyncClientSession`, or None. .. versionadded:: 3.6 """ @@ -1063,13 +1063,13 @@ class AsyncCursor(Generic[_DocumentType]): :class:`str`. The :meth:`distinct` method obeys the - :attr:`~pymongo.collection.AsyncCollection.read_preference` of the - :class:`~pymongo.collection.AsyncCollection` instance on which - :meth:`~pymongo.collection.AsyncCollection.find` was called. + :attr:`~pymongo.asynchronous.collection.AsyncCollection.read_preference` of the + :class:`~pymongo.asynchronous.collection.AsyncCollection` instance on which + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find` was called. :param key: name of key for which we want to get the distinct values - .. seealso:: :meth:`pymongo.collection.AsyncCollection.distinct` + .. seealso:: :meth:`pymongo.asynchronous.collection.AsyncCollection.distinct` """ options: dict[str, Any] = {} if self._spec: @@ -1111,7 +1111,7 @@ class AsyncCursor(Generic[_DocumentType]): await 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 + # self._killed to True ensures AsyncCursor.alive will be # False. No need to re-raise. if ( exc.code in _CURSOR_CLOSED_ERRORS @@ -1316,7 +1316,7 @@ class AsyncRawBatchCursor(AsyncCursor, Generic[_DocumentType]): """Create a new cursor / iterator over raw batches of BSON data. Should not be called directly by application developers - - see :meth:`~pymongo.collection.AsyncCollection.find_raw_batches` + see :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_raw_batches` instead. .. seealso:: The MongoDB documentation on `cursors `_. diff --git a/pymongo/asynchronous/database.py b/pymongo/asynchronous/database.py index 4bdf0ff51..b61d58183 100644 --- a/pymongo/asynchronous/database.py +++ b/pymongo/asynchronous/database.py @@ -74,7 +74,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): :class:`str`. Raises :class:`~pymongo.errors.InvalidName` if `name` is not a valid database name. - :param client: A :class:`~pymongo.mongo_client.AsyncMongoClient` instance. + :param client: A :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` instance. :param name: The database name. :param codec_options: An instance of :class:`~bson.codec_options.CodecOptions`. If ``None`` (the @@ -102,8 +102,8 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): .. versionchanged:: 3.0 Added the codec_options, read_preference, and write_concern options. - :class:`~pymongo.database.AsyncDatabase` no longer returns an instance - of :class:`~pymongo.collection.AsyncCollection` for attribute names + :class:`~pymongo.asynchronous.database.AsyncDatabase` no longer returns an instance + of :class:`~pymongo.asynchronous.collection.AsyncCollection` for attribute names with leading underscores. You must use dict-style lookups instead:: db['__my_collection__'] @@ -230,10 +230,10 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): write_concern: Optional[WriteConcern] = None, read_concern: Optional[ReadConcern] = None, ) -> AsyncCollection[_DocumentType]: - """Get a :class:`~pymongo.collection.AsyncCollection` with the given name + """Get a :class:`~pymongo.asynchronous.collection.AsyncCollection` with the given name and options. - Useful for creating a :class:`~pymongo.collection.AsyncCollection` with + Useful for creating a :class:`~pymongo.asynchronous.collection.AsyncCollection` with different codec options, read preference, and/or write concern from this :class:`AsyncDatabase`. @@ -307,7 +307,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): __iter__ = None def __next__(self) -> NoReturn: - raise TypeError("'Database' object is not iterable") + raise TypeError("'AsyncDatabase' object is not iterable") next = __next__ @@ -364,7 +364,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): async for insert_change in stream: print(insert_change) except pymongo.errors.PyMongoError: - # The ChangeStream encountered an unrecoverable error or the + # The AsyncChangeStream encountered an unrecoverable error or the # resume attempt failed to recreate the cursor. logging.error("...") @@ -401,7 +401,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): the specified :class:`~bson.timestamp.Timestamp`. Requires MongoDB >= 4.0. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param start_after: The same as `resume_after` except that `start_after` can resume notifications after an invalidate event. This option and `resume_after` are mutually exclusive. @@ -461,7 +461,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): check_exists: Optional[bool] = True, **kwargs: Any, ) -> AsyncCollection[_DocumentType]: - """Create a new :class:`~pymongo.collection.AsyncCollection` in this + """Create a new :class:`~pymongo.asynchronous.collection.AsyncCollection` in this database. Normally collection creation is automatic. This method should @@ -488,7 +488,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): :param collation: An instance of :class:`~pymongo.collation.Collation`. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param check_exists: if True (the default), send a listCollections command to check if the collection already exists before creation. :param kwargs: additional keyword arguments will @@ -621,19 +621,19 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): print(operation) The :meth:`aggregate` method obeys the :attr:`read_preference` of this - :class:`Database`, except when ``$out`` or ``$merge`` are used, in + :class:`AsyncDatabase`, except when ``$out`` or ``$merge`` are used, in which case :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY` is used. .. note:: This method does not support the 'explain' option. Please - use :meth:`~pymongo.database.Database.command` instead. + use :meth:`~pymongo.asynchronous.database.AsyncDatabase.command` instead. - .. note:: The :attr:`~pymongo.database.AsyncDatabase.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.database.AsyncDatabase.write_concern` of this collection is automatically applied to this operation. :param pipeline: a list of aggregation pipeline stages :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param kwargs: extra `aggregate command`_ parameters. All optional `aggregate command`_ parameters should be passed as @@ -656,7 +656,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): aggregate expression context (e.g. ``"$$var"``). This option is only supported on MongoDB >= 5.0. - :return: A :class:`~pymongo.command_cursor.AsyncCommandCursor` over the result + :return: A :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor` over the result set. .. versionadded:: 3.9 @@ -851,7 +851,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): :param codec_options: A :class:`~bson.codec_options.CodecOptions` instance. :param session: A - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: additional keyword arguments will @@ -952,7 +952,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): :param codec_options: A :class:`~bson.codec_options.CodecOptions` instance. :param session: A - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to future getMores for this command. :param max_await_time_ms: The number of ms to wait for more data on future getMores for this command. @@ -1082,7 +1082,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): """Get a cursor over the collections of this database. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param filter: A query document to filter the list of collections returned from the listCollections command. :param comment: A user-provided comment to attach to this @@ -1094,7 +1094,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): options differ by server version. - :return: An instance of :class:`~pymongo.command_cursor.AsyncCommandCursor`. + :return: An instance of :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor`. .. versionadded:: 3.6 """ @@ -1128,7 +1128,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): """Get a cursor over the collections of this database. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param filter: A query document to filter the list of collections returned from the listCollections command. :param comment: A user-provided comment to attach to this @@ -1140,7 +1140,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): options differ by server version. - :return: An instance of :class:`~pymongo.command_cursor.AsyncCommandCursor`. + :return: An instance of :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor`. .. versionadded:: 3.6 """ @@ -1186,7 +1186,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): db.list_collection_names(filter=filter) :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param filter: A query document to filter the list of collections returned from the listCollections command. :param comment: A user-provided comment to attach to this @@ -1235,7 +1235,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): :param name_or_collection: the name of a collection to drop or the collection object itself :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param encrypted_fields: **(BETA)** Document that describes the encrypted fields for @@ -1261,7 +1261,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): } - .. note:: The :attr:`~pymongo.database.Database.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.database.AsyncDatabase.write_concern` of this database is automatically applied to this operation. .. versionchanged:: 4.2 @@ -1325,7 +1325,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): of the structure of the collection and the individual documents. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param background: A boolean flag that determines whether the command runs in the background. Requires MongoDB 4.4+. :param comment: A user-provided comment to attach to this @@ -1347,7 +1347,7 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): name = name.name if not isinstance(name, str): - raise TypeError("name_or_collection must be an instance of str or Collection") + raise TypeError("name_or_collection must be an instance of str or AsyncCollection") cmd = {"validate": name, "scandata": scandata, "full": full} if comment is not None: cmd["comment"] = comment @@ -1400,12 +1400,12 @@ class AsyncDatabase(common.BaseObject, Generic[_DocumentType]): :param dbref: the reference :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: any additional keyword arguments are the same as the arguments to - :meth:`~pymongo.collection.AsyncCollection.find`. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find`. .. versionchanged:: 4.1 diff --git a/pymongo/asynchronous/encryption.py b/pymongo/asynchronous/encryption.py index b1a36eefa..f8c03b21c 100644 --- a/pymongo/asynchronous/encryption.py +++ b/pymongo/asynchronous/encryption.py @@ -673,7 +673,7 @@ class ClientEncryption(Generic[_DocumentType]): All optional `create collection command`_ parameters should be passed as keyword arguments to this method. - See the documentation for :meth:`~pymongo.database.AsyncDatabase.create_collection` for all valid options. + See the documentation for :meth:`~pymongo.asynchronous.database.AsyncDatabase.create_collection` for all valid options. :raises: - :class:`~pymongo.errors.EncryptedCollectionError`: When either data-key creation or creating the collection fails. @@ -978,7 +978,7 @@ class ClientEncryption(Generic[_DocumentType]): def get_keys(self) -> AsyncCursor[RawBSONDocument]: """Get all of the data keys. - :return: An instance of :class:`~pymongo.cursor.Cursor` over the data key + :return: An instance of :class:`~pymongo.asynchronous.cursor.AsyncCursor` over the data key documents. .. versionadded:: 4.2 diff --git a/pymongo/asynchronous/mongo_client.py b/pymongo/asynchronous/mongo_client.py index a320249b4..53fa14858 100644 --- a/pymongo/asynchronous/mongo_client.py +++ b/pymongo/asynchronous/mongo_client.py @@ -17,18 +17,18 @@ .. seealso:: :doc:`/examples/high_availability` for examples of connecting to replica sets or sets of mongos servers. -To get a :class:`~pymongo.database.Database` instance from a -:class:`MongoClient` use either dictionary-style or attribute-style +To get a :class:`~pymongo.asynchronous.database.AsyncDatabase` instance from a +:class:`AsyncMongoClient` use either dictionary-style or attribute-style access: .. doctest:: - >>> from pymongo import MongoClient - >>> c = MongoClient() + >>> from pymongo import AsyncMongoClient + >>> c = AsyncMongoClient() >>> c.test_database - Database(MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), 'test_database') + AsyncDatabase(AsyncMongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), 'test_database') >>> c["test-database"] - Database(MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), 'test-database') + AsyncDatabase(AsyncMongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), 'test-database') """ from __future__ import annotations @@ -175,18 +175,18 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): uri = "mongodb://%s:%s@%s" % ( quote_plus(user), quote_plus(password), host) - client = MongoClient(uri) + client = AsyncMongoClient(uri) Unix domain sockets are also supported. The socket path must be percent encoded in the URI:: uri = "mongodb://%s:%s@%s" % ( quote_plus(user), quote_plus(password), quote_plus(socket_path)) - client = MongoClient(uri) + client = AsyncMongoClient(uri) But not when passed as a simple hostname:: - client = MongoClient('/tmp/mongodb-27017.sock') + client = AsyncMongoClient('/tmp/mongodb-27017.sock') Starting with version 3.6, PyMongo supports mongodb+srv:// URIs. The URI must include one, and only one, hostname. The hostname will be @@ -202,10 +202,10 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): for more details. Note that the use of SRV URIs implicitly enables TLS support. Pass tls=false in the URI to override. - .. note:: MongoClient creation will block waiting for answers from + .. note:: AsyncMongoClient creation will block waiting for answers from DNS when mongodb+srv:// URIs are used. - .. note:: Starting with version 3.0 the :class:`MongoClient` + .. note:: Starting with version 3.0 the :class:`AsyncMongoClient` constructor no longer blocks while connecting to the server or servers, and it no longer raises :class:`~pymongo.errors.ConnectionFailure` if they are @@ -216,7 +216,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): like this:: from pymongo.errors import ConnectionFailure - client = MongoClient() + client = AsyncMongoClient() try: # The ping command is cheap and does not require auth. client.admin.command('ping') @@ -242,7 +242,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): documents returned from queries on this client :param tz_aware: if ``True``, :class:`~datetime.datetime` instances returned as values - in a document by this :class:`MongoClient` will be timezone + in a document by this :class:`AsyncMongoClient` will be timezone aware (otherwise they will be naive) :param connect: **Not supported by AsyncMongoClient**. :param type_registry: instance of @@ -314,7 +314,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): - `serverMonitoringMode`: (optional) The server monitoring mode to use. Valid values are the strings: "auto", "stream", "poll". Defaults to "auto". - `appname`: (string or None) The name of the application that - created this MongoClient instance. The server will log this value + created this AsyncMongoClient instance. The server will log this value upon establishing each connection. It is also recorded in the slow query log and profile collections. - `driver`: (pair or None) A driver implemented on top of PyMongo can @@ -324,47 +324,47 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): - `event_listeners`: a list or tuple of event listeners. See :mod:`~pymongo.monitoring` for details. - `retryWrites`: (boolean) Whether supported write operations - executed within this MongoClient will be retried once after a + executed within this AsyncMongoClient will be retried once after a network error. Defaults to ``True``. The supported write operations are: - - :meth:`~pymongo.collection.Collection.bulk_write`, as long as - :class:`~pymongo.operations.UpdateMany` or - :class:`~pymongo.operations.DeleteMany` are not included. - - :meth:`~pymongo.collection.Collection.delete_one` - - :meth:`~pymongo.collection.Collection.insert_one` - - :meth:`~pymongo.collection.Collection.insert_many` - - :meth:`~pymongo.collection.Collection.replace_one` - - :meth:`~pymongo.collection.Collection.update_one` - - :meth:`~pymongo.collection.Collection.find_one_and_delete` - - :meth:`~pymongo.collection.Collection.find_one_and_replace` - - :meth:`~pymongo.collection.Collection.find_one_and_update` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.bulk_write`, as long as + :class:`~pymongo.asynchronous.operations.UpdateMany` or + :class:`~pymongo.asynchronous.operations.DeleteMany` are not included. + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.delete_one` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.insert_one` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.insert_many` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.replace_one` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.update_one` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_delete` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_replace` + - :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_update` Unsupported write operations include, but are not limited to, - :meth:`~pymongo.collection.Collection.aggregate` using the ``$out`` + :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate` using the ``$out`` pipeline operator and any operation with an unacknowledged write concern (e.g. {w: 0})). See https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst - `retryReads`: (boolean) Whether supported read operations - executed within this MongoClient will be retried once after a + executed within this AsyncMongoClient will be retried once after a network error. Defaults to ``True``. The supported read operations are: - :meth:`~pymongo.collection.Collection.find`, - :meth:`~pymongo.collection.Collection.find_one`, - :meth:`~pymongo.collection.Collection.aggregate` without ``$out``, - :meth:`~pymongo.collection.Collection.distinct`, - :meth:`~pymongo.collection.Collection.count`, - :meth:`~pymongo.collection.Collection.estimated_document_count`, - :meth:`~pymongo.collection.Collection.count_documents`, - :meth:`pymongo.collection.Collection.watch`, - :meth:`~pymongo.collection.Collection.list_indexes`, - :meth:`pymongo.database.Database.watch`, - :meth:`~pymongo.database.Database.list_collections`, - :meth:`pymongo.mongo_client.MongoClient.watch`, - and :meth:`~pymongo.mongo_client.MongoClient.list_databases`. + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find`, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one`, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate` without ``$out``, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.distinct`, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.count`, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.estimated_document_count`, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.count_documents`, + :meth:`pymongo.asynchronous.collection.AsyncCollection.watch`, + :meth:`~pymongo.asynchronous.collection.AsyncCollection.list_indexes`, + :meth:`pymongo.asynchronous.database.AsyncDatabase.watch`, + :meth:`~pymongo.asynchronous.database.AsyncDatabase.list_collections`, + :meth:`pymongo.asynchronous.mongo_client.AsyncMongoClient.watch`, + and :meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.list_databases`. Unsupported read operations include, but are not limited to - :meth:`~pymongo.database.Database.command` and any getMore + :meth:`~pymongo.asynchronous.database.AsyncDatabase.command` and any getMore operation on a cursor. Enabling retryable reads makes applications more resilient to @@ -403,7 +403,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): - `srvServiceName`: (string) The SRV service name to use for "mongodb+srv://" URIs. Defaults to "mongodb". Use it like so:: - MongoClient("mongodb+srv://example.com/?srvServiceName=customname") + AsyncMongoClient("mongodb+srv://example.com/?srvServiceName=customname") - `srvMaxHosts`: (int) limits the number of mongos-like hosts a client will connect to. More specifically, when a "mongodb+srv://" connection string resolves to more than srvMaxHosts number of hosts, the client will randomly @@ -470,7 +470,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): this example, both the space and slash special characters are passed as-is:: - MongoClient(username="user name", password="pass/word") + AsyncMongoClient(username="user name", password="pass/word") - `authSource`: The database to authenticate on. Defaults to the database specified in the URI, if provided, or to "admin". @@ -549,9 +549,9 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): configures this client to automatically encrypt collection commands and automatically decrypt results. See :ref:`automatic-client-side-encryption` for an example. - If a :class:`MongoClient` is configured with + If a :class:`AsyncMongoClient` is configured with ``auto_encryption_opts`` and a non-None ``maxPoolSize``, a - separate internal ``MongoClient`` is created if any of the + separate internal ``AsyncMongoClient`` is created if any of the following are true: - A ``key_vault_client`` is not passed to @@ -640,14 +640,14 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): ``socketKeepAlive`` now defaults to ``True``. .. versionchanged:: 3.0 - :class:`~pymongo.mongo_client.MongoClient` is now the one and only + :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` is now the one and only client class for a standalone server, mongos, or replica set. It includes the functionality that had been split into - :class:`~pymongo.mongo_client.MongoReplicaSetClient`: it can connect + :class:`~pymongo.asynchronous.mongo_client.MongoReplicaSetClient`: it can connect to a replica set, discover all its members, and monitor the set for stepdowns, elections, and reconfigs. - The :class:`~pymongo.mongo_client.MongoClient` constructor no + The :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` constructor no longer blocks while connecting to the server or servers, and it no longer raises :class:`~pymongo.errors.ConnectionFailure` if they are unavailable, nor :class:`~pymongo.errors.ConfigurationError` @@ -659,10 +659,10 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): provides meaningful information; even if the client is disconnected, it may discover a server in time to fulfill the next operation. - In PyMongo 2.x, :class:`~pymongo.MongoClient` accepted a list of + In PyMongo 2.x, :class:`~pymongo.asynchronous.AsyncMongoClient` accepted a list of standalone MongoDB servers and used the first it could connect to:: - MongoClient(['host1.com:27017', 'host2.com:27017']) + AsyncMongoClient(['host1.com:27017', 'host2.com:27017']) A list of multiple standalones is no longer supported; if multiple servers are listed they must be members of the same replica set, or @@ -685,11 +685,11 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): The ``copy_database`` method is removed, see the :doc:`copy_database examples ` for alternatives. - The :meth:`MongoClient.disconnect` method is removed; it was a - synonym for :meth:`~pymongo.MongoClient.close`. + The :meth:`AsyncMongoClient.disconnect` method is removed; it was a + synonym for :meth:`~pymongo.asynchronous.AsyncMongoClient.close`. - :class:`~pymongo.mongo_client.MongoClient` no longer returns an - instance of :class:`~pymongo.database.Database` for attribute names + :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` no longer returns an + instance of :class:`~pymongo.asynchronous.database.AsyncDatabase` for attribute names with leading underscores. You must use dict-style lookups instead:: client['__my_database__'] @@ -924,7 +924,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): Performs an aggregation with an implicit initial ``$changeStream`` stage and returns a - :class:`~pymongo.change_stream.ClusterChangeStream` cursor which + :class:`~pymongo.asynchronous.change_stream.AsyncClusterChangeStream` cursor which iterates over changes on all databases on this cluster. Introduced in MongoDB 4.0. @@ -935,10 +935,10 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): for change in stream: print(change) - The :class:`~pymongo.change_stream.ClusterChangeStream` iterable + The :class:`~pymongo.asynchronous.change_stream.AsyncClusterChangeStream` iterable blocks until the next change document is returned or an error is raised. If the - :meth:`~pymongo.change_stream.ClusterChangeStream.next` method + :meth:`~pymongo.asynchronous.change_stream.AsyncClusterChangeStream.next` method encounters a network error when retrieving a batch from the server, it will automatically attempt to recreate the cursor such that no change events are missed. Any error encountered during the resume @@ -951,7 +951,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): for insert_change in stream: print(insert_change) except pymongo.errors.PyMongoError: - # The ChangeStream encountered an unrecoverable error or the + # The AsyncChangeStream encountered an unrecoverable error or the # resume attempt failed to recreate the cursor. logging.error("...") @@ -988,7 +988,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): the specified :class:`~bson.timestamp.Timestamp`. Requires MongoDB >= 4.0. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param start_after: The same as `resume_after` except that `start_after` can resume notifications after an invalidate event. This option and `resume_after` are mutually exclusive. @@ -996,7 +996,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): command. :param show_expanded_events: Include expanded events such as DDL events like `dropIndexes`. - :return: A :class:`~pymongo.change_stream.ClusterChangeStream` cursor. + :return: A :class:`~pymongo.asynchronous.change_stream.AsyncClusterChangeStream` cursor. .. versionchanged:: 4.3 Added `show_expanded_events` parameter. @@ -1062,9 +1062,9 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Set of all currently connected servers. .. warning:: When connected to a replica set the value of :attr:`nodes` - can change over time as :class:`MongoClient`'s view of the replica + can change over time as :class:`AsyncMongoClient`'s view of the replica set changes. :attr:`nodes` can also be an empty set when - :class:`MongoClient` is first instantiated and hasn't yet connected + :class:`AsyncMongoClient` is first instantiated and hasn't yet connected to any servers, or a network partition causes it to lose connection to all servers. """ @@ -1176,16 +1176,16 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Start a logical session. This method takes the same parameters as - :class:`~pymongo.client_session.SessionOptions`. See the - :mod:`~pymongo.client_session` module for details and examples. + :class:`~pymongo.asynchronous.client_session.SessionOptions`. See the + :mod:`~pymongo.asynchronous.client_session` module for details and examples. - A :class:`~pymongo.client_session.AsyncClientSession` may only be used with - the MongoClient that started it. :class:`AsyncClientSession` instances are + A :class:`~pymongo.asynchronous.client_session.AsyncClientSession` may only be used with + the AsyncMongoClient that started it. :class:`AsyncClientSession` instances are **not thread-safe or fork-safe**. They can only be used by one thread or process at a time. A single :class:`AsyncClientSession` cannot be used to run multiple operations concurrently. - :return: An instance of :class:`~pymongo.client_session.AsyncClientSession`. + :return: An instance of :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. .. versionadded:: 3.6 """ @@ -1237,7 +1237,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Get the database named in the MongoDB connection URI. >>> uri = 'mongodb://host/my_database' - >>> client = MongoClient(uri) + >>> client = AsyncMongoClient(uri) >>> db = client.get_default_database() >>> assert db.name == 'my_database' >>> db = client.get_database() @@ -1250,19 +1250,19 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): was provided in the URI. :param codec_options: An instance of :class:`~bson.codec_options.CodecOptions`. If ``None`` (the - default) the :attr:`codec_options` of this :class:`MongoClient` is + default) the :attr:`codec_options` of this :class:`AsyncMongoClient` is used. :param read_preference: The read preference to use. If ``None`` (the default) the :attr:`read_preference` of this - :class:`MongoClient` is used. See :mod:`~pymongo.read_preferences` + :class:`AsyncMongoClient` is used. See :mod:`~pymongo.read_preferences` for options. :param write_concern: An instance of :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the - default) the :attr:`write_concern` of this :class:`MongoClient` is + default) the :attr:`write_concern` of this :class:`AsyncMongoClient` is used. :param read_concern: An instance of :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the - default) the :attr:`read_concern` of this :class:`MongoClient` is + default) the :attr:`read_concern` of this :class:`AsyncMongoClient` is used. :param comment: A user-provided comment to attach to this command. @@ -1294,12 +1294,12 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): write_concern: Optional[WriteConcern] = None, read_concern: Optional[ReadConcern] = None, ) -> database.AsyncDatabase[_DocumentType]: - """Get a :class:`~pymongo.database.Database` with the given name and + """Get a :class:`~pymongo.asynchronous.database.AsyncDatabase` with the given name and options. - Useful for creating a :class:`~pymongo.database.Database` with + Useful for creating a :class:`~pymongo.asynchronous.database.AsyncDatabase` with different codec options, read preference, and/or write concern from - this :class:`MongoClient`. + this :class:`AsyncMongoClient`. >>> client.read_preference Primary() @@ -1317,19 +1317,19 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): returned. :param codec_options: An instance of :class:`~bson.codec_options.CodecOptions`. If ``None`` (the - default) the :attr:`codec_options` of this :class:`MongoClient` is + default) the :attr:`codec_options` of this :class:`AsyncMongoClient` is used. :param read_preference: The read preference to use. If ``None`` (the default) the :attr:`read_preference` of this - :class:`MongoClient` is used. See :mod:`~pymongo.read_preferences` + :class:`AsyncMongoClient` is used. See :mod:`~pymongo.read_preferences` for options. :param write_concern: An instance of :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the - default) the :attr:`write_concern` of this :class:`MongoClient` is + default) the :attr:`write_concern` of this :class:`AsyncMongoClient` is used. :param read_concern: An instance of :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the - default) the :attr:`read_concern` of this :class:`MongoClient` is + default) the :attr:`read_concern` of this :class:`AsyncMongoClient` is used. .. versionchanged:: 3.5 @@ -1346,7 +1346,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): ) def _database_default_options(self, name: str) -> database.AsyncDatabase: - """Get a Database instance with the default settings.""" + """Get a AsyncDatabase instance with the default settings.""" return self.get_database( name, codec_options=DEFAULT_CODEC_OPTIONS, @@ -1426,7 +1426,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): `replicaSet` option. .. versionadded:: 3.0 - MongoClient gained this property in version 3.0. + AsyncMongoClient gained this property in version 3.0. """ return await self._topology.get_primary() # type: ignore[return-value] @@ -1439,7 +1439,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): client was created without the `replicaSet` option. .. versionadded:: 3.0 - MongoClient gained this property in version 3.0. + AsyncMongoClient gained this property in version 3.0. """ return await self._topology.get_secondaries() @@ -1522,7 +1522,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): await self._encrypter.close() async def _get_topology(self) -> Topology: - """Get the internal :class:`~pymongo.topology.Topology` object. + """Get the internal :class:`~pymongo.asynchronous.topology.Topology` object. If this client was created with "connect=False", calling _get_topology launches the connection process in the background. @@ -2074,7 +2074,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Get information about the MongoDB server we're connected to. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. .. versionchanged:: 3.6 Added ``session`` parameter. @@ -2117,7 +2117,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Get a cursor over the databases of the connected server. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. :param kwargs: Optional parameters of the @@ -2127,7 +2127,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): options differ by server version. - :return: An instance of :class:`~pymongo.command_cursor.CommandCursor`. + :return: An instance of :class:`~pymongo.asynchronous.command_cursor.AsyncCommandCursor`. .. versionadded:: 3.6 """ @@ -2141,7 +2141,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Get a list of the names of all databases on the connected server. :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. @@ -2163,13 +2163,13 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): """Drop a database. Raises :class:`TypeError` if `name_or_database` is not an instance of - :class:`str` or :class:`~pymongo.database.Database`. + :class:`str` or :class:`~pymongo.asynchronous.database.AsyncDatabase`. :param name_or_database: the name of a database to drop, or a - :class:`~pymongo.database.Database` instance representing the + :class:`~pymongo.asynchronous.database.AsyncDatabase` instance representing the database to drop :param session: a - :class:`~pymongo.client_session.AsyncClientSession`. + :class:`~pymongo.asynchronous.client_session.AsyncClientSession`. :param comment: A user-provided comment to attach to this command. @@ -2179,7 +2179,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): .. versionchanged:: 3.6 Added ``session`` parameter. - .. note:: The :attr:`~pymongo.mongo_client.MongoClient.write_concern` of + .. note:: The :attr:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.write_concern` of this client is automatically applied to this operation. .. versionchanged:: 3.4 @@ -2192,7 +2192,7 @@ class AsyncMongoClient(common.BaseObject, Generic[_DocumentType]): name = name.name if not isinstance(name, str): - raise TypeError("name_or_database must be an instance of str or a Database") + raise TypeError("name_or_database must be an instance of str or a AsyncDatabase") async with await self._conn_for_writes(session, operation=_Op.DROP_DATABASE) as conn: await self[name]._command( diff --git a/pymongo/synchronous/change_stream.py b/pymongo/synchronous/change_stream.py index f7489249d..a971ad08c 100644 --- a/pymongo/synchronous/change_stream.py +++ b/pymongo/synchronous/change_stream.py @@ -297,8 +297,8 @@ class ChangeStream(Generic[_DocumentType]): try: resume_token = None pipeline = [{'$match': {'operationType': 'insert'}}] - async with db.collection.watch(pipeline) as stream: - async for insert_change in stream: + with db.collection.watch(pipeline) as stream: + for insert_change in stream: print(insert_change) resume_token = stream.resume_token except pymongo.errors.PyMongoError: @@ -312,9 +312,9 @@ class ChangeStream(Generic[_DocumentType]): # Use the interrupted ChangeStream's resume token to create # a new ChangeStream. The new stream will continue from the # last seen insert change without missing any events. - async with db.collection.watch( + with db.collection.watch( pipeline, resume_after=resume_token) as stream: - async for insert_change in stream: + for insert_change in stream: print(insert_change) Raises :exc:`StopIteration` if this ChangeStream is closed. @@ -346,9 +346,9 @@ class ChangeStream(Generic[_DocumentType]): This method returns the next change document without waiting indefinitely for the next change. For example:: - async with db.collection.watch() as stream: + with db.collection.watch() as stream: while stream.alive: - change = await stream.try_next() + change = stream.try_next() # Note that the ChangeStream's resume token may be updated # even when no changes are returned. print("Current resume token: %r" % (stream.resume_token,)) diff --git a/pymongo/synchronous/client_session.py b/pymongo/synchronous/client_session.py index e07298b49..f1d680fc0 100644 --- a/pymongo/synchronous/client_session.py +++ b/pymongo/synchronous/client_session.py @@ -23,11 +23,11 @@ Causally Consistent Reads with client.start_session(causal_consistency=True) as session: collection = client.db.collection - await collection.update_one({"_id": 1}, {"$set": {"x": 10}}, session=session) + collection.update_one({"_id": 1}, {"$set": {"x": 10}}, session=session) secondary_c = collection.with_options(read_preference=ReadPreference.SECONDARY) # A secondary read waits for replication of the write. - await secondary_c.find_one({"_id": 1}, session=session) + secondary_c.find_one({"_id": 1}, session=session) If `causal_consistency` is True (the default), read operations that use the session are causally after previous read and write operations. Using a @@ -54,15 +54,15 @@ operation: orders = client.db.orders inventory = client.db.inventory with client.start_session() as session: - async with session.start_transaction(): - await orders.insert_one({"sku": "abc123", "qty": 100}, session=session) - await inventory.update_one( + with session.start_transaction(): + orders.insert_one({"sku": "abc123", "qty": 100}, session=session) + inventory.update_one( {"sku": "abc123", "qty": {"$gte": 100}}, {"$inc": {"qty": -100}}, session=session, ) -Upon normal completion of ``async with session.start_transaction()`` block, the +Upon normal completion of ``with session.start_transaction()`` block, the transaction automatically calls :meth:`ClientSession.commit_transaction`. If the block exits with an exception, the transaction automatically calls :meth:`ClientSession.abort_transaction`. @@ -114,8 +114,8 @@ replica set secondaries. # Each read using this session reads data from the same point in time. with client.start_session(snapshot=True) as session: - order = await orders.find_one({"sku": "abc123"}, session=session) - inventory = await inventory.find_one({"sku": "abc123"}, session=session) + order = orders.find_one({"sku": "abc123"}, session=session) + inventory = inventory.find_one({"sku": "abc123"}, session=session) Snapshot Reads Limitations ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -609,24 +609,24 @@ class ClientSession: This method starts a transaction on this session, executes ``callback`` once, and then commits the transaction. For example:: - async def callback(session): + def callback(session): orders = session.client.db.orders inventory = session.client.db.inventory - await orders.insert_one({"sku": "abc123", "qty": 100}, session=session) - await inventory.update_one({"sku": "abc123", "qty": {"$gte": 100}}, + orders.insert_one({"sku": "abc123", "qty": 100}, session=session) + inventory.update_one({"sku": "abc123", "qty": {"$gte": 100}}, {"$inc": {"qty": -100}}, session=session) with client.start_session() as session: - await session.with_transaction(callback) + session.with_transaction(callback) To pass arbitrary arguments to the ``callback``, wrap your callable with a ``lambda`` like this:: - async def callback(session, custom_arg, custom_kwarg=None): + def callback(session, custom_arg, custom_kwarg=None): # Transaction operations... with client.start_session() as session: - await session.with_transaction( + session.with_transaction( lambda s: callback(s, "custom_arg", custom_kwarg=1)) In the event of an exception, ``with_transaction`` may retry the commit diff --git a/pymongo/synchronous/collection.py b/pymongo/synchronous/collection.py index 5803e34b2..54db3a56b 100644 --- a/pymongo/synchronous/collection.py +++ b/pymongo/synchronous/collection.py @@ -385,7 +385,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): __iter__ = None def __next__(self) -> NoReturn: - raise TypeError(f"'{type(self).__name__}' object is not iterable") + raise TypeError("'Collection' object is not iterable") next = __next__ @@ -423,19 +423,19 @@ class Collection(common.BaseObject, Generic[_DocumentType]): Performs an aggregation with an implicit initial ``$changeStream`` stage and returns a - :class:`~pymongo.synchronous.change_stream.CollectionChangeStream` cursor which + :class:`~pymongo.change_stream.CollectionChangeStream` cursor which iterates over changes on this collection. .. code-block:: python - async with db.collection.watch() as stream: - async for change in stream: + with db.collection.watch() as stream: + for change in stream: print(change) - The :class:`~pymongo.synchronous.change_stream.CollectionChangeStream` iterable + The :class:`~pymongo.change_stream.CollectionChangeStream` iterable blocks until the next change document is returned or an error is raised. If the - :meth:`~pymongo.synchronous.change_stream.CollectionChangeStream.next` method + :meth:`~pymongo.change_stream.CollectionChangeStream.next` method encounters a network error when retrieving a batch from the server, it will automatically attempt to recreate the cursor such that no change events are missed. Any error encountered during the resume @@ -444,8 +444,8 @@ class Collection(common.BaseObject, Generic[_DocumentType]): .. code-block:: python try: - async with db.collection.watch([{"$match": {"operationType": "insert"}}]) as stream: - async for insert_change in stream: + with db.coll.watch([{"$match": {"operationType": "insert"}}]) as stream: + for insert_change in stream: print(insert_change) except pymongo.errors.PyMongoError: # The ChangeStream encountered an unrecoverable error or the @@ -502,7 +502,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): command. :param show_expanded_events: Include expanded events such as DDL events like `dropIndexes`. - :return: A :class:`~pymongo.synchronous.change_stream.CollectionChangeStream` cursor. + :return: A :class:`~pymongo.change_stream.CollectionChangeStream` cursor. .. versionchanged:: 4.3 Added `show_expanded_events` parameter. @@ -818,12 +818,12 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> InsertOneResult: """Insert a single document. - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 0 - >>> result = await db.test.insert_one({'x': 1}) + >>> result = db.test.insert_one({'x': 1}) >>> result.inserted_id ObjectId('54f112defba522406c9cc208') - >>> await db.test.find_one({'x': 1}) + >>> db.test.find_one({'x': 1}) {'x': 1, '_id': ObjectId('54f112defba522406c9cc208')} :param document: The document to insert. Must be a mutable mapping @@ -884,12 +884,12 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> InsertManyResult: """Insert an iterable of documents. - >>> await db.test.count_documents({}) + >>> db.test.count_documents({}) 0 - >>> result = await db.test.insert_many([{'x': i} for i in range(2)]) - >>> await result.inserted_ids + >>> result = db.test.insert_many([{'x': i} for i in range(2)]) + >>> result.inserted_ids [ObjectId('54f113fffba522406c9cc20e'), ObjectId('54f113fffba522406c9cc20f')] - >>> await db.test.count_documents({}) + >>> db.test.count_documents({}) 2 :param documents: A iterable of documents to insert. @@ -1098,16 +1098,16 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> UpdateResult: """Replace a single document matching the filter. - >>> async for doc in db.test.find({}): + >>> for doc in db.test.find({}): ... print(doc) ... {'x': 1, '_id': ObjectId('54f4c5befba5220aa4d6dee7')} - >>> result = await db.test.replace_one({'x': 1}, {'y': 1}) + >>> result = db.test.replace_one({'x': 1}, {'y': 1}) >>> result.matched_count 1 >>> result.modified_count 1 - >>> async for doc in db.test.find({}): + >>> for doc in db.test.find({}): ... print(doc) ... {'y': 1, '_id': ObjectId('54f4c5befba5220aa4d6dee7')} @@ -1115,14 +1115,14 @@ class Collection(common.BaseObject, Generic[_DocumentType]): The *upsert* option can be used to insert a new document if a matching document does not exist. - >>> result = await db.test.replace_one({'x': 1}, {'x': 1}, True) + >>> result = db.test.replace_one({'x': 1}, {'x': 1}, True) >>> result.matched_count 0 >>> result.modified_count 0 >>> result.upserted_id ObjectId('54f11e5c8891e756a6e1abd4') - >>> await db.test.find_one({'x': 1}) + >>> db.test.find_one({'x': 1}) {'x': 1, '_id': ObjectId('54f11e5c8891e756a6e1abd4')} :param filter: A query that matches the document to replace. @@ -1201,18 +1201,18 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> UpdateResult: """Update a single document matching the filter. - >>> async for doc in db.test.find(): + >>> for doc in db.test.find(): ... print(doc) ... {'x': 1, '_id': 0} {'x': 1, '_id': 1} {'x': 1, '_id': 2} - >>> result = await db.test.update_one({'x': 1}, {'$inc': {'x': 3}}) + >>> result = db.test.update_one({'x': 1}, {'$inc': {'x': 3}}) >>> result.matched_count 1 >>> result.modified_count 1 - >>> async for doc in db.test.find(): + >>> for doc in db.test.find(): ... print(doc) ... {'x': 4, '_id': 0} @@ -1222,14 +1222,14 @@ class Collection(common.BaseObject, Generic[_DocumentType]): If ``upsert=True`` and no documents match the filter, create a new document based on the filter criteria and update modifications. - >>> result = await db.test.update_one({'x': -10}, {'$inc': {'x': 3}}, upsert=True) + >>> result = db.test.update_one({'x': -10}, {'$inc': {'x': 3}}, upsert=True) >>> result.matched_count 0 >>> result.modified_count 0 >>> result.upserted_id ObjectId('626a678eeaa80587d4bb3fb7') - >>> await db.test.find_one(result.upserted_id) + >>> db.test.find_one(result.upserted_id) {'_id': ObjectId('626a678eeaa80587d4bb3fb7'), 'x': -7} :param filter: A query that matches the document to update. @@ -1314,18 +1314,18 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> UpdateResult: """Update one or more documents that match the filter. - >>> async for doc in db.test.find(): + >>> for doc in db.test.find(): ... print(doc) ... {'x': 1, '_id': 0} {'x': 1, '_id': 1} {'x': 1, '_id': 2} - >>> result = await db.test.update_many({'x': 1}, {'$inc': {'x': 3}}) + >>> result = db.test.update_many({'x': 1}, {'$inc': {'x': 3}}) >>> result.matched_count 3 >>> result.modified_count 3 - >>> async for doc in db.test.find(): + >>> for doc in db.test.find(): ... print(doc) ... {'x': 4, '_id': 0} @@ -1417,8 +1417,8 @@ class Collection(common.BaseObject, Generic[_DocumentType]): The following two calls are equivalent: - >>> await db.foo.drop() - >>> await db.drop_collection("foo") + >>> db.foo.drop() + >>> db.drop_collection("foo") .. versionchanged:: 4.2 Added ``encrypted_fields`` parameter. @@ -1550,12 +1550,12 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> DeleteResult: """Delete a single document matching the filter. - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 3 - >>> result = await db.test.delete_one({'x': 1}) + >>> result = db.test.delete_one({'x': 1}) >>> result.deleted_count 1 - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 2 :param filter: A query that matches the document to delete. @@ -1615,12 +1615,12 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> DeleteResult: """Delete one or more documents matching the filter. - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 3 - >>> result = await db.test.delete_many({'x': 1}) + >>> result = db.test.delete_many({'x': 1}) >>> result.deleted_count 3 - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 0 :param filter: A query that matches the documents to delete. @@ -1694,7 +1694,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): :: code-block: python - >>> await collection.find_one(max_time_ms=100) + >>> collection.find_one(max_time_ms=100) """ if filter is not None and not isinstance(filter, abc.Mapping): @@ -1904,8 +1904,8 @@ class Collection(common.BaseObject, Generic[_DocumentType]): :mod:`bson` module. >>> import bson - >>> cursor = await db.test.find_raw_batches() - >>> async for batch in cursor: + >>> cursor = db.test.find_raw_batches() + >>> for batch in cursor: ... print(bson.decode_all(batch)) .. note:: find_raw_batches does not support auto encryption. @@ -2133,7 +2133,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): >>> index1 = IndexModel([("hello", DESCENDING), ... ("world", ASCENDING)], name="hello_world") >>> index2 = IndexModel([("goodbye", DESCENDING)]) - >>> await db.test.create_indexes([index1, index2]) + >>> db.test.create_indexes([index1, index2]) ["hello_world", "goodbye_-1"] :param indexes: A list of :class:`~pymongo.operations.IndexModel` @@ -2232,18 +2232,18 @@ class Collection(common.BaseObject, Generic[_DocumentType]): To create a single key ascending index on the key ``'mike'`` we just use a string argument:: - >>> await my_collection.create_index("mike") + >>> my_collection.create_index("mike") For a compound index on ``'mike'`` descending and ``'eliot'`` ascending we need to use a list of tuples:: - >>> await my_collection.create_index([("mike", pymongo.DESCENDING), + >>> my_collection.create_index([("mike", pymongo.DESCENDING), ... "eliot"]) All optional index creation parameters should be passed as keyword arguments to this method. For example:: - >>> await my_collection.create_index([("mike", pymongo.DESCENDING)], + >>> my_collection.create_index([("mike", pymongo.DESCENDING)], ... background=True) Valid options include, but are not limited to: @@ -2448,7 +2448,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> CommandCursor[MutableMapping[str, Any]]: """Get a cursor over the index documents for this collection. - >>> async for index in db.test.list_indexes(): + >>> for index in db.test.list_indexes(): ... print(index) ... SON([('v', 2), ('key', SON([('_id', 1)])), ('name', '_id_')]) @@ -2957,9 +2957,9 @@ class Collection(common.BaseObject, Generic[_DocumentType]): :mod:`bson` module. >>> import bson - >>> cursor = await db.test.aggregate_raw_batches([ + >>> cursor = db.test.aggregate_raw_batches([ ... {'$project': {'x': {'$multiply': [2, '$x']}}}]) - >>> async for batch in cursor: + >>> for batch in cursor: ... print(bson.decode_all(batch)) .. note:: aggregate_raw_batches does not support auto encryption. @@ -3217,28 +3217,28 @@ class Collection(common.BaseObject, Generic[_DocumentType]): ) -> _DocumentType: """Finds a single document and deletes it, returning the document. - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 2 - >>> await db.test.find_one_and_delete({'x': 1}) + >>> db.test.find_one_and_delete({'x': 1}) {'x': 1, '_id': ObjectId('54f4e12bfba5220aa4d6dee8')} - >>> await db.test.count_documents({'x': 1}) + >>> db.test.count_documents({'x': 1}) 1 If multiple documents match *filter*, a *sort* can be applied. - >>> async for doc in db.test.find({'x': 1}): + >>> for doc in db.test.find({'x': 1}): ... print(doc) ... {'x': 1, '_id': 0} {'x': 1, '_id': 1} {'x': 1, '_id': 2} - >>> await db.test.find_one_and_delete( + >>> db.test.find_one_and_delete( ... {'x': 1}, sort=[('_id', pymongo.DESCENDING)]) {'x': 1, '_id': 2} The *projection* option can be used to limit the fields returned. - >>> await db.test.find_one_and_delete({'x': 1}, projection={'_id': False}) + >>> db.test.find_one_and_delete({'x': 1}, projection={'_id': False}) {'x': 1} :param filter: A query that matches the document to delete. @@ -3314,15 +3314,15 @@ class Collection(common.BaseObject, Generic[_DocumentType]): :meth:`find_one_and_update` by replacing the document matched by *filter*, rather than modifying the existing document. - >>> async for doc in db.test.find({}): + >>> for doc in db.test.find({}): ... print(doc) ... {'x': 1, '_id': 0} {'x': 1, '_id': 1} {'x': 1, '_id': 2} - >>> await db.test.find_one_and_replace({'x': 1}, {'y': 1}) + >>> db.test.find_one_and_replace({'x': 1}, {'y': 1}) {'x': 1, '_id': 0} - >>> async for doc in db.test.find({}): + >>> for doc in db.test.find({}): ... print(doc) ... {'y': 1, '_id': 0} @@ -3418,13 +3418,13 @@ class Collection(common.BaseObject, Generic[_DocumentType]): """Finds a single document and updates it, returning either the original or the updated document. - >>> await db.test.find_one_and_update( + >>> db.test.find_one_and_update( ... {'_id': 665}, {'$inc': {'count': 1}, '$set': {'done': True}}) {'_id': 665, 'done': False, 'count': 25}} Returns ``None`` if no document matches the filter. - >>> await db.test.find_one_and_update( + >>> db.test.find_one_and_update( ... {'_exists': False}, {'$inc': {'count': 1}}) When the filter matches, by default :meth:`find_one_and_update` @@ -3434,7 +3434,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): option. >>> from pymongo import ReturnDocument - >>> await db.example.find_one_and_update( + >>> db.example.find_one_and_update( ... {'_id': 'userid'}, ... {'$inc': {'seq': 1}}, ... return_document=ReturnDocument.AFTER) @@ -3442,7 +3442,7 @@ class Collection(common.BaseObject, Generic[_DocumentType]): You can limit the fields returned with the *projection* option. - >>> await db.example.find_one_and_update( + >>> db.example.find_one_and_update( ... {'_id': 'userid'}, ... {'$inc': {'seq': 1}}, ... projection={'seq': True, '_id': False}, @@ -3452,9 +3452,9 @@ class Collection(common.BaseObject, Generic[_DocumentType]): The *upsert* option can be used to create the document if it doesn't already exist. - >>> await db.example.delete_many({}).deleted_count + >>> (db.example.delete_many({})).deleted_count 1 - >>> await db.example.find_one_and_update( + >>> db.example.find_one_and_update( ... {'_id': 'userid'}, ... {'$inc': {'seq': 1}}, ... projection={'seq': True, '_id': False}, @@ -3464,12 +3464,12 @@ class Collection(common.BaseObject, Generic[_DocumentType]): If multiple documents match *filter*, a *sort* can be applied. - >>> async for doc in db.test.find({'done': True}): + >>> for doc in db.test.find({'done': True}): ... print(doc) ... {'_id': 665, 'done': True, 'result': {'count': 26}} {'_id': 701, 'done': True, 'result': {'count': 17}} - >>> await db.test.find_one_and_update( + >>> db.test.find_one_and_update( ... {'done': True}, ... {'$set': {'final': True}}, ... sort=[('_id', pymongo.DESCENDING)]) diff --git a/pymongo/synchronous/command_cursor.py b/pymongo/synchronous/command_cursor.py index 1cd4d8694..86fa69dcb 100644 --- a/pymongo/synchronous/command_cursor.py +++ b/pymongo/synchronous/command_cursor.py @@ -164,7 +164,7 @@ class CommandCursor(Generic[_DocumentType]): Even if :attr:`alive` is ``True``, :meth:`next` can raise :exc:`StopIteration`. Best to use a for loop:: - async for doc in collection.aggregate(pipeline): + for doc in collection.aggregate(pipeline): print(doc) .. note:: :attr:`alive` can be True while iterating a cursor from @@ -382,11 +382,11 @@ class CommandCursor(Generic[_DocumentType]): self.close() def to_list(self) -> list[_DocumentType]: - """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``. + """Converts the contents of this cursor to a list more efficiently than ``[doc for doc in cursor]``. To use:: - >>> await cursor.to_list() + >>> cursor.to_list() If the cursor is empty or has no more results, an empty list will be returned. diff --git a/pymongo/synchronous/cursor.py b/pymongo/synchronous/cursor.py index 652af606c..1595ce40b 100644 --- a/pymongo/synchronous/cursor.py +++ b/pymongo/synchronous/cursor.py @@ -527,7 +527,7 @@ class Cursor(Generic[_DocumentType]): 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_shared.CursorType.TAILABLE_AWAIT` cursor. For all other + :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 @@ -712,27 +712,27 @@ class Cursor(Generic[_DocumentType]): Pass a field name and a direction, either :data:`~pymongo.ASCENDING` or :data:`~pymongo.DESCENDING`.:: - async for doc in collection.find().sort('field', pymongo.ASCENDING): + 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:: - async for doc in collection.find().sort([ + for doc in collection.find().sort([ 'field1', ('field2', pymongo.DESCENDING)]): print(doc) Text search results can be sorted by relevance:: - cursor = await db.test.find( + cursor = db.test.find( {'$text': {'$search': 'some words'}}, {'score': {'$meta': 'textScore'}}) # Sort by 'score' field. cursor.sort([('score', {'$meta': 'textScore'})]) - async for doc in cursor: + for doc in cursor: print(doc) For more advanced text search functionality, see MongoDB's @@ -831,7 +831,7 @@ class Cursor(Generic[_DocumentType]): to the object currently being scanned. For example:: # Find all documents where field "a" is less than "b" plus "c". - async for doc in db.test.find().where('this.a < (this.b + this.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 @@ -904,7 +904,7 @@ class Cursor(Generic[_DocumentType]): With regular cursors, simply use a for loop instead of :attr:`alive`:: - async for doc in collection.find(): + for doc in collection.find(): print(doc) .. note:: Even if :attr:`alive` is True, :meth:`next` can raise @@ -1285,11 +1285,11 @@ class Cursor(Generic[_DocumentType]): self.close() def to_list(self) -> list[_DocumentType]: - """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``. + """Converts the contents of this cursor to a list more efficiently than ``[doc for doc in cursor]``. To use:: - >>> await cursor.to_list() + >>> cursor.to_list() If the cursor is empty or has no more results, an empty list will be returned. diff --git a/pymongo/synchronous/database.py b/pymongo/synchronous/database.py index 3b3a91095..93a998528 100644 --- a/pymongo/synchronous/database.py +++ b/pymongo/synchronous/database.py @@ -337,21 +337,21 @@ class Database(common.BaseObject, Generic[_DocumentType]): Performs an aggregation with an implicit initial ``$changeStream`` stage and returns a - :class:`~pymongo.synchronous.change_stream.DatabaseChangeStream` cursor which + :class:`~pymongo.change_stream.DatabaseChangeStream` cursor which iterates over changes on all collections in this database. Introduced in MongoDB 4.0. .. code-block:: python - async with db.watch() as stream: - async for change in stream: + with db.watch() as stream: + for change in stream: print(change) - The :class:`~pymongo.synchronous.change_stream.DatabaseChangeStream` iterable + The :class:`~pymongo.change_stream.DatabaseChangeStream` iterable blocks until the next change document is returned or an error is raised. If the - :meth:`~pymongo.synchronous.change_stream.DatabaseChangeStream.next` method + :meth:`~pymongo.change_stream.DatabaseChangeStream.next` method encounters a network error when retrieving a batch from the server, it will automatically attempt to recreate the cursor such that no change events are missed. Any error encountered during the resume @@ -360,8 +360,8 @@ class Database(common.BaseObject, Generic[_DocumentType]): .. code-block:: python try: - async with db.watch([{"$match": {"operationType": "insert"}}]) as stream: - async for insert_change in stream: + with db.watch([{"$match": {"operationType": "insert"}}]) as stream: + for insert_change in stream: print(insert_change) except pymongo.errors.PyMongoError: # The ChangeStream encountered an unrecoverable error or the @@ -409,7 +409,7 @@ class Database(common.BaseObject, Generic[_DocumentType]): command. :param show_expanded_events: Include expanded events such as DDL events like `dropIndexes`. - :return: A :class:`~pymongo.synchronous.change_stream.DatabaseChangeStream` cursor. + :return: A :class:`~pymongo.change_stream.DatabaseChangeStream` cursor. .. versionchanged:: 4.3 Added `show_expanded_events` parameter. @@ -810,23 +810,23 @@ class Database(common.BaseObject, Generic[_DocumentType]): For example, a command like ``{buildinfo: 1}`` can be sent using: - >>> await db.command("buildinfo") + >>> db.command("buildinfo") OR - >>> await db.command({"buildinfo": 1}) + >>> db.command({"buildinfo": 1}) For a command where the value matters, like ``{count: collection_name}`` we can do: - >>> await db.command("count", collection_name) + >>> db.command("count", collection_name) OR - >>> await db.command({"count": collection_name}) + >>> db.command({"count": collection_name}) For commands that take additional arguments we can use kwargs. So ``{count: collection_name, query: query}`` becomes: - >>> await db.command("count", collection_name, query=query) + >>> db.command("count", collection_name, query=query) OR - >>> await db.command({"count": collection_name, "query": query}) + >>> db.command({"count": collection_name, "query": query}) :param command: document representing the command to be issued, or the name of the command (for simple commands only). diff --git a/test/asynchronous/test_database.py b/test/asynchronous/test_database.py index 0d848458d..c20a74d3d 100644 --- a/test/asynchronous/test_database.py +++ b/test/asynchronous/test_database.py @@ -116,10 +116,10 @@ class TestDatabaseNoConnect(unittest.TestCase): with self.assertRaises(TypeError): _ = db[0] # next fails - with self.assertRaisesRegex(TypeError, "'Database' object is not iterable"): + with self.assertRaisesRegex(TypeError, "'AsyncDatabase' object is not iterable"): _ = next(db) # .next() fails - with self.assertRaisesRegex(TypeError, "'Database' object is not iterable"): + with self.assertRaisesRegex(TypeError, "'AsyncDatabase' object is not iterable"): _ = db.next() # Do not implement typing.Iterable. self.assertNotIsInstance(db, Iterable) diff --git a/test/test_cursor.py b/test/test_cursor.py index 12cb0cd57..26f0575da 100644 --- a/test/test_cursor.py +++ b/test/test_cursor.py @@ -232,7 +232,7 @@ class TestCursor(IntegrationTest): listener = AllowListEventListener("find", "getMore") coll = (rs_or_single_client(event_listeners=[listener]))[self.db.name].pymongo_test - # Tailable_await defaults. + # Tailable_defaults. coll.find(cursor_type=CursorType.TAILABLE_AWAIT).to_list() # find self.assertFalse("maxTimeMS" in listener.started_events[0].command) @@ -240,7 +240,7 @@ class TestCursor(IntegrationTest): self.assertFalse("maxTimeMS" in listener.started_events[1].command) listener.reset() - # Tailable_await with max_await_time_ms set. + # Tailable_with max_await_time_ms set. coll.find(cursor_type=CursorType.TAILABLE_AWAIT).max_await_time_ms(99).to_list() # find self.assertEqual("find", listener.started_events[0].command_name) @@ -251,7 +251,7 @@ class TestCursor(IntegrationTest): self.assertEqual(99, listener.started_events[1].command["maxTimeMS"]) listener.reset() - # Tailable_await with max_time_ms and make sure list() works on synchronous cursors + # Tailable_with max_time_ms and make sure list() works on synchronous cursors if _IS_SYNC: list(coll.find(cursor_type=CursorType.TAILABLE_AWAIT).max_time_ms(99)) # type: ignore[call-overload] else: @@ -265,7 +265,7 @@ class TestCursor(IntegrationTest): self.assertFalse("maxTimeMS" in listener.started_events[1].command) listener.reset() - # Tailable_await with both max_time_ms and max_await_time_ms + # Tailable_with both max_time_ms and max_await_time_ms ( coll.find(cursor_type=CursorType.TAILABLE_AWAIT) .max_time_ms(99) diff --git a/tools/synchro.py b/tools/synchro.py index 94f3d7f8f..57b089c5a 100644 --- a/tools/synchro.py +++ b/tools/synchro.py @@ -272,15 +272,26 @@ def translate_docstrings(lines: list[str]) -> list[str]: # This sequence of replacements fixes the grammar issues caused by translating async -> sync if "an Async" in lines[i]: lines[i] = lines[i].replace("an Async", "a Async") + if "an 'Async" in lines[i]: + lines[i] = lines[i].replace("an 'Async", "a 'Async") if "An Async" in lines[i]: lines[i] = lines[i].replace("An Async", "A Async") + if "An 'Async" in lines[i]: + lines[i] = lines[i].replace("An 'Async", "A 'Async") if "an asynchronous" in lines[i]: lines[i] = lines[i].replace("an asynchronous", "a") if "An asynchronous" in lines[i]: lines[i] = lines[i].replace("An asynchronous", "A") + # This ensures docstring links are for `pymongo.X` instead of `pymongo.synchronous.X` + if "pymongo.asynchronous" in lines[i] and "import" not in lines[i]: + lines[i] = lines[i].replace("pymongo.asynchronous", "pymongo") lines[i] = lines[i].replace(k, replacements[k]) if "Sync" in lines[i] and "Synchronous" not in lines[i] and replacements[k] in lines[i]: lines[i] = lines[i].replace("Sync", "") + if "async for" in lines[i] or "async with" in lines[i] or "async def" in lines[i]: + lines[i] = lines[i].replace("async ", "") + if "await " in lines[i] and "tailable" not in lines[i]: + lines[i] = lines[i].replace("await ", "") for i in range(len(lines)): for k in docstring_replacements: # type: ignore[assignment] if f":param {k[1]}: **Not supported by {k[0]}**." in lines[i]: