fixes

Author: mongoKart

source/connect/mongoclient.txt

@@ -33,12 +33,6 @@ 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
@@ -125,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.
@@ -134,7 +128,7 @@ 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.
@@ -257,16 +251,14 @@ To use type hints in your {+driver-short+} application, you must add a type anno
    client: MongoClient = MongoClient()
 
 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:
+``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()
 
-.. include:: /includes/type-hints/tip-more-info.rst
-
 Troubleshooting
 ---------------
 
@@ -341,4 +333,4 @@ 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/databases-collections.txt

@@ -328,9 +328,7 @@ Type Hints
 
 .. include:: /includes/type-hints/intro.rst
 
-.. include:: /includes/type-hints/tip-more-info.rst
-
-.. note:: TypedDict Requires Python 3.8+
+.. note:: TypedDict in Python 3.7 and Earlier
 
    .. include:: /includes/type-hints/typeddict-availability.rst
 

source/includes/type-hints/tip-more-info.rst

@@ -1,5 +1,7 @@
-See the following resources for more information about type hints:
+.. tip:: Learn More About Type Hints
 
-- `typing <https://docs.python.org/3.5/library/typing.html>`__ module (Python 3.5)
-- `mypy  <https://mypy.readthedocs.io/en/stable/getting_started.html>`__
-- `typing_extensions <https://pypi.org/project/typing-extensions/>`__ package
+   See the following resources for more information about type hints:
+
+   - `typing <https://docs.python.org/3.5/library/typing.html>`__ module (Python 3.5+)
+   - `mypy  <https://mypy.readthedocs.io/en/stable/getting_started.html>`__
+   - `typing_extensions <https://pypi.org/project/typing-extensions/>`__ package

source/includes/type-hints/troubleshooting-client-type.rst

@@ -2,7 +2,7 @@ Client Type Annotations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 If you don't add a type annotation for your ``MongoClient`` object,
-you might see the following mypy error:
+your type checker might show an error similar to the following:
 
 .. code-block:: python
 

source/includes/type-hints/troubleshooting-incompatible-type.rst

@@ -1,8 +1,8 @@
 Incompatible Type
 ~~~~~~~~~~~~~~~~~
 
-If you use the generic form of the ``MongoClient`` class, you
-might see the following mypy error:
+If you use the generic form of the ``MongoClient`` class, your type checker might
+show an error similar to the following:
 
 .. code-block:: python
 

source/includes/type-hints/typeddict-availability.rst

@@ -1,3 +1,3 @@
-The ``typing`` module, which contains the ``TypedDict`` class, is available only in
-Python 3.8 and later. To use the ``TypedDict`` class in earlier versions of Python,
-install the ``typing_extensions`` package.
+The examples in this section use the ``TypedDict`` class from the ``typing`` module. This
+module is available only in Python 3.8 and later. To use the ``TypedDict`` class in
+earlier versions of Python, install the ``typing_extensions`` package.

source/includes/write/bulk-write.py

@@ -10,6 +10,17 @@
 )
 # end-bulk-insert-one
 
+# start-bulk-insert-one-typed
+class Restaurant (TypedDict):
+    name: str
+    cuisine: str
+    borough: str
+    restaurant_id: str
+
+operation = pymongo.InsertOne(Restaurant(
+    name="Mongo's Deli", cuisine="Sandwiches", borough="Manhattan", restaurant_id="1234"))
+# end-bulk-insert-one-typed
+
 # start-bulk-update-one
 operation = UpdateOne(
     namespace="sample_restaurants.restaurants",
@@ -39,6 +50,19 @@
 )
 # end-bulk-replace-one
 
+# start-bulk-replace-one-typed
+class Restaurant (TypedDict):
+    name: str
+    cuisine: str
+    borough: str
+    restaurant_id: str
+
+operation = pymongo.ReplaceOne(
+    { "restaurant_id": "1234" },
+    Restaurant(name="Mongo's Pizza", cuisine="Pizza", borough="Brooklyn", restaurant_id="5678")
+)
+# end-bulk-replace-one-typed
+
 # start-bulk-delete-one
 operation = DeleteOne(
     namespace="sample_restaurants.restaurants",

source/run-command.txt

@@ -226,10 +226,9 @@ collections.
 Type Hints
 ----------
 
-When you use the ``Database.command()`` method to run a database command, you can instruct
-the method to decode the returned BSON to a specific document type. To do so,
-construct a ``CodecOptions`` object and pass the name of the class the documents should
-be decoded to. The class can be one of the following types:
+The ``Database.command()`` method can decode the returned BSON documents to instances
+of a specific class. To specify this class, construct a ``CodecOptions`` object and pass
+the class name. The class can be one of the following types:
 
 - ``bson.raw_bson.RawBSONDocument``.
 - A subclass of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``. 
@@ -239,11 +238,13 @@ be decoded to. The class can be one of the following types:
   parameter, you must also include the class in a type hint for your ``CodecOptions``
   object.
 
-The following example shows how to specify the document type for the result of the
-``ping`` command:
+.. include:: /includes/type-hints/typeddict-availability.rst
+
+The following example decodes the BSON returned by the ``ping`` command to instances
+of the ``RawBSONDocument`` class:
 
 .. code-block:: python
-   :emphasize-lines: 3, 5
+   :emphasize-lines: 3, 6-7
 
    from pymongo import MongoClient
    from bson.raw_bson import RawBSONDocument
@@ -253,9 +254,11 @@ The following example shows how to specify the document type for the result of t
    options = CodecOptions(RawBSONDocument)
    result = client.admin.command("ping", codec_options=options)
 
-To pass a ``TypedDict`` subclass, use the following syntax: 
+To decode BSON to a subclass of the ``TypedDict`` class, specify the class name in
+the ``CodecOptions`` type hint, as shown in the following example:
 
 .. code-block:: python
+   :emphasize-lines: 4, 6-8, 11
 
    from pymongo import MongoClient
    from bson.raw_bson import RawBSONDocument
@@ -270,8 +273,6 @@ To pass a ``TypedDict`` subclass, use the following syntax:
    options: CodecOptions[Movie] = CodecOptions(Movie)
    result = client.admin.command("ping", codec_options=options)
 
-.. include:: /includes/type-hints/tip-more-info.rst
-
 Troubleshooting
 ---------------
 

source/write/bulk-write.txt

@@ -95,6 +95,21 @@ 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.
+
+.. 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,6 +172,21 @@ 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.
+
+.. 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.
 
 Delete Operations

source/write/insert.txt

@@ -60,6 +60,23 @@ The following example inserts a document into the ``restaurants`` collection:
 
    sample_restaurants.restaurants.insert_one({"name" : "Mongo's Burgers"})
 
+You can also pass an instance of a custom class to the ``insert_one()`` method.
+This provides additional type safety if you're using a type-checking
+tool. The instance you pass must inherit from the ``TypedDict`` class.
+
+.. include:: /includes/type-hints/typeddict-availability.rst
+
+The following example passes an instance of the ``Restaurant`` class to the ``insert_one()``
+method for added type safety:
+
+.. code-block:: python
+   :copyable: true
+
+   class Restaurant(TypedDict):
+       name: str
+   
+   sample_restaurants.restaurants.insert_one(Movie(name="Mongo's Burgers")
+
 Insert Multiple Documents
 -------------------------
 
@@ -78,6 +95,28 @@ The following example inserts a list of documents into the ``restaurants`` colle
 
    sample_restaurants.restaurants.insert_many(document_list)
 
+You can also pass a list of instances of a custom class to the ``insert_many()`` method.
+This provides additional type safety if you're using a type-checking
+tool. The instances you pass must inherit from the ``TypedDict`` class.
+
+.. include:: /includes/type-hints/typeddict-availability.rst
+
+The following example calls the ``insert_many()`` method and passes a list that contains
+instances of the ``Restaurant`` class. This adds type safety to the insert operation. 
+
+.. code-block:: python
+   :copyable: true
+
+   class Restaurant(TypedDict):
+       name: str
+   
+   document_list = [
+      Restaurant(name="Mongo's Burgers"),
+      Restaurant(name="Mongo's Pizza")
+   ]
+
+   sample_restaurants.restaurants.insert_many(document_list)
+
 Modify Insert Behavior
 ----------------------
 
@@ -140,41 +179,6 @@ document-level validation.
 
    sample_restaurants.restaurants.insert_many(document_list, bypass_document_validation = True)
 
-Type Hints
-----------
-
-.. include:: /includes/type-hints/intro.rst
-
-When you call the ``insert_one()`` or ``insert_many()`` method, you can pass one or more
-instances of a custom class that represents the documents in the collection.
-
-To create
-a custom type, define a class that inherits from the ``TypedDict`` class. In the class,
-add a property for each field in the document.
-
-After you define the class, you can insert instances of the class. The following example
-defines a ``Movie`` class to represent documents from the
-``sample_mflix.movies`` collection.
-Each ``Movie`` object contains two key-value pairs: ``name``, a string key with a string
-value, and ``year``, a string key with an integer value.
-The code then uses the ``insert_one()`` method to insert a ``Movie`` object.
-
-.. code-block:: python
-   :emphasize-lines: 10
-
-   from typing import TypedDict
-   
-   class Movie(TypedDict):
-       name: str
-       year: int
-
-   client: MongoClient = MongoClient()
-   database = client["test_database"]
-   collection: Collection[Movie] = database["test_collection"]
-   inserted = collection.insert_one(Movie(name="Jurassic Park", year=1993))
-
-.. include:: /includes/type-hints/tip-more-info.rst
-
 Troubleshooting
 ---------------
 
@@ -308,6 +312,7 @@ The following code example shows how to implement this solution:
    The ``NotRequired`` class is available only in Python 3.11 and later.
    To use ``NotRequired`` in earlier versions of Python, install the ``typing_extensions``
    package instead.
+
 Additional Information
 ----------------------