Модель данных

3.2.1. None

У этого типа есть единственное значение. Существует только один объект с этим значением. К нему обращаются по встроенному имени None. Во многих ситуациях он обозначает отсутствие значения; например, его возвращают функции, которые явно ничего не возвращают. Его логическое значение — ложь.

3.2.2. NotImplemented

У этого типа есть единственное значение. Существует только один объект с этим значением. К нему обращаются по встроенному имени NotImplemented. Числовые методы и методы расширенного сравнения должны возвращать это значение, если они не реализуют операцию для переданных операндов. (Затем интерпретатор попробует выполнить отражённую операцию или применит другой запасной вариант — в зависимости от оператора.) Не следует вычислять его в логическом контексте.

Подробнее см. Реализация арифметических операций.

3.2.3. Ellipsis

У этого типа есть единственное значение. Существует только один объект с этим значением. К нему обращаются с помощью литерала ... или встроенного имени Ellipsis. Его логическое значение — истина.

3.2.4. numbers.Number

Числа создаются числовыми литералами и возвращаются в качестве результатов арифметических операторов и встроенных арифметических функций. Числовые объекты неизменяемы: после создания их значение не меняется. Числа Python, конечно, тесно связаны с математическими числами, но ограничены особенностями представления чисел в компьютерах.

Строковые представления числовых классов, вычисляемые методами __repr__() и __str__(), обладают следующими свойствами:

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

В Python различаются целые числа, числа с плавающей точкой и комплексные числа:

3.2.5. Последовательности

Они представляют собой конечные упорядоченные наборы, индексируемые неотрицательными числами. Встроенная функция len() возвращает количество элементов последовательности. Если длина последовательности равна n, набор индексов содержит числа от 0 до n-1. Элемент i последовательности a выбирается с помощью a[i]. Некоторые последовательности, в том числе встроенные, обрабатывают отрицательные индексы, прибавляя к ним длину последовательности. Например, a[-2] равно a[n-2] — предпоследнему элементу последовательности a длиной n.

Последовательности также поддерживают срезы: a[i:j] выбирает все элементы с индексом k, для которого i <= k < j. При использовании в выражении срез представляет собой последовательность того же типа. Приведённое выше замечание об отрицательных индексах также относится к отрицательным позициям среза.

Некоторые последовательности также поддерживают «расширенную нарезку» с третьим параметром — «шагом»: a[i:j:k] выбирает все элементы a с индексом x, для которого x = i + n*k, n >= 0 и i <= x < j.

Последовательности различаются по изменяемости:

3.2.6. Типы множеств

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

К элементам множеств применяются те же правила неизменяемости, что и к ключам словарей. Обратите внимание, что для числовых типов действуют обычные правила сравнения чисел: если два числа равны при сравнении (например, 1 и 1.0), во множестве может содержаться только одно из них.

В настоящее время существуют два встроенных типа множеств:

Множества

Они представляют изменяемое множество. Такие множества создаются встроенным конструктором set(), а затем могут изменяться с помощью различных методов, например add().

Неизменяемые множества

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

3.2.7. Отображения

Они представляют конечные наборы объектов, индексируемые произвольными наборами индексов. Обозначение индексации a[k] выбирает из отображения a элемент с индексом k; его можно использовать в выражениях и в качестве цели присваивания или оператора del. Встроенная функция len() возвращает количество элементов в отображении.

В настоящее время существует один встроенный тип отображений:

3.2.8. Вызываемые типы

Это типы, к которым можно применить операцию вызова функции (см. раздел Вызовы).

3.2.9. Модули

Модули — базовая организационная единица кода Python. Они создаются системой импорта, вызываемой оператором import или вызовом таких функций, как importlib.import_module() и встроенная функция __import__(). У объекта модуля есть пространство имён, реализованное объектом dictionary (это словарь, на который ссылается атрибут __globals__ функций, определённых в модуле). Обращения к атрибутам преобразуются в обращения к этому словарю, например, m.x эквивалентно m.__dict__["x"]. Объект модуля не содержит объект кода, использованный для инициализации модуля (поскольку после завершения инициализации он не нужен).

Присваивание атрибуту обновляет словарь пространства имён модуля, например, m.x = 1 эквивалентно m.__dict__["x"] = 1.

>>> import typing
>>> typing.__name__, typing.__spec__.name
('typing', 'typing')
>>> typing.__spec__.name = 'spelling'
>>> typing.__name__, typing.__spec__.name
('typing', 'spelling')
>>> typing.__name__ = 'keyboard_smashing'
>>> typing.__name__, typing.__spec__.name
('keyboard_smashing', 'spelling')

3.2.10. Пользовательские классы

Пользовательские типы классов обычно создаются определениями классов (см. раздел Определения классов). У класса есть пространство имён, реализованное объектом-словарём. Обращения к атрибутам класса преобразуются в обращения к этому словарю: например, C.x преобразуется в C.__dict__["x"] (хотя существует несколько механизмов, позволяющих находить атрибуты другими способами). Если имя атрибута там не найдено, поиск продолжается в базовых классах. Для поиска в базовых классах используется порядок разрешения методов C3, который работает корректно даже при наличии «ромбовидных» структур наследования, когда несколько путей наследования ведут к одному общему предку. Дополнительные сведения об используемом Python порядке разрешения методов C3 (C3 MRO) см. в разделе Порядок разрешения методов в Python 2.3.

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

Присваивание атрибутам класса обновляет словарь класса, но никогда — словарь базового класса.

Объект класса можно вызвать (см. выше), чтобы получить экземпляр класса (см. ниже).

3.2.11. Экземпляры классов

Экземпляр класса создаётся вызовом объекта класса (см. выше). У экземпляра класса есть пространство имён, реализованное в виде словаря; именно в нём в первую очередь выполняется поиск при обращении к атрибутам. Если атрибут там не найден, а у класса экземпляра есть атрибут с таким именем, поиск продолжается среди атрибутов класса. Если найденный атрибут класса является объектом пользовательской функции, он преобразуется в объект метода экземпляра, атрибут __self__ которого является экземпляром. Объекты статических методов и методов класса также преобразуются; см. выше раздел «Классы». Другой способ, которым атрибуты класса, полученные через его экземпляры, могут отличаться от объектов, фактически хранящихся в __dict__ класса, описан в разделе Реализация дескрипторов. Если атрибут класса не найден, а у класса объекта есть метод __getattr__(), этот метод вызывается для обработки поиска.

Присваивание атрибутов и их удаление обновляют словарь экземпляра, но никогда — словарь класса. Если у класса есть метод __setattr__() или __delattr__(), вместо непосредственного обновления словаря экземпляра вызывается этот метод.

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

3.2.12. Объекты ввода-вывода (также известные как файловые объекты)

Файловый объект представляет открытый файл. Для создания файловых объектов доступны различные удобные способы: встроенная функция open(), а также os.popen(), os.fdopen() и метод makefile() объектов сокетов (а также, возможно, другие функции или методы, предоставляемые модулями расширений).

Объекты sys.stdin, sys.stdout и sys.stderr инициализируются как файловые объекты, соответствующие стандартным потокам ввода, вывода и ошибок интерпретатора; все они открыты в текстовом режиме и поэтому соответствуют интерфейсу абстрактного класса io.TextIOBase.

3.2.13. Внутренние типы

Некоторые типы, используемые интерпретатором внутри системы, доступны пользователю. Их определения могут измениться в будущих версиях интерпретатора, но для полноты они упоминаются здесь.

3.3.1. Основная настройка

object.__new__(cls[, ...])

Вызывается для создания нового экземпляра класса cls. __new__() — статический метод (обрабатываемый особым образом, поэтому его не нужно объявлять как статический), первым аргументом принимающий класс, экземпляр которого запрошен. Остальные аргументы передаются в выражение-конструктор объекта (вызов класса). Возвращаемым значением __new__() должен быть новый экземпляр объекта (обычно экземпляр cls).

Типичные реализации создают новый экземпляр класса, вызывая метод __new__() суперкласса с помощью super().__new__(cls[, ...]) и подходящих аргументов, а затем при необходимости изменяют только что созданный экземпляр и возвращают его.

Если __new__() вызывается при создании объекта и возвращает экземпляр cls, тогда вызывается метод __init__() нового экземпляра, как в __init__(self[, ...]), где self — новый экземпляр, а остальные аргументы совпадают с переданными конструктору объекта.

Если __new__() не возвращает экземпляр cls, метод __init__() нового экземпляра вызван не будет.

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

object.__init__(self[, ...])

Вызывается после создания экземпляра (методом __new__()), но до его возврата вызывающему коду. Аргументы совпадают с переданными выражению-конструктору класса. Если у базового класса есть метод __init__(), производный класс должен явно вызвать его из своего метода __init__(), если он определён, чтобы обеспечить правильную инициализацию части экземпляра, относящейся к базовому классу; например: super().__init__([args...]).

Так как __new__() и __init__() работают совместно при создании объектов (__new__() создаёт объект, а __init__() настраивает его), метод __init__() не должен возвращать значение, отличное от None; в противном случае во время выполнения будет вызвано исключение TypeError.

object.__del__(self)

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

Метод __del__() может (хотя так делать не рекомендуется!) отложить уничтожение экземпляра, создав на него новую ссылку. Это называется воскрешением объекта. Зависит от реализации, будет ли __del__() вызван повторно, когда воскрешённый объект собираются уничтожить; текущая реализация CPython вызывает его только один раз.

Не гарантируется, что методы __del__() будут вызваны для объектов, которые всё ещё существуют при завершении интерпретатора. weakref.finalize предоставляет простой способ зарегистрировать функцию очистки, которая будет вызвана при сборке объекта сборщиком мусора.

Примечание

del x не вызывает x.__del__() напрямую — первый уменьшает счётчик ссылок x на единицу, а последний вызывается только тогда, когда счётчик ссылок x достигает нуля.

Особенность реализации CPython: Цикл ссылок может помешать счётчику ссылок объекта достичь нуля. В этом случае цикл будет обнаружен и удалён позднее сборщиком циклического мусора. Частая причина циклов ссылок — исключение, сохранённое в локальной переменной. Тогда локальные переменные кадра ссылаются на исключение, которое ссылается на собственную трассировку стека, а та ссылается на локальные переменные всех кадров, попавших в трассировку.

См. также

Документация модуля gc.

Предупреждение

Из-за ненадёжных обстоятельств, при которых вызываются методы __del__(), исключения, возникающие во время их выполнения, игнорируются, а вместо этого предупреждение выводится в sys.stderr. В частности:

• __del__() может быть вызван, когда выполняется произвольный код, в том числе в любом произвольном потоке. Если __del__() потребуется захватить блокировку или обратиться к другому блокирующему ресурсу, может возникнуть взаимная блокировка, поскольку этот ресурс уже может быть занят кодом, выполнение которого было прервано для вызова __del__().
• __del__() может выполняться при завершении работы интерпретатора. В результате глобальные переменные, к которым ему нужно обратиться (включая переменные других модулей), могут быть уже удалены или иметь значение None. Python гарантирует, что глобальные переменные, имена которых начинаются с одного символа подчёркивания, удаляются из модуля до удаления остальных глобальных переменных; если на такие переменные нет других ссылок, это может помочь обеспечить доступность импортированных модулей в момент вызова метода __del__().

object.__repr__(self)

Вызывается встроенной функцией repr() для вычисления «официального» строкового представления объекта. По возможности оно должно выглядеть как допустимое выражение Python, которое можно использовать для воссоздания объекта с тем же значением (при наличии подходящего окружения). Если это невозможно, следует вернуть строку вида <...some useful description...>. Возвращаемое значение должно быть строковым объектом. Если класс определяет __repr__(), но не __str__(), метод __repr__() также используется, когда требуется «неформальное» строковое представление экземпляров этого класса.

Этот метод обычно используется для отладки, поэтому важно, чтобы представление было информативным и однозначным. Класс object предоставляет реализацию по умолчанию.

object.__str__(self)

Вызывается функцией str(object), реализацией __format__() по умолчанию и встроенной функцией print() для вычисления «неформального» или удобного для вывода строкового представления объекта. Возвращаемое значение должно быть объектом str.

Этот метод отличается от object.__repr__() тем, что от __str__() не требуется возвращать допустимое выражение Python: можно использовать более удобное или краткое представление.

Реализация по умолчанию, определённая встроенным типом object, вызывает object.__repr__().

object.__bytes__(self)

Вызывается функцией bytes для вычисления байтового представления объекта. Метод должен возвращать объект bytes. Сам класс object этот метод не предоставляет.

object.__format__(self, format_spec)

Вызывается встроенной функцией format(), а также, косвенно, при вычислении форматированных строковых литералов и метода str.format(), чтобы получить «форматированное» строковое представление объекта. Аргумент format_spec — это строка с описанием желаемых параметров форматирования. Интерпретация аргумента format_spec зависит от типа, реализующего __format__(), однако большинство классов либо делегируют форматирование одному из встроенных типов, либо используют похожий синтаксис параметров форматирования.

Описание стандартного синтаксиса форматирования см. в разделе Мини-язык спецификации формата.

Возвращаемое значение должно быть строковым объектом.

Реализации по умолчанию класса object следует передавать пустую строку format_spec. Она делегирует вызов __str__().

Изменено в версии 3.4: Метод __format__ самого object теперь вызывает TypeError, если ему передана непустая строка.

Изменено в версии 3.7: Теперь object.__format__(x, '') эквивалентно str(x), а не format(str(x), '').

object.__lt__(self, other)

object.__le__(self, other)

object.__eq__(self, other)

object.__ne__(self, other)

object.__gt__(self, other)

object.__ge__(self, other)

Это так называемые методы «расширенного сравнения». Соответствие символов операторов и имён методов выглядит так: x<y вызывает x.__lt__(y), x<=y вызывает x.__le__(y), x==y вызывает x.__eq__(y), x!=y вызывает x.__ne__(y), x>y вызывает x.__gt__(y), а x>=y вызывает x.__ge__(y).

Метод расширенного сравнения может вернуть синглтон NotImplemented, если он не реализует операцию для данной пары аргументов. По соглашению при успешном сравнении возвращаются False и True. Однако эти методы могут возвращать любое значение, поэтому, если оператор сравнения используется в булевом контексте (например, в условии оператора if), Python вызовет для значения bool(), чтобы определить, истинно оно или ложно.

По умолчанию object реализует __eq__() с помощью is, возвращая NotImplemented при ложном сравнении: True if x is y else NotImplemented. По умолчанию __ne__() делегирует вызов __eq__() и инвертирует результат, если он не равен NotImplemented. Между операторами сравнения и реализациями по умолчанию нет других подразумеваемых взаимосвязей; например, истинность (x<y or x==y) не означает истинность x<=y. Чтобы автоматически сгенерировать операции упорядочивания на основе одной корневой операции, см. functools.total_ordering().

По умолчанию класс object предоставляет реализации, соответствующие разделу Сравнение значений: равенство определяется идентичностью объектов, а сравнение на порядок вызывает TypeError. Каждый метод по умолчанию может непосредственно выдавать эти результаты, но также может возвращать NotImplemented.

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

Для этих методов не предусмотрены версии с переставленными аргументами (на случай, когда левый аргумент не поддерживает операцию, а правый поддерживает); вместо этого __lt__() и __gt__() являются отражениями друг друга, __le__() и __ge__() также являются отражениями друг друга, а __eq__() и __ne__() являются отражениями самих себя. Если операнды имеют разные типы и тип правого операнда является прямым или косвенным подклассом типа левого операнда, приоритет имеет отражённый метод правого операнда; в противном случае приоритет имеет метод левого операнда. Виртуальное наследование не учитывается.

Если ни один подходящий метод не возвращает значение, отличное от NotImplemented, операторы == и != переходят соответственно к is и is not.

object.__hash__(self)

Вызывается встроенной функцией hash() и при выполнении операций над элементами хешируемых коллекций, включая set, frozenset и dict. Метод __hash__() должен возвращать целое число. Единственное обязательное свойство: объекты, которые считаются равными, должны иметь одинаковые хеш-значения; рекомендуется объединять хеш-значения компонентов объекта, участвующих также в сравнении объектов, помещая их в кортеж и вычисляя его хеш. Пример:

def __hash__(self):
    return hash((self.name, self.nick, self.color))

Примечание

hash() усекает значение, возвращённое пользовательским методом объекта __hash__(), до размера Py_ssize_t. Обычно это 8 байт в 64-разрядных сборках и 4 байта в 32-разрядных. Если метод __hash__() объекта должен работать в сборках с разной разрядностью, обязательно проверьте разрядность во всех поддерживаемых сборках. Это легко сделать с помощью python -c "import sys; print(sys.hash_info.width)".

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

Пользовательские классы по умолчанию имеют методы __eq__() и __hash__() (унаследованные от класса object); благодаря им все объекты считаются неравными (кроме сравнения с самими собой), а x.__hash__() возвращает подходящее значение, так что из x == y следует одновременно, что x is y и hash(x) == hash(y).

У класса, переопределяющего __eq__() и не определяющего __hash__(), значение __hash__() неявно устанавливается в None. Если метод __hash__() класса имеет значение None, при попытке получить хеш-значение экземпляра этого класса программа вызовет соответствующее исключение TypeError; кроме того, при проверке с помощью isinstance(obj, collections.abc.Hashable) экземпляр будет правильно определён как нехешируемый.

Если классу, переопределяющему __eq__(), нужно сохранить реализацию __hash__() родительского класса, интерпретатору нужно явно сообщить об этом, присвоив __hash__ = <ParentClass>.__hash__.

Если класс, не переопределяющий __eq__(), хочет отключить поддержку хеширования, ему следует включить __hash__ = None в определение класса. Класс, определяющий собственный __hash__(), который явно вызывает исключение TypeError, будет ошибочно считаться хешируемым при вызове isinstance(obj, collections.abc.Hashable).

Примечание

По умолчанию значения __hash__() объектов str и bytes «солью» смешиваются с непредсказуемым случайным значением. Хотя в пределах одного процесса Python они остаются постоянными, при повторных запусках Python их нельзя предсказать.

Это предназначено для защиты от отказа в обслуживании, вызванного специально подобранными входными данными, которые используют наихудшую производительность вставки в dict с квадратичной сложностью O(n²). Подробности см. по адресу http://ocert.org/advisories/ocert-2011-003.html.

Изменение хеш-значений влияет на порядок обхода множеств. Python никогда не гарантировал этот порядок (и обычно он различается в 32- и 64-разрядных сборках).

См. также PYTHONHASHSEED.

Изменено в версии 3.3: Рандомизация хешей включена по умолчанию.

object.__bool__(self)

Вызывается для проверки истинности значения и выполнения встроенной операции bool(); должен возвращать False или True. Если этот метод не определён, вызывается __len__(), если он определён, и объект считается истинным, если результат ненулевой. Если класс не определяет ни __len__(), ни __bool__() (как, например, сам класс object), все его экземпляры считаются истинными.

3.3.2. Настройка доступа к атрибутам

Для настройки смысла доступа к атрибутам (использования, присваивания или удаления x.name) для экземпляров классов можно определить следующие методы.

object.__getattr__(self, name)

Вызывается, когда стандартный доступ к атрибуту завершается ошибкой AttributeError (либо __getattribute__() вызывает AttributeError, потому что name не является атрибутом экземпляра или атрибутом в иерархии классов для self; либо __get__() свойства name вызывает AttributeError). Этот метод должен либо возвращать вычисленное значение атрибута, либо вызывать исключение AttributeError. Сам класс object этот метод не предоставляет.

Обратите внимание: если атрибут найден обычным способом, __getattr__() не вызывается. (Это намеренная асимметрия между __getattr__() и __setattr__().) Это сделано как по соображениям эффективности, так и потому, что иначе у __getattr__() не было бы способа получить доступ к другим атрибутам экземпляра. Обратите внимание: по крайней мере для переменных экземпляра можно полностью взять управление на себя, не помещая значения в словарь атрибутов экземпляра (а вместо этого помещая их в другой объект). См. приведённый ниже метод __getattribute__(), позволяющий действительно полностью контролировать доступ к атрибутам.

object.__getattribute__(self, name)

Вызывается безусловно для реализации доступа к атрибутам экземпляров класса. Если класс также определяет __getattr__(), последний не будет вызван, если только __getattribute__() не вызовет его явно или не вызовет исключение AttributeError. Этот метод должен возвращать вычисленное значение атрибута или вызывать исключение AttributeError. Чтобы избежать бесконечной рекурсии в этом методе, его реализация всегда должна вызывать одноимённый метод базового класса для доступа к нужным атрибутам, например, object.__getattribute__(self, name).

Примечание

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

При определённых обращениях к чувствительным атрибутам вызывает событие аудита object.__getattr__ с аргументами obj и name.

object.__setattr__(self, name, value)

Вызывается при попытке присвоить атрибут. Вызывается вместо обычного механизма (то есть сохранения значения в словаре экземпляра). name — имя атрибута, value — присваиваемое ему значение.

Если __setattr__() требуется присвоить атрибут экземпляра, ему следует вызвать одноимённый метод базового класса, например, object.__setattr__(self, name, value).

При определённых операциях присваивания чувствительным атрибутам вызывает событие аудита object.__setattr__ с аргументами obj, name, value.

object.__delattr__(self, name)

Подобен __setattr__(), но вызывается при удалении атрибута, а не при присваивании. Его следует реализовывать, только если del obj.name имеет смысл для объекта.

При определённых операциях удаления чувствительных атрибутов вызывает событие аудита object.__delattr__ с аргументами obj и name.

object.__dir__(self)

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

import sys
from types import ModuleType

class VerboseModule(ModuleType):
    def __repr__(self):
        return f'Verbose {self.__name__}'

    def __setattr__(self, attr, value):
        print(f'Setting {attr}...')
        super().__setattr__(attr, value)

sys.modules[__name__].__class__ = VerboseModule

3.3.3. Настройка создания классов

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

classmethod object.__init_subclass__(cls)

Этот метод вызывается каждый раз при создании подкласса содержащего его класса. В этом случае cls — это новый подкласс. Если метод определён как обычный метод экземпляра, он неявно преобразуется в метод класса.

Ключевые аргументы, переданные новому классу, передаются в __init_subclass__ родительского класса. Для совместимости с другими классами, использующими __init_subclass__, следует извлечь необходимые ключевые аргументы и передать остальные базовому классу, как показано ниже:

class Philosopher:
    def __init_subclass__(cls, /, default_name, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.default_name = default_name

class AustralianPhilosopher(Philosopher, default_name="Bruce"):
    pass

Реализация по умолчанию object.__init_subclass__ ничего не делает, но вызывает ошибку, если ей переданы какие-либо аргументы.

Примечание

Подсказка метакласса metaclass обрабатывается остальной частью механизма типов и никогда не передаётся реализациям __init_subclass__. Доступ к фактическому метаклассу (а не к явной подсказке) можно получить через type(cls).

Добавлено в версии 3.6.

При создании класса type.__new__() просматривает переменные класса и вызывает методы с хуком __set_name__().

object.__set_name__(self, owner, name)

Автоматически вызывается при создании класса-владельца owner. Объекту присвоено имя name в этом классе:

class A:
    x = C()  # Automatically calls: x.__set_name__(A, 'x')

Если переменной класса присвоено значение после создания класса, __set_name__() не будет вызван автоматически. При необходимости __set_name__() можно вызвать напрямую:

class A:
   pass

c = C()
A.x = c                  # The hook is not called
c.__set_name__(A, 'x')   # Manually invoke the hook

Подробнее см. раздел Создание объекта класса.

Добавлено в версии 3.6.

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

3.3.4. Настройка проверок экземпляров и подклассов

Следующие методы используются для переопределения поведения по умолчанию встроенных функций isinstance() и issubclass().

В частности, метакласс abc.ABCMeta реализует эти методы, чтобы разрешить добавление абстрактных базовых классов (ABC) в качестве «виртуальных базовых классов» для любого класса или типа (включая встроенные типы), в том числе для других ABC.

type.__instancecheck__(self, instance)

Возвращает true, если instance следует считать (прямым или косвенным) экземпляром class. Если метод определён, вызывается для реализации isinstance(instance, class).

type.__subclasscheck__(self, subclass)

Возвращает true, если subclass следует считать (прямым или косвенным) подклассом class. Если метод определён, вызывается для реализации issubclass(subclass, class).

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

3.3.5. Эмуляция обобщённых типов

При использовании аннотаций типов часто бывает полезно параметризовать обобщённый тип, используя нотацию квадратных скобок Python. Например, аннотацию list[int] можно использовать для обозначения list, все элементы которой имеют тип int.

Как правило, класс можно параметризовать, только если в нём определён специальный метод класса __class_getitem__().

classmethod object.__class_getitem__(cls, key)

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

Если __class_getitem__() определён в классе, он автоматически становится методом класса. Поэтому при его определении нет необходимости декорировать его с помощью @classmethod.

from inspect import isclass

def subscribe(obj, x):
    """Return the result of the expression 'obj[x]'"""

    class_of_obj = type(obj)

    # If the class of obj defines __getitem__,
    # call class_of_obj.__getitem__(obj, x)
    if hasattr(class_of_obj, '__getitem__'):
        return class_of_obj.__getitem__(obj, x)

    # Else, if obj is a class and defines __class_getitem__,
    # call obj.__class_getitem__(x)
    elif isclass(obj) and hasattr(obj, '__class_getitem__'):
        return obj.__class_getitem__(x)

    # Else, raise an exception
    else:
        raise TypeError(
            f"'{class_of_obj.__name__}' object is not subscriptable"
        )

>>> # list has class "type" as its metaclass, like most classes:
>>> type(list)
<class 'type'>
>>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
True
>>> # "list[int]" calls "list.__class_getitem__(int)"
>>> list[int]
list[int]
>>> # list.__class_getitem__ returns a GenericAlias object:
>>> type(list[int])
<class 'types.GenericAlias'>

>>> from enum import Enum
>>> class Menu(Enum):
...     """A breakfast menu"""
...     SPAM = 'spam'
...     BACON = 'bacon'
...
>>> # Enum classes have a custom metaclass:
>>> type(Menu)
<class 'enum.EnumMeta'>
>>> # EnumMeta defines __getitem__,
>>> # so __class_getitem__ is not called,
>>> # and the result is not a GenericAlias object:
>>> Menu['SPAM']
<Menu.SPAM: 'spam'>
>>> type(Menu['SPAM'])
<enum 'Menu'>

3.3.6. Эмуляция вызываемых объектов

object.__call__(self[, args...])

Вызывается, когда экземпляр «вызывается» как функция; если этот метод определён, x(arg1, arg2, ...) приблизительно эквивалентен type(x).__call__(x, arg1, ...). Сам класс object не предоставляет этот метод.

3.3.7. Эмуляция типов контейнеров

Для реализации объектов-контейнеров можно определить следующие методы. Ни один из них не предоставляется самим классом object. Контейнеры обычно являются последовательностями (например, lists или tuples) или отображениями (например, словарями), но также могут представлять и другие контейнеры. Первый набор методов используется для эмуляции последовательности или отображения; разница в том, что для последовательности допустимыми ключами должны быть целые числа k, для которых 0 <= k < N, где N — длина последовательности, либо объекты slice, задающие диапазон элементов. Также рекомендуется, чтобы отображения предоставляли методы keys(), values(), items(), get(), clear(), setdefault(), pop(), popitem(), copy() и update(), работающие аналогично соответствующим методам стандартных объектов Python dictionary. Модуль collections.abc предоставляет абстрактный базовый класс MutableMapping, помогающий создать эти методы на основе набора методов __getitem__(), __setitem__(), __delitem__() и keys(). Изменяемые последовательности должны предоставлять методы append(), count(), index(), extend(), insert(), pop(), remove(), reverse() и sort(), как у стандартных списков Python list. Наконец, типы последовательностей должны поддерживать сложение (то есть конкатенацию) и умножение (то есть повторение), определяя описанные ниже методы __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() и __imul__(); другие арифметические операторы определять не следует. Рекомендуется, чтобы и отображения, и последовательности реализовывали метод __contains__(), обеспечивающий эффективное использование оператора in; для отображений метод in должен искать среди ключей отображения, а для последовательностей — среди значений. Кроме того, рекомендуется, чтобы и отображения, и последовательности реализовывали метод __iter__(), обеспечивающий эффективный перебор контейнера; для отображений метод __iter__() должен перебирать ключи объекта, а для последовательностей — значения.

object.__len__(self)

Вызывается для реализации встроенной функции len(). Должен возвращать длину объекта — целое число >= 0. Кроме того, объект, у которого не определён метод __bool__() и метод __len__() которого возвращает ноль, считается ложным в логическом контексте.

Особенность реализации CPython: В CPython длина не должна превышать sys.maxsize. Если длина больше sys.maxsize, некоторые функции (например, len()) могут вызвать исключение OverflowError. Чтобы при проверке логического значения не возникало исключение OverflowError, объект должен определять метод __bool__().

object.__length_hint__(self)

Вызывается для реализации operator.length_hint(). Должен возвращать предполагаемую длину объекта (которая может быть больше или меньше фактической длины). Длина должна быть целым числом >= 0. Возвращаемым значением также может быть NotImplemented; оно обрабатывается так же, как если бы метода __length_hint__ вовсе не существовало. Этот метод служит исключительно для оптимизации и никогда не требуется для корректной работы.

Добавлено в версии 3.4.

a[1:2] = b

a[slice(1, 2, None)] = b

object.__getitem__(self, key)

Вызывается для реализации вычисления self[key]. Для типов последовательностей допустимыми ключами должны быть целые числа. При желании также можно поддерживать объекты slice. Поддержка отрицательных индексов также необязательна. Если key имеет неподходящий тип, можно вызвать исключение TypeError; если key находится вне множества индексов последовательности (после специальной интерпретации отрицательных значений), следует вызвать исключение IndexError. Для типов отображений, если key отсутствует (то есть не входит в контейнер), следует вызвать исключение KeyError.

Примечание

Циклы for предполагают, что для недопустимых индексов будет вызвано исключение IndexError, чтобы корректно определить конец последовательности.

Примечание

При индексировании класса вместо __getitem__() может быть вызван специальный метод класса __class_getitem__(). Подробнее см. раздел __class_getitem__ и __getitem__.

object.__setitem__(self, key, value)

Вызывается для реализации присваивания self[key]. См. примечание к методу __getitem__(). Этот метод следует реализовывать только для отображений, если объекты поддерживают изменение значений по ключам или добавление новых ключей, либо для последовательностей, если элементы можно заменять. При недопустимых значениях key следует вызывать те же исключения, что и в методе __getitem__().

object.__delitem__(self, key)

Вызывается для реализации удаления self[key]. См. примечание к методу __getitem__(). Этот метод следует реализовывать только для отображений, если объекты поддерживают удаление ключей, либо для последовательностей, если из последовательности можно удалять элементы. При недопустимых значениях key следует вызывать те же исключения, что и в методе __getitem__().

object.__missing__(self, key)

Вызывается методом dict.__getitem__() для реализации self[key] в подклассах dict, если ключ отсутствует в словаре.

object.__iter__(self)

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

object.__reversed__(self)

Вызывается (если определён) встроенной функцией reversed() для реализации обратного перебора. Метод должен возвращать новый объект-итератор, который перебирает все объекты контейнера в обратном порядке.

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

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

object.__contains__(self, item)

Вызывается для реализации операторов проверки принадлежности. Должен возвращать True, если item входит в self, и False в противном случае. Для объектов-отображений следует проверять ключи отображения, а не значения или пары ключ-значение.

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

3.3.8. Эмуляция числовых типов

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

object.__add__(self, other)

object.__sub__(self, other)

object.__mul__(self, other)

object.__matmul__(self, other)

object.__truediv__(self, other)

object.__floordiv__(self, other)

object.__mod__(self, other)

object.__divmod__(self, other)

object.__pow__(self, other[, modulo])

object.__lshift__(self, other)

object.__rshift__(self, other)

object.__and__(self, other)

object.__xor__(self, other)

object.__or__(self, other)

Эти методы вызываются для реализации бинарных арифметических операций (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |). Например, для вычисления выражения x + y, где x — экземпляр класса с методом __add__(), вызывается type(x).__add__(x, y). Метод __divmod__() должен быть эквивалентен использованию __floordiv__() и __mod__(); он не должен быть связан с __truediv__(). Обратите внимание: если требуется поддержка трёхаргументной версии встроенной функции pow(), метод __pow__() следует определить так, чтобы он принимал необязательный третий аргумент.

Если один из этих методов не поддерживает операцию с переданными аргументами, он должен вернуть NotImplemented.

object.__radd__(self, other)

object.__rsub__(self, other)

object.__rmul__(self, other)

object.__rmatmul__(self, other)

object.__rtruediv__(self, other)

object.__rfloordiv__(self, other)

object.__rmod__(self, other)

object.__rdivmod__(self, other)

object.__rpow__(self, other[, modulo])

object.__rlshift__(self, other)

object.__rrshift__(self, other)

object.__rand__(self, other)

object.__rxor__(self, other)

object.__ror__(self, other)

Эти методы вызываются для реализации бинарных арифметических операций (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |) с отражёнными (переставленными) операндами. Эти функции вызываются только в том случае, если левый операнд не поддерживает соответствующую операцию [3], а типы операндов различаются. [4] Например, для вычисления выражения x - y, где y — экземпляр класса с методом __rsub__(), вызывается type(y).__rsub__(y, x), если type(x).__sub__(x, y) возвращает NotImplemented.

Обратите внимание: трёхаргументная функция pow() не пытается вызвать __rpow__() (правила приведения типов стали бы слишком сложными).

Примечание

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

object.__iadd__(self, other)

object.__isub__(self, other)

object.__imul__(self, other)

object.__imatmul__(self, other)

object.__itruediv__(self, other)

object.__ifloordiv__(self, other)

object.__imod__(self, other)

object.__ipow__(self, other[, modulo])

object.__ilshift__(self, other)

object.__irshift__(self, other)

object.__iand__(self, other)

object.__ixor__(self, other)

object.__ior__(self, other)

Эти методы вызываются для реализации арифметических операций с присваиванием (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=). Эти методы должны по возможности выполнять операцию на месте (изменяя self) и возвращать результат (которым может быть, но не обязательно является, self). Если определённого метода нет или он возвращает NotImplemented, операция с присваиванием переходит к обычным методам. Например, если x — экземпляр класса с методом __iadd__(), x += y эквивалентно x = x.__iadd__(y) . Если __iadd__() не существует или x.__iadd__(y) возвращает NotImplemented, рассматриваются x.__add__(y) и y.__radd__(x), как и при вычислении x + y. В некоторых ситуациях операция с присваиванием может привести к неожиданным ошибкам (см. Почему a_tuple[i] += [‘item’] вызывает исключение, если сложение работает?), однако такое поведение является частью модели данных.

object.__neg__(self)

object.__pos__(self)

object.__abs__(self)

object.__invert__(self)

Вызывается для реализации унарных арифметических операций (-, +, abs() и ~).

object.__complex__(self)

object.__int__(self)

object.__float__(self)

Вызывается для реализации встроенных функций complex(), int() и float(). Должен возвращать значение соответствующего типа.

object.__index__(self)

Вызывается для реализации operator.index(), а также всякий раз, когда Python требуется преобразовать числовой объект в целочисленный объект без потери данных (например, при создании среза или вызове встроенных функций bin(), hex() и oct()). Наличие этого метода указывает на то, что числовой объект относится к целочисленному типу. Метод должен возвращать целое число.

Если методы __int__(), __float__() и __complex__() не определены, соответствующие встроенные функции int(), float() и complex() используют в качестве запасного варианта __index__().

object.__round__(self[, ndigits])

object.__trunc__(self)

object.__floor__(self)

object.__ceil__(self)

Вызывается для реализации встроенной функции round() и функций модуля math: trunc(), floor() и ceil(). Если в __round__() не передан аргумент ndigits, все эти методы должны возвращать значение объекта, усечённое до целого числа типа Integral (обычно int).

Встроенная функция int() использует __trunc__() в качестве запасного варианта, если не определён ни __int__(), ни __index__().

Изменено в версии 3.11: Передача вызова int() методу __trunc__() объявлена устаревшей.

3.3.9. Менеджеры контекста оператора with

Менеджер контекста — это объект, который определяет контекст выполнения, устанавливаемый при выполнении оператора with. Менеджер контекста отвечает за вход в нужный контекст выполнения и выход из него при выполнении блока кода. Обычно менеджеры контекста вызываются с помощью оператора with (описанного в разделе Оператор with), но их методы можно вызывать и напрямую.

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

Дополнительные сведения о менеджерах контекста см. в разделе Типы менеджеров контекста. Сам класс object не предоставляет методы менеджера контекста.

object.__enter__(self)

Входит в контекст выполнения, связанный с этим объектом. Оператор with привяжет возвращаемое этим методом значение к целевой переменной или переменным, указанным в предложении as оператора, если таковое имеется.

object.__exit__(self, exc_type, exc_value, traceback)

Выходит из контекста выполнения, связанного с этим объектом. Параметры описывают исключение, из-за которого был завершён контекст. Если контекст был завершён без исключения, все три аргумента будут равны None.

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

Обратите внимание: методы __exit__() не должны повторно возбуждать переданное исключение; это обязанность вызывающего кода.

3.3.10. Настройка позиционных аргументов при сопоставлении с образцом класса

При использовании имени класса в образце позиционные аргументы в образце по умолчанию не допускаются, то есть case MyClass(x, y) обычно недопустимо без специальной поддержки в MyClass. Чтобы использовать такой образец, класс должен определить атрибут __match_args__.

object.__match_args__

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

Например, если MyClass.__match_args__ равно ("left", "center", "right"), это означает, что case MyClass(x, y) эквивалентно case MyClass(left=x, center=y). Обратите внимание: число аргументов в образце должно быть меньше или равно числу элементов в __match_args__; в противном случае попытка сопоставления с образцом вызовет исключение TypeError.

3.3.11. Эмуляция буферных типов

Протокол буфера позволяет объектам Python предоставлять эффективный доступ к низкоуровневому массиву в памяти. Этот протокол реализован встроенными типами, такими как bytes и memoryview, а сторонние библиотеки могут определять дополнительные буферные типы.

Хотя буферные типы обычно реализуются на C, протокол также можно реализовать на Python.

object.__buffer__(self, flags)

Вызывается, когда у self запрашивается буфер (например, конструктором memoryview). Аргумент flags — это целое число, обозначающее тип запрошенного буфера и, например, определяющее, будет ли возвращённый буфер доступен только для чтения или для записи. inspect.BufferFlags позволяет удобно интерпретировать флаги. Метод должен вернуть объект memoryview.

object.__release_buffer__(self, buffer)

Вызывается, когда буфер больше не нужен. Аргумент buffer — это объект memoryview, ранее возвращённый методом __buffer__(). Метод должен освободить все ресурсы, связанные с буфером. Этот метод должен вернуть None. Буферным объектам, которым не требуется выполнять очистку, реализовывать этот метод необязательно.

3.3.12. Поиск специальных методов

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

>>> class C:
...     pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()

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

>>> 1 .__hash__() == hash(1)
True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an argument

Неправильную попытку вызвать таким образом несвязанный метод класса иногда называют «путаницей метаклассов». Чтобы её избежать, при поиске специальных методов обходят экземпляр:

>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True

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

>>> class Meta(type):
...     def __getattribute__(*args):
...         print("Metaclass getattribute invoked")
...         return type.__getattribute__(*args)
...
>>> class C(object, metaclass=Meta):
...     def __len__(self):
...         return 10
...     def __getattribute__(*args):
...         print("Class getattribute invoked")
...         return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__()                 # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c)          # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c)                      # Implicit lookup
10

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

3.4.1. Объекты, допускающие ожидание

Объект, допускающий ожидание, обычно реализует метод __await__(). Объекты сопрограмм, возвращаемые функциями async def, допускают ожидание.

object.__await__(self)

Должен возвращать итератор. Используется для реализации объектов, допускающих ожидание. Например, asyncio.Future реализует этот метод для совместимости с выражением await. Сам класс object не допускает ожидание и не предоставляет этот метод.

Примечание

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

3.4.2. Объекты сопрограмм

Объекты сопрограмм — это объекты, допускающие ожидание. Выполнением сопрограммы можно управлять, вызывая __await__() и перебирая результат. Когда выполнение сопрограммы завершается и она возвращает результат, итератор вызывает исключение StopIteration, а атрибут value этого исключения содержит возвращаемое значение. Если сопрограмма вызывает исключение, итератор передаёт его дальше. Сопрограммы не должны напрямую вызывать необработанные исключения StopIteration.

У сопрограмм также есть перечисленные ниже методы, аналогичные методам генераторов (см. раздел Методы итератора-генератора). Однако, в отличие от генераторов, сопрограммы не поддерживают непосредственный перебор.

coroutine.send(value)

Запускает или возобновляет выполнение сопрограммы. Если value равно None, это равносильно переходу к следующему элементу итератора, возвращённого методом __await__(). Если value не равно None, этот метод делегирует вызов методу send() итератора, из-за которого выполнение сопрограммы было приостановлено. Результат (возвращаемое значение, StopIteration или другое исключение) совпадает с результатом перебора возвращаемого значения __await__(), описанного выше.

coroutine.throw(value)

coroutine.throw(type[, value[, traceback]])

Вызывает указанное исключение в сопрограмме. Если у итератора, из-за которого выполнение сопрограммы было приостановлено, есть метод throw(), этот метод делегирует ему вызов. В противном случае исключение вызывается в точке приостановки. Результат (возвращаемое значение, StopIteration или другое исключение) совпадает с результатом перебора возвращаемого значения __await__(), описанного выше. Если исключение не перехвачено в сопрограмме, оно передаётся вызывающему коду.

Изменено в версии 3.12: Вторая сигнатура (type[, value[, traceback]]) устарела и может быть удалена в будущей версии Python.

coroutine.close()

Заставляет сопрограмму выполнить очистку и завершиться. Если сопрограмма приостановлена, этот метод сначала делегирует вызов методу close() итератора, из-за которого выполнение сопрограммы было приостановлено, если такой метод имеется. Затем он вызывает исключение GeneratorExit в точке приостановки, заставляя сопрограмму немедленно выполнить очистку. Наконец, сопрограмма помечается как завершившая выполнение, даже если она ни разу не запускалась.

Объекты сопрограмм автоматически закрываются описанным выше способом перед уничтожением.

3.4.3. Асинхронные итераторы

Асинхронный итератор может вызывать асинхронный код в своём методе __anext__.

Асинхронные итераторы можно использовать в операторе async for.

Сам класс object не предоставляет эти методы.

object.__aiter__(self)

Должен возвращать объект асинхронного итератора.

object.__anext__(self)

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

Пример асинхронного итерируемого объекта:

class Reader:
    async def readline(self):
        ...

    def __aiter__(self):
        return self

    async def __anext__(self):
        val = await self.readline()
        if val == b'':
            raise StopAsyncIteration
        return val

3.4.4. Асинхронные менеджеры контекста

Асинхронный менеджер контекста — это менеджер контекста, который может приостанавливать выполнение в своих методах __aenter__ и __aexit__.

Асинхронные менеджеры контекста можно использовать в операторе async with.

Сам класс object не предоставляет эти методы.

object.__aenter__(self)

Семантически аналогичен методу __enter__(); единственное отличие состоит в том, что он должен возвращать объект, допускающий ожидание.

object.__aexit__(self, exc_type, exc_value, traceback)

Семантически аналогичен методу __exit__(); единственное отличие состоит в том, что он должен возвращать объект, допускающий ожидание.

Пример класса асинхронного менеджера контекста:

class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')

    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')

Сноски