Простые инструкции

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

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

expression_stmt ::= starred_expression

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

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

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

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

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

(Синтаксис attributeref, subscription и slicing определён в разделе Основные выражения.)

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

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

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

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

• Иначе:

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

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

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

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

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

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

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

  class Cls:
      x = 3             # class variable
  inst = Cls()
  inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3
  

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

• Если цель является подпиской: вычисляется основное выражение в ссылке. Оно должно возвращать либо изменяемый объект-последовательность (например, список), либо объект-отображение (например, словарь). Затем вычисляется выражение индекса.

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

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

  Для объектов, определённых пользователем, вызывается метод __setitem__() с соответствующими аргументами.

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

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

x = [0, 1]
i = 0
i, x[i] = 1, 2         # i is updated, then x[i] is updated
print(x)

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

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

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

Инструкции 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, а при запросе оптимизации (параметр командной строки -O) — False. Текущий генератор кода не создаёт код для инструкции assert, если при компиляции запрошена оптимизация. Обратите внимание, что включать исходный код выражения, которое не прошло проверку, в сообщение об ошибке не требуется: он будет показан в трассировке стека.

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

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

pass_stmt ::= "pass"

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

def f(arg): pass    # a function that does nothing (yet)

class C: pass       # a class with no methods (yet)

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

del_stmt ::= "del" target_list

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

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

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

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

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

return_stmt ::= "return" [expression_list]

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

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

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

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

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

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

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

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

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

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

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

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

При вызове исключения обычно автоматически создаётся объект трассировки стека и прикрепляется к нему как атрибут __traceback__. Создать исключение и за один шаг установить собственную трассировку стека можно с помощью метода исключения with_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

break_stmt ::= "break"

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

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

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

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

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

continue_stmt ::= "continue"

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

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

7.11. Оператор import

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

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

1. поиск модуля, его загрузка и инициализация, если это необходимо;
2. определение имени или имен в локальном пространстве имён для области видимости, в которой находится оператор import.

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

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

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

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

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

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

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

   1. проверка, есть ли у импортированного модуля атрибут с таким именем;
   2. если нет, попытка импортировать подмодуль с таким именем, после чего повторная проверка наличия этого атрибута у импортированного модуля;
   3. если атрибут не найден, возникает исключение ImportError;
   4. в противном случае ссылка на это значение сохраняется в локальном пространстве имён под именем из предложения as, если оно указано, или под именем атрибута.

Примеры:

import foo                 # foo imported and bound locally
import foo.bar.baz         # foo, foo.bar, and foo.bar.baz imported, foo bound locally
import foo.bar.baz as fbb  # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as fbb
from foo.bar import baz    # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as baz
from foo import attr       # foo imported and foo.attr bound as attr

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

Общедоступные имена, определённые модулем, определяются по пространству имён модуля: проверяется, есть ли в нём переменная с именем __all__; если есть, она должна быть последовательностью строк, содержащих имена, определённые или импортированные этим модулем. Все имена, указанные в __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.

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

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

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

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

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

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

7.13. Оператор nonlocal

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

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

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

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

7.14. Оператор type

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 — это мягкое ключевое слово.