Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork32.4k
gh-105286: Improvetyping.py
docstrings#105287
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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
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.
Inline justifications for some of the changes:
@@ -1,20 +1,21 @@ | |||
""" | |||
The typing module: Support for gradual typing as defined by PEP 484. | |||
The typing module: Support for gradual typing as defined by PEP 484 and subsequent PEPs. |
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.
Many other PEPs have revised the typing spec since PEP 484
Lib/typing.py Outdated
Any,NoReturn, Never, ClassVar,Union, Optional,Concatenate, Unpack | ||
* Classes whose instances can be type arguments in addition to types: | ||
ForwardRef, TypeVar andParamSpec | ||
NoReturn, Never, ClassVar,Self,Concatenate, Unpack, and others. | ||
* Classes whose instances can be type arguments: | ||
TypeVar,ParamSpec, TypeVarTuple. |
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.
Any
is now its own class, rather than being an instance of_SpecialForm
- Numerous other
_SpecialForm
s have now been added. Rather than attempting to list them all (which would just go out of date again), I've just added "and others" at the end of an abbreviated list. - Instances of
ForwardRef
aren't actually accepted by type checkers as type annotations, as far as I know, so that was somewhat confusing here.
* Public helper functions: get_type_hints, overload, cast, no_type_check, | ||
no_type_check_decorator. | ||
* Generic aliases for collections.abc ABCs and few additional protocols. | ||
* Public helper functions: get_type_hints, overload, cast, final, and others. |
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.
Many other public helper functions have been added that aren't listed here, so I just made it an abbreviated list and put "and others" at the end
Lib/typing.py Outdated
_collect_parameters((T, Callable[P, T])) == (T, P) | ||
assert_collect_parameters((T, Callable[P, T])) == (T, P) |
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.
Guido mentioned in#101827 that he didn't like this style of code example, where it's not really a REPL example, but also isn't something you'd ever put in an executable.py
file either. I agree that using an explicitassert
is better for this kind of code example.
There is no runtime checking of these properties. The decorator | ||
sets the ``__final__`` attribute to ``True`` on the decorated object | ||
to allow runtime introspection. | ||
attempts to set the ``__final__`` attribute to ``True`` on the decorated |
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.
IfAttributeError
orTypeError
is encountered, the__final__
attribute won't be set.
Alternative equivalent keyword syntax is also accepted:: | ||
Employee = NamedTuple('Employee', name=str, id=int) | ||
An alternative equivalent functional syntax is also accepted:: | ||
Employee = NamedTuple('Employee', [('name', str), ('id', int)]) |
AlexWaygoodJun 4, 2023 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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.
This is a partial revert of#104945.
#104945 removed any mention of the functional syntax from this docstring. I agree with removing the mention of Python 3.5 from the docstring (also done in#104945), but I disagree with removing any mention of the functional syntax. The functional syntax is supported by type checkers, and still quite common in many codebases.
However, Ido think we should remove any mention of the keyword-argument syntax, since this way of creatingNamedTuple
sisn't supported by any type checker that I know of.
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 good to me, two minor comments
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
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!
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Lib/typing.py Outdated
no_type_check_decorator. | ||
* Generic aliases for collections.abc ABCs and few additional protocols. | ||
* Public helper functions: get_type_hints, overload, cast, final, and others. | ||
* Deprecated aliases for collections.abc ABCs. |
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.
All points except this one have examples. Is it intentional?
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.
Yeah, they're deprecated ;p
Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
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 for all the improvements!
Thanks@AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
Sorry,@AlexWaygood, I could not cleanly backport this to |
Sorry@AlexWaygood, I had trouble checking out the |
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
bedevere-bot commentedJun 5, 2023
GH-105319 is a backport of this pull request to the3.12 branch. |
bedevere-bot commentedJun 5, 2023
GH-105322 is a backport of this pull request to the3.11 branch. |
pythongh-105286: Improve `typing.py` docstrings (python#105287)Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Uh oh!
There was an error while loading.Please reload this page.
typing.py
docstrings #105286