gh-105286: Improve `typing.py` docstrings #105287

AlexWaygood · 2023-06-04T18:11:00Z

Issue: Improve typing.py docstrings #105286

AlexWaygood

Inline justifications for some of the changes:

AlexWaygood · 2023-06-04T18:11:51Z

Lib/typing.py

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


Many other PEPs have revised the typing spec since PEP 484

AlexWaygood · 2023-06-04T18:13:26Z

Lib/typing.py

-  Any, NoReturn, Never, ClassVar, Union, Optional, Concatenate, Unpack
-* Classes whose instances can be type arguments in addition to types:
-  ForwardRef, TypeVar and ParamSpec
+  NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others.
+* Classes whose instances can be type arguments:
+  TypeVar, ParamSpec, TypeVarTuple.


Any is now its own class, rather than being an instance of _SpecialForm

Numerous other _SpecialForms 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.

AlexWaygood · 2023-06-04T18:13:55Z

Lib/typing.py

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


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

AlexWaygood · 2023-06-04T18:15:09Z

Lib/typing.py

-        _collect_parameters((T, Callable[P, T])) == (T, P)
+        assert _collect_parameters((T, Callable[P, T])) == (T, P)


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 explicit assert is better for this kind of code example.

AlexWaygood · 2023-06-04T18:16:22Z

Lib/typing.py


    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


If AttributeError or TypeError is encountered, the __final__ attribute won't be set.

AlexWaygood · 2023-06-04T18:18:30Z

Lib/typing.py

-    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)])


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, I do think we should remove any mention of the keyword-argument syntax, since this way of creating NamedTuples isn't supported by any type checker that I know of.

hauntsaninja

Looks good to me, two minor comments

Lib/typing.py

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

sobolevn

Thanks!

Lib/typing.py

sobolevn · 2023-06-05T07:39:29Z

Lib/typing.py

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


All points except this one have examples. Is it intentional?

Yeah, they're deprecated ;p

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

Lib/typing.py

JelleZijlstra

Thanks for all the improvements!

miss-islington · 2023-06-05T14:16:13Z

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

miss-islington · 2023-06-05T14:16:16Z

Sorry, @AlexWaygood, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker f714aa2c29eae5cc4b5b54e4d83d83eebd5eac53 3.12

miss-islington · 2023-06-05T14:16:18Z

Sorry @AlexWaygood, I had trouble checking out the 3.11 backport branch.
Please retry by removing and re-adding the "needs backport to 3.11" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker f714aa2c29eae5cc4b5b54e4d83d83eebd5eac53 3.11

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

bedevere-bot · 2023-06-05T14:25:55Z

GH-105319 is a backport of this pull request to the 3.12 branch.

gh-105286: Improve `typing.py` docstrings (#105287) Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

bedevere-bot · 2023-06-05T15:25:31Z

GH-105322 is a backport of this pull request to the 3.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>

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

Improve typing.py docstrings

e808f2b

AlexWaygood requested review from gvanrossum, Fidget-Spinner and JelleZijlstra as code owners June 4, 2023 18:11

bedevere-bot added the awaiting core review label Jun 4, 2023

bedevere-bot mentioned this pull request Jun 4, 2023

Improve typing.py docstrings #105286

Closed

AlexWaygood added skip news topic-typing needs backport to 3.11 only security fixes needs backport to 3.12 bug and security fixes labels Jun 4, 2023

AlexWaygood commented Jun 4, 2023

View reviewed changes

hauntsaninja reviewed Jun 5, 2023

View reviewed changes

Lib/typing.py Outdated Show resolved Hide resolved

Lib/typing.py Outdated Show resolved Hide resolved

Apply suggestions from code review

7f20599

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

sobolevn reviewed Jun 5, 2023

View reviewed changes

AlexWaygood and others added 8 commits June 5, 2023 08:43

Update Lib/typing.py

d59d72b

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

Update Lib/typing.py

f96723e

Colons

9f132e9

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

Use two colons everywhere

e7983b2

Newlines following class docstrings as per PEP 257

ff90369

Nit

d54c06b

Fix first line of NoReturn docstring

ab3e627

Better first sentences

748c55f

JelleZijlstra reviewed Jun 5, 2023

View reviewed changes

Lib/typing.py Outdated Show resolved Hide resolved

Lib/typing.py Outdated Show resolved Hide resolved

Lib/typing.py Show resolved Hide resolved

Lib/typing.py Outdated Show resolved Hide resolved

AlexWaygood added 2 commits June 5, 2023 14:47

Make module docstring more user-facing

f9e27e2

Capitalise Point2D

58fbb0f

JelleZijlstra approved these changes Jun 5, 2023

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting core review labels Jun 5, 2023

AlexWaygood enabled auto-merge (squash) June 5, 2023 13:54

AlexWaygood merged commit f714aa2 into python:main Jun 5, 2023
21 checks passed

bedevere-bot removed the awaiting merge label Jun 5, 2023

miss-islington assigned AlexWaygood Jun 5, 2023

AlexWaygood deleted the improve-typing-docstrings branch June 5, 2023 14:19

AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Jun 5, 2023

pythongh-105286: Improve typing.py docstrings (python#105287)

e4b6cb7

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

bedevere-bot removed the needs backport to 3.12 bug and security fixes label Jun 5, 2023

bedevere-bot removed the needs backport to 3.11 only security fixes label Jun 5, 2023

ambv pushed a commit that referenced this pull request Jun 5, 2023

[3.11] gh-105286: Improve typing.py docstrings (#105287) (#105322)

93d9e99

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

erlend-aasland mentioned this pull request Jun 6, 2023

3.12 backport gh 105236 #105358

Closed

AlexWaygood mentioned this pull request Jun 6, 2023

gh-105286: Further improvements to typing.py docstrings #105363

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-105286: Improve `typing.py` docstrings #105287

gh-105286: Improve `typing.py` docstrings #105287

AlexWaygood commented Jun 4, 2023 •

edited by bedevere-bot

AlexWaygood left a comment

AlexWaygood Jun 4, 2023

AlexWaygood Jun 4, 2023

AlexWaygood Jun 4, 2023

AlexWaygood Jun 4, 2023

AlexWaygood Jun 4, 2023

AlexWaygood Jun 4, 2023 •

edited

hauntsaninja left a comment

sobolevn left a comment

sobolevn Jun 5, 2023

AlexWaygood Jun 5, 2023

JelleZijlstra left a comment

miss-islington commented Jun 5, 2023

miss-islington commented Jun 5, 2023

miss-islington commented Jun 5, 2023

bedevere-bot commented Jun 5, 2023

bedevere-bot commented Jun 5, 2023

		_collect_parameters((T, Callable[P, T])) == (T, P)
		assert _collect_parameters((T, Callable[P, T])) == (T, P)

gh-105286: Improve typing.py docstrings #105287

gh-105286: Improve typing.py docstrings #105287

Conversation

AlexWaygood commented Jun 4, 2023 • edited by bedevere-bot

AlexWaygood left a comment

Choose a reason for hiding this comment

AlexWaygood Jun 4, 2023

Choose a reason for hiding this comment

AlexWaygood Jun 4, 2023

Choose a reason for hiding this comment

AlexWaygood Jun 4, 2023

Choose a reason for hiding this comment

AlexWaygood Jun 4, 2023

Choose a reason for hiding this comment

AlexWaygood Jun 4, 2023

Choose a reason for hiding this comment

AlexWaygood Jun 4, 2023 • edited

Choose a reason for hiding this comment

hauntsaninja left a comment

Choose a reason for hiding this comment

sobolevn left a comment

Choose a reason for hiding this comment

sobolevn Jun 5, 2023

Choose a reason for hiding this comment

AlexWaygood Jun 5, 2023

Choose a reason for hiding this comment

JelleZijlstra left a comment

Choose a reason for hiding this comment

miss-islington commented Jun 5, 2023

miss-islington commented Jun 5, 2023

miss-islington commented Jun 5, 2023

bedevere-bot commented Jun 5, 2023

bedevere-bot commented Jun 5, 2023

gh-105286: Improve `typing.py` docstrings #105287

gh-105286: Improve `typing.py` docstrings #105287

AlexWaygood commented Jun 4, 2023 •

edited by bedevere-bot

AlexWaygood Jun 4, 2023 •

edited