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

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). Это позволяет encapsulate общие шаблоны 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__() всегда будет вызван. Таким образом, если ошибка произойдёт во время присваивания значений целевым переменным, она будет обработана так же, как если бы ошибка возникла внутри блока.

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)

try:
    TARGET = value
    SUITE
except:
    if not exit(manager, *sys.exc_info()):
        raise
else:
    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   ::=  "*" [star_parameter] ("," defparameter)* ["," ["**" parameter [","]]]
                               | "**" 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. Наличие аннотаций не изменяет семантики функции. Значения аннотаций доступны в качестве значений словаря, ключами которого являются имена параметров, в атрибуте __annotations__ объекта функции. Если используется импорт annotations из __future__, аннотации сохраняются как строки во время выполнения, что позволяет отложить вычисление. В противном случае они вычисляются при выполнении определения функции. В этом случае аннотации могут быть вычислены в другом порядке, чем они появляются в исходном коде.

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