Skip to content

Improve the typing docs #92264

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 3 commits into from
May 3, 2022
Merged

Improve the typing docs #92264

merged 3 commits into from
May 3, 2022

Conversation

JelleZijlstra
Copy link
Member

I started out noticing that the link here is broken:
https://docs.python.org/3.11/library/typing.html#typing.assert_never

Then I decided to read through the whole thing and look
for other issues. I'll comment on specific things that need
explanation.

I'll backport this to 3.9 and 3.10 as much as it is applicable.

@bedevere-bot bedevere-bot added docs Documentation in the Doc dir awaiting core review labels May 3, 2022
JelleZijlstra
JelleZijlstra commented May 3, 2022
View reviewed changes
Doc/library/typing.rst
@@ -125,7 +125,7 @@ Note that ``None`` as a type hint is a special case and is replaced by
NewType
=======

Use the :class:`NewType` helper class to create distinct types::
Use the :class:`NewType` helper to create distinct types::
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's an implementation detail whether it is a class or a function, so avoid being specific.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An alternative would be "helper callable", but I think "helper" is also fine.

Doc/library/typing.rst
@@ -880,7 +880,6 @@ These can be used as types in annotations using ``[]``, each having a unique syn

def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
'''A type-safe decorator which provides a lock.'''
global my_lock
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not needed since we're not writing to the variable

Doc/library/typing.rst
@@ -1036,7 +1035,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
``no_type_check`` functionality that currently exists in the ``typing``
module which completely disables typechecking annotations on a function
or a class, the ``Annotated`` type allows for both static typechecking
of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``)
of ``T`` (which can safely ignore ``x``)
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to call out specific type checkers here

Doc/library/typing.rst
@@ -1695,7 +1694,7 @@ These are not used in annotations. They are building blocks for declaring types.
in 3.13. It may also be unsupported by static type checkers.

The functional syntax should also be used when any of the keys are not valid
:ref:`identifiers`, for example because they are keywords or contain hyphens.
:ref:`identifiers <identifiers>`, for example because they are keywords or contain hyphens.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This showed up as "Identifiers and keywords" (the section title over there).

AlexWaygood
AlexWaygood reviewed May 3, 2022
View reviewed changes
AlexWaygood
AlexWaygood reviewed May 3, 2022
View reviewed changes
AlexWaygood
AlexWaygood approved these changes May 3, 2022
View reviewed changes
Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow there were a lot of markup errors.

@AlexWaygood
Copy link
Member

Here's a pdf of what the docs look like with these changes:

typing — Support for type hints — Python 3.11.0a7 documentation.pdf

@JelleZijlstra JelleZijlstra added needs backport to 3.9 only security fixes needs backport to 3.10 only security fixes labels May 3, 2022
@JelleZijlstra JelleZijlstra merged commit 27e3665 into python:main May 3, 2022
@miss-islington
Copy link
Contributor

Thanks @JelleZijlstra for the PR 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖

@JelleZijlstra JelleZijlstra deleted the typingdocs branch May 3, 2022 21:49
@miss-islington
Copy link
Contributor

Sorry, @JelleZijlstra, I could not cleanly backport this to 3.10 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 27e366571590e9e98f61dccf69dbeaa88ee66737 3.10

@miss-islington
Copy link
Contributor

Sorry @JelleZijlstra, I had trouble checking out the 3.9 backport branch.
Please backport using cherry_picker on command line.
cherry_picker 27e366571590e9e98f61dccf69dbeaa88ee66737 3.9

JelleZijlstra added a commit to JelleZijlstra/cpython that referenced this pull request May 3, 2022
@JelleZijlstra
[3.10] Improve the typing docs (pythonGH-92264)
1697373 
Co-authored-by: Alex Waygood <[email protected]>.
(cherry picked from commit 27e3665)

Co-authored-by: Jelle Zijlstra <[email protected]>
@bedevere-bot
Copy link

GH-92270 is a backport of this pull request to the 3.10 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.10 only security fixes label May 3, 2022
JelleZijlstra added a commit to JelleZijlstra/cpython that referenced this pull request May 3, 2022
@JelleZijlstra
[3.9] Improve the typing docs (pythonGH-92264)
5aba14f 
Co-authored-by: Alex Waygood <[email protected]>.
(cherry picked from commit 27e3665)

Co-authored-by: Jelle Zijlstra <[email protected]>
@bedevere-bot bedevere-bot removed the needs backport to 3.9 only security fixes label May 3, 2022
@bedevere-bot
Copy link

GH-92271 is a backport of this pull request to the 3.9 branch.

JelleZijlstra added a commit that referenced this pull request May 3, 2022
@JelleZijlstra
[3.10] Improve the typing docs (GH-92264) (#92270)
31d9a88 
Co-authored-by: Alex Waygood <[email protected]>.
(cherry picked from commit 27e3665)

Co-authored-by: Jelle Zijlstra <[email protected]>
JelleZijlstra added a commit that referenced this pull request May 3, 2022
@JelleZijlstra
[3.9] Improve the typing docs (GH-92264) (#92271)
187cb95 
Co-authored-by: Alex Waygood <[email protected]>.
(cherry picked from commit 27e3665)

Co-authored-by: Jelle Zijlstra <[email protected]>
hello-adam pushed a commit to hello-adam/cpython that referenced this pull request Jun 2, 2022
@JelleZijlstra @hello-adam
[3.9] Improve the typing docs (pythonGH-92264) (python#92271)
ff555a7 
Co-authored-by: Alex Waygood <[email protected]>.
(cherry picked from commit 27e3665)

Co-authored-by: Jelle Zijlstra <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@AlexWaygood AlexWaygood AlexWaygood approved these changes

@gvanrossum gvanrossum Awaiting requested review from gvanrossum

@Fidget-Spinner Fidget-Spinner Awaiting requested review from Fidget-Spinner

Assignees

@JelleZijlstra JelleZijlstra

Labels
docs Documentation in the Doc dir skip issue skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@JelleZijlstra @AlexWaygood @miss-islington @bedevere-bot