diff --git a/doc/changelog.rst b/doc/changelog.rst index ec01e3e9..efa7b4fd 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -241,8 +241,8 @@ Breaking Changes - Comparing two :class:`~motor.motor_tornado.MotorClient` instances now uses a set of immutable properties rather than :attr:`~motor.motor_tornado.MotorClient.address` which can change. -- Removed the ``disable_md5`` parameter for :class:`~gridfs.GridFSBucket` and - :class:`~gridfs.GridFS`. See :ref:`removed-gridfs-checksum` for details. +- Removed the ``disable_md5`` parameter for :class:`~pymongo.GridFSBucket` and + :class:`~pymongo.GridFS`. See :ref:`removed-gridfs-checksum` for details. - PyMongoCrypt 1.2.0 or later is now required for client side field level encryption support. @@ -711,7 +711,7 @@ Highlights include: - Unicode aware string comparison using collations. - :class:`MotorCursor` and :class:`MotorGridOutCursor` have a new attribute :meth:`~MotorCursor.collation`. - - Support for the new :class:`~bson.decimal128.Decimal128` BSON type. + - Support for the new :class:`~pymongo.decimal128.Decimal128` BSON type. - A new maxStalenessSeconds read preference option. - A username is no longer required for the MONGODB-X509 authentication mechanism when connected to MongoDB >= 3.4. @@ -741,8 +741,8 @@ Highlights include: - TLS compression is now explicitly disabled when possible. - The Server Name Indication (SNI) TLS extension is used when possible. - PyMongo's ``bson`` module provides finer control over JSON encoding/decoding - with :class:`~bson.json_util.JSONOptions`. -- Allow :class:`~bson.code.Code` objects to have a scope of ``None``, + with :class:`~pymongo.json_util.JSONOptions`. +- Allow :class:`~pymongo.code.Code` objects to have a scope of ``None``, signifying no scope. Also allow encoding Code objects with an empty scope (i.e. ``{}``). @@ -862,9 +862,9 @@ The following find/find_one options have been removed: - await_data (use the new ``cursor_type`` option instead) - exhaust (use the new ``cursor_type`` option instead) - as_class (use :meth:`~motor.motor_tornado.MotorCollection.with_options` with - :class:`~bson.codec_options.CodecOptions` instead) + :class:`~pymongo.codec_options.CodecOptions` instead) - compile_re (BSON regular expressions are always decoded to - :class:`~bson.regex.Regex`) + :class:`~pymongo.regex.Regex`) The following find/find_one options are deprecated: diff --git a/doc/conf.py b/doc/conf.py index 664c3a12..bbc90206 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -224,8 +224,6 @@ pymongo_version = metadata("pymongo")["version"] pymongo_inventory = ("https://pymongo.readthedocs.io/en/%s/" % pymongo_version, None) intersphinx_mapping = { - "bson": pymongo_inventory, - "gridfs": pymongo_inventory, "pymongo": pymongo_inventory, "aiohttp": ("http://aiohttp.readthedocs.io/en/stable/", None), "tornado": ("http://www.tornadoweb.org/en/stable/", None), diff --git a/doc/differences.rst b/doc/differences.rst index 131ea31e..87985a0f 100644 --- a/doc/differences.rst +++ b/doc/differences.rst @@ -49,8 +49,8 @@ GridFS - File-like - PyMongo's :class:`~gridfs.grid_file.GridIn` and - :class:`~gridfs.grid_file.GridOut` strive to act like Python's built-in + PyMongo's :class:`~pymongo.grid_file.GridIn` and + :class:`~pymongo.grid_file.GridOut` strive to act like Python's built-in file objects, so they can be passed to many functions that expect files. But the I/O methods of :class:`MotorGridIn` and :class:`MotorGridOut` are asynchronous, so they cannot obey the @@ -59,7 +59,7 @@ GridFS - Setting properties In PyMongo, you can set arbitrary attributes on - a :class:`~gridfs.grid_file.GridIn` and they're stored as metadata on + a :class:`~pymongo.grid_file.GridIn` and they're stored as metadata on the server, even after the ``GridIn`` is closed:: fs = gridfs.GridFSBucket(db) diff --git a/doc/examples/type_hints.rst b/doc/examples/type_hints.rst index 4c486f2f..77f864c3 100644 --- a/doc/examples/type_hints.rst +++ b/doc/examples/type_hints.rst @@ -74,7 +74,7 @@ Typed Client :class:`~motor.motor_asyncio.AsyncIOMotorClient` is generic on the document type used to decode BSON documents. -You can specify a :class:`~bson.raw_bson.RawBSONDocument` document type: +You can specify a :class:`~pymongo.raw_bson.RawBSONDocument` document type: .. code-block:: python @@ -89,7 +89,7 @@ You can specify a :class:`~bson.raw_bson.RawBSONDocument` document type: result = await collection.find_one({"x": 1}) assert isinstance(result, RawBSONDocument) -Subclasses of :py:class:`collections.abc.Mapping` can also be used, such as :class:`~bson.son.SON`: +Subclasses of :py:class:`collections.abc.Mapping` can also be used, such as :class:`~pymongo.son.SON`: .. code-block:: python @@ -105,7 +105,7 @@ Subclasses of :py:class:`collections.abc.Mapping` can also be used, such as :cla assert result is not None assert result["x"] == 1 -Note that when using :class:`~bson.son.SON`, the key and value types must be given, e.g. ``SON[str, Any]``. +Note that when using :class:`~pymongo.son.SON`, the key and value types must be given, e.g. ``SON[str, Any]``. Typed Collection @@ -260,7 +260,7 @@ match a well-defined schema using :py:class:`~typing.TypedDict`. Typed Command ------------- -When using the :meth:`~motor.motor_asyncio.AsyncIOMotorDatabase.command`, you can specify the document type by providing a custom :class:`~bson.codec_options.CodecOptions`: +When using the :meth:`~motor.motor_asyncio.AsyncIOMotorDatabase.command`, you can specify the document type by providing a custom :class:`~pymongo.codec_options.CodecOptions`: .. code-block:: python @@ -280,7 +280,7 @@ For :py:class:`~typing.TypedDict`, use the form: ``options: CodecOptions[MyTyped Typed BSON Decoding ------------------- -You can specify the document type returned by :mod:`bson` decoding functions by providing :class:`~bson.codec_options.CodecOptions`: +You can specify the document type returned by :mod:`bson` decoding functions by providing :class:`~pymongo.codec_options.CodecOptions`: .. code-block:: python @@ -302,7 +302,7 @@ You can specify the document type returned by :mod:`bson` decoding functions by rt_document = decode(bsonbytes, codec_options=options) assert rt_document.foo() == "bar" -:class:`~bson.raw_bson.RawBSONDocument` and :py:class:`~typing.TypedDict` are also supported. +:class:`~pymongo.raw_bson.RawBSONDocument` and :py:class:`~typing.TypedDict` are also supported. For :py:class:`~typing.TypedDict`, use the form: ``options: CodecOptions[MyTypedDict] = CodecOptions(...)``. @@ -363,7 +363,7 @@ Other times ``mypy`` will catch an actual error, like the following code: In this case the solution is to use ``insert_one({})``, passing a document instead of a list. -Another example is trying to set a value on a :class:`~bson.raw_bson.RawBSONDocument`, which is read-only.: +Another example is trying to set a value on a :class:`~pymongo.raw_bson.RawBSONDocument`, which is read-only.: .. code-block:: python diff --git a/doc/migrate-to-motor-3.rst b/doc/migrate-to-motor-3.rst index f4930467..61396a25 100644 --- a/doc/migrate-to-motor-3.rst +++ b/doc/migrate-to-motor-3.rst @@ -186,7 +186,7 @@ can be changed to this:: ``tz_aware`` defaults to ``False`` .................................. -``tz_aware``, an argument for :class:`~bson.json_util.JSONOptions`, +``tz_aware``, an argument for :class:`~pymongo.json_util.JSONOptions`, now defaults to ``False`` instead of ``True``. ``json_util.loads`` now decodes datetime as naive by default. @@ -416,8 +416,8 @@ documents in your own code before passing them to PyMongo, and transform incoming documents after receiving them from PyMongo. Alternatively, if your application uses the ``SONManipulator`` API to convert -custom types to BSON, the :class:`~bson.codec_options.TypeCodec` and -:class:`~bson.codec_options.TypeRegistry` APIs may be a suitable alternative. +custom types to BSON, the :class:`~pymongo.codec_options.TypeCodec` and +:class:`~pymongo.codec_options.TypeRegistry` APIs may be a suitable alternative. For more information, see the `Custom Types documentation`_. .. _Custom Types documentation: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/ @@ -454,8 +454,8 @@ Removed features with no migration path Encoding a UUID raises an error by default .......................................... -The default uuid_representation for :class:`~bson.codec_options.CodecOptions`, -:class:`~bson.json_util.JSONOptions`, and +The default uuid_representation for :class:`~pymongo.codec_options.CodecOptions`, +:class:`~pymongo.json_util.JSONOptions`, and :class:`~motor.motor_tornado.MotorClient` has been changed from :data:`bson.binary.UuidRepresentation.PYTHON_LEGACY` to :data:`bson.binary.UuidRepresentation.UNSPECIFIED`. Attempting to encode a diff --git a/motor/core.py b/motor/core.py index cc3c500a..81c18d73 100644 --- a/motor/core.py +++ b/motor/core.py @@ -242,7 +242,7 @@ class AgnosticClient(AgnosticBaseProperties): to use for the aggregation. - `start_at_operation_time` (optional): If provided, the resulting change stream will only return changes that occurred at or after - the specified :class:`~bson.timestamp.Timestamp`. Requires + the specified :class:`~pymongo.timestamp.Timestamp`. Requires MongoDB >= 4.0. - `session` (optional): a :class:`~pymongo.client_session.ClientSession`. @@ -708,7 +708,7 @@ class AgnosticDatabase(AgnosticBaseProperties): to use for the aggregation. - `start_at_operation_time` (optional): If provided, the resulting change stream will only return changes that occurred at or after - the specified :class:`~bson.timestamp.Timestamp`. Requires + the specified :class:`~pymongo.timestamp.Timestamp`. Requires MongoDB >= 4.0. - `session` (optional): a :class:`~pymongo.client_session.ClientSession`. @@ -786,7 +786,7 @@ class AgnosticDatabase(AgnosticBaseProperties): .. note:: the order of keys in the `command` document is significant (the "verb" must come first), so commands which require multiple keys (e.g. `findandmodify`) - should use an instance of :class:`~bson.son.SON` or + should use an instance of :class:`~pymongo.son.SON` or a string and kwargs instead of a Python `dict`. - `value` (optional): value to use for the command verb when @@ -797,7 +797,7 @@ class AgnosticDatabase(AgnosticBaseProperties): read preference configured for the transaction. Otherwise, defaults to :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`. - - `codec_options`: A :class:`~bson.codec_options.CodecOptions` + - `codec_options`: A :class:`~pymongo.codec_options.CodecOptions` instance. - `session` (optional): A :class:`MotorClientSession`. diff --git a/motor/docstrings.py b/motor/docstrings.py index 66ee4fda..cb09dc94 100644 --- a/motor/docstrings.py +++ b/motor/docstrings.py @@ -31,7 +31,7 @@ read preference, and/or write concern from this :class:`MotorClient`. :Parameters: - `name`: The name of the database - a string. - `codec_options` (optional): An instance of - :class:`~bson.codec_options.CodecOptions`. If ``None`` (the + :class:`~pymongo.codec_options.CodecOptions`. If ``None`` (the default) the :attr:`codec_options` of this :class:`MotorClient` is used. - `read_preference` (optional): The read preference to use. If @@ -66,7 +66,7 @@ based only on the URI in a configuration file. - `default` (optional): the database name to use if no database name was provided in the URI. - `codec_options` (optional): An instance of - :class:`~bson.codec_options.CodecOptions`. If ``None`` (the + :class:`~pymongo.codec_options.CodecOptions`. If ``None`` (the default) the :attr:`codec_options` of this :class:`MotorClient` is used. - `read_preference` (optional): The read preference to use. If @@ -344,7 +344,7 @@ kwargs. So ``{count: collection_name, query: query}`` becomes:: .. note:: the order of keys in the `command` document is significant (the "verb" must come first), so commands which require multiple keys (e.g. `findandmodify`) - should use an instance of :class:`~bson.son.SON` or + should use an instance of :class:`~pymongo.son.SON` or a string and kwargs instead of a Python :class:`dict`. - `value` (optional): value to use for the command verb when @@ -890,7 +890,7 @@ response from the server to the `map reduce command`_. - `reduce`: reduce function (as a JavaScript string) - `out`: output collection name or `out object` (dict). See the `map reduce command`_ documentation for available options. - Note: `out` options are order sensitive. :class:`~bson.son.SON` + Note: `out` options are order sensitive. :class:`~pymongo.son.SON` can be used to specify multiple options. e.g. SON([('replace', ), ('db', )]) - `full_response` (optional): if ``True``, return full response to @@ -1277,7 +1277,7 @@ started it. where_doc = """Adds a `$where`_ clause to this query. The `code` argument must be an instance of :class:`str` -:class:`~bson.code.Code` containing a JavaScript expression. +:class:`~pymongo.code.Code` containing a JavaScript expression. This expression will be evaluated for each document scanned. Only those documents for which the expression evaluates to *true* will be returned as results. The keyword *this* refers to the object @@ -1293,7 +1293,7 @@ if this :class:`~motor.motor_tornado.MotorCursor` has already been used. Only the last call to :meth:`where` applied to a :class:`~motor.motor_tornado.MotorCursor` has any effect. -.. note:: MongoDB 4.4 drops support for :class:`~bson.code.Code` +.. note:: MongoDB 4.4 drops support for :class:`~pymongo.code.Code` with scope variables. Consider using `$expr`_ instead. :Parameters: @@ -1337,7 +1337,7 @@ gridfs_delete_doc = """Delete a file's metadata and data chunks from a GridFS bu b"data I want to store!") await fs.delete(file_id) - Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists. + Raises :exc:`~pymongo.errors.NoFile` if no file with file_id exists. :Parameters: - `file_id`: The _id of the file to be deleted. @@ -1361,7 +1361,7 @@ gridfs_download_to_stream_doc = """Downloads the contents of the stored file spe file.seek(0) contents = file.read() - Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists. + Raises :exc:`~pymongo.errors.NoFile` if no file with file_id exists. :Parameters: - `file_id`: The _id of the file to be downloaded. @@ -1383,7 +1383,7 @@ gridfs_download_to_stream_by_name_doc = """ Write the contents of `filename file = open('myfile','wb') await fs.download_to_stream_by_name("test_file", file) - Raises :exc:`~gridfs.errors.NoFile` if no such version of + Raises :exc:`~pymongo.errors.NoFile` if no such version of that file exists. Raises :exc:`~ValueError` if `filename` is not a string. @@ -1419,7 +1419,7 @@ gridfs_open_download_stream_doc = """Opens a stream to read the contents of the grid_out = await fs.open_download_stream(file_id) contents = await grid_out.read() - Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists. + Raises :exc:`~pymongo.errors.NoFile` if no file with file_id exists. :Parameters: - `file_id`: The _id of the file to be downloaded. @@ -1441,7 +1441,7 @@ gridfs_open_download_stream_by_name_doc = """Opens a stream to read the contents grid_out = await fs.open_download_stream_by_name(file_id) contents = await grid_out.read() - Raises :exc:`~gridfs.errors.NoFile` if no such version of + Raises :exc:`~pymongo.errors.NoFile` if no such version of that file exists. Raises :exc:`~ValueError` filename is not a string. @@ -1484,7 +1484,7 @@ gridfs_open_upload_stream_doc = """Opens a stream for writing. Returns an instance of :class:`AsyncIOMotorGridIn`. - Raises :exc:`~gridfs.errors.NoFile` if no such version of + Raises :exc:`~pymongo.errors.NoFile` if no such version of that file exists. Raises :exc:`~ValueError` if `filename` is not a string. @@ -1528,7 +1528,7 @@ gridfs_open_upload_stream_with_id_doc = """Opens a stream for writing. Returns an instance of :class:`AsyncIOMotorGridIn`. - Raises :exc:`~gridfs.errors.NoFile` if no such version of + Raises :exc:`~pymongo.errors.NoFile` if no such version of that file exists. Raises :exc:`~ValueError` if `filename` is not a string. @@ -1560,7 +1560,7 @@ gridfs_rename_doc = """Renames the stored file with the specified file_id. await fs.rename(file_id, "new_test_name") - Raises :exc:`~gridfs.errors.NoFile` if no file with file_id exists. + Raises :exc:`~pymongo.errors.NoFile` if no file with file_id exists. :Parameters: - `file_id`: The _id of the file to be renamed. @@ -1581,7 +1581,7 @@ gridfs_upload_from_stream_doc = """Uploads a user file to a GridFS bucket. b"data I want to store!", metadata={"contentType": "text/plain"}) - Raises :exc:`~gridfs.errors.NoFile` if no such version of + Raises :exc:`~pymongo.errors.NoFile` if no such version of that file exists. Raises :exc:`~ValueError` if `filename` is not a string. @@ -1616,7 +1616,7 @@ gridfs_upload_from_stream_with_id_doc = """Uploads a user file to a GridFS bucke b"data I want to store!", metadata={"contentType": "text/plain"}) - Raises :exc:`~gridfs.errors.NoFile` if no such version of + Raises :exc:`~pymongo.errors.NoFile` if no such version of that file exists. Raises :exc:`~ValueError` if `filename` is not a string. diff --git a/motor/motor_gridfs.py b/motor/motor_gridfs.py index d4c8bc8b..8abac713 100644 --- a/motor/motor_gridfs.py +++ b/motor/motor_gridfs.py @@ -73,7 +73,7 @@ class AgnosticGridOut: """Class to read data out of GridFS. MotorGridOut supports the same attributes as PyMongo's - :class:`~gridfs.grid_file.GridOut`, such as ``_id``, ``content_type``, + :class:`~pymongo.grid_file.GridOut`, such as ``_id``, ``content_type``, etc. You don't need to instantiate this class directly - use the @@ -255,7 +255,7 @@ Metadata set on the file appears as attributes on a arguments include: - ``"_id"``: unique ID for this file (default: - :class:`~bson.objectid.ObjectId`) - this ``"_id"`` must + :class:`~pymongo.objectid.ObjectId`) - this ``"_id"`` must not have already been used for another file - ``"filename"``: human name for the file diff --git a/requirements/docs.txt b/requirements/docs.txt index fcad0e35..456fba07 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,6 +1,6 @@ tornado aiohttp -sphinx>=5.3,<8 +sphinx>=5.3,<9 sphinx_rtd_theme>=2,<4 readthedocs-sphinx-search~=0.3 furo==2025.9.25