split to multiple pages

Author: mongoKart

source/connect/mongoclient.txt

@@ -33,6 +33,12 @@ while connected to MongoDB.
 This guide shows you how to create a connection string and use a ``MongoClient`` object
 to connect to MongoDB.
 
+.. tip:: Type Hints
+
+   If your application uses Python 3.5 or later, you can add type hints to your
+   ``MongoClient`` objects. To learn how to add type hints, see
+   :ref:`Type Hints <pymongo-type-hints-client>`.
+
 .. _pymongo_connection_uri:
 
 Connection URI
@@ -132,11 +138,21 @@ constructor accepts. All parameters are optional.
 
    * - ``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 supports 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``.
+       - A subclass of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``. 
+         If you specify ``bson.son.SON`` as the document class, you must also specify types
+         for the key and value.
+       - 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]``
 
@@ -176,28 +192,38 @@ constructor accepts. All parameters are optional.
    a process, the child process *does* need its own ``MongoClient`` object.
    To learn more, see the :ref:`FAQ <pymongo-faq>` page.
 
-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 type matches all documents in MongoDB.
+The following example shows how to add this type hint:
 
 .. code-block:: python
 
    from typing import Any, Dict
    client: MongoClient[Dict[str, Any]] = MongoClient()
 
+.. include:: /includes/type-hints/tip-more-info.rst
+
+Troubleshooting
+---------------
+
+.. include:: /includes/type-hints/troubleshooting-client-type.rst
+
+.. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
+
 API Documentation
 -----------------
 

source/databases-collections.txt

@@ -253,9 +253,81 @@ within 35 milliseconds of the closest member's ping time.
    :manual:`localThreshold </reference/program/mongos/#std-option-mongos.--localThreshold>`
    command-line option.
 
+.. _pymongo-databases-collection-type-hints:
+
+Type Hints
+----------
+
+.. include:: /includes/type-hints/intro.rst
+
+.. include:: /includes/type-hints/tip-more-info.rst
+
+.. note:: TypedDict Requires Python 3.8+
+   
+   .. include:: /includes/type-hints/typeddict-availability.rst
+
+Database
+~~~~~~~~
+
+If all documents in a database match a well-defined schema, you can specify a type hint
+that uses a Python class to represent the documents' structure. By including this class
+in the type hint for your ``Database`` object, you can ensure that all documents you
+store or retrieve have the required structure. This provides more accurate type
+checking and code completion than the default ``Dict[str, Any]`` type.
+
+First, define a class to represent a document from the database. The class must inherit
+from the ``TypedDict`` class and must contain the same fields as the documents in the
+database. After you define your class, include its name as the generic type for the
+``Database`` type hint.
+
+The following example defines a ``Movie`` class and uses it as the
+generic type for a ``Database`` type hint:
+
+.. code-block:: python
+   :emphasize-lines: 5-7, 10
+
+   from typing import TypedDict
+   from pymongo import MongoClient
+   from pymongo.database import Database
+
+   class Movie(TypedDict):
+       name: str
+       year: int
+   
+   client: MongoClient = MongoClient()
+   database: Database[Movie] = client["test_database"]
+
+Collection
+~~~~~~~~~~
+
+Adding a generic type to a ``Collection`` type hint is similar to adding a generic type
+to a ``Database`` type hint. First, define a class that inherits from the ``TypedDict`` class
+and represents the structure of the
+documents in the collection. Then, include the class name as the generic type for the
+``Collection`` type hint, as shown in the following example:
+
+.. code-block:: python
+   :emphasize-lines: 5-7,11
+
+   from typing import TypedDict
+   from pymongo import MongoClient
+   from pymongo.collection import Collection
+   
+   class Movie(TypedDict):
+       name: str
+       year: int
+   
+   client: MongoClient = MongoClient()
+   database = client["test_database"]
+   collection: Collection[Movie] = database["test_collection"]
+
 Troubleshooting
 ---------------
 
+.. include:: /includes/type-hints/troubleshooting-client-type.rst
+
+.. include:: /includes/type-hints/troubleshooting-incompatible-type.rst
+
 .. include:: /includes/troubleshooting/read-write-options.rst
 
 API Documentation