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.
@@ -207,16 +201,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
 ---------------
 
@@ -230,4 +222,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

@@ -9,6 +9,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 = pymongo.UpdateOne(
     { "name": "Mongo's Deli" },
@@ -35,6 +46,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 = pymongo.DeleteOne({ "restaurant_id": "5678" })
 # end-bulk-delete-one

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/tools.txt

@@ -260,20 +260,6 @@ daemon in the global application group:
    and in the `Multiple Python Sub Interpreters <https://modwsgi.readthedocs.io/en/master/user-guides/application-issues.html#multiple-python-sub-interpreters>`__
    section of the mod_wsgi documentation.
 
-Alternative Python Drivers
---------------------------
-
-This section lists alternatives to {+driver-short+}.
-
-- `Motor <https://github.com/mongodb/motor>`__ is a full-featured, non-blocking
-  MongoDB driver for Python Tornado applications.
-
-- `TxMongo <https://github.com/twisted/txmongo>`__ is an asynchronous Twisted
-  Python driver for MongoDB.
-
-- `MongoMock <https://github.com/mongomock/mongomock>`__ is a small
-  library to help test Python code. It uses {+driver-short+} to interact with MongoDB.
-
 Type Checkers
 -------------
 
@@ -293,4 +279,18 @@ in the ``typing`` module documentation.
    .. code-block:: python
 
       [mypy-pymongo]
-      follow_imports = False
+      follow_imports = False
+
+Alternative Python Drivers
+--------------------------
+
+This section lists alternatives to {+driver-short+}.
+
+- `Motor <https://github.com/mongodb/motor>`__ is a full-featured, non-blocking
+  MongoDB driver for Python Tornado applications.
+
+- `TxMongo <https://github.com/twisted/txmongo>`__ is an asynchronous Twisted
+  Python driver for MongoDB.
+
+- `MongoMock <https://github.com/mongomock/mongomock>`__ is a small
+  library to help test Python code. It uses {+driver-short+} to interact with MongoDB.

source/write/bulk-write.txt

@@ -65,6 +65,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.
 
 .. note::
@@ -122,6 +137,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
@@ -286,37 +316,6 @@ The ``bulk_write()`` method returns a ``BulkWriteResult`` object. The
      - | A map of the operation's index to the ``_id`` of the upserted documents, if
          applicable.
 
-Type Hints
-----------  
-
-.. include:: /includes/type-hints/intro.rst
-
-When you use the ``bulk_write()`` method to perform an ``InsertOne`` or ``ReplaceOne``
-operation, 
-The following code example shows how to insert 
-- ``~pymongo.collection.Collection.bulk_write()``
-
-For ``bulk_write()``, both the ``~pymongo.operations.InsertOne()`` and
-``~pymongo.operations.ReplaceOne()`` operators are generic.
-
-The following code example shows that the results are the same as the preceding examples
-when you call the ``bulk_write()`` method:
-
-.. code-block:: python
-
-   from typing import TypedDict
-   from pymongo import MongoClient
-   from pymongo.operations import InsertOne
-   from pymongo.collection import Collection
-   client: MongoClient = MongoClient()
-   collection: Collection[Movie] = client.test.test
-   inserted = collection.bulk_write([InsertOne(Movie(name="Jurassic Park", year=1993))])
-   result = collection.find_one({"name": "Jurassic Park"})
-   assert result is not None
-   assert result["year"] == 1993
-
-.. include:: /includes/type-hints/tip-more-info.rst
-
 Troubleshooting
 ---------------