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

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 с одним элементом («item») происходит следующим образом:

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 используется для сопоставления с образцом (pattern matching). Синтаксис:

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

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 | "-" 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 "(" [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.

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

Значения параметров по умолчанию вычисляются слева направо при выполнении определения функции. Это означает, что выражение вычисляется один раз, когда функция определяется, и одно и то же «предварительно вычисленное» значение используется для каждого вызова. Это особенно важно понимать, когда значение параметра по умолчанию является изменяемым объектом, таким как список или словарь: если функция изменяет объект (например, путем добавления элемента в список), значение параметра по умолчанию фактически изменяется. Обычно это не то, что предполагалось. Способ обойти это — использовать 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__, аннотации сохраняются как строки во время выполнения, что позволяет отложить вычисление. В противном случае они вычисляются при выполнении определения функции. В этом случае аннотации могут вычисляться в порядке, отличном от порядка их появления в исходном коде.

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

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

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

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

classdef    ::=  [decorators] "class" classname [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))

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

Примечание для программиста: Переменные, определенные в определении класса, являются атрибутами класса; они разделяются всеми экземплярами. Атрибуты экземпляра могут быть установлены в методе с помощью 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)