Skip to content

Commit 1bf1b65

Browse files
committed
Merge remote-tracking branch 'upstream/master' into docsp-46362-toc-reorg
2 parents d56fcc8 + 9e673bc commit 1bf1b65

19 files changed

+628
-479
lines changed

config/redirects

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,4 +57,7 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/
5757
[*-master]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/reference/release-notes/
5858
[*-master]: ${prefix}/${version}/tools/ -> ${base}/${version}/reference/third-party-tools/
5959
[*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/reference/upgrade/
60-
[*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/
60+
[*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/[v4.7-*]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/run-sample-query/
61+
62+
# temp redirect until DOP deletes unversioned URLs
63+
[master]: ${prefix}/compatibility/ -> ${base}/current/compatibility/

source/aggregation/aggregation-tutorials/filtered-subset.txt

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,9 +90,7 @@ Tutorial
9090
Next, add a :manual:`$sort
9191
</reference/operator/aggregation/sort>` stage that sorts the
9292
documents in descending order by the ``dateofbirth`` field to
93-
list the youngest people first. Because Python dictionaries don't maintain the
94-
order of their elements, use a ``SON``or ``OrderedDict`` object
95-
instead:
93+
list the youngest people first:
9694

9795
.. literalinclude:: /includes/aggregation/filtered-subset.py
9896
:language: python

source/connect/mongoclient.txt

Lines changed: 60 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ constructor accepts. All parameters are optional.
119119
:wikipedia:`round-robin DNS <Round-robin_DNS>` addresses.
120120

121121
**Data type:** ``Union[str, Sequence[str]]``
122-
**Default value:** ``"localhost"``
122+
| **Default value:** ``"localhost"``
123123

124124
* - ``port``
125125
- The port number {+mdb-server+} is running on.
@@ -128,17 +128,35 @@ constructor accepts. All parameters are optional.
128128
instead of using this parameter.
129129

130130
**Data type:** ``int``
131-
**Default value:** ``27017``
131+
| **Default value:** ``27017``
132132

133133
* - ``document_class``
134134
- 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:
137136

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
140157

141158
**Data type:** ``Type[_DocumentType]``
159+
**Default:** ``dict``
142160

143161
* - ``tz_aware``
144162
- If this parameter is ``True``, the client treats ``datetime`` values as aware.
@@ -168,6 +186,11 @@ constructor accepts. All parameters are optional.
168186

169187
**Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__
170188

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+
171194
Concurrent Execution
172195
--------------------
173196

@@ -226,28 +249,46 @@ To use multiprocessing with {+driver-short+}, write code similar to the followin
226249
Do not copy an instance of the ``MongoClient`` class from the parent process to a child
227250
process.
228251

229-
Type Hints
252+
.. _pymongo-type-hints-client:
253+
254+
Type Hints
230255
----------
231256

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
233258

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:
236261

237262
.. code-block:: python
238263

239264
client: MongoClient = MongoClient()
240265

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:
245269

246270
.. code-block:: python
247271

248272
from typing import Any, Dict
249273
client: MongoClient[Dict[str, Any]] = MongoClient()
250274

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+
251292
Troubleshooting
252293
---------------
253294

@@ -312,10 +353,14 @@ process.
312353
multithreaded contexts with ``fork()``, see `Issue 6721 <http://bugs.python.org/issue6721>`__
313354
in the Python Issue Tracker.
314355

356+
.. include:: /includes/type-hints/troubleshooting-client-type.rst
357+
358+
.. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
359+
315360
API Documentation
316361
-----------------
317362

318363
To learn more about creating a ``MongoClient`` object in {+driver-short+},
319364
see the following API documentation:
320365

321-
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
366+
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__

source/crud/bulk-write.txt

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,23 @@ The following example creates an instance of ``InsertOne``:
9595
:language: python
9696
:copyable:
9797

98+
You can also create an instance of ``InsertOne`` by passing an instance of a custom class
99+
to the constructor. This provides additional type safety if you're using a type-checking
100+
tool. The instance you pass must inherit from the ``TypedDict`` class.
101+
102+
.. note:: TypedDict in Python 3.7 and Earlier
103+
104+
.. include:: /includes/type-hints/typeddict-availability.rst
105+
106+
The following example constructs an ``InsertOne`` instance by using a custom
107+
class for added type safety:
108+
109+
.. literalinclude:: /includes/write/bulk-write.py
110+
:start-after: start-bulk-insert-one-typed
111+
:end-before: end-bulk-insert-one-typed
112+
:language: python
113+
:copyable:
114+
98115
To insert multiple documents, create an instance of ``InsertOne`` for each document.
99116

100117
.. include:: /includes/write/unique-id-note.rst
@@ -157,8 +174,27 @@ The following example creates an instance of ``ReplaceOne``:
157174
:language: python
158175
:copyable:
159176

177+
You can also create an instance of ``ReplaceOne`` by passing an instance of a custom class
178+
to the constructor. This provides additional type safety if you're using a type-checking
179+
tool. The instance you pass must inherit from the ``TypedDict`` class.
180+
181+
.. note:: TypedDict in Python 3.7 and Earlier
182+
183+
.. include:: /includes/type-hints/typeddict-availability.rst
184+
185+
The following example constructs a ``ReplaceOne`` instance by using a custom
186+
class for added type safety:
187+
188+
.. literalinclude:: /includes/write/bulk-write.py
189+
:start-after: start-bulk-replace-one-typed
190+
:end-before: end-bulk-replace-one-typed
191+
:language: python
192+
:copyable:
193+
160194
To replace multiple documents, you must create an instance of ``ReplaceOne`` for each document.
161195

196+
.. include:: /includes/type-hints/tip-type-checkers.rst
197+
162198
Delete Operations
163199
~~~~~~~~~~~~~~~~~
164200

@@ -517,6 +553,13 @@ The ``MongoClient.bulk_write()`` method returns a ``ClientBulkWriteResult`` obje
517553
* - ``upserted_count``
518554
- | The number of documents upserted, if any.
519555

556+
Troubleshooting
557+
---------------
558+
559+
.. include:: /includes/type-hints/troubleshooting-client-type.rst
560+
561+
.. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
562+
520563
Additional Information
521564
----------------------
522565

0 commit comments

Comments
 (0)