PYTHON-5653: 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?

[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.

[caseyclements]

I've updated the title with a JIRA ticket. Shane is on leave, but this LGTM!

Shane has just begun a sabbatical.

[cj81499]

Thanks Casey! I see there's some failing checks, but I can't seem to tell what actually failed. Is there anything needed from me or is it something wonky (eg: test infrastructure) on your end?

[caseyclements]

Failures are unrelated.