mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PYTHON-4592 - Synchronize inline examples and docstrings (#1756)

Browse Source
This commit is contained in:
Noah Stapp 2024-08-02 12:02:28 -07:00 committed by GitHub
parent 294f10b724
commit f7da1172cb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
18 changed files with 396 additions and 385 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
pymongo/asynchronous/aggregation.py
View File

@ -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__(

38
pymongo/asynchronous/change_stream.py
View File

@ -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 <https://mongodb.com/docs/manual/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
"""

22
pymongo/asynchronous/client_session.py
View File

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

184
pymongo/asynchronous/collection.py
View File

@ -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.

4
pymongo/asynchronous/command_cursor.py
View File

@ -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 <https://dochub.mongodb.org/core/cursors>`_.

40
pymongo/asynchronous/cursor.py
View File

@ -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 <https://dochub.mongodb.org/core/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
<https://mongodb.com/docs/manual/reference/command/explain/>`_,
``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 <https://dochub.mongodb.org/core/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 <https://dochub.mongodb.org/core/cursors>`_.

56
pymongo/asynchronous/database.py
View File

@ -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

4
pymongo/asynchronous/encryption.py
View File

@ -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

186
pymongo/asynchronous/mongo_client.py
View File

@ -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 </examples/copydb>` 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(

12
pymongo/synchronous/change_stream.py
View File

@ -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,))

28
pymongo/synchronous/client_session.py
View File

@ -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

128
pymongo/synchronous/collection.py
View File

@ -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)])

6
pymongo/synchronous/command_cursor.py
View File

@ -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.

18
pymongo/synchronous/cursor.py
View File

@ -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.

28
pymongo/synchronous/database.py
View File

@ -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).

4
test/asynchronous/test_database.py
View File

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

8
test/test_cursor.py
View File

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

11
tools/synchro.py
View File

@ -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]: