8. Составные инструкции¶Compound statements

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

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

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

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

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

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

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

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

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

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

Инструкция 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             # это не повлияет на цикл for
                      # потому что i будет перезаписано следующим
                      # индексом в range

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

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

Инструкция 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¶The with statement

Оператор 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__() менеджера контекста. Если исключение вызвало выход из блока, его тип, значение и traceback передаются в качестве аргументов __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¶The match statement

Оператор 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):  # Несоответствие: 200 != 300
...        print('Case 1')
...    case (100, 200) if flag:  # Успешное сопоставление, но страж не сработал
...        print('Case 2')
...    case (100, y):  # Сопоставляется и связывает y с 200
...        print(f'Case 3, y: {y}')
...    case _:  # Шаблон не был задействован
...        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. Определения функций¶Function definitions

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

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__ функции. Подробнее см. Generic functions.

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

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

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

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

Параметры могут иметь аннотацию вида «: expression» после имени параметра. Любой параметр может иметь аннотацию, даже параметры вида *identifier или **identifier. (Как частный случай, параметры вида *identifier могут иметь аннотацию «: *expression».) Функции могут иметь аннотацию «return» вида «-> expression» после списка параметров. Эти аннотации могут быть любым допустимым выражением Python. Наличие аннотаций не меняет семантику функции. См. Annotations для получения дополнительной информации об аннотациях.

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

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

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

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

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

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

class Foo:
    pass

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

class Foo(object):
    pass

Базовых классов может быть один или несколько; подробнее см. Множественное наследование ниже.

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

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

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

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

@f1(arg)
@f2
class Foo: pass

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

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

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

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

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

>>> class A: pass
>>> class B: pass
>>> class C(A, B): pass

>>> class SubBool(bool):  # TypeError
...    pass
Traceback (most recent call last):
   ...
TypeError: type 'bool' is not an acceptable base type

>>> class Base: pass
>>> class Child(Base): pass
>>> class Grandchild(Base, Child): pass  # TypeError
Traceback (most recent call last):
   ...
TypeError: Cannot create a consistent method resolution order (MRO) for bases Base, Child

>>> class Solid1:
...    __slots__ = ("solid1",)
>>>
>>> class Solid2:
...    __slots__ = ("solid2",)
>>>
>>> class SolidChild(Solid1):
...    __slots__ = ("solid_child",)
>>>
>>> class C1:  # фиксированный базовый класс – `object`
...    pass
>>>
>>> # OK: фиксированные базовые классы – `Solid1` и `object`, и `Solid1` является подклассом `object`.
>>> class C2(Solid1, C1):  # фиксированный базовый класс – `Solid1`
...    pass
>>>
>>> # OK: фиксированные базовые классы – `SolidChild` и `Solid1`, и `SolidChild` является подклассом `Solid1`.
>>> class C3(SolidChild, Solid1):  # фиксированный базовый класс – `SolidChild`
...    pass
>>>
>>> # Ошибка: фиксированные базовые классы – `Solid1` и `Solid2`, но ни один из них не является подклассом другого.
>>> class C4(Solid1, Solid2):  # ошибка: нет единственного фиксированного базового класса
...    pass
Traceback (most recent call last):
  ...
TypeError: multiple bases have instance lay-out conflict

8.9. Корутины¶Coroutines

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 parameter lists

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__ устанавливается в специальный sentinel-объект 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
    # На самом деле, BOUND_OF_T() вычисляется только по требованию.
    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]
    # На самом деле, значение вычисляется лениво.
    return typing.TypeAliasType("ListOrSet", VALUE_OF_ListOrSet(), type_params=(T,))
ListOrSet = TYPE_PARAMS_OF_ListOrSet()

8.11. Аннотации¶Annotations

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

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(), с меньшей вероятностью смогут разрешить аннотации во время выполнения.

Сноски