DOCSP-48161: Async examples for Connect pages (#236)

Author: mcmorisi

source/connect.txt

@@ -46,43 +46,118 @@ the relevant values for your MongoDB deployment.
 
 .. include:: /includes/usage-examples/sample-app-intro.rst
 
-.. literalinclude:: /includes/usage-examples/connect-sample-app.py
-   :language: python
-   :copyable: true
-   :linenos:
-   :emphasize-lines: 4-6
+Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding
+code:
+
+.. tabs::
+
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. literalinclude:: /includes/usage-examples/connect-sample-app.py
+         :language: python
+         :copyable: true
+         :linenos:
+         :emphasize-lines: 4-6
+
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. literalinclude:: /includes/usage-examples/connect-sample-app-async.py
+         :language: python
+         :copyable: true
+         :linenos:
+         :emphasize-lines: 6-8
 
 Connection
 ----------
 
+The following sections describe how to connect to different targets, such as a local
+instance of MongoDB or a cloud-hosted instance on Atlas.
+
 Local Deployment
 ~~~~~~~~~~~~~~~~
 
-.. code-block:: python
+The following code shows how to connect  the connection string to connect to a local
+MongoDB deployment. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to 
+see the corresponding code:
 
-   uri = "mongodb://localhost:27017/"
-   client = MongoClient(uri)
+.. tabs::
+
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         uri = "mongodb://localhost:27017/"
+         client = MongoClient(uri)
+
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. code-block:: python
+
+         uri = "mongodb://localhost:27017/"
+         client = AsyncMongoClient(uri)
 
 Atlas
 ~~~~~
 
-.. code-block:: python
+The following code shows the connection string to connect to a deployment hosted on
+Atlas. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the
+corresponding code:
 
-   uri = "<Atlas connection string>"
-   client = MongoClient(uri, server_api=pymongo.server_api.ServerApi(
-    version="1", strict=True, deprecation_errors=True))
+.. tabs::
+
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         uri = "<Atlas connection string>"
+         client = MongoClient(uri, server_api=pymongo.server_api.ServerApi(
+            version="1", strict=True, deprecation_errors=True))
+
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. code-block:: python
+
+         uri = "<Atlas connection string>"
+         client = AsyncMongoClient(uri, server_api=pymongo.server_api.ServerApi(
+            version="1", strict=True, deprecation_errors=True))
 
 Replica Set
 ~~~~~~~~~~~
 
-.. code-block:: python
+The following code shows the connection string to connect to a replica set. Select the
+:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding
+code:
+
+.. tabs::
+
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
+         client = MongoClient(uri)
 
-   uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
-   client = MongoClient(uri)
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. code-block:: python
+
+         uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
+         client = AsyncMongoClient(uri)
 
 Network Compression
 -------------------
 
+The following sections describe how to connect to MongoDB while specifying network
+compression algorithms.
+
 Compression Algorithms
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -94,6 +169,8 @@ To learn more about specifying compression algorithms, see
 zlib Compression Level
 ~~~~~~~~~~~~~~~~~~~~~~
 
+The following tabs demonstrate how to specify a compression level for the ``zlib`` compressor:
+
 .. tabs::
 
    .. tab:: MongoClient
@@ -102,8 +179,8 @@ zlib Compression Level
       .. code-block:: python
 
          client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
-                                      compressors = "zlib",
-                                      zlibCompressionLevel=<zlib compression level>)
+            compressors = "zlib",
+            zlibCompressionLevel=<zlib compression level>)
 
    .. tab:: Connection String
       :tabid: connectionstring
@@ -115,29 +192,84 @@ zlib Compression Level
                 "zlibCompressionLevel=<zlib compression level>")
          client = pymongo.MongoClient(uri)
 
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+            compressors = "zlib",
+            zlibCompressionLevel=<zlib compression level>)
+
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
+
+      .. code-block:: python
+
+         uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
+            "compressors=zlib"
+            "zlibCompressionLevel=<zlib compression level>")
+         client = pymongo.AsyncMongoClient(uri)
+
 To learn more about setting the zlib compression level, see
 :ref:`pymongo-enable-compression` in the Network Compression guide.
 
 Server Selection
 ----------------
 
-.. code-block:: python
+The following code shows a connection string that specifies a server selection function.
+Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding
+code:
 
-   client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
-                                server_selector=<selector function>)
+.. tabs::
+
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+            server_selector=<selector function>)
+
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
+            server_selector=<selector function>)
 
 To learn more about customizing server selection, see
 :ref:`pymongo-server-selection`.
 
 {+stable-api+}
 --------------
 
-.. code-block:: python
+The following code shows how to specify {+stable-api+} settings for a connection.Select the
+:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding
+code:
 
-   from pymongo.server_api import ServerApi
+.. tabs::
 
-   client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
-                                server_api=ServerApi("<{+stable-api+} version>"))
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         from pymongo.server_api import ServerApi
+
+         client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
+            server_api=ServerApi("<{+stable-api+} version>"))
+
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. code-block:: python
+
+         from pymongo.server_api import ServerApi
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
+            server_api=ServerApi("<{+stable-api+} version>"))
 
 To learn more about the {+stable-api+}, see :ref:`pymongo-stable-api`.
 
@@ -147,6 +279,8 @@ Limit Server Execution Time
 timeout Block
 ~~~~~~~~~~~~~
 
+The following code shows how to set a client-side timeout by using the ``timeout()`` method:
+
 .. code-block:: python
 
    with pymongo.timeout(<timeout length>):
@@ -157,6 +291,9 @@ To learn more about client-side timeouts, see :ref:`pymongo-csot`.
 timeoutMS Connection Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The following tabs demonstrate how to set a client-side timeout by using the ``timeoutMS``
+connection option:
+
 .. tabs::
 
    .. tab:: MongoClient
@@ -165,7 +302,7 @@ timeoutMS Connection Option
       .. code-block:: python
 
          client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname@:<port>",
-                                      timeoutMS=<timeout length>)
+            timeoutMS=<timeout length>)
 
    .. tab:: Connection String
       :tabid: connectionstring
@@ -175,5 +312,20 @@ timeoutMS Connection Option
          uri = "mongodb://<db_username>:<db_password>@<hostname:<port>/?timeoutMS=<timeout length>"
          client = pymongo.MongoClient(uri)
 
-To learn more about client-side timeouts, see :ref:`pymongo-csot`.
+   .. tab:: MongoClient (Asynchronous)
+      :tabid: mongoclient-async
+
+      .. code-block:: python
+
+         client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname@:<port>",
+            timeoutMS=<timeout length>)
+
+   .. tab:: Connection String (Asynchronous)
+      :tabid: connectionstring-async
 
+      .. code-block:: python
+
+         uri = "mongodb://<db_username>:<db_password>@<hostname:<port>/?timeoutMS=<timeout length>"
+         client = pymongo.AsyncMongoClient(uri)
+
+To learn more about client-side timeouts, see :ref:`pymongo-csot`.

source/connect/connection-options.txt

@@ -42,12 +42,26 @@ Using the Connection URI
 If you pass a connection URI to the ``MongoClient`` constructor, you can include
 connection options in the string as ``<name>=<value>`` pairs. In the following example,
 the connection URI contains the ``connectTimeoutMS`` option with a value of ``60000``
-and the ``tls`` option with a value of ``true``:
+and the ``tls`` option with a value of ``true``. Select the :guilabel:`Synchronous` or
+:guilabel:`Asynchronous` tab to see the corresponding code:
 
-.. code-block:: python
+.. tabs::
 
-   uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
-   client = pymongo.MongoClient(uri)
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
+         client = pymongo.MongoClient(uri)
+   
+   .. tab:: Asynchronous
+      :tabid: async
+
+      .. code-block:: python
+
+         uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
+         client = pymongo.AsyncMongoClient(uri)
 
 .. _pymongo-mongo-client-settings:
 
@@ -59,12 +73,26 @@ instead of including them in your connection URI.
 Configuring the connection this way makes it easier to
 change settings at runtime and helps you catch errors during compilation.
 The following example shows how to use the ``MongoClient`` constructor to set
-connection options:
+connection options. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to
+see the corresponding code:
+
+.. tabs::
+
+   .. tab:: Synchronous
+      :tabid: sync
+
+      .. code-block:: python
+
+         uri = "mongodb://<hostname>:<port>"
+         client = pymongo.MongoClient(uri, connectTimeoutMS=60000, tls=True)
+   
+   .. tab:: Asynchronous
+      :tabid: async
 
-.. code-block:: python
+      .. code-block:: python
 
-   uri = "mongodb://<hostname>:<port>"
-   client = pymongo.MongoClient(uri, connectTimeoutMS=60000, tls=True)
+         uri = "mongodb://<hostname>:<port>"
+         client = pymongo.AsyncMongoClient(uri, connectTimeoutMS=60000, tls=True)
 
 Connection Options
 ------------------