Skip to content

Commit 6e33f81

Browse files
andresdelfinoilevkivskyi
authored andcommitted
bpo-32769: A new take on annotations/type hinting glossary entries (GH-6829)
1 parent 19de8b3 commit 6e33f81

File tree

1 file changed

+60
-35
lines changed

1 file changed

+60
-35
lines changed

Doc/glossary.rst

Lines changed: 60 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -40,16 +40,18 @@ Glossary
4040
ABCs with the :mod:`abc` module.
4141

4242
annotation
43-
A metadata value associated with a global variable, a class attribute or a
44-
function or method parameter or return value, that stores a
45-
:term:`type hint`.
43+
A label associated with a variable, a class
44+
attribute or a function parameter or return value,
45+
used by convention as a :term:`type hint`.
4646

47-
Annotations are stored in the :attr:`__annotations__` special attribute
48-
of a module (when annotating a global variable), class (when annotating
49-
one of its attributes) or function or method (when annotating a parameter or a
50-
return value) and can be accessed using :func:`typing.get_type_hints`.
47+
Annotations of local variables cannot be accesed at runtime, but
48+
annotations of global variables, class attributes, and functions
49+
are stored in the :attr:`__annotations__`
50+
special attribute of modules, classes, and functions,
51+
respectively.
5152

52-
See :pep:`484` and :pep:`526` which describe this functionality.
53+
See :term:`variable annotation`, :term:`function annotation`, :pep:`484`
54+
and :pep:`526`, which describe this functionality.
5355

5456
argument
5557
A value passed to a :term:`function` (or :term:`method`) when calling the
@@ -191,11 +193,6 @@ Glossary
191193
A variable defined in a class and intended to be modified only at
192194
class level (i.e., not in an instance of the class).
193195

194-
Class variables can be specified as such through
195-
:term:`type hints <type hint>`.
196-
197-
See :pep:`526` which describes class variable annotations.
198-
199196
coercion
200197
The implicit conversion of an instance of one type to another during an
201198
operation which involves two arguments of the same type. For example,
@@ -388,19 +385,20 @@ Glossary
388385
and the :ref:`function` section.
389386

390387
function annotation
391-
An :term:`annotation` of a function, or a method.
388+
An :term:`annotation` of a function parameter or return value.
392389

393-
For example, this function has its parameters annotated as taking
394-
:class:`int` arguments and its return value annotated as being an
395-
:class:`int` as well::
390+
Function annotations are usually used for
391+
:term:`type hints <type hint>`: for example this function is expected to take two
392+
:class:`int` arguments and is also expected to have an :class:`int`
393+
return value::
396394

397395
def sum_two_numbers(a: int, b: int) -> int:
398396
return a + b
399397

400-
Its syntax is explained in section :ref:`function`.
398+
Function annotation syntax is explained in section :ref:`function`.
401399

402-
See also the :term:`variable annotation` glossary entry, and :pep:`484`,
403-
which describes this functionality.
400+
See :term:`variable annotation` and :pep:`484`,
401+
which describe this functionality.
404402

405403
__future__
406404
A pseudo-module which programmers can use to enable new language features
@@ -1048,17 +1046,42 @@ Glossary
10481046
:attr:`~instance.__class__` attribute or can be retrieved with
10491047
``type(obj)``.
10501048

1049+
type alias
1050+
A synonym for a type, created by assigning the type to an identifier.
1051+
1052+
Type aliases are useful for simplifying :term:`type hints <type hint>`.
1053+
For example::
1054+
1055+
from typing import List, Tuple
1056+
1057+
def remove_gray_shades(
1058+
colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
1059+
pass
1060+
1061+
could be made more readable like this::
1062+
1063+
from typing import List, Tuple
1064+
1065+
Color = Tuple[int, int, int]
1066+
1067+
def remove_gray_shades(colors: List[Color]) -> List[Color]:
1068+
pass
1069+
1070+
See :mod:`typing` and :pep:`484`, which describe this functionality.
1071+
10511072
type hint
1052-
A specification about the expected type for a global variable, class
1053-
variable, function or method parameter or return value.
1073+
An :term:`annotation` that specifies the expected type for a variable, a class
1074+
attribute, or a function parameter or return value.
10541075

1055-
While type hints are optional and are not enforced by Python when used,
1056-
they are useful for static type analysis tools, and aid IDEs on code
1076+
Type hints are optional and are not enforced by Python but
1077+
they are useful to static type analysis tools, and aid IDEs with code
10571078
completion and refactoring.
10581079

1059-
Type hints are stored in :term:`annotations <annotation>`.
1080+
Type hints of global variables, class attributes, and functions,
1081+
but not local variables, can be accessed using
1082+
:func:`typing.get_type_hints`.
10601083

1061-
See also :pep:`483` which describe this functionality.
1084+
See :mod:`typing` and :pep:`484`, which describe this functionality.
10621085

10631086
universal newlines
10641087
A manner of interpreting text streams in which all of the following are
@@ -1068,21 +1091,23 @@ Glossary
10681091
:func:`bytes.splitlines` for an additional use.
10691092

10701093
variable annotation
1071-
An :term:`annotation` of a global variable, or a class attribute.
1094+
An :term:`annotation` of a variable or a class attribute.
10721095

1073-
For example, this variable is annotated as taking :class:`int` values::
1096+
When annotating a variable or a class attribute, assignment is optional::
10741097

1075-
count: int = 0
1098+
class C:
1099+
field: 'annotation'
10761100

1077-
When annotating variables, assignment is optional::
1101+
Variable annotations are usually used for
1102+
:term:`type hints <type hint>`: for example this variable is expected to take
1103+
:class:`int` values::
10781104

1079-
class C:
1080-
field: int
1105+
count: int = 0
10811106

1082-
Its syntax is explained in section :ref:`annassign`.
1107+
Variable annotation syntax is explained in section :ref:`annassign`.
10831108

1084-
See also the :term:`function annotation` glossary entry, and :pep:`484`
1085-
and :pep:`526` which describe this functionality.
1109+
See :term:`function annotation`, :pep:`484`
1110+
and :pep:`526`, which describe this functionality.
10861111

10871112
virtual environment
10881113
A cooperatively isolated runtime environment that allows Python users

0 commit comments

Comments
 (0)