@@ -119,7 +119,7 @@ constructor accepts. All parameters are optional.
119
119
:wikipedia:`round-robin DNS <Round-robin_DNS>` addresses.
120
120
121
121
**Data type:** ``Union[str, Sequence[str]]``
122
- **Default value:** ``"localhost"``
122
+ | **Default value:** ``"localhost"``
123
123
124
124
* - ``port``
125
125
- The port number {+mdb-server+} is running on.
@@ -128,17 +128,35 @@ constructor accepts. All parameters are optional.
128
128
instead of using this parameter.
129
129
130
130
**Data type:** ``int``
131
- **Default value:** ``27017``
131
+ | **Default value:** ``27017``
132
132
133
133
* - ``document_class``
134
134
- The default class that the client uses to decode BSON documents returned by queries.
135
- This parameter supports the ``bson.raw_bson.RawBSONDocument`` type, as well as
136
- subclasses of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``.
135
+ This parameter accepts the following types:
137
136
138
- If you specify ``bson.son.SON`` as the document class, you must also specify types
139
- for the key and value.
137
+ - ``bson.raw_bson.RawBSONDocument``. To learn more about the ``RawBSONDocument`` class,
138
+ see :ref:`pymongo-bson-raw`.
139
+
140
+ - A subclass of the ``collections.abc.Mapping`` type, such as ``OrderedDict``.
141
+ Depending on the strictness of your type-checking rules, you might also need to
142
+ specify types for the key and value, as shown in the following example:
143
+
144
+ .. code-block:: python
145
+
146
+ client = MongoClient(document_class=OrderedDict[str, int])
147
+
148
+ - A subclass of the ``TypedDict`` type. To pass a ``TypedDict`` subclass for this
149
+ parameter, you must also include the class in a type hint for your ``MongoClient``
150
+ object, as shown in the following example:
151
+
152
+ .. code-block:: python
153
+
154
+ client: MongoClient[MyTypedDict] = MongoClient()
155
+
156
+ .. include:: /includes/type-hints/typeddict-availability.rst
140
157
141
158
**Data type:** ``Type[_DocumentType]``
159
+ **Default:** ``dict``
142
160
143
161
* - ``tz_aware``
144
162
- If this parameter is ``True``, the client treats ``datetime`` values as aware.
@@ -168,6 +186,11 @@ constructor accepts. All parameters are optional.
168
186
169
187
**Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__
170
188
189
+ You can also pass keyword arguments to the ``MongoClient()`` constructor to specify
190
+ optional parameters. For a complete list of keyword arguments, see the
191
+ `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
192
+ class in the API documentation.
193
+
171
194
Concurrent Execution
172
195
--------------------
173
196
@@ -226,28 +249,46 @@ To use multiprocessing with {+driver-short+}, write code similar to the followin
226
249
Do not copy an instance of the ``MongoClient`` class from the parent process to a child
227
250
process.
228
251
229
- Type Hints
252
+ .. _pymongo-type-hints-client:
253
+
254
+ Type Hints
230
255
----------
231
256
232
- If you're using Python v3.5 or later, you can add type hints to your Python code.
257
+ .. include:: /includes/ type- hints/intro.rst
233
258
234
- The following code example shows how to declare a type hint for a ``MongoClient``
235
- object:
259
+ To use type hints in your {+driver-short+} application, you must add a type annotation to your
260
+ ``MongoClient`` object, as shown in the following example :
236
261
237
262
.. code-block:: python
238
263
239
264
client: MongoClient = MongoClient()
240
265
241
- In the previous example, the code doesn't specify a type for the documents that the
242
- ``MongoClient`` object will work with. To specify a document type,
243
- include the ``Dict[str, Any]`` type when you
244
- create the ``MongoClient`` object, as shown in the following example:
266
+ For more accurate type information, you can include the generic document type
267
+ ``Dict[str, Any]`` in your type annotation. This data type matches all documents in MongoDB.
268
+ The following example shows how to include this data type in your type annotation:
245
269
246
270
.. code-block:: python
247
271
248
272
from typing import Any, Dict
249
273
client: MongoClient[Dict[str, Any]] = MongoClient()
250
274
275
+ If all the documents that you are working with correspond to a single custom type, you
276
+ can specify the custom type as a type hint for your ``MongoClient`` object. This
277
+ provides more accurate type information than the generic ``Dict[str, Any]`` type.
278
+
279
+ The following example shows how to specify the ``Movie`` type as a type hint for a
280
+ ``MongoClient`` object:
281
+
282
+ .. code-block:: python
283
+
284
+ from typing import TypedDict
285
+
286
+ class Movie(TypedDict):
287
+ name: str
288
+ year: int
289
+
290
+ client: MongoClient[Movie] = MongoClient()
291
+
251
292
Troubleshooting
252
293
---------------
253
294
@@ -312,10 +353,14 @@ process.
312
353
multithreaded contexts with ``fork()``, see `Issue 6721 <http://bugs.python.org/issue6721>`__
313
354
in the Python Issue Tracker.
314
355
356
+ .. include:: /includes/type-hints/troubleshooting-client-type.rst
357
+
358
+ .. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
359
+
315
360
API Documentation
316
361
-----------------
317
362
318
363
To learn more about creating a ``MongoClient`` object in {+driver-short+},
319
364
see the following API documentation:
320
365
321
- - `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
366
+ - `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
0 commit comments