Skip to content

Link to the Python type system specification #117400

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
Mar 31, 2024
Merged

Link to the Python type system specification #117400

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
88 changes: 15 additions & 73 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,27 +23,25 @@

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

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`.
This module provides runtime support for type hints.

Consider the function below::

The function below takes and returns a string and is annotated as follows::
def moon_weight(earth_weight: float) -> str:
return f'On the moon, you would weigh {earth_weight * 0.166} kilograms.'

def greeting(name: str) -> str:
return 'Hello ' + name
The function ``moon_weight`` takes an argument expected to be an instance of :class:`float`,
as indicated by the *type hint* ``earth_weight: float``. The function is expected to
return an instance of :class:`str`, as indicated by the ``-> str`` hint.

In the function ``greeting``, the argument ``name`` is expected to be of type
:class:`str` and the return type :class:`str`. Subtypes are accepted as
arguments.
While type hints can be simple classes like :class:`float` or :class:`str`,
they can also be more complex. The :mod:`typing` module provides a vocabulary of
more advanced type hints.

New features are frequently added to the ``typing`` module.
The `typing_extensions <https://pypi.org/project/typing-extensions/>`_ package
provides backports of these new features to older versions of Python.

For a summary of deprecated features and a deprecation timeline, please see
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I didn't see a need for this to be that prominently mentioned (it's also just a bit of a downer for this to be the first thing people read) — but happy to add back if people think it's useful to mention up top!

`Deprecation Timeline of Major Features`_.

.. seealso::

`"Typing cheat sheet" <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_
Expand All @@ -61,67 +59,11 @@ For a summary of deprecated features and a deprecation timeline, please see

.. _relevant-peps:

Relevant PEPs
=============

Since the initial introduction of type hints in :pep:`484` and :pep:`483`, a
number of PEPs have modified and enhanced Python's framework for type
annotations:

.. raw:: html

<details>
<summary><a style="cursor:pointer;">The full list of PEPs</a></summary>

* :pep:`526`: Syntax for Variable Annotations
*Introducing* syntax for annotating variables outside of function
definitions, and :data:`ClassVar`
* :pep:`544`: Protocols: Structural subtyping (static duck typing)
*Introducing* :class:`Protocol` and the
:func:`@runtime_checkable<runtime_checkable>` decorator
* :pep:`585`: Type Hinting Generics In Standard Collections
*Introducing* :class:`types.GenericAlias` and the ability to use standard
library classes as :ref:`generic types<types-genericalias>`
* :pep:`586`: Literal Types
*Introducing* :data:`Literal`
* :pep:`589`: TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys
*Introducing* :class:`TypedDict`
* :pep:`591`: Adding a final qualifier to typing
*Introducing* :data:`Final` and the :func:`@final<final>` decorator
* :pep:`593`: Flexible function and variable annotations
*Introducing* :data:`Annotated`
* :pep:`604`: Allow writing union types as ``X | Y``
*Introducing* :data:`types.UnionType` and the ability to use
the binary-or operator ``|`` to signify a
:ref:`union of types<types-union>`
* :pep:`612`: Parameter Specification Variables
*Introducing* :class:`ParamSpec` and :data:`Concatenate`
* :pep:`613`: Explicit Type Aliases
*Introducing* :data:`TypeAlias`
* :pep:`646`: Variadic Generics
*Introducing* :data:`TypeVarTuple`
* :pep:`647`: User-Defined Type Guards
*Introducing* :data:`TypeGuard`
* :pep:`655`: Marking individual TypedDict items as required or potentially missing
*Introducing* :data:`Required` and :data:`NotRequired`
* :pep:`673`: Self type
*Introducing* :data:`Self`
* :pep:`675`: Arbitrary Literal String Type
*Introducing* :data:`LiteralString`
* :pep:`681`: Data Class Transforms
*Introducing* the :func:`@dataclass_transform<dataclass_transform>` decorator
* :pep:`692`: Using ``TypedDict`` for more precise ``**kwargs`` typing
*Introducing* a new way of typing ``**kwargs`` with :data:`Unpack` and
:data:`TypedDict`
* :pep:`695`: Type Parameter Syntax
*Introducing* builtin syntax for creating generic functions, classes, and type aliases.
* :pep:`698`: Adding an override decorator to typing
*Introducing* the :func:`@override<override>` decorator

.. raw:: html

</details>
<br>
Specification for the Python Type System
========================================

The canonical, up-to-date specification of the Python type system can be
found at `"Specification for the Python type system" <https://typing.readthedocs.io/en/latest/spec/index.html>`_.

.. _type-aliases:

Expand Down