From ff1230f17afc06bd2f021abd06b6515590f77934 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Tue, 6 Jun 2023 13:58:13 +0100 Subject: [PATCH 1/4] Improve docs for `typing.TypeAlias` --- 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 a9ea4b9fee3ad4..567b5d8034d8e2 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -805,19 +805,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") + + # "Container" 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. + ContainerOfInts: TypeAlias = "Container[int]" - Factors: TypeAlias = list[int] + class Container(Generic[T]): + @classmethod + def make_container_of_ints(cls) -> ContainerOfInts: ... - 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. From 335e72cd0440ce74f63d5f47c8e67838d1b6ac17 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Tue, 6 Jun 2023 14:05:15 +0100 Subject: [PATCH 2/4] Update Doc/library/typing.rst --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 567b5d8034d8e2..efa84ab162a1a5 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -824,7 +824,7 @@ These can be used as types in annotations and do not support ``[]``. # "Container" 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, + # Using ``TypeAlias`` tells the type checker that this is a type alias declaration, # not a variable assignment to a string. ContainerOfInts: TypeAlias = "Container[int]" From 3bbcc9a86816726f3540a88421cd2dc01cc52d23 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 7 Jun 2023 09:10:56 +0100 Subject: [PATCH 3/4] Box --- Doc/library/typing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 567b5d8034d8e2..0166bbab423e89 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -826,11 +826,11 @@ These can be used as types in annotations and do not support ``[]``. # 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. - ContainerOfInts: TypeAlias = "Container[int]" + BoxOfStrings: TypeAlias = "Box[str]" - class Container(Generic[T]): + class Box(Generic[T]): @classmethod - def make_container_of_ints(cls) -> ContainerOfInts: ... + def make_box_of_strings(cls) -> BoxOfStrings: ... See :pep:`613` for more details. From 68e2f47c1e8017ee4bfea4155381951b052bf722 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 09:12:09 +0100 Subject: [PATCH 4/4] Update Doc/library/typing.rst --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index a430cf2f2a8798..50063d004101ad 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -849,7 +849,7 @@ These can be used as types in annotations and do not support ``[]``. T = TypeVar("T") - # "Container" does not exist yet, + # "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.