3. Модель данных¶Data model

3.2.1. None¶

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

3.2.2. NotImplemented¶

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

См. Реализация арифметических операций для получения дополнительных сведений.

3.2.3. Ellipsis¶

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

3.2.4. numbers.Number¶

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

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

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

• Представление, когда возможно, даётся по основанию 10.

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

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

• Знак отображается только для отрицательных чисел.

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

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

Они представляют конечные упорядоченные множества, индексируемые неотрицательными числами. Встроенная функция 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. Типы множеств¶Set types

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

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

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

Множества

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

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

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

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

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

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

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

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

3.2.9. Модули¶Modules

Модули – это основная организационная единица кода 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. Пользовательские классы¶Custom classes

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

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

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

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

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

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

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

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

3.2.12. Объекты ввода-вывода (также известные как файловые объекты)¶I/O objects (also known as file objects)

Файловый объект представляет открытый файл. Существуют различные краткие способы создания файловых объектов: встроенная функция 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. Внутренние типы¶Internal types

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

3.3.1. Базовая настройка¶Basic customization

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. Настройка доступа к атрибутам¶Customizing attribute access

Следующие методы могут быть определены для настройки смысла доступа к атрибутам (чтения, присваивания или удаления 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. Настройка создания классов¶Customizing class creation

Всякий раз, когда класс наследуется от другого класса, у родительского класса вызывается __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()  # Автоматически вызывает: x.__set_name__(A, 'x')

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

class A:
   pass

c = C()
A.x = c                  # Хук не вызывается
c.__set_name__(A, 'x')   # Явный вызов хука

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

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

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

3.3.4. Customizing instance and subclass checks¶

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

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

type.__instancecheck__(self, instance)¶

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

type.__subclasscheck__(self, subclass)¶

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

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

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

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

A class can generally only be parameterized if it defines the special class method __class_getitem__().

classmethod object.__class_getitem__(cls, key)¶

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

При определении на классе __class_getitem__() автоматически является методом класса. Поэтому его не нужно декорировать @classmethod при определении.

from inspect import isclass

def subscribe(obj, x):
    """Возвращает результат выражения 'obj[x]'"""

    class_of_obj = type(obj)

    # Если класс obj определяет __getitem__,
    # вызывается class_of_obj.__getitem__(obj, x)
    if hasattr(class_of_obj, '__getitem__'):
        return class_of_obj.__getitem__(obj, x)

    # Иначе, если obj является классом и определяет __class_getitem__,
    # вызывается obj.__class_getitem__(x)
    elif isclass(obj) and hasattr(obj, '__class_getitem__'):
        return obj.__class_getitem__(x)

    # Иначе, возбуждается исключение
    else:
        raise TypeError(
            f"'{class_of_obj.__name__}' object is not subscriptable"
        )

>>> # list имеет класс "type" в качестве метакласса, как и большинство классов:
>>> type(list)
<class 'type'>
>>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
True
>>> # "list[int]" вызывает "list.__class_getitem__(int)"
>>> list[int]
list[int]
>>> # list.__class_getitem__ возвращает объект GenericAlias:
>>> type(list[int])
<class 'types.GenericAlias'>

>>> from enum import Enum
>>> class Menu(Enum):
...     """Меню завтрака"""
...     SPAM = 'spam'
...     BACON = 'bacon'
...
>>> # Классы Enum имеют собственный метакласс:
>>> type(Menu)
<class 'enum.EnumMeta'>
>>> # EnumMeta определяет __getitem__,
>>> # поэтому __class_getitem__ не вызывается,
>>> # и результат не является объектом GenericAlias:
>>> Menu['SPAM']
<Menu.SPAM: 'spam'>
>>> type(Menu['SPAM'])
<enum 'Menu'>

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

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

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

3.3.7. Эмуляция контейнерных типов¶Emulating container types

Следующие методы могут быть определены для реализации контейнерных объектов. Ни один из них не предоставляется самим классом 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)¶

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

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

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

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

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]

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

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

Изменено в версии 3.14: int() больше не делегирует полномочия методу __trunc__().

3.3.9. Контекстные менеджеры оператора with¶With Statement Context Managers

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

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

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

object.__enter__(self)¶

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

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

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

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

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

3.3.10. Настройка позиционных аргументов в сопоставлении с образцом класса¶Customizing positional arguments in class pattern matching

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

Протокол буфера предоставляет способ для объектов 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. Аннотации¶Annotations

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

object.__annotations__¶

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

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

object.__annotate__(format)¶

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

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

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

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

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

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

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

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

>>> 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__()                 # Явный поиск через экземпляр
Class getattribute invoked
10
>>> type(c).__len__(c)          # Явный поиск через тип
Metaclass getattribute invoked
10
>>> len(c)                      # Неявный поиск
10

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

3.4.1. Ожидаемые объекты¶Awaitable Objects

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

object.__await__(self)¶

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

Примечание

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

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

Объекты корутины являются объектами ожидаемыми. Выполнение корутины можно контролировать с помощью вызова __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. Асинхронные итераторы¶Asynchronous Iterators

Объект асинхронный итератор может вызывать асинхронный код в своем методе __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