Skip to content

typing docs: Improve the intro to each section #105901

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

Merged
merged 1 commit into from
Jun 18, 2023
Merged

typing docs: Improve the intro to each section #105901

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 40 additions & 36 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,9 @@

--------------

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`.
Comment on lines -26 to +28
Copy link
Member Author

Choose a reason for hiding this comment

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

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.



The function below takes and returns a string and is annotated as follows::
Expand All @@ -47,16 +46,18 @@ For a summary of deprecated features and a deprecation timeline, please see

.. seealso::

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.
Comment on lines -50 to +60
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 huge changes here, this is mostly to improve the Sphinx rendering of the links in the .. seealso box


.. _relevant-peps:

Expand Down Expand Up @@ -654,33 +655,16 @@ can define new custom protocols to fully enjoy structural subtyping
Module contents
===============

The module defines the following classes, functions and decorators.

.. 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*.
Comment on lines -659 to -674
Copy link
Member Author

@AlexWaygood AlexWaygood Jun 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

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.


The ``typing`` module defines the following classes, functions and decorators.

Special typing primitives
-------------------------

Special types
"""""""""""""

These can be used as types in annotations and do not support ``[]``.
These can be used as types in annotations. They do not support subscription
using ``[]``.

.. data:: Any

Expand Down Expand Up @@ -890,7 +874,8 @@ These can be used as types in annotations and do not support ``[]``.
Special forms
"""""""""""""

These can be used as types in annotations using ``[]``, each having a unique syntax.
These can be used as types in annotations. They all support subscription using
``[]``, but each has a unique syntax.

.. data:: Tuple

Expand Down Expand Up @@ -1471,7 +1456,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
Building generic types and type aliases
"""""""""""""""""""""""""""""""""""""""

The following objects are not used directly in annotations. Instead, they are building blocks
The following classes should not be used directly as annotations.
Their intended purpose is to be building blocks
for creating generic types and type aliases.

These objects can be created through special syntax
Expand Down Expand Up @@ -1962,7 +1948,9 @@ without the dedicated syntax, as documented below.
Other special directives
""""""""""""""""""""""""

These are not used in annotations. They are building blocks for declaring types.
These functions and classes should not be used directly as annotations.
Their intended purpose is to be building blocks for creating and declaring
types.

.. class:: NamedTuple

Expand Down Expand Up @@ -2399,7 +2387,8 @@ These are not used in annotations. They are building blocks for declaring types.
Protocols
---------

These protocols are decorated with :func:`runtime_checkable`.
The following protocols are provided by the typing module. All are decorated
with :func:`@runtime_checkable <runtime_checkable>`.

.. class:: SupportsAbs

Expand Down Expand Up @@ -3069,6 +3058,21 @@ Constant
Deprecated aliases
------------------

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

.. _corresponding-to-built-in-types:

Aliases to built-in types
Expand Down