Составные операторы

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_list ":" suite
              ["else" ":" suite]

Выражение starred_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 "<stdin>", line 2, in <module>
  | ExceptionGroup: eg
  +-+---------------- 1 ----------------
    | ValueError: 1
    +------------------------------------

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

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

>>> def foo():
...     try:
...         return 'try'
...     finally:
...         return 'finally'
...
>>> foo()
'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 = type(manager).__enter__
exit = type(manager).__exit__
value = enter(manager)
hit_except = False

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

При использовании более одного элемента, менеджеры контекста обрабатываются как если бы были вложены несколько операторов 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 ::=  star_named_expression "," star_named_expressions?
                  | named_expression
case_block   ::=  'case' patterns [guard] ":" block

Сопоставление с образцом принимает шаблон в качестве входных данных (после 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" named_expression

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   ::=  "*" [parameter] ("," defparameter)* ["," ["**" parameter [","]]]
                               | "**" parameter [","]
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. Функции могут иметь аннотацию «возвращаемого значения» вида «-> expression» после списка параметров. Эти аннотации могут быть любым допустимым выражением Python. Наличие аннотаций не изменяет семантики функции. Значения аннотаций доступны как значения словаря, ключами которого являются имена параметров, в атрибуте __annotations__ объекта функции. Если используется импорт annotations из __future__, аннотации сохраняются как строки во время выполнения, что позволяет отложить вычисление. В противном случае они вычисляются при выполнении определения функции. В этом случае аннотации могут быть вычислены в порядке, отличном от того, в котором они появляются в исходном коде.

Также можно создать анонимные функции (функции, не привязанные к имени), для непосредственного использования в выражениях. Это используется с выражениями lambda, описанными в разделе Lambda-выражения. Обратите внимание, что выражение lambda — это всего лишь сокращённая запись для упрощённого определения функции; функция, определённая в операторе «def», может передаваться или присваиваться другому имени, как функция, определённая с помощью выражения lambda. Форма «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)
iter = type(iter).__aiter__(iter)
running = True

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

async_with_stmt ::=  "async" with_stmt

async with EXPRESSION as TARGET:
    SUITE

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

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

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

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

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

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 не могут иметь границ или ограничений.

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

def overly_generic[
   SimpleTypeVar,
   TypeVarWithBound: int,
   TypeVarWithConstraints: (str, bytes),
   *SimpleTypeVarTuple,
   **SimpleParamSpec,
](
   a: SimpleTypeVar,
   b: TypeVarWithBound,
   c: Callable[SimpleParamSpec, TypeVarWithConstraints],
   *d: 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())