PYTHON-4773 - Async PyMongo Beta docs update (#1868)

NoahStapp · web-flow · commit d0772f21619a · 2024-09-18T17:09:20.000-05:00
diff --git 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 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
@@ -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 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
@@ -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 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
@@ -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 https://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
@@ -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 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
@@ -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 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
@@ -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 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
@@ -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 https://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
@@ -7,11 +7,18 @@ 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.
 - 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`.
diff --git 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
@@ -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:
