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

3.2.1. None

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

3.2.2. NotImplemented

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

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

3.2.3. Многоточие

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

3.2.4. numbers.Number

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

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

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

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

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

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

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

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

Если start отсутствует или равен None, срез обрабатывается так, как если бы start был равен нулю. Если stop отсутствует или равен None, срез обрабатывается так, как если бы stop был равен длине последовательности.

Некоторые последовательности также поддерживают «расширенные срезы» с третьим параметром «шаг»: 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 см. в разделе Порядок разрешения методов в 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() объектов сокетов (а также, возможно, другие функции или методы, предоставляемые модулями расширения).

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

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

file.read(size=-1, /)

Получить из файла не более size данных. Для удобства, если size не указан или равен -1, получить все доступные данные.

file.write(data, /)

Записать data в файл.

file.close()

Сбросить все буферы и закрыть соответствующий файл.

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²). Подробности см. по адресу https://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(), clear(), count(), extend(), index(), insert(), pop(), remove() и reverse(), как и стандартные списки 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.

object.__getitem__(self, subscript)

Вызывается для реализации индексации, то есть self[subscript]. Подробнее о синтаксисе см. в разделе Индексация и срезы.

Существуют два типа встроенных объектов, поддерживающих индексацию с помощью __getitem__():

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

Если индекс имеет неподходящий тип, __getitem__() должен вызвать исключение TypeError. Если индекс имеет неподходящее значение, __getitem__() должен вызвать исключение LookupError или одно из его подклассов (IndexError для последовательностей; KeyError для отображений).

Примечание

Обработка срезов выполняется методами __getitem__(), __setitem__() и __delitem__(). Вызов вида

a[1:2] = b

преобразуется в

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

и так далее. Пропущенные элементы среза всегда заменяются на None.

Примечание

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

Примечание

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

object.__setitem__(self, key, value)

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

object.__delitem__(self, key)

Вызывается для реализации удаления self[key]. См. примечание к __getitem__(). Этот метод следует реализовывать для отображений только в том случае, если объекты поддерживают удаление ключей, а для последовательностей — если элементы можно удалять из последовательности. Для недопустимых значений ключа должны вызываться те же исключения, что и для метода __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)

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

Для объектов, в которых не определён __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 или если type(y) является подклассом type(x). [5]

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

Изменено в версии 3.14: Вызов функции pow() с тремя аргументами теперь при необходимости пытается вызвать __rpow__(). Ранее он вызывался только для pow() с двумя аргументами и бинарного оператора возведения в степень.

Примечание

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

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).

Изменено в версии 3.14: 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.

Потокобезопасность: В Python со свободной многопоточностью реализации должны управлять внутренним счётчиком экспортов с помощью атомарных операций. Метод должен быть безопасен при одновременном вызове из нескольких потоков, а базовые данные возвращённого буфера должны оставаться действительными до завершения соответствующего вызова __release_buffer__(). Подробности см. в разделе Потокобезопасность объектов memoryview.

object.__release_buffer__(self, buffer)

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

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

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

3.3.12. Аннотации

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

object.__annotations__

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

Изменено в версии 3.14: Аннотации теперь вычисляются лениво.

object.__annotate__(format)

Функция аннотирования. Возвращает новый объект-словарь, сопоставляющий имена атрибутов и параметров со значениями их аннотаций.

Принимает параметр format, задающий формат предоставления значений аннотаций. Он должен быть элементом перечисления annotationlib.Format либо целым числом, соответствующим значению одного из элементов перечисления.

Если функция аннотирования не поддерживает запрошенный формат, она должна вызвать исключение NotImplementedError. Функции аннотирования всегда должны поддерживать формат VALUE; при вызове с этим форматом они не должны вызывать исключение NotImplementedError().

При вызове с форматом VALUE функция аннотирования может вызвать исключение NameError; при запросе любого другого формата она не должна вызывать NameError.

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

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

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

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

>>> 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.

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

Сопрограммы являются обобщёнными по типам возвращаемых ими значений yield, send и return соответственно.

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')

Сноски