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

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

Об’єкти — це абстракція Python для даних. Усі дані в програмі Python представлені об’єктами або зв’язками між об’єктами. (У певному сенсі та відповідно до моделі фон Неймана «комп’ютера зі збереженою програмою» код також представлений об’єктами.)

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: Для CPython id(x) — це адреса пам’яті, де зберігається x.

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

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

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

Деталі реалізації CPython: Наразі 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. E.g., 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, but after c = []; d = [], c and d are guaranteed to refer to two different, unique, newly created empty lists. (Note that c = d = [] assigns the same object to both c and d.)

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 is deprecated. While it currently evaluates as true, it will emit a DeprecationWarning. It will raise a TypeError in a future version of Python.

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.

Sequences also support slicing: a[i:j] selects all items with index k such that i <= k < j. When used as an expression, a slice is a sequence of the same type. The comment above about negative indexes also applies to negative slice positions.

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

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

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

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

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

рядки

A string is a sequence of values that represent Unicode code points. All the code points in the range U+0000 - U+10FFFF can be represented in a string. Python doesn’t have a char 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 - 10FFFF; chr() converts an integer in the range 0 - 10FFFF 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.

Кортежі

Елементи кортежу є довільними об’єктами Python. Кортежі з двох або більше елементів утворюються списками виразів, розділених комами. Кортеж з одного елемента («синглтон») може бути сформований шляхом додавання коми до виразу (вираз сам по собі не створює кортеж, оскільки дужки повинні використовуватися для групування виразів). Порожній кортеж може бути утворений пустою парою круглих дужок.

Байти

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.__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 function’s free variables. Об’єкт клітинки має атрибут 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. Not inherited by subclasses.
function.__name__	The function’s name. See also: __name__ attributes.
function.__qualname__	The function’s qualified name. See also: __qualname__ attributes. Нове в версії 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: Рекомендації щодо анотацій.
function.__kwdefaults__	A dictionary containing defaults for keyword-only parameters.

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.

Note that the transformation from function object to instance method object happens each time the attribute is retrieved from the instance. In some cases, a fruitful optimization is to assign the attribute to a local variable and call that local variable. Also notice that this transformation only happens for user-defined functions; other callable objects (and all non-callable objects) are retrieved without transformation. It is also 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.

Попередньо визначені (записувані) атрибути:

__name__

Назва модуля.

__doc__

Рядок документації модуля або None, якщо він недоступний.

__file__

Шлях до файлу, з якого було завантажено модуль, якщо він був завантажений із файлу. Атрибут __file__ може бути відсутнім для певних типів модулів, таких як модулі C, які статично пов’язані з інтерпретатором. Для модулів розширення, які динамічно завантажуються зі спільної бібліотеки, це шлях до файлу спільної бібліотеки.

__annotations__

Словник, що містить анотації змінних, зібрані під час виконання тіла модуля. Найкращі методи роботи з __annotations__ див. Рекомендації щодо анотацій.

Спеціальний атрибут лише для читання: __dict__ — це простір імен модуля як об’єкт словника.

Деталі реалізації CPython: Через те, як 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 in the documentation accompanying the 2.3 release at https://www.python.org/download/releases/2.3/mro/.

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

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

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

Особливі атрибути:

__name__

Назва класу.

__module__

Ім’я модуля, в якому було визначено клас.

__dict__

Словник, що містить простір імен класу.

__bases__

Кортеж, що містить базові класи в порядку їх появи в списку базових класів.

__doc__

Рядок документації класу або None, якщо не визначено.

__annotations__

Словник, що містить анотації змінних, зібрані під час виконання тіла класу. Найкращі методи роботи з __annotations__ див. Рекомендації щодо анотацій.

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

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

Спеціальні атрибути: __dict__ — це словник атрибутів; __class__ є класом екземпляра.

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

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

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

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 Нове в версії 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 by nested functions inside the function
codeobject.co_freevars	A tuple containing the names of free variables in the function
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_lnotab	A string encoding the mapping from bytecode offsets to line numbers. For details, see the source code of the interpreter.
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 (from __future__ import division) also use bits in co_flags to indicate whether a code object was compiled with a particular feature enabled: bit 0x2000 is set if the function was compiled with future division enabled; bits 0x10 and 0x1000 were used in earlier versions of Python.

Other bits in co_flags are reserved for internal use.

If a code object represents a function, the first item in co_consts is the documentation string of the function, or None if undefined.

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

Нове в версії 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 tuples, 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.

Нове в версії 3.10.

Дивись також

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

The PEP that introduced the co_lines() method.

codeobject.replace(**kwargs)

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

Нове в версії 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 dictionary used by the frame to look up local variables
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)

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.

Нове в версії 3.4.

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

Спеціальні атрибути лише для читання: 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]

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

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.

Примітка

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__() також використовується, коли потрібне «неформальне» рядкове представлення екземплярів цього класу.

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

object.__str__(self)

Викликається str(object) і вбудованими функціями format() і print() для обчислення «неформального» або зручного для друку рядкового представлення об’єкта. Повернене значення має бути об’єктом string.

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

Стандартна реалізація, визначена вбудованим типом object, викликає object.__repr__().

object.__bytes__(self)

Викликається bytes для обчислення байтового представлення об’єкта. Це має повернути об’єкт bytes.

object.__format__(self, format_spec)

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

Перегляньте Міні-мова специфікації формату для опису стандартного синтаксису форматування.

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

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

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

object.__lt__(self, other)

object.__le__(self, other)

object.__eq__(self, other)

object.__ne__(self, other)

object.__gt__(self, other)

object.__ge__(self, other)

Це так звані методи «багатого порівняння». Відповідність між символами оператора та назвами методів така: x <y 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().

Перегляньте параграф про __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).

Визначені користувачем класи за замовчуванням мають методи __eq__() і __hash__(); з ними всі об’єкти порівнюються нерівно (крім самих себе), і x.__hash__() повертає відповідне значення, так що x == y означає, що x є y і hash (x) == хеш(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(n²) complexity. See http://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__(), all its instances are considered true.

3.3.2. Налаштування доступу до атрибутів

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

object.__getattr__(self, name)

Викликається, коли доступ до атрибута за замовчуванням не вдається через AttributeError (будь-який __getattribute__() викликає AttributeError, оскільки name не є атрибутом екземпляра або атрибутом у дереві класів для self; або __get__() властивості name викликає AttributeError). Цей метод має повертати (обчислене) значення атрибута або викликати виняток AttributeError.

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

Спеціальні імена __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.

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

Нове в версії 3.7: Атрибути модуля __getattr__ і __dir__.

Дивись також

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

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

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

Наступні методи застосовуються лише тоді, коли екземпляр класу, що містить метод (так званий клас descriptor), з’являється в класі owner (дескриптор має бути або в словнику класу власника, або в словнику класу для одного з його батьки). У наведених нижче прикладах «атрибут» відноситься до атрибута, ім’я якого є ключем властивості в класі власника __dict__.

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 (включаючи ті, що прикрашені @staticmethod і @classmethod) реалізовані як дескриптори не даних. Відповідно, екземпляри можуть перевизначати та замінювати методи. Це дозволяє окремим примірникам набувати поведінки, яка відрізняється від інших примірників того самого класу.

Функція 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__; інакше атрибут класу перезапише призначення дескриптора.

• Дія оголошення __slots__ не обмежується класом, де воно визначено. __slots__, оголошені в батьківських класах, доступні в дочірніх класах. Однак дочірні підкласи отримають __dict__ і __weakref__, якщо вони також не визначають __slots__ (які мають містити лише назви будь-яких додаткових слотів).

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

• TypeError will be raised if nonempty __slots__ are defined for a class derived from a "variable-length" built-in type such as int, bytes, and tuple.

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

• Якщо dictionary використовується для призначення __slots__, ключі словника будуть використані як імена слотів. Значення словника можна використовувати для надання рядків документів для кожного атрибута, які розпізнаються inspect.getdoc() і відображаються у виводі help().

• __class__ призначення працює, лише якщо обидва класи мають однакові __slots__.

• Множинне успадкування з кількома батьківськими класами зі слотами можна використовувати, але лише одному з батьківських класів дозволено мати атрибути, створені слотами (інші бази повинні мати порожні макети слотів) - порушення викликають TypeError.

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

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

Нове в версії 3.6.

Коли клас створюється, type.__new__() сканує змінні класу та виконує зворотні виклики до тих, що мають хук __set_name__().

object.__set_name__(self, owner, name)

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

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

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

class A:
   pass

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

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

Нове в версії 3.6.

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.

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: У 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__() викликається на безпосередньому батькові нового класу в порядку вирішення методів.

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

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

Дивись також

PEP 3135 - Новий супер

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

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

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

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

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

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

class.__instancecheck__(self, instance)

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

class.__subclasscheck__(self, subclass)

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

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

Дивись також

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

Включає специфікацію для налаштування поведінки isinstance() і issubclass() через __instancecheck__() і __subclasscheck__() з мотивацією для цієї функції в контексті додавання Абстрактні базові класи (див. модуль abc) до мови.

3.3.5. Емуляція загальних типів

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

Дивись також

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

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

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

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

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

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

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

classmethod object.__class_getitem__(cls, key)

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

Коли визначено в класі, __class_getitem__() автоматично стає методом класу. Таким чином, немає необхідності прикрашати його @classmethod, коли він визначений.

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

Викликається, коли екземпляр «викликається» як функція; якщо цей метод визначено, x(arg1, arg2, ...) приблизно перекладається як type(x).__call__(x, arg1, ...).

3.3.7. Емуляція типів контейнерів

The following methods can be defined to implement container objects. 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(), count(), index(), extend(), insert(), pop(), remove(), reverse() and sort(), like Python standard list objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() and __imul__() described below; they should not define other numerical operators. It is recommended that both mappings and sequences implement the __contains__() method to allow efficient use of the in operator; for mappings, in should search the mapping’s keys; for sequences, it should search through the values. It is further recommended that both mappings and sequences implement the __iter__() method to allow efficient iteration through the container; for mappings, __iter__() should iterate through the object’s keys; for sequences, it should iterate through the values.

object.__len__(self)

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

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

object.__length_hint__(self)

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

Нове в версії 3.4.

Примітка

Нарізка виконується виключно трьома способами. Дзвінок типу

a[1:2] = b

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

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

і так далі. Відсутні елементи фрагмента завжди заповнюються None.

object.__getitem__(self, key)

Called to implement evaluation of self[key]. For sequence types, the accepted keys should be integers. Optionally, they may support slice objects as well. Negative index support is also optional. If key is of an inappropriate type, TypeError may be raised; if key is a value outside the set of indexes for the sequence (after any special interpretation of negative values), IndexError should be raised. For mapping types, if key is missing (not in the container), KeyError should be raised.

Примітка

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

Примітка

Коли індексує клас, спеціальний метод класу __class_getitem__() може викликатися замість __getitem__(). Перегляньте __class_getitem__ проти __getitem__ для отримання додаткової інформації.

object.__setitem__(self, key, value)

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

object.__delitem__(self, key)

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

object.__missing__(self, key)

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

object.__iter__(self)

Цей метод викликається, коли для контейнера потрібен 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 ternary 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 left operand does not support the corresponding operation [3] and the operands are of different types. [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.

Зауважте, що тернарний pow() не намагатиметься викликати __rpow__() (правила примусу стануть надто складними).

Примітка

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

object.__iadd__(self, other)

object.__isub__(self, other)

object.__imul__(self, other)

object.__imatmul__(self, other)

object.__itruediv__(self, other)

object.__ifloordiv__(self, other)

object.__imod__(self, other)

object.__ipow__(self, other[, modulo])

object.__ilshift__(self, other)

object.__irshift__(self, other)

object.__iand__(self, other)

object.__ixor__(self, other)

object.__ior__(self, other)

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

Вбудована функція int() повертається до __trunc__(), якщо не визначено ні __int__(), ні __index__().

Змінено в версії 3.11: The delegation of int() to __trunc__() is deprecated.

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

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

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

Для отримання додаткової інформації про контекстні менеджери див. Типи менеджера контексту.

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.

Нове в версії 3.10.

Дивись також

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

Має повертати iterator. Слід використовувати для реалізації об’єктів awaitable. Наприклад, asyncio.Future реалізує цей метод для сумісності з виразом await.

Примітка

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

Нове в версії 3.5.

Дивись також

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

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__(), описаному вище. Якщо виняток не перехоплюється співпрограмою, він поширюється назад до абонента.

coroutine.close()

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

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

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

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

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

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

Нове в версії 3.5.

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

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

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

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

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

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

Нове в версії 3.5.

Виноски

[1]

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

[2]

The __hash__(), __iter__(), __reversed__(), and __contains__() 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]

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