Skip to content

Commit 335eb40

Browse files
mongoKartmongoKart
authored
DOCSP-38412 - Connect Usage Examples (#71)
1 parent c79f01c commit 335eb40

20 files changed

+451
-230
lines changed

‎source/connect.txt‎

Lines changed: 211 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,19 @@
44
Connect to MongoDB
55
==================
66

7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
717
.. meta::
8-
:description: Learn how to use (+driver-short+} to connect to from MongoDB.
18+
:description: Learn how to use {+driver-short+} to connect to MongoDB.
19+
:keywords: client, ssl
920

1021
.. toctree::
1122
:titlesonly:
@@ -17,8 +28,202 @@ Connect to MongoDB
1728
/connect/stable-api
1829
/connect/csot
1930

20-
- :ref:`pymongo-tls`
21-
- :ref:`pymongo-network-compression`
22-
- :ref:`pymongo-server-selection`
23-
- :ref:`pymongo-stable-api`
24-
- :ref:`pymongo-csot`
31+
Overview
32+
--------
33+
34+
This page contains code examples that show how to connect your Python application
35+
to MongoDB with various settings.
36+
37+
.. tip::
38+
39+
To learn more about the connection options on this page, see the link
40+
provided in each section.
41+
42+
To use a connection example from this page, copy the code example into the
43+
:ref:`sample application <pymongo-connect-sample>` or your own application.
44+
Be sure to replace all placeholders in the code examples, such as ``<hostname>``, with
45+
the relevant values for your MongoDB deployment.
46+
47+
.. _pymongo-connect-sample:
48+
49+
.. include:: /includes/usage-examples/sample-app-intro.rst
50+
51+
.. literalinclude:: /includes/usage-examples/connect-sample-app.py
52+
:language: python
53+
:copyable: true
54+
:linenos:
55+
:emphasize-lines: 5-7
56+
57+
Transport Layer Security (TLS)
58+
------------------------------
59+
60+
Enable TLS
61+
~~~~~~~~~~
62+
63+
.. include:: /includes/connect/tls-tabs.rst
64+
65+
To learn more about enabling TLS, see :ref:`pymongo-enable-tls` in
66+
the TLS configuration guide.
67+
68+
Specify a Certificate Authority (CA) File
69+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70+
71+
.. include:: /includes/connect/ca-file-tabs.rst
72+
73+
To learn more about specifying a CA file, see :ref:`pymongo-specify-ca-file` in
74+
the TLS configuration guide.
75+
76+
Disable OCSP Checks
77+
~~~~~~~~~~~~~~~~~~~
78+
79+
.. include:: /includes/connect/ocsp-tabs.rst
80+
81+
To learn more about disabling OCSP checks, see :ref:`pymongo-disable-ocsp` in
82+
the TLS configuration guide.
83+
84+
Specify a Certificate Revocation List (CRL)
85+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
86+
87+
.. include:: /includes/connect/crl-tabs.rst
88+
89+
To learn more about specifying a CRL, see :ref:`pymongo-crl` in
90+
the TLS configuration guide.
91+
92+
Present a Client Certificate
93+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94+
95+
.. include:: /includes/connect/client-cert-tabs.rst
96+
97+
To learn more about specifying a client certificate, see :ref:`pymongo-client-cert` in
98+
the TLS configuration guide.
99+
100+
Provide a Certificate Key File Password
101+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102+
103+
.. include:: /includes/connect/key-file-password.rst
104+
105+
To learn more about providing a key file password, see :ref:`pymongo-key-file-password` in
106+
the TLS configuration guide.
107+
108+
Allow Insecure TLS
109+
~~~~~~~~~~~~~~~~~~
110+
111+
.. include:: /includes/connect/insecure-tls-tabs.rst
112+
113+
To learn more about allowing insecure TLS, see :ref:`pymongo-insecure-tls` in
114+
the TLS configuration guide.
115+
116+
Disable Certificate Validation
117+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118+
119+
.. include:: /includes/connect/disable-cert-validation-tabs.rst
120+
121+
To learn more about disabling certificate validation, see :ref:`pymongo-insecure-tls` in
122+
the TLS configuration guide.
123+
124+
Disable Hostname Verification
125+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126+
127+
.. include:: /includes/connect/disable-host-verification-tabs.rst
128+
129+
To learn more about disabling hostname verification, see :ref:`pymongo-insecure-tls` in
130+
the TLS configuration guide.
131+
132+
Network Compression
133+
-------------------
134+
135+
Compression Algorithms
136+
~~~~~~~~~~~~~~~~~~~~~~
137+
138+
.. include:: /includes/connect/compression-tabs.rst
139+
140+
To learn more about specifying compression algorithms, see
141+
:ref:`pymongo-enable-compression` in the Network Compression guide.
142+
143+
zlib Compression Level
144+
~~~~~~~~~~~~~~~~~~~~~~
145+
146+
.. tabs::
147+
148+
.. tab:: MongoClient
149+
:tabid: mongoclient
150+
151+
.. code-block:: python
152+
153+
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname>:<port>",
154+
compressors = "zlib",
155+
zlibCompressionLevel=<zlib compression level>)
156+
157+
.. tab:: Connection String
158+
:tabid: connectionstring
159+
160+
.. code-block:: python
161+
162+
uri = ("mongodb://<username>:<password>@<hostname>:<port>/?"
163+
"compressors=zlib"
164+
"zlibCompressionLevel=<zlib compression level>")
165+
client = pymongo.MongoClient(uri)
166+
167+
To learn more about setting the zlib compression level, see
168+
:ref:`pymongo-enable-compression` in the Network Compression guide.
169+
170+
Server Selection
171+
----------------
172+
173+
.. code-block:: python
174+
175+
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname>:<port>",
176+
server_selector=<selector function>)
177+
178+
To learn more about customizing server selection, see
179+
:ref:`pymongo-server-selection`.
180+
181+
{+stable-api+}
182+
--------------
183+
184+
.. code-block:: python
185+
:emphasize-lines: 4
186+
187+
from pymongo.server_api import ServerApi
188+
189+
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname:<port>",
190+
server_api=ServerApi("<{+stable-api+} version>"))
191+
192+
To learn more about the {+stable-api+}, see :ref:`pymongo-stable-api`.
193+
194+
Limit Server Execution Time
195+
---------------------------
196+
197+
timeout Block
198+
~~~~~~~~~~~~~
199+
200+
.. code-block:: python
201+
202+
with pymongo.timeout(<timeout length>):
203+
# perform operations here
204+
205+
To learn more about client-side timeouts, see :ref:`pymongo-csot`.
206+
207+
timeoutMS Connection Option
208+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
209+
210+
.. tabs::
211+
212+
.. tab:: MongoClient
213+
:tabid: mongoclient
214+
215+
.. code-block:: python
216+
217+
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname@:<port>",
218+
timeoutMS=<timeout length>)
219+
220+
.. tab:: Connection String
221+
:tabid: connectionstring
222+
223+
.. code-block:: python
224+
225+
uri = "mongodb://<username>:<password>@<hostname:<port>/?timeoutMS=<timeout length>"
226+
client = pymongo.MongoClient(uri)
227+
228+
To learn more about client-side timeouts, see :ref:`pymongo-csot`.
229+

‎source/connect/csot.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ The following code examples use the ``timeoutMS`` option to specify a timeout of
136136
.. code-block:: python
137137
:emphasize-lines: 2
138138

139-
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname@:<port>",
139+
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname:<port>",
140140
timeoutMS=10000)
141141

142142
.. tab:: Connection String
@@ -145,7 +145,7 @@ The following code examples use the ``timeoutMS`` option to specify a timeout of
145145
.. code-block:: python
146146
:emphasize-lines: 1
147147

148-
uri = "mongodb://<username>:<password>@<hostname@:<port>/?timeoutMS=10000"
148+
uri = "mongodb://<username>:<password>@<hostname:<port>/?timeoutMS=10000"
149149
client = pymongo.MongoClient(uri)
150150

151151
If you specify the ``timeoutMS`` option, {+driver-short+} automatically applies the

‎source/connect/network-compression.txt‎

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -52,26 +52,7 @@ You can do this in two ways:
5252

5353
The following code example shows both options:
5454

55-
.. tabs::
56-
57-
.. tab:: MongoClient
58-
:tabid: mongoclient
59-
60-
.. code-block:: python
61-
:emphasize-lines: 2
62-
63-
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname>:<port>",
64-
compressors = "snappy,zstd,zlib")
65-
66-
.. tab:: Connection String
67-
:tabid: connectionstring
68-
69-
.. code-block:: python
70-
:emphasize-lines: 2
71-
72-
uri = ("mongodb://<username>:<password>@<hostname>:<port>/?"
73-
"compressors=snappy,zstd,zlib")
74-
client = pymongo.MongoClient(uri)
55+
.. include:: /includes/connect/compression-tabs.rst
7556

7657
Set the zlib Compression Level
7758
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎source/connect/server-selection.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,8 @@ constructor and pass the ``server_selector`` argument with your function name as
121121

122122
.. code-block:: python
123123

124-
client = MongoClient(server_selector=prefer_local)
124+
client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname>:<port>",
125+
server_selector=prefer_local)
125126

126127
API Documentation
127128
-----------------

‎source/connect/stable-api.txt‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -48,13 +48,16 @@ To enable the {+stable-api+}, perform the following steps:
4848
#. Construct a ``MongoClient`` object, passing in your ``ServerApi`` object for the
4949
``server_api`` argument.
5050

51-
The following code example shows how to perform this process:
51+
The following code example shows how to specify {+stable-api+} version 1:
5252

53-
.. literalinclude:: /includes/connect/stable_api.py
54-
:start-after: # start stable api
55-
:end-before: # end stable api
56-
:language: python
57-
:dedent:
53+
.. code-block:: python
54+
:emphasize-lines: 5
55+
56+
from pymongo import MongoClient
57+
from pymongo.server_api import ServerApi
58+
59+
client = MongoClient("mongodb://<username>:<password>@<hostname:<port>",
60+
server_api=ServerApi("1"))
5861

5962
Once you create a ``MongoClient`` instance with
6063
a specified API version, all commands you run with the client use the specified
@@ -92,11 +95,16 @@ parameters to customize the behavior of the {+stable-api+}.
9295
The following code example shows how you can use these parameters when constructing a
9396
``ServerApi`` object:
9497

95-
.. literalinclude:: /includes/connect/stable_api.py
96-
:start-after: # start stable api options
97-
:end-before: # end stable api options
98-
:language: python
99-
:dedent:
98+
.. code-block:: python
99+
:emphasize-lines: 5-7
100+
101+
from pymongo import MongoClient
102+
from pymongo.server_api import ServerApi
103+
104+
client = MongoClient("mongodb://<username>:<password>@<hostname:<port>",
105+
server_api=ServerApi("1",
106+
strict=True,
107+
deprecation_errors=True))
100108

101109
Troubleshooting
102110
---------------

0 commit comments

Comments
 (0)