From 1d8676ae0a117cac110cda11d9eda3d914e7854a Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 18 Sep 2024 12:36:16 -0400 Subject: [PATCH 1/4] Beta docs update --- doc/api/pymongo/asynchronous/change_stream.rst | 5 +++++ doc/api/pymongo/asynchronous/client_session.rst | 5 +++++ doc/api/pymongo/asynchronous/collection.rst | 5 +++++ doc/api/pymongo/asynchronous/command_cursor.rst | 5 +++++ doc/api/pymongo/asynchronous/cursor.rst | 5 +++++ doc/api/pymongo/asynchronous/database.rst | 5 +++++ doc/api/pymongo/asynchronous/index.rst | 5 +++++ doc/api/pymongo/asynchronous/mongo_client.rst | 5 +++++ doc/changelog.rst | 3 ++- 9 files changed, 42 insertions(+), 1 deletion(-) diff --git a/doc/api/pymongo/asynchronous/change_stream.rst b/doc/api/pymongo/asynchronous/change_stream.rst index 2ba0feb5c7..3d750d3907 100644 --- a/doc/api/pymongo/asynchronous/change_stream.rst +++ b/doc/api/pymongo/asynchronous/change_stream.rst @@ -1,5 +1,10 @@ :mod:`change_stream` -- Watch changes on a collection, database, or cluster =========================================================================== +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.change_stream :members: diff --git a/doc/api/pymongo/asynchronous/client_session.rst b/doc/api/pymongo/asynchronous/client_session.rst index 1e74e1be70..fd31840f5d 100644 --- a/doc/api/pymongo/asynchronous/client_session.rst +++ b/doc/api/pymongo/asynchronous/client_session.rst @@ -1,5 +1,10 @@ :mod:`client_session` -- Logical sessions for sequential operations =================================================================== +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.client_session :members: diff --git a/doc/api/pymongo/asynchronous/collection.rst b/doc/api/pymongo/asynchronous/collection.rst index 779557ff65..9899eaf7e4 100644 --- a/doc/api/pymongo/asynchronous/collection.rst +++ b/doc/api/pymongo/asynchronous/collection.rst @@ -1,6 +1,11 @@ :mod:`collection` -- Collection level operations ================================================ +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.collection :synopsis: Collection level operations diff --git a/doc/api/pymongo/asynchronous/command_cursor.rst b/doc/api/pymongo/asynchronous/command_cursor.rst index 41a8f617e1..5a409b1e9c 100644 --- a/doc/api/pymongo/asynchronous/command_cursor.rst +++ b/doc/api/pymongo/asynchronous/command_cursor.rst @@ -1,6 +1,11 @@ :mod:`command_cursor` -- Tools for iterating over MongoDB command results ========================================================================= +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.command_cursor :synopsis: Tools for iterating over MongoDB command results :members: diff --git a/doc/api/pymongo/asynchronous/cursor.rst b/doc/api/pymongo/asynchronous/cursor.rst index ff7103c013..a622c928bb 100644 --- a/doc/api/pymongo/asynchronous/cursor.rst +++ b/doc/api/pymongo/asynchronous/cursor.rst @@ -1,6 +1,11 @@ :mod:`cursor` -- Tools for iterating over MongoDB query results =============================================================== +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.cursor :synopsis: Tools for iterating over MongoDB query results diff --git a/doc/api/pymongo/asynchronous/database.rst b/doc/api/pymongo/asynchronous/database.rst index afd6959c9a..6e9864c180 100644 --- a/doc/api/pymongo/asynchronous/database.rst +++ b/doc/api/pymongo/asynchronous/database.rst @@ -1,6 +1,11 @@ :mod:`database` -- Database level operations ============================================ +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.database :synopsis: Database level operations diff --git a/doc/api/pymongo/asynchronous/index.rst b/doc/api/pymongo/asynchronous/index.rst index 25dfac6323..6a4e1abb7d 100644 --- a/doc/api/pymongo/asynchronous/index.rst +++ b/doc/api/pymongo/asynchronous/index.rst @@ -1,6 +1,11 @@ :mod:`pymongo async` -- Async Python driver for MongoDB ======================================================= +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous :synopsis: Asynchronous Python driver for MongoDB diff --git a/doc/api/pymongo/asynchronous/mongo_client.rst b/doc/api/pymongo/asynchronous/mongo_client.rst index 75952f1b6d..943a54e15d 100644 --- a/doc/api/pymongo/asynchronous/mongo_client.rst +++ b/doc/api/pymongo/asynchronous/mongo_client.rst @@ -1,6 +1,11 @@ :mod:`mongo_client` -- Tools for connecting to MongoDB ====================================================== +.. warning:: This API is currently in beta, meaning the classes, methods, + and behaviors described within may change before the full release. + If you come across any bugs during your use of this API, + please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + .. automodule:: pymongo.asynchronous.mongo_client :synopsis: Tools for connecting to MongoDB diff --git a/doc/changelog.rst b/doc/changelog.rst index 69fbb6f8fd..3a5000f861 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -11,7 +11,8 @@ PyMongo 4.9 brings a number of improvements including: - Added support for MongoDB 8.0. - Added support for Python 3.13. -- A new asynchronous API with full asyncio support. +- A new beta asynchronous API with full asyncio support. + This new asynchronous API is a work-in-progress that may change during the beta period before the full release. - Added support for In-Use Encryption range queries with MongoDB 8.0. Added :attr:`~pymongo.encryption.Algorithm.RANGE`. ``sparsity`` and ``trim_factor`` are now optional in :class:`~pymongo.encryption_options.RangeOpts`. From 9a89f88f7129edd395c73f1b39df6de66e278599 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 18 Sep 2024 13:50:40 -0400 Subject: [PATCH 2/4] Add AsyncMongoClient beta docstring --- pymongo/asynchronous/mongo_client.py | 2 ++ tools/synchro.py | 11 ++++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/pymongo/asynchronous/mongo_client.py b/pymongo/asynchronous/mongo_client.py index 6d0e5d5280..814c604562 100644 --- a/pymongo/asynchronous/mongo_client.py +++ b/pymongo/asynchronous/mongo_client.py @@ -177,6 +177,8 @@ def __init__( For more details, see the relevant section of the PyMongo 4.x migration guide: :ref:`pymongo4-migration-direct-connection`. + .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. + The client object is thread-safe and has connection-pooling built in. If an operation fails because of a network error, :class:`~pymongo.errors.ConnectionFailure` is raised and the client diff --git a/tools/synchro.py b/tools/synchro.py index fdf3a05c95..59d6e653e5 100644 --- a/tools/synchro.py +++ b/tools/synchro.py @@ -119,6 +119,10 @@ be passed as options for the create collection command.""", } +docstring_removals: set[str] = { + ".. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release." +} + type_replacements = {"_Condition": "threading.Condition"} import_replacements = {"test.synchronous": "test"} @@ -322,7 +326,12 @@ def translate_docstrings(lines: list[str]) -> list[str]: docstring_replacements[k], # type: ignore[index] ) - return lines + for line in docstring_removals: + if line in lines[i]: + lines[i] = "DOCSTRING_REMOVED" + lines[i + 1] = "DOCSTRING_REMOVED" + + return [line for line in lines if line != "DOCSTRING_REMOVED"] def unasync_directory(files: list[str], src: str, dest: str, replacements: dict[str, str]) -> None: From 790bfe2eafd075fefdc134d09f4f583ccf5013cf Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 18 Sep 2024 14:56:06 -0400 Subject: [PATCH 3/4] Add Motor compatibility warning to changelog --- doc/changelog.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/changelog.rst b/doc/changelog.rst index 3a5000f861..dfb3c79827 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -7,6 +7,12 @@ Changes in Version 4.9.0 .. warning:: Driver support for MongoDB 3.6 reached end of life in April 2024. PyMongo 4.9 will be the last release to support MongoDB 3.6. +.. warning:: PyMongo 4.9 refactors a large portion of internal APIs to support the new asynchronous API beta. + As a result, versions of Motor older than 3.6 are not compatible with PyMongo 4.9. + Existing users of these versions must either upgrade to Motor 3.6 and PyMongo 4.9, + or cap their PyMongo version to ``< 4.9``. + Any applications that use private APIs may also break as a result of these internal changes. + PyMongo 4.9 brings a number of improvements including: - Added support for MongoDB 8.0. From e3044c0100bf5315615fff2e7cc853592be5d728 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 18 Sep 2024 16:08:22 -0400 Subject: [PATCH 4/4] http -> https links --- doc/api/pymongo/asynchronous/change_stream.rst | 2 +- doc/api/pymongo/asynchronous/client_session.rst | 2 +- doc/api/pymongo/asynchronous/collection.rst | 2 +- doc/api/pymongo/asynchronous/command_cursor.rst | 2 +- doc/api/pymongo/asynchronous/cursor.rst | 2 +- doc/api/pymongo/asynchronous/database.rst | 2 +- doc/api/pymongo/asynchronous/index.rst | 2 +- doc/api/pymongo/asynchronous/mongo_client.rst | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/api/pymongo/asynchronous/change_stream.rst b/doc/api/pymongo/asynchronous/change_stream.rst index 3d750d3907..df4f5dee41 100644 --- a/doc/api/pymongo/asynchronous/change_stream.rst +++ b/doc/api/pymongo/asynchronous/change_stream.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.change_stream :members: diff --git a/doc/api/pymongo/asynchronous/client_session.rst b/doc/api/pymongo/asynchronous/client_session.rst index fd31840f5d..c4bbd8edd2 100644 --- a/doc/api/pymongo/asynchronous/client_session.rst +++ b/doc/api/pymongo/asynchronous/client_session.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.client_session :members: diff --git a/doc/api/pymongo/asynchronous/collection.rst b/doc/api/pymongo/asynchronous/collection.rst index 9899eaf7e4..ce1fe3ca04 100644 --- a/doc/api/pymongo/asynchronous/collection.rst +++ b/doc/api/pymongo/asynchronous/collection.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.collection :synopsis: Collection level operations diff --git a/doc/api/pymongo/asynchronous/command_cursor.rst b/doc/api/pymongo/asynchronous/command_cursor.rst index 5a409b1e9c..7058563eee 100644 --- a/doc/api/pymongo/asynchronous/command_cursor.rst +++ b/doc/api/pymongo/asynchronous/command_cursor.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.command_cursor :synopsis: Tools for iterating over MongoDB command results diff --git a/doc/api/pymongo/asynchronous/cursor.rst b/doc/api/pymongo/asynchronous/cursor.rst index a622c928bb..d357b84514 100644 --- a/doc/api/pymongo/asynchronous/cursor.rst +++ b/doc/api/pymongo/asynchronous/cursor.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.cursor :synopsis: Tools for iterating over MongoDB query results diff --git a/doc/api/pymongo/asynchronous/database.rst b/doc/api/pymongo/asynchronous/database.rst index 6e9864c180..b45fe457e7 100644 --- a/doc/api/pymongo/asynchronous/database.rst +++ b/doc/api/pymongo/asynchronous/database.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.database :synopsis: Database level operations diff --git a/doc/api/pymongo/asynchronous/index.rst b/doc/api/pymongo/asynchronous/index.rst index 6a4e1abb7d..1b41fb8222 100644 --- a/doc/api/pymongo/asynchronous/index.rst +++ b/doc/api/pymongo/asynchronous/index.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous :synopsis: Asynchronous Python driver for MongoDB diff --git a/doc/api/pymongo/asynchronous/mongo_client.rst b/doc/api/pymongo/asynchronous/mongo_client.rst index 943a54e15d..d0729da78b 100644 --- a/doc/api/pymongo/asynchronous/mongo_client.rst +++ b/doc/api/pymongo/asynchronous/mongo_client.rst @@ -4,7 +4,7 @@ .. warning:: This API is currently in beta, meaning the classes, methods, and behaviors described within may change before the full release. If you come across any bugs during your use of this API, - please file a Jira ticket in the "Python Driver" project at http://jira.mongodb.org/browse/PYTHON. + please file a Jira ticket in the "Python Driver" project at https://jira.mongodb.org/browse/PYTHON. .. automodule:: pymongo.asynchronous.mongo_client :synopsis: Tools for connecting to MongoDB