Merge remote-tracking branch 'upstream/master' into docsp-46362-toc-reorg

Author: mongoKart

config/redirects

@@ -57,4 +57,7 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/
 [*-master]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/reference/release-notes/
 [*-master]: ${prefix}/${version}/tools/ -> ${base}/${version}/reference/third-party-tools/
 [*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/reference/upgrade/
-[*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/
+[*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/[v4.7-*]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/run-sample-query/
+
+# temp redirect until DOP deletes unversioned URLs
+[master]: ${prefix}/compatibility/ -> ${base}/current/compatibility/

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

@@ -90,9 +90,7 @@ Tutorial
       Next, add a :manual:`$sort
       </reference/operator/aggregation/sort>` stage that sorts the
       documents in descending order by the ``dateofbirth`` field to
-      list the youngest people first. Because Python dictionaries don't maintain the
-      order of their elements, use a ``SON``or ``OrderedDict`` object
-      instead:
+      list the youngest people first:
 
       .. literalinclude:: /includes/aggregation/filtered-subset.py
          :language: python

source/connect/mongoclient.txt

@@ -119,7 +119,7 @@ constructor accepts. All parameters are optional.
        :wikipedia:`round-robin DNS <Round-robin_DNS>` addresses.
 
        **Data type:** ``Union[str, Sequence[str]]``
-       **Default value:** ``"localhost"``
+       | **Default value:** ``"localhost"``
 
    * - ``port``
      - The port number {+mdb-server+} is running on.
@@ -128,17 +128,35 @@ constructor accepts. All parameters are optional.
        instead of using this parameter.
 
        **Data type:** ``int``
-       **Default value:** ``27017``
+       | **Default value:** ``27017``
 
    * - ``document_class``
      - The default class that the client uses to decode BSON documents returned by queries.
-       This parameter supports the ``bson.raw_bson.RawBSONDocument`` type, as well as
-       subclasses of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``.
+       This parameter accepts the following types:
 
-       If you specify ``bson.son.SON`` as the document class, you must also specify types
-       for the key and value.
+       - ``bson.raw_bson.RawBSONDocument``. To learn more about the ``RawBSONDocument`` class,
+         see :ref:`pymongo-bson-raw`.
+
+       - A subclass of the ``collections.abc.Mapping`` type, such as ``OrderedDict``.
+         Depending on the strictness of your type-checking rules, you might also need to
+         specify types for the key and value, as shown in the following example:
+
+         .. code-block:: python
+
+            client = MongoClient(document_class=OrderedDict[str, int])
+       
+       - A subclass of the ``TypedDict`` type. To pass a ``TypedDict`` subclass for this
+         parameter, you must also include the class in a type hint for your ``MongoClient``
+         object, as shown in the following example:
+
+         .. code-block:: python
+
+            client: MongoClient[MyTypedDict] = MongoClient() 
+
+         .. include:: /includes/type-hints/typeddict-availability.rst
 
        **Data type:** ``Type[_DocumentType]``
+       **Default:** ``dict``
 
    * - ``tz_aware``
      - If this parameter is ``True``, the client treats ``datetime`` values as aware.
@@ -168,6 +186,11 @@ constructor accepts. All parameters are optional.
 
        **Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__
 
+You can also pass keyword arguments to the ``MongoClient()`` constructor to specify
+optional parameters. For a complete list of keyword arguments, see the
+`MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ 
+class in the API documentation.
+
 Concurrent Execution
 --------------------
 
@@ -226,28 +249,46 @@ To use multiprocessing with {+driver-short+}, write code similar to the followin
    Do not copy an instance of the ``MongoClient`` class from the parent process to a child
    process.
 
-Type Hints
+.. _pymongo-type-hints-client:
+
+Type Hints 
 ----------
 
-If you're using Python v3.5 or later, you can add type hints to your Python code.
+.. include:: /includes/type-hints/intro.rst
 
-The following code example shows how to declare a type hint for a ``MongoClient``
-object:
+To use type hints in your {+driver-short+} application, you must add a type annotation to your
+``MongoClient`` object, as shown in the following example:
 
 .. code-block:: python
 
    client: MongoClient = MongoClient()
 
-In the previous example, the code doesn't specify a type for the documents that the
-``MongoClient`` object will work with. To specify a document type,
-include the ``Dict[str, Any]`` type when you
-create the ``MongoClient`` object, as shown in the following example:
+For more accurate type information, you can include the generic document type
+``Dict[str, Any]`` in your type annotation. This data type matches all documents in MongoDB.
+The following example shows how to include this data type in your type annotation:
 
 .. code-block:: python
 
    from typing import Any, Dict
    client: MongoClient[Dict[str, Any]] = MongoClient()
 
+If all the documents that you are working with correspond to a single custom type, you
+can specify the custom type as a type hint for your ``MongoClient`` object. This
+provides more accurate type information than the generic ``Dict[str, Any]`` type.
+
+The following example shows how to specify the ``Movie`` type as a type hint for a
+``MongoClient`` object:
+
+.. code-block:: python
+
+   from typing import TypedDict
+
+   class Movie(TypedDict):
+       name: str
+       year: int
+   
+   client: MongoClient[Movie] = MongoClient()
+
 Troubleshooting
 ---------------
 
@@ -312,10 +353,14 @@ process.
    multithreaded contexts with ``fork()``, see `Issue 6721 <http://bugs.python.org/issue6721>`__
    in the Python Issue Tracker.
 
+.. include:: /includes/type-hints/troubleshooting-client-type.rst
+
+.. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
+
 API Documentation
 -----------------
 
 To learn more about creating a ``MongoClient`` object in {+driver-short+},
 see the following API documentation:
 
-- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ 
+- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__

source/crud/bulk-write.txt

@@ -95,6 +95,23 @@ The following example creates an instance of ``InsertOne``:
    :language: python
    :copyable:
 
+You can also create an instance of ``InsertOne`` by passing an instance of a custom class
+to the constructor. This provides additional type safety if you're using a type-checking
+tool. The instance you pass must inherit from the ``TypedDict`` class.
+
+.. note:: TypedDict in Python 3.7 and Earlier
+
+   .. include:: /includes/type-hints/typeddict-availability.rst
+
+The following example constructs an ``InsertOne`` instance by using a custom
+class for added type safety:
+
+.. literalinclude:: /includes/write/bulk-write.py
+   :start-after: start-bulk-insert-one-typed
+   :end-before: end-bulk-insert-one-typed
+   :language: python
+   :copyable:
+
 To insert multiple documents, create an instance of ``InsertOne`` for each document.
 
 .. include:: /includes/write/unique-id-note.rst
@@ -157,8 +174,27 @@ The following example creates an instance of ``ReplaceOne``:
    :language: python
    :copyable:
 
+You can also create an instance of ``ReplaceOne`` by passing an instance of a custom class
+to the constructor. This provides additional type safety if you're using a type-checking
+tool. The instance you pass must inherit from the ``TypedDict`` class.
+
+.. note:: TypedDict in Python 3.7 and Earlier
+
+   .. include:: /includes/type-hints/typeddict-availability.rst
+
+The following example constructs a ``ReplaceOne`` instance by using a custom
+class for added type safety:
+
+.. literalinclude:: /includes/write/bulk-write.py
+   :start-after: start-bulk-replace-one-typed
+   :end-before: end-bulk-replace-one-typed
+   :language: python
+   :copyable:
+
 To replace multiple documents, you must create an instance of ``ReplaceOne`` for each document.
 
+.. include:: /includes/type-hints/tip-type-checkers.rst
+
 Delete Operations
 ~~~~~~~~~~~~~~~~~
 
@@ -517,6 +553,13 @@ The ``MongoClient.bulk_write()`` method returns a ``ClientBulkWriteResult`` obje
    * - ``upserted_count``
      - | The number of documents upserted, if any.
 
+Troubleshooting
+---------------
+
+.. include:: /includes/type-hints/troubleshooting-client-type.rst
+
+.. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
+
 Additional Information
 ----------------------