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`.
+ A label associated with a variable, a class
+ attribute or a function parameter or return value,
+ used by convention as 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`.
+ Annotations of local variables cannot be accesed at runtime, but
+ annotations of global variables, class attributes, and functions
+ are stored in the :attr:`__annotations__`
+ 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
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,
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
- :class:`int` arguments and its return value annotated as being an
- :class:`int` as well::
+ Function annotations are usually used for
+ :term:`type hints <type hint>`: for example this function is expected to take two
+ :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`,
- which describes this functionality.
+ See :term:`variable annotation` and :pep:`484`,
+ which describe this functionality.
__future__
A pseudo-module which programmers can use to enable new language features
:attr:`~instance.__class__` attribute or can be retrieved with
``type(obj)``.
+ type alias
+ A synonym for a type, created by assigning the type to an identifier.
+
+ Type aliases are useful for simplifying :term:`type hints <type hint>`.
+ 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
- A specification about the expected type for a global variable, class
- variable, function or method parameter or return value.
+ An :term:`annotation` that specifies the expected type for a variable, a class
+ attribute, or a function 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
+ 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
: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::
- count: int = 0
+ class C:
+ field: 'annotation'
- When annotating variables, assignment is optional::
+ Variable annotations are usually used for
+ :term:`type hints <type hint>`: for example this variable is expected to take
+ :class:`int` values::
- class C:
- field: int
+ count: int = 0
- Its syntax is explained in section :ref:`annassign`.
+ Variable annotation 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.
+ See :term:`function annotation`, :pep:`484`
+ and :pep:`526`, which describe this functionality.
virtual environment
A cooperatively isolated runtime environment that allows Python users
projects / python / commitdiff