Draft the bare-bones documentation for TypeAlias

python · gvanrossum · Oct 7, 2020 · Oct 3, 2020 · Oct 5, 2020 · Oct 6, 2020
commit c49533f3e066492fe95b7e0ae5312bd571feb210
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -34,6 +34,8 @@ 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.
 
+.. _type-aliases:
+
 Type aliases
 ============
 
@@ -489,6 +491,17 @@ These can be used as types in annotations and do not support ``[]``.
    .. versionadded:: 3.5.4
    .. versionadded:: 3.6.2
 
+.. data:: TypeAlias
+
+   Special annotation for explicitly declaring a :ref:`type alias <type-aliases>`.
+   For example::
+
+    from typing import TypeAlias
+
+    Factors: TypeAlias = list[int]
+
+   .. versionadded:: 3.10
+
 Special forms
 """""""""""""
 

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -82,9 +82,26 @@ New Features
 * :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used
   to require that all the iterables have an equal length.
 
-* :pep:`613`: The :mod:`typing` module now has a special annotation
-  :class:`TypeAlias` to explicitly declare :pep:`484`-compliant type aliases,
-  better differentiating them from regular assignments.
+PEP613: TypeAlias Annotation
+----------------------------
+
+:pep:`484` introduced the concept of type aliases, only requiring them to be
+top-level unannotated assignments. This simplicity sometimes made it difficult
+for type checkers to distinguish between type aliases and ordinary assignments,
+especially when forward references or invalid types were involved. Compare::
+
+   StrCache = 'Cache[str]'  # a type alias
+   LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
+
+Now the :mod:`typing` module has a special annotation :data:`TypeAlias` to
+declare type aliases more explicitly::
+
+   StrCache: TypeAlias = 'Cache[str]'  # a type alias
+   LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
+
+See :pep:`613` for more details.
+
+(Contributed by Mikhail Golubev in :issue:`41923`.)
 
 PEP604: New Type Operator
 -------------------------

diff --git a/Misc/NEWS.d/next/Library/2020-10-03-23-14-50.bpo-41923.Buonw9.rst b/Misc/NEWS.d/next/Library/2020-10-03-23-14-50.bpo-41923.Buonw9.rst
@@ -1 +1 @@
-Implement :pep:`613`, introducing :class:`typing.TypeAlias` annotation.
+Implement :pep:`613`, introducing :data:`typing.TypeAlias` annotation.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		Implement :pep:`613`, introducing :class:`typing.TypeAlias` annotation.
		Implement :pep:`613`, introducing :data:`typing.TypeAlias` annotation.