-
-
Notifications
You must be signed in to change notification settings - Fork 32k
gh-113255: Clarify docs for typing.reveal_type
#113286
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! Some initial feedback:
I wonder if we can get the same benefit even more concisely by tweaking the existing documentation for this function to be clearer. Specifically, I think the first sentence ("Reveal the inferred static type of an expression.") is potentially misleading, and lends itself to the confusion you had, because it can easily be read to imply that that is what the function does at runtime. I can see two potential ways to adjust this. One would be to simply move the qualifier "inferred static" from the opening sentence to the second paragraph, so that it reads like this:
Alternatively, if we want to continue to feature the static type checker use as the primary purpose (which it is), we could clarify the opening sentence like this instead (using a similar form as already used in the documentation of
Which makes it clear that we are here describing the effect on static type checkers. I think a clarification like one of the above, plus the existing clear use of the term "runtime type" below, might be sufficient to avoid this misunderstanding, without needing to add an entirely new paragraph. I find the newly added paragraph in the current PR cumbersome because a) the first sentence basically repeats what was just said immediately above, and b) the rest of it goes into details about specifically how runtime types and static types can differ, which is a larger topic that I don't think the documentation for If we do still want an additional clarification at the end, I would just add one sentence, something like this:
What do you both think? @AlexWaygood @note35 |
…d shortening the added description.
…nto reveal_type_msg
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @note35, this is looking much better now! Could you also make equivalent changes to the docstring here?
Lines 3304 to 3317 in 5a7cc66
"""Reveal the inferred type of a variable. | |
When a static type checker encounters a call to ``reveal_type()``, | |
it will emit the inferred type of the argument:: | |
x: int = 1 | |
reveal_type(x) | |
Running a static type checker (e.g., mypy) on this example | |
will produce output similar to 'Revealed type is "builtins.int"'. | |
At runtime, the function prints the runtime type of the | |
argument and returns it unchanged. | |
""" |
@carljm Thanks for the comments. I basically agree with you and consider Just one humble insight I want to share for both |
Done. I made a change for only the first two lines of the comment, please let me know if it's sufficient. |
typing.reveal_type
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks! @carljm, anything more from you?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great, thanks all!
Thanks @note35 for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
(cherry picked from commit 11ee912) Co-authored-by: Kir <[email protected]> Co-authored-by: AlexWaygood <[email protected]>
Sorry, @note35 and @AlexWaygood, I could not cleanly backport this to
|
GH-113323 is a backport of this pull request to the 3.12 branch. |
…113323) gh-113255: Clarify docs for `typing.reveal_type` (GH-113286) (cherry picked from commit 11ee912) Co-authored-by: Kir <[email protected]> Co-authored-by: AlexWaygood <[email protected]>
GH-113326 is a backport of this pull request to the 3.11 branch. |
…#113286) (cherry-picked from commit 11ee912) Co-authored-by: AlexWaygood <[email protected]>
…13326) (cherry-picked from commit 11ee912) Co-authored-by: Kir <[email protected]>
Co-authored-by: AlexWaygood <[email protected]>
Co-authored-by: AlexWaygood <[email protected]>
Co-authored-by: AlexWaygood <[email protected]>
Co-authored-by: AlexWaygood <[email protected]>
Why?
The current comment mentioned
reveal_type()
is supported by other type checkers, and with this we can run without runtime errors. This may mislead readers the fact that CPython'sreveal_type()
does not necessary to infer the same type as other type checkers (even though runtime is mentioned many times, but it's not obvious).Initial proposal
The comment by Carl Meyer resolves this confusion. So I suggest adding the comment (with a bit modification to make it concise) to the doc.
📚 Documentation preview 📚: https://cpython-previews--113286.org.readthedocs.build/