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

3.1. Объекты, значения и типы данных¶

Объекты — это абстракция данных в Python. Все данные в программе Python представлены объектами или отношениями между ними. Даже код представлен объектами.

Каждый объект имеет идентификатор, тип и значение. Идентификатор объекта никогда не меняется после его создания; его можно рассматривать как адрес объекта в памяти. Оператор is сравнивает идентификаторы двух объектов, а функция id() возвращает его в виде целого числа.

Для CPython, id(x) — это адрес памяти, где хранится x.

Тип объекта определяет операции, которые поддерживает этот объект (например, «имеет ли он длину?»), а также задаёт возможные значения для объектов этого типа. Функция type() возвращает тип объекта (который сам является объектом). Как и идентификатор, тип объекта также неизменен. [1]

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

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

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

Заметьте, что использование конкретных средств трассировки или отладки может удерживать объекты живыми, которые в обычных условиях были бы собраны. Также имейте в виду, что перехват исключений в инструкциях try…except может удерживать объекты живыми.

Некоторые объекты содержат ссылки на «внешние» ресурсы, такие как открытые файлы или окна. Разумеется, эти ресурсы освобождаются при удалении объекта сборщиком мусора. Но поскольку сборка мусора не гарантируется, такие объекты также предоставляют явный способ освободить внешний ресурс, обычно через метод close(). Настоятельно рекомендуется явно закрывать такие объекты. Инструкции try…finally и with предоставляют удобные способы сделать это.

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

Типы влияют практически на все аспекты поведения объектов. Даже значение идентификатора объекта в некотором смысле зависит от типа: для неизменяемых типов операции, вычисляющие новые значения, могут на самом деле возвращать ссылку на существующий объект с тем же типом и значением, тогда как для изменяемых объектов это не разрешено. Например, после a = 1; b = 1, a и b могут ссылаться на один и тот же объект со значением один или на разные объекты, в зависимости от реализации. Это происходит потому, что int — неизменяемый тип, поэтому ссылка на 1 может быть переиспользована. Такое поведение зависит от используемой реализации и не должно восприниматься как гарантированное, но его стоит учитывать при проверках идентичности объектов. Однако после c = []; d = [], c и d гарантированно ссылаются на два различных, уникальных, заново созданных пустых списка. (Обратите внимание, что e = f = [] присваивает один и тот же объект и e, и f.)

3.2. Иерархия стандартных типов¶

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

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

3.2.1. None¶

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

3.2.2. NotImplemented¶

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

См. Implementing the arithmetic operations для получения подробностей.

Изменено в версии 3.9: Использование NotImplemented в логическом контексте было объявлено устаревшим.

Изменено в версии 3.14: Использование NotImplemented в логическом контексте теперь возбуждает TypeError. Ранее оно оценивалось как True и генерировало DeprecationWarning начиная с Python 3.9.

3.2.3. Ellipsis¶

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

3.2.4. `numbers.Number`¶

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

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

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

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

3.2.4.1. `numbers.Integral`¶

Эти объекты представляют элементы математического множества целых чисел (положительных и отрицательных).

Примечание

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

Существует два типа целых чисел:

Целые числа (int): Они представляют числа неограниченного диапазона, ограниченного лишь объёмом доступной (виртуальной) памяти. Для операций сдвига и наложения маски предполагается двоичное представление, а отрицательные числа представляются в варианте дополнительного до степени 2 кода, создающем иллюзию бесконечной последовательности значащих битов, продолжающейся влево.
Логические значения (bool): Они представляют логические значения Ложь и Истина. Два объекта, представляющие значения False и True, являются единственными логическими объектами. Логический тип является подтипом целых чисел, и логические значения ведут себя как числа 0 и 1 соответственно почти во всех контекстах, за исключением случая преобразования их в строки "False" и "True" соответственно.

3.2.4.2. `numbers.Real` (`float`)¶

Они представляют числа с плавающей точкой двойной точности на машинном уровне. Диапазон допустимых значений и обработка переполнения зависят от архитектуры машины (и реализации на C или Java). Python не поддерживает числа с плавающей точкой одинарной точности — экономия процессорного времени и памяти, ради которой их обычно используют, ничтожна по сравнению с накладными расходами на использование объектов в Python. Поэтому нет смысла усложнять язык двумя видами чисел с плавающей точкой.

3.2.4.3. `numbers.Complex` (`complex`)¶

Они представляют комплексные числа как пару чисел с плавающей точкой двойной точности на машинном уровне. Здесь действуют те же оговорки, что и для чисел с плавающей точкой. Вещественную и мнимую части комплексного числа z можно получить через атрибуты только для чтения z.real и z.imag.

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

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

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

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

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

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

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

3.2.5.1. Неизменяемые последовательности¶

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

Следующие типы являются неизменяемыми последовательностями:

Строки

Строка (str) — это последовательность значений, представляющих символы или, более формально, кодовые точки Юникод. Все кодовые точки в диапазоне от 0 до 0x10FFFF могут быть представлены в строке.

В Python нет отдельного типа символ. Вместо этого каждая кодовая точка в строке представлена объектом строки длиной 1.

Встроенная функция ord() преобразует кодовую точку из строкового представления в целое число из диапазона от 0 до 0x10FFFF; chr() преобразует целое число из диапазона от 0 до 0x10FFFF в соответствующий объект строки длиной 1. Метод str.encode() можно использовать для преобразования str в bytes с использованием указанной кодировки текста, а bytes.decode() позволяет выполнить обратное преобразование.

Кортежи

Элементы tuple могут быть произвольными объектами Python. Кортежи из двух и более элементов создаются списками выражений, разделённых запятыми. Кортеж из одного элемента (так называемый «одноэлементный кортеж») создаётся добавлением запятой после выражения (само по себе выражение не создаёт кортеж, поскольку круглые скобки должны оставаться доступными для группировки выражений). Пустой кортеж создаётся пустой парой круглых скобок.

Байты

Объект bytes является неизменяемым массивом. Его элементы — это 8-битные байты, представленные целыми числами из диапазона 0 <= x < 256. Литералы байтов (например, b'abc') и встроенный конструктор bytes() можно использовать для создания объектов bytes. Кроме того, объекты bytes можно декодировать в строки с помощью метода decode().

3.2.5.2. Изменяемые последовательности¶

Изменяемые последовательности можно изменять после их создания. Выражение с доступом к элементу или взятием среза можно использовать в качестве цели присваивания и инструкции del (удаления).

Примечание

Модули collections и array предоставляют дополнительные примеры типов изменяемых последовательностей.

В настоящее время существует два внутренних типа изменяемых последовательностей:

Списки: Элементы списка могут быть произвольными объектами Python. Списки формируются размещением списка выражений через запятую в квадратные скобки. (Обратите внимание, что для создания списков длиной 0 или 1 не требуется никаких особых правил.)
Массивы байтов: Объекты bytearray представляют собой изменяемые массивы. Они создаются встроенным конструктором bytearray(). Помимо того, что байтовые массивы изменяемы (и, следовательно, не хэшируются), в остальном они предоставляют тот же интерфейс и функциональность, что и неизменяемые объекты bytes.

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

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

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

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

Множества: Они представляют собой изменяемые множества. Множества создаются встроенным конструктором set() и впоследствии могут изменяться с помощью различных методов, таких как add().
Замороженные множества: Они представляют собой неизменяемые множества. Неизменяемые множества создаются встроенным конструктором frozenset(). Поскольку такое множество является неизменяемым и хешируемым, его можно использовать как элемент другого множества или как ключ словаря.

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

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

There is currently a single intrinsic mapping type:

3.2.7.1. Словари¶

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

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

Словари изменяемы; они могут быть созданы с помощью нотации {} (см. раздел Dictionary displays).

Модули расширения dbm.ndbm и dbm.gnu предоставляют дополнительные примеры типов отображения, как и модуль collections.

Изменено в версии 3.7: Словари не сохраняли порядок вставки в версиях Python до 3.6. В CPython 3.6 порядок вставки сохранялся, но в то время это считалось деталью реализации, а не гарантией языка.

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

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

3.2.8.1. Пользовательские функции¶

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

3.2.8.1.1. Специальные атрибуты, доступные только для чтения¶

Атрибут

Значение

function.__builtins__¶

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

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

function.__globals__¶

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

function.__closure__¶

None или tuple ячеек, содержащих привязки имён, указанных в атрибуте co_freevars объекта кода функции.

Объект ячейки имеет атрибут cell_contents. С его помощью можно получить значение ячейки, а также изменить его.

3.2.8.1.2. Специальные атрибуты, доступные для записи¶

Большинство этих атрибутов проверяют тип присваиваемого значения:

Атрибут	Значение
function.__doc__¶	Строка документации функции или `None`, если она недоступна.
function.__name__¶	Имя функции. См. также: `__name__ атрибуты`.
function.__qualname__¶	Квалифицированное имя функции. См. также: `атрибуты __qualname__`. Добавлено в версии 3.3.
function.__module__¶	Имя модуля, в котором была определена функция, или `None`, если оно недоступно.
function.__defaults__¶	`tuple`, содержащий значения по умолчанию для тех параметров, для которых они заданы, или `None`, если ни один параметр не имеет значения по умолчанию.
function.__code__¶	Объект кода, представляющий скомпилированное тело функции.
function.__dict__¶	Пространство имён, поддерживающее произвольные атрибуты функции. См. также: `атрибуты __dict__`.
function.__annotations__¶	`Словарь`, содержащий аннотации параметров. Ключами словаря являются имена параметров, а для аннотации возвращаемого значения — `'return'`, если она задана. См. также: `object.__annotations__`. Изменено в версии 3.14: Теперь аннотации вычисляются лениво. См. PEP 649.
function.__annotate__¶	Функция аннотации для этой функция или `None`, если у функция нет аннотация. См. `object.__annotate__`. Добавлено в версии 3.14.
function.__kwdefaults__¶	`Словарь`, содержащий значения по умолчанию для параметров, доступных только по имени.
function.__type_params__¶	`tuple`, содержащий параметры типов обобщённой функции. Добавлено в версии 3.12.

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

Текущая реализация CPython поддерживает атрибуты функций только у пользовательских функций. В будущем атрибуты функций могут поддерживаться и у встроенных функций.

Дополнительную информацию об определении функции можно получить из её объекта кода (доступного через атрибут __code__).

3.2.8.2. Методы экземпляра¶

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

Специальные атрибуты, доступные только для чтения:

method.__self__¶	Ссылается на объект экземпляра класса, к которому метод привязан.
method.__func__¶	Ссылается на исходный объект функции.
method.__doc__¶	Документация метода (то же, что и `method.__func__.__doc__`). Это `строка`, если исходная функция имела строку документации, иначе — `None`.
method.__name__¶	Имя метода (то же, что и `method.__func__.__name__`)
method.__module__¶	Имя модуля, в котором был определён метод, или `None`, если оно недоступно.

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

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

Когда объект метода экземпляра создаётся при получении объекта пользовательской функции из класса через один из его экземпляров, его атрибут __self__ является этим экземпляром, а сам объект метода называется привязанным. Атрибут __func__ нового метода является исходным объектом функции.

Когда объект метода экземпляра создаётся при получении объекта classmethod из класса или экземпляра, его атрибут __self__ фактически является самим классом, а атрибут __func__ — объектом функции, лежащей в основе метода класса.

При вызове объекта метода экземпляра вызывается лежащая в его основе функция (__func__), причём экземпляр класса (__self__) вставляется в начало списка аргументов. Например, если C — класс, содержащий определение функции f(), а x — экземпляр C, то вызов x.f(1) эквивалентен вызову C.f(x, 1).

Если объект метода экземпляра создан на основе объекта classmethod, то «экземпляр класса», хранящийся в __self__, фактически является самим классом. Поэтому вызов x.f(1) или C.f(1) эквивалентен вызову f(C,1), где f — лежащая в основе функция.

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

3.2.8.3. Генераторные функции¶

A function or method which contains a yield expression (see section Yield expressions) is called a generator function. Such a function, when called, always returns an iterator object which can be used to execute the body of the function: calling the iterator’s iterator.__next__() method will cause the function to execute until it provides a value using the yield expression. When the function executes a return statement or falls off the end, a StopIteration exception is raised and the iterator will have reached the end of the set of values to be returned.

3.2.8.4. Сопрограммные функции¶

Функция или метод, определённые с помощью async def, называются сопрограммными функциями. При вызове такая функция возвращает объект сопрограммы. Она может содержать выражения await, а также инструкции async with и async for. См. также раздел Coroutine Objects.

3.2.8.5. Асинхронные генераторные функции¶

A function or method which is defined using async def and which contains a yield expression is called a asynchronous generator function. Such a function, when called, returns an asynchronous iterator object which can be used in an async for statement to execute the body of the function.

Вызов метода aiterator.__anext__ асинхронного итератора возвращает ожидаемый объект, который при ожидании выполняется до тех пор, пока не предоставит значение с помощью выражения yield. Когда функция выполняет пустую инструкцию return или доходит до конца, возникает исключение StopAsyncIteration, указывающее на исчерпание асинхронного итератора: он больше не выдаёт новых значений.

3.2.8.6. Встроенные функции¶

Объект встроенной функции является обёрткой вокруг C-функции. Примерами встроенных функций являются len() и math.sin() (math — стандартный встроенный модуль). Количество и тип аргументов определяются C-функцией. Специальные атрибуты, доступные только для чтения:

__doc__ — строка документации функции или None, если она недоступна. См. function.__doc__.
__name__ — имя функции. См. function.__name__.
__self__ устанавливается в None (но см. следующий пункт).
__module__ — имя модуля, в котором была определена функция, или None, если оно недоступно. См. function.__module__.

3.2.8.7. Встроенные методы¶

Это фактически другая форма встроенной функции, на этот раз содержащая объект, передаваемый C-функции в качестве неявного дополнительного аргумента. Пример встроенного метода — alist.append(), если alist является объектом списка. В этом случае специальный доступный только для чтения атрибут __self__ устанавливается в объект, обозначенный alist. (Атрибут имеет ту же семантику, что и в случае с другими методами экземпляра.)

3.2.8.8. Классы¶

Классы являются вызываемыми объектами. Обычно эти объекты служат фабриками для создания своих новых экземпляров, но для типов классов, переопределяющих __new__(), возможны варианты. Аргументы вызова передаются в __new__(), а в обычном случае — в __init__() для инициализации нового экземпляра.

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

Экземпляры произвольных классов можно сделать вызываемыми, определив в их классе метод __call__().

3.2.9. Модули¶

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

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

3.2.9.1. Атрибуты объектов модулей, связанные с импортом¶

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

Для динамического создания модуля вместо использования системы импорта рекомендуется применять importlib.util.module_from_spec(), которая установит различные атрибуты, управляемые системой импорта, в соответствующие значения. Также можно непосредственно создавать модули с помощью конструктора types.ModuleType, но этот способ более подвержен ошибкам: при таком подходе после создания объекта модуля большинство атрибутов приходится устанавливать вручную.

Осторожно

За исключением __name__, настоятельно рекомендуется полагаться на __spec__ и его атрибуты, а не на какие-либо другие отдельные атрибуты, перечисленные в этом подразделе. Обратите внимание, что изменение атрибута объекта __spec__ не приводит к изменению соответствующего атрибута самого модуля:

>>> import typing
>>> typing.__name__, typing.__spec__.name
('typing', 'typing')
>>> typing.__spec__.name = 'правописание'
>>> typing.__name__, typing.__spec__.name
('typing', 'правописание')
>>> typing.__name__ = 'избиение_клавиатуры'
>>> typing.__name__, typing.__spec__.name
('избиение_клавиатуры', 'правописание')

module.__name__¶

Имя, используемое для уникальной идентификации модуля в системе импорта. Для непосредственно выполняемого модуля будет установлено значение "__main__".

Этот атрибут должен содержать полное квалифицированное имя модуля. Предполагается, что оно совпадает со значением module.__spec__.name.

module.__spec__¶

Запись о состоянии модуля, связанном с системой импорта.

Устанавливается в спецификацию модуля, которая использовалась при импорте модуля. Дополнительную информацию см. в Module specs.

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

module.__package__¶

Пакет, которому принадлежит модуль.

Если модуль является модулем верхнего уровня (то есть не является частью какого-либо определённого пакета), атрибут должен быть равен '' (пустой строке). В противном случае он должен содержать имя пакета модуля (которое может совпадать с module.__name__, если сам модуль является пакетом). Подробнее см. PEP 366.

Этот атрибут используется вместо __name__ для вычисления явных относительных импортов главных модулей. Для модулей, динамически созданных с помощью конструктора types.ModuleType, по умолчанию устанавливается значение None; вместо этого используйте importlib.util.module_from_spec(), чтобы гарантировать, что атрибут будет иметь тип str.

Настоятельно рекомендуется использовать атрибут module.__spec__.parent вместо module.__package__. Теперь __package__ используется только как запасной вариант, если __spec__.parent не установлен, и этот путь резервного использования объявлен устаревшим.

Изменено в версии 3.4: Этот атрибут теперь имеет значение по умолчанию None для модулей, динамически созданных с помощью конструктора types.ModuleType. Ранее атрибут был необязательным.

Изменено в версии 3.6: Ожидается, что значение __package__ совпадает со значением __spec__.parent. Теперь __package__ используется только как запасной вариант при разрешении импорта, если __spec__.parent не определён.

Изменено в версии 3.10: Возникает ImportWarning, если при разрешении импорта происходит переход к __package__ вместо __spec__.parent.

Изменено в версии 3.12: При переходе к __package__ во время разрешения импорта вместо ImportWarning возникает DeprecationWarning.

Устарело с версии 3.13, будет удалено в версии 3.15: __package__ перестанет устанавливаться и учитываться системой импорта или стандартной библиотекой.

module.__loader__¶

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

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

Для модулей, динамически созданных с помощью конструктора types.ModuleType, __loader__ по умолчанию имеет значение None; вместо этого используйте importlib.util.module_from_spec(), чтобы гарантировать, что атрибут будет установлен в объект загрузчика.

Настоятельно рекомендуется использовать module.__spec__.loader вместо module.__loader__.

Изменено в версии 3.4: Этот атрибут теперь имеет значение по умолчанию None для модулей, динамически созданных с помощью конструктора types.ModuleType. Ранее атрибут был необязательным.

Устарело с версии 3.12, будет удалено в версии 3.16: Установка __loader__ для модуля без установки __spec__.loader считается устаревшей. В Python 3.16 __loader__ перестанет устанавливаться и учитываться системой импорта или стандартной библиотекой.

module.__path__¶

Последовательность строк (возможно, пустая), перечисляющая расположения, в которых будут найдены подмодули пакета. Модули, не являющиеся пакетами, не должны иметь атрибут __path__. Подробнее см. в __path__ attributes on modules.

Настоятельно рекомендуется использовать атрибут module.__spec__.submodule_search_locations вместо module.__path__.

module.__file__¶

module.__cached__¶

__file__ and __cached__ are both optional attributes that may or may not be set. Both attributes should be a str when they are available.

__file__ indicates the pathname of the file from which the module was loaded (if loaded from a file), or the pathname of the shared library file for extension modules loaded dynamically from a shared library. It might be missing for certain types of modules, such as C modules that are statically linked into the interpreter, and the import system may opt to leave it unset if it has no semantic meaning (for example, a module loaded from a database).

If __file__ is set then the __cached__ attribute might also be set, which is the path to any compiled version of the code (for example, a byte-compiled file). The file does not need to exist to set this attribute; the path can simply point to where the compiled file would exist (see PEP 3147).

Note that __cached__ may be set even if __file__ is not set. However, that scenario is quite atypical. Ultimately, the loader is what makes use of the module spec provided by the finder (from which __file__ and __cached__ are derived). So if a loader can load from a cached module but otherwise does not load from a file, that atypical scenario may be appropriate.

It is strongly recommended that you use module.__spec__.cached instead of module.__cached__.

Устарело с версии 3.13, будет удалено в версии 3.15: Setting __cached__ on a module while failing to set __spec__.cached is deprecated. In Python 3.15, __cached__ will cease to be set or taken into consideration by the import system or standard library.

3.2.9.2. Другие доступные для записи атрибуты объектов модулей¶

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

module.__doc__¶: Строка документации модуля или None, если она недоступна. См. также: __doc__ атрибуты.

module.__annotations__¶: Словарь, содержащий аннотации переменных, собранные во время выполнения тела модуля. Рекомендации по работе с __annotations__, см. в annotationlib.

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

module.__annotate__¶: Аннотирующая функция этого модуля или None, если модуль не содержит аннотаций. См. также атрибуты __annotate__.

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

3.2.9.3. Словари модулей¶

Объекты модулей также имеют следующий специальный доступный только для чтения атрибут:

module.__dict__¶: Пространство имён модуля в виде объекта-словаря. В отличие от всех остальных перечисленных здесь атрибутов, __dict__ нельзя получить как глобальную переменную внутри модуля. К нему можно обратиться только как к атрибуту объекта модуля.

Из-за особенностей очистки словарей модулей в CPython словарь модуля будет очищен, когда модуль выйдет из области видимости, даже если на словарь по-прежнему существуют активные ссылки. Чтобы этого избежать, скопируйте словарь или сохраните модуль, пока напрямую используете его словарь.

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

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

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

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

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

3.2.10.1. Специальные атрибуты¶

Атрибут	Значение
type.__name__¶	Имя класса. См. также: `__name__ атрибуты`.
type.__qualname__¶	Квалифицированное имя класса. См. также: `атрибуты __qualname__`.
type.__module__¶	Имя модуля, в котором был определён класс.
type.__dict__¶	`Прокси-отображение`, предоставляющее доступное только для чтения представление пространства имён класса. См. также: `атрибуты __dict__`.
type.__bases__¶	`tuple`, содержащий базовые классы класса. В большинстве случаев для класса, определённого как `class X(A, B, C)`, `X.__bases__` будет в точности равен `(A, B, C)`.
type.__base__¶	Единственный базовый класс в цепочке наследования, отвечающий за расположение экземпляров в памяти. Этот атрибут соответствует `tp_base` на уровне C.
type.__doc__¶	Строка документации класса или `None`, если она не определена. Не наследуется подклассами.
type.__annotations__¶	Словарь, содержащий аннотации переменных, собранные во время выполнения тела класса. См. также: `атрибуты __annotations__`. Рекомендации по работе с `__annotations__` см. в `annotationlib`. Вместо непосредственного обращения к этому атрибуту используйте `annotationlib.get_annotations()`. Предупреждение Непосредственное обращение к атрибуту `__annotations__` объекта класса может вернуть аннотации не того класса — в частности, в определённых случаях, когда класс, его базовый класс или метакласс определены с использованием `from __future__ import annotations`. Подробности см. в 749. Этот атрибут отсутствует у некоторых встроенных классов. У пользовательских классов без `__annotations__` это пустой словарь. Изменено в версии 3.14: Теперь аннотации вычисляются лениво. См. PEP 649.
type.__annotate__()¶	Аннотирующая функция для этого класса или `None`, если у класса нет аннотаций. См. также: `атрибуты __annotate__`. Добавлено в версии 3.14.
type.__type_params__¶	`tuple`, содержащий параметры типов обобщённого класса. Добавлено в версии 3.12.
type.__static_attributes__¶	`tuple`, содержащий имена атрибутов этого класса, которым присваивается значение через `self.X` в любой функции из его тела. Добавлено в версии 3.13.
type.__firstlineno__¶	Номер строки, на которой начинается определение класса, включая декораторы. Присваивание атрибуту `__module__` нового значения удаляет элемент `__firstlineno__` из словаря типа. Добавлено в версии 3.13.
type.__mro__¶	`tuple` классов, просматриваемых при поиске в базовых классах в процессе разрешения методов.

3.2.10.2. Специальные методы¶

В дополнение к специальным атрибутам, описанным выше, все классы Python также имеют следующие два метода:

type.mro()¶: Этот метод может быть переопределен метаклассом, чтобы настроить порядок разрешения методов для его экземпляров. Он вызывается при создании экземпляра класса, а его результат сохраняется в __mro__.

type.__subclasses__()¶

Каждый класс хранит список слабых ссылок на свои непосредственные подклассы. Этот метод возвращает список всех таких живых ссылок. Список приведён в порядке определения. Пример:

>>> class A: pass
>>> class B(A): pass
>>> A.__subclasses__()
[<class 'B'>]

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

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

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

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

3.2.11.1. Специальные атрибуты¶

object.__class__¶: Класс, которому принадлежит экземпляр.

object.__dict__¶: Словарь или другой объект-отображение, используемый для хранения (доступных для записи) атрибутов объекта. Не у всех экземпляров есть атрибут __dict__; подробнее см. раздел __slots__.

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

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

Файловые объекты реализуют общие методы, перечисленные ниже, чтобы упростить их использование в универсальном коде. Ожидается, что они являются With Statement Context Managers.

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

file.read(size=-1, /)¶: Извлекает из файла до size данных. Для удобства, если size не указан или равен -1, извлекаются все доступные данные.

file.write(data, /)¶: Сохраняет data в файл.

file.close()¶: Сбрасывает все буферы и закрывает соответствующий файл.

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

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

3.2.13.1. Объекты кода¶

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

3.2.13.1.1. Специальные атрибуты, доступные только для чтения¶

codeobject.co_name¶	Имя функции
codeobject.co_qualname¶	Полное квалифицированное имя функции Добавлено в версии 3.11.
codeobject.co_argcount¶	Общее количество позиционных параметров функции (включая только позиционные параметры и параметры со значениями по умолчанию)
codeobject.co_posonlyargcount¶	Количество только позиционных параметров функции (включая аргументы со значениями по умолчанию)
codeobject.co_kwonlyargcount¶	Количество параметров функции, доступных только по имени (включая аргументы со значениями по умолчанию)
codeobject.co_nlocals¶	Количество локальных переменных, используемых функцией (включая параметры)
codeobject.co_varnames¶	`tuple`, содержащий имена локальных переменных функции (начиная с имён параметров)
codeobject.co_cellvars¶	`tuple`, содержащий имена локальных переменных, на которые ссылаются из хотя бы одной вложенной области видимости внутри функции
codeobject.co_freevars¶	`tuple`, содержащий имена свободных переменных (замыкания), на которые вложенная область видимости ссылается во внешней области видимости. См. также `function.__closure__`. Примечание: ссылки на глобальные и встроенные имена не включены.
codeobject.co_code¶	Строка, представляющая последовательность инструкций байт-кода в функции
codeobject.co_consts¶	`tuple`, содержащий литералы, используемые байт-кодом функции
codeobject.co_names¶	`tuple`, содержащий имена, используемые байт-кодом функции
codeobject.co_filename¶	Имя файла, из которого был скомпилирован код
codeobject.co_firstlineno¶	Номер первой строки функции
codeobject.co_lnotab¶	A string encoding the mapping from bytecode offsets to line numbers. For details, see the source code of the interpreter. Устарело, начиная с версии 3.12: This attribute of code objects is deprecated, and may be removed in Python 3.15.
codeobject.co_stacksize¶	Требуемый размер стека для объекта кода
codeobject.co_flags¶	`Целое число`, кодирующее набор флагов для интерпретатора

Для co_flags определены следующие биты флагов: бит 0x04 устанавливается, если функция использует синтаксис *arguments для приёма произвольного количества позиционных аргументов; бит 0x08 устанавливается, если функция использует синтаксис **keywords для приёма произвольных именованных аргументов; бит 0x20 устанавливается, если функция является генератором. Подробнее о семантике каждого из возможных флагов см. Code Objects Bit Flags.

Объявления будущих возможностей (например, from __future__ import division) также используют биты co_flags, чтобы указать, была ли включена определённая возможность при компиляции объекта кода. См. compiler_flag.

Другие биты co_flags зарезервированы для внутреннего использования.

Если объект кода представляет функцию и имеет строку документации, в co_flags устанавливается бит CO_HAS_DOCSTRING, а первым элементом co_consts становится строка документации функции.

3.2.13.1.2. Методы объектов кода¶

codeobject.co_positions()¶

Возвращает итерируемый объект с позициями в исходном коде для каждой инструкции байт-кода в объекте кода.

Итератор возвращает кортежи, содержащие (start_line, end_line, start_column, end_column). i-й кортеж соответствует позиции в исходном коде, скомпилированной в i-ю единицу кода. Информация о столбцах — это смещения в байтах UTF-8, отсчитываемые с 0, в пределах соответствующей строки исходного кода.

Эта информация о позиции может отсутствовать. Неполный список случаев, когда это может произойти:

Запуск интерпретатора с параметром -X no_debug_ranges.
Загрузка pyc-файла, скомпилированного с использованием -X no_debug_ranges.
Кортежи позиций, соответствующие искусственным инструкциям.
Номера строк и столбцов, которые невозможно представить из-за ограничений конкретной реализации.

Когда это происходит, некоторые или все элементы кортежа могут быть равны None.

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

Примечание

Для этой функциональности требуется хранить позиции столбцов в объектах кода, что может привести к небольшому увеличению использования дискового пространства скомпилированными файлами Python или памяти, используемой интерпретатором. Чтобы избежать хранения этой дополнительной информации и/или отключить вывод дополнительной информации в трассировке, можно использовать флаг командной строки -X no_debug_ranges или переменную окружения PYTHONNODEBUGRANGES.

codeobject.co_lines()¶

Возвращает итератор, который выдаёт информацию о последовательных диапазонах байт-кода. Каждый выдаваемый элемент — это tuple вида (start, end, lineno):

start (int) представляет смещение (включительно) начала диапазона байт-кода
end (int) представляет смещение (не включая его) конца диапазона байт-кода
lineno — это int, представляющий номер строки диапазона байт-кода, или None, если инструкции байт-кода в данном диапазоне не имеют номера строки

Выдаваемые элементы обладают следующими свойствами:

Первый выдаваемый диапазон будет иметь start, равный 0.
Диапазоны (start, end) будут неубывающими и последовательными. То есть для любой пары кортежей значение start второго будет равно значению end первого.
Ни один диапазон не будет направлен назад: end >= start для всех троек.
Последний выдаваемый tuple будет иметь end, равный размеру байт-кода.

Допускаются диапазоны нулевой ширины, где start == end. Они используются для строк, которые присутствуют в исходном коде, но были удалены компилятором байт-кода.

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

См. также

PEP 626 — Точные номера строк для отладки и других инструментов.: PEP, представивший метод co_lines().

codeobject.replace(**kwargs)¶

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

Объекты кода также поддерживаются обобщённой функцией copy.replace().

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

3.2.13.2. Объекты кадров¶

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

3.2.13.2.1. Специальные атрибуты, доступные только для чтения¶

frame.f_back¶	Указывает на предыдущий кадр стека (в сторону вызывающего кода), или `None`, если это самый нижний кадр стека
frame.f_code¶	Объект кода, выполняемый в этом кадре. Обращение к этому атрибуту возбуждает событие аудита `object.__getattr__` с аргументами `obj` и `"f_code"`.
frame.f_locals¶	Отображение, используемое кадром для поиска локальных переменных. Если кадр относится к оптимизированной области видимости, этот метод может вернуть прокси-объект со сквозной записью. Изменено в версии 3.13: Возвращает прокси-объект для оптимизированных областей видимости.
frame.f_globals¶	Словарь, используемый кадром для поиска глобальных переменных
frame.f_builtins¶	Словарь, используемый кадром для поиска встроенных (внутренних) имён
frame.f_lasti¶	«Точная инструкция» объекта кадра (это индекс в строке байт-кода объекта кода)
frame.f_generator¶	Объект генератора или сопрограммы, которому принадлежит этот кадр, или `None`, если кадр представляет обычную функцию. Добавлено в версии 3.14.

3.2.13.2.2. Специальные атрибуты, доступные для записи¶

frame.f_trace¶	Если не равно `None`, это функция, вызываемая для различных событий во время выполнения кода (используется отладчиками). Обычно событие вызывается для каждой новой строки исходного кода (см. `f_trace_lines`).
frame.f_trace_lines¶	Установите этот атрибут в `False`, чтобы отключить вызов события трассировки для каждой строки исходного кода.
frame.f_trace_opcodes¶	Установите этот атрибут в `True`, чтобы разрешить запрос событий для каждого кода операции. Обратите внимание, что это может привести к неопределённому поведению интерпретатора, если исключения, возбуждённые функцией трассировки, выходят за пределы трассируемой функции.
frame.f_lineno¶	Текущий номер строки кадра — запись в этот атрибут из функции трассировки выполняет переход к указанной строке (только для самого нижнего кадра). Отладчик может реализовать команду перехода (также известную как «Установить следующую инструкцию»), записывая в этот атрибут.

3.2.13.2.3. Методы объекта кадра¶

Объекты кадра поддерживают один метод:

frame.clear()¶

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

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

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

Изменено в версии 3.13: Попытка очистить приостановленный кадр возбуждает RuntimeError (как это всегда было и для выполняющихся кадров).

3.2.13.3. Объекты трассировки¶

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

Изменено в версии 3.7: Объекты трассировки теперь можно явно создавать из кода Python.

Для неявно созданных трассировок, когда поиск обработчика исключения разворачивает стек выполнения, на каждом развёрнутом уровне перед текущей трассировкой вставляется объект трассировки. Когда управление передаётся обработчику исключения, трассировка стека становится доступна программе. (См. раздел The try statement.) Она доступна как третий элемент кортежа, возвращаемого функцией sys.exc_info(), а также как атрибут __traceback__ перехваченного исключения.

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

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

Специальные атрибуты, доступные только для чтения:

traceback.tb_frame¶

Указывает на исполняемый кадр текущего уровня.

Обращение к этому атрибуту возбуждает событие аудита object.__getattr__ с аргументами obj и "tb_frame".

traceback.tb_lineno¶

Указывает номер строки, на которой возникло исключение

traceback.tb_lasti¶

Указывает на «точную инструкцию».

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

traceback.tb_next¶: Специальный доступный для записи атрибут tb_next — это следующий уровень в трассировке стека (в сторону кадра, где возникло исключение), или None, если следующего уровня нет.

Изменено в версии 3.7: Этот атрибут теперь доступен для записи

3.2.13.4. Объекты срезов¶

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

Специальные атрибуты, доступные только для чтения: start — нижняя граница; stop — верхняя граница; step — значение шага; каждый из них имеет значение None, если опущен. Эти атрибуты могут иметь любой тип.

Объекты среза поддерживают один метод:

slice.indices(self, length)¶: Этот метод принимает единственный целочисленный аргумент length и вычисляет информацию о срезе, который описывал бы объект среза, если бы применялся к последовательности из length элементов. Он возвращает кортеж из трёх целых чисел; это, соответственно, индексы start и stop, а также step среза. Отсутствующие или выходящие за границы индексы обрабатываются так же, как и в обычных срезах.

3.2.13.5. Объекты статических методов¶

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

3.2.13.6. Объекты методов класса¶

Объект метода класса, как и объект статического метода, является обёрткой вокруг другого объекта, изменяющей то, как этот объект извлекается из классов и экземпляров классов. Поведение объектов методов класса при таком извлечении описано выше, в разделе «методы экземпляра». Объекты методов класса создаются встроенным конструктором classmethod().

3.3. Имена специальных методов¶

Класс может реализовывать определённые операции, вызываемые особым синтаксисом (такие как арифметические операции или обращение к элементу и срезы), определяя методы со специальными именами. Это подход Python к перегрузке операторов, позволяющий классам определять собственное поведение по отношению к операторам языка. Например, если класс определяет метод с именем __getitem__(), а x — экземпляр этого класса, то x[i] примерно эквивалентно type(x).__getitem__(x, i). За исключением специально оговорённых случаев, попытка выполнить операцию при отсутствии подходящего определённого метода возбуждает исключение (как правило, AttributeError или TypeError).

Установка специального метода в значение None означает, что соответствующая операция недоступна. Например, если класс устанавливает __iter__() в значение None, класс не является итерируемым, поэтому вызов iter() на его экземплярах будет возбуждать исключение TypeError (без отката к методу __getitem__()). [2]

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

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[, ...])¶

Called after the instance has been created (by __new__()), but before it is returned to the caller. The arguments are those passed to the class constructor expression. If a base class has an __init__() method, the derived class’s __init__() method, if any, must explicitly call it to ensure proper initialization of the base class part of the instance; for example: super().__init__([args...]).

Because __new__() and __init__() work together in constructing objects (__new__() to create it, and __init__() to customize it), no non-None value may be returned by __init__(); doing so will cause a TypeError to be raised at runtime.

object.__del__(self)¶

Called when the instance is about to be destroyed. This is also called a finalizer or (improperly) a destructor. If a base class has a __del__() method, the derived class’s __del__() method, if any, must explicitly call it to ensure proper deletion of the base class part of the instance.

It is possible (though not recommended!) for the __del__() method to postpone destruction of the instance by creating a new reference to it. This is called object resurrection. It is implementation-dependent whether __del__() is called a second time when a resurrected object is about to be destroyed; the current CPython implementation only calls it once.

It is not guaranteed that __del__() methods are called for objects that still exist when the interpreter exits. weakref.finalize provides a straightforward way to register a cleanup function to be called when an object is garbage collected.

Примечание

del x doesn’t directly call x.__del__() — the former decrements the reference count for x by one, and the latter is only called when x’s reference count reaches zero.

Деталь реализации CPython: It is possible for a reference cycle to prevent the reference count of an object from going to zero. In this case, the cycle will be later detected and deleted by the cyclic garbage collector. A common cause of reference cycles is when an exception has been caught in a local variable. The frame’s locals then reference the exception, which references its own traceback, which references the locals of all frames caught in the traceback.

См. также

Documentation for the gc module.

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

Due to the precarious circumstances under which __del__() methods are invoked, exceptions that occur during their execution are ignored, and a warning is printed to sys.stderr instead. In particular:

__del__() can be invoked when arbitrary code is being executed, including from any arbitrary thread. If __del__() needs to take a lock or invoke any other blocking resource, it may deadlock as the resource may already be taken by the code that gets interrupted to execute __del__().
__del__() can be executed during interpreter shutdown. As a consequence, the global variables it needs to access (including other modules) may already have been deleted or set to None. Python guarantees that globals whose name begins with a single underscore are deleted from their module before other globals are deleted; if no other references to such globals exist, this may help in assuring that imported modules are still available at the time when the __del__() method is called.

object.__repr__(self)¶

Called by the repr() built-in function to compute the «official» string representation of an object. If at all possible, this should look like a valid Python expression that could be used to recreate an object with the same value (given an appropriate environment). If this is not possible, a string of the form <...some useful description...> should be returned. The return value must be a string object. If a class defines __repr__() but not __str__(), then __repr__() is also used when an «informal» string representation of instances of that class is required.

This is typically used for debugging, so it is important that the representation is information-rich and unambiguous. A default implementation is provided by the object class itself.

object.__str__(self)¶

Called by str(object), the default __format__() implementation, and the built-in function print(), to compute the «informal» or nicely printable string representation of an object. The return value must be a str object.

This method differs from object.__repr__() in that there is no expectation that __str__() return a valid Python expression: a more convenient or concise representation can be used.

The default implementation defined by the built-in type object calls object.__repr__().

object.__bytes__(self)¶: Called by bytes to compute a byte-string representation of an object. This should return a bytes object. The object class itself does not provide this method.

object.__format__(self, format_spec)¶

Called by the format() built-in function, and by extension, evaluation of formatted string literals and the str.format() method, to produce a «formatted» string representation of an object. The format_spec argument is a string that contains a description of the formatting options desired. The interpretation of the format_spec argument is up to the type implementing __format__(), however most classes will either delegate formatting to one of the built-in types, or use a similar formatting option syntax.

See Format specification mini-language for a description of the standard formatting syntax.

The return value must be a string object.

The default implementation by the object class should be given an empty format_spec string. It delegates to __str__().

Изменено в версии 3.4: The __format__ method of object itself raises a TypeError if passed any non-empty string.

Изменено в версии 3.7: object.__format__(x, '') is now equivalent to str(x) rather than 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)¶

These are the so-called «rich comparison» methods. The correspondence between operator symbols and method names is as follows: x<y calls x.__lt__(y), x<=y calls x.__le__(y), x==y calls x.__eq__(y), x!=y calls x.__ne__(y), x>y calls x.__gt__(y), and x>=y calls x.__ge__(y).

A rich comparison method may return the singleton NotImplemented if it does not implement the operation for a given pair of arguments. By convention, False and True are returned for a successful comparison. However, these methods can return any value, so if the comparison operator is used in a Boolean context (e.g., in the condition of an if statement), Python will call bool() on the value to determine if the result is true or false.

By default, object implements __eq__() by using is, returning NotImplemented in the case of a false comparison: True if x is y else NotImplemented. For __ne__(), by default it delegates to __eq__() and inverts the result unless it is NotImplemented. There are no other implied relationships among the comparison operators or default implementations; for example, the truth of (x<y or x==y) does not imply x<=y. To automatically generate ordering operations from a single root operation, see @functools.total_ordering.

By default, the object class provides implementations consistent with Value comparisons: equality compares according to object identity, and order comparisons raise TypeError. Each default method may generate these results directly, but may also return NotImplemented.

See the paragraph on __hash__() for some important notes on creating hashable objects which support custom comparison operations and are usable as dictionary keys.

There are no swapped-argument versions of these methods (to be used when the left argument does not support the operation but the right argument does); rather, __lt__() and __gt__() are each other’s reflection, __le__() and __ge__() are each other’s reflection, and __eq__() and __ne__() are their own reflection. If the operands are of different types, and the right operand’s type is a direct or indirect subclass of the left operand’s type, the reflected method of the right operand has priority, otherwise the left operand’s method has priority. Virtual subclassing is not considered.

When no appropriate method returns any value other than NotImplemented, the == and != operators will fall back to is and is not, respectively.

object.__hash__(self)¶

Called by built-in function hash() and for operations on members of hashed collections including set, frozenset, and dict. The __hash__() method should return an integer. The only required property is that objects which compare equal have the same hash value; it is advised to mix together the hash values of the components of the object that also play a part in comparison of objects by packing them into a tuple and hashing the tuple. Example:

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

Примечание

hash() truncates the value returned from an object’s custom __hash__() method to the size of a Py_ssize_t. This is typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds. If an object’s __hash__() must interoperate on builds of different bit sizes, be sure to check the width on all supported builds. An easy way to do this is with python -c "import sys; print(sys.hash_info.width)".

If a class does not define an __eq__() method it should not define a __hash__() operation either; if it defines __eq__() but not __hash__(), its instances will not be usable as items in hashable collections. If a class defines mutable objects and implements an __eq__() method, it should not implement __hash__(), since the implementation of hashable collections requires that a key’s hash value is immutable (if the object’s hash value changes, it will be in the wrong hash bucket).

User-defined classes have __eq__() and __hash__() methods by default (inherited from the object class); with them, all objects compare unequal (except with themselves) and x.__hash__() returns an appropriate value such that x == y implies both that x is y and hash(x) == hash(y).

A class that overrides __eq__() and does not define __hash__() will have its __hash__() implicitly set to None. When the __hash__() method of a class is None, instances of the class will raise an appropriate TypeError when a program attempts to retrieve their hash value, and will also be correctly identified as unhashable when checking isinstance(obj, collections.abc.Hashable).

If a class that overrides __eq__() needs to retain the implementation of __hash__() from a parent class, the interpreter must be told this explicitly by setting __hash__ = <ParentClass>.__hash__.

If a class that does not override __eq__() wishes to suppress hash support, it should include __hash__ = None in the class definition. A class which defines its own __hash__() that explicitly raises a TypeError would be incorrectly identified as hashable by an isinstance(obj, collections.abc.Hashable) call.

Примечание

By default, the __hash__() values of str and bytes objects are «salted» with an unpredictable random value. Although they remain constant within an individual Python process, they are not predictable between repeated invocations of Python.

This is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict insertion, O(n²) complexity. See https://ocert.org/advisories/ocert-2011-003.html for details.

Changing hash values affects the iteration order of sets. Python has never made guarantees about this ordering (and it typically varies between 32-bit and 64-bit builds).

3.3.2. Customizing attribute access¶

The following methods can be defined to customize the meaning of attribute access (use of, assignment to, or deletion of x.name) for class instances.

object.__getattr__(self, name)¶

Called when the default attribute access fails with an AttributeError (either __getattribute__() raises an AttributeError because name is not an instance attribute or an attribute in the class tree for self; or __get__() of a name property raises AttributeError). This method should either return the (computed) attribute value or raise an AttributeError exception. The object class itself does not provide this method.

Note that if the attribute is found through the normal mechanism, __getattr__() is not called. (This is an intentional asymmetry between __getattr__() and __setattr__().) This is done both for efficiency reasons and because otherwise __getattr__() would have no way to access other attributes of the instance. Note that at least for instance variables, you can take total control by not inserting any values in the instance attribute dictionary (but instead inserting them in another object). See the __getattribute__() method below for a way to actually get total control over attribute access.

object.__getattribute__(self, name)¶

Called unconditionally to implement attribute accesses for instances of the class. If the class also defines __getattr__(), the latter will not be called unless __getattribute__() either calls it explicitly or raises an AttributeError. This method should return the (computed) attribute value or raise an AttributeError exception. In order to avoid infinite recursion in this method, its implementation should always call the base class method with the same name to access any attributes it needs, for example, object.__getattribute__(self, name).

Примечание

This method may still be bypassed when looking up special methods as the result of implicit invocation via language syntax or built-in functions. See Special method lookup.

For certain sensitive attribute accesses, raises an auditing event object.__getattr__ with arguments obj and name.

object.__setattr__(self, name, value)¶

Called when an attribute assignment is attempted. This is called instead of the normal mechanism (i.e. store the value in the instance dictionary). name is the attribute name, value is the value to be assigned to it.

If __setattr__() wants to assign to an instance attribute, it should call the base class method with the same name, for example, object.__setattr__(self, name, value).

For certain sensitive attribute assignments, raises an auditing event object.__setattr__ with arguments obj, name, value.

object.__delattr__(self, name)¶

Like __setattr__() but for attribute deletion instead of assignment. This should only be implemented if del obj.name is meaningful for the object.

For certain sensitive attribute deletions, raises an auditing event object.__delattr__ with arguments obj and name.

object.__dir__(self)¶: Called when dir() is called on the object. An iterable must be returned. dir() converts the returned iterable to a list and sorts it.

3.3.2.1. Customizing module attribute access¶

module.__getattr__()¶
module.__dir__()¶

Special names __getattr__ and __dir__ can be also used to customize access to module attributes. The __getattr__ function at the module level should accept one argument which is the name of an attribute and return the computed value or raise an AttributeError. If an attribute is not found on a module object through the normal lookup, i.e. object.__getattribute__(), then __getattr__ is searched in the module __dict__ before raising an AttributeError. If found, it is called with the attribute name and the result is returned.

The __dir__ function should accept no arguments, and return an iterable of strings that represents the names accessible on module. If present, this function overrides the standard dir() search on a module.

module.__class__¶

For a more fine grained customization of the module behavior (setting attributes, properties, etc.), one can set the __class__ attribute of a module object to a subclass of types.ModuleType. For example:

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

Примечание

Defining module __getattr__ and setting module __class__ only affect lookups made using the attribute access syntax – directly accessing the module globals (whether by code within the module, or via a reference to the module’s globals dictionary) is unaffected.

Изменено в версии 3.5: __class__ module attribute is now writable.

Добавлено в версии 3.7: __getattr__ and __dir__ module attributes.

См. также

PEP 562 - Module __getattr__ and __dir__: Describes the __getattr__ and __dir__ functions on modules.

3.3.2.2. Implementing Descriptors¶

The following methods only apply when an instance of the class containing the method (a so-called descriptor class) appears in an owner class (the descriptor must be in either the owner’s class dictionary or in the class dictionary for one of its parents). In the examples below, «the attribute» refers to the attribute whose name is the key of the property in the owner class“ __dict__. The object class itself does not implement any of these protocols.

object.__get__(self, instance, owner=None)¶

Called to get the attribute of the owner class (class attribute access) or of an instance of that class (instance attribute access). The optional owner argument is the owner class, while instance is the instance that the attribute was accessed through, or None when the attribute is accessed through the owner.

This method should return the computed attribute value or raise an AttributeError exception.

PEP 252 specifies that __get__() is callable with one or two arguments. Python’s own built-in descriptors support this specification; however, it is likely that some third-party tools have descriptors that require both arguments. Python’s own __getattribute__() implementation always passes in both arguments whether they are required or not.

object.__set__(self, instance, value)¶

Called to set the attribute on an instance instance of the owner class to a new value, value.

Note, adding __set__() or __delete__() changes the kind of descriptor to a «data descriptor». See Invoking Descriptors for more details.

object.__delete__(self, instance)¶: Called to delete the attribute on an instance instance of the owner class.

Instances of descriptors may also have the __objclass__ attribute present:

object.__objclass__¶: The attribute __objclass__ is interpreted by the inspect module as specifying the class where this object was defined (setting this appropriately can assist in runtime introspection of dynamic class attributes). For callables, it may indicate that an instance of the given type (or a subclass) is expected or required as the first positional argument (for example, CPython sets this attribute for unbound methods that are implemented in C).

3.3.2.3. Invoking Descriptors¶

In general, a descriptor is an object attribute with «binding behavior», one whose attribute access has been overridden by methods in the descriptor protocol: __get__(), __set__(), and __delete__(). If any of those methods are defined for an object, it is said to be a descriptor.

The default behavior for attribute access is to get, set, or delete the attribute from an object’s dictionary. For instance, a.x has a lookup chain starting with a.__dict__['x'], then type(a).__dict__['x'], and continuing through the base classes of type(a) excluding metaclasses.

However, if the looked-up value is an object defining one of the descriptor methods, then Python may override the default behavior and invoke the descriptor method instead. Where this occurs in the precedence chain depends on which descriptor methods were defined and how they were called.

The starting point for descriptor invocation is a binding, a.x. How the arguments are assembled depends on a:

Direct Call: The simplest and least common call is when user code directly invokes a descriptor method: x.__get__(a).
Instance Binding: If binding to an object instance, a.x is transformed into the call: type(a).__dict__['x'].__get__(a, type(a)).
Class Binding: If binding to a class, A.x is transformed into the call: A.__dict__['x'].__get__(None, A).
Super Binding: A dotted lookup such as super(A, a).x searches a.__class__.__mro__ for a base class B following A and then returns B.__dict__['x'].__get__(a, A). If not a descriptor, x is returned unchanged.

For instance bindings, the precedence of descriptor invocation depends on which descriptor methods are defined. A descriptor can define any combination of __get__(), __set__() and __delete__(). If it does not define __get__(), then accessing the attribute will return the descriptor object itself unless there is a value in the object’s instance dictionary. If the descriptor defines __set__() and/or __delete__(), it is a data descriptor; if it defines neither, it is a non-data descriptor. Normally, data descriptors define both __get__() and __set__(), while non-data descriptors have just the __get__() method. Data descriptors with __get__() and __set__() (and/or __delete__()) defined always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by instances.

Python methods (including those decorated with @staticmethod and @classmethod) are implemented as non-data descriptors. Accordingly, instances can redefine and override methods. This allows individual instances to acquire behaviors that differ from other instances of the same class.

The @property decorator is implemented as a data descriptor. Accordingly, instances cannot override the behavior of a property.

3.3.2.4. slots¶

__slots__ allow us to explicitly declare data members (like properties) and deny the creation of __dict__ and __weakref__ (unless explicitly declared in __slots__ or available in a parent.)

The space saved over using __dict__ can be significant. Attribute lookup speed can be significantly improved as well.

object.__slots__¶: This class variable can be assigned a string, iterable, or sequence of strings with variable names used by instances. __slots__ reserves space for the declared variables and prevents the automatic creation of __dict__ and __weakref__ for each instance.

Notes on using __slots__:

When inheriting from a class without __slots__, the __dict__ and __weakref__ attribute of the instances will always be accessible.
Without a __dict__ variable, instances cannot be assigned new variables not listed in the __slots__ definition. Attempts to assign to an unlisted variable name raises AttributeError. If dynamic assignment of new variables is desired, then add '__dict__' to the sequence of strings in the __slots__ declaration.
Without a __weakref__ variable for each instance, classes defining __slots__ do not support weak references to its instances. If weak reference support is needed, then add '__weakref__' to the sequence of strings in the __slots__ declaration.
__slots__ are implemented at the class level by creating descriptors for each variable name. As a result, class attributes cannot be used to set default values for instance variables defined by __slots__; otherwise, the class attribute would overwrite the descriptor assignment.
The action of a __slots__ declaration is not limited to the class where it is defined. __slots__ declared in parents are available in child classes. However, instances of a child subclass will get a __dict__ and __weakref__ unless the subclass also defines __slots__ (which should only contain names of any additional slots).
If a class defines a slot also defined in a base class, the instance variable defined by the base class slot is inaccessible (except by retrieving its descriptor directly from the base class). This renders the meaning of the program undefined. In the future, a check may be added to prevent this.
TypeError will be raised if nonempty __slots__ are defined for a class derived from a "variable-length" built-in type such as int, bytes, and tuple.
Any non-string iterable may be assigned to __slots__.
If a dictionary is used to assign __slots__, the dictionary keys will be used as the slot names. The values of the dictionary can be used to provide per-attribute docstrings that will be recognised by inspect.getdoc() and displayed in the output of help().
__class__ assignment works only if both classes have the same __slots__.
Multiple inheritance with multiple slotted parent classes can be used, but only one parent is allowed to have attributes created by slots (the other bases must have empty slot layouts) - violations raise TypeError.
If an iterator is used for __slots__ then a descriptor is created for each of the iterator’s values. However, the __slots__ attribute will be an empty iterator.

3.3.3. Customizing class creation¶

Whenever a class inherits from another class, __init_subclass__() is called on the parent class. This way, it is possible to write classes which change the behavior of subclasses. This is closely related to class decorators, but where class decorators only affect the specific class they’re applied to, __init_subclass__ solely applies to future subclasses of the class defining the method.

classmethod object.__init_subclass__(cls)¶

This method is called whenever the containing class is subclassed. cls is then the new subclass. If defined as a normal instance method, this method is implicitly converted to a class method.

Keyword arguments which are given to a new class are passed to the parent class’s __init_subclass__. For compatibility with other classes using __init_subclass__, one should take out the needed keyword arguments and pass the others over to the base class, as in:

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

The default implementation object.__init_subclass__ does nothing, but raises an error if it is called with any arguments.

Примечание

The metaclass hint metaclass is consumed by the rest of the type machinery, and is never passed to __init_subclass__ implementations. The actual metaclass (rather than the explicit hint) can be accessed as type(cls).

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

When a class is created, type.__new__() scans the class variables and makes callbacks to those with a __set_name__() hook.

object.__set_name__(self, owner, name)¶

Automatically called at the time the owning class owner is created. The object has been assigned to name in that class:

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

If the class variable is assigned after the class is created, __set_name__() will not be called automatically. If needed, __set_name__() can be called directly:

class A:
   pass

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

See Creating the class object for more details.

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

3.3.3.1. Metaclasses¶

By default, classes are constructed using type(). The class body is executed in a new namespace and the class name is bound locally to the result of type(name, bases, namespace).

The class creation process can be customized by passing the metaclass keyword argument in the class definition line, or by inheriting from an existing class that included such an argument. In the following example, both MyClass and MySubclass are instances of Meta:

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

Any other keyword arguments that are specified in the class definition are passed through to all metaclass operations described below.

When a class definition is executed, the following steps occur:

MRO entries are resolved;
the appropriate metaclass is determined;
the class namespace is prepared;
the class body is executed;
the class object is created.

3.3.3.2. Resolving MRO entries¶

object.__mro_entries__(self, bases)¶: If a base that appears in a class definition is not an instance of type, then an __mro_entries__() method is searched on the base. If an __mro_entries__() method is found, the base is substituted with the result of a call to __mro_entries__() when creating the class. The method is called with the original bases tuple passed to the bases parameter, and must return a tuple of classes that will be used instead of the base. The returned tuple may be empty: in these cases, the original base is ignored.

См. также

types.resolve_bases(): Dynamically resolve bases that are not instances of type.
types.get_original_bases(): Retrieve a class’s «original bases» prior to modifications by __mro_entries__().
PEP 560: Core support for typing module and generic types.

3.3.3.3. Determining the appropriate metaclass¶

The appropriate metaclass for a class definition is determined as follows:

if no bases and no explicit metaclass are given, then type() is used;
if an explicit metaclass is given and it is not an instance of type(), then it is used directly as the metaclass;
if an instance of type() is given as the explicit metaclass, or bases are defined, then the most derived metaclass is used.

The most derived metaclass is selected from the explicitly specified metaclass (if any) and the metaclasses (i.e. type(cls)) of all specified base classes. The most derived metaclass is one which is a subtype of all of these candidate metaclasses. If none of the candidate metaclasses meets that criterion, then the class definition will fail with TypeError.

3.3.3.4. Preparing the class namespace¶

Once the appropriate metaclass has been identified, then the class namespace is prepared. If the metaclass has a __prepare__ attribute, it is called as namespace = metaclass.__prepare__(name, bases, **kwds) (where the additional keyword arguments, if any, come from the class definition). The __prepare__ method should be implemented as a classmethod. The namespace returned by __prepare__ is passed in to __new__, but when the final class object is created the namespace is copied into a new dict.

If the metaclass has no __prepare__ attribute, then the class namespace is initialised as an empty ordered mapping.

См. также

PEP 3115 - Metaclasses in Python 3000: Introduced the __prepare__ namespace hook

3.3.3.5. Executing the class body¶

The class body is executed (approximately) as exec(body, globals(), namespace). The key difference from a normal call to exec() is that lexical scoping allows the class body (including any methods) to reference names from the current and outer scopes when the class definition occurs inside a function.

However, even when the class definition occurs inside the function, methods defined inside the class still cannot see names defined at the class scope. Class variables must be accessed through the first parameter of instance or class methods, or through the implicit lexically scoped __class__ reference described in the next section.

3.3.3.6. Creating the class object¶

Once the class namespace has been populated by executing the class body, the class object is created by calling metaclass(name, bases, namespace, **kwds) (the additional keywords passed here are the same as those passed to __prepare__).

This class object is the one that will be referenced by the zero-argument form of super(). __class__ is an implicit closure reference created by the compiler if any methods in a class body refer to either __class__ or super. This allows the zero argument form of super() to correctly identify the class being defined based on lexical scoping, while the class or instance that was used to make the current call is identified based on the first argument passed to the method.

Деталь реализации CPython: In CPython 3.6 and later, the __class__ cell is passed to the metaclass as a __classcell__ entry in the class namespace. If present, this must be propagated up to the type.__new__ call in order for the class to be initialised correctly. Failing to do so will result in a RuntimeError in Python 3.8.

When using the default metaclass type, or any metaclass that ultimately calls type.__new__, the following additional customization steps are invoked after creating the class object:

The type.__new__ method collects all of the attributes in the class namespace that define a __set_name__() method;
Those __set_name__ methods are called with the class being defined and the assigned name of that particular attribute;
The __init_subclass__() hook is called on the immediate parent of the new class in its method resolution order.

After the class object is created, it is passed to the class decorators included in the class definition (if any) and the resulting object is bound in the local namespace as the defined class.

When a new class is created by type.__new__, the object provided as the namespace parameter is copied to a new ordered mapping and the original object is discarded. The new copy is wrapped in a read-only proxy, which becomes the __dict__ attribute of the class object.

См. также

PEP 3135 - New super: Describes the implicit __class__ closure reference

3.3.3.7. Uses for metaclasses¶

The potential uses for metaclasses are boundless. Some ideas that have been explored include enum, logging, interface checking, automatic delegation, automatic property creation, proxies, frameworks, and automatic resource locking/synchronization.

3.3.4. Customizing instance and subclass checks¶

The following methods are used to override the default behavior of the isinstance() and issubclass() built-in functions.

In particular, the metaclass abc.ABCMeta implements these methods in order to allow the addition of Abstract Base Classes (ABCs) as «virtual base classes» to any class or type (including built-in types), including other ABCs.

type.__instancecheck__(self, instance)¶: Return true if instance should be considered a (direct or indirect) instance of class. If defined, called to implement isinstance(instance, class).

type.__subclasscheck__(self, subclass)¶: Return true if subclass should be considered a (direct or indirect) subclass of class. If defined, called to implement issubclass(subclass, class).

Note that these methods are looked up on the type (metaclass) of a class. They cannot be defined as class methods in the actual class. This is consistent with the lookup of special methods that are called on instances, only in this case the instance is itself a class.

См. также

PEP 3119 - Introducing Abstract Base Classes: Includes the specification for customizing isinstance() and issubclass() behavior through __instancecheck__() and __subclasscheck__(), with motivation for this functionality in the context of adding Abstract Base Classes (see the abc module) to the language.

3.3.5. Emulating generic types¶

When using type annotations, it is often useful to parameterize a generic type using Python’s square-brackets notation. For example, the annotation list[int] might be used to signify a list in which all the elements are of type int.

См. также

PEP 484 - Type Hints: Introducing Python’s framework for type annotations
Generic Alias Types: Documentation for objects representing parameterized generic classes
Generics, user-defined generics and typing.Generic: Documentation on how to implement generic classes that can be parameterized at runtime and understood by static type-checkers.

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

classmethod object.__class_getitem__(cls, key)¶

Return an object representing the specialization of a generic class by type arguments found in key.

When defined on a class, __class_getitem__() is automatically a class method. As such, there is no need for it to be decorated with @classmethod when it is defined.

3.3.5.1. The purpose of __class_getitem__¶

The purpose of __class_getitem__() is to allow runtime parameterization of standard-library generic classes in order to more easily apply type hints to these classes.

To implement custom generic classes that can be parameterized at runtime and understood by static type-checkers, users should either inherit from a standard library class that already implements __class_getitem__(), or inherit from typing.Generic, which has its own implementation of __class_getitem__().

Custom implementations of __class_getitem__() on classes defined outside of the standard library may not be understood by third-party type-checkers such as mypy. Using __class_getitem__() on any class for purposes other than type hinting is discouraged.

3.3.5.2. __class_getitem versus getitem__¶

Usually, the subscription of an object using square brackets will call the __getitem__() instance method defined on the object’s class. However, if the object being subscribed is itself a class, the class method __class_getitem__() may be called instead. __class_getitem__() should return a GenericAlias object if it is properly defined.

Presented with the expression obj[x], the Python interpreter follows something like the following process to decide whether __getitem__() or __class_getitem__() should be called:

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

In Python, all classes are themselves instances of other classes. The class of a class is known as that class’s metaclass, and most classes have the type class as their metaclass. type does not define __getitem__(), meaning that expressions such as list[int], dict[str, float] and tuple[str, bytes] all result in __class_getitem__() being called:

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

However, if a class has a custom metaclass that defines __getitem__(), subscribing the class may result in different behaviour. An example of this can be found in the enum module:

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

См. также

PEP 560 - Core Support for typing module and generic types: Introducing __class_getitem__(), and outlining when a subscription results in __class_getitem__() being called instead of __getitem__()

3.3.6. Emulating callable objects¶

object.__call__(self[, args...])¶: Called when the instance is «called» as a function; if this method is defined, x(arg1, arg2, ...) roughly translates to type(x).__call__(x, arg1, ...). The object class itself does not provide this method.

3.3.7. Emulating container types¶

The following methods can be defined to implement container objects. None of them are provided by the object class itself. Containers usually are sequences (such as lists or tuples) or mappings (like dictionaries), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers k for which 0 <= k < N where N is the length of the sequence, or slice objects, which define a range of items. It is also recommended that mappings provide the methods keys(), values(), items(), get(), clear(), setdefault(), pop(), popitem(), copy(), and update() behaving similar to those for Python’s standard dictionary objects. The collections.abc module provides a MutableMapping abstract base class to help create those methods from a base set of __getitem__(), __setitem__(), __delitem__(), and keys().

Mutable sequences should provide methods append(), clear(), count(), extend(), index(), insert(), pop(), remove(), and reverse(), like Python standard list objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() and __imul__() described below; they should not define other numerical operators.

It is recommended that both mappings and sequences implement the __contains__() method to allow efficient use of the in operator; for mappings, in should search the mapping’s keys; for sequences, it should search through the values. It is further recommended that both mappings and sequences implement the __iter__() method to allow efficient iteration through the container; for mappings, __iter__() should iterate through the object’s keys; for sequences, it should iterate through the values.

object.__len__(self)¶: Called to implement the built-in function len(). Should return the length of the object, an integer >= 0. Also, an object that doesn’t define a __bool__() method and whose __len__() method returns zero is considered to be false in a Boolean context.

Деталь реализации CPython: In CPython, the length is required to be at most sys.maxsize. If the length is larger than sys.maxsize some features (such as len()) may raise OverflowError. To prevent raising OverflowError by truth value testing, an object must define a __bool__() method.

object.__length_hint__(self)¶: Called to implement operator.length_hint(). Should return an estimated length for the object (which may be greater or less than the actual length). The length must be an integer >= 0. The return value may also be NotImplemented, which is treated the same as if the __length_hint__ method didn’t exist at all. This method is purely an optimization and is never required for correctness.

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

object.__getitem__(self, subscript)¶

Called to implement subscription, that is, self[subscript]. See Subscriptions and slicings for details on the syntax.

There are two types of built-in objects that support subscription via __getitem__():

sequences, where subscript (also called index) should be an integer or a slice object. See the sequence documentation for the expected behavior, including handling slice objects and negative indices.
mappings, where subscript is also called the key. See mapping documentation for the expected behavior.

If subscript is of an inappropriate type, __getitem__() should raise TypeError. If subscript has an inappropriate value, __getitem__() should raise an LookupError or one of its subclasses (IndexError for sequences; KeyError for mappings).

Примечание

Slicing is handled by __getitem__(), __setitem__(), and __delitem__(). A call like

a[1:2] = b

is translated to

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

and so forth. Missing slice items are always filled in with None.

Примечание

The sequence iteration protocol (used, for example, in for loops), expects that an IndexError will be raised for illegal indexes to allow proper detection of the end of a sequence.

Примечание

When subscripting a class, the special class method __class_getitem__() may be called instead of __getitem__(). See __class_getitem__ versus __getitem__ for more details.

object.__setitem__(self, key, value)¶: Called to implement assignment to self[key]. Same note as for __getitem__(). This should only be implemented for mappings if the objects support changes to the values for keys, or if new keys can be added, or for sequences if elements can be replaced. The same exceptions should be raised for improper key values as for the __getitem__() method.

object.__delitem__(self, key)¶: Called to implement deletion of self[key]. Same note as for __getitem__(). This should only be implemented for mappings if the objects support removal of keys, or for sequences if elements can be removed from the sequence. The same exceptions should be raised for improper key values as for the __getitem__() method.

object.__missing__(self, key)¶: Called by dict.__getitem__() to implement self[key] for dict subclasses when key is not in the dictionary.

object.__iter__(self)¶: This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the container. For mappings, it should iterate over the keys of the container.

object.__reversed__(self)¶

Called (if present) by the reversed() built-in to implement reverse iteration. It should return a new iterator object that iterates over all the objects in the container in reverse order.

If the __reversed__() method is not provided, the reversed() built-in will fall back to using the sequence protocol (__len__() and __getitem__()). Objects that support the sequence protocol should only provide __reversed__() if they can provide an implementation that is more efficient than the one provided by reversed().

The membership test operators (in and not in) are normally implemented as an iteration through a container. However, container objects can supply the following special method with a more efficient implementation, which also does not require the object be iterable.

object.__contains__(self, item)¶

Called to implement membership test operators. Should return true if item is in self, false otherwise. For mapping objects, this should consider the keys of the mapping rather than the values or the key-item pairs.

For objects that don’t define __contains__(), the membership test first tries iteration via __iter__(), then the old sequence iteration protocol via __getitem__(), see this section in the language reference.

3.3.8. Emulating numeric types¶

The following methods can be defined to emulate numeric objects. Methods corresponding to operations that are not supported by the particular kind of number implemented (e.g., bitwise operations for non-integral numbers) should be left undefined.

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

These methods are called to implement the binary arithmetic operations (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |). For instance, to evaluate the expression x + y, where x is an instance of a class that has an __add__() method, type(x).__add__(x, y) is called. The __divmod__() method should be the equivalent to using __floordiv__() and __mod__(); it should not be related to __truediv__(). Note that __pow__() should be defined to accept an optional third argument if the three-argument version of the built-in pow() function is to be supported.

If one of those methods does not support the operation with the supplied arguments, it should return 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)¶

These methods are called to implement the binary arithmetic operations (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |) with reflected (swapped) operands. These functions are only called if the operands are of different types, when the left operand does not support the corresponding operation [3], or the right operand’s class is derived from the left operand’s class. [4] For instance, to evaluate the expression x - y, where y is an instance of a class that has an __rsub__() method, type(y).__rsub__(y, x) is called if type(x).__sub__(x, y) returns NotImplemented or type(y) is a subclass of type(x). [5]

Note that __rpow__() should be defined to accept an optional third argument if the three-argument version of the built-in pow() function is to be supported.

Изменено в версии 3.14: Three-argument pow() now try calling __rpow__() if necessary. Previously it was only called in two-argument pow() and the binary power operator.

Примечание

If the right operand’s type is a subclass of the left operand’s type and that subclass provides a different implementation of the reflected method for the operation, this method will be called before the left operand’s non-reflected method. This behavior allows subclasses to override their ancestors“ operations.

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)¶: These methods are called to implement the augmented arithmetic assignments (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=). These methods should attempt to do the operation in-place (modifying self) and return the result (which could be, but does not have to be, self). If a specific method is not defined, or if that method returns NotImplemented, the augmented assignment falls back to the normal methods. For instance, if x is an instance of a class with an __iadd__() method, x += y is equivalent to x = x.__iadd__(y) . If __iadd__() does not exist, or if x.__iadd__(y) returns NotImplemented, x.__add__(y) and y.__radd__(x) are considered, as with the evaluation of x + y. In certain situations, augmented assignment can result in unexpected errors (see Why does a_tuple[i] += [„item“] raise an exception when the addition works?), but this behavior is in fact part of the data model.

object.__neg__(self)¶
object.__pos__(self)¶
object.__abs__(self)¶
object.__invert__(self)¶: Called to implement the unary arithmetic operations (-, +, abs() and ~).

object.__complex__(self)¶
object.__int__(self)¶
object.__float__(self)¶: Called to implement the built-in functions complex(), int() and float(). Should return a value of the appropriate type.

object.__index__(self)¶

Called to implement operator.index(), and whenever Python needs to losslessly convert the numeric object to an integer object (such as in slicing, or in the built-in bin(), hex() and oct() functions). Presence of this method indicates that the numeric object is an integer type. Must return an integer.

If __int__(), __float__() and __complex__() are not defined then corresponding built-in functions int(), float() and complex() fall back to __index__().

object.__round__(self[, ndigits])¶
object.__trunc__(self)¶
object.__floor__(self)¶
object.__ceil__(self)¶: Called to implement the built-in function round() and math functions trunc(), floor() and ceil(). Unless ndigits is passed to __round__() all these methods should return the value of the object truncated to an Integral (typically an int).

Изменено в версии 3.14: int() no longer delegates to the __trunc__() method.

3.3.9. With Statement Context Managers¶

A context manager is an object that defines the runtime context to be established when executing a with statement. The context manager handles the entry into, and the exit from, the desired runtime context for the execution of the block of code. Context managers are normally invoked using the with statement (described in section The with statement), but can also be used by directly invoking their methods.

Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc.

For more information on context managers, see Context Manager Types. The object class itself does not provide the context manager methods.

object.__enter__(self)¶: Enter the runtime context related to this object. The with statement will bind this method’s return value to the target(s) specified in the as clause of the statement, if any.

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

Exit the runtime context related to this object. The parameters describe the exception that caused the context to be exited. If the context was exited without an exception, all three arguments will be None.

If an exception is supplied, and the method wishes to suppress the exception (i.e., prevent it from being propagated), it should return a true value. Otherwise, the exception will be processed normally upon exit from this method.

Note that __exit__() methods should not reraise the passed-in exception; this is the caller’s responsibility.

См. также

PEP 343 - The «with» statement: The specification, background, and examples for the Python with statement.

3.3.10. Customizing positional arguments in class pattern matching¶

When using a class name in a pattern, positional arguments in the pattern are not allowed by default, i.e. case MyClass(x, y) is typically invalid without special support in MyClass. To be able to use that kind of pattern, the class needs to define a __match_args__ attribute.

object.__match_args__¶: This class variable can be assigned a tuple of strings. When this class is used in a class pattern with positional arguments, each positional argument will be converted into a keyword argument, using the corresponding value in __match_args__ as the keyword. The absence of this attribute is equivalent to setting it to ().

For example, if MyClass.__match_args__ is ("left", "center", "right") that means that case MyClass(x, y) is equivalent to case MyClass(left=x, center=y). Note that the number of arguments in the pattern must be smaller than or equal to the number of elements in __match_args__; if it is larger, the pattern match attempt will raise a TypeError.

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

См. также

PEP 634 - Structural Pattern Matching: The specification for the Python match statement.

3.3.11. Emulating buffer types¶

The buffer protocol provides a way for Python objects to expose efficient access to a low-level memory array. This protocol is implemented by builtin types such as bytes and memoryview, and third-party libraries may define additional buffer types.

While buffer types are usually implemented in C, it is also possible to implement the protocol in Python.

object.__buffer__(self, flags)¶

Called when a buffer is requested from self (for example, by the memoryview constructor). The flags argument is an integer representing the kind of buffer requested, affecting for example whether the returned buffer is read-only or writable. inspect.BufferFlags provides a convenient way to interpret the flags. The method must return a memoryview object.

Thread safety: In free-threaded Python, implementations must manage any internal export counter using atomic operations. The method must be safe to call concurrently from multiple threads, and the returned buffer’s underlying data must remain valid until the corresponding __release_buffer__() call completes. See Thread safety for memoryview objects for details.

object.__release_buffer__(self, buffer)¶

Called when a buffer is no longer needed. The buffer argument is a memoryview object that was previously returned by __buffer__(). The method must release any resources associated with the buffer. This method should return None.

Thread safety: In free-threaded Python, any export counter decrement must use atomic operations. Resource cleanup must be thread-safe, as the final release may race with concurrent releases from other threads.

Buffer objects that do not need to perform any cleanup are not required to implement this method.

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

См. также

PEP 688 - Making the buffer protocol accessible in Python: Introduces the Python __buffer__ and __release_buffer__ methods.
collections.abc.Buffer: ABC for buffer types.

3.3.12. Annotations¶

Functions, classes, and modules may contain annotations, which are a way to associate information (usually type hints) with a symbol.

object.__annotations__¶: This attribute contains the annotations for an object. It is lazily evaluated, so accessing the attribute may execute arbitrary code and raise exceptions. If evaluation is successful, the attribute is set to a dictionary mapping from variable names to annotations.

Изменено в версии 3.14: Annotations are now lazily evaluated.

object.__annotate__(format)¶

An annotate function. Returns a new dictionary object mapping attribute/parameter names to their annotation values.

Takes a format parameter specifying the format in which annotations values should be provided. It must be a member of the annotationlib.Format enum, or an integer with a value corresponding to a member of the enum.

If an annotate function doesn’t support the requested format, it must raise NotImplementedError. Annotate functions must always support VALUE format; they must not raise NotImplementedError() when called with this format.

When called with VALUE format, an annotate function may raise NameError; it must not raise NameError when called requesting any other format.

If an object does not have any annotations, __annotate__ should preferably be set to None (it can’t be deleted), rather than set to a function that returns an empty dict.

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

См. также

PEP 649 — Deferred evaluation of annotation using descriptors: Introduces lazy evaluation of annotations and the __annotate__ function.

3.3.13. Special method lookup¶

For custom classes, implicit invocations of special methods are only guaranteed to work correctly if defined on an object’s type, not in the object’s instance dictionary. That behaviour is the reason why the following code raises an exception:

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

The rationale behind this behaviour lies with a number of special methods such as __hash__() and __repr__() that are implemented by all objects, including type objects. If the implicit lookup of these methods used the conventional lookup process, they would fail when invoked on the type object itself:

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

Incorrectly attempting to invoke an unbound method of a class in this way is sometimes referred to as „metaclass confusion“, and is avoided by bypassing the instance when looking up special methods:

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

In addition to bypassing any instance attributes in the interest of correctness, implicit special method lookup generally also bypasses the __getattribute__() method even of the object’s metaclass:

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

Bypassing the __getattribute__() machinery in this fashion provides significant scope for speed optimisations within the interpreter, at the cost of some flexibility in the handling of special methods (the special method must be set on the class object itself in order to be consistently invoked by the interpreter).

3.4. Coroutines¶

3.4.1. Awaitable Objects¶

An awaitable object generally implements an __await__() method. Coroutine objects returned from async def functions are awaitable.

Примечание

The generator iterator objects returned from generators decorated with types.coroutine() are also awaitable, but they do not implement __await__().

object.__await__(self)¶: Must return an iterator. Should be used to implement awaitable objects. For instance, asyncio.Future implements this method to be compatible with the await expression. The object class itself is not awaitable and does not provide this method.

Примечание

The language doesn’t place any restriction on the type or value of the objects yielded by the iterator returned by __await__, as this is specific to the implementation of the asynchronous execution framework (e.g. asyncio) that will be managing the awaitable object.

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

См. также

PEP 492 for additional information about awaitable objects.

3.4.2. Coroutine Objects¶

Coroutine objects are awaitable objects. A coroutine’s execution can be controlled by calling __await__() and iterating over the result. When the coroutine has finished executing and returns, the iterator raises StopIteration, and the exception’s value attribute holds the return value. If the coroutine raises an exception, it is propagated by the iterator. Coroutines should not directly raise unhandled StopIteration exceptions.

Coroutines also have the methods listed below, which are analogous to those of generators (see Generator-iterator methods). However, unlike generators, coroutines do not directly support iteration.

Coroutines are generic over the types of their yield, send, and return values, respectively.

Изменено в версии 3.5.2: It is a RuntimeError to await on a coroutine more than once.

coroutine.send(value)¶: Starts or resumes execution of the coroutine. If value is None, this is equivalent to advancing the iterator returned by __await__(). If value is not None, this method delegates to the send() method of the iterator that caused the coroutine to suspend. The result (return value, StopIteration, or other exception) is the same as when iterating over the __await__() return value, described above.

coroutine.throw(value)¶
coroutine.throw(type[, value[, traceback]]): Raises the specified exception in the coroutine. This method delegates to the throw() method of the iterator that caused the coroutine to suspend, if it has such a method. Otherwise, the exception is raised at the suspension point. The result (return value, StopIteration, or other exception) is the same as when iterating over the __await__() return value, described above. If the exception is not caught in the coroutine, it propagates back to the caller.

Изменено в версии 3.12: The second signature (type[, value[, traceback]]) is deprecated and may be removed in a future version of Python.

coroutine.close()¶

Causes the coroutine to clean itself up and exit. If the coroutine is suspended, this method first delegates to the close() method of the iterator that caused the coroutine to suspend, if it has such a method. Then it raises GeneratorExit at the suspension point, causing the coroutine to immediately clean itself up. Finally, the coroutine is marked as having finished executing, even if it was never started.

Coroutine objects are automatically closed using the above process when they are about to be destroyed.

3.4.3. Asynchronous Iterators¶

An asynchronous iterator can call asynchronous code in its __anext__ method.

Asynchronous iterators can be used in an async for statement.

The object class itself does not provide these methods.

object.__aiter__(self)¶: Must return an asynchronous iterator object.

object.__anext__(self)¶: Must return an awaitable resulting in a next value of the iterator. Should raise a StopAsyncIteration error when the iteration is over.

An example of an asynchronous iterable object:

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

Изменено в версии 3.7: Prior to Python 3.7, __aiter__() could return an awaitable that would resolve to an asynchronous iterator.

Starting with Python 3.7, __aiter__() must return an asynchronous iterator object. Returning anything else will result in a TypeError error.

3.4.4. Asynchronous Context Managers¶

An asynchronous context manager is a context manager that is able to suspend execution in its __aenter__ and __aexit__ methods.

Asynchronous context managers can be used in an async with statement.

The object class itself does not provide these methods.

object.__aenter__(self)¶: Semantically similar to __enter__(), the only difference being that it must return an awaitable.

object.__aexit__(self, exc_type, exc_value, traceback)¶: Semantically similar to __exit__(), the only difference being that it must return an awaitable.

An example of an asynchronous context manager class:

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

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

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

Примечания

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

3.1. Объекты, значения и типы данных¶

3.2. Иерархия стандартных типов¶

3.2.1. None¶

3.2.2. NotImplemented¶

3.2.3. Ellipsis¶

3.2.4. numbers.Number¶

3.2.4.1. numbers.Integral¶

3.2.4.2. numbers.Real (float)¶

3.2.4.3. numbers.Complex (complex)¶

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

3.2.5.1. Неизменяемые последовательности¶

3.2.5.2. Изменяемые последовательности¶

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

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

3.2.7.1. Словари¶

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

3.2.8.1. Пользовательские функции¶

3.2.8.1.1. Специальные атрибуты, доступные только для чтения¶

3.2.8.1.2. Специальные атрибуты, доступные для записи¶

3.2.8.2. Методы экземпляра¶

3.2.8.3. Генераторные функции¶

3.2.8.4. Сопрограммные функции¶

3.2.8.5. Асинхронные генераторные функции¶

3.2.8.6. Встроенные функции¶

3.2.8.7. Встроенные методы¶

3.2.8.8. Классы¶

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

3.2.9. Модули¶

3.2.9.1. Атрибуты объектов модулей, связанные с импортом¶

3.2.9.2. Другие доступные для записи атрибуты объектов модулей¶

3.2.9.3. Словари модулей¶

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

3.2.10.1. Специальные атрибуты¶

3.2.10.2. Специальные методы¶

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

3.2.11.1. Специальные атрибуты¶

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

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

3.2.13.1. Объекты кода¶

3.2.13.1.1. Специальные атрибуты, доступные только для чтения¶

3.2.13.1.2. Методы объектов кода¶

3.2.13.2. Объекты кадров¶

3.2.13.2.1. Специальные атрибуты, доступные только для чтения¶

3.2.13.2.2. Специальные атрибуты, доступные для записи¶

3.2.13.2.3. Методы объекта кадра¶

3.2.13.3. Объекты трассировки¶

3.2.13.4. Объекты срезов¶

3.2.13.5. Объекты статических методов¶

3.2.13.6. Объекты методов класса¶

3.3. Имена специальных методов¶

3.3.1. Базовая настройка поведения¶

3.3.2. Customizing attribute access¶

3.3.2.1. Customizing module attribute access¶

3.3.2.2. Implementing Descriptors¶

3.3.2.3. Invoking Descriptors¶

3.3.2.4. __slots__¶

3.3.3. Customizing class creation¶

3.3.3.1. Metaclasses¶

3.3.3.2. Resolving MRO entries¶

3.3.3.3. Determining the appropriate metaclass¶

3.3.3.4. Preparing the class namespace¶

3.3.3.5. Executing the class body¶

3.3.3.6. Creating the class object¶

3.3.3.7. Uses for metaclasses¶

3.3.4. Customizing instance and subclass checks¶

3.3.5. Emulating generic types¶

3.3.5.1. The purpose of __class_getitem__¶

3.3.5.2. __class_getitem__ versus __getitem__¶

3.3.6. Emulating callable objects¶

3.3.7. Emulating container types¶

3.3.8. Emulating numeric types¶

3.3.9. With Statement Context Managers¶

3.3.10. Customizing positional arguments in class pattern matching¶

3.3.11. Emulating buffer types¶

3.3.12. Annotations¶

3.3.13. Special method lookup¶

3.4. Coroutines¶

3.4.1. Awaitable Objects¶

3.4.2. Coroutine Objects¶

3.2.4. `numbers.Number`¶

3.2.4.1. `numbers.Integral`¶

3.2.4.2. `numbers.Real` (`float`)¶

3.2.4.3. `numbers.Complex` (`complex`)¶

3.3.2.4. slots¶

3.3.5.2. __class_getitem versus getitem__¶