typing docs: Improve the intro to each section #105901
Conversation
AlexWaygood
added
skip issue
skip news
needs backport to 3.11
AlexWaygood
requested review from
gvanrossum,
Fidget-Spinner and
JelleZijlstra
as code owners
| This module provides runtime support for type hints. The most fundamental | ||
| support consists of the types :data:`Any`, :data:`Union`, :data:`Callable`, | ||
| :class:`TypeVar`, and :class:`Generic`. For a specification, please see | ||
| :pep:`484`. For a simplified introduction to type hints, see :pep:`483`. | ||
| This module provides runtime support for type hints. For the original | ||
| specification of the typing system, see :pep:`484`. For a simplified | ||
| introduction to type hints, see :pep:`483`. |
There was a problem hiding this comment.
Union is "soft-deprecated"; Callable is deprecated; following PEP-695, we prefer for people not to instantiate TypeVars directly or to inherit from Generic directly. I feel like this list doesn't serve much purpose anymore, so it's better to just delete it.
Also, describe PEP-484 as the "original specification" rather than "the specification". The typing system has evolved a lot since then.
| For a quick overview of type hints, refer to | ||
| `this cheat sheet <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_. | ||
| `"Typing cheat sheet" <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_ | ||
| A quick overview of type hints (hosted at the mypy docs) | ||
|
|
||
| The "Type System Reference" section of https://mypy.readthedocs.io/ -- since | ||
| the Python typing system is standardised via PEPs, this reference should | ||
| broadly apply to most Python type checkers, although some parts may still be | ||
| specific to mypy. | ||
| "Type System Reference" section of `the mypy docs <https://mypy.readthedocs.io/en/stable/index.html>`_ | ||
| The Python typing system is standardised via PEPs, so this reference | ||
| should broadly apply to most Python type checkers. (Some parts may still | ||
| be specific to mypy.) | ||
|
|
||
| The documentation at https://typing.readthedocs.io/ serves as useful reference | ||
| for type system features, useful typing related tools and typing best practices. | ||
| `"Static Typing with Python" <https://typing.readthedocs.io/en/latest/>`_ | ||
| Type-checker-agnostic documentation written by the community detailing | ||
| type system features, useful typing related tools and typing best | ||
| practices. |
There was a problem hiding this comment.
No huge changes here, this is mostly to improve the Sphinx rendering of the links in the .. seealso box
| .. note:: | ||
|
|
||
| This module defines several deprecated aliases to pre-existing | ||
| standard library classes. These were originally included in the typing | ||
| module in order to support parameterizing these generic classes using ``[]``. | ||
| However, the aliases became redundant in Python 3.9 when the | ||
| corresponding pre-existing classes were enhanced to support ``[]``. | ||
|
|
||
| The redundant types are deprecated as of Python 3.9 but no | ||
| deprecation warnings are issued by the interpreter. | ||
| It is expected that type checkers will flag the deprecated types | ||
| when the checked program targets Python 3.9 or newer. | ||
|
|
||
| The deprecated types will be removed from the :mod:`typing` module | ||
| no sooner than the first Python version released 5 years after the release of Python 3.9.0. | ||
| See details in :pep:`585`—*Type Hinting Generics In Standard Collections*. |
There was a problem hiding this comment.
I moved this note down so it's immediately above the section where nearly all the deprecated things are.
Some deprecated things (typing.Callable, typing.Tuple) are in the "Special Forms" section rather than the "Deprecated aliases" section. But I still think this note makes more sense immediately above the "Deprecated aliases" section.
|
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 |
|
GH-105902 is a backport of this pull request to the 3.12 branch. |
(cherry picked from commit 4426279) Co-authored-by: Alex Waygood <[email protected]>
…05902) typing docs: Improve the intro to each section (GH-105901) (cherry picked from commit 4426279) Co-authored-by: Alex Waygood <[email protected]>
|
GH-105903 is a backport of this pull request to the 3.11 branch. |
This PR splits off the hopefully-less-controversial parts of #105827 :-)
📚 Documentation preview 📚: https://cpython-previews--105901.org.readthedocs.build/