DOCSP-46812 - Distribute Type Hints #167

mongoKart · 2025-02-06T15:29:48Z

Continuation of #156 (already approved). This PR moves content from the old Type Hints page to the relevant subject pages

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-46812

Staging Links

aggregation/aggregation-tutorials/filtered-subset

connect/mongoclient

data-formats/bson

databases-collections

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2025-02-06T15:30:13Z

✅ Deploy Preview for docs-pymongo ready!

Name	Link
🔨 Latest commit	`013530d`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-pymongo/deploys/67cf2a29641e410008b95d21
😎 Deploy Preview	https://deploy-preview-167--docs-pymongo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rachel-mack

A couple things:

source/connect/mongoclient.txt

rachel-mack · 2025-02-07T15:02:43Z

source/connect/mongoclient.txt

+       - ``bson.raw_bson.RawBSONDocument``.
+       - A subclass of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``. 
+         If you specify ``bson.son.SON`` as the document class, you must also specify types
+         for the key and value.
+       - A subclass of the ``TypedDict`` type. To pass a ``TypedDict`` subclass for this
+         parameter, you must also include the class in a type hint for your ``MongoClient``
+         object, as shown in the following example:


Suggested change

- ``bson.raw_bson.RawBSONDocument``.

- A subclass of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``.

If you specify ``bson.son.SON`` as the document class, you must also specify types

for the key and value.

- A subclass of the ``TypedDict`` type. To pass a ``TypedDict`` subclass for this

parameter, you must also include the class in a type hint for your ``MongoClient``

object, as shown in the following example:

- ``bson.raw_bson.RawBSONDocument``

- Subclasses of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``

If you specify ``bson.son.SON`` as the document class, you must also specify types

for the key and value.

- A subclass of the ``TypedDict`` type

To pass a ``TypedDict`` subclass to this parameter, you must also include the class in a type hint for your ``MongoClient``

object, as shown in the following example:

I think this would also benefit from an example of specifying the key and value types of a bson.son.SON instance.

I think we need the period at the end of the first item.

Makes more sense to me to say 'a subclass' than 'subclasses,' because you can only pass one type.

I'll add the SON example.

rachel-mack · 2025-02-07T15:04:07Z

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

+The ``TypedDict`` class is in the ``typing`` module, which
+is available only in Python 3.8 and later. To use the ``TypedDict`` class in
+earlier versions of Python, install the ``typing_extensions`` package.


Are there links available for TypeDict and the typing_extensions package?

yeah, i went back and forth on including them. i'll add if you think they're helpful

source/includes/type-hints/intro.rst

rachel-mack · 2025-02-07T16:10:45Z

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

+If you use the generic form of the ``MongoClient`` class, your type checker might
+show an error similar to the following:


I'm a little weak on Python, but I think this is more specific:

Suggested change

If you use the generic form of the ``MongoClient`` class, your type checker might

show an error similar to the following:

If you do not specify a type when you instantiate the ``MongoClient`` class, your type checker might

show an error similar to the following:

I agree about keeping 'generic' as the term for 'type that accepts another type as an argument'

source/write/insert.txt

rachel-mack · 2025-02-07T16:38:28Z

source/write/insert.txt

+As discussed above, if you don't specify the ``_id`` field, {+driver-short+} automatically
+inserts it into the document.
+You can retrieve the value of the ``_id`` field at runtime, but if you use MyPy or another
+tool to perform static type-checking, it won't find the ``_id`` field in your class and
+will show an error similar to the following: 


I don't think many people are reading through the troubleshooting section, so we I think we should treat each section as though it will be read without broader context.

Suggested change

As discussed above, if you don't specify the ``_id`` field, {+driver-short+} automatically

inserts it into the document.

You can retrieve the value of the ``_id`` field at runtime, but if you use MyPy or another

tool to perform static type-checking, it won't find the ``_id`` field in your class and

will show an error similar to the following:

If you don't specify the ``_id`` field, {+driver-short+} automatically

inserts it into the document.

You can retrieve the value of the ``_id`` field at runtime, but if you use MyPy or another

tool to perform static type-checking, it won't find the ``_id`` field in your class and

will show an error similar to the following:

rachel-mack · 2025-02-07T16:40:59Z

source/write/insert.txt

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


Link to NotRequired class and typing_extensions package.

source/write/insert.txt

rachel-mack

LGTM

NoahStapp · 2025-02-19T20:14:23Z

source/connect/mongoclient.txt


-       If you specify ``bson.son.SON`` as the document class, you must also specify types
-       for the key and value.
+       - ``bson.raw_bson.RawBSONDocument``.


Should this have an accompanying brief explanation of what a RawBSONDocument is?

From the docstring: "a representation of a BSON document that
provides access to the underlying raw BSON bytes. Only when a field is
accessed or modified within the document does RawBSONDocument decode
its bytes." Or maybe just a link?

source/connect/mongoclient.txt

NoahStapp · 2025-02-19T20:17:08Z

source/run-command.txt

+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``.


Same question here.

Sorry, which question?

Should we link to or describe what RawBSONDocument is here?

caseyclements

I'll approve and resolve comments once you've replied.

caseyclements · 2025-02-21T21:21:16Z

source/connect/mongoclient.txt


-       If you specify ``bson.son.SON`` as the document class, you must also specify types
-       for the key and value.
+       - ``bson.raw_bson.RawBSONDocument``.


From the docstring: "a representation of a BSON document that
provides access to the underlying raw BSON bytes. Only when a field is
accessed or modified within the document does RawBSONDocument decode
its bytes." Or maybe just a link?

caseyclements · 2025-02-21T21:23:29Z

source/connect/mongoclient.txt

+       - ``bson.raw_bson.RawBSONDocument``.
+       - A subclass of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``. 
+         If you specify ``bson.son.SON`` as the document class, you must also specify types
+         for the key and value, as shown in the following example:


I just tried this with SON without further subtypes. It worked fine. Maybe change "must" to "may".

c4 = MongoClient(document_class=SON) clxn4 = c4["db"]["clxn"] clxn4.find_one({}) Out[27]: SON([('_id', ObjectId('67b8ebf181dbbd497b835248')), ('i', 0)])

Do the old docs need to be updated too, or did I misinterpret?

The subtypes are still required depending on how strict the user has their type checking settings. I don't think we want to update either docs.

@blink1073 Is it most accurate to say 'you may need to specify types' ?

Yes I think that is fair

Should we remove all references to bson.son.SON here? Its use case for ordered Python dictionaries is no longe relevant now that OrderedDict exists. Default dict has also been ordered since Python 3.7.

Updated to OrderedDict and removed other references to SON

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

source/connect/mongoclient.txt

source/write/insert.txt

caseyclements

A few comments, foremost is the question of why to distribute type hint discussion as opposed to having its own page.

caseyclements

LGTM

NoahStapp · 2025-03-05T21:04:12Z

source/run-command.txt

+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``.


Should we link to or describe what RawBSONDocument is here?

…ibute-type-hints

caseyclements

still lgtm

NoahStapp · 2025-03-06T14:47:29Z

source/connect/mongoclient.txt

+       - ``bson.raw_bson.RawBSONDocument``.
+       - A subclass of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``. 
+         If you specify ``bson.son.SON`` as the document class, you must also specify types
+         for the key and value, as shown in the following example:


Should we remove all references to bson.son.SON here? Its use case for ordered Python dictionaries is no longe relevant now that OrderedDict exists. Default dict has also been ordered since Python 3.7.

NoahStapp · 2025-03-06T14:48:27Z

source/connect/mongoclient.txt

+can specify the custom type as a type hint for your ``MongoClient`` object. This
+provides more accurate type information than the generic ``Dict[str, Any]`` type.
+
+The following example shows how to specify the ``Movie`` type as a type hint for a


We should add the definition of Movie here for clarity.

Still missing the Movie definition here.

NoahStapp · 2025-03-07T15:06:20Z

source/connect/mongoclient.txt

+can specify the custom type as a type hint for your ``MongoClient`` object. This
+provides more accurate type information than the generic ``Dict[str, Any]`` type.
+
+The following example shows how to specify the ``Movie`` type as a type hint for a


Still missing the Movie definition here.

github-actions · 2025-03-10T20:05:35Z

The backport to v4.10 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-v4.10 v4.10
# Navigate to the new working tree
cd .worktrees/backport-v4.10
# Create a new branch
git switch --create backport-167-to-v4.10
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c4f389516721cd7d99b931e4eca342b99c0f8840
# Push it to GitHub
git push --set-upstream origin backport-167-to-v4.10
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-v4.10

Then, create a pull request where the base branch is v4.10 and the compare/head branch is backport-167-to-v4.10.

github-actions · 2025-03-10T20:05:35Z

The backport to v4.9 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-v4.9 v4.9
# Navigate to the new working tree
cd .worktrees/backport-v4.9
# Create a new branch
git switch --create backport-167-to-v4.9
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c4f389516721cd7d99b931e4eca342b99c0f8840
# Push it to GitHub
git push --set-upstream origin backport-167-to-v4.9
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-v4.9

Then, create a pull request where the base branch is v4.9 and the compare/head branch is backport-167-to-v4.9.

github-actions · 2025-03-10T20:05:36Z

The backport to v4.8 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-v4.8 v4.8
# Navigate to the new working tree
cd .worktrees/backport-v4.8
# Create a new branch
git switch --create backport-167-to-v4.8
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c4f389516721cd7d99b931e4eca342b99c0f8840
# Push it to GitHub
git push --set-upstream origin backport-167-to-v4.8
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-v4.8

Then, create a pull request where the base branch is v4.8 and the compare/head branch is backport-167-to-v4.8.

github-actions · 2025-03-10T20:05:36Z

The backport to v4.7 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-v4.7 v4.7
# Navigate to the new working tree
cd .worktrees/backport-v4.7
# Create a new branch
git switch --create backport-167-to-v4.7
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c4f389516721cd7d99b931e4eca342b99c0f8840
# Push it to GitHub
git push --set-upstream origin backport-167-to-v4.7
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-v4.7

Then, create a pull request where the base branch is v4.7 and the compare/head branch is backport-167-to-v4.7.

github-actions · 2025-03-10T20:05:37Z

The backport to v4.11 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-v4.11 v4.11
# Navigate to the new working tree
cd .worktrees/backport-v4.11
# Create a new branch
git switch --create backport-167-to-v4.11
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 c4f389516721cd7d99b931e4eca342b99c0f8840
# Push it to GitHub
git push --set-upstream origin backport-167-to-v4.11
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-v4.11

Then, create a pull request where the base branch is v4.11 and the compare/head branch is backport-167-to-v4.11.

(cherry picked from commit c4f3895)

(cherry picked from commit c4f3895) (cherry picked from commit 56ba281)

mongoKart force-pushed the docsp-46812-distribute-type-hints branch from 906a49d to 0da250f Compare February 6, 2025 16:54

rachel-mack requested changes Feb 7, 2025

View reviewed changes

mongoKart commented Feb 11, 2025

View reviewed changes

source/write/insert.txt Show resolved Hide resolved

mongoKart requested a review from rachel-mack February 11, 2025 23:22

rachel-mack approved these changes Feb 19, 2025

View reviewed changes

NoahStapp suggested changes Feb 19, 2025

View reviewed changes

caseyclements suggested changes Feb 21, 2025

View reviewed changes

caseyclements suggested changes Feb 24, 2025

View reviewed changes

mongoKart and others added 5 commits March 4, 2025 13:37

autobuilder

1def2b0

split to multiple pages

0809a78

fixes

8f7ba00

fixes

4a208ee

rm feedback

c420d12

caseyclements approved these changes Mar 5, 2025

View reviewed changes

tech review

301d38a

mongoKart force-pushed the docsp-46812-distribute-type-hints branch from 0eae39a to 301d38a Compare March 5, 2025 20:56

mongoKart requested review from NoahStapp and caseyclements and removed request for caseyclements March 5, 2025 20:56

NoahStapp suggested changes Mar 5, 2025

View reviewed changes

mongoKart added 3 commits March 5, 2025 15:15

add link to rawbson docs

c6bd034

Merge remote-tracking branch 'upstream/master' into docsp-46812-distr…

7f48d6f

…ibute-type-hints

add link ref

7f3d560

caseyclements approved these changes Mar 5, 2025

View reviewed changes

NoahStapp suggested changes Mar 6, 2025

View reviewed changes

feedback

9a33331

mongoKart requested a review from NoahStapp March 6, 2025 22:49

NoahStapp suggested changes Mar 7, 2025

View reviewed changes

add movie definition

013530d

mongoKart requested a review from NoahStapp March 10, 2025 18:09

NoahStapp approved these changes Mar 10, 2025

View reviewed changes

mongoKart added backport v4.10 backport v4.9 backport v4.8 backport v4.7 backport v4.11 labels Mar 10, 2025

mongoKart merged commit c4f3895 into mongodb:master Mar 10, 2025
10 of 11 checks passed

mongoKart deleted the docsp-46812-distribute-type-hints branch March 10, 2025 20:05

mongoKart added a commit that referenced this pull request Mar 10, 2025

DOCSP-46812 - Distribute Type Hints (#167)

56ba281

(cherry picked from commit c4f3895)

mongoKart added a commit that referenced this pull request Mar 10, 2025

DOCSP-46812 - Distribute Type Hints (#167)

a8a010f

(cherry picked from commit c4f3895) (cherry picked from commit 56ba281)

mongoKart added a commit that referenced this pull request Mar 10, 2025

DOCSP-46812 - Distribute Type Hints (#167)

dfe9ac5

(cherry picked from commit c4f3895) (cherry picked from commit 56ba281)

mongoKart added a commit that referenced this pull request Mar 10, 2025

DOCSP-46812 - Distribute Type Hints (#167)

77b792c

(cherry picked from commit c4f3895) (cherry picked from commit 56ba281)

mongoKart added a commit to mongoKart/docs-pymongo that referenced this pull request Mar 10, 2025

DOCSP-46812 - Distribute Type Hints (mongodb#167)

225082a

(cherry picked from commit c4f3895) (cherry picked from commit 56ba281)

		If you use the generic form of the ``MongoClient`` class, your type checker might
		show an error similar to the following:

DOCSP-46812 - Distribute Type Hints #167

DOCSP-46812 - Distribute Type Hints #167

Uh oh!

Conversation

mongoKart commented Feb 6, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Staging Links

Self-Review Checklist

Uh oh!

netlify bot commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-pymongo ready!

Uh oh!

rachel-mack left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rachel-mack left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caseyclements left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

caseyclements left a comment

Choose a reason for hiding this comment

Uh oh!

mongoKart commented Feb 6, 2025 •

edited by github-actions bot

Loading

netlify bot commented Feb 6, 2025 •

edited

Loading