Related to PYTHON-2427, and https://github.com/mongodb-labs/pymongo-stubs/issues/15 we should audit our improvements to _DocumentOut for bson.decode, coll.find_one, etc... I believe there are two goals to give users a good typing experience:

1. All correct usage of the driver does not generate mypy errors.
2. Where possible, incorrect usage of the driver does generate mypy errors

Goal 1) is the most important in my view since we don't want to force users to workaround false positives caused by our types. Back in PYTHON-2427 I had decided the best way to accomplish this was via Any because dict and RawBSONDocument are incompatible in that one is mutable the other is not. In PYTHON-3060, steve.silvester improved the client/db/coll apis to be generic (eg Collection[dict[str, Any]]).

We should reevaluate the design to make sure that goal 1) is still satisfied. One issue like this was fixed in review:

            error_object = bson.BSON(self.documents).decode()
            # Fake the ok field if it doesn't exist.
-             error_object.setdefault("ok", 0)
+            if hasattr(error_object, "setdefault"):
+                error_object.setdefault("ok", 0)  # type: ignore

In response we changed the decode signatures to return Dict[str, Any] to avoid false positives like the above.

To fix this ticket, let's add a few tests that exercises the different cases (dict vs RawBSONDocument vs custom dict class) with a few of the apis (bson.decode, find_one, etc...) to ensure a good user experience.