@@ -40,16 +40,18 @@ Glossary
40
40
ABCs with the :mod: `abc ` module.
41
41
42
42
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 `.
46
46
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.
51
52
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.
53
55
54
56
argument
55
57
A value passed to a :term: `function ` (or :term: `method `) when calling the
@@ -191,11 +193,6 @@ Glossary
191
193
A variable defined in a class and intended to be modified only at
192
194
class level (i.e., not in an instance of the class).
193
195
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
-
199
196
coercion
200
197
The implicit conversion of an instance of one type to another during an
201
198
operation which involves two arguments of the same type. For example,
@@ -388,19 +385,20 @@ Glossary
388
385
and the :ref: `function ` section.
389
386
390
387
function annotation
391
- An :term: `annotation ` of a function, or a method .
388
+ An :term: `annotation ` of a function parameter or return value .
392
389
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::
396
394
397
395
def sum_two_numbers(a: int, b: int) -> int:
398
396
return a + b
399
397
400
- Its syntax is explained in section :ref: `function `.
398
+ Function annotation syntax is explained in section :ref: `function `.
401
399
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.
404
402
405
403
__future__
406
404
A pseudo-module which programmers can use to enable new language features
@@ -1048,17 +1046,42 @@ Glossary
1048
1046
:attr: `~instance.__class__ ` attribute or can be retrieved with
1049
1047
``type(obj) ``.
1050
1048
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
+
1051
1072
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.
1054
1075
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
1057
1078
completion and refactoring.
1058
1079
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 `.
1060
1083
1061
- See also :pep: `483 ` which describe this functionality.
1084
+ See :mod: ` typing ` and :pep: `484 `, which describe this functionality.
1062
1085
1063
1086
universal newlines
1064
1087
A manner of interpreting text streams in which all of the following are
@@ -1068,21 +1091,23 @@ Glossary
1068
1091
:func: `bytes.splitlines ` for an additional use.
1069
1092
1070
1093
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.
1072
1095
1073
- For example, this variable is annotated as taking :class: ` int ` values ::
1096
+ When annotating a variable or a class attribute, assignment is optional ::
1074
1097
1075
- count: int = 0
1098
+ class C:
1099
+ field: 'annotation'
1076
1100
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::
1078
1104
1079
- class C:
1080
- field: int
1105
+ count: int = 0
1081
1106
1082
- Its syntax is explained in section :ref: `annassign `.
1107
+ Variable annotation syntax is explained in section :ref: `annassign `.
1083
1108
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.
1086
1111
1087
1112
virtual environment
1088
1113
A cooperatively isolated runtime environment that allows Python users
0 commit comments