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

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

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

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

CPython implementation detail: Наразі 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 можуть додавати типи до ієрархії типів (наприклад, раціональні числа, ефективно збережені масиви цілих чисел тощо), хоча такі доповнення часто надаватимуться через стандартну бібліотеку.

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

Жодного

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

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

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.) Its truth value is true.

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

Еліпсис

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

numbers.Number

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

The string representations of the numeric classes, computed by __repr__() and __str__(), have the following properties:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.

Послідовності

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

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. This implies that the index set is renumbered so that it starts at 0.

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

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

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

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

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

рядки

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.

Змінні послідовності

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

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

списки

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

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

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

The extension module array provides an additional example of a mutable sequence type, as does the collections module.

Встановити типи

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

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

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

Набори

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

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

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

Відображення

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

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

словники

Вони представляють кінцеві набори об’єктів, індексованих майже довільними значеннями. Єдиними типами значень, неприйнятними як ключі, є значення, що містять списки, словники чи інші змінні типи, які порівнюються за значенням, а не за ідентичністю об’єкта, тому що для ефективної реалізації словників необхідно, щоб хеш-значення ключа залишалося постійним. Числові типи, що використовуються для ключів, підкоряються звичайним правилам для числового порівняння: якщо два числа порівнюються (наприклад, 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 порядок вставки було збережено, але в той час це вважалося деталлю реалізації, а не гарантією мови.

Викличні типи

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

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

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

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

Атрибут	Значення
__doc__	The function’s documentation string, or None if unavailable; not inherited by subclasses.	Writable
__name__	The function’s name.	Writable
__qualname__	The function’s qualified name. Нове в версії 3.3.	Writable
__module__	Назва модуля, у якому була визначена функція, або «Немає», якщо вона недоступна.	Writable
__defaults__	A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value.	Writable
__code__	The code object representing the compiled function body.	Writable
__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.	Read-only
__dict__	The namespace supporting arbitrary function attributes.	Writable
__closure__	None or a tuple of cells that contain bindings for the function’s free variables. See below for information on the cell_contents attribute.	Read-only
__annotations__	A dict containing annotations of parameters. The keys of the dict are the parameter names, and 'return' for the return annotation, if provided.	Writable
__kwdefaults__	A dict containing defaults for keyword-only parameters.	Writable

Most of the attributes labelled «Writable» check the type of the assigned value.

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. Note that the current implementation only supports function attributes on user-defined functions. Function attributes on built-in functions may be supported in the future.

Об’єкт клітинки має атрибут cell_contents. Це можна використовувати для отримання значення комірки, а також для встановлення значення.

Additional information about a function’s definition can be retrieved from its code object; see the description of internal types below. The cell type can be accessed in the types module.

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

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

Special read-only attributes: __self__ is the class instance object, __func__ is the function object; __doc__ is the method’s documentation (same as __func__.__doc__); __name__ is the method name (same as __func__.__name__); __module__ is 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 class method 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 class method 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 class method 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.

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

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

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

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

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

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

Calling the asynchronous iterator’s aiterator.__anext__() method will return an awaitable which when awaited will execute until it provides a value using the yield expression. When the function executes an empty return statement or falls off the end, a StopAsyncIteration exception is raised and the asynchronous iterator will have reached the end of the set of values to be yielded.

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

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; __name__ is the function’s 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.

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

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.

Заняття

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.

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

Instances of arbitrary classes can be made callable by defining a __call__() method in their class.

Модулі

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.

Predefined (writable) attributes: __name__ is the module’s name; __doc__ is the module’s documentation string, or None if unavailable; __annotations__ (optional) is a dictionary containing variable annotations collected during module body execution; __file__ is the pathname of the file from which the module was loaded, if it was loaded from a file. The __file__ attribute may be missing for certain types of modules, such as C modules that are statically linked into the interpreter; for extension modules loaded dynamically from a shared library, it is the pathname of the shared library file.

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

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

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

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

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

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

Special attributes: __name__ is the class name; __module__ is the module name in which the class was defined; __dict__ is the dictionary containing the class’s namespace; __bases__ is a tuple containing the base classes, in the order of their occurrence in the base class list; __doc__ is the class’s documentation string, or None if undefined; __annotations__ (optional) is a dictionary containing variable annotations collected during class body execution.

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

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.

Attribute assignments and deletions update the instance’s dictionary, never a class’s dictionary. If the class has a __setattr__() or __delattr__() method, this is called instead of updating the instance dictionary directly.

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

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

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

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

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

Внутрішні типи

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

Об’єкти коду

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

Special read-only attributes: co_name gives the function name; co_argcount is the total number of positional arguments (including positional-only arguments and arguments with default values); co_posonlyargcount is the number of positional-only arguments (including arguments with default values); co_kwonlyargcount is the number of keyword-only arguments (including arguments with default values); co_nlocals is the number of local variables used by the function (including arguments); co_varnames is a tuple containing the names of the local variables (starting with the argument names); co_cellvars is a tuple containing the names of local variables that are referenced by nested functions; co_freevars is a tuple containing the names of free variables; co_code is a string representing the sequence of bytecode instructions; co_consts is a tuple containing the literals used by the bytecode; co_names is a tuple containing the names used by the bytecode; co_filename is the filename from which the code was compiled; co_firstlineno is the first line number of the function; co_lnotab is a string encoding the mapping from bytecode offsets to line numbers (for details see the source code of the interpreter); co_stacksize is the required stack size; co_flags is 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.

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.

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

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

Special read-only attributes: f_back is to the previous stack frame (towards the caller), or None if this is the bottom stack frame; f_code is the code object being executed in this frame; f_locals is the dictionary used to look up local variables; f_globals is used for global variables; f_builtins is used for built-in (intrinsic) names; f_lasti gives the precise instruction (this is an index into the bytecode string of the code object).

Accessing f_code raises an auditing event object.__getattr__ with arguments obj and "f_code".

Special writable attributes: f_trace, if not None, is a function called for various events during code execution (this is used by the debugger). Normally an event is triggered for each new source line - this can be disabled by setting f_trace_lines to False.

Implementations may allow per-opcode events to be requested by setting f_trace_opcodes to True. Note that this may lead to undefined interpreter behaviour if exceptions raised by the trace function escape to the function being traced.

f_lineno is 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 f_lineno.

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

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.

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

Traceback objects represent a 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.

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: tb_frame points to the execution frame of the current level; tb_lineno gives the line number where the exception occurred; 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.

Accessing tb_frame raises an auditing event object.__getattr__ with arguments obj and "tb_frame".

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: Traceback objects can now be explicitly instantiated from Python code, and the tb_next attribute of existing instances can be updated.

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

Slice objects are used to represent slices for __getitem__() methods. They are also created by the built-in slice() function.

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

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

slice.indices(self, length)

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

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

Static method objects provide a way of defeating the transformation of function objects to method objects described above. A static method object is a wrapper around any other object, usually a user-defined method object. When a static method object is retrieved from a class or a class instance, the object actually returned is the wrapped object, which is not subject to any further transformation. Static method objects are not themselves callable, although the objects they wrap usually are. Static method objects are created by the built-in staticmethod() constructor.

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

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 «User-defined methods». Class method objects are created by the built-in classmethod() constructor.

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

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

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

При реалізації класу, який емулює будь-який вбудований тип, важливо, щоб емуляція була реалізована лише в тій мірі, в якій це має сенс для об’єкта, що моделюється. Наприклад, деякі послідовності можуть добре працювати з отриманням окремих елементів, але вилучення фрагмента може не мати сенсу. (Одним із прикладів цього є інтерфейс 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 implementation detail: 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, '') is now equivalent to str(x) rather than format(str(self), '').

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

object.__hash__(self)

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

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

Примітка

hash() скорочує значення, що повертається користувацьким методом __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^2) complexity. See http://www.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. A sequence must be returned. dir() converts the returned sequence 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 a sequence 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)

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

object.__set_name__(self, owner, name)

Called at the time the owning class owner is created. The descriptor has been assigned to name.

Примітка

__set_name__() is only called implicitly as part of the type constructor, so it will need to be called explicitly with the appropriate parameters when a descriptor is added to a class after initial creation:

class A:
   pass
descr = custom_descriptor()
A.attr = descr
descr.__set_name__(A, 'attr')

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

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

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

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

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

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

If a is an instance of super, then the binding super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['m'].__get__(obj, obj.__class__).

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 __set__() and __get__() defined always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by instances.

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

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

3.3.2.4. __slots__

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

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

object.__slots__

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

3.3.2.4.1. Notes on using __slots__

• When inheriting from a class without __slots__, the __dict__ and __weakref__ attribute of the instances will always be accessible.

• Without a __dict__ variable, instances cannot be assigned new variables not listed in the __slots__ definition. Attempts to assign to an unlisted variable name raises AttributeError. If dynamic assignment of new variables is desired, then add '__dict__' to the sequence of strings in the __slots__ declaration.

• Without a __weakref__ variable for each instance, classes defining __slots__ do not support weak references to its instances. If weak reference support is needed, then add '__weakref__' to the sequence of strings in the __slots__ declaration.

• __slots__ are implemented at the class level by creating descriptors (Реалізація дескрипторів) for each variable name. As a result, class attributes cannot be used to set default values for instance variables defined by __slots__; otherwise, the class attribute would overwrite the descriptor assignment.

• The action of a __slots__ declaration is not limited to the class where it is defined. __slots__ declared in parents are available in child classes. However, child subclasses will get a __dict__ and __weakref__ unless they also define __slots__ (which should only contain names of any additional slots).

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

• Nonempty __slots__ does not work for classes derived from «variable-length» built-in types such as int, bytes and tuple.

• Any non-string iterable may be assigned to __slots__. Mappings may also be used; however, in the future, special meaning may be assigned to the values corresponding to each key.

• __class__ assignment works only if both classes have the same __slots__.

• Multiple inheritance with multiple slotted parent classes can be used, but only one parent is allowed to have attributes created by slots (the other bases must have empty slot layouts) - violations raise TypeError.

• If an iterator is used for __slots__ then a descriptor is created for each of the iterator’s values. However, the __slots__ attribute will be an empty iterator.

3.3.3. Налаштування створення класу

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

classmethod object.__init_subclass__(cls)

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

Keyword arguments which are given to a new class are passed to the parent’s class __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.

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

If a base that appears in class definition is not an instance of type, then an __mro_entries__ method is searched on it. If found, it is called with the original bases tuple. This method must return a tuple of classes that will be used instead of this base. The tuple may be empty, in such case the original base is ignored.

Дивись також

PEP 560 - Core support for typing module and generic types

3.3.3.3. Визначення відповідного метакласу

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

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

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

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

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

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

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

Якщо метаклас не має атрибута __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 implementation detail: У CPython 3.6 і пізніших версіях клітинка __class__ передається метакласу як запис __classcell__ у просторі імен класу. Якщо є, це має бути передано до виклику type.__new__ для правильної ініціалізації класу. Якщо цього не зробити, у Python 3.8 виникне RuntimeError.

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

• first, type.__new__ collects all of the descriptors in the class namespace that define a __set_name__() method;

• second, all of these __set_name__ methods are called with the class being defined and the assigned name of that particular descriptor;

• finally, the __init_subclass__() hook is called on the immediate parent of the new class in its method resolution order.

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

Коли новий клас створюється за допомогою 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. Емуляція загальних типів

One can implement the generic class syntax as specified by PEP 484 (for example List[int]) by defining a special method:

classmethod object.__class_getitem__(cls, key)

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

This method is looked up on the class object itself, and when defined in the class body, this method is implicitly a class method. Note, this mechanism is primarily reserved for use with static type hints, other usage is discouraged.

Дивись також

PEP 560 - Core support for typing module and generic types

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 implementation detail: 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 and slice objects. Note that the special interpretation of negative indexes (if the class wishes to emulate a sequence type) is up to the __getitem__() method. If key is of an inappropriate type, TypeError may be raised; if of 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 буде викликано для недопустимих індексів, щоб забезпечити належне виявлення кінця послідовності.

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)

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

Iterator objects also need to implement this method; they are required to return themselves. For more information on iterator objects, see Типи ітераторів.

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, x.__add__(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, y.__rsub__(x) is called if x.__sub__(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, 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) . Otherwise, 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.

Примітка

Due to a bug in the dispatching mechanism for **=, a class that defines __ipow__() but returns NotImplemented would fail to fall back to x.__pow__(y) and y.__rpow__(x). This bug is fixed in Python 3.10.

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.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. Спеціальний метод пошуку

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

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

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

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

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

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

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

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

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

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

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

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

Примітка

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

object.__await__(self)

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

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

Дивись також

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

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

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

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

Змінено в версії 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(type[, value[, traceback]])

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

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: Prior to Python 3.7, __aiter__ could return an awaitable that would resolve to an asynchronous iterator.

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

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

Асинхронний контекстний менеджер — це контекстний менеджер, який може призупинити виконання своїх методів __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

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