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

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. Хотя они остаются постоянными в рамках одного процесса Python, они непредсказуемы при повторных запусках 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.

При создании класса 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.

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)

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

При определении в классе __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; если значение key находится вне набора индексов для последовательности (после любой специальной интерпретации отрицательных значений), должно быть поднято исключение IndexError. Для типов отображений, если key отсутствует (не входит в контейнер), должно быть поднято исключение KeyError.

Примечание

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

Примечание

При подстановке в класс может быть вызван специальный метод класса __class_getitem__() вместо __getitem__(). Подробнее см. __class_getitem__ versus __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, если элемент находится в 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’] вызывает исключение, когда сложение работает?), но это поведение на самом деле является частью модели данных.

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. Настройка позиционных аргументов в соответствии с шаблонами классов

При использовании имени класса в шаблоне позиционные аргументы в шаблоне по умолчанию не допускаются, т. е. 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. Поиск специальных методов

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

>>> 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 объявлением, являются awaitable.

object.__await__(self)

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

Примечание

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

3.4.2. Объекты корутин

Объекты корутин являются awaitable объектами. Выполнение корутины можно контролировать, вызвав __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)

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