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()"
возвращает количество элементов в отображении.

Есть два встроенных типа отображений:


3.2.7.1. Словари
~~~~~~~~~~~~~~~~

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

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

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

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

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


3.2.7.2. Замороженные словари
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Они представляют собой неизменяемые словари. Они создаются с помощью
встроенного конструктора "frozendict()". Такой словарь является
*хешируемым*, если все его ключи и значения хэшируемы. В этом случае
его можно использовать как элемент множества или как ключ другого
отображения. "frozendict" не является подклассом "dict"; он
непосредственно наследует от "object".

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


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.16: "__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__

   "__file__" — необязательный атрибут, который может быть установлен
   или отсутствовать. Оба атрибута должны иметь тип "str", если они
   доступны.

   Необязательный атрибут "__file__" указывает имя файла, из которого
   был загружен модуль (если он был загружен из файла), либо имя файла
   общей библиотеки для модулей расширений, динамически загруженных из
   общей библиотеки. Он может отсутствовать у некоторых типов модулей,
   например у модулей C, статически скомпонованных с интерпретатором.
   Кроме того, система импорта может оставить его неустановленным,
   если он не имеет смысла (например, для модуля, загруженного из базы
   данных).

Изменено в версии 3.15: Атрибут "__cached__" больше не устанавливается
для модулей и не учитывается системой импорта или стандартной
библиотекой.


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

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

module.__doc__

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

module.__annotations__

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

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

module.__annotate__

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

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

module.__lazy_modules__

   Контейнер (объект, реализующий "__contains__()") строк с полными
   квалифицированными именами модулей. Если он определён на уровне
   модуля, любая обычная инструкция "import" в этом модуле, целевой
   модуль которой указан в этом контейнере, рассматривается как
   ленивый импорт, словно используется ключевое слово "lazy". На
   импорты внутри функций, классов или блоков "try"/"except"/"finally"
   это не влияет.

   Подробности и примеры см. в Совместимость через __lazy_modules__.

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


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__()", то он вызывается вместо
непосредственного изменения словаря экземпляра.

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


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_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()".

Добавлено в версии 3.15: Тип "slice()" теперь поддерживает обращение к
элементу. Например, "slice[float]" можно использовать в аннотациях
типов для указания среза, содержащего объекты "float".

Специальные атрибуты, доступные только для чтения: "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. Special method names
=========================

A class can implement certain operations that are invoked by special
syntax (such as arithmetic operations or subscripting and slicing) by
defining methods with special names. This is Python's approach to
*operator overloading*, allowing classes to define their own behavior
with respect to language operators.  For instance, if a class defines
a method named "__getitem__()", and "x" is an instance of this class,
then "x[i]" is roughly equivalent to "type(x).__getitem__(x, i)".
Except where mentioned, attempts to execute an operation raise an
exception when no appropriate method is defined (typically
"AttributeError" or "TypeError").

Setting a special method to "None" indicates that the corresponding
operation is not available.  For example, if a class sets "__iter__()"
to "None", the class is not iterable, so calling "iter()" on its
instances will raise a "TypeError" (without falling back to
"__getitem__()"). [2]

When implementing a class that emulates any built-in type, it is
important that the emulation only be implemented to the degree that it
makes sense for the object being modelled.  For example, some
sequences may work well with retrieval of individual elements, but
extracting a slice may not make sense. (One example of this is the
NodeList interface in the W3C's Document Object Model.)


3.3.1. Basic customization
--------------------------

object.__new__(cls[, ...])

   Called to create a new instance of class *cls*.  "__new__()" is a
   static method (special-cased so you need not declare it as such)
   that takes the class of which an instance was requested as its
   first argument.  The remaining arguments are those passed to the
   object constructor expression (the call to the class).  The return
   value of "__new__()" should be the new object instance (usually an
   instance of *cls*).

   Typical implementations create a new instance of the class by
   invoking the superclass's "__new__()" method using
   "super().__new__(cls[, ...])" with appropriate arguments and then
   modifying the newly created instance as necessary before returning
   it.

   If "__new__()" is invoked during object construction and it returns
   an instance of *cls*, then the new instance’s "__init__()" method
   will be invoked like "__init__(self[, ...])", where *self* is the
   new instance and the remaining arguments are the same as were
   passed to the object constructor.

   If "__new__()" does not return an instance of *cls*, then the new
   instance's "__init__()" method will not be invoked.

   "__new__()" is intended mainly to allow subclasses of immutable
   types (like int, str, or tuple) to customize instance creation.  It
   is also commonly overridden in custom metaclasses in order to
   customize class creation.

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", "dict", and
   "frozendict". 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*^2) 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).See also
     "PYTHONHASHSEED".

   Изменено в версии 3.3: Hash randomization is enabled by default.

object.__bool__(self)

   Called to implement truth value testing and the built-in operation
   "bool()"; should return "False" or "True".  When this method is not
   defined, "__len__()" is called, if it is defined, and the object is
   considered true if its result is nonzero.  If a class defines
   neither "__len__()" nor "__bool__()" (which is true of the "object"
   class itself), all its instances are considered true.


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 *__slots__* other than *__dict__* and
  *__weakref__* are defined for a class derived from a ""variable-
  length" built-in type" such as "int", "bytes", and "type", except
  "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.15: Allowed defining the *__dict__* and
*__weakref__* *__slots__* for any class. Allowed defining any
*__slots__* for a class derived from "tuple".


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:

1. The "type.__new__" method collects all of the attributes in the
   class namespace that define a "__set_name__()" method;

2. Those "__set_name__" methods are called with the class being
   defined and the assigned name of that particular attribute;

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

-[ Примечания ]-

[1] It *is* possible in some cases to change an object's type, under
    certain controlled conditions. It generally isn't a good idea
    though, since it can lead to some very strange behaviour if it is
    handled incorrectly.

[2] The "__hash__()", "__iter__()", "__reversed__()",
    "__contains__()", "__class_getitem__()" and "__fspath__()" methods
    have special handling for this. Others will still raise a
    "TypeError", but may do so by relying on the behavior that "None"
    is not callable.

[3] "Does not support" here means that the class has no such method,
    or the method returns "NotImplemented".  Do not set the method to
    "None" if you want to force fallback to the right operand's
    reflected method—that will instead have the opposite effect of
    explicitly *blocking* such fallback.

[4] For operands of the same type, it is assumed that if the non-
    reflected method (such as "__add__()") fails then the operation is
    not supported, which is why the reflected method is not called.

[5] If the right operand's type is a subclass of the left operand's
    type, the reflected method having precedence allows subclasses to
    override their ancestors' operations.
