From c5ec51ec8f4508e1f01f6d98ac8364a13da9bec7 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 14:31:02 +0100 Subject: Improve docs for `typing.TypeAlias` (#105372) --- Doc/library/typing.rst | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index f75fb48..50063d0 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -832,19 +832,41 @@ These can be used as types in annotations and do not support ``[]``. .. data:: TypeAlias Special annotation for explicitly declaring a :ref:`type alias `. + For example:: - from typing import TypeAlias + from typing import TypeAlias + + Factors: TypeAlias = list[int] + + ``TypeAlias`` is particularly useful on older Python versions for annotating + aliases that make use of forward references, as it can be hard for type + checkers to distinguish these from normal variable assignments: + + .. testcode:: + + from typing import Generic, TypeAlias, TypeVar + + T = TypeVar("T") + + # "Box" does not exist yet, + # so we have to use quotes for the forward reference on Python <3.12. + # Using ``TypeAlias`` tells the type checker that this is a type alias declaration, + # not a variable assignment to a string. + BoxOfStrings: TypeAlias = "Box[str]" - Factors: TypeAlias = list[int] + class Box(Generic[T]): + @classmethod + def make_box_of_strings(cls) -> BoxOfStrings: ... - See :pep:`613` for more details about explicit type aliases. + See :pep:`613` for more details. .. versionadded:: 3.10 .. deprecated:: 3.12 :data:`TypeAlias` is deprecated in favor of the :keyword:`type` statement, - which creates instances of :class:`TypeAliasType`. + which creates instances of :class:`TypeAliasType` + and which natively supports forward references. Note that while :data:`TypeAlias` and :class:`TypeAliasType` serve similar purposes and have similar names, they are distinct and the latter is not the type of the former. -- cgit v0.12