diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 2eab003146829b..16b52670ef20f1 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -39,6 +39,18 @@ Glossary and loaders (in the :mod:`importlib.abc` module). You can create your own ABCs with the :mod:`abc` module. + annotation + A metadata value associated with a global variable, a class attribute or a + function or method parameter or return value, that stores a + :term:`type hint`. + + Annotations are stored in the :attr:`__annotations__` special attribute + of a module (when annotating a global variable), class (when annotating + one of its attributes) or function or method (when annotating a parameter or a + return value) and can be accessed using :func:`typing.get_type_hints`. + + See :pep:`484` and :pep:`526` which describe this functionality. + argument A value passed to a :term:`function` (or :term:`method`) when calling the function. There are two kinds of argument: @@ -175,6 +187,15 @@ Glossary normally contain method definitions which operate on instances of the class. + class variable + 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 `. + + 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, @@ -367,16 +388,19 @@ Glossary and the :ref:`function` section. function annotation - An arbitrary metadata value associated with a function parameter or return - value. Its syntax is explained in section :ref:`function`. Annotations - may be accessed via the :attr:`__annotations__` special attribute of a - function object. + An :term:`annotation` of a function, or a method. + + For example, this function has its parameters annotated as taking + :class:`int` arguments and its return value annotated as being an + :class:`int` as well:: + + def sum_two_numbers(a: int, b: int) -> int: + return a + b - See also the :term:`variable annotation` glossary entry. + Its syntax is explained in section :ref:`function`. - Annotations are meant to provide a standard way for programmers to - document types of functions they design. See :pep:`484`, which - describes this functionality. + See also the :term:`variable annotation` glossary entry, and :pep:`484`, + which describes this functionality. __future__ A pseudo-module which programmers can use to enable new language features @@ -1009,6 +1033,18 @@ Glossary :attr:`~instance.__class__` attribute or can be retrieved with ``type(obj)``. + type hint + A specification about the expected type for a global variable, class + variable, function or method parameter or return value. + + While type hints are optional and are not enforced by Python when used, + they are useful for static type analysis tools, and aid IDEs on code + completion and refactoring. + + Type hints are stored in :term:`annotations `. + + See also :pep:`483` which describe this functionality. + universal newlines A manner of interpreting text streams in which all of the following are recognized as ending a line: the Unix end-of-line convention ``'\n'``, @@ -1017,17 +1053,21 @@ Glossary :func:`bytes.splitlines` for an additional use. variable annotation - A type metadata value associated with a module global variable or - a class attribute. Its syntax is explained in section :ref:`annassign`. - Annotations are stored in the :attr:`__annotations__` special - attribute of a class or module object and can be accessed using - :func:`typing.get_type_hints`. + An :term:`annotation` of a global variable, or a class attribute. + + For example, this variable is annotated as taking :class:`int` values:: + + count: int = 0 + + When annotating variables, assignment is optional:: + + class C: + field: int - See also the :term:`function annotation` glossary entry. + Its syntax is explained in section :ref:`annassign`. - Annotations are meant to provide a standard way for programmers to - document types of functions they design. See :pep:`484` and :pep:`526` - which describe this functionality. + 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