fix: correct return type annotation for find_one_and_* methods to include None

[cj81499]

Summary

find_one_and_update's existing type hint makes the false claim that the method returns a _DocumentType. However, the docstring (correctly) tells us that the method "Returns ``None`` if no document matches the filter."

The same is true of other find_one_and_* methods.

Changes in this PR

This PR corrects the type hint of the find_one_and_* methods to indicate that the function may return either _DocumentType or None (rather than just _DocumentType).

I've also updated the docstrings for the methods to make this behavior clearer.

Depending on what you consider to be the "surface area" of your library's API, this might be considered a breaking change.
I can't think of any code that would break at runtime (since the PR doesn't change runtime behavior), but it's possible someone has written code like the following. This PR would cause the assert_type to fail at "type checking time".

my_collection: pymongo.collection.Collection[MyDocument] = ...
x = my_collection.find_one_and_update(...)
assert_type(x, MyDocument)

Testing Plan

This change isn't changing any runtime behavior, so I'm not sure how I'd test it. I'm open to suggestions for how to test this if you have any.

Screenshots (optional)

N/A

Checklist

Checklist for Author

• Did you update the changelog (if necessary)?
• Is the intention of the code captured in relevant tests?
• If there are new TODOs, has a related JIRA ticket been created?

Checklist for Reviewer {@primary_reviewer}

• Does the title of the PR reference a JIRA Ticket?
• Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
• Have you checked for spelling & grammar errors?
• Is all relevant documentation (README or docstring) updated?

Focus Areas for Reviewer (optional)

[ShaneHarvey]

Is this also a bug in the other find_one_and_* methods?

[ZachOldham]

As someone not familiar with the ins-and-outs of this repo, is Optional[<type>] preferred over <type> | None? Or is it that it needs to support python versions that don't have the | syntax? (Same comment goes for the other instance of this as well)

[cj81499]

For reviewers, Zach is my coworker looking over this PR before I mark it as ready for review.

pymongo supports Python 3.9+. See requires-python = ">=3.9" in pyproject.toml.

Support for the "|" syntax for a Union was added with Python 3.10 (PEP 604).

Regardless of what is/isn't supported/required, using Optional (rather than |) is more consistent with the rest of the code.

[cj81499]

Is this also a bug in the other find_one_and_* methods?

I just checked and it is. I'll update this PR to fix the type hints for those methods shortly.