Составные инструкции

8.1. Инструкция if

Инструкция if используется для условного выполнения:

if_stmt: "if" assignment_expression ":" suite
         ("elif" assignment_expression ":" suite)*
         ["else" ":" suite]

Она выбирает ровно один блок, последовательно вычисляя выражения, пока одно из них не окажется истинным (определения истинности и ложности см. в разделе Логические операции); затем выполняется этот блок (а остальные части инструкции if не выполняются и не вычисляются). Если все выражения ложны, выполняется блок части else, если она присутствует.

8.2. Инструкция while

Инструкция while используется для многократного выполнения, пока выражение истинно:

while_stmt: "while" assignment_expression ":" suite
            ["else" ":" suite]

Выражение проверяется повторно, и, если оно истинно, выполняется первый блок; если выражение ложно (возможно, уже при первой проверке), выполняется блок части else, если она присутствует, и цикл завершается.

Инструкция break, выполненная в первом блоке, завершает цикл, не выполняя блок части else. Инструкция continue, выполненная в первом блоке, пропускает оставшуюся часть блока и возвращается к проверке выражения.

8.3. Инструкция for

Инструкция for используется для перебора элементов последовательности (например, строки, кортежа или списка) либо другого итерируемого объекта:

for_stmt: "for" target_list "in" starred_expression_list ":" suite
          ["else" ":" suite]

Выражение starred_expression_list вычисляется один раз; в результате должен получиться итерируемый объект. Для этого объекта создаётся итератор. Первый элемент, предоставленный итератором, присваивается целевому списку по стандартным правилам присваивания (см. раздел Инструкции присваивания), после чего выполняется блок. Это повторяется для каждого элемента, предоставленного итератором. Когда элементы итератора заканчиваются, выполняется блок части else, если она присутствует, и цикл завершается.

Инструкция break, выполненная в первом блоке, завершает цикл, не выполняя блок части else. Инструкция continue, выполненная в первом блоке, пропускает оставшуюся часть блока и переходит к следующему элементу либо к части else, если следующего элемента нет.

Цикл for присваивает значения переменным из целевого списка. При этом перезаписываются все предыдущие значения этих переменных, включая присвоенные в блоке цикла for:

for i in range(10):
    print(i)
    i = 5             # this will not affect the for-loop
                      # because i will be overwritten with the next
                      # index in the range

Имена в целевом списке не удаляются после завершения цикла, но если последовательность пуста, цикл не присвоит им никаких значений. Подсказка: встроенный тип range() представляет неизменяемые арифметические последовательности целых чисел. Например, последовательный перебор range(3) возвращает 0, 1, а затем 2.

8.4. Инструкция try

Инструкция try задаёт обработчики исключений и/или код очистки для группы инструкций:

try_stmt:  try1_stmt | try2_stmt | try3_stmt
try1_stmt: "try" ":" suite
           ("except" [expression ["as" identifier]] ":" suite)+
           ["else" ":" suite]
           ["finally" ":" suite]
try2_stmt: "try" ":" suite
           ("except" "*" expression ["as" identifier] ":" suite)+
           ["else" ":" suite]
           ["finally" ":" suite]
try3_stmt: "try" ":" suite
           "finally" ":" suite

Дополнительные сведения об исключениях приведены в разделе Исключения, а сведения об использовании инструкции raise для генерации исключений можно найти в разделе Инструкция raise.

except E as N:
    foo

except E as N:
    try:
        foo
    finally:
        del N

>>> print(sys.exception())
None
>>> try:
...     raise TypeError
... except:
...     print(repr(sys.exception()))
...     try:
...          raise ValueError
...     except:
...         print(repr(sys.exception()))
...     print(repr(sys.exception()))
...
TypeError()
ValueError()
TypeError()
>>> print(sys.exception())
None

>>> try:
...     raise ExceptionGroup("eg",
...         [ValueError(1), TypeError(2), OSError(3), OSError(4)])
... except* TypeError as e:
...     print(f'caught {type(e)} with nested {e.exceptions}')
... except* OSError as e:
...     print(f'caught {type(e)} with nested {e.exceptions}')
...
caught <class 'ExceptionGroup'> with nested (TypeError(2),)
caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
  + Exception Group Traceback (most recent call last):
  |   File "<doctest default[0]>", line 2, in <module>
  |     raise ExceptionGroup("eg",
  |         [ValueError(1), TypeError(2), OSError(3), OSError(4)])
  | ExceptionGroup: eg (1 sub-exception)
  +-+---------------- 1 ----------------
    | ValueError: 1
    +------------------------------------

>>> try:
...     raise BlockingIOError
... except* BlockingIOError as e:
...     print(repr(e))
...
ExceptionGroup('', (BlockingIOError(),))

def f():
    try:
        1/0
    finally:
        return 42

def foo():
    try:
        return 'try'
    finally:
        return 'finally'

8.5. Инструкция with

Инструкция with используется для обёртывания выполнения блока методами, определёнными менеджером контекста (см. раздел Менеджеры контекста инструкции with). Это позволяет инкапсулировать типичные шаблоны использования try…except…finally для удобного повторного использования.

with_stmt:          "with" ( "(" with_stmt_contents ","? ")" | with_stmt_contents ) ":" suite
with_stmt_contents: with_item ("," with_item)*
with_item:          expression ["as" target]

Выполнение инструкции with с одним «элементом» происходит следующим образом:

1. Вычисляется выражение контекста (выражение, указанное в with_item), чтобы получить менеджер контекста.
2. Для последующего использования загружается метод __enter__() менеджера контекста.
3. Для последующего использования загружается метод __exit__() менеджера контекста.
4. Вызывается метод __enter__() менеджера контекста.

5. Если в инструкции with указана цель, ей присваивается возвращаемое значение __enter__().

   Примечание

   Инструкция with гарантирует, что если метод __enter__() завершится без ошибки, то __exit__() будет вызван всегда. Поэтому ошибка при присваивании целевому списку будет обработана так же, как ошибка, возникшая внутри блока. См. шаг 7 ниже.

6. Выполняется блок.

7. Вызывается метод __exit__() менеджера контекста. Если выход из блока был вызван исключением, его тип, значение и трассировка передаются в качестве аргументов методу __exit__(). В противном случае передаются три аргумента None.

   Если выход из блока был вызван исключением и возвращаемое значение метода __exit__() было ложным, исключение возбуждается повторно. Если возвращаемое значение было истинным, исключение подавляется, и выполнение продолжается с инструкции, следующей за инструкцией with.

   Если выход из блока произошёл по любой причине, кроме исключения, возвращаемое значение метода __exit__() игнорируется, и выполнение продолжается в обычном месте для соответствующего типа выхода.

Следующий код:

with EXPRESSION as TARGET:
    SUITE

семантически эквивалентен:

manager = (EXPRESSION)
enter = manager.__enter__
exit = manager.__exit__
value = enter()
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not exit(*sys.exc_info()):
        raise
finally:
    if not hit_except:
        exit(None, None, None)

за исключением того, что для __enter__() и __exit__() используется неявный поиск специальных методов.

Если указано несколько элементов, менеджеры контекста обрабатываются так, как если бы несколько инструкций with были вложены друг в друга:

with A() as a, B() as b:
    SUITE

семантически эквивалентен:

with A() as a:
    with B() as b:
        SUITE

Многоэлементные менеджеры контекста также можно записать в несколько строк, если элементы заключены в скобки. Например:

with (
    A() as a,
    B() as b,
):
    SUITE

8.6. Инструкция match

Инструкция match используется для сопоставления с образцом. Синтаксис:

match_stmt:   'match' subject_expr ":" NEWLINE INDENT case_block+ DEDENT
subject_expr: flexible_expression "," [flexible_expression_list [',']]
              | assignment_expression
case_block:   'case' patterns [guard] ":" suite

Сопоставление с образцом принимает на вход образец (следующий за case) и значение субъекта (следующее за match). Образец (который может содержать подобразцы) сопоставляется со значением субъекта. Возможны следующие результаты:

• Успешное или неуспешное сопоставление (также называемое успешным или неуспешным совпадением с образцом).
• Возможная привязка сопоставленных значений к имени. Условия для этого подробнее обсуждаются ниже.

Ключевые слова match и case являются мягкими ключевыми словами.

>>> flag = False
>>> match (100, 200):
...    case (100, 300):  # Mismatch: 200 != 300
...        print('Case 1')
...    case (100, 200) if flag:  # Successful match, but guard fails
...        print('Case 2')
...    case (100, y):  # Matches and binds y to 200
...        print(f'Case 3, y: {y}')
...    case _:  # Pattern not attempted
...        print('Case 4, I match anything!')
...
Case 3, y: 200

guard: "if" assignment_expression

patterns:       open_sequence_pattern | pattern
pattern:        as_pattern | or_pattern
closed_pattern: | literal_pattern
                | capture_pattern
                | wildcard_pattern
                | value_pattern
                | group_pattern
                | sequence_pattern
                | mapping_pattern
                | class_pattern

or_pattern: "|".closed_pattern+

as_pattern: or_pattern "as" capture_pattern

literal_pattern: signed_number
                 | signed_number "+" NUMBER
                 | signed_number "-" NUMBER
                 | strings
                 | "None"
                 | "True"
                 | "False"
signed_number:   ["-"] NUMBER

capture_pattern: !'_' NAME

wildcard_pattern: '_'

value_pattern: attr
attr:          name_or_attr "." NAME
name_or_attr:  attr | NAME

group_pattern: "(" pattern ")"

sequence_pattern:       "[" [maybe_sequence_pattern] "]"
                        | "(" [open_sequence_pattern] ")"
open_sequence_pattern:  maybe_star_pattern "," [maybe_sequence_pattern]
maybe_sequence_pattern: ",".maybe_star_pattern+ ","?
maybe_star_pattern:     star_pattern | pattern
star_pattern:           "*" (capture_pattern | wildcard_pattern)

mapping_pattern:     "{" [items_pattern] "}"
items_pattern:       ",".key_value_pattern+ ","?
key_value_pattern:   (literal_pattern | value_pattern) ":" pattern
                     | double_star_pattern
double_star_pattern: "**" capture_pattern

class_pattern:       name_or_attr "(" [pattern_arguments ","?] ")"
pattern_arguments:   positional_patterns ["," keyword_patterns]
                     | keyword_patterns
positional_patterns: ",".pattern+
keyword_patterns:    ",".keyword_pattern+
keyword_pattern:     NAME "=" pattern

8.7. Определения функций

Определение функции определяет объект пользовательской функции (см. раздел Стандартная иерархия типов):

funcdef:                   [decorators] "def" funcname [type_params] "(" [parameter_list] ")"
                           ["->" expression] ":" suite
decorators:                decorator+
decorator:                 "@" assignment_expression NEWLINE
parameter_list:            defparameter ("," defparameter)* "," "/" ["," [parameter_list_no_posonly]]
                             | parameter_list_no_posonly
parameter_list_no_posonly: defparameter ("," defparameter)* ["," [parameter_list_starargs]]
                           | parameter_list_starargs
parameter_list_starargs:   "*" [star_parameter] ("," defparameter)* ["," [parameter_star_kwargs]]
                           | "*" ("," defparameter)+ ["," [parameter_star_kwargs]]
                           | parameter_star_kwargs
parameter_star_kwargs:     "**" parameter [","]
parameter:                 identifier [":" expression]
star_parameter:            identifier [":" ["*"] expression]
defparameter:              parameter ["=" expression]
funcname:                  identifier

Определение функции является исполняемой инструкцией. При её выполнении имя функции в текущем локальном пространстве имён связывается с объектом функции (обёрткой вокруг исполняемого кода функции). Этот объект функции содержит ссылку на текущее глобальное пространство имён, которое будет использоваться при вызове функции.

Определение функции не выполняет тело функции; оно выполняется только при вызове функции. [4]

Определение функции может быть обёрнуто одним или несколькими выражениями декоратора. Выражения декораторов вычисляются при определении функции, в области видимости, содержащей определение функции. Результат должен быть вызываемым объектом, который вызывается с объектом функции в качестве единственного аргумента. Возвращённое значение связывается с именем функции вместо объекта функции. Несколько декораторов применяются вложенным образом. Например, следующий код

@f1(arg)
@f2
def func(): pass

примерно эквивалентен

def func(): pass
func = f1(arg)(f2(func))

за исключением того, что исходная функция временно не связывается с именем func.

Список параметров типа можно указать в квадратных скобках между именем функции и открывающей скобкой списка её параметров. Это указывает средствам статической проверки типов, что функция является обобщённой. Во время выполнения параметры типа можно получить из атрибута функции __type_params__. Подробнее см. в разделе Обобщённые функции.

Если один или несколько параметров имеют форму параметр = выражение, у функции есть «значения параметров по умолчанию». Для параметра со значением по умолчанию соответствующий аргумент можно опустить при вызове; в этом случае вместо него подставляется значение параметра по умолчанию. Если у параметра есть значение по умолчанию, все последующие параметры вплоть до «*» также должны иметь значения по умолчанию — это синтаксическое ограничение, не выраженное в грамматике.

Значения параметров по умолчанию вычисляются слева направо при выполнении определения функции. Это означает, что выражение вычисляется один раз при определении функции и что при каждом вызове используется одно и то же «предварительно вычисленное» значение. Особенно важно помнить об этом, если значение параметра по умолчанию — изменяемый объект, например список или словарь: если функция изменяет этот объект (например, добавляет элемент в список), фактически изменяется и значение параметра по умолчанию. Обычно это не то, что предполагалось. Этого можно избежать, используя None в качестве значения по умолчанию и явно проверяя его в теле функции, например:

def whats_on_the_telly(penguin=None):
    if penguin is None:
        penguin = []
    penguin.append("property of the zoo")
    return penguin

Семантика вызова функции подробнее описана в разделе Вызовы. При вызове функции значения всегда присваиваются всем параметрам, указанным в списке параметров: из позиционных аргументов, именованных аргументов или значений по умолчанию. Если присутствует форма «*identifier», ей присваивается кортеж, содержащий все избыточные позиционные параметры; по умолчанию используется пустой кортеж. Если присутствует форма «**identifier», ей присваивается новое упорядоченное отображение, содержащее все избыточные именованные аргументы; по умолчанию используется новое пустое отображение того же типа. Параметры после «*» или «*identifier» являются параметрами, доступными только по имени, и передавать их можно только в виде именованных аргументов. Параметры перед «/» являются параметрами, доступными только по позиции, и передавать их можно только в виде позиционных аргументов.

У параметров может быть аннотация вида «: expression», следующая за именем параметра. Аннотацию можно указать для любого параметра, в том числе для параметров вида *identifier или **identifier. (В особом случае параметры вида *identifier могут иметь аннотацию «: *expression».) После списка параметров функции может быть указана аннотация «возвращаемого значения» вида «-> expression». Эти аннотации могут быть любыми допустимыми выражениями Python. Наличие аннотаций не меняет семантику функции. Дополнительные сведения об аннотациях см. в разделе Аннотации.

Также можно создавать анонимные функции (функции, не связанные с именем) для непосредственного использования в выражениях. Для этого используются лямбда-выражения, описанные в разделе Лямбда-выражения. Обратите внимание: лямбда-выражение — это лишь сокращённая форма упрощённого определения функции; функцию, определённую в инструкции «def», можно передавать или присваивать другому имени так же, как функцию, определённую лямбда-выражением. Форма «def» на самом деле мощнее, поскольку позволяет выполнять несколько инструкций и использовать аннотации.

Примечание для программистов: Функции являются объектами первого класса. Инструкция «def», выполненная внутри определения функции, определяет локальную функцию, которую можно вернуть или передать. Свободные переменные, используемые во вложенной функции, могут обращаться к локальным переменным содержащей её функции. Подробности см. в разделе Имена и связывание.

8.8. Определения классов

Определение класса определяет объект класса (см. раздел Стандартная иерархия типов):

classdef:    [decorators] "class" classname [type_params] [inheritance] ":" suite
inheritance: "(" [argument_list] ")"
classname:   identifier

Определение класса является исполняемой инструкцией. Список наследования обычно содержит список базовых классов (о более сложных вариантах использования см. раздел Метаклассы), поэтому каждый элемент списка должен вычисляться в объект класса, допускающий создание подклассов. Классы без списка наследования по умолчанию наследуются от базового класса object; следовательно,

class Foo:
    pass

эквивалентно

class Foo(object):
    pass

Затем блок класса выполняется в новом кадре выполнения (см. раздел Имена и связывание) с использованием вновь созданного локального пространства имён и исходного глобального пространства имён. (Обычно блок состоит преимущественно из определений функций.) После завершения выполнения блока класса его кадр выполнения удаляется, но локальное пространство имён сохраняется. [5] Затем создаётся объект класса: для базовых классов используется список наследования, а для словаря атрибутов — сохранённое локальное пространство имён. Имя класса связывается с этим объектом класса в исходном локальном пространстве имён.

Порядок определения атрибутов в теле класса сохраняется в атрибуте нового класса __dict__. Обратите внимание, что это гарантируется только сразу после создания класса и только для классов, определённых с помощью синтаксиса определений.

Создание классов можно в значительной степени настраивать с помощью метаклассов.

Классы также можно декорировать: так же, как и при декорировании функций,

@f1(arg)
@f2
class Foo: pass

примерно эквивалентно

class Foo: pass
Foo = f1(arg)(f2(Foo))

Правила вычисления выражений декораторов такие же, как для декораторов функций. Результат затем связывается с именем класса.

Список параметров типа можно указать в квадратных скобках сразу после имени класса. Это указывает средствам статической проверки типов, что класс является обобщённым. Во время выполнения параметры типа можно получить из атрибута класса __type_params__. Подробнее см. в разделе Обобщённые классы.

Примечание для программистов: Переменные, определённые в определении класса, являются атрибутами класса; они общие для его экземпляров. Атрибуты экземпляра можно задавать в методе с помощью self.name = value. К атрибутам класса и экземпляра можно обращаться через запись «self.name»; при таком обращении атрибут экземпляра скрывает одноимённый атрибут класса. Атрибуты класса можно использовать как значения по умолчанию для атрибутов экземпляра, но использование там изменяемых значений может привести к неожиданным результатам. Дескрипторы можно использовать для создания переменных экземпляра с другими особенностями реализации.

8.9. Сопрограммы

async_funcdef: [decorators] "async" "def" funcname "(" [parameter_list] ")"
               ["->" expression] ":" suite

async def func(param1, param2):
    do_stuff()
    await some_coroutine()

async_for_stmt: "async" for_stmt

async for TARGET in ITER:
    SUITE
else:
    SUITE2

iter = (ITER).__aiter__()
running = True

while running:
    try:
        TARGET = await iter.__anext__()
    except StopAsyncIteration:
        running = False
    else:
        SUITE
else:
    SUITE2

async_with_stmt: "async" with_stmt

async with EXPRESSION as TARGET:
    SUITE

manager = (EXPRESSION)
aenter = manager.__aenter__
aexit = manager.__aexit__
value = await aenter()
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not await aexit(*sys.exc_info()):
        raise
finally:
    if not hit_except:
        await aexit(None, None, None)

8.10. Списки параметров типа

type_params:  "[" type_param ("," type_param)* "]"
type_param:   typevar | typevartuple | paramspec
typevar:      identifier (":" expression)? ("=" expression)?
typevartuple: "*" identifier ("=" expression)?
paramspec:    "**" identifier ("=" expression)?

Функции (включая сопрограммы), классы и псевдонимы типов могут содержать список параметров типа:

def max[T](args: list[T]) -> T:
    ...

async def amax[T](args: list[T]) -> T:
    ...

class Bag[T]:
    def __iter__(self) -> Iterator[T]:
        ...

    def add(self, arg: T) -> None:
        ...

type ListOrSet[T] = list[T] | set[T]

Семантически это означает, что функция, класс или псевдоним типа обобщены по переменной типа. Эти сведения используются преимущественно средствами статической проверки типов; во время выполнения обобщённые объекты ведут себя почти так же, как их необобщённые аналоги.

Параметры типа объявляются в квадратных скобках ([]) сразу после имени функции, класса или псевдонима типа. Параметры типа доступны в области видимости обобщённого объекта, но не за её пределами. Поэтому после объявления def func[T](): pass имя T недоступно в области видимости модуля. Далее семантика обобщённых объектов описывается точнее. Область видимости параметров типа моделируется специальной функцией (технически — областью видимости аннотаций), которая оборачивает создание обобщённого объекта.

У обобщённых функций, классов и псевдонимов типов есть атрибут __type_params__, содержащий список их параметров типа.

Существует три вида параметров типа:

• typing.TypeVar, вводимый обычным именем (например, T). Семантически для средства проверки типов он представляет один тип.
• typing.TypeVarTuple, вводимый именем с одной звёздочкой в начале (например, *Ts). Семантически он представляет кортеж из произвольного количества типов.
• typing.ParamSpec, вводимый именем с двумя звёздочками в начале (например, **P). Семантически он представляет параметры вызываемого объекта.

Объявления typing.TypeVar могут задавать границы и ограничения: после двоеточия (:) указывается выражение. Одно выражение после двоеточия задаёт границу (например, T: int). Семантически это означает, что typing.TypeVar может представлять только типы, являющиеся подтипами этой границы. Кортеж выражений в скобках после двоеточия задаёт набор ограничений (например, T: (str, bytes)). Каждый элемент кортежа должен быть типом (это также не проверяется во время выполнения). Переменные типа с ограничениями могут принимать только один из типов в списке ограничений.

Для typing.TypeVar, объявленных с помощью синтаксиса списка параметров типа, граница и ограничения вычисляются не при создании обобщённого объекта, а только при явном обращении к атрибутам __bound__ и __constraints__. Для этого границы и ограничения вычисляются в отдельной области видимости аннотаций.

У typing.TypeVarTuple и typing.ParamSpec не может быть границ или ограничений.

Все три вида параметров типа также могут иметь значение по умолчанию, которое используется, если параметр типа не указан явно. Оно задаётся добавлением одного знака равенства (=), за которым следует выражение. Как и границы и ограничения переменных типа, значение по умолчанию вычисляется не при создании объекта, а только при обращении к атрибуту __default__ параметра типа. Для этого значение по умолчанию вычисляется в отдельной области видимости аннотаций. Если для параметра типа не указано значение по умолчанию, атрибуту __default__ присваивается специальный объект-маркер typing.NoDefault.

В следующем примере показан полный набор допустимых объявлений параметров типа:

def overly_generic[
   SimpleTypeVar,
   TypeVarWithDefault = int,
   TypeVarWithBound: int,
   TypeVarWithConstraints: (str, bytes),
   *SimpleTypeVarTuple = (int, float),
   **SimpleParamSpec = (str, bytearray),
](
   a: SimpleTypeVar,
   b: TypeVarWithDefault,
   c: TypeVarWithBound,
   d: Callable[SimpleParamSpec, TypeVarWithConstraints],
   *e: SimpleTypeVarTuple,
): ...

def func[T](arg: T): ...

annotation-def TYPE_PARAMS_OF_func():
    T = typing.TypeVar("T")
    def func(arg: T): ...
    func.__type_params__ = (T,)
    return func
func = TYPE_PARAMS_OF_func()

@decorator
def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = some_default):
    ...

DEFAULT_OF_arg = some_default

annotation-def TYPE_PARAMS_OF_func():

    annotation-def BOUND_OF_T():
        return int
    # In reality, BOUND_OF_T() is evaluated only on demand.
    T = typing.TypeVar("T", bound=BOUND_OF_T())

    Ts = typing.TypeVarTuple("Ts")
    P = typing.ParamSpec("P")

    def func(*args: *Ts, arg: Callable[P, T] = DEFAULT_OF_arg):
        ...

    func.__type_params__ = (T, Ts, P)
    return func
func = decorator(TYPE_PARAMS_OF_func())

class Bag[T]: ...

annotation-def TYPE_PARAMS_OF_Bag():
    T = typing.TypeVar("T")
    class Bag(typing.Generic[T]):
        __type_params__ = (T,)
        ...
    return Bag
Bag = TYPE_PARAMS_OF_Bag()

@decorator
class Bag(Base[T], arg=T): ...

annotation-def TYPE_PARAMS_OF_Bag():
    T = typing.TypeVar("T")
    class Bag(Base[T], typing.Generic[T], arg=T):
        __type_params__ = (T,)
        ...
    return Bag
Bag = decorator(TYPE_PARAMS_OF_Bag())

type ListOrSet[T] = list[T] | set[T]

annotation-def TYPE_PARAMS_OF_ListOrSet():
    T = typing.TypeVar("T")

    annotation-def VALUE_OF_ListOrSet():
        return list[T] | set[T]
    # In reality, the value is lazily evaluated
    return typing.TypeAliasType("ListOrSet", VALUE_OF_ListOrSet(), type_params=(T,))
ListOrSet = TYPE_PARAMS_OF_ListOrSet()

8.11. Аннотации

Переменные и параметры функций могут иметь аннотации, которые создаются добавлением двоеточия после имени с последующим выражением:

x: annotation = 1
def f(param: annotation): ...

Функции также могут иметь аннотацию возвращаемого значения, следующую за стрелкой:

def f() -> annotation: ...

Аннотации обычно используются для подсказок типов, однако язык не требует этого, и в целом аннотации могут содержать произвольные выражения. Наличие аннотаций не меняет семантику выполнения кода, за исключением случаев, когда используется механизм, который анализирует аннотации и применяет их (например, dataclasses или @functools.singledispatch).

По умолчанию аннотации отложенно вычисляются в области видимости аннотаций. Это означает, что они не вычисляются при вычислении кода, содержащего аннотацию. Вместо этого интерпретатор сохраняет сведения, которые можно использовать для вычисления аннотации позднее, если это потребуется. Модуль annotationlib предоставляет инструменты для вычисления аннотаций.

Если присутствует инструкция future from __future__ import annotations, все аннотации вместо этого сохраняются в виде строк:

>>> from __future__ import annotations
>>> def f(param: annotation): ...
>>> f.__annotations__
{'param': 'annotation'}

Эта инструкция future будет объявлена устаревшей и удалена в будущей версии Python, но не ранее окончания срока поддержки Python 3.13 (см. PEP 749). При её использовании средства интроспекции, такие как annotationlib.get_annotations() и typing.get_type_hints(), с меньшей вероятностью смогут разрешить аннотации во время выполнения.

Сноски