# 3. Модель даних

## 3.1. Об’єкти, значення та типи

Objects are Python’s abstraction for data. All data in a Python program is represented by objects or by relations between objects. Even code is represented by objects.

Every object has an identity, a type and a value. An object’s identity never changes once it has been created; you may think of it as the object’s address in memory. The `is` operator compares the identity of two objects; the `id()` function returns an integer representing its identity.

Для CPython `id(x)` — це адреса пам’яті, де зберігається `x`.

Тип об’єкта визначає операції, які об’єкт підтримує (наприклад, «чи має він довжину?»), а також визначає можливі значення для об’єктів цього типу. Функція `type()` повертає тип об’єкта (який сам є об’єктом). Як і його ідентифікатор, type об’єкта також не змінюється. [1]

Значення деяких об’єктів може змінюватися. Об’єкти, чиє значення може змінюватися, називаються змінними; об’єкти, значення яких не змінюються після їх створення, називаються незмінними. (Значення незмінного об’єкта-контейнера, що містить посилання на змінний об’єкт, може змінюватися, коли змінюється значення останнього; однак контейнер усе ще вважається незмінним, оскільки набір об’єктів, який він містить, не можна змінити. Таким чином, незмінність не є строго те саме, що має незмінне значення, воно більш тонке.) Змінність об’єкта визначається його типом; наприклад, числа, рядки та кортежі незмінні, тоді як словники та списки змінні.

Об’єкти ніколи не знищуються явно; однак, коли вони стають недоступними, вони можуть бути зібрані сміттям. Реалізації дозволено відкладати збирання сміття або взагалі опускати його — це питання якості реалізації, як реалізовано збирання сміття, доки не збираються об’єкти, які все ще доступні.

Наразі CPython використовує схему підрахунку посилань із (необов’язковим) відкладеним виявленням циклічно пов’язаного сміття, яка збирає більшість об’єктів, щойно вони стають недоступними, але не гарантовано збирає сміття, що містить циклічні посилання. Перегляньте документацію модуля `gc` для отримання інформації про керування збиранням циклічного сміття. Інші реалізації діють інакше, і CPython може змінитися. Не покладайтеся на негайну фіналізацію об’єктів, коли вони стають недоступними (тому ви завжди повинні явно закривати файли).

Note that the use of the implementation’s tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching an exception with a `try`…`except` statement may keep objects alive.

Some objects contain references to «external» resources such as open files or windows. It is understood that these resources are freed when the object is garbage-collected, but since garbage collection is not guaranteed to happen, such objects also provide an explicit way to release the external resource, usually a `close()` method. Programs are strongly recommended to explicitly close such objects. The `try`…`finally` statement and the `with` statement provide convenient ways to do this.

Деякі об’єкти містять посилання на інші об’єкти; вони називаються контейнерами. Прикладами контейнерів є кортежі, списки та словники. Посилання є частиною значення контейнера. У більшості випадків, коли ми говоримо про значення контейнера, ми маємо на увазі значення, а не ідентифікацію об’єктів, що містяться; однак, коли ми говоримо про мінливість контейнера, мається на увазі лише ідентичність об’єктів, які безпосередньо містяться. Отже, якщо незмінний контейнер (наприклад, кортеж) містить посилання на змінний об’єкт, його значення змінюється, якщо змінюється цей змінний об’єкт.

Types affect almost all aspects of object behavior. Even the importance of object identity is affected in some sense: for immutable types, operations that compute new values may actually return a reference to any existing object with the same type and value, while for mutable objects this is not allowed. For example, after `a = 1; b = 1`, a and b may or may not refer to the same object with the value one, depending on the implementation. This is because `int` is an immutable type, so the reference to `1` can be reused. This behaviour depends on the implementation used, so should not be relied upon, but is something to be aware of when making use of object identity tests. However, after `c = []; d = []`, c and d are guaranteed to refer to two different, unique, newly created empty lists. (Note that `e = f = []` assigns the same object to both e and f.)

## 3.2. Стандартна ієрархія типів

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

Деякі з наведених нижче описів типів містять абзац із переліком «спеціальних атрибутів». Це атрибути, які надають доступ до реалізації і не призначені для загального використання. У майбутньому їх визначення може змінитися.

### 3.2.1. Жодного

Цей тип має єдине значення. Існує єдиний об’єкт із таким значенням. Доступ до цього об’єкта здійснюється через вбудоване ім’я `None`. Він використовується для позначення відсутності значення в багатьох ситуаціях, наприклад, його повертають функції, які явно нічого не повертають. Його значення істинності є хибним.

### 3.2.2. Не впроваджений

This type has a single value. There is a single object with this value. This object is accessed through the built-in name `NotImplemented`. Numeric methods and rich comparison methods should return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) It should not be evaluated in a boolean context.

Перегляньте Реалізація арифметичних дій для отримання додаткової інформації.

Змінено в версії 3.9: Evaluating `NotImplemented` in a boolean context was deprecated.

Змінено в версії 3.14: Evaluating `NotImplemented` in a boolean context now raises a `TypeError`. It previously evaluated to `True` and emitted a `DeprecationWarning` since Python 3.9.

### 3.2.3. Еліпсис

Цей тип має єдине значення. Існує єдиний об’єкт із таким значенням. Доступ до цього об’єкта здійснюється за допомогою літералу `...` або вбудованої назви `Ellipsis`. Його істинна цінність є істинною.

### 3.2.4. `numbers.Number`

Вони створюються за допомогою числових літералів і повертаються як результати арифметичними операторами та арифметичними вбудованими функціями. Числові об’єкти незмінні; після створення їхня цінність ніколи не змінюється. Числа Python, звичайно, тісно пов’язані з математичними числами, але підлягають обмеженням числового представлення в комп’ютерах.

Рядкові представлення числових класів, обчислені за допомогою `__repr__()` і `__str__()`, мають такі властивості:

- Це дійсні числові літерали, які, коли їх передають конструктору класу, створюють об’єкт, що має значення вихідного числа.

- Представлення в базі 10, коли це можливо.

- Початкові нулі, можливо, за винятком одного нуля перед десятковою комою, не показані.

- Кінцеві нулі, можливо, за винятком одного нуля після коми, не відображаються.

- Знак відображається лише тоді, коли число від’ємне.

Python distinguishes between integers, floating-point numbers, and complex numbers:

#### 3.2.4.1. `числа.Інтеграл`

Вони представляють елементи з математичного набору цілих чисел (додатних і від’ємних).

Примітка

Правила подання цілих чисел мають на меті дати найбільш змістовну інтерпретацію операцій зсуву та маски, що включають від’ємні цілі числа.

Є два типи цілих чисел:

Цілі числа (`int`)

  Вони представляють числа в необмеженому діапазоні, що залежить лише від доступної (віртуальної) пам’яті. Для цілей операцій зсуву та маски передбачається двійкове представлення, а від’ємні числа представлені у варіанті доповнення до 2, що створює ілюзію нескінченного рядка знакових бітів, що тягнеться вліво.

Логічні значення (`bool`)

  Вони представляють істинні значення False і True. Два об’єкти, що представляють значення `False` і `True`, є єдиними логічними об’єктами. Логічний тип є підтипом цілочисельного типу, а логічні значення поводяться як значення 0 і 1 відповідно майже в усіх контекстах, за винятком того, що при перетворенні на рядок рядки `"False"` або `"True"` повертаються відповідно.

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

These represent machine-level double precision floating-point numbers. You are at the mercy of the underlying machine architecture (and C or Java implementation) for the accepted range and handling of overflow. Python does not support single-precision floating-point numbers; the savings in processor and memory usage that are usually the reason for using these are dwarfed by the overhead of using objects in Python, so there is no reason to complicate the language with two kinds of floating-point numbers.

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

These represent complex numbers as a pair of machine-level double precision floating-point numbers. The same caveats apply as for floating-point numbers. The real and imaginary parts of a complex number `z` can be retrieved through the read-only attributes `z.real` and `z.imag`.

### 3.2.5. Послідовності

These represent finite ordered sets indexed by non-negative numbers. The built-in function `len()` returns the number of items of a sequence. When the length of a sequence is n, the index set contains the numbers 0, 1, …, n-1. Item i of sequence a is selected by `a[i]`. Some sequences, including built-in sequences, interpret negative subscripts by adding the sequence length. For example, `a[-2]` equals `a[n-2]`, the second to last item of sequence a with length `n`.

The resulting value must be a nonnegative integer less than the number of items in the sequence. If it is not, an `IndexError` is raised.

Sequences also support slicing: `a[start:stop]` selects all items with index k such that start `<=` k `<` stop. When used as an expression, a slice is a sequence of the same type. The comment above about negative subscripts also applies to negative slice positions. Note that no error is raised if a slice position is less than zero or larger than the length of the sequence.

If start is missing or `None`, slicing behaves as if start was zero. If stop is missing or `None`, slicing behaves as if stop was equal to the length of the sequence.

Деякі послідовності також підтримують «розширене нарізання» з третім параметром «кроку»: `a[i:j:k]` вибирає всі елементи a з індексом x, де `x = i + n*k`, n `>=` `0` і i `<=` x `<` j.

Послідовності розрізняють відповідно до їх мінливості:

#### 3.2.5.1. Незмінні послідовності

Об’єкт типу незмінної послідовності не може змінюватися після створення. (Якщо об’єкт містить посилання на інші об’єкти, ці інші об’єкти можуть бути змінними та змінюватися; однак набір об’єктів, на який безпосередньо посилається незмінний об’єкт, не може змінитися.)

Наступні типи є незмінними послідовностями:

рядки

  A string (`str`) is a sequence of values that represent characters, or more formally, Unicode code points. All the code points in the range `0` to `0x10FFFF` can be represented in a string.

  Python doesn’t have a dedicated character type. Instead, every code point in the string is represented as a string object with length `1`.

  The built-in function `ord()` converts a code point from its string form to an integer in the range `0` to `0x10FFFF`; `chr()` converts an integer in the range `0` to `0x10FFFF` to the corresponding length `1` string object. `str.encode()` can be used to convert a `str` to `bytes` using the given text encoding, and `bytes.decode()` can be used to achieve the opposite.

Кортежі

  The items of a `tuple` are arbitrary Python objects. Tuples of two or more items are formed by comma-separated lists of expressions. A tuple of one item (a „singleton“) can be formed by affixing a comma to an expression (an expression by itself does not create a tuple, since parentheses must be usable for grouping of expressions). An empty tuple can be formed by an empty pair of parentheses.

Байти

  A `bytes` object is an immutable array. The items are 8-bit bytes, represented by integers in the range 0 <= x < 256. Bytes literals (like `b'abc'`) and the built-in `bytes()` constructor can be used to create bytes objects. Also, bytes objects can be decoded to strings via the `decode()` method.

#### 3.2.5.2. Змінні послідовності

Змінні послідовності можна змінювати після їх створення. Нотації підписки та зрізу можна використовувати як ціль операторів призначення та `del` (видалити).

Примітка

The `collections` and `array` module provide additional examples of mutable sequence types.

На даний момент існує два типи внутрішніх змінних послідовностей:

списки

  Елементи списку є довільними об’єктами Python. Списки формуються шляхом розміщення списку виразів, розділених комами, у квадратних дужках. (Зауважте, що для формування списків довжиною 0 або 1 не потрібні особливі випадки.)

Байтові масиви

  Об’єкт bytearray є змінним масивом. Вони створюються за допомогою вбудованого конструктора `bytearray()`. Крім того, що байтові масиви є змінними (і, отже, нехешованими), байтові масиви забезпечують той самий інтерфейс і функціональність, що й незмінні об’єкти `bytes`.

### 3.2.6. Встановити типи

Вони представляють невпорядковані, кінцеві набори унікальних, незмінних об’єктів. Таким чином, вони не можуть бути індексовані жодним індексом. Однак їх можна повторювати, а вбудована функція `len()` повертає кількість елементів у наборі. Набори зазвичай використовують для швидкого тестування членства, видалення дублікатів із послідовності та обчислення математичних операцій, таких як перетин, об’єднання, різниця та симетрична різниця.

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

Наразі існує два типи внутрішніх наборів:

Набори

  Вони представляють змінний набір. Вони створюються за допомогою вбудованого конструктора `set()` і можуть бути змінені згодом кількома методами, наприклад `add()`.

Заморожені набори

  Вони являють собою незмінний набір. Вони створюються за допомогою вбудованого конструктора `frozenset()`. Оскільки заморожений набір є незмінним і hashable, його можна знову використовувати як елемент іншого набору або як ключ словника.

### 3.2.7. Відображення

Вони представляють кінцеві набори об’єктів, індексованих довільними наборами індексів. Підрядкова нотація `a[k]` вибирає елемент з індексом `k` із відображення `a`; це можна використовувати у виразах і як ціль присвоєння або операторів `del`. Вбудована функція `len()` повертає кількість елементів у відображенні.

Наразі існує єдиний внутрішній тип відображення:

#### 3.2.7.1. словники

Вони представляють кінцеві набори об’єктів, індексованих майже довільними значеннями. Єдиними типами значень, неприйнятними як ключі, є значення, що містять списки, словники чи інші змінні типи, які порівнюються за значенням, а не за ідентичністю об’єкта, тому що для ефективної реалізації словників необхідно, щоб хеш-значення ключа залишалося постійним. Числові типи, що використовуються для ключів, підкоряються звичайним правилам для числового порівняння: якщо два числа порівнюються (наприклад, `1` і `1.0`), тоді їх можна використовувати як взаємозамінні для індексування тієї самої статті словника.

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

Dictionaries are mutable; they can be created by the `{}` notation (see section Відображення словника).

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

Змінено в версії 3.7: Словники не зберігали порядок вставки у версіях Python до 3.6. У CPython 3.6 порядок вставки було збережено, але в той час це вважалося деталлю реалізації, а не гарантією мови.

### 3.2.8. Викличні типи

Це типи, до яких можна застосувати операцію виклику функції (див. розділ Дзвінки):

#### 3.2.8.1. Визначені користувачем функції

Визначений користувачем об’єкт функції створюється визначенням функції (див. розділ Визначення функцій). Її слід викликати зі списком аргументів, що містить таку саму кількість елементів, як і формальний список параметрів функції.

##### 3.2.8.1.1. Special read-only attributes

Атрибут | Значення
--- | ---
function.__builtins__ | A reference to the `dictionary` that holds the function’s builtins namespace. Added in version 3.10.
function.__globals__ | A reference to the `dictionary` that holds the function’s global variables – the global namespace of the module in which the function was defined.
function.__closure__ | `None` or a `tuple` of cells that contain bindings for the names specified in the `co_freevars` attribute of the function’s `code object`. Об’єкт клітинки має атрибут `cell_contents`. Це можна використовувати для отримання значення комірки, а також для встановлення значення.

##### 3.2.8.1.2. Special writable attributes

Most of these attributes check the type of the assigned value:

Атрибут | Значення
--- | ---
function.__doc__ | The function’s documentation string, or `None` if unavailable.
function.__name__ | The function’s name. See also: `__name__ attributes`.
function.__qualname__ | The function’s qualified name. See also: `__qualname__ attributes`. Added in version 3.3.
function.__module__ | Назва модуля, у якому була визначена функція, або «Немає», якщо вона недоступна.
function.__defaults__ | A `tuple` containing default parameter values for those parameters that have defaults, or `None` if no parameters have a default value.
function.__code__ | The code object representing the compiled function body.
function.__dict__ | The namespace supporting arbitrary function attributes. See also: `__dict__ attributes`.
function.__annotations__ | A `dictionary` containing annotations of parameters. The keys of the dictionary are the parameter names, and `'return'` for the return annotation, if provided. See also: `object.__annotations__`. Змінено в версії 3.14: Annotations are now lazily evaluated. See PEP 649.
function.__annotate__ | The annotate function for this function, or `None` if the function has no annotations. See `object.__annotate__`. Added in version 3.14.
function.__kwdefaults__ | A `dictionary` containing defaults for keyword-only parameters.
function.__type_params__ | A `tuple` containing the type parameters of a generic function. Added in version 3.12.

Function objects also support getting and setting arbitrary attributes, which can be used, for example, to attach metadata to functions. Regular attribute dot-notation is used to get and set such attributes.

Деталі реалізації CPython: CPython’s current implementation only supports function attributes on user-defined functions. Function attributes on built-in functions may be supported in the future.

Additional information about a function’s definition can be retrieved from its code object (accessible via the `__code__` attribute).

#### 3.2.8.2. Методи екземплярів

Об’єкт методу екземпляра поєднує в собі клас, екземпляр класу та будь-який об’єкт, що викликається (зазвичай це функція, визначена користувачем).

Special read-only attributes:

method.__self__ | Refers to the class instance object to which the method is bound
method.__func__ | Refers to the original function object
method.__doc__ | The method’s documentation (same as `method.__func__.__doc__`). A `string` if the original function had a docstring, else `None`.
method.__name__ | The name of the method (same as `method.__func__.__name__`)
method.__module__ | The name of the module the method was defined in, or `None` if unavailable.

Methods also support accessing (but not setting) the arbitrary function attributes on the underlying function object.

User-defined method objects may be created when getting an attribute of a class (perhaps via an instance of that class), if that attribute is a user-defined function object or a `classmethod` object.

When an instance method object is created by retrieving a user-defined function object from a class via one of its instances, its `__self__` attribute is the instance, and the method object is said to be bound. The new method’s `__func__` attribute is the original function object.

When an instance method object is created by retrieving a `classmethod` object from a class or instance, its `__self__` attribute is the class itself, and its `__func__` attribute is the function object underlying the class method.

When an instance method object is called, the underlying function (`__func__`) is called, inserting the class instance (`__self__`) in front of the argument list. For instance, when `C` is a class which contains a definition for a function `f()`, and `x` is an instance of `C`, calling `x.f(1)` is equivalent to calling `C.f(x, 1)`.

When an instance method object is derived from a `classmethod` object, the «class instance» stored in `__self__` will actually be the class itself, so that calling either `x.f(1)` or `C.f(1)` is equivalent to calling `f(C,1)` where `f` is the underlying function.

It is important to note that user-defined functions which are attributes of a class instance are not converted to bound methods; this only happens when the function is an attribute of the class.

#### 3.2.8.3. Функції генератора

Функція або метод, який використовує оператор `yield` (див. розділ Оператор yield), називається функцією-генератором. Під час виклику така функція завжди повертає об’єкт iterator, який можна використовувати для виконання тіла функції: виклик методу `iterator.__next__()` ітератора призведе до виконання функції, доки вона не надасть значення за допомогою оператора `yield`. Коли функція виконує оператор `return` або виходить з кінця, виникає виняток `StopIteration`, і ітератор досягне кінця набору значень, які потрібно повернути.

#### 3.2.8.4. Функції співпрограми

Функція або метод, визначений за допомогою `async def`, називається coroutine function. Така функція під час виклику повертає об’єкт coroutine. Він може містити вирази `await`, а також оператори `async with` і `async for`. Дивіться також розділ Об’єкти співпрограми.

#### 3.2.8.5. Функції асинхронного генератора

Функція або метод, визначений за допомогою `async def` і який використовує оператор `yield`, називається функцією асинхронного генератора. Під час виклику така функція повертає об’єкт asynchronous iterator, який можна використовувати в операторі `async for` для виконання тіла функції.

Виклик методу `aiterator.__anext__` асинхронного ітератора поверне awaitable, який у разі очікування виконуватиметься, доки не надасть значення за допомогою виразу `yield`. Коли функція виконує порожній оператор `return` або виходить за межі кінця, виникає виняткова ситуація `StopAsyncIteration`, і асинхронний ітератор досягне кінця набору значень, які потрібно отримати.

#### 3.2.8.6. Вбудовані функції

A built-in function object is a wrapper around a C function. Examples of built-in functions are `len()` and `math.sin()` (`math` is a standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes:

- `__doc__` is the function’s documentation string, or `None` if unavailable. See `function.__doc__`.

- `__name__` is the function’s name. See `function.__name__`.

- `__self__` is set to `None` (but see the next item).

- `__module__` is the name of the module the function was defined in or `None` if unavailable. See `function.__module__`.

#### 3.2.8.7. Вбудовані методи

This is really a different disguise of a built-in function, this time containing an object passed to the C function as an implicit extra argument. An example of a built-in method is `alist.append()`, assuming alist is a list object. In this case, the special read-only attribute `__self__` is set to the object denoted by alist. (The attribute has the same semantics as it does with `other instance methods`.)

#### 3.2.8.8. Заняття

Classes are callable. These objects normally act as factories for new instances of themselves, but variations are possible for class types that override `__new__()`. The arguments of the call are passed to `__new__()` and, in the typical case, to `__init__()` to initialize the new instance.

#### 3.2.8.9. Екземпляри класу

Екземпляри довільних класів можна зробити викликаними, визначивши метод `__call__()` у їхньому класі.

### 3.2.9. Модулі

Modules are a basic organizational unit of Python code, and are created by the import system as invoked either by the `import` statement, or by calling functions such as `importlib.import_module()` and built-in `__import__()`. A module object has a namespace implemented by a `dictionary` object (this is the dictionary referenced by the `__globals__` attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., `m.x` is equivalent to `m.__dict__["x"]`. A module object does not contain the code object used to initialize the module (since it isn’t needed once the initialization is done).

Призначення атрибутів оновлює словник простору імен модуля, наприклад, `m.x = 1` еквівалентно `m.__dict__["x"] = 1`.

#### 3.2.9.1. Import-related attributes on module objects

Module objects have the following attributes that relate to the import system. When a module is created using the machinery associated with the import system, these attributes are filled in based on the module’s spec, before the loader executes and loads the module.

To create a module dynamically rather than using the import system, it’s recommended to use `importlib.util.module_from_spec()`, which will set the various import-controlled attributes to appropriate values. It’s also possible to use the `types.ModuleType` constructor to create modules directly, but this technique is more error-prone, as most attributes must be manually set on the module object after it has been created when using this approach.

Застереження

With the exception of `__name__`, it is strongly recommended that you rely on `__spec__` and its attributes instead of any of the other individual attributes listed in this subsection. Note that updating an attribute on `__spec__` will not update the corresponding attribute on the module itself:

    >>> import typing
    >>> typing.__name__, typing.__spec__.name
    ('typing', 'typing')
    >>> typing.__spec__.name = 'spelling'
    >>> typing.__name__, typing.__spec__.name
    ('typing', 'spelling')
    >>> typing.__name__ = 'keyboard_smashing'
    >>> typing.__name__, typing.__spec__.name
    ('keyboard_smashing', 'spelling')

module.__name__

  The name used to uniquely identify the module in the import system. For a directly executed module, this will be set to `"__main__"`.

  This attribute must be set to the fully qualified name of the module. It is expected to match the value of `module.__spec__.name`.

module.__spec__

  A record of the module’s import-system-related state.

  Set to the `module spec` that was used when importing the module. See Module specs for more details.

  Added in version 3.4.

module.__package__

  The package a module belongs to.

  If the module is top-level (that is, not a part of any specific package) then the attribute should be set to `''` (the empty string). Otherwise, it should be set to the name of the module’s package (which can be equal to `module.__name__` if the module itself is a package). See PEP 366 for further details.

  This attribute is used instead of `__name__` to calculate explicit relative imports for main modules. It defaults to `None` for modules created dynamically using the `types.ModuleType` constructor; use `importlib.util.module_from_spec()` instead to ensure the attribute is set to a `str`.

  It is strongly recommended that you use `module.__spec__.parent` instead of `module.__package__`. `__package__` is now only used as a fallback if `__spec__.parent` is not set, and this fallback path is deprecated.

  Змінено в версії 3.4: This attribute now defaults to `None` for modules created dynamically using the `types.ModuleType` constructor. Previously the attribute was optional.

  Змінено в версії 3.6: The value of `__package__` is expected to be the same as `__spec__.parent`. `__package__` is now only used as a fallback during import resolution if `__spec__.parent` is not defined.

  Змінено в версії 3.10: `ImportWarning` is raised if an import resolution falls back to `__package__` instead of `__spec__.parent`.

  Змінено в версії 3.12: Raise `DeprecationWarning` instead of `ImportWarning` when falling back to `__package__` during import resolution.

  Deprecated since version 3.13, removed in version 3.15: `__package__` will cease to be set or taken into consideration by the import system or standard library.

module.__loader__

  The loader object that the import machinery used to load the module.

  This attribute is mostly useful for introspection, but can be used for additional loader-specific functionality, for example getting data associated with a loader.

  `__loader__` defaults to `None` for modules created dynamically using the `types.ModuleType` constructor; use `importlib.util.module_from_spec()` instead to ensure the attribute is set to a loader object.

  It is strongly recommended that you use `module.__spec__.loader` instead of `module.__loader__`.

  Змінено в версії 3.4: This attribute now defaults to `None` for modules created dynamically using the `types.ModuleType` constructor. Previously the attribute was optional.

  Deprecated since version 3.12, removed in version 3.16: Setting `__loader__` on a module while failing to set `__spec__.loader` is deprecated. In Python 3.16, `__loader__` will cease to be set or taken into consideration by the import system or the standard library.

module.__path__

  A (possibly empty) sequence of strings enumerating the locations where the package’s submodules will be found. Non-package modules should not have a `__path__` attribute. See __path__ attributes on modules for more details.

  It is strongly recommended that you use `module.__spec__.submodule_search_locations` instead of `module.__path__`.

module.__file__

  `__file__` is an optional attribute that may or may not be set. Both attributes should be a `str` when they are available.

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

  Deprecated since version 3.13, removed in version 3.15: Setting `__cached__` on a module while failing to set `__spec__.cached` is deprecated. In Python 3.15, `__cached__` will cease to be set or taken into consideration by the import system or standard library.

  Змінено в версії 3.15: `__cached__` is no longer set.

#### 3.2.9.2. Other writable attributes on module objects

As well as the import-related attributes listed above, module objects also have the following writable attributes:

module.__doc__

  The module’s documentation string, or `None` if unavailable. See also: `__doc__ attributes`.

module.__annotations__

  A dictionary containing variable annotations collected during module body execution. For best practices on working with `__annotations__`, see `annotationlib`.

  Змінено в версії 3.14: Annotations are now lazily evaluated. See PEP 649.

module.__annotate__

  The annotate function for this module, or `None` if the module has no annotations. See also: `__annotate__` attributes.

  Added in version 3.14.

module.__lazy_modules__

  A container (an object implementing `__contains__()`) of fully qualified module name strings. When defined at module scope, any regular `import` statement in that module whose target module name appears in this container is treated as a lazy import, as if the `lazy` keyword had been used. Imports inside functions, class bodies, or `try`/`except`/`finally` blocks are unaffected.

  See Compatibility via __lazy_modules__ for details and examples.

  Added in version 3.15.

#### 3.2.9.3. Module dictionaries

Module objects also have the following special read-only attribute:

module.__dict__

  The module’s namespace as a dictionary object. Uniquely among the attributes listed here, `__dict__` cannot be accessed as a global variable from within a module; it can only be accessed as an attribute on module objects.

  Через те, як CPython очищає словники модулів, словник модуля буде очищено, коли модуль виходить із області видимості, навіть якщо в словнику все ще є живі посилання. Щоб уникнути цього, скопіюйте словник або збережіть модуль, використовуючи його словник безпосередньо.

### 3.2.10. Спеціальні заняття

Custom class types are typically created by class definitions (see section Визначення класів). A class has a namespace implemented by a dictionary object. Class attribute references are translated to lookups in this dictionary, e.g., `C.x` is translated to `C.__dict__["x"]` (although there are a number of hooks which allow for other means of locating attributes). When the attribute name is not found there, the attribute search continues in the base classes. This search of the base classes uses the C3 method resolution order which behaves correctly even in the presence of „diamond“ inheritance structures where there are multiple inheritance paths leading back to a common ancestor. Additional details on the C3 MRO used by Python can be found at The Python 2.3 Method Resolution Order.

When a class attribute reference (for class `C`, say) would yield a class method object, it is transformed into an instance method object whose `__self__` attribute is `C`. When it would yield a `staticmethod` object, it is transformed into the object wrapped by the static method object. See section Реалізація дескрипторів for another way in which attributes retrieved from a class may differ from those actually contained in its `__dict__`.

Призначення атрибутів класу оновлює словник класу, а не словник базового класу.

Об’єкт класу можна викликати (див. вище), щоб створити екземпляр класу (див. нижче).

#### 3.2.10.1. Special attributes

Атрибут | Значення
--- | ---
type.__name__ | The class’s name. See also: `__name__ attributes`.
type.__qualname__ | The class’s qualified name. See also: `__qualname__ attributes`.
type.__module__ | Ім’я модуля, в якому було визначено клас.
type.__dict__ | A `mapping proxy` providing a read-only view of the class’s namespace. See also: `__dict__ attributes`.
type.__bases__ | A `tuple` containing the class’s bases. In most cases, for a class defined as `class X(A, B, C)`, `X.__bases__` will be exactly equal to `(A, B, C)`.
type.__base__ | Деталі реалізації CPython: The single base class in the inheritance chain that is responsible for the memory layout of instances. This attribute corresponds to `tp_base` at the C level.
type.__doc__ | The class’s documentation string, or `None` if undefined. Not inherited by subclasses.
type.__annotations__ | A dictionary containing variable annotations collected during class body execution. See also: `__annotations__ attributes`. For best practices on working with `__annotations__`, please see `annotationlib`. Use `annotationlib.get_annotations()` instead of accessing this attribute directly. Попередження Accessing the `__annotations__` attribute directly on a class object may return annotations for the wrong class, specifically in certain cases where the class, its base class, or a metaclass is defined under `from __future__ import annotations`. See 749 for details. This attribute does not exist on certain builtin classes. On user-defined classes without `__annotations__`, it is an empty dictionary. Змінено в версії 3.14: Annotations are now lazily evaluated. See PEP 649.
type.__annotate__() | The annotate function for this class, or `None` if the class has no annotations. See also: `__annotate__ attributes`. Added in version 3.14.
type.__type_params__ | A `tuple` containing the type parameters of a generic class. Added in version 3.12.
type.__static_attributes__ | A `tuple` containing names of attributes of this class which are assigned through `self.X` from any function in its body. Added in version 3.13.
type.__firstlineno__ | The line number of the first line of the class definition, including decorators. Setting the `__module__` attribute removes the `__firstlineno__` item from the type’s dictionary. Added in version 3.13.
type.__mro__ | The `tuple` of classes that are considered when looking for base classes during method resolution.

#### 3.2.10.2. Special methods

In addition to the special attributes described above, all Python classes also have the following two methods available:

type.mro()

  This method can be overridden by a metaclass to customize the method resolution order for its instances. It is called at class instantiation, and its result is stored in `__mro__`.

type.__subclasses__()

  Each class keeps a list of weak references to its immediate subclasses. This method returns a list of all those references still alive. The list is in definition order. Example:

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

### 3.2.11. Екземпляри класу

A class instance is created by calling a class object (see above). A class instance has a namespace implemented as a dictionary which is the first place in which attribute references are searched. When an attribute is not found there, and the instance’s class has an attribute by that name, the search continues with the class attributes. If a class attribute is found that is a user-defined function object, it is transformed into an instance method object whose `__self__` attribute is the instance. Static method and class method objects are also transformed; see above under «Classes». See section Реалізація дескрипторів for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in the class’s `__dict__`. If no class attribute is found, and the object’s class has a `__getattr__()` method, that is called to satisfy the lookup.

Призначення та видалення атрибутів оновлюють словник екземпляра, а не словник класу. Якщо клас має метод `__setattr__()` або `__delattr__()`, він викликається замість безпосереднього оновлення словника примірника.

Екземпляри класу можуть видавати себе за числа, послідовності або відображення, якщо вони мають методи з певними спеціальними назвами. Дивіться розділ Назви спеціальних методів.

#### 3.2.11.1. Special attributes

object.__class__

  Клас, до якого належить екземпляр класу.

object.__dict__

  A dictionary or other mapping object used to store an object’s (writable) attributes. Not all instances have a `__dict__` attribute; see the section on __slots__ for more details.

### 3.2.12. Об’єкти введення-виведення (також відомі як файлові об’єкти)

file object представляє відкритий файл. Для створення файлових об’єктів доступні різні ярлики: вбудована функція `open()`, а також `os.popen()`, `os.fdopen()` і `makefile()` метод об’єктів сокета (і, можливо, за допомогою інших функцій або методів, наданих модулями розширення).

File objects implement common methods, listed below, to simplify usage in generic code. They are expected to be З менеджерами контексту операторів.

Об’єкти `sys.stdin`, `sys.stdout` і `sys.stderr` ініціалізуються об’єктами файлів, що відповідають стандартним потокам введення, виведення та помилок інтерпретатора; усі вони відкриті в текстовому режимі, тому відповідають інтерфейсу, визначеному `io.TextIOBase` абстрактним класом.

file.read(size=-1, /)

  Retrieve up to size data from the file. As a convenience if size is unspecified or -1 retrieve all data available.

file.write(data, /)

  Store data to the file.

file.close()

  Flush any buffers and close the underlying file.

### 3.2.13. Внутрішні типи

Кілька типів, які використовуються внутрішньо інтерпретатором, доступні користувачеві. Їх визначення можуть змінюватися в майбутніх версіях інтерпретатора, але вони згадуються тут для повноти.

#### 3.2.13.1. Об’єкти коду

Об’єкти коду представляють байт-скомпільований виконуваний код Python або bytecode. Різниця між об’єктом коду та об’єктом функції полягає в тому, що об’єкт функції містить явне посилання на глобальні елементи функції (модуль, у якому вона була визначена), тоді як об’єкт коду не містить контексту; також значення аргументів за замовчуванням зберігаються в об’єкті функції, а не в об’єкті коду (оскільки вони представляють значення, обчислені під час виконання). На відміну від функціональних об’єктів, об’єкти коду є незмінними і не містять посилань (прямих чи опосередкованих) на змінні об’єкти.

##### 3.2.13.1.1. Special read-only attributes

codeobject.co_name | The function name
codeobject.co_qualname | The fully qualified function name Added in version 3.11.
codeobject.co_argcount | The total number of positional parameters (including positional-only parameters and parameters with default values) that the function has
codeobject.co_posonlyargcount | The number of positional-only parameters (including arguments with default values) that the function has
codeobject.co_kwonlyargcount | The number of keyword-only parameters (including arguments with default values) that the function has
codeobject.co_nlocals | The number of local variables used by the function (including parameters)
codeobject.co_varnames | A `tuple` containing the names of the local variables in the function (starting with the parameter names)
codeobject.co_cellvars | A `tuple` containing the names of local variables that are referenced from at least one nested scope inside the function
codeobject.co_freevars | A `tuple` containing the names of free (closure) variables that a nested scope references in an outer scope. See also `function.__closure__`. Note: references to global and builtin names are not included.
codeobject.co_code | A string representing the sequence of bytecode instructions in the function
codeobject.co_consts | A `tuple` containing the literals used by the bytecode in the function
codeobject.co_names | A `tuple` containing the names used by the bytecode in the function
codeobject.co_filename | The name of the file from which the code was compiled
codeobject.co_firstlineno | The line number of the first line of the function
codeobject.co_stacksize | The required stack size of the code object
codeobject.co_flags | An `integer` encoding a number of flags for the interpreter.

The following flag bits are defined for `co_flags`: bit `0x04` is set if the function uses the `*arguments` syntax to accept an arbitrary number of positional arguments; bit `0x08` is set if the function uses the `**keywords` syntax to accept arbitrary keyword arguments; bit `0x20` is set if the function is a generator. See Кодові об’єкти Бітові прапорці for details on the semantics of each flags that might be present.

Future feature declarations (for example, `from __future__ import division`) also use bits in `co_flags` to indicate whether a code object was compiled with a particular feature enabled. See `compiler_flag`.

Other bits in `co_flags` are reserved for internal use.

If a code object represents a function and has a docstring, the `CO_HAS_DOCSTRING` bit is set in `co_flags` and the first item in `co_consts` is the docstring of the function.

##### 3.2.13.1.2. Methods on code objects

codeobject.co_positions()

  Returns an iterable over the source code positions of each bytecode instruction in the code object.

  The iterator returns `tuple`s containing the `(start_line, end_line, start_column, end_column)`. The i-th tuple corresponds to the position of the source code that compiled to the i-th code unit. Column information is 0-indexed utf-8 byte offsets on the given source line.

  This positional information can be missing. A non-exhaustive lists of cases where this may happen:

  - Running the interpreter with `-X` `no_debug_ranges`.

  - Loading a pyc file compiled while using `-X` `no_debug_ranges`.

  - Position tuples corresponding to artificial instructions.

  - Line and column numbers that can’t be represented due to implementation specific limitations.

  When this occurs, some or all of the tuple elements can be `None`.

  Added in version 3.11.

  Примітка

  This feature requires storing column positions in code objects which may result in a small increase of disk usage of compiled Python files or interpreter memory usage. To avoid storing the extra information and/or deactivate printing the extra traceback information, the `-X` `no_debug_ranges` command line flag or the `PYTHONNODEBUGRANGES` environment variable can be used.

codeobject.co_lines()

  Returns an iterator that yields information about successive ranges of bytecodes. Each item yielded is a `(start, end, lineno)` `tuple`:

  - `start` (an `int`) represents the offset (inclusive) of the start of the bytecode range

  - `end` (an `int`) represents the offset (exclusive) of the end of the bytecode range

  - `lineno` is an `int` representing the line number of the bytecode range, or `None` if the bytecodes in the given range have no line number

  The items yielded will have the following properties:

  - The first range yielded will have a `start` of 0.

  - The `(start, end)` ranges will be non-decreasing and consecutive. That is, for any pair of `tuple`s, the `start` of the second will be equal to the `end` of the first.

  - No range will be backwards: `end >= start` for all triples.

  - The last `tuple` yielded will have `end` equal to the size of the bytecode.

  Zero-width ranges, where `start == end`, are allowed. Zero-width ranges are used for lines that are present in the source code, but have been eliminated by the bytecode compiler.

  Added in version 3.10.

  Дивись також

  PEP 626 - Precise line numbers for debugging and other tools.

    The PEP that introduced the `co_lines()` method.

codeobject.replace(**kwargs)

  Повернути копію об’єкта коду з новими значеннями для вказаних полів.

  Code objects are also supported by the generic function `copy.replace()`.

  Added in version 3.8.

#### 3.2.13.2. Рамкові об’єкти

Frame objects represent execution frames. They may occur in traceback objects, and are also passed to registered trace functions.

##### 3.2.13.2.1. Special read-only attributes

frame.f_back | Points to the previous stack frame (towards the caller), or `None` if this is the bottom stack frame
frame.f_code | The code object being executed in this frame. Accessing this attribute raises an auditing event `object.__getattr__` with arguments `obj` and `"f_code"`.
frame.f_locals | The mapping used by the frame to look up local variables. If the frame refers to an optimized scope, this may return a write-through proxy object. Змінено в версії 3.13: Return a proxy for optimized scopes.
frame.f_globals | The dictionary used by the frame to look up global variables
frame.f_builtins | The dictionary used by the frame to look up built-in (intrinsic) names
frame.f_lasti | The «precise instruction» of the frame object (this is an index into the bytecode string of the code object)
frame.f_generator | The generator or coroutine object that owns this frame, or `None` if the frame is a normal function. Added in version 3.14.

##### 3.2.13.2.2. Special writable attributes

frame.f_trace | If not `None`, this is a function called for various events during code execution (this is used by debuggers). Normally an event is triggered for each new source line (see `f_trace_lines`).
frame.f_trace_lines | Set this attribute to `False` to disable triggering a tracing event for each source line.
frame.f_trace_opcodes | Set this attribute to `True` to allow per-opcode events to be requested. Note that this may lead to undefined interpreter behaviour if exceptions raised by the trace function escape to the function being traced.
frame.f_lineno | The current line number of the frame – writing to this from within a trace function jumps to the given line (only for the bottom-most frame). A debugger can implement a Jump command (aka Set Next Statement) by writing to this attribute.

##### 3.2.13.2.3. Frame object methods

Об’єкти фрейму підтримують один метод:

frame.clear()

  This method clears all references to local variables held by the frame. Also, if the frame belonged to a generator, the generator is finalized. This helps break reference cycles involving frame objects (for example when catching an exception and storing its traceback for later use).

  `RuntimeError` is raised if the frame is currently executing or suspended.

  Added in version 3.4.

  Змінено в версії 3.13: Attempting to clear a suspended frame raises `RuntimeError` (as has always been the case for executing frames).

#### 3.2.13.3. Об’єкти відстеження

Traceback objects represent the stack trace of an exception. A traceback object is implicitly created when an exception occurs, and may also be explicitly created by calling `types.TracebackType`.

Змінено в версії 3.7: Traceback objects can now be explicitly instantiated from Python code.

For implicitly created tracebacks, when the search for an exception handler unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section Оператор try.) It is accessible as the third item of the tuple returned by `sys.exc_info()`, and as the `__traceback__` attribute of the caught exception.

When the program contains no suitable handler, the stack trace is written (nicely formatted) to the standard error stream; if the interpreter is interactive, it is also made available to the user as `sys.last_traceback`.

For explicitly created tracebacks, it is up to the creator of the traceback to determine how the `tb_next` attributes should be linked to form a full stack trace.

Special read-only attributes:

traceback.tb_frame | Points to the execution frame of the current level. Accessing this attribute raises an auditing event `object.__getattr__` with arguments `obj` and `"tb_frame"`.
traceback.tb_lineno | Gives the line number where the exception occurred
traceback.tb_lasti | Indicates the «precise instruction».

The line number and last instruction in the traceback may differ from the line number of its frame object if the exception occurred in a `try` statement with no matching except clause or with a `finally` clause.

traceback.tb_next

  The special writable attribute `tb_next` is the next level in the stack trace (towards the frame where the exception occurred), or `None` if there is no next level.

  Змінено в версії 3.7: This attribute is now writable

#### 3.2.13.4. Розрізати об’єкти

Об’єкти фрагментів використовуються для представлення фрагментів для методів `__getitem__()`. Вони також створюються за допомогою вбудованої функції `slice()`.

Added in version 3.15: The `slice()` type now supports subscription. For example, `slice[float]` may be used in type annotations to indicate a slice containing `float` objects.

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

Об’єкти Slice підтримують один метод:

slice.indices(self, length)

  Цей метод приймає єдиний цілочисельний аргумент length і обчислює інформацію про зріз, який описав би об’єкт slice, якщо його застосувати до послідовності елементів length. Він повертає кортеж із трьох цілих чисел; відповідно, це індекси start і stop і крок або довжина кроку зрізу. Відсутні індекси або індекси, що виходять за межі, обробляються відповідно до звичайних фрагментів.

#### 3.2.13.5. Об’єкти статичних методів

Об’єкти статичних методів забезпечують спосіб відмови від перетворення об’єктів функції в об’єкти методів, описані вище. Статичний об’єкт методу є обгорткою навколо будь-якого іншого об’єкта, зазвичай об’єкта методу, визначеного користувачем. Коли об’єкт статичного методу отримується з класу або екземпляра класу, фактично повернутий об’єкт є об’єктом-огорткою, який не підлягає подальшому перетворенню. Об’єкти статичних методів також можна викликати. Об’єкти статичних методів створюються за допомогою вбудованого конструктора `staticmethod()`.

#### 3.2.13.6. Об’єкти методу класу

A class method object, like a static method object, is a wrapper around another object that alters the way in which that object is retrieved from classes and class instances. The behaviour of class method objects upon such retrieval is described above, under «instance methods». Class method objects are created by the built-in `classmethod()` constructor.

## 3.3. Назви спеціальних методів

Клас може реалізувати певні операції, які викликаються спеціальним синтаксисом (такі як арифметичні операції або індексування та зрізання), визначаючи методи зі спеціальними іменами. Це підхід Python до operator overloading, що дозволяє класам визначати власну поведінку щодо операторів мови. Наприклад, якщо клас визначає метод із назвою `__getitem__()`, а `x` є екземпляром цього класу, то `x[i]` приблизно еквівалентний `type( x).__getitem__(x, i)`. Якщо не зазначено вище, спроби виконати операцію викликають виняток, якщо відповідний метод не визначено (зазвичай `AttributeError` або `TypeError`).

Встановлення для спеціального методу значення `None` означає, що відповідна операція недоступна. Наприклад, якщо клас встановлює `__iter__()` на `None`, клас не піддається ітерації, тому виклик `iter()` у його екземплярах викличе `TypeError` ( не повертаючись до `__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. Базове налаштування

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

  Викликається для створення нового екземпляра класу cls. `__new__()` — це статичний метод (з особливим регістром, тому вам не потрібно оголошувати його як такий), який приймає клас, екземпляр якого був запитаний, як свій перший аргумент. Решта аргументів передаються у вираз конструктора об’єкта (виклик класу). Поверненим значенням `__new__()` має бути новий екземпляр об’єкта (зазвичай це екземпляр 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.

  Якщо `__new__()` викликається під час побудови об’єкта і повертає екземпляр cls, тоді новий метод `__init__()` буде викликано як `__init__(self[, ...])`, де self — це новий екземпляр, а решта аргументів ті самі, що були передані конструктору об’єкта.

  Якщо `__new__()` не повертає екземпляр cls, то метод `__init__()` нового екземпляра не буде викликано.

  `__new__()` призначений головним чином для того, щоб дозволити підкласам незмінних типів (наприклад, int, str або tuple) налаштовувати створення екземплярів. Його також зазвичай перевизначають у власних метакласах, щоб налаштувати створення класу.

object.__init__(self[, ...])

  Викликається після створення екземпляра (за допомогою `__new__()`), але до того, як його буде повернено до викликаючого. Аргументи передаються у вираз конструктора класу. Якщо базовий клас має метод `__init__()`, метод `__init__()` похідного класу, якщо такий є, повинен явно викликати його, щоб забезпечити правильну ініціалізацію частини базового класу примірника; наприклад: `super().__init__([args...])`.

  Оскільки `__new__()` і `__init__()` працюють разом у створенні об’єктів (`__new__()`, щоб створити його, і `__init__()`, щоб налаштувати його), немає не-`None` значення може повертати `__init__()`; це призведе до появи `TypeError` під час виконання.

object.__del__(self)

  Викликається, коли примірник збирається знищити. Це також називається фіналізатором або (неправильно) деструктором. Якщо базовий клас має метод `__del__()`, метод `__del__()` похідного класу, якщо такий є, повинен явно викликати його, щоб забезпечити належне видалення частини базового класу екземпляра.

  Метод `__del__()` може (хоча і не рекомендується!) відкласти знищення екземпляра шляхом створення нового посилання на нього. Це називається воскресіння об’єкта. Це залежить від реалізації, чи `__del__()` викликається вдруге, коли воскреслий об’єкт збирається знищити; поточна реалізація CPython викликає його лише один раз.

  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` не викликає напряму `x.__del__()` — перший зменшує кількість посилань для `x` на одиницю, а останній викликається лише тоді, коли `x` кількість посилань досягає нуля.

  Деталі реалізації 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.

  Дивись також

  Документація для модуля `gc`.

  Попередження

  Через ненадійні обставини, за яких викликаються методи `__del__()`, винятки, що виникають під час їх виконання, ігноруються, а попередження друкується в `sys.stderr`. Зокрема:

  - `__del__()` можна викликати, коли виконується довільний код, у тому числі з будь-якого довільного потоку. Якщо `__del__()` потрібно заблокувати або викликати будь-який інший блокуючий ресурс, це може призвести до блокування, оскільки ресурс може вже бути зайнятий кодом, який переривається для виконання `__del__()`.

  - `__del__()` можна виконати під час завершення роботи інтерпретатора. Як наслідок, глобальні змінні, до яких він має отримати доступ (включно з іншими модулями), можливо, уже були видалені або встановлені на `None`. Python гарантує, що глобальні елементи, ім’я яких починається з одного підкреслення, будуть видалені з їхнього модуля перед видаленням інших глобальних елементів; якщо немає інших посилань на такі глобали, це може допомогти впевнитися, що імпортовані модулі все ще доступні під час виклику методу `__del__()`.

object.__repr__(self)

  Викликається вбудованою функцією `repr()` для обчислення «офіційного» рядкового представлення об’єкта. Якщо це взагалі можливо, це має виглядати як дійсний вираз Python, який можна використати для відтворення об’єкта з тим самим значенням (за умови відповідного середовища). Якщо це неможливо, слід повернути рядок у формі `<...some useful description...>`. Повернене значення має бути рядковим об’єктом. Якщо клас визначає `__repr__()`, але не `__str__()`, тоді `__repr__()` також використовується, коли потрібне «неформальне» рядкове представлення екземплярів цього класу.

  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.

  Цей метод відрізняється від `object.__repr__()` тим, що не очікується, що `__str__()` поверне дійсний вираз Python: можна використовувати більш зручне або стисле представлення.

  Стандартна реалізація, визначена вбудованим типом `object`, викликає `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)

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

  Перегляньте Format specification mini-language для опису стандартного синтаксису форматування.

  Повернене значення має бути рядковим об’єктом.

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

  Змінено в версії 3.4: Сам метод __format__ `object` викликає `TypeError`, якщо передати будь-який непорожній рядок.

  Змінено в версії 3.7: `object.__format__(x, '')` тепер еквівалентний `str(x)`, а не `format(str(x), '')`.

object.__lt__(self, other)
object.__le__(self, other)
object.__eq__(self, other)
object.__ne__(self, other)
object.__gt__(self, other)
object.__ge__(self, other)

  Це так звані методи «багатого порівняння». Відповідність між символами оператора та назвами методів така: `x <y` calls `x.__lt__(y)`, `x<=y` calls `x.__le__(y)`, `x==y` calls `x.__eq__(y)`, `x!=y` calls `x.__ne__(y)`, `x> y` викликає `x.__gt__(y)`, а `x>=y` викликає `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 Порівняння цінностей: equality compares according to object identity, and order comparisons raise `TypeError`. Each default method may generate these results directly, but may also return `NotImplemented`.

  Перегляньте параграф про `__hash__()` для деяких важливих приміток щодо створення об’єктів hashable, які підтримують спеціальні операції порівняння та використовуються як ключі словника.

  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)

  Викликається вбудованою функцією `hash()` і для операцій над членами хешованих колекцій, включаючи `set`, `frozenset` і `dict`. Метод `__hash__()` має повертати ціле число. Єдиною необхідною властивістю є те, що об’єкти, які порівнюються, мають однакове хеш-значення; рекомендується змішувати геш-значення компонентів об’єкта, які також відіграють роль у порівнянні об’єктів, упаковуючи їх у кортеж і хешуючи кортеж. Приклад:

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

  Примітка

  `hash()` скорочує значення, що повертається користувацьким методом `__hash__()` об’єкта, до розміру `Py_ssize_t`. Зазвичай це 8 байтів для 64-розрядних збірок і 4 байти для 32-розрядних збірок. Якщо `__hash__()` об’єкта має взаємодіяти зі збірками різних бітових розмірів, обов’язково перевірте ширину всіх підтримуваних збірок. Простий спосіб зробити це за допомогою `python -c "import sys; print(sys.hash_info.width)"`.

  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)`.

  Для класу, який перевизначає `__eq__()` і не визначає `__hash__()`, його `__hash__()` буде неявно встановлено на `None`. Коли метод `__hash__()` класу має значення `None`, екземпляри класу викличуть відповідну `TypeError`, коли програма намагатиметься отримати їх хеш-значення, а також будуть правильно визначені як нехешується під час перевірки `isinstance(obj, collections.abc.Hashable)`.

  Якщо клас, який перевизначає `__eq__()`, потребує збереження реалізації `__hash__()` від батьківського класу, інтерпретатор має бути повідомлений про це явно, встановивши `__hash__ = <ParentClass> .__hash__`.

  Якщо клас, який не перевизначає `__eq__()`, бажає придушити підтримку хешу, він повинен включити `__hash__ = None` у визначення класу. Клас, який визначає власний `__hash__()`, який явно викликає `TypeError`, буде неправильно ідентифікований як хешований викликом `isinstance(obj, collections.abc.Hashable)`.

  Примітка

  За замовчуванням значення `__hash__()` об’єктів str і bytes «підсолюються» непередбачуваним випадковим значенням. Хоча вони залишаються незмінними в окремому процесі Python, вони не передбачувані між повторними викликами Python.

  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(n2) complexity. See https://ocert.org/advisories/ocert-2011-003.html for details.

  Зміна хеш-значень впливає на порядок ітерацій наборів. Python ніколи не надавав гарантій щодо такого порядку (і він зазвичай варіюється між 32-бітними та 64-бітними збірками).

  Дивіться також `PYTHONHASHSEED`.

  Змінено в версії 3.3: Хеш-рандомізація ввімкнена за замовчуванням.

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. Налаштування доступу до атрибутів

Наступні методи можна визначити для налаштування значення доступу до атрибутів (використання, призначення або видалення `x.name`) для екземплярів класу.

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)

  Викликається безумовно для реалізації доступу до атрибутів для екземплярів класу. Якщо клас також визначає `__getattr__()`, останній не буде викликаний, якщо `__getattribute__()` не викличе його явно або не викличе `AttributeError`. Цей метод має повертати (обчислене) значення атрибута або викликати виняток `AttributeError`. Щоб уникнути нескінченної рекурсії в цьому методі, його реалізація повинна завжди викликати метод базового класу з тим самим іменем для доступу до будь-яких необхідних атрибутів, наприклад, `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 Спеціальний метод пошуку.

  Для доступу до певних конфіденційних атрибутів викликає подію аудиту `object.__getattr__` з аргументами `obj` і `name`.

object.__setattr__(self, name, value)

  Викликається під час спроби призначення атрибута. Це викликається замість звичайного механізму (тобто збереження значення в словнику екземпляра). name — ім’я атрибута, value — значення, яке йому буде присвоєно.

  Якщо `__setattr__()` хоче призначити атрибут екземпляра, він повинен викликати метод базового класу з такою самою назвою, наприклад, `object.__setattr__(self, name, value)`.

  Для певних конфіденційних призначень атрибутів створює подію аудиту `object.__setattr__` з аргументами `obj`, `name`, `value`.

object.__delattr__(self, name)

  Як `__setattr__()`, але для видалення атрибута замість призначення. Це слід застосовувати, лише якщо `del obj.name` має значення для об’єкта.

  Для певних видалень конфіденційних атрибутів викликає подію аудиту `object.__delattr__` з аргументами `obj` і `name`.

object.__dir__(self)

  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. Налаштування доступу до атрибутів модуля

module.__getattr__()
module.__dir__()

Спеціальні імена `__getattr__` і `__dir__` також можна використовувати для налаштування доступу до атрибутів модуля. Функція `__getattr__` на рівні модуля повинна приймати один аргумент, який є назвою атрибута, і повертати обчислене значення або викликати `AttributeError`. Якщо атрибут не знайдено в об’єкті модуля за допомогою звичайного пошуку, тобто `object.__getattribute__()`, тоді `__getattr__` шукається в модулі `__dict__` перед тим, як викликати `AttributeError` . Якщо знайдено, воно викликається з назвою атрибута та повертає результат.

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__

Для більш точного налаштування поведінки модуля (встановлення атрибутів, властивостей тощо) можна встановити атрибут `__class__` об’єкта модуля до підкласу `types.ModuleType`. Наприклад:

    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

Примітка

Визначення модуля `__getattr__` і налаштування модуля `__class__` впливають лише на пошуки, зроблені за допомогою синтаксису доступу до атрибутів – прямий доступ до глобалів модуля (чи то за допомогою коду в модулі, чи через посилання на словник глобалів модуля) не впливає.

Змінено в версії 3.5: Атрибут модуля `__class__` тепер доступний для запису.

Added in version 3.7: Атрибути модуля `__getattr__` і `__dir__`.

Дивись також

PEP 562 - Модуль __getattr__ і __dir__

  Описує функції `__getattr__` і `__dir__` для модулів.

#### 3.3.2.2. Реалізація дескрипторів

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)

  Викликається, щоб отримати атрибут класу власника (доступ до атрибуту класу) або екземпляра цього класу (доступ до атрибуту екземпляра). Необов’язковий аргумент owner — це клас власника, тоді як instance — це екземпляр, через який був доступ до атрибута, або `None`, коли доступ до атрибута здійснюється через owner.

  Цей метод має повертати обчислене значення атрибута або викликати виняток `AttributeError`.

  PEP 252 вказує, що `__get__()` можна викликати за допомогою одного або двох аргументів. Власні вбудовані дескриптори Python підтримують цю специфікацію; проте ймовірно, що деякі інструменти сторонніх розробників мають дескриптори, які потребують обох аргументів. Власна реалізація `__getattribute__()` Python завжди передає обидва аргументи незалежно від того, потрібні вони чи ні.

object.__set__(self, instance, value)

  Викликається, щоб встановити атрибуту екземпляра екземпляру класу власника нове значення value.

  Зверніть увагу: додавання `__set__()` або `__delete__()` змінює тип дескриптора на «дескриптор даних». Перегляньте Виклик дескрипторів для отримання додаткової інформації.

object.__delete__(self, instance)

  Викликається для видалення атрибута екземпляра екземпляра класу власника.

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. Виклик дескрипторів

Загалом, дескриптор — це атрибут об’єкта з «зв’язуючою поведінкою», доступ до атрибутів якого перевизначено методами в протоколі дескриптора: `__get__()`, `__set__()` і `__delete__()`. Якщо будь-який із цих методів визначено для об’єкта, він називається дескриптором.

Поведінка за умовчанням для доступу до атрибутів полягає в отриманні, установці або видаленні атрибута зі словника об’єкта. Наприклад, `a.x` має ланцюжок пошуку, який починається з `a.__dict__['x']`, потім `type(a).__dict__['x']` і продовжується через базові класи типу `type(a)`, за винятком метакласів.

Проте, якщо шукане значення є об’єктом, що визначає один із методів дескриптора, тоді Python може замінити поведінку за замовчуванням і замість цього викликати метод дескриптора. Де це відбувається в ланцюжку пріоритетів, залежить від того, які методи дескриптора були визначені та як вони були викликані.

Початковою точкою для виклику дескриптора є прив’язка, `a.x`. Спосіб збирання аргументів залежить від `a`:

Прямий дзвінок

  Найпростіший і найменш поширений виклик — це коли код користувача безпосередньо викликає метод дескриптора: `x.__get__(a)`.

Прив’язка екземпляра

  У разі прив’язки до екземпляра об’єкта `a.x` перетворюється на виклик: `type(a).__dict__['x'].__get__(a, type(a))`.

Прив’язка класу

  Якщо прив’язується до класу, `A.x` перетворюється на виклик: `A.__dict__['x'].__get__(None, A)`.

Супер прив’язка

  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.

Функція `property()` реалізована як дескриптор даних. Відповідно, екземпляри не можуть перевизначати поведінку властивості.

#### 3.3.2.4. __slots__

__slots__ дозволяє нам явно оголошувати елементи даних (наприклад, властивості) і забороняти створення `__dict__` і __weakref__ (якщо це явно не оголошено в __slots__ або доступно в батьківському).

Місце, збережене за допомогою `__dict__` може бути значним. Швидкість пошуку атрибутів також можна значно покращити.

object.__slots__

  Цій змінній класу можна призначити рядок, ітерацію або послідовність рядків з іменами змінних, які використовуються екземплярами. __slots__ резервує місце для оголошених змінних і запобігає автоматичному створенню `__dict__` і __weakref__ для кожного екземпляра.

Notes on using __slots__:

- При успадкуванні від класу без __slots__ атрибути `__dict__` і __weakref__ екземплярів завжди будуть доступними.

- Без змінної `__dict__` екземплярам не можна призначати нові змінні, не вказані у визначенні __slots__. Спроби призначити змінній, яка не вказана в списку, викликають помилку `AttributeError`. Якщо потрібне динамічне призначення нових змінних, тоді додайте `'__dict__'` до послідовності рядків у декларації __slots__.

- Без змінної __weakref__ для кожного екземпляра класи, що визначають __slots__, не підтримують `слабкі посилання` на його екземпляри. Якщо необхідна підтримка слабких посилань, додайте `'__weakref__'` до послідовності рядків у декларації __slots__.

- __slots__ реалізуються на рівні класу шляхом створення дескрипторів для кожної назви змінної. Як результат, атрибути класу не можна використовувати для встановлення значень за замовчуванням для змінних екземплярів, визначених __slots__; інакше атрибут класу перезапише призначення дескриптора.

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

- Якщо клас визначає слот, також визначений у базовому класі, змінна екземпляра, визначена слотом базового класу, недоступна (за винятком отримання її дескриптора безпосередньо з базового класу). Це робить значення програми невизначеним. У майбутньому для запобігання цьому може бути додана перевірка.

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

- Будь-який нерядковий iterable може бути призначений __slots__.

- Якщо `dictionary` використовується для призначення __slots__, ключі словника будуть використані як імена слотів. Значення словника можна використовувати для надання рядків документів для кожного атрибута, які розпізнаються `inspect.getdoc()` і відображаються у виводі `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`.

- Якщо iterator використовується для __slots__, то descriptor створюється для кожного значення ітератора. Однак атрибут __slots__ буде порожнім ітератором.

Змінено в версії 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. Налаштування створення класу

Щоразу, коли клас успадковує інший клас, `__init_subclass__()` викликається в батьківському класі. Таким чином можна писати класи, які змінюють поведінку підкласів. Це тісно пов’язане з декораторами класів, але де декоратори класів впливають лише на конкретний клас, до якого вони застосовані, `__init_subclass__` застосовується виключно до майбутніх підкласів класу, що визначає метод.

classmethod object.__init_subclass__(cls)

  Цей метод викликається кожного разу, коли клас, що містить, є підкласом. Тоді cls є новим підкласом. Якщо визначено як звичайний метод екземпляра, цей метод неявно перетворюється на метод класу.

  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

  Реалізація за замовчуванням `object.__init_subclass__` нічого не робить, але викликає помилку, якщо вона викликається з будь-якими аргументами.

  Примітка

  Підказка метакласу `metaclass` споживається рештою механізму типів і ніколи не передається реалізаціям `__init_subclass__`. Фактичний метаклас (а не явна підказка) можна отримати як `type(cls)`.

  Added in version 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)

  Автоматично викликається під час створення класу власника owner. Об’єкту було призначено name у цьому класі:

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

  Якщо змінна класу призначається після створення класу, `__set_name__()` не буде викликатися автоматично. За потреби `__set_name__()` можна викликати безпосередньо:

      class A:
         pass

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

  Дивіться Створення об’єкта класу для отримання додаткової інформації.

  Added in version 3.6.

#### 3.3.3.1. Метакласи

За замовчуванням класи створюються за допомогою `type()`. Тіло класу виконується в новому просторі імен, а ім’я класу прив’язується локально до результату `type(name, bases, namespace)`.

Процес створення класу можна налаштувати, передавши аргумент ключового слова `metaclass` у рядку визначення класу або успадкувавши від існуючого класу, який містив такий аргумент. У наступному прикладі і `MyClass`, і `MySubclass` є екземплярами `Meta`:

    class Meta(type):
        pass

    class MyClass(metaclass=Meta):
        pass

    class MySubclass(MyClass):
        pass

Будь-які інші ключові аргументи, указані у визначенні класу, передаються до всіх операцій метакласу, описаних нижче.

Коли виконується визначення класу, відбуваються наступні кроки:

- Записи MRO вирішено;

- визначається відповідний метаклас;

- підготовлено простір імен класу;

- виконується тіло класу;

- створюється об’єкт класу.

#### 3.3.3.2. Вирішення записів MRO

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. Визначення відповідного метакласу

Відповідний метаклас для визначення класу визначається таким чином:

- якщо не вказано жодних баз і явного метакласу, то використовується `type()`;

- якщо задано явний метаклас і він не є екземпляром `type()`, тоді він використовується безпосередньо як метаклас;

- якщо екземпляр `type()` задано як явний метаклас або визначено основи, то використовується найбільш похідний метаклас.

Найбільш похідний метаклас вибирається з явно визначеного метакласу (якщо такий є) і метакласів (тобто `type(cls)`) усіх указаних базових класів. Найбільш похідним метакласом є той, який є підтипом усіх цих метакласів-кандидатів. Якщо жоден із метакласів-кандидатів не відповідає цьому критерію, визначення класу буде невдалим із `TypeError`.

#### 3.3.3.4. Підготовка простору імен класу

Після визначення відповідного метакласу готується простір імен класу. Якщо метаклас має атрибут `__prepare__`, він викликається як `namespace = metaclass.__prepare__(name, bases, **kwds)` (де додаткові ключові аргументи, якщо такі є, надходять із визначення класу) . Метод `__prepare__` має бути реалізований як `classmethod`. Простір імен, повернутий `__prepare__`, передається в `__new__`, але коли створюється останній об’єкт класу, простір імен копіюється в новий `dict`.

Якщо метаклас не має атрибута `__prepare__`, тоді простір імен класу ініціалізується як порожнє впорядковане відображення.

Дивись також

PEP 3115 - Метакласи в Python 3000

  Представлено хук простору імен `__prepare__`

#### 3.3.3.5. Виконання тіла класу

Тіло класу виконується (приблизно) як `exec(body, globals(), namespace)`. Ключова відмінність від звичайного виклику `exec()` полягає в тому, що лексична область видимості дозволяє тілу класу (включаючи будь-які методи) посилатися на імена з поточної та зовнішньої областей, коли визначення класу відбувається всередині функції.

Однак, навіть коли визначення класу відбувається всередині функції, методи, визначені всередині класу, все одно не можуть бачити імена, визначені в області класу. Доступ до змінних класу має здійснюватися через перший параметр екземпляра або методів класу, або через неявне посилання `__class__` з лексичною областю, описане в наступному розділі.

#### 3.3.3.6. Створення об’єкта класу

Коли простір імен класу заповнено виконанням тіла класу, об’єкт класу створюється шляхом виклику `metaclass(name, bases, namespace, **kwds)` (додаткові ключові слова, передані тут, такі самі, як ті, що передані `__prepare__`).

Цей об’єкт класу є тим, на який посилатиметься форма `super()` з нульовим аргументом. `__class__` — це неявне посилання на закриття, створене компілятором, якщо будь-які методи в тілі класу посилаються на `__class__` або `super`. Це дозволяє формі нульового аргументу `super()` правильно ідентифікувати клас, який визначається на основі лексичного визначення, тоді як клас або екземпляр, який використовувався для здійснення поточного виклику, ідентифікується на основі першого аргументу, переданого методу.

У CPython 3.6 і пізніших версіях клітинка `__class__` передається метакласу як запис `__classcell__` у просторі імен класу. Якщо є, це має бути передано до виклику `type.__new__` для правильної ініціалізації класу. Якщо цього не зробити, у Python 3.8 виникне `RuntimeError`.

При використанні метакласу за замовчуванням `type` або будь-якого метакласу, який остаточно викликає `type.__new__`, наступні додаткові кроки налаштування викликаються після створення об’єкта класу:

1. Метод `type.__new__` збирає всі атрибути в просторі імен класу, які визначають метод `__set_name__()`;

2. Ці методи `__set_name__` викликаються з визначеним класом і присвоєною назвою цього конкретного атрибута;

3. Хук `__init_subclass__()` викликається на безпосередньому батькові нового класу в порядку вирішення методів.

Після того, як об’єкт класу створено, він передається до декораторів класу, включених у визначення класу (якщо такі є), і отриманий об’єкт зв’язується в локальному просторі імен як визначений клас.

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 - Новий супер

  Описує неявне посилання на закриття `__class__`

#### 3.3.3.7. Використання для метакласів

Можливості використання метакласів безмежні. Деякі ідеї, які були досліджені, включають enum, журналювання, перевірку інтерфейсу, автоматичне делегування, автоматичне створення властивостей, проксі, фреймворки та автоматичне блокування/синхронізацію ресурсів.

### 3.3.4. Налаштування перевірок екземплярів і підкласів

Наступні методи використовуються для заміни типової поведінки вбудованих функцій `isinstance()` і `issubclass()`.

Зокрема, метаклас `abc.ABCMeta` реалізує ці методи, щоб дозволити додавання абстрактних базових класів (ABC) як «віртуальних базових класів» до будь-якого класу або типу (включно з вбудованими типами), включаючи інші Азбука.

type.__instancecheck__(self, instance)

  Повертає true, якщо екземпляр слід вважати (прямим чи непрямим) екземпляром класу. Якщо визначено, викликається для реалізації `isinstance(instance, class)`.

type.__subclasscheck__(self, subclass)

  Повертає true, якщо підклас слід вважати (прямим чи непрямим) підкласом класу. Якщо визначено, викликається для реалізації `issubclass(subclass, class)`.

Зауважте, що ці методи шукаються за типом (метакласом) класу. Вони не можуть бути визначені як методи класу в реальному класі. Це узгоджується з пошуком спеціальних методів, які викликаються для екземплярів, тільки в цьому випадку екземпляр сам по собі є класом.

Дивись також

PEP 3119 - Представляємо абстрактні базові класи

  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. Емуляція загальних типів

Використовуючи анотації типу, часто корисно параметризувати загальний тип (generic type) за допомогою нотації Python у квадратних дужках. Наприклад, анотацію `list[int]` можна використовувати для позначення `list`, у якому всі елементи мають тип `int`.

Дивись також

PEP 484 - підказки типу

  Представляємо структуру Python для анотацій типів

Загальні типи псевдонімів

  Документація для об’єктів, що представляють параметризовані загальні класи

Узагальнення, визначені користувачем узагальнення і `typing.Generic`

  Документація про те, як реалізувати загальні класи, які можна параметризувати під час виконання та розуміти статичними засобами перевірки типів.

Зазвичай клас може бути параметризований, лише якщо він визначає спеціальний метод класу `__class_getitem__()`.

classmethod object.__class_getitem__(cls, key)

  Повертає об’єкт, який представляє спеціалізацію загального класу за аргументами типу, знайденими в 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. Мета __class_getitem__

Метою `__class_getitem__()` є можливість параметризації загальних класів стандартної бібліотеки під час виконання, щоб легше застосовувати підказки типу до цих класів.

Щоб реалізувати користувальницькі загальні класи, які можна параметризувати під час виконання та розуміти статичними засобами перевірки типів, користувачі повинні або успадкувати від класу стандартної бібліотеки, яка вже реалізує `__class_getitem__()`, або успадкувати від `typing. Generic`, який має власну реалізацію `__class_getitem__()`.

Спеціальні реалізації `__class_getitem__()` у класах, визначених за межами стандартної бібліотеки, можуть бути не зрозумілі сторонніми засобами перевірки типів, такими як mypy. Не рекомендується використовувати `__class_getitem__()` для будь-якого класу для цілей, відмінних від підказки типу.

#### 3.3.5.2. __class_getitem__ проти __getitem__

Зазвичай підписка об’єкта з використанням квадратних дужок викликає метод екземпляра `__getitem__()`, визначений у класі об’єкта. Проте, якщо об’єкт, на який підписується, сам є класом, замість нього можна викликати метод класу `__class_getitem__()`. `__class_getitem__()` має повертати об’єкт GenericAlias, якщо він правильно визначений.

Представлений у вигляді expression `obj[x]`, інтерпретатор Python виконує щось на зразок наступного процесу, щоб вирішити, чи слід `__getitem__()` або `__class_getitem__()` бути викликаним:

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

У Python усі класи самі є екземплярами інших класів. Клас класу відомий як metaclass цього класу, і більшість класів мають клас `type` як метаклас. `type` не визначає `__getitem__()`, тобто такі вирази, як `list[int]`, `dict[str, float]` і `tuple[str, bytes]` все призводить до виклику `__class_getitem__()`:

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

Однак, якщо клас має спеціальний метаклас, який визначає `__getitem__()`, підписка на клас може призвести до іншої поведінки. Приклад цього можна знайти в модулі `enum`:

    >>> 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 - Основна підтримка модуля введення тексту та загальних типів

  Представляємо `__class_getitem__()` і пояснюємо, коли підписка призводить до виклику `__class_getitem__()` замість `__getitem__()`

### 3.3.6. Емуляція викликаних об’єктів

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. Емуляція типів контейнерів

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.

  Added in version 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

  перекладається на

      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__ проти __getitem__ for more details.

object.__setitem__(self, key, value)

  Викликається для реалізації призначення `self[key]`. Така сама примітка, як і для `__getitem__()`. Це має бути реалізовано лише для відображень, якщо об’єкти підтримують зміни значень для ключів, або якщо можна додати нові ключі, або для послідовностей, якщо елементи можна замінити. Для неправильних значень key мають бути викликані ті самі винятки, що й для методу `__getitem__()`.

object.__delitem__(self, key)

  Викликається для реалізації видалення `self[key]`. Така сама примітка, як і для `__getitem__()`. Це слід застосовувати лише для відображень, якщо об’єкти підтримують видалення ключів, або для послідовностей, якщо елементи можна видалити з послідовності. Для неправильних значень key мають бути викликані ті самі винятки, що й для методу `__getitem__()`.

object.__missing__(self, key)

  Викликається `dict`.`__getitem__()` для реалізації `self[key]` для підкласів dict, коли ключа немає в словнику.

object.__iter__(self)

  Цей метод викликається, коли для контейнера потрібен iterator. Цей метод має повертати новий об’єкт-ітератор, який може виконувати ітерацію по всіх об’єктах у контейнері. Для зіставлення він повинен перебирати ключі контейнера.

object.__reversed__(self)

  Викликається (якщо є) вбудованим `reversed()` для реалізації зворотної ітерації. Він має повернути новий об’єкт-ітератор, який обходить усі об’єкти в контейнері у зворотному порядку.

  Якщо метод `__reversed__()` не надано, вбудований `reversed()` повернеться до використання протоколу послідовності (`__len__()` і `__getitem__()`). Об’єкти, які підтримують протокол послідовності, повинні надавати лише `__reversed__()`, якщо вони можуть забезпечити ефективнішу реалізацію, ніж та, яку надає `reversed()`.

Оператори перевірки членства (`in` і `not in`) зазвичай реалізуються як ітерація через контейнер. Однак об’єкти-контейнери можуть надавати наступний спеціальний метод з більш ефективною реалізацією, яка також не вимагає, щоб об’єкт був повторюваним.

object.__contains__(self, item)

  Викликано реалізувати оператори перевірки членства. Має повертати true, якщо item знаходиться в self, і false в іншому випадку. Для відображення об’єктів це має враховувати ключі відображення, а не значення або пари ключ-елемент.

  Для об’єктів, які не визначають `__contains__()`, тест на приналежність спочатку намагається виконати ітерацію через `__iter__()`, потім старий протокол ітерації послідовності через `__getitem__()`, див. цей розділ у посилання на мову.

### 3.3.8. Емуляція числових типів

Наступні методи можна визначити для емуляції числових об’єктів. Методи, що відповідають операціям, які не підтримуються конкретним видом реалізованого числа (наприклад, побітові операції для нецілісних чисел), слід залишити невизначеними.

object.__add__(self, other)
object.__sub__(self, other)
object.__mul__(self, other)
object.__matmul__(self, other)
object.__truediv__(self, other)
object.__floordiv__(self, other)
object.__mod__(self, other)
object.__divmod__(self, other)
object.__pow__(self, other[, modulo])
object.__lshift__(self, other)
object.__rshift__(self, other)
object.__and__(self, other)
object.__xor__(self, other)
object.__or__(self, other)

  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.

  Примітка

  Якщо тип правого операнда є підкласом типу лівого операнда і цей підклас забезпечує іншу реалізацію відображеного методу для операції, цей метод буде викликаний перед невідображеним методом лівого операнда. Така поведінка дозволяє підкласам перевизначати операції своїх предків.

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 Чому a_tuple[i] += [„item“] викликає виключення, коли додавання працює?), but this behavior is in fact part of the data model.

object.__neg__(self)
object.__pos__(self)
object.__abs__(self)
object.__invert__(self)

  Викликається для реалізації унарних арифметичних операцій (`-`, `+`, `abs()` і `~`).

object.__complex__(self)
object.__int__(self)
object.__float__(self)

  Викликається для реалізації вбудованих функцій `complex()`, `int()` і `float()`. Має повертати значення відповідного типу.

object.__index__(self)

  Викликається для реалізації `operator.index()` і кожного разу, коли Python потребує без втрат перетворити числовий об’єкт у цілочисельний об’єкт (наприклад, у зрізі або у вбудованих `bin()`, `hex()` і `oct()`). Наявність цього методу вказує на те, що числовий об’єкт є цілим типом. Має повертати ціле число.

  Якщо `__int__()`, `__float__()` і `__complex__()` не визначено, то відповідні вбудовані функції `int()`, `float()` і `complex()` повернутися до `__index__()`.

object.__round__(self[, ndigits])
object.__trunc__(self)
object.__floor__(self)
object.__ceil__(self)

  Викликається для реалізації вбудованої функції `round()` і `math` функції `trunc()`, `floor()` і `ceil()`. Якщо ndigits не передано в `__round__()`, усі ці методи повинні повертати значення об’єкта, усічене до `Integral` (зазвичай `int`).

  Змінено в версії 3.14: `int()` no longer delegates to the `__trunc__()` method.

### 3.3.9. З менеджерами контексту операторів

context manager — це об’єкт, який визначає контекст виконання, який буде встановлено під час виконання оператора `with`. Менеджер контексту керує входом і виходом з потрібного контексту виконання для виконання блоку коду. Менеджери контексту зазвичай викликаються за допомогою оператора `with` (описаного в розділі Оператор with), але їх також можна використовувати шляхом безпосереднього виклику їхніх методів.

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

For more information on context managers, see Типи менеджера контексту. The `object` class itself does not provide the context manager methods.

object.__enter__(self)

  Введіть контекст виконання, пов’язаний із цим об’єктом. Оператор `with` прив’яже значення, що повертається цим методом, до цілей(ів), указаних у пункті `as` оператора, якщо такий є.

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

  Вийти з контексту виконання, пов’язаного з цим об’єктом. Параметри описують виняток, який спричинив вихід із контексту. Якщо контекст вийшов без винятку, усі три аргументи будуть `None`.

  Якщо надається виняток, і метод хоче придушити виняток (тобто запобігти його розповсюдженню), він повинен повернути істинне значення. В іншому випадку виняток буде оброблено звичайним чином після виходу з цього методу.

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

Дивись також

PEP 343 - оператор «з».

  Специфікація, передумови та приклади оператора Python `with`.

### 3.3.10. Налаштування позиційних аргументів у відповідності шаблону класу

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__

  Цій змінній класу можна призначити кортеж рядків. Коли цей клас використовується в шаблоні класу з позиційними аргументами, кожен позиційний аргумент буде перетворено в аргумент ключового слова, використовуючи відповідне значення в __match_args__ як ключове слово. Відсутність цього атрибута еквівалентна встановленню для нього значення `()`.

Наприклад, якщо `MyClass.__match_args__` є `("left", "center", "right")`, це означає, що `case MyClass(x, y)` еквівалентний `case MyClass (ліворуч=x, центр=y)`. Зверніть увагу, що кількість аргументів у шаблоні має бути меншою або дорівнювати кількості елементів у __match_args__; якщо він більший, спроба збігу шаблону викличе `TypeError`.

Added in version 3.10.

Дивись також

PEP 634 - зіставлення структурних шаблонів

  Специфікація оператора `match` Python.

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

Added in version 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.

  Added in version 3.14.

Дивись також

PEP 649 — Deferred evaluation of annotation using descriptors

  Introduces lazy evaluation of annotations and the `__annotate__` function.

### 3.3.13. Спеціальний метод пошуку

Для користувальницьких класів неявні виклики спеціальних методів гарантовано працюють правильно, лише якщо вони визначені для типу об’єкта, а не в словнику екземплярів об’єкта. Така поведінка є причиною того, що наступний код викликає виняток:

    >>> class C:
    ...     pass
    ...
    >>> c = C()
    >>> c.__len__ = lambda: 5
    >>> len(c)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: object of type 'C' has no len()

Обґрунтування такої поведінки полягає в ряді спеціальних методів, таких як `__hash__()` і `__repr__()`, які реалізуються всіма об’єктами, включаючи об’єкти типу. Якби неявний пошук цих методів використовував звичайний процес пошуку, вони зазнали б помилки під час виклику в самому об’єкті типу:

    >>> 1 .__hash__() == hash(1)
    True
    >>> int.__hash__() == hash(int)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: descriptor '__hash__' of 'int' object needs an argument

Неправильна спроба викликати незв’язаний метод класу таким чином іноді називається «плутаниною метакласу», і її можна уникнути шляхом обходу екземпляра під час пошуку спеціальних методів:

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

Окрім обходу будь-яких атрибутів екземпляра в інтересах коректності, неявний пошук спеціального методу зазвичай також обходить метод `__getattribute__()` навіть метакласу об’єкта:

    >>> class Meta(type):
    ...     def __getattribute__(*args):
    ...         print("Metaclass getattribute invoked")
    ...         return type.__getattribute__(*args)
    ...
    >>> class C(object, metaclass=Meta):
    ...     def __len__(self):
    ...         return 10
    ...     def __getattribute__(*args):
    ...         print("Class getattribute invoked")
    ...         return object.__getattribute__(*args)
    ...
    >>> c = C()
    >>> c.__len__()                 # Explicit lookup via instance
    Class getattribute invoked
    10
    >>> type(c).__len__(c)          # Explicit lookup via type
    Metaclass getattribute invoked
    10
    >>> len(c)                      # Implicit lookup
    10

Обхід механізму `__getattribute__()` у такий спосіб забезпечує значні можливості для оптимізації швидкості в інтерпретаторі за рахунок певної гнучкості в обробці спеціальних методів (спеціальний метод має бути встановлений на об’єкті класу сам для того, щоб бути послідовно викликаним інтерпретатором).

## 3.4. Співпрограми

### 3.4.1. Очікувані об’єкти

Об’єкт awaitable зазвичай реалізує метод `__await__()`. Очікуються об’єкти співпрограми, повернуті функціями `async def`.

Примітка

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.

Added in version 3.5.

Дивись також

PEP 492 для додаткової інформації про очікувані об’єкти.

### 3.4.2. Об’єкти співпрограми

Об’єкти співпрограми є awaitable об’єктами. Виконання співпрограми можна контролювати викликом `__await__()` і повторенням результату. Коли співпрограма завершує виконання та повертається, ітератор викликає `StopIteration`, а атрибут винятку `value` зберігає значення, що повертається. Якщо співпрограма викликає виключення, воно поширюється ітератором. Співпрограми не повинні безпосередньо викликати необроблені винятки `StopIteration`.

Співпрограми також мають наведені нижче методи, аналогічні генераторам (див. Методи генератор-ітератор). Однак, на відміну від генераторів, співпрограми безпосередньо не підтримують ітерацію.

Змінено в версії 3.5.2: Це `RuntimeError`, якщо очікувати в співпрограмі більше одного разу.

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

  Викликає вказаний виняток у співпрограмі. Цей метод делегує метод `throw()` ітератора, який викликав призупинення співпрограми, якщо він має такий метод. В іншому випадку виняток виникає в точці призупинення. Результат (повернене значення, `StopIteration` або інший виняток) такий самий, як і під час ітерації по поверненому значенню `__await__()`, описаному вище. Якщо виняток не перехоплюється співпрограмою, він поширюється назад до абонента.

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

coroutine.close()

  Примушує співпрограму самоочиститися та завершити роботу. Якщо співпрограму призупинено, цей метод спочатку делегує метод `close()` ітератора, який викликав призупинення співпрограми, якщо він має такий метод. Потім він викликає `GeneratorExit` у точці призупинення, змушуючи співпрограму негайно очищатися. Нарешті, співпрограма позначається як завершена, навіть якщо вона ніколи не запускалася.

  Об’єкти співпрограми автоматично закриваються за допомогою описаного вище процесу, коли їх збираються знищити.

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

Асинхронний ітератор може викликати асинхронний код у своєму методі `__anext__`.

Асинхронні ітератори можна використовувати в операторі `async for`.

The `object` class itself does not provide these methods.

object.__aiter__(self)

  Має повертати об’єкт асинхронного ітератора.

object.__anext__(self)

  Має повернути waitable, що призводить до наступного значення ітератора. Має викликати помилку `StopAsyncIteration` після завершення ітерації.

Приклад асинхронного ітерованого об’єкта:

    class Reader:
        async def readline(self):
            ...

        def __aiter__(self):
            return self

        async def __anext__(self):
            val = await self.readline()
            if val == b'':
                raise StopAsyncIteration
            return val

Added in version 3.5.

Змінено в версії 3.7: До Python 3.7 `__aiter__()` міг повертати waitable, який перетворювався на асинхронний ітератор.

Починаючи з Python 3.7, `__aiter__()` має повертати об’єкт асинхронного ітератора. Повернення чогось іншого призведе до помилки `TypeError`.

### 3.4.4. Менеджери асинхронного контексту

Асинхронний контекстний менеджер — це контекстний менеджер, який може призупинити виконання своїх методів `__aenter__` і `__aexit__`.

Асинхронні менеджери контексту можна використовувати в операторі `async with`.

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.

Приклад класу диспетчера асинхронного контексту:

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

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

Added in version 3.5.

Виноски

[1]

У деяких випадках можливо змінити тип об’єкта за певних контрольованих умов. Загалом це не дуже гарна ідея, оскільки це може призвести до дуже дивної поведінки, якщо з ним поводитись неправильно.

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