7. Простые инструкции¶Simple statements

7.1. Инструкции-выражения¶Expression statements

Инструкции-выражения используются (в основном в интерактивном режиме) для вычисления и вывода значения, или (обычно) для вызова процедуры (функции, не возвращающей осмысленного результата; в Python процедуры возвращают значение None). Другие применения инструкций-выражений допустимы и иногда полезны. Синтаксис инструкции-выражения:

expression_stmt: starred_expression

Инструкция-выражение вычисляет список выражений (который может быть одиночным выражением).

В интерактивном режиме, если значение не равно None, оно преобразуется в строку с помощью встроенной функции repr(), и полученная строка выводится в стандартный вывод на отдельной строке (за исключением случая, когда результат равен None, чтобы вызовы процедур не приводили к выводу).

7.2. Инструкции присваивания¶Assignment statements

Инструкции присваивания используются для (пере)привязки имён к значениям и изменения атрибутов или элементов изменяемых объектов:

assignment_stmt: (target_list "=")+ (starred_expression | yield_expression)
target_list:     target ("," target)* [","]
target:          identifier
                 | "(" [target_list] ")"
                 | "[" [target_list] "]"
                 | attributeref
                 | subscription
                 | "*" target

(См. раздел Первичные для определения синтаксиса attributeref и subscription.)

Инструкция присваивания вычисляет список выражений (помните, что это может быть одно выражение или список, разделённый запятыми, последний даёт кортеж) и присваивает единственный результирующий объект каждому из списков целей, слева направо.

Присваивание определяется рекурсивно в зависимости от формы цели (списка). Когда цель является частью изменяемого объекта (ссылка на атрибут или индексация), изменяемый объект в конечном счёте должен выполнить присваивание и решить, допустимо ли оно, и может возбудить исключение, если присваивание неприемлемо. Правила, соблюдаемые различными типами, и возбуждаемые исключения приводятся в определении типов объектов (см. раздел Стандартная иерархия типов).

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

• Если список целей состоит из одной цели без завершающей запятой, возможно в круглых скобках, объект присваивается этой цели.

• Иначе:

  • Если список целей содержит одну цель с префиксом в виде звёздочки, называемую «звёздной» целью: объект должен быть итерируемым, содержащим как минимум столько же элементов, сколько целей в списке целей, минус один. Первые элементы итерируемого объекта присваиваются, слева направо, целям перед звёздной целью. Последние элементы итерируемого объекта присваиваются целям после звёздной цели. Затем список оставшихся элементов итерируемого объекта присваивается звёздной цели (список может быть пустым).

  • Иначе: объект должен быть итерируемым с тем же количеством элементов, сколько целей в списке целей, и элементы присваиваются, слева направо, соответствующим целям.

Присваивание объекта одной цели рекурсивно определяется следующим образом.

• Если цель является идентификатором (именем):

  • Если имя не встречается в инструкции global или nonlocal в текущем блоке кода: имя привязывается к объекту в текущем локальном пространстве имён.

  • В противном случае: имя привязывается к объекту в глобальном пространстве имён или во внешнем пространстве имён, определяемом nonlocal, соответственно.

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

• Если цель является ссылкой на атрибут: вычисляется первичное выражение в ссылке. Оно должно давать объект с назначаемыми атрибутами; если это не так, возбуждается TypeError. Затем этому объекту предлагается присвоить заданный объект указанному атрибуту; если он не может выполнить присваивание, он возбуждает исключение (обычно, но не обязательно AttributeError).

  Примечание: Если объект является экземпляром класса и ссылка на атрибут встречается по обе стороны от оператора присваивания, выражение в правой части, a.x, может обращаться как к атрибуту экземпляра, так и (если атрибут экземпляра отсутствует) к атрибуту класса. Цель в левой части a.x всегда устанавливается как атрибут экземпляра, создавая его при необходимости. Таким образом, два вхождения a.x не обязательно ссылаются на один и тот же атрибут: если выражение в правой части ссылается на атрибут класса, левая часть создаёт новый атрибут экземпляра в качестве цели присваивания:

  class Cls:
      x = 3             # переменная класса
  inst = Cls()
  inst.x = inst.x + 1   # записывает inst.x как 4, оставляя Cls.x равным 3
  

  Это описание не обязательно применимо к атрибутам-дескрипторам, таким как свойства, созданные с помощью property().

• Если целью является индексация: вычисляется первичное выражение в ссылке. Затем вычисляется выражение индекса. Затем вызывается метод __setitem__() первичного объекта с двумя аргументами: индексом и присваиваемым объектом.

  Обычно __setitem__() определён для изменяемых последовательностей (таких как списки) и отображений (таких как словари) и ведёт себя следующим образом.

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

  Если первичным выражением является отображение (например, словарь), то индекс должен иметь тип, совместимый с типом ключа отображения, и отображению затем предлагается создать пару ключ/значение, которая связывает индекс с присваиваемым объектом. Это может либо заменить существующую пару ключ/значение с тем же значением ключа, либо вставить новую пару ключ/значение (если ключа с таким значением не существовало).

  Если целью является срез: первичное выражение должно вычисляться в изменяемый последовательный объект (например, список). Присваиваемый объект должен быть итерируемым. Нижняя и верхняя границы среза должны быть целыми числами; если они равны None (или отсутствуют), по умолчанию используются ноль и длина последовательности. Если любая из границ отрицательна, к ней прибавляется длина последовательности. Полученные границы обрезаются так, чтобы находиться в диапазоне от нуля до длины последовательности включительно. Наконец, объекту последовательности предлагается заменить срез элементами присваиваемой последовательности. Длина среза может отличаться от длины присваиваемой последовательности, что изменяет длину целевой последовательности, если целевая последовательность это допускает.

Хотя определение присваивания подразумевает, что пересечения левой и правой частей являются «одновременными» (например, a, b = b, a меняет местами две переменные), пересечения внутри набора присваиваемых переменных обрабатываются слева направо, что иногда приводит к путанице. Например, следующая программа выводит [0, 2]:

x = [0, 1]
i = 0
i, x[i] = 1, 2         # i обновляется, затем обновляется x[i]
print(x)

augmented_assignment_stmt: augtarget augop (expression_list | yield_expression)
augtarget:                 identifier | attributeref | subscription
augop:                     "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
                           | ">>=" | "<<=" | "&=" | "^=" | "|="

annotated_assignment_stmt: augtarget ":" expression
                           ["=" (starred_expression | yield_expression)]

7.3. Инструкция assert¶The assert statement

Операторы assert – это удобный способ вставить отладочные утверждения в программу:

assert_stmt: "assert" expression ["," expression]

Простая форма, assert expression, эквивалентна

if __debug__:
    if not expression: raise AssertionError

Расширенная форма, assert expression1, expression2, эквивалентна

if __debug__:
    if not expression1: raise AssertionError(expression2)

Эти эквивалентности предполагают, что __debug__ и AssertionError ссылаются на встроенные переменные с такими именами. В текущей реализации встроенная переменная __debug__ равна True в обычных условиях и False, когда запрошена оптимизация (параметр командной строки -O). Текущий генератор кода не генерирует код для оператора assert, когда оптимизация запрошена на этапе компиляции. Обратите внимание, что нет необходимости включать исходный код выражения, вызвавшего ошибку, в сообщение об ошибке; он будет отображён как часть трассировки стека.

Присваивания __debug__ запрещены. Значение встроенной переменной определяется при запуске интерпретатора.

7.4. Инструкция pass¶The pass statement

pass_stmt: "pass"

pass – пустая операция; при её выполнении ничего не происходит. Она полезна в качестве заполнителя, когда синтаксически требуется оператор, но выполнять код не нужно, например:

def f(arg): pass    # функция, которая пока ничего не делает

class C: pass       # класс без методов (пока)

7.5. Инструкция del¶The del statement

del_stmt: "del" target_list

Удаление рекурсивно определяется очень похоже на то, как определяется присваивание. Вместо подробного изложения приведём несколько подсказок.

Удаление списка целей рекурсивно удаляет каждую цель слева направо.

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

Удаление ссылок на атрибуты и индексации передаётся основному объекту; удаление среза в общем случае эквивалентно присваиванию пустого среза соответствующего типа (но даже это определяется объектом среза).

7.6. Инструкция return¶The return statement

return_stmt: "return" [expression_list]

return может синтаксически встречаться только внутри определения функции, а не внутри определения вложенного класса.

Если указан список выражений, он вычисляется, иначе подставляется None.

return завершает текущий вызов функции, возвращая список выражений (или None).

Когда return передаёт управление из оператора try с предложением finally, это предложение finally выполняется перед фактическим выходом из функции.

В генераторной функции оператор return указывает, что генератор завершён, и вызовет StopIteration. Возвращаемое значение (если есть) используется как аргумент для создания StopIteration и становится атрибутом StopIteration.value.

В асинхронной генераторной функции пустой оператор return указывает, что асинхронный генератор завершён, и вызовет StopAsyncIteration. Непустой оператор return является синтаксической ошибкой в асинхронной генераторной функции.

7.7. Инструкция yield¶The yield statement

yield_stmt: yield_expression

Оператор yield семантически эквивалентен выражению yield. Оператор yield можно использовать, чтобы опустить скобки, которые в противном случае потребовались бы в эквивалентном выражении yield. Например, операторы yield

yield <expr>
yield from <expr>

эквивалентны выражениям-операторам yield.

(yield <expr>)
(yield from <expr>)

Выражения и операторы yield используются только при определении генераторной функции и используются только в теле функции-генератора. Использование yield в определении функции достаточно, чтобы это определение создавало функцию-генератор вместо обычной функции.

За полными подробностями семантики yield обратитесь к разделу Выражения yield.

7.8. Инструкция raise¶The raise statement

raise_stmt: "raise" [expression ["from" expression]]

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

В противном случае raise вычисляет первое выражение как объект исключения. Оно должно быть подклассом или экземпляром BaseException. Если это класс, экземпляр исключения будет получен при необходимости инстанцированием класса без аргументов.

Типом исключения является класс экземпляра исключения, значением – сам экземпляр.

Объект traceback обычно создаётся автоматически при возбуждении исключения и прикрепляется к нему как атрибут __traceback__. Вы можете создать исключение и установить собственный traceback за один шаг, используя метод with_traceback() (который возвращает тот же экземпляр исключения с traceback, установленным в переданный аргумент), например:

raise Exception("foo occurred").with_traceback(tracebackobj)

Предложение from используется для цепочки исключений: если указано, второе выражение должно быть другим классом или экземпляром исключения. Если второе выражение является экземпляром исключения, оно будет прикреплено к возбуждённому исключению как атрибут __cause__ (который доступен для записи). Если выражение является классом исключения, класс будет инстанцирован, и полученный экземпляр исключения будет прикреплён к возбуждённому исключению как атрибут __cause__. Если возбуждённое исключение не обработано, оба исключения будут выведены:

>>> try:
...     print(1 / 0)
... except Exception as exc:
...     raise RuntimeError("Something bad happened") from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("Something bad happened") from exc
RuntimeError: Something bad happened

Аналогичный механизм работает неявно, если новое исключение возбуждается, когда уже обрабатывается другое исключение. Исключение может быть обработано при использовании предложения except или finally, или оператора with. Предыдущее исключение затем прикрепляется как атрибут __context__ нового исключения:

>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("Something bad happened")
RuntimeError: Something bad happened

Цепочку исключений можно явно подавить, указав None в предложении from:

>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened") from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

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

7.9. Инструкция break¶The break statement

break_stmt: "break"

break может синтаксически находиться только внутри цикла for или while, но не внутри определения функции или класса в этом цикле.

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

Если цикл for завершается оператором break, то целевая переменная цикла сохраняет своё текущее значение.

Когда break передаёт управление из оператора try с предложением finally, это предложение finally выполняется перед фактическим выходом из цикла.

7.10. Инструкция continue¶The continue statement

continue_stmt: "continue"

continue может синтаксически находиться только внутри цикла for или while, но не внутри определения функции или класса в этом цикле. Он переходит к следующей итерации ближайшего охватывающего цикла.

Когда continue передаёт управление из оператора try с предложением finally, это предложение finally выполняется перед фактическим началом следующей итерации цикла.

7.11. Инструкция import¶The import statement

import_stmt:     ["lazy"] "import" module ["as" identifier] ("," module ["as" identifier])*
                 | ["lazy"] "from" relative_module "import" identifier ["as" identifier]
                 ("," identifier ["as" identifier])*
                 | ["lazy"] "from" relative_module "import" "(" identifier ["as" identifier]
                 ("," identifier ["as" identifier])* [","] ")"
                 | "from" relative_module "import" "*"
module:          (identifier ".")* identifier
relative_module: "."* module | "."+

Базовый оператор import (без предложения from) выполняется в два этапа:

1. найти модуль, загрузив и проинициализировав его при необходимости

2. определить имя или имена в текущем пространстве имен для области видимости, в которой находится оператор import, точно так же, как это сделал бы оператор присваивания (включая семантику global и nonlocal).

Когда оператор содержит несколько частей (разделённых запятыми), два этапа выполняются отдельно для каждой части, точно так, как если бы эти части были разделены на отдельные операторы import.

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

Если запрошенный модуль успешно получен, он становится доступным в локальном пространстве имен одним из трёх способов:

• Если за именем модуля следует as, то имя, следующее за as, привязывается непосредственно к импортированному модулю.

• Если не указано другое имя и импортируемый модуль является модулем верхнего уровня, имя модуля привязывается в локальном пространстве имен как ссылка на импортированный модуль.

• Если импортируемый модуль не является модулем верхнего уровня, то имя пакета верхнего уровня, содержащего этот модуль, привязывается в локальном пространстве имен как ссылка на пакет верхнего уровня. Импортированный модуль должен быть доступен по его полному квалифицированному имени, а не напрямую.

Форма from использует немного более сложный процесс:

1. найти модуль, указанный в предложении from, загрузив и проинициализировав его при необходимости;

2. для каждого из идентификаторов, указанных в предложениях import:

   1. проверить, имеет ли импортированный модуль атрибут с таким именем

   2. если нет, попытаться импортировать подмодуль с таким именем, а затем снова проверить импортированный модуль на наличие этого атрибута

   3. если атрибут не найден, возбуждается ImportError.

   4. в противном случае ссылка на это значение сохраняется в текущем пространстве имен, с использованием имени из предложения as, если оно присутствует, иначе с использованием имени атрибута

Примеры:

import foo                 # foo импортирован и привязан локально
import foo.bar.baz         # foo, foo.bar и foo.bar.baz импортированы, foo привязан локально
import foo.bar.baz as fbb  # foo, foo.bar и foo.bar.baz импортированы, foo.bar.baz привязан как fbb
from foo.bar import baz    # foo, foo.bar и foo.bar.baz импортированы, foo.bar.baz привязан как baz
from foo import attr       # foo импортирован и foo.attr привязан как attr

Если список идентификаторов заменён звёздочкой ('*'), все публичные имена, определённые в модуле, привязываются в локальном пространстве имен для области видимости, в которой находится оператор import.

Публичные имена, определённые модулем, определяются путём проверки пространства имен модуля на наличие переменной с именем __all__; если она определена, это должна быть последовательность строк, которые являются именами, определёнными или импортированными этим модулем. Имена, содержащие не-ASCII символы, должны быть в нормализованной форме NFKC; подробнее см. Не-ASCII символы в именах. Имена, указанные в __all__, считаются публичными и должны существовать. Если __all__ не определён, набор публичных имен включает все имена, найденные в пространстве имен модуля, которые не начинаются с символа подчёркивания ('_'). __all__ должно содержать весь публичный API. Это предназначено для того, чтобы избежать случайного экспорта элементов, не являющихся частью API (таких как библиотечные модули, которые были импортированы и использованы внутри модуля).

Групповая форма импорта – from module import * – разрешена только на уровне модуля. Попытка использовать её в определениях класса или функции приведёт к возбуждению SyntaxError.

При указании того, какой модуль импортировать, необязательно указывать абсолютное имя модуля. Когда модуль или пакет находится внутри другого пакета, можно выполнить относительный импорт в пределах того же верхнего пакета, не указывая имя пакета. Используя начальные точки в указанном модуле или пакете после from, можно указать, на сколько уровней подняться по иерархии текущего пакета, не указывая точных имён. Одна начальная точка означает текущий пакет, в котором существует модуль, выполняющий импорт. Две точки – на один уровень пакета выше. Три точки – на два уровня выше и т.д. Так, если выполнить from . import mod из модуля в пакете pkg, то в итоге будет импортирован pkg.mod. Если выполнить from ..subpkg2 import mod из pkg.subpkg1, будет импортирован pkg.subpkg2.mod. Спецификация относительных импортов содержится в разделе Относительные импорты пакетов.

importlib.import_module() предоставлен для поддержки приложений, которые динамически определяют загружаемые модули.

Возбуждает событие аудита import с аргументами module, filename, sys.path, sys.meta_path, sys.path_hooks.

lazy import json
import sys

print('json' in sys.modules)  # False – модуль json ещё не загружен

# Первое использование запускает загрузку
result = json.dumps({"hello": "world"})

print('json' in sys.modules)  # True – теперь загружен

__lazy_modules__ = ["json", "pathlib"]

import json     # загружен лениво (имя есть в __lazy_modules__)
import os       # загружен немедленно (имя отсутствует в __lazy_modules__)

import pathlib  # загружен лениво

# В mypackage/mymodule.py
__lazy_modules__ = ["mypackage", "mypackage.sub.utils"]

from . import helper         # загружен лениво: . разрешается в mypackage
from .sub.utils import func  # загружен лениво: .sub.utils разрешается в mypackage.sub.utils
import json                  # загружен немедленно (нет в __lazy_modules__)

future_stmt: "from" "__future__" "import" feature ["as" identifier]
             ("," feature ["as" identifier])*
             | "from" "__future__" "import" "(" feature ["as" identifier]
             ("," feature ["as" identifier])* [","] ")"
feature:     identifier

import __future__ [as name]

7.12. Инструкция global¶The global statement

global_stmt: "global" identifier ("," identifier)*

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

Инструкция global применяется ко всей текущей области видимости (модуль, тело функции или определение класса). Вызывается SyntaxError, если переменная используется или ей присваивается значение до её объявления как глобальной в этой области.

На уровне модуля все переменные являются глобальными, поэтому инструкция global не имеет эффекта. Однако переменные по-прежнему не должны использоваться или получать значение до их объявления с помощью global. Это требование смягчается в интерактивном приглашении (REPL).

Замечание для программистов: global – это директива для парсера. Она применяется только к коду, который разбирается одновременно с инструкцией global. В частности, инструкция global, содержащаяся в строке или объекте кода, переданном встроенной функции exec(), не влияет на блок кода , содержащий вызов функции, а код, содержащийся в такой строке, не подвержен влиянию инструкций global в коде, содержащем вызов функции. То же самое относится к функциям eval() и compile().

7.13. Инструкция nonlocal¶The nonlocal statement

nonlocal_stmt: "nonlocal" identifier ("," identifier)*

Если определение функции или класса вложено (находится внутри) в определения других функций, его нелокальные области видимости – это локальные области видимости окружающих функций. Инструкция nonlocal заставляет перечисленные идентификаторы ссылаться на имена, ранее связанные в нелокальных областях видимости. Она позволяет вложенному коду переназначать такие нелокальные идентификаторы. Если имя связано в нескольких нелокальных областях, используется ближайшее связывание. Если имя не связано ни в одной нелокальной области, или если нелокальной области нет, вызывается SyntaxError.

Инструкция nonlocal применяется ко всей области видимости функции или тела класса. Вызывается SyntaxError, если переменная используется или ей присваивается значение до её объявления как нелокальной в этой области.

Замечание для программистов: nonlocal – это директива для парсера и применяется только к коду, который разбирается вместе с ней. См. примечание для инструкции global.

7.14. Инструкция type¶The type statement

type_stmt: 'type' identifier [type_params] "=" expression

Инструкция type объявляет псевдоним типа, который является экземпляром typing.TypeAliasType.

Например, следующая инструкция создаёт псевдоним типа:

type Point = tuple[float, float]

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

annotation-def VALUE_OF_Point():
    return tuple[float, float]
Point = typing.TypeAliasType("Point", VALUE_OF_Point())

annotation-def указывает на аннотационную область, которая ведёт себя почти как функция, но с несколькими небольшими отличиями.

Значение псевдонима типа вычисляется в области видимости аннотации. Оно не вычисляется при создании псевдонима типа, а только при обращении к значению через атрибут __value__ псевдонима типа (см. Ленивое вычисление). Это позволяет псевдониму типа ссылаться на имена, которые еще не определены.

Псевдонимы типов могут быть обобщёнными, если после имени добавить список параметров типа. Подробнее см. Обобщённые псевдонимы типов.

type – это мягкое ключевое слово.