bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829)

Doc/glossary.rst

@@ -40,16 +40,18 @@ Glossary
       ABCs with the :mod:`abc` module.
 
    annotation
-      A metadata value associated with a global variable, a class attribute or a
+      A label associated with a variable, a class
-      function or method parameter or return value, that stores a
+      attribute or a function parameter or return value,
-      :term:`type hint`.
+      used by convention as a :term:`type hint`.
 
-      Annotations are stored in the :attr:`__annotations__` special attribute
+      Annotations of local variables cannot be accesed at runtime, but
-      of a module (when annotating a global variable), class (when annotating
+      annotations of global variables, class attributes, and functions
-      one of its attributes) or function or method (when annotating a parameter or a
+      are stored in the :attr:`__annotations__`
-      return value) and can be accessed using :func:`typing.get_type_hints`.
+      special attribute of modules, classes, and functions,
+      respectively.
 
-      See :pep:`484` and :pep:`526` which describe this functionality.
+      See :term:`variable annotation`, :term:`function annotation`, :pep:`484`
+      and :pep:`526`, which describe this functionality.
 
    argument
       A value passed to a :term:`function` (or :term:`method`) when calling the
@@ -191,11 +193,6 @@ Glossary
       A variable defined in a class and intended to be modified only at
       class level (i.e., not in an instance of the class).
 
-      Class variables can be specified as such through
-      :term:`type hints <type hint>`.
-
-      See :pep:`526` which describes class variable annotations.
-
    coercion
       The implicit conversion of an instance of one type to another during an
       operation which involves two arguments of the same type.  For example,
@@ -388,19 +385,20 @@ Glossary
       and the :ref:`function` section.
 
    function annotation
-      An :term:`annotation` of a function, or a method.
+      An :term:`annotation` of a function parameter or return value.
 
-      For example, this function has its parameters annotated as taking
+      Function annotations are usually used for
-      :class:`int` arguments and its return value annotated as being an
+      :term:`type hints <type hint>`: for example this function is expected to take two
-      :class:`int` as well::
+      :class:`int` arguments and is also expected to have an :class:`int`
+      return value::
 
          def sum_two_numbers(a: int, b: int) -> int:
             return a + b
 
-      Its syntax is explained in section :ref:`function`.
+      Function annotation syntax is explained in section :ref:`function`.
 
-      See also the :term:`variable annotation` glossary entry, and :pep:`484`,
+      See :term:`variable annotation` and :pep:`484`,
-      which describes this functionality.
+      which describe this functionality.
 
    __future__
       A pseudo-module which programmers can use to enable new language features
@@ -1048,17 +1046,42 @@ Glossary
       :attr:`~instance.__class__` attribute or can be retrieved with
       ``type(obj)``.
 
-   type hint
+   type alias
-      A specification about the expected type for a global variable, class
+      A synonym for a type, created by assigning the type to an identifier.
-      variable, function or method parameter or return value.
 
-      While type hints are optional and are not enforced by Python when used,
+      Type aliases are useful for simplifying :term:`type hints <type hint>`.
-      they are useful for static type analysis tools, and aid IDEs on code
+      For example::
+
+         from typing import List, Tuple
+
+         def remove_gray_shades(
+                 colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
+             pass
+
+      could be made more readable like this::
+
+         from typing import List, Tuple
+
+         Color = Tuple[int, int, int]
+
+         def remove_gray_shades(colors: List[Color]) -> List[Color]:
+             pass
+
+      See :mod:`typing` and :pep:`484`, which describe this functionality.
+
+   type hint
+      An :term:`annotation` that specifies the expected type for a variable, a class
+      attribute, or a function parameter or return value.
+
+      Type hints are optional and are not enforced by Python but
+      they are useful to static type analysis tools, and aid IDEs with code
       completion and refactoring.
 
-      Type hints are stored in :term:`annotations <annotation>`.
+      Type hints of global variables, class attributes, and functions,
+      but not local variables, can be accessed using
+      :func:`typing.get_type_hints`.
 
-      See also :pep:`483` which describe this functionality.
+      See :mod:`typing` and :pep:`484`, which describe this functionality.
 
    universal newlines
       A manner of interpreting text streams in which all of the following are
@@ -1068,21 +1091,23 @@ Glossary
       :func:`bytes.splitlines` for an additional use.
 
    variable annotation
-      An :term:`annotation` of a global variable, or a class attribute.
+      An :term:`annotation` of a variable or a class attribute.
 
-      For example, this variable is annotated as taking :class:`int` values::
+      When annotating a variable or a class attribute, assignment is optional::
+
+         class C:
+             field: 'annotation'
+
+      Variable annotations are usually used for
+      :term:`type hints <type hint>`: for example this variable is expected to take
+      :class:`int` values::
 
          count: int = 0
 
-      When annotating variables, assignment is optional::
+      Variable annotation syntax is explained in section :ref:`annassign`.
 
-         class C:
+      See :term:`function annotation`, :pep:`484`
-             field: int
+      and :pep:`526`, which describe this functionality.
-
-      Its syntax is explained in section :ref:`annassign`.
-
-      See also the :term:`function annotation` glossary entry, and :pep:`484`
-      and :pep:`526` which describe this functionality.
 
    virtual environment
       A cooperatively isolated runtime environment that allows Python users