Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCSP-48161: Async examples for Connect pages #236

Merged
merged 5 commits into from
Mar 24, 2025
Merged

DOCSP-48161: Async examples for Connect pages #236

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fe6f7de
DOCSP-48161: Async examples for Connect pages
mcmorisi Mar 21, 2025
0a1f666
Fix
mcmorisi Mar 21, 2025
92a88c0
RR feedback
mcmorisi Mar 21, 2025
fbc4ade
Fix
mcmorisi Mar 21, 2025
9f3f89d
NS feedback
mcmorisi Mar 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 178 additions & 26 deletions source/connect.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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`.

Expand All @@ -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>):
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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`.
44 changes: 36 additions & 8 deletions source/connect/connection-options.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
------------------
Expand Down
Loading
Loading