Skip to content

Commit

Permalink
typing docs: Improve the intro to each section (python#105901)
Browse files Browse the repository at this point in the history
  • Loading branch information
AlexWaygood authored Jun 18, 2023
1 parent 6849acb commit 4426279
Showing 1 changed file with 40 additions and 36 deletions.
76 changes: 40 additions & 36 deletions Doc/library/typing.rst
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`.


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.

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

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

0 comments on commit 4426279

Please sign in to comment.