Skip to content

Commit 8bb16f6

Browse files
authored
[3.11] typing docs: Improve the intro to each section (#105901) (#105903)
typing docs: Improve the intro to each section (#105901)
1 parent 043c831 commit 8bb16f6

File tree

1 file changed

+40
-36
lines changed

1 file changed

+40
-36
lines changed

Doc/library/typing.rst

Lines changed: 40 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,9 @@
2323

2424
--------------
2525

26-
This module provides runtime support for type hints. The most fundamental
27-
support consists of the types :data:`Any`, :data:`Union`, :data:`Callable`,
28-
:class:`TypeVar`, and :class:`Generic`. For a specification, please see
29-
:pep:`484`. For a simplified introduction to type hints, see :pep:`483`.
26+
This module provides runtime support for type hints. For the original
27+
specification of the typing system, see :pep:`484`. For a simplified
28+
introduction to type hints, see :pep:`483`.
3029

3130

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

4847
.. seealso::
4948

50-
For a quick overview of type hints, refer to
51-
`this cheat sheet <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_.
49+
`"Typing cheat sheet" <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_
50+
A quick overview of type hints (hosted at the mypy docs)
5251

53-
The "Type System Reference" section of https://mypy.readthedocs.io/ -- since
54-
the Python typing system is standardised via PEPs, this reference should
55-
broadly apply to most Python type checkers, although some parts may still be
56-
specific to mypy.
52+
"Type System Reference" section of `the mypy docs <https://mypy.readthedocs.io/en/stable/index.html>`_
53+
The Python typing system is standardised via PEPs, so this reference
54+
should broadly apply to most Python type checkers. (Some parts may still
55+
be specific to mypy.)
5756

58-
The documentation at https://typing.readthedocs.io/ serves as useful reference
59-
for type system features, useful typing related tools and typing best practices.
57+
`"Static Typing with Python" <https://typing.readthedocs.io/en/latest/>`_
58+
Type-checker-agnostic documentation written by the community detailing
59+
type system features, useful typing related tools and typing best
60+
practices.
6061

6162
.. _relevant-peps:
6263

@@ -606,33 +607,16 @@ can define new custom protocols to fully enjoy structural subtyping
606607
Module contents
607608
===============
608609

609-
The module defines the following classes, functions and decorators.
610-
611-
.. note::
612-
613-
This module defines several deprecated aliases to pre-existing
614-
standard library classes. These were originally included in the typing
615-
module in order to support parameterizing these generic classes using ``[]``.
616-
However, the aliases became redundant in Python 3.9 when the
617-
corresponding pre-existing classes were enhanced to support ``[]``.
618-
619-
The redundant types are deprecated as of Python 3.9 but no
620-
deprecation warnings are issued by the interpreter.
621-
It is expected that type checkers will flag the deprecated types
622-
when the checked program targets Python 3.9 or newer.
623-
624-
The deprecated types will be removed from the :mod:`typing` module
625-
no sooner than the first Python version released 5 years after the release of Python 3.9.0.
626-
See details in :pep:`585`—*Type Hinting Generics In Standard Collections*.
627-
610+
The ``typing`` module defines the following classes, functions and decorators.
628611

629612
Special typing primitives
630613
-------------------------
631614

632615
Special types
633616
"""""""""""""
634617

635-
These can be used as types in annotations and do not support ``[]``.
618+
These can be used as types in annotations. They do not support subscription
619+
using ``[]``.
636620

637621
.. data:: Any
638622

@@ -832,7 +816,8 @@ These can be used as types in annotations and do not support ``[]``.
832816
Special forms
833817
"""""""""""""
834818

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

837822
.. data:: Tuple
838823

@@ -1397,7 +1382,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
13971382
Building generic types
13981383
""""""""""""""""""""""
13991384

1400-
The following objects are not used directly in annotations. Instead, they are building blocks
1385+
The following classes should not be used directly as annotations.
1386+
Their intended purpose is to be building blocks
14011387
for creating generic types.
14021388

14031389
.. class:: Generic
@@ -1738,7 +1724,9 @@ for creating generic types.
17381724
Other special directives
17391725
""""""""""""""""""""""""
17401726

1741-
These are not used in annotations. They are building blocks for declaring types.
1727+
These functions and classes should not be used directly as annotations.
1728+
Their intended purpose is to be building blocks for creating and declaring
1729+
types.
17421730

17431731
.. class:: NamedTuple
17441732

@@ -2125,7 +2113,8 @@ These are not used in annotations. They are building blocks for declaring types.
21252113
Protocols
21262114
---------
21272115

2128-
These protocols are decorated with :func:`runtime_checkable`.
2116+
The following protocols are provided by the typing module. All are decorated
2117+
with :func:`@runtime_checkable <runtime_checkable>`.
21292118

21302119
.. class:: SupportsAbs
21312120

@@ -2716,6 +2705,21 @@ Constant
27162705
Deprecated aliases
27172706
------------------
27182707

2708+
This module defines several deprecated aliases to pre-existing
2709+
standard library classes. These were originally included in the typing
2710+
module in order to support parameterizing these generic classes using ``[]``.
2711+
However, the aliases became redundant in Python 3.9 when the
2712+
corresponding pre-existing classes were enhanced to support ``[]``.
2713+
2714+
The redundant types are deprecated as of Python 3.9 but no
2715+
deprecation warnings are issued by the interpreter.
2716+
It is expected that type checkers will flag the deprecated types
2717+
when the checked program targets Python 3.9 or newer.
2718+
2719+
The deprecated types will be removed from the :mod:`typing` module
2720+
no sooner than the first Python version released 5 years after the release of Python 3.9.0.
2721+
See details in :pep:`585`—*Type Hinting Generics In Standard Collections*.
2722+
27192723
.. _corresponding-to-built-in-types:
27202724

27212725
Aliases to built-in types

0 commit comments

Comments
 (0)