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

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__() вызываются для объектов, которые всё ещё существуют при выходе интерпретатора.

Примечание

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.__str__(self)

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

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

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

object.__bytes__(self)

Вызывается bytes для вычисления байтовой строковой записи объекта. Должен вернуть объект bytes.

object.__format__(self, format_spec)

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

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

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

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

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

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

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__(); с ними все объекты считаются неравными (кроме самих себя) и 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).

Примечание

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

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

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

См. также PYTHONHASHSEED.

Изменено в версии 3.3: Случайное хэширование включено по умолчанию.

object.__bool__(self)

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

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

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

object.__getattr__(self, name)

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

Обратите внимание, что если атрибут найден обычным способом, __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)

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

Если __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.

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

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

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

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

class.__instancecheck__(self, instance)

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

class.__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, ...).

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

Следующие методы могут быть определены для реализации контейнерных объектов. Контейнеры обычно являются последовательностями (такими как lists или tuples) или отображениями (например, dictionaries), но также могут представлять и другие контейнеры. Первый набор методов используется для эмуляции последовательности или отображения; разница заключается в том, что для последовательности допустимыми ключами должны быть целые числа 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]. Для типов последовательностей допустимыми ключами должны быть целые числа и объекты срезов. Обратите внимание, что специальная интерпретация отрицательных индексов (если класс хочет эмулировать тип последовательности) зависит от метода __getitem__(). Если тип key неподходящий, может быть поднято исключение TypeError; если значение за пределами набора индексов для последовательности (после любой специальной интерпретации отрицательных значений), должно быть поднято исключение IndexError. Для типов отображений, если key отсутствует (не содержится в контейнере), должно быть поднято исключение KeyError.

Примечание

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

Примечание

При подстановке в класс может вызываться специальный метод класса __class_getitem__() вместо __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__(), вызывается x.__add__(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__(), вызывается y.__rsub__(x) если x.__sub__(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). Если определённый метод не определён, расширенное присваивание возвращается к обычным методам. Например, если x — экземпляр класса с методом __iadd__(), x += y эквивалентно x = x.__iadd__(y) . В противном случае, рассматриваются x.__add__(y) и y.__radd__(x) , как и при вычислении x + y. В определённых ситуациях расширенное присваивание может привести к непредвиденным ошибкам (см. Почему a_tuple[i] += [‘item’] вызывает исключение, когда сложение работает?), но это поведение на самом деле является частью модели данных.

Примечание

Из-за ошибки в механизме диспетчеризации для **=, класс, который определяет __ipow__(), но возвращает NotImplemented , не сможет перейти к x.__pow__(y) и y.__rpow__(x). Эта ошибка исправлена в Python 3.10.

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(). Если параметр ndigits не передан в __round__(), все эти методы должны возвращать значение объекта, усечённого до Integral (обычно int).

Встроенная функция int() обращается к __trunc__(), если ни __int__(), ни __index__() не определены.

3.3.9. Управляющие контексты оператора with

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

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

Дополнительную информацию о управляющих контекстах см. в Типы управляющих контекстов.

object.__enter__(self)

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

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

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

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

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

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

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

>>> 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. Объекты-ожидания

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

object.__await__(self)

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

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

coroutine.close()

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

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

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

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

Асинхронные итераторы могут использоваться в инструкции async for.

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.__aenter__(self)

Семантически подобен __enter__(), единственное отличие состоит в том, что он должен возвращать awaitable.

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

Семантически подобен __exit__(), единственное отличие состоит в том, что он должен возвращать awaitable.

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

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

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

Примечания

1

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

2

Методы __hash__(), __iter__(), __reversed__() и __contains__() имеют особую обработку в этом случае; другие методы по-прежнему будут поднимать TypeError, но могут делать это, полагаясь на поведение, когда None не является вызываемым.

3

«Не поддерживает» в данном случае означает, что у класса нет такого метода или метод возвращает NotImplemented. Не устанавливайте метод в None, если вы хотите принудительно использовать отражённый метод правого операнда — это вместо этого будет иметь противоположный эффект, явно блокируя такой возврат.

4

Для операндов одного типа предполагается, что если неотражённый метод — такой как __add__() — не удаётся, то операция в целом не поддерживается, поэтому отражённый метод не вызывается.