Debian Codegraph @

Doc/reference/datamodel.rst

raw
1
2 .. _datamodel:
3
4 **********
5 Data model
6 **********
7
8
9 .. _objects:
10
11 Objects, values and types
12 =========================
13
14 .. index::
15 single: object
16 single: data
17
18 :dfn:`Objects` are Python's abstraction for data. All data in a Python program
19 is represented by objects or by relations between objects. Even code is
20 represented by objects.
21
22 .. index::
23 pair: built-in function; id
24 pair: built-in function; type
25 single: identity of an object
26 single: value of an object
27 single: type of an object
28 single: mutable object
29 single: immutable object
30
31 Every object has an identity, a type and a value. An object's *identity* never
32 changes once it has been created; you may think of it as the object's address in
33 memory. The :keyword:`is` operator compares the identity of two objects; the
34 :func:`id` function returns an integer representing its identity.
35
36 .. impl-detail::
37
38 For CPython, ``id(x)`` is the memory address where ``x`` is stored.
39
40 An object's type determines the operations that the object supports (e.g., "does
41 it have a length?") and also defines the possible values for objects of that
42 type. The :func:`type` function returns an object's type (which is an object
43 itself). Like its identity, an object's :dfn:`type` is also unchangeable.
44 [#]_
45
46 The *value* of some objects can change. Objects whose value can
47 change are said to be *mutable*; objects whose value is unchangeable once they
48 are created are called *immutable*. (The value of an immutable container object
49 that contains a reference to a mutable object can change when the latter's value
50 is changed; however the container is still considered immutable, because the
51 collection of objects it contains cannot be changed. So, immutability is not
52 strictly the same as having an unchangeable value, it is more subtle.) An
53 object's mutability is determined by its type; for instance, numbers, strings
54 and tuples are immutable, while dictionaries and lists are mutable.
55
56 .. index::
57 single: garbage collection
58 single: reference counting
59 single: unreachable object
60
61 Objects are never explicitly destroyed; however, when they become unreachable
62 they may be garbage-collected. An implementation is allowed to postpone garbage
63 collection or omit it altogether --- it is a matter of implementation quality
64 how garbage collection is implemented, as long as no objects are collected that
65 are still reachable.
66
67 .. impl-detail::
68
69 CPython currently uses a reference-counting scheme with (optional) delayed
70 detection of cyclically linked garbage, which collects most objects as soon
71 as they become unreachable, but is not guaranteed to collect garbage
72 containing circular references. See the documentation of the :mod:`gc`
73 module for information on controlling the collection of cyclic garbage.
74 Other implementations act differently and CPython may change.
75 Do not depend on immediate finalization of objects when they become
76 unreachable (so you should always close files explicitly).
77
78 Note that the use of the implementation's tracing or debugging facilities may
79 keep objects alive that would normally be collectable. Also note that catching
80 an exception with a :keyword:`try`...\ :keyword:`except` statement may keep
81 objects alive.
82
83 Some objects contain references to "external" resources such as open files or
84 windows. It is understood that these resources are freed when the object is
85 garbage-collected, but since garbage collection is not guaranteed to happen,
86 such objects also provide an explicit way to release the external resource,
87 usually a :meth:`!close` method. Programs are strongly recommended to explicitly
88 close such objects. The :keyword:`try`...\ :keyword:`finally` statement
89 and the :keyword:`with` statement provide convenient ways to do this.
90
91 .. index:: single: container
92
93 Some objects contain references to other objects; these are called *containers*.
94 Examples of containers are tuples, lists and dictionaries. The references are
95 part of a container's value. In most cases, when we talk about the value of a
96 container, we imply the values, not the identities of the contained objects;
97 however, when we talk about the mutability of a container, only the identities
98 of the immediately contained objects are implied. So, if an immutable container
99 (like a tuple) contains a reference to a mutable object, its value changes if
100 that mutable object is changed.
101
102 Types affect almost all aspects of object behavior. Even the importance of
103 object identity is affected in some sense: for immutable types, operations that
104 compute new values may actually return a reference to any existing object with
105 the same type and value, while for mutable objects this is not allowed.
106 For example, after ``a = 1; b = 1``, *a* and *b* may or may not refer to
107 the same object with the value one, depending on the implementation.
108 This is because :class:`int` is an immutable type, so the reference to ``1``
109 can be reused. This behaviour depends on the implementation used, so should
110 not be relied upon, but is something to be aware of when making use of object
111 identity tests.
112 However, after ``c = []; d = []``, *c* and *d* are guaranteed to refer to two
113 different, unique, newly created empty lists. (Note that ``e = f = []`` assigns
114 the *same* object to both *e* and *f*.)
115
116
117 .. _types:
118
119 The standard type hierarchy
120 ===========================
121
122 .. index::
123 single: type
124 pair: data; type
125 pair: type; hierarchy
126 pair: extension; module
127 pair: C; language
128
129 Below is a list of the types that are built into Python. Extension modules
130 (written in C, Java, or other languages, depending on the implementation) can
131 define additional types. Future versions of Python may add types to the type
132 hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.),
133 although such additions will often be provided via the standard library instead.
134
135 .. index::
136 single: attribute
137 pair: special; attribute
138 triple: generic; special; attribute
139
140 Some of the type descriptions below contain a paragraph listing 'special
141 attributes.' These are attributes that provide access to the implementation and
142 are not intended for general use. Their definition may change in the future.
143
144
145 None
146 ----
147
148 .. index:: pair: object; None
149
150 This type has a single value. There is a single object with this value. This
151 object is accessed through the built-in name ``None``. It is used to signify the
152 absence of a value in many situations, e.g., it is returned from functions that
153 don't explicitly return anything. Its truth value is false.
154
155
156 NotImplemented
157 --------------
158
159 .. index:: pair: object; NotImplemented
160
161 This type has a single value. There is a single object with this value. This
162 object is accessed through the built-in name :data:`NotImplemented`. Numeric methods
163 and rich comparison methods should return this value if they do not implement the
164 operation for the operands provided. (The interpreter will then try the
165 reflected operation, or some other fallback, depending on the operator.) It
166 should not be evaluated in a boolean context.
167
168 See
169 :ref:`implementing-the-arithmetic-operations`
170 for more details.
171
172 .. versionchanged:: 3.9
173 Evaluating :data:`NotImplemented` in a boolean context was deprecated.
174
175 .. versionchanged:: 3.14
176 Evaluating :data:`NotImplemented` in a boolean context now raises a :exc:`TypeError`.
177 It previously evaluated to :const:`True` and emitted a :exc:`DeprecationWarning`
178 since Python 3.9.
179
180
181 Ellipsis
182 --------
183 .. index::
184 pair: object; Ellipsis
185 single: ...; ellipsis literal
186
187 This type has a single value. There is a single object with this value. This
188 object is accessed through the literal ``...`` or the built-in name
189 ``Ellipsis``. Its truth value is true.
190
191
192 :class:`numbers.Number`
193 -----------------------
194
195 .. index:: pair: object; numeric
196
197 These are created by numeric literals and returned as results by arithmetic
198 operators and arithmetic built-in functions. Numeric objects are immutable;
199 once created their value never changes. Python numbers are of course strongly
200 related to mathematical numbers, but subject to the limitations of numerical
201 representation in computers.
202
203 The string representations of the numeric classes, computed by
204 :meth:`~object.__repr__` and :meth:`~object.__str__`, have the following
205 properties:
206
207 * They are valid numeric literals which, when passed to their
208 class constructor, produce an object having the value of the
209 original numeric.
210
211 * The representation is in base 10, when possible.
212
213 * Leading zeros, possibly excepting a single zero before a
214 decimal point, are not shown.
215
216 * Trailing zeros, possibly excepting a single zero after a
217 decimal point, are not shown.
218
219 * A sign is shown only when the number is negative.
220
221 Python distinguishes between integers, floating-point numbers, and complex
222 numbers:
223
224
225 :class:`numbers.Integral`
226 ^^^^^^^^^^^^^^^^^^^^^^^^^
227
228 .. index:: pair: object; integer
229
230 These represent elements from the mathematical set of integers (positive and
231 negative).
232
233 .. note::
234 .. index:: pair: integer; representation
235
236 The rules for integer representation are intended to give the most meaningful
237 interpretation of shift and mask operations involving negative integers.
238
239 There are two types of integers:
240
241 Integers (:class:`int`)
242 These represent numbers in an unlimited range, subject to available (virtual)
243 memory only. For the purpose of shift and mask operations, a binary
244 representation is assumed, and negative numbers are represented in a variant of
245 2's complement which gives the illusion of an infinite string of sign bits
246 extending to the left.
247
248 Booleans (:class:`bool`)
249 .. index::
250 pair: object; Boolean
251 single: False
252 single: True
253
254 These represent the truth values False and True. The two objects representing
255 the values ``False`` and ``True`` are the only Boolean objects. The Boolean type is a
256 subtype of the integer type, and Boolean values behave like the values 0 and 1,
257 respectively, in almost all contexts, the exception being that when converted to
258 a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
259
260
261 .. _datamodel-float:
262
263 :class:`numbers.Real` (:class:`float`)
264 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
265
266 .. index::
267 pair: object; floating-point
268 pair: floating-point; number
269 pair: C; language
270 pair: Java; language
271
272 These represent machine-level double precision floating-point numbers. You are
273 at the mercy of the underlying machine architecture (and C or Java
274 implementation) for the accepted range and handling of overflow. Python does not
275 support single-precision floating-point numbers; the savings in processor and
276 memory usage that are usually the reason for using these are dwarfed by the
277 overhead of using objects in Python, so there is no reason to complicate the
278 language with two kinds of floating-point numbers.
279
280
281 :class:`numbers.Complex` (:class:`complex`)
282 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
283
284 .. index::
285 pair: object; complex
286 pair: complex; number
287
288 These represent complex numbers as a pair of machine-level double precision
289 floating-point numbers. The same caveats apply as for floating-point numbers.
290 The real and imaginary parts of a complex number ``z`` can be retrieved through
291 the read-only attributes ``z.real`` and ``z.imag``.
292
293 .. _datamodel-sequences:
294
295 Sequences
296 ---------
297
298 .. index::
299 pair: built-in function; len
300 pair: object; sequence
301 single: index operation
302 single: item selection
303 single: subscription
304
305 These represent finite ordered sets indexed by non-negative numbers. The
306 built-in function :func:`len` returns the number of items of a sequence. When
307 the length of a sequence is *n*, the index set contains the numbers 0, 1,
308 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. Some sequences,
309 including built-in sequences, interpret negative subscripts by adding the
310 sequence length. For example, ``a[-2]`` equals ``a[n-2]``, the second to last
311 item of sequence a with length ``n``.
312
313 The resulting value must be a nonnegative integer less than the number of items
314 in the sequence. If it is not, an :exc:`IndexError` is raised.
315
316 .. index::
317 single: slicing
318 single: start (slice object attribute)
319 single: stop (slice object attribute)
320 single: step (slice object attribute)
321
322 Sequences also support slicing: ``a[start:stop]`` selects all items with index *k* such
323 that *start* ``<=`` *k* ``<`` *stop*. When used as an expression, a slice is a
324 sequence of the same type. The comment above about negative subscripts also applies
325 to negative slice positions.
326 Note that no error is raised if a slice position is less than zero or larger
327 than the length of the sequence.
328
329 If *start* is missing or :data:`None`, slicing behaves as if *start* was zero.
330 If *stop* is missing or ``None``, slicing behaves as if *stop* was equal to
331 the length of the sequence.
332
333 Some sequences also support "extended slicing" with a third "step" parameter:
334 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
335 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
336
337 Sequences are distinguished according to their mutability:
338
339
340 Immutable sequences
341 ^^^^^^^^^^^^^^^^^^^
342
343 .. index::
344 pair: object; immutable sequence
345 pair: object; immutable
346
347 An object of an immutable sequence type cannot change once it is created. (If
348 the object contains references to other objects, these other objects may be
349 mutable and may be changed; however, the collection of objects directly
350 referenced by an immutable object cannot change.)
351
352 The following types are immutable sequences:
353
354 .. index::
355 single: string; immutable sequences
356
357 Strings
358 .. index::
359 pair: built-in function; chr
360 pair: built-in function; ord
361 single: character
362 pair: string; item
363 single: Unicode
364
365 A string (:class:`str`) is a sequence of values that represent
366 :dfn:`characters`, or more formally, *Unicode code points*.
367 All the code points in the range ``0`` to ``0x10FFFF`` can be
368 represented in a string.
369
370 Python doesn't have a dedicated *character* type.
371 Instead, every code point in the string is represented as a string
372 object with length ``1``.
373
374 The built-in function :func:`ord`
375 converts a code point from its string form to an integer in the
376 range ``0`` to ``0x10FFFF``; :func:`chr` converts an integer in the range
377 ``0`` to ``0x10FFFF`` to the corresponding length ``1`` string object.
378 :meth:`str.encode` can be used to convert a :class:`str` to
379 :class:`bytes` using the given text encoding, and
380 :meth:`bytes.decode` can be used to achieve the opposite.
381
382 Tuples
383 .. index::
384 pair: object; tuple
385 pair: singleton; tuple
386 pair: empty; tuple
387
388 The items of a :class:`tuple` are arbitrary Python objects. Tuples of two or
389 more items are formed by comma-separated lists of expressions. A tuple
390 of one item (a 'singleton') can be formed by affixing a comma to an
391 expression (an expression by itself does not create a tuple, since
392 parentheses must be usable for grouping of expressions). An empty
393 tuple can be formed by an empty pair of parentheses.
394
395 Bytes
396 .. index:: bytes, byte
397
398 A :class:`bytes` object is an immutable array. The items are 8-bit bytes,
399 represented by integers in the range 0 <= x < 256. Bytes literals
400 (like ``b'abc'``) and the built-in :func:`bytes` constructor
401 can be used to create bytes objects. Also, bytes objects can be
402 decoded to strings via the :meth:`~bytes.decode` method.
403
404
405 Mutable sequences
406 ^^^^^^^^^^^^^^^^^
407
408 .. index::
409 pair: object; mutable sequence
410 pair: object; mutable
411 pair: assignment; statement
412 single: subscription
413 single: slicing
414
415 Mutable sequences can be changed after they are created. The subscription and
416 slicing notations can be used as the target of assignment and :keyword:`del`
417 (delete) statements.
418
419 .. note::
420 .. index:: pair: module; array
421 .. index:: pair: module; collections
422
423 The :mod:`collections` and :mod:`array` module provide
424 additional examples of mutable sequence types.
425
426 There are currently two intrinsic mutable sequence types:
427
428 Lists
429 .. index:: pair: object; list
430
431 The items of a list are arbitrary Python objects. Lists are formed by
432 placing a comma-separated list of expressions in square brackets. (Note
433 that there are no special cases needed to form lists of length 0 or 1.)
434
435 Byte Arrays
436 .. index:: bytearray
437
438 A bytearray object is a mutable array. They are created by the built-in
439 :func:`bytearray` constructor. Aside from being mutable
440 (and hence unhashable), byte arrays otherwise provide the same interface
441 and functionality as immutable :class:`bytes` objects.
442
443
444 Set types
445 ---------
446
447 .. index::
448 pair: built-in function; len
449 pair: object; set type
450
451 These represent unordered, finite sets of unique, immutable objects. As such,
452 they cannot be indexed by any subscript. However, they can be iterated over, and
453 the built-in function :func:`len` returns the number of items in a set. Common
454 uses for sets are fast membership testing, removing duplicates from a sequence,
455 and computing mathematical operations such as intersection, union, difference,
456 and symmetric difference.
457
458 For set elements, the same immutability rules apply as for dictionary keys. Note
459 that numeric types obey the normal rules for numeric comparison: if two numbers
460 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
461 set.
462
463 There are currently two intrinsic set types:
464
465
466 Sets
467 .. index:: pair: object; set
468
469 These represent a mutable set. They are created by the built-in :func:`set`
470 constructor and can be modified afterwards by several methods, such as
471 :meth:`~set.add`.
472
473
474 Frozen sets
475 .. index:: pair: object; frozenset
476
477 These represent an immutable set. They are created by the built-in
478 :func:`frozenset` constructor. As a frozenset is immutable and
479 :term:`hashable`, it can be used again as an element of another set, or as
480 a dictionary key.
481
482
483 .. _datamodel-mappings:
484
485 Mappings
486 --------
487
488 .. index::
489 pair: built-in function; len
490 single: subscription
491 pair: object; mapping
492
493 These represent finite sets of objects indexed by arbitrary index sets. The
494 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
495 ``a``; this can be used in expressions and as the target of assignments or
496 :keyword:`del` statements. The built-in function :func:`len` returns the number
497 of items in a mapping.
498
499 There is currently a single intrinsic mapping type:
500
501
502 Dictionaries
503 ^^^^^^^^^^^^
504
505 .. index:: pair: object; dictionary
506
507 These represent finite sets of objects indexed by nearly arbitrary values. The
508 only types of values not acceptable as keys are values containing lists or
509 dictionaries or other mutable types that are compared by value rather than by
510 object identity, the reason being that the efficient implementation of
511 dictionaries requires a key's hash value to remain constant. Numeric types used
512 for keys obey the normal rules for numeric comparison: if two numbers compare
513 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
514 the same dictionary entry.
515
516 Dictionaries preserve insertion order, meaning that keys will be produced
517 in the same order they were added sequentially over the dictionary.
518 Replacing an existing key does not change the order, however removing a key
519 and re-inserting it will add it to the end instead of keeping its old place.
520
521 Dictionaries are mutable; they can be created by the ``{}`` notation (see
522 section :ref:`dict`).
523
524 .. index::
525 pair: module; dbm.ndbm
526 pair: module; dbm.gnu
527
528 The extension modules :mod:`dbm.ndbm` and :mod:`dbm.gnu` provide
529 additional examples of mapping types, as does the :mod:`collections`
530 module.
531
532 .. versionchanged:: 3.7
533 Dictionaries did not preserve insertion order in versions of Python before 3.6.
534 In CPython 3.6, insertion order was preserved, but it was considered
535 an implementation detail at that time rather than a language guarantee.
536
537
538 Callable types
539 --------------
540
541 .. index::
542 pair: object; callable
543 pair: function; call
544 single: invocation
545 pair: function; argument
546
547 These are the types to which the function call operation (see section
548 :ref:`calls`) can be applied:
549
550
551 .. _user-defined-funcs:
552
553 User-defined functions
554 ^^^^^^^^^^^^^^^^^^^^^^
555
556 .. index::
557 pair: user-defined; function
558 pair: object; function
559 pair: object; user-defined function
560
561 A user-defined function object is created by a function definition (see
562 section :ref:`function`). It should be called with an argument list
563 containing the same number of items as the function's formal parameter
564 list.
565
566 Special read-only attributes
567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
568
569 .. index::
570 single: __builtins__ (function attribute)
571 single: __closure__ (function attribute)
572 single: __globals__ (function attribute)
573 pair: global; namespace
574
575 .. list-table::
576 :header-rows: 1
577
578 * - Attribute
579 - Meaning
580
581 * - .. attribute:: function.__builtins__
582 - A reference to the :class:`dictionary <dict>` that holds the function's
583 builtins namespace.
584
585 .. versionadded:: 3.10
586
587 * - .. attribute:: function.__globals__
588 - A reference to the :class:`dictionary <dict>` that holds the function's
589 :ref:`global variables <naming>` -- the global namespace of the module
590 in which the function was defined.
591
592 * - .. attribute:: function.__closure__
593 - ``None`` or a :class:`tuple` of cells that contain bindings for the names specified
594 in the :attr:`~codeobject.co_freevars` attribute of the function's
595 :attr:`code object <function.__code__>`.
596
597 A cell object has the attribute ``cell_contents``.
598 This can be used to get the value of the cell, as well as set the value.
599
600 Special writable attributes
601 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
602
603 .. index::
604 single: __doc__ (function attribute)
605 single: __name__ (function attribute)
606 single: __module__ (function attribute)
607 single: __dict__ (function attribute)
608 single: __defaults__ (function attribute)
609 single: __code__ (function attribute)
610 single: __annotations__ (function attribute)
611 single: __annotate__ (function attribute)
612 single: __kwdefaults__ (function attribute)
613 single: __type_params__ (function attribute)
614
615 Most of these attributes check the type of the assigned value:
616
617 .. list-table::
618 :header-rows: 1
619
620 * - Attribute
621 - Meaning
622
623 * - .. attribute:: function.__doc__
624 - The function's documentation string, or ``None`` if unavailable.
625
626 * - .. attribute:: function.__name__
627 - The function's name.
628 See also: :attr:`__name__ attributes <definition.__name__>`.
629
630 * - .. attribute:: function.__qualname__
631 - The function's :term:`qualified name`.
632 See also: :attr:`__qualname__ attributes <definition.__qualname__>`.
633
634 .. versionadded:: 3.3
635
636 * - .. attribute:: function.__module__
637 - The name of the module the function was defined in,
638 or ``None`` if unavailable.
639
640 * - .. attribute:: function.__defaults__
641 - A :class:`tuple` containing default :term:`parameter` values
642 for those parameters that have defaults,
643 or ``None`` if no parameters have a default value.
644
645 * - .. attribute:: function.__code__
646 - The :ref:`code object <code-objects>` representing
647 the compiled function body.
648
649 * - .. attribute:: function.__dict__
650 - The namespace supporting arbitrary function attributes.
651 See also: :attr:`__dict__ attributes <object.__dict__>`.
652
653 * - .. attribute:: function.__annotations__
654 - A :class:`dictionary <dict>` containing annotations of
655 :term:`parameters <parameter>`.
656 The keys of the dictionary are the parameter names,
657 and ``'return'`` for the return annotation, if provided.
658 See also: :attr:`object.__annotations__`.
659
660 .. versionchanged:: 3.14
661 Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
662 See :pep:`649`.
663
664 * - .. attribute:: function.__annotate__
665 - The :term:`annotate function` for this function, or ``None``
666 if the function has no annotations. See :attr:`object.__annotate__`.
667
668 .. versionadded:: 3.14
669
670 * - .. attribute:: function.__kwdefaults__
671 - A :class:`dictionary <dict>` containing defaults for keyword-only
672 :term:`parameters <parameter>`.
673
674 * - .. attribute:: function.__type_params__
675 - A :class:`tuple` containing the :ref:`type parameters <type-params>` of
676 a :ref:`generic function <generic-functions>`.
677
678 .. versionadded:: 3.12
679
680 Function objects also support getting and setting arbitrary attributes, which
681 can be used, for example, to attach metadata to functions. Regular attribute
682 dot-notation is used to get and set such attributes.
683
684 .. impl-detail::
685
686 CPython's current implementation only supports function attributes
687 on user-defined functions. Function attributes on
688 :ref:`built-in functions <builtin-functions>` may be supported in the
689 future.
690
691 Additional information about a function's definition can be retrieved from its
692 :ref:`code object <code-objects>`
693 (accessible via the :attr:`~function.__code__` attribute).
694
695
696 .. _instance-methods:
697
698 Instance methods
699 ^^^^^^^^^^^^^^^^
700
701 .. index::
702 pair: object; method
703 pair: object; user-defined method
704 pair: user-defined; method
705
706 An instance method object combines a class, a class instance and any
707 callable object (normally a user-defined function).
708
709 .. index::
710 single: __func__ (method attribute)
711 single: __self__ (method attribute)
712 single: __doc__ (method attribute)
713 single: __name__ (method attribute)
714 single: __module__ (method attribute)
715
716 Special read-only attributes:
717
718 .. list-table::
719
720 * - .. attribute:: method.__self__
721 - Refers to the class instance object to which the method is
722 :ref:`bound <method-binding>`
723
724 * - .. attribute:: method.__func__
725 - Refers to the original :ref:`function object <user-defined-funcs>`
726
727 * - .. attribute:: method.__doc__
728 - The method's documentation
729 (same as :attr:`method.__func__.__doc__ <function.__doc__>`).
730 A :class:`string <str>` if the original function had a docstring, else
731 ``None``.
732
733 * - .. attribute:: method.__name__
734 - The name of the method
735 (same as :attr:`method.__func__.__name__ <function.__name__>`)
736
737 * - .. attribute:: method.__module__
738 - The name of the module the method was defined in, or ``None`` if
739 unavailable.
740
741 Methods also support accessing (but not setting) the arbitrary function
742 attributes on the underlying :ref:`function object <user-defined-funcs>`.
743
744 User-defined method objects may be created when getting an attribute of a
745 class (perhaps via an instance of that class), if that attribute is a
746 user-defined :ref:`function object <user-defined-funcs>` or a
747 :class:`classmethod` object.
748
749 .. _method-binding:
750
751 When an instance method object is created by retrieving a user-defined
752 :ref:`function object <user-defined-funcs>` from a class via one of its
753 instances, its :attr:`~method.__self__` attribute is the instance, and the
754 method object is said to be *bound*. The new method's :attr:`~method.__func__`
755 attribute is the original function object.
756
757 When an instance method object is created by retrieving a :class:`classmethod`
758 object from a class or instance, its :attr:`~method.__self__` attribute is the
759 class itself, and its :attr:`~method.__func__` attribute is the function object
760 underlying the class method.
761
762 When an instance method object is called, the underlying function
763 (:attr:`~method.__func__`) is called, inserting the class instance
764 (:attr:`~method.__self__`) in front of the argument list. For instance, when
765 :class:`!C` is a class which contains a definition for a function
766 :meth:`!f`, and ``x`` is an instance of :class:`!C`, calling ``x.f(1)`` is
767 equivalent to calling ``C.f(x, 1)``.
768
769 When an instance method object is derived from a :class:`classmethod` object, the
770 "class instance" stored in :attr:`~method.__self__` will actually be the class
771 itself, so that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to
772 calling ``f(C,1)`` where ``f`` is the underlying function.
773
774 It is important to note that user-defined functions
775 which are attributes of a class instance are not converted to bound
776 methods; this *only* happens when the function is an attribute of the
777 class.
778
779
780 Generator functions
781 ^^^^^^^^^^^^^^^^^^^
782
783 .. index::
784 single: generator; function
785 single: generator; iterator
786
787 A function or method which uses the :keyword:`yield` statement (see section
788 :ref:`yield`) is called a :dfn:`generator function`. Such a function, when
789 called, always returns an :term:`iterator` object which can be used to
790 execute the body of the function: calling the iterator's
791 :meth:`iterator.__next__` method will cause the function to execute until
792 it provides a value using the :keyword:`!yield` statement. When the
793 function executes a :keyword:`return` statement or falls off the end, a
794 :exc:`StopIteration` exception is raised and the iterator will have
795 reached the end of the set of values to be returned.
796
797
798 Coroutine functions
799 ^^^^^^^^^^^^^^^^^^^
800
801 .. index::
802 single: coroutine; function
803
804 A function or method which is defined using :keyword:`async def` is called
805 a :dfn:`coroutine function`. Such a function, when called, returns a
806 :term:`coroutine` object. It may contain :keyword:`await` expressions,
807 as well as :keyword:`async with` and :keyword:`async for` statements. See
808 also the :ref:`coroutine-objects` section.
809
810
811 Asynchronous generator functions
812 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
813
814 .. index::
815 single: asynchronous generator; function
816 single: asynchronous generator; asynchronous iterator
817
818 A function or method which is defined using :keyword:`async def` and
819 which uses the :keyword:`yield` statement is called a
820 :dfn:`asynchronous generator function`. Such a function, when called,
821 returns an :term:`asynchronous iterator` object which can be used in an
822 :keyword:`async for` statement to execute the body of the function.
823
824 Calling the asynchronous iterator's
825 :meth:`aiterator.__anext__ <object.__anext__>` method
826 will return an :term:`awaitable` which when awaited
827 will execute until it provides a value using the :keyword:`yield`
828 expression. When the function executes an empty :keyword:`return`
829 statement or falls off the end, a :exc:`StopAsyncIteration` exception
830 is raised and the asynchronous iterator will have reached the end of
831 the set of values to be yielded.
832
833
834 .. _builtin-functions:
835
836 Built-in functions
837 ^^^^^^^^^^^^^^^^^^
838
839 .. index::
840 pair: object; built-in function
841 pair: object; function
842 pair: C; language
843
844 A built-in function object is a wrapper around a C function. Examples of
845 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
846 standard built-in module). The number and type of the arguments are
847 determined by the C function. Special read-only attributes:
848
849 * :attr:`!__doc__` is the function's documentation string, or ``None`` if
850 unavailable. See :attr:`function.__doc__`.
851 * :attr:`!__name__` is the function's name. See :attr:`function.__name__`.
852 * :attr:`!__self__` is set to ``None`` (but see the next item).
853 * :attr:`!__module__` is the name of
854 the module the function was defined in or ``None`` if unavailable.
855 See :attr:`function.__module__`.
856
857
858 .. _builtin-methods:
859
860 Built-in methods
861 ^^^^^^^^^^^^^^^^
862
863 .. index::
864 pair: object; built-in method
865 pair: object; method
866 pair: built-in; method
867
868 This is really a different disguise of a built-in function, this time containing
869 an object passed to the C function as an implicit extra argument. An example of
870 a built-in method is ``alist.append()``, assuming *alist* is a list object. In
871 this case, the special read-only attribute :attr:`!__self__` is set to the object
872 denoted by *alist*. (The attribute has the same semantics as it does with
873 :attr:`other instance methods <method.__self__>`.)
874
875 .. _classes:
876
877 Classes
878 ^^^^^^^
879
880 Classes are callable. These objects normally act as factories for new
881 instances of themselves, but variations are possible for class types that
882 override :meth:`~object.__new__`. The arguments of the call are passed to
883 :meth:`!__new__` and, in the typical case, to :meth:`~object.__init__` to
884 initialize the new instance.
885
886
887 Class Instances
888 ^^^^^^^^^^^^^^^
889
890 Instances of arbitrary classes can be made callable by defining a
891 :meth:`~object.__call__` method in their class.
892
893
894 .. _module-objects:
895
896 Modules
897 -------
898
899 .. index::
900 pair: statement; import
901 pair: object; module
902
903 Modules are a basic organizational unit of Python code, and are created by
904 the :ref:`import system <importsystem>` as invoked either by the
905 :keyword:`import` statement, or by calling
906 functions such as :func:`importlib.import_module` and built-in
907 :func:`__import__`. A module object has a namespace implemented by a
908 :class:`dictionary <dict>` object (this is the dictionary referenced by the
909 :attr:`~function.__globals__`
910 attribute of functions defined in the module). Attribute references are
911 translated to lookups in this dictionary, e.g., ``m.x`` is equivalent to
912 ``m.__dict__["x"]``. A module object does not contain the code object used
913 to initialize the module (since it isn't needed once the initialization is
914 done).
915
916 Attribute assignment updates the module's namespace dictionary, e.g.,
917 ``m.x = 1`` is equivalent to ``m.__dict__["x"] = 1``.
918
919 .. index::
920 single: __name__ (module attribute)
921 single: __spec__ (module attribute)
922 single: __package__ (module attribute)
923 single: __loader__ (module attribute)
924 single: __path__ (module attribute)
925 single: __file__ (module attribute)
926 single: __cached__ (module attribute)
927 single: __doc__ (module attribute)
928 single: __annotations__ (module attribute)
929 single: __annotate__ (module attribute)
930 pair: module; namespace
931
932 .. _import-mod-attrs:
933
934 Import-related attributes on module objects
935 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
936
937 Module objects have the following attributes that relate to the
938 :ref:`import system <importsystem>`. When a module is created using the machinery associated
939 with the import system, these attributes are filled in based on the module's
940 :term:`spec <module spec>`, before the :term:`loader` executes and loads the
941 module.
942
943 To create a module dynamically rather than using the import system,
944 it's recommended to use :func:`importlib.util.module_from_spec`,
945 which will set the various import-controlled attributes to appropriate values.
946 It's also possible to use the :class:`types.ModuleType` constructor to create
947 modules directly, but this technique is more error-prone, as most attributes
948 must be manually set on the module object after it has been created when using
949 this approach.
950
951 .. caution::
952
953 With the exception of :attr:`~module.__name__`, it is **strongly**
954 recommended that you rely on :attr:`~module.__spec__` and its attributes
955 instead of any of the other individual attributes listed in this subsection.
956 Note that updating an attribute on :attr:`!__spec__` will not update the
957 corresponding attribute on the module itself:
958
959 .. doctest::
960
961 >>> import typing
962 >>> typing.__name__, typing.__spec__.name
963 ('typing', 'typing')
964 >>> typing.__spec__.name = 'spelling'
965 >>> typing.__name__, typing.__spec__.name
966 ('typing', 'spelling')
967 >>> typing.__name__ = 'keyboard_smashing'
968 >>> typing.__name__, typing.__spec__.name
969 ('keyboard_smashing', 'spelling')
970
971 .. attribute:: module.__name__
972
973 The name used to uniquely identify the module in the import system.
974 For a directly executed module, this will be set to ``"__main__"``.
975
976 This attribute must be set to the fully qualified name of the module.
977 It is expected to match the value of
978 :attr:`module.__spec__.name <importlib.machinery.ModuleSpec.name>`.
979
980 .. attribute:: module.__spec__
981
982 A record of the module's import-system-related state.
983
984 Set to the :class:`module spec <importlib.machinery.ModuleSpec>` that was
985 used when importing the module. See :ref:`module-specs` for more details.
986
987 .. versionadded:: 3.4
988
989 .. attribute:: module.__package__
990
991 The :term:`package` a module belongs to.
992
993 If the module is top-level (that is, not a part of any specific package)
994 then the attribute should be set to ``''`` (the empty string). Otherwise,
995 it should be set to the name of the module's package (which can be equal to
996 :attr:`module.__name__` if the module itself is a package). See :pep:`366`
997 for further details.
998
999 This attribute is used instead of :attr:`~module.__name__` to calculate
1000 explicit relative imports for main modules. It defaults to ``None`` for
1001 modules created dynamically using the :class:`types.ModuleType` constructor;
1002 use :func:`importlib.util.module_from_spec` instead to ensure the attribute
1003 is set to a :class:`str`.
1004
1005 It is **strongly** recommended that you use
1006 :attr:`module.__spec__.parent <importlib.machinery.ModuleSpec.parent>`
1007 instead of :attr:`!module.__package__`. :attr:`__package__` is now only used
1008 as a fallback if :attr:`!__spec__.parent` is not set, and this fallback
1009 path is deprecated.
1010
1011 .. versionchanged:: 3.4
1012 This attribute now defaults to ``None`` for modules created dynamically
1013 using the :class:`types.ModuleType` constructor.
1014 Previously the attribute was optional.
1015
1016 .. versionchanged:: 3.6
1017 The value of :attr:`!__package__` is expected to be the same as
1018 :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.
1019 :attr:`__package__` is now only used as a fallback during import
1020 resolution if :attr:`!__spec__.parent` is not defined.
1021
1022 .. versionchanged:: 3.10
1023 :exc:`ImportWarning` is raised if an import resolution falls back to
1024 :attr:`!__package__` instead of
1025 :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.
1026
1027 .. versionchanged:: 3.12
1028 Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning` when
1029 falling back to :attr:`!__package__` during import resolution.
1030
1031 .. deprecated-removed:: 3.13 3.15
1032 :attr:`!__package__` will cease to be set or taken into consideration
1033 by the import system or standard library.
1034
1035 .. attribute:: module.__loader__
1036
1037 The :term:`loader` object that the import machinery used to load the module.
1038
1039 This attribute is mostly useful for introspection, but can be used for
1040 additional loader-specific functionality, for example getting data
1041 associated with a loader.
1042
1043 :attr:`!__loader__` defaults to ``None`` for modules created dynamically
1044 using the :class:`types.ModuleType` constructor;
1045 use :func:`importlib.util.module_from_spec` instead to ensure the attribute
1046 is set to a :term:`loader` object.
1047
1048 It is **strongly** recommended that you use
1049 :attr:`module.__spec__.loader <importlib.machinery.ModuleSpec.loader>`
1050 instead of :attr:`!module.__loader__`.
1051
1052 .. versionchanged:: 3.4
1053 This attribute now defaults to ``None`` for modules created dynamically
1054 using the :class:`types.ModuleType` constructor.
1055 Previously the attribute was optional.
1056
1057 .. deprecated-removed:: 3.12 3.16
1058 Setting :attr:`!__loader__` on a module while failing to set
1059 :attr:`!__spec__.loader` is deprecated. In Python 3.16,
1060 :attr:`!__loader__` will cease to be set or taken into consideration by
1061 the import system or the standard library.
1062
1063 .. attribute:: module.__path__
1064
1065 A (possibly empty) :term:`sequence` of strings enumerating the locations
1066 where the package's submodules will be found. Non-package modules should
1067 not have a :attr:`!__path__` attribute. See :ref:`package-path-rules` for
1068 more details.
1069
1070 It is **strongly** recommended that you use
1071 :attr:`module.__spec__.submodule_search_locations <importlib.machinery.ModuleSpec.submodule_search_locations>`
1072 instead of :attr:`!module.__path__`.
1073
1074 .. attribute:: module.__file__
1075 .. attribute:: module.__cached__
1076
1077 :attr:`!__file__` and :attr:`!__cached__` are both optional attributes that
1078 may or may not be set. Both attributes should be a :class:`str` when they
1079 are available.
1080
1081 :attr:`!__file__` indicates the pathname of the file from which the module
1082 was loaded (if loaded from a file), or the pathname of the shared library
1083 file for extension modules loaded dynamically from a shared library.
1084 It might be missing for certain types of modules, such as C modules that are
1085 statically linked into the interpreter, and the
1086 :ref:`import system <importsystem>` may opt to leave it unset if it
1087 has no semantic meaning (for example, a module loaded from a database).
1088
1089 If :attr:`!__file__` is set then the :attr:`!__cached__` attribute might
1090 also be set, which is the path to any compiled version of
1091 the code (for example, a byte-compiled file). The file does not need to exist
1092 to set this attribute; the path can simply point to where the
1093 compiled file *would* exist (see :pep:`3147`).
1094
1095 Note that :attr:`!__cached__` may be set even if :attr:`!__file__` is not
1096 set. However, that scenario is quite atypical. Ultimately, the
1097 :term:`loader` is what makes use of the module spec provided by the
1098 :term:`finder` (from which :attr:`!__file__` and :attr:`!__cached__` are
1099 derived). So if a loader can load from a cached module but otherwise does
1100 not load from a file, that atypical scenario may be appropriate.
1101
1102 It is **strongly** recommended that you use
1103 :attr:`module.__spec__.cached <importlib.machinery.ModuleSpec.cached>`
1104 instead of :attr:`!module.__cached__`.
1105
1106 .. deprecated-removed:: 3.13 3.15
1107 Setting :attr:`!__cached__` on a module while failing to set
1108 :attr:`!__spec__.cached` is deprecated. In Python 3.15,
1109 :attr:`!__cached__` will cease to be set or taken into consideration by
1110 the import system or standard library.
1111
1112 Other writable attributes on module objects
1113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1114
1115 As well as the import-related attributes listed above, module objects also have
1116 the following writable attributes:
1117
1118 .. attribute:: module.__doc__
1119
1120 The module's documentation string, or ``None`` if unavailable.
1121 See also: :attr:`__doc__ attributes <definition.__doc__>`.
1122
1123 .. attribute:: module.__annotations__
1124
1125 A dictionary containing :term:`variable annotations <variable annotation>`
1126 collected during module body execution. For best practices on working with
1127 :attr:`!__annotations__`, see :mod:`annotationlib`.
1128
1129 .. versionchanged:: 3.14
1130 Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
1131 See :pep:`649`.
1132
1133 .. attribute:: module.__annotate__
1134
1135 The :term:`annotate function` for this module, or ``None`` if the module has
1136 no annotations. See also: :attr:`~object.__annotate__` attributes.
1137
1138 .. versionadded:: 3.14
1139
1140 Module dictionaries
1141 ^^^^^^^^^^^^^^^^^^^
1142
1143 Module objects also have the following special read-only attribute:
1144
1145 .. index:: single: __dict__ (module attribute)
1146 .. attribute:: module.__dict__
1147
1148 The module's namespace as a dictionary object. Uniquely among the attributes
1149 listed here, :attr:`!__dict__` cannot be accessed as a global variable from
1150 within a module; it can only be accessed as an attribute on module objects.
1151
1152 .. impl-detail::
1153
1154 Because of the way CPython clears module dictionaries, the module
1155 dictionary will be cleared when the module falls out of scope even if the
1156 dictionary still has live references. To avoid this, copy the dictionary
1157 or keep the module around while using its dictionary directly.
1158
1159
1160 .. _class-attrs-and-methods:
1161
1162 Custom classes
1163 --------------
1164
1165 Custom class types are typically created by class definitions (see section
1166 :ref:`class`). A class has a namespace implemented by a dictionary object.
1167 Class attribute references are translated to lookups in this dictionary, e.g.,
1168 ``C.x`` is translated to ``C.__dict__["x"]`` (although there are a number of
1169 hooks which allow for other means of locating attributes). When the attribute
1170 name is not found there, the attribute search continues in the base classes.
1171 This search of the base classes uses the C3 method resolution order which
1172 behaves correctly even in the presence of 'diamond' inheritance structures
1173 where there are multiple inheritance paths leading back to a common ancestor.
1174 Additional details on the C3 MRO used by Python can be found at
1175 :ref:`python_2.3_mro`.
1176
1177 .. index::
1178 pair: object; class
1179 pair: object; class instance
1180 pair: object; instance
1181 pair: class object; call
1182 single: container
1183 pair: object; dictionary
1184 pair: class; attribute
1185
1186 When a class attribute reference (for class :class:`!C`, say) would yield a
1187 class method object, it is transformed into an instance method object whose
1188 :attr:`~method.__self__` attribute is :class:`!C`.
1189 When it would yield a :class:`staticmethod` object,
1190 it is transformed into the object wrapped by the static method
1191 object. See section :ref:`descriptors` for another way in which attributes
1192 retrieved from a class may differ from those actually contained in its
1193 :attr:`~object.__dict__`.
1194
1195 .. index:: triple: class; attribute; assignment
1196
1197 Class attribute assignments update the class's dictionary, never the dictionary
1198 of a base class.
1199
1200 .. index:: pair: class object; call
1201
1202 A class object can be called (see above) to yield a class instance (see below).
1203
1204 Special attributes
1205 ^^^^^^^^^^^^^^^^^^
1206
1207 .. index::
1208 single: __name__ (class attribute)
1209 single: __module__ (class attribute)
1210 single: __dict__ (class attribute)
1211 single: __bases__ (class attribute)
1212 single: __base__ (class attribute)
1213 single: __doc__ (class attribute)
1214 single: __annotations__ (class attribute)
1215 single: __annotate__ (class attribute)
1216 single: __type_params__ (class attribute)
1217 single: __static_attributes__ (class attribute)
1218 single: __firstlineno__ (class attribute)
1219
1220 .. list-table::
1221 :header-rows: 1
1222
1223 * - Attribute
1224 - Meaning
1225
1226 * - .. attribute:: type.__name__
1227 - The class's name.
1228 See also: :attr:`__name__ attributes <definition.__name__>`.
1229
1230 * - .. attribute:: type.__qualname__
1231 - The class's :term:`qualified name`.
1232 See also: :attr:`__qualname__ attributes <definition.__qualname__>`.
1233
1234 * - .. attribute:: type.__module__
1235 - The name of the module in which the class was defined.
1236
1237 * - .. attribute:: type.__dict__
1238 - A :class:`mapping proxy <types.MappingProxyType>`
1239 providing a read-only view of the class's namespace.
1240 See also: :attr:`__dict__ attributes <object.__dict__>`.
1241
1242 * - .. attribute:: type.__bases__
1243 - A :class:`tuple` containing the class's bases.
1244 In most cases, for a class defined as ``class X(A, B, C)``,
1245 ``X.__bases__`` will be exactly equal to ``(A, B, C)``.
1246
1247 * - .. attribute:: type.__base__
1248 - .. impl-detail::
1249
1250 The single base class in the inheritance chain that is responsible
1251 for the memory layout of instances. This attribute corresponds to
1252 :c:member:`~PyTypeObject.tp_base` at the C level.
1253
1254 * - .. attribute:: type.__doc__
1255 - The class's documentation string, or ``None`` if undefined.
1256 Not inherited by subclasses.
1257
1258 * - .. attribute:: type.__annotations__
1259 - A dictionary containing
1260 :term:`variable annotations <variable annotation>`
1261 collected during class body execution. See also:
1262 :attr:`__annotations__ attributes <object.__annotations__>`.
1263
1264 For best practices on working with :attr:`~object.__annotations__`,
1265 please see :mod:`annotationlib`. Use
1266 :func:`annotationlib.get_annotations` instead of accessing this
1267 attribute directly.
1268
1269 .. warning::
1270
1271 Accessing the :attr:`!__annotations__` attribute directly
1272 on a class object may return annotations for the wrong class, specifically
1273 in certain cases where the class, its base class, or a metaclass
1274 is defined under ``from __future__ import annotations``.
1275 See :pep:`749 <749#pep749-metaclasses>` for details.
1276
1277 This attribute does not exist on certain builtin classes. On
1278 user-defined classes without ``__annotations__``, it is an
1279 empty dictionary.
1280
1281 .. versionchanged:: 3.14
1282 Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
1283 See :pep:`649`.
1284
1285 * - .. method:: type.__annotate__
1286 - The :term:`annotate function` for this class, or ``None``
1287 if the class has no annotations.
1288 See also: :attr:`__annotate__ attributes <object.__annotate__>`.
1289
1290 .. versionadded:: 3.14
1291
1292 * - .. attribute:: type.__type_params__
1293 - A :class:`tuple` containing the :ref:`type parameters <type-params>` of
1294 a :ref:`generic class <generic-classes>`.
1295
1296 .. versionadded:: 3.12
1297
1298 * - .. attribute:: type.__static_attributes__
1299 - A :class:`tuple` containing names of attributes of this class which are
1300 assigned through ``self.X`` from any function in its body.
1301
1302 .. versionadded:: 3.13
1303
1304 * - .. attribute:: type.__firstlineno__
1305 - The line number of the first line of the class definition,
1306 including decorators.
1307 Setting the :attr:`~type.__module__` attribute removes the
1308 :attr:`!__firstlineno__` item from the type's dictionary.
1309
1310 .. versionadded:: 3.13
1311
1312 * - .. attribute:: type.__mro__
1313 - The :class:`tuple` of classes that are considered when looking for
1314 base classes during method resolution.
1315
1316
1317 Special methods
1318 ^^^^^^^^^^^^^^^
1319
1320 In addition to the special attributes described above, all Python classes also
1321 have the following two methods available:
1322
1323 .. method:: type.mro
1324
1325 This method can be overridden by a metaclass to customize the method
1326 resolution order for its instances. It is called at class instantiation,
1327 and its result is stored in :attr:`~type.__mro__`.
1328
1329 .. method:: type.__subclasses__
1330
1331 Each class keeps a list of weak references to its immediate subclasses. This
1332 method returns a list of all those references still alive. The list is in
1333 definition order. Example:
1334
1335 .. doctest::
1336
1337 >>> class A: pass
1338 >>> class B(A): pass
1339 >>> A.__subclasses__()
1340 [<class 'B'>]
1341
1342 Class instances
1343 ---------------
1344
1345 .. index::
1346 pair: object; class instance
1347 pair: object; instance
1348 pair: class; instance
1349 pair: class instance; attribute
1350
1351 A class instance is created by calling a class object (see above). A class
1352 instance has a namespace implemented as a dictionary which is the first place
1353 in which attribute references are searched. When an attribute is not found
1354 there, and the instance's class has an attribute by that name, the search
1355 continues with the class attributes. If a class attribute is found that is a
1356 user-defined function object, it is transformed into an instance method
1357 object whose :attr:`~method.__self__` attribute is the instance. Static method and
1358 class method objects are also transformed; see above under "Classes". See
1359 section :ref:`descriptors` for another way in which attributes of a class
1360 retrieved via its instances may differ from the objects actually stored in
1361 the class's :attr:`~object.__dict__`. If no class attribute is found, and the
1362 object's class has a :meth:`~object.__getattr__` method, that is called to satisfy
1363 the lookup.
1364
1365 .. index:: triple: class instance; attribute; assignment
1366
1367 Attribute assignments and deletions update the instance's dictionary, never a
1368 class's dictionary. If the class has a :meth:`~object.__setattr__` or
1369 :meth:`~object.__delattr__` method, this is called instead of updating the instance
1370 dictionary directly.
1371
1372 .. index::
1373 pair: object; numeric
1374 pair: object; sequence
1375 pair: object; mapping
1376
1377 Class instances can pretend to be numbers, sequences, or mappings if they have
1378 methods with certain special names. See section :ref:`specialnames`.
1379
1380 Special attributes
1381 ^^^^^^^^^^^^^^^^^^
1382
1383 .. index::
1384 single: __dict__ (instance attribute)
1385 single: __class__ (instance attribute)
1386
1387 .. attribute:: object.__class__
1388
1389 The class to which a class instance belongs.
1390
1391 .. attribute:: object.__dict__
1392
1393 A dictionary or other mapping object used to store an object's (writable)
1394 attributes. Not all instances have a :attr:`!__dict__` attribute; see the
1395 section on :ref:`slots` for more details.
1396
1397
1398 I/O objects (also known as file objects)
1399 ----------------------------------------
1400
1401 .. index::
1402 pair: built-in function; open
1403 pair: module; io
1404 single: popen() (in module os)
1405 single: makefile() (socket method)
1406 single: sys.stdin
1407 single: sys.stdout
1408 single: sys.stderr
1409 single: stdio
1410 single: stdin (in module sys)
1411 single: stdout (in module sys)
1412 single: stderr (in module sys)
1413
1414 A :term:`file object` represents an open file. Various shortcuts are
1415 available to create file objects: the :func:`open` built-in function, and
1416 also :func:`os.popen`, :func:`os.fdopen`, and the
1417 :meth:`~socket.socket.makefile` method of socket objects (and perhaps by
1418 other functions or methods provided by extension modules).
1419
1420 File objects implement common methods, listed below, to simplify usage in
1421 generic code. They are expected to be :ref:`context-managers`.
1422
1423 The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are
1424 initialized to file objects corresponding to the interpreter's standard
1425 input, output and error streams; they are all open in text mode and
1426 therefore follow the interface defined by the :class:`io.TextIOBase`
1427 abstract class.
1428
1429 .. method:: file.read(size=-1, /)
1430
1431 Retrieve up to *size* data from the file. As a convenience if *size* is
1432 unspecified or -1 retrieve all data available.
1433
1434 .. method:: file.write(data, /)
1435
1436 Store *data* to the file.
1437
1438 .. method:: file.close()
1439
1440 Flush any buffers and close the underlying file.
1441
1442
1443 Internal types
1444 --------------
1445
1446 .. index::
1447 single: internal type
1448 single: types, internal
1449
1450 A few types used internally by the interpreter are exposed to the user. Their
1451 definitions may change with future versions of the interpreter, but they are
1452 mentioned here for completeness.
1453
1454
1455 .. _code-objects:
1456
1457 Code objects
1458 ^^^^^^^^^^^^
1459
1460 .. index:: bytecode, object; code, code object
1461
1462 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
1463 The difference between a code object and a function object is that the function
1464 object contains an explicit reference to the function's globals (the module in
1465 which it was defined), while a code object contains no context; also the default
1466 argument values are stored in the function object, not in the code object
1467 (because they represent values calculated at run-time). Unlike function
1468 objects, code objects are immutable and contain no references (directly or
1469 indirectly) to mutable objects.
1470
1471 .. index::
1472 single: co_argcount (code object attribute)
1473 single: co_posonlyargcount (code object attribute)
1474 single: co_kwonlyargcount (code object attribute)
1475 single: co_code (code object attribute)
1476 single: co_consts (code object attribute)
1477 single: co_filename (code object attribute)
1478 single: co_firstlineno (code object attribute)
1479 single: co_flags (code object attribute)
1480 single: co_lnotab (code object attribute)
1481 single: co_name (code object attribute)
1482 single: co_names (code object attribute)
1483 single: co_nlocals (code object attribute)
1484 single: co_stacksize (code object attribute)
1485 single: co_varnames (code object attribute)
1486 single: co_cellvars (code object attribute)
1487 single: co_freevars (code object attribute)
1488 single: co_qualname (code object attribute)
1489
1490 Special read-only attributes
1491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1492
1493 .. list-table::
1494
1495 * - .. attribute:: codeobject.co_name
1496 - The function name
1497
1498 * - .. attribute:: codeobject.co_qualname
1499 - The fully qualified function name
1500
1501 .. versionadded:: 3.11
1502
1503 * - .. attribute:: codeobject.co_argcount
1504 - The total number of positional :term:`parameters <parameter>`
1505 (including positional-only parameters and parameters with default values)
1506 that the function has
1507
1508 * - .. attribute:: codeobject.co_posonlyargcount
1509 - The number of positional-only :term:`parameters <parameter>`
1510 (including arguments with default values) that the function has
1511
1512 * - .. attribute:: codeobject.co_kwonlyargcount
1513 - The number of keyword-only :term:`parameters <parameter>`
1514 (including arguments with default values) that the function has
1515
1516 * - .. attribute:: codeobject.co_nlocals
1517 - The number of :ref:`local variables <naming>` used by the function
1518 (including parameters)
1519
1520 * - .. attribute:: codeobject.co_varnames
1521 - A :class:`tuple` containing the names of the local variables in the
1522 function (starting with the parameter names)
1523
1524 * - .. attribute:: codeobject.co_cellvars
1525 - A :class:`tuple` containing the names of :ref:`local variables <naming>`
1526 that are referenced from at least one :term:`nested scope` inside the function
1527
1528 * - .. attribute:: codeobject.co_freevars
1529 - A :class:`tuple` containing the names of
1530 :term:`free (closure) variables <closure variable>` that a :term:`nested scope`
1531 references in an outer scope. See also :attr:`function.__closure__`.
1532
1533 Note: references to global and builtin names are *not* included.
1534
1535 * - .. attribute:: codeobject.co_code
1536 - A string representing the sequence of :term:`bytecode` instructions in
1537 the function
1538
1539 * - .. attribute:: codeobject.co_consts
1540 - A :class:`tuple` containing the literals used by the :term:`bytecode` in
1541 the function
1542
1543 * - .. attribute:: codeobject.co_names
1544 - A :class:`tuple` containing the names used by the :term:`bytecode` in
1545 the function
1546
1547 * - .. attribute:: codeobject.co_filename
1548 - The name of the file from which the code was compiled
1549
1550 * - .. attribute:: codeobject.co_firstlineno
1551 - The line number of the first line of the function
1552
1553 * - .. attribute:: codeobject.co_lnotab
1554 - A string encoding the mapping from :term:`bytecode` offsets to line
1555 numbers. For details, see the source code of the interpreter.
1556
1557 .. deprecated:: 3.12
1558 This attribute of code objects is deprecated, and may be removed in
1559 Python 3.15.
1560
1561 * - .. attribute:: codeobject.co_stacksize
1562 - The required stack size of the code object
1563
1564 * - .. attribute:: codeobject.co_flags
1565 - An :class:`integer <int>` encoding a number of flags for the
1566 interpreter.
1567
1568 .. index:: pair: object; generator
1569
1570 The following flag bits are defined for :attr:`~codeobject.co_flags`:
1571 bit ``0x04`` is set if
1572 the function uses the ``*arguments`` syntax to accept an arbitrary number of
1573 positional arguments; bit ``0x08`` is set if the function uses the
1574 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
1575 if the function is a generator. See :ref:`inspect-module-co-flags` for details
1576 on the semantics of each flags that might be present.
1577
1578 Future feature declarations (for example, ``from __future__ import division``) also use bits
1579 in :attr:`~codeobject.co_flags` to indicate whether a code object was compiled with a
1580 particular feature enabled. See :attr:`~__future__._Feature.compiler_flag`.
1581
1582 Other bits in :attr:`~codeobject.co_flags` are reserved for internal use.
1583
1584 .. index:: single: documentation string
1585
1586 If a code object represents a function and has a docstring,
1587 the :data:`~inspect.CO_HAS_DOCSTRING` bit is set in :attr:`~codeobject.co_flags`
1588 and the first item in :attr:`~codeobject.co_consts` is
1589 the docstring of the function.
1590
1591 Methods on code objects
1592 ~~~~~~~~~~~~~~~~~~~~~~~
1593
1594 .. method:: codeobject.co_positions()
1595
1596 Returns an iterable over the source code positions of each :term:`bytecode`
1597 instruction in the code object.
1598
1599 The iterator returns :class:`tuple`\s containing the ``(start_line, end_line,
1600 start_column, end_column)``. The *i-th* tuple corresponds to the
1601 position of the source code that compiled to the *i-th* code unit.
1602 Column information is 0-indexed utf-8 byte offsets on the given source
1603 line.
1604
1605 This positional information can be missing. A non-exhaustive lists of
1606 cases where this may happen:
1607
1608 - Running the interpreter with :option:`-X` ``no_debug_ranges``.
1609 - Loading a pyc file compiled while using :option:`-X` ``no_debug_ranges``.
1610 - Position tuples corresponding to artificial instructions.
1611 - Line and column numbers that can't be represented due to
1612 implementation specific limitations.
1613
1614 When this occurs, some or all of the tuple elements can be
1615 :const:`None`.
1616
1617 .. versionadded:: 3.11
1618
1619 .. note::
1620 This feature requires storing column positions in code objects which may
1621 result in a small increase of disk usage of compiled Python files or
1622 interpreter memory usage. To avoid storing the extra information and/or
1623 deactivate printing the extra traceback information, the
1624 :option:`-X` ``no_debug_ranges`` command line flag or the :envvar:`PYTHONNODEBUGRANGES`
1625 environment variable can be used.
1626
1627 .. method:: codeobject.co_lines()
1628
1629 Returns an iterator that yields information about successive ranges of
1630 :term:`bytecode`\s. Each item yielded is a ``(start, end, lineno)``
1631 :class:`tuple`:
1632
1633 * ``start`` (an :class:`int`) represents the offset (inclusive) of the start
1634 of the :term:`bytecode` range
1635 * ``end`` (an :class:`int`) represents the offset (exclusive) of the end of
1636 the :term:`bytecode` range
1637 * ``lineno`` is an :class:`int` representing the line number of the
1638 :term:`bytecode` range, or ``None`` if the bytecodes in the given range
1639 have no line number
1640
1641 The items yielded will have the following properties:
1642
1643 * The first range yielded will have a ``start`` of 0.
1644 * The ``(start, end)`` ranges will be non-decreasing and consecutive. That
1645 is, for any pair of :class:`tuple`\s, the ``start`` of the second will be
1646 equal to the ``end`` of the first.
1647 * No range will be backwards: ``end >= start`` for all triples.
1648 * The last :class:`tuple` yielded will have ``end`` equal to the size of the
1649 :term:`bytecode`.
1650
1651 Zero-width ranges, where ``start == end``, are allowed. Zero-width ranges
1652 are used for lines that are present in the source code, but have been
1653 eliminated by the :term:`bytecode` compiler.
1654
1655 .. versionadded:: 3.10
1656
1657 .. seealso::
1658
1659 :pep:`626` - Precise line numbers for debugging and other tools.
1660 The PEP that introduced the :meth:`!co_lines` method.
1661
1662 .. method:: codeobject.replace(**kwargs)
1663
1664 Return a copy of the code object with new values for the specified fields.
1665
1666 Code objects are also supported by the generic function :func:`copy.replace`.
1667
1668 .. versionadded:: 3.8
1669
1670
1671 .. _frame-objects:
1672
1673 Frame objects
1674 ^^^^^^^^^^^^^
1675
1676 .. index:: pair: object; frame
1677
1678 Frame objects represent execution frames. They may occur in
1679 :ref:`traceback objects <traceback-objects>`,
1680 and are also passed to registered trace functions.
1681
1682 .. index::
1683 single: f_back (frame attribute)
1684 single: f_code (frame attribute)
1685 single: f_globals (frame attribute)
1686 single: f_locals (frame attribute)
1687 single: f_lasti (frame attribute)
1688 single: f_builtins (frame attribute)
1689 single: f_generator (frame attribute)
1690
1691 Special read-only attributes
1692 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1693
1694 .. list-table::
1695
1696 * - .. attribute:: frame.f_back
1697 - Points to the previous stack frame (towards the caller),
1698 or ``None`` if this is the bottom stack frame
1699
1700 * - .. attribute:: frame.f_code
1701 - The :ref:`code object <code-objects>` being executed in this frame.
1702 Accessing this attribute raises an :ref:`auditing event <auditing>`
1703 ``object.__getattr__`` with arguments ``obj`` and ``"f_code"``.
1704
1705 * - .. attribute:: frame.f_locals
1706 - The mapping used by the frame to look up
1707 :ref:`local variables <naming>`.
1708 If the frame refers to an :term:`optimized scope`,
1709 this may return a write-through proxy object.
1710
1711 .. versionchanged:: 3.13
1712 Return a proxy for optimized scopes.
1713
1714 * - .. attribute:: frame.f_globals
1715 - The dictionary used by the frame to look up
1716 :ref:`global variables <naming>`
1717
1718 * - .. attribute:: frame.f_builtins
1719 - The dictionary used by the frame to look up
1720 :ref:`built-in (intrinsic) names <naming>`
1721
1722 * - .. attribute:: frame.f_lasti
1723 - The "precise instruction" of the frame object
1724 (this is an index into the :term:`bytecode` string of the
1725 :ref:`code object <code-objects>`)
1726
1727 * - .. attribute:: frame.f_generator
1728 - The :term:`generator` or :term:`coroutine` object that owns this frame,
1729 or ``None`` if the frame is a normal function.
1730
1731 .. versionadded:: 3.14
1732
1733 .. index::
1734 single: f_trace (frame attribute)
1735 single: f_trace_lines (frame attribute)
1736 single: f_trace_opcodes (frame attribute)
1737 single: f_lineno (frame attribute)
1738
1739 Special writable attributes
1740 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1741
1742 .. list-table::
1743
1744 * - .. attribute:: frame.f_trace
1745 - If not ``None``, this is a function called for various events during
1746 code execution (this is used by debuggers). Normally an event is
1747 triggered for each new source line (see :attr:`~frame.f_trace_lines`).
1748
1749 * - .. attribute:: frame.f_trace_lines
1750 - Set this attribute to :const:`False` to disable triggering a tracing
1751 event for each source line.
1752
1753 * - .. attribute:: frame.f_trace_opcodes
1754 - Set this attribute to :const:`True` to allow per-opcode events to be
1755 requested. Note that this may lead to
1756 undefined interpreter behaviour if exceptions raised by the trace
1757 function escape to the function being traced.
1758
1759 * - .. attribute:: frame.f_lineno
1760 - The current line number of the frame -- writing to this
1761 from within a trace function jumps to the given line (only for the bottom-most
1762 frame). A debugger can implement a Jump command (aka Set Next Statement)
1763 by writing to this attribute.
1764
1765 Frame object methods
1766 ~~~~~~~~~~~~~~~~~~~~
1767
1768 Frame objects support one method:
1769
1770 .. method:: frame.clear()
1771
1772 This method clears all references to :ref:`local variables <naming>` held by the
1773 frame. Also, if the frame belonged to a :term:`generator`, the generator
1774 is finalized. This helps break reference cycles involving frame
1775 objects (for example when catching an :ref:`exception <bltin-exceptions>`
1776 and storing its :ref:`traceback <traceback-objects>` for later use).
1777
1778 :exc:`RuntimeError` is raised if the frame is currently executing
1779 or suspended.
1780
1781 .. versionadded:: 3.4
1782
1783 .. versionchanged:: 3.13
1784 Attempting to clear a suspended frame raises :exc:`RuntimeError`
1785 (as has always been the case for executing frames).
1786
1787
1788 .. _traceback-objects:
1789
1790 Traceback objects
1791 ^^^^^^^^^^^^^^^^^
1792
1793 .. index::
1794 pair: object; traceback
1795 pair: stack; trace
1796 pair: exception; handler
1797 pair: execution; stack
1798 single: exc_info (in module sys)
1799 single: last_traceback (in module sys)
1800 single: sys.exc_info
1801 single: sys.exception
1802 single: sys.last_traceback
1803
1804 Traceback objects represent the stack trace of an :ref:`exception <tut-errors>`.
1805 A traceback object
1806 is implicitly created when an exception occurs, and may also be explicitly
1807 created by calling :class:`types.TracebackType`.
1808
1809 .. versionchanged:: 3.7
1810 Traceback objects can now be explicitly instantiated from Python code.
1811
1812 For implicitly created tracebacks, when the search for an exception handler
1813 unwinds the execution stack, at each unwound level a traceback object is
1814 inserted in front of the current traceback. When an exception handler is
1815 entered, the stack trace is made available to the program. (See section
1816 :ref:`try`.) It is accessible as the third item of the
1817 tuple returned by :func:`sys.exc_info`, and as the
1818 :attr:`~BaseException.__traceback__` attribute
1819 of the caught exception.
1820
1821 When the program contains no suitable
1822 handler, the stack trace is written (nicely formatted) to the standard error
1823 stream; if the interpreter is interactive, it is also made available to the user
1824 as :data:`sys.last_traceback`.
1825
1826 For explicitly created tracebacks, it is up to the creator of the traceback
1827 to determine how the :attr:`~traceback.tb_next` attributes should be linked to
1828 form a full stack trace.
1829
1830 .. index::
1831 single: tb_frame (traceback attribute)
1832 single: tb_lineno (traceback attribute)
1833 single: tb_lasti (traceback attribute)
1834 pair: statement; try
1835
1836 Special read-only attributes:
1837
1838 .. list-table::
1839
1840 * - .. attribute:: traceback.tb_frame
1841 - Points to the execution :ref:`frame <frame-objects>` of the current
1842 level.
1843
1844 Accessing this attribute raises an
1845 :ref:`auditing event <auditing>` ``object.__getattr__`` with arguments
1846 ``obj`` and ``"tb_frame"``.
1847
1848 * - .. attribute:: traceback.tb_lineno
1849 - Gives the line number where the exception occurred
1850
1851 * - .. attribute:: traceback.tb_lasti
1852 - Indicates the "precise instruction".
1853
1854 The line number and last instruction in the traceback may differ from the
1855 line number of its :ref:`frame object <frame-objects>` if the exception
1856 occurred in a
1857 :keyword:`try` statement with no matching except clause or with a
1858 :keyword:`finally` clause.
1859
1860 .. index::
1861 single: tb_next (traceback attribute)
1862
1863 .. attribute:: traceback.tb_next
1864
1865 The special writable attribute :attr:`!tb_next` is the next level in the
1866 stack trace (towards the frame where the exception occurred), or ``None`` if
1867 there is no next level.
1868
1869 .. versionchanged:: 3.7
1870 This attribute is now writable
1871
1872
1873 Slice objects
1874 ^^^^^^^^^^^^^
1875
1876 .. index:: pair: built-in function; slice
1877
1878 Slice objects are used to represent slices for
1879 :meth:`~object.__getitem__`
1880 methods. They are also created by the built-in :func:`slice` function.
1881
1882 .. index::
1883 single: start (slice object attribute)
1884 single: stop (slice object attribute)
1885 single: step (slice object attribute)
1886
1887 Special read-only attributes: :attr:`~slice.start` is the lower bound;
1888 :attr:`~slice.stop` is the upper bound; :attr:`~slice.step` is the step
1889 value; each is ``None`` if omitted. These attributes can have any type.
1890
1891 Slice objects support one method:
1892
1893 .. method:: slice.indices(self, length)
1894
1895 This method takes a single integer argument *length* and computes
1896 information about the slice that the slice object would describe if
1897 applied to a sequence of *length* items. It returns a tuple of three
1898 integers; respectively these are the *start* and *stop* indices and the
1899 *step* or stride length of the slice. Missing or out-of-bounds indices
1900 are handled in a manner consistent with regular slices.
1901
1902
1903 Static method objects
1904 ^^^^^^^^^^^^^^^^^^^^^
1905
1906 Static method objects provide a way of defeating the transformation of function
1907 objects to method objects described above. A static method object is a wrapper
1908 around any other object, usually a user-defined method object. When a static
1909 method object is retrieved from a class or a class instance, the object actually
1910 returned is the wrapped object, which is not subject to any further
1911 transformation. Static method objects are also callable. Static method
1912 objects are created by the built-in :func:`staticmethod` constructor.
1913
1914
1915 Class method objects
1916 ^^^^^^^^^^^^^^^^^^^^
1917
1918 A class method object, like a static method object, is a wrapper around another
1919 object that alters the way in which that object is retrieved from classes and
1920 class instances. The behaviour of class method objects upon such retrieval is
1921 described above, under :ref:`"instance methods" <instance-methods>`. Class method objects are created
1922 by the built-in :func:`classmethod` constructor.
1923
1924
1925 .. _specialnames:
1926
1927 Special method names
1928 ====================
1929
1930 .. index::
1931 pair: operator; overloading
1932 single: __getitem__() (mapping object method)
1933
1934 A class can implement certain operations that are invoked by special syntax
1935 (such as arithmetic operations or subscripting and slicing) by defining methods
1936 with special names. This is Python's approach to :dfn:`operator overloading`,
1937 allowing classes to define their own behavior with respect to language
1938 operators. For instance, if a class defines a method named
1939 :meth:`~object.__getitem__`,
1940 and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
1941 to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an
1942 operation raise an exception when no appropriate method is defined (typically
1943 :exc:`AttributeError` or :exc:`TypeError`).
1944
1945 Setting a special method to ``None`` indicates that the corresponding
1946 operation is not available. For example, if a class sets
1947 :meth:`~object.__iter__` to ``None``, the class is not iterable, so calling
1948 :func:`iter` on its instances will raise a :exc:`TypeError` (without
1949 falling back to :meth:`~object.__getitem__`). [#]_
1950
1951 When implementing a class that emulates any built-in type, it is important that
1952 the emulation only be implemented to the degree that it makes sense for the
1953 object being modelled. For example, some sequences may work well with retrieval
1954 of individual elements, but extracting a slice may not make sense.
1955 (One example of this is the :ref:`NodeList <dom-nodelist-objects>` interface
1956 in the W3C's Document Object Model.)
1957
1958
1959 .. _customization:
1960
1961 Basic customization
1962 -------------------
1963
1964 .. method:: object.__new__(cls[, ...])
1965
1966 .. index:: pair: subclassing; immutable types
1967
1968 Called to create a new instance of class *cls*. :meth:`__new__` is a static
1969 method (special-cased so you need not declare it as such) that takes the class
1970 of which an instance was requested as its first argument. The remaining
1971 arguments are those passed to the object constructor expression (the call to the
1972 class). The return value of :meth:`__new__` should be the new object instance
1973 (usually an instance of *cls*).
1974
1975 Typical implementations create a new instance of the class by invoking the
1976 superclass's :meth:`__new__` method using ``super().__new__(cls[, ...])``
1977 with appropriate arguments and then modifying the newly created instance
1978 as necessary before returning it.
1979
1980 If :meth:`__new__` is invoked during object construction and it returns an
1981 instance of *cls*, then the new instance’s :meth:`__init__` method
1982 will be invoked like ``__init__(self[, ...])``, where *self* is the new instance
1983 and the remaining arguments are the same as were passed to the object constructor.
1984
1985 If :meth:`__new__` does not return an instance of *cls*, then the new instance's
1986 :meth:`__init__` method will not be invoked.
1987
1988 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
1989 int, str, or tuple) to customize instance creation. It is also commonly
1990 overridden in custom metaclasses in order to customize class creation.
1991
1992
1993 .. method:: object.__init__(self[, ...])
1994
1995 .. index:: pair: class; constructor
1996
1997 Called after the instance has been created (by :meth:`__new__`), but before
1998 it is returned to the caller. The arguments are those passed to the
1999 class constructor expression. If a base class has an :meth:`__init__`
2000 method, the derived class's :meth:`__init__` method, if any, must explicitly
2001 call it to ensure proper initialization of the base class part of the
2002 instance; for example: ``super().__init__([args...])``.
2003
2004 Because :meth:`__new__` and :meth:`__init__` work together in constructing
2005 objects (:meth:`__new__` to create it, and :meth:`__init__` to customize it),
2006 no non-``None`` value may be returned by :meth:`__init__`; doing so will
2007 cause a :exc:`TypeError` to be raised at runtime.
2008
2009
2010 .. method:: object.__del__(self)
2011
2012 .. index::
2013 single: destructor
2014 single: finalizer
2015 pair: statement; del
2016
2017 Called when the instance is about to be destroyed. This is also called a
2018 finalizer or (improperly) a destructor. If a base class has a
2019 :meth:`__del__` method, the derived class's :meth:`__del__` method,
2020 if any, must explicitly call it to ensure proper deletion of the base
2021 class part of the instance.
2022
2023 It is possible (though not recommended!) for the :meth:`__del__` method
2024 to postpone destruction of the instance by creating a new reference to
2025 it. This is called object *resurrection*. It is implementation-dependent
2026 whether :meth:`__del__` is called a second time when a resurrected object
2027 is about to be destroyed; the current :term:`CPython` implementation
2028 only calls it once.
2029
2030 It is not guaranteed that :meth:`__del__` methods are called for objects
2031 that still exist when the interpreter exits.
2032 :class:`weakref.finalize` provides a straightforward way to register
2033 a cleanup function to be called when an object is garbage collected.
2034
2035 .. note::
2036
2037 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
2038 the reference count for ``x`` by one, and the latter is only called when
2039 ``x``'s reference count reaches zero.
2040
2041 .. impl-detail::
2042 It is possible for a reference cycle to prevent the reference count
2043 of an object from going to zero. In this case, the cycle will be
2044 later detected and deleted by the :term:`cyclic garbage collector
2045 <garbage collection>`. A common cause of reference cycles is when
2046 an exception has been caught in a local variable. The frame's
2047 locals then reference the exception, which references its own
2048 traceback, which references the locals of all frames caught in the
2049 traceback.
2050
2051 .. seealso::
2052 Documentation for the :mod:`gc` module.
2053
2054 .. warning::
2055
2056 Due to the precarious circumstances under which :meth:`__del__` methods are
2057 invoked, exceptions that occur during their execution are ignored, and a warning
2058 is printed to ``sys.stderr`` instead. In particular:
2059
2060 * :meth:`__del__` can be invoked when arbitrary code is being executed,
2061 including from any arbitrary thread. If :meth:`__del__` needs to take
2062 a lock or invoke any other blocking resource, it may deadlock as
2063 the resource may already be taken by the code that gets interrupted
2064 to execute :meth:`__del__`.
2065
2066 * :meth:`__del__` can be executed during interpreter shutdown. As a
2067 consequence, the global variables it needs to access (including other
2068 modules) may already have been deleted or set to ``None``. Python
2069 guarantees that globals whose name begins with a single underscore
2070 are deleted from their module before other globals are deleted; if
2071 no other references to such globals exist, this may help in assuring
2072 that imported modules are still available at the time when the
2073 :meth:`__del__` method is called.
2074
2075
2076 .. index::
2077 single: repr() (built-in function); __repr__() (object method)
2078
2079 .. method:: object.__repr__(self)
2080
2081 Called by the :func:`repr` built-in function to compute the "official" string
2082 representation of an object. If at all possible, this should look like a
2083 valid Python expression that could be used to recreate an object with the
2084 same value (given an appropriate environment). If this is not possible, a
2085 string of the form ``<...some useful description...>`` should be returned.
2086 The return value must be a string object. If a class defines :meth:`__repr__`
2087 but not :meth:`__str__`, then :meth:`__repr__` is also used when an
2088 "informal" string representation of instances of that class is required.
2089
2090 This is typically used for debugging, so it is important that the representation
2091 is information-rich and unambiguous. A default implementation is provided by the
2092 :class:`object` class itself.
2093
2094 .. index::
2095 single: string; __str__() (object method)
2096 single: format() (built-in function); __str__() (object method)
2097 single: print() (built-in function); __str__() (object method)
2098
2099
2100 .. method:: object.__str__(self)
2101
2102 Called by :func:`str(object) <str>`, the default :meth:`__format__` implementation,
2103 and the built-in function :func:`print`, to compute the "informal" or nicely
2104 printable string representation of an object. The return value must be a
2105 :ref:`str <textseq>` object.
2106
2107 This method differs from :meth:`object.__repr__` in that there is no
2108 expectation that :meth:`__str__` return a valid Python expression: a more
2109 convenient or concise representation can be used.
2110
2111 The default implementation defined by the built-in type :class:`object`
2112 calls :meth:`object.__repr__`.
2113
2114 .. XXX what about subclasses of string?
2115
2116
2117 .. method:: object.__bytes__(self)
2118
2119 .. index:: pair: built-in function; bytes
2120
2121 Called by :ref:`bytes <func-bytes>` to compute a byte-string representation
2122 of an object. This should return a :class:`bytes` object. The :class:`object`
2123 class itself does not provide this method.
2124
2125 .. index::
2126 single: string; __format__() (object method)
2127 pair: string; conversion
2128 pair: built-in function; print
2129
2130
2131 .. method:: object.__format__(self, format_spec)
2132
2133 Called by the :func:`format` built-in function,
2134 and by extension, evaluation of :ref:`formatted string literals
2135 <f-strings>` and the :meth:`str.format` method, to produce a "formatted"
2136 string representation of an object. The *format_spec* argument is
2137 a string that contains a description of the formatting options desired.
2138 The interpretation of the *format_spec* argument is up to the type
2139 implementing :meth:`__format__`, however most classes will either
2140 delegate formatting to one of the built-in types, or use a similar
2141 formatting option syntax.
2142
2143 See :ref:`formatspec` for a description of the standard formatting syntax.
2144
2145 The return value must be a string object.
2146
2147 The default implementation by the :class:`object` class should be given
2148 an empty *format_spec* string. It delegates to :meth:`__str__`.
2149
2150 .. versionchanged:: 3.4
2151 The __format__ method of ``object`` itself raises a :exc:`TypeError`
2152 if passed any non-empty string.
2153
2154 .. versionchanged:: 3.7
2155 ``object.__format__(x, '')`` is now equivalent to ``str(x)`` rather
2156 than ``format(str(x), '')``.
2157
2158
2159 .. _richcmpfuncs:
2160 .. method:: object.__lt__(self, other)
2161 object.__le__(self, other)
2162 object.__eq__(self, other)
2163 object.__ne__(self, other)
2164 object.__gt__(self, other)
2165 object.__ge__(self, other)
2166
2167 .. index::
2168 single: comparisons
2169
2170 These are the so-called "rich comparison" methods. The correspondence between
2171 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
2172 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls
2173 ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
2174 ``x.__ge__(y)``.
2175
2176 A rich comparison method may return the singleton :data:`NotImplemented` if it does
2177 not implement the operation for a given pair of arguments. By convention,
2178 ``False`` and ``True`` are returned for a successful comparison. However, these
2179 methods can return any value, so if the comparison operator is used in a Boolean
2180 context (e.g., in the condition of an ``if`` statement), Python will call
2181 :func:`bool` on the value to determine if the result is true or false.
2182
2183 By default, ``object`` implements :meth:`__eq__` by using ``is``, returning
2184 :data:`NotImplemented` in the case of a false comparison:
2185 ``True if x is y else NotImplemented``. For :meth:`__ne__`, by default it
2186 delegates to :meth:`__eq__` and inverts the result unless it is
2187 :data:`!NotImplemented`. There are no other implied relationships among the
2188 comparison operators or default implementations; for example, the truth of
2189 ``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering
2190 operations from a single root operation, see :func:`functools.total_ordering`.
2191
2192 By default, the :class:`object` class provides implementations consistent
2193 with :ref:`expressions-value-comparisons`: equality compares according to
2194 object identity, and order comparisons raise :exc:`TypeError`. Each default
2195 method may generate these results directly, but may also return
2196 :data:`NotImplemented`.
2197
2198 See the paragraph on :meth:`__hash__` for
2199 some important notes on creating :term:`hashable` objects which support
2200 custom comparison operations and are usable as dictionary keys.
2201
2202 There are no swapped-argument versions of these methods (to be used when the
2203 left argument does not support the operation but the right argument does);
2204 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
2205 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
2206 :meth:`__eq__` and :meth:`__ne__` are their own reflection.
2207 If the operands are of different types, and the right operand's type is
2208 a direct or indirect subclass of the left operand's type,
2209 the reflected method of the right operand has priority, otherwise
2210 the left operand's method has priority. Virtual subclassing is
2211 not considered.
2212
2213 When no appropriate method returns any value other than :data:`NotImplemented`, the
2214 ``==`` and ``!=`` operators will fall back to ``is`` and ``is not``, respectively.
2215
2216 .. method:: object.__hash__(self)
2217
2218 .. index::
2219 pair: object; dictionary
2220 pair: built-in function; hash
2221
2222 Called by built-in function :func:`hash` and for operations on members of
2223 hashed collections including :class:`set`, :class:`frozenset`, and
2224 :class:`dict`. The ``__hash__()`` method should return an integer. The only required
2225 property is that objects which compare equal have the same hash value; it is
2226 advised to mix together the hash values of the components of the object that
2227 also play a part in comparison of objects by packing them into a tuple and
2228 hashing the tuple. Example::
2229
2230 def __hash__(self):
2231 return hash((self.name, self.nick, self.color))
2232
2233 .. note::
2234
2235 :func:`hash` truncates the value returned from an object's custom
2236 :meth:`__hash__` method to the size of a :c:type:`Py_ssize_t`. This is
2237 typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds. If an
2238 object's :meth:`__hash__` must interoperate on builds of different bit
2239 sizes, be sure to check the width on all supported builds. An easy way
2240 to do this is with
2241 ``python -c "import sys; print(sys.hash_info.width)"``.
2242
2243 If a class does not define an :meth:`__eq__` method it should not define a
2244 :meth:`__hash__` operation either; if it defines :meth:`__eq__` but not
2245 :meth:`__hash__`, its instances will not be usable as items in hashable
2246 collections. If a class defines mutable objects and implements an
2247 :meth:`__eq__` method, it should not implement :meth:`__hash__`, since the
2248 implementation of :term:`hashable` collections requires that a key's hash value is
2249 immutable (if the object's hash value changes, it will be in the wrong hash
2250 bucket).
2251
2252 User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods
2253 by default (inherited from the :class:`object` class); with them, all objects compare
2254 unequal (except with themselves) and ``x.__hash__()`` returns an appropriate
2255 value such that ``x == y`` implies both that ``x is y`` and ``hash(x) == hash(y)``.
2256
2257 A class that overrides :meth:`__eq__` and does not define :meth:`__hash__`
2258 will have its :meth:`__hash__` implicitly set to ``None``. When the
2259 :meth:`__hash__` method of a class is ``None``, instances of the class will
2260 raise an appropriate :exc:`TypeError` when a program attempts to retrieve
2261 their hash value, and will also be correctly identified as unhashable when
2262 checking ``isinstance(obj, collections.abc.Hashable)``.
2263
2264 If a class that overrides :meth:`__eq__` needs to retain the implementation
2265 of :meth:`__hash__` from a parent class, the interpreter must be told this
2266 explicitly by setting ``__hash__ = <ParentClass>.__hash__``.
2267
2268 If a class that does not override :meth:`__eq__` wishes to suppress hash
2269 support, it should include ``__hash__ = None`` in the class definition.
2270 A class which defines its own :meth:`__hash__` that explicitly raises
2271 a :exc:`TypeError` would be incorrectly identified as hashable by
2272 an ``isinstance(obj, collections.abc.Hashable)`` call.
2273
2274
2275 .. note::
2276
2277 By default, the :meth:`__hash__` values of str and bytes objects are
2278 "salted" with an unpredictable random value. Although they
2279 remain constant within an individual Python process, they are not
2280 predictable between repeated invocations of Python.
2281
2282 This is intended to provide protection against a denial-of-service caused
2283 by carefully chosen inputs that exploit the worst case performance of a
2284 dict insertion, *O*\ (*n*\ :sup:`2`) complexity. See
2285 https://ocert.org/advisories/ocert-2011-003.html for details.
2286
2287 Changing hash values affects the iteration order of sets.
2288 Python has never made guarantees about this ordering
2289 (and it typically varies between 32-bit and 64-bit builds).
2290
2291 See also :envvar:`PYTHONHASHSEED`.
2292
2293 .. versionchanged:: 3.3
2294 Hash randomization is enabled by default.
2295
2296
2297 .. method:: object.__bool__(self)
2298
2299 .. index:: single: __len__() (mapping object method)
2300
2301 Called to implement truth value testing and the built-in operation
2302 ``bool()``; should return ``False`` or ``True``. When this method is not
2303 defined, :meth:`~object.__len__` is called, if it is defined, and the object is
2304 considered true if its result is nonzero. If a class defines neither
2305 :meth:`!__len__` nor :meth:`!__bool__` (which is true of the :class:`object`
2306 class itself), all its instances are considered true.
2307
2308
2309 .. _attribute-access:
2310
2311 Customizing attribute access
2312 ----------------------------
2313
2314 The following methods can be defined to customize the meaning of attribute
2315 access (use of, assignment to, or deletion of ``x.name``) for class instances.
2316
2317 .. XXX explain how descriptors interfere here!
2318
2319
2320 .. method:: object.__getattr__(self, name)
2321
2322 Called when the default attribute access fails with an :exc:`AttributeError`
2323 (either :meth:`__getattribute__` raises an :exc:`AttributeError` because
2324 *name* is not an instance attribute or an attribute in the class tree
2325 for ``self``; or :meth:`__get__` of a *name* property raises
2326 :exc:`AttributeError`). This method should either return the (computed)
2327 attribute value or raise an :exc:`AttributeError` exception.
2328 The :class:`object` class itself does not provide this method.
2329
2330 Note that if the attribute is found through the normal mechanism,
2331 :meth:`__getattr__` is not called. (This is an intentional asymmetry between
2332 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
2333 reasons and because otherwise :meth:`__getattr__` would have no way to access
2334 other attributes of the instance. Note that at least for instance variables,
2335 you can take total control by not inserting any values in the instance attribute
2336 dictionary (but instead inserting them in another object). See the
2337 :meth:`__getattribute__` method below for a way to actually get total control
2338 over attribute access.
2339
2340
2341 .. method:: object.__getattribute__(self, name)
2342
2343 Called unconditionally to implement attribute accesses for instances of the
2344 class. If the class also defines :meth:`__getattr__`, the latter will not be
2345 called unless :meth:`__getattribute__` either calls it explicitly or raises an
2346 :exc:`AttributeError`. This method should return the (computed) attribute value
2347 or raise an :exc:`AttributeError` exception. In order to avoid infinite
2348 recursion in this method, its implementation should always call the base class
2349 method with the same name to access any attributes it needs, for example,
2350 ``object.__getattribute__(self, name)``.
2351
2352 .. note::
2353
2354 This method may still be bypassed when looking up special methods as the
2355 result of implicit invocation via language syntax or
2356 :ref:`built-in functions <builtin-functions>`.
2357 See :ref:`special-lookup`.
2358
2359 .. audit-event:: object.__getattr__ obj,name object.__getattribute__
2360
2361 For certain sensitive attribute accesses, raises an
2362 :ref:`auditing event <auditing>` ``object.__getattr__`` with arguments
2363 ``obj`` and ``name``.
2364
2365
2366 .. method:: object.__setattr__(self, name, value)
2367
2368 Called when an attribute assignment is attempted. This is called instead of
2369 the normal mechanism (i.e. store the value in the instance dictionary).
2370 *name* is the attribute name, *value* is the value to be assigned to it.
2371
2372 If :meth:`__setattr__` wants to assign to an instance attribute, it should
2373 call the base class method with the same name, for example,
2374 ``object.__setattr__(self, name, value)``.
2375
2376 .. audit-event:: object.__setattr__ obj,name,value object.__setattr__
2377
2378 For certain sensitive attribute assignments, raises an
2379 :ref:`auditing event <auditing>` ``object.__setattr__`` with arguments
2380 ``obj``, ``name``, ``value``.
2381
2382
2383 .. method:: object.__delattr__(self, name)
2384
2385 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
2386 should only be implemented if ``del obj.name`` is meaningful for the object.
2387
2388 .. audit-event:: object.__delattr__ obj,name object.__delattr__
2389
2390 For certain sensitive attribute deletions, raises an
2391 :ref:`auditing event <auditing>` ``object.__delattr__`` with arguments
2392 ``obj`` and ``name``.
2393
2394
2395 .. method:: object.__dir__(self)
2396
2397 Called when :func:`dir` is called on the object. An iterable must be
2398 returned. :func:`dir` converts the returned iterable to a list and sorts it.
2399
2400
2401 Customizing module attribute access
2402 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2403
2404 .. index::
2405 single: __getattr__ (module attribute)
2406 single: __dir__ (module attribute)
2407 single: __class__ (module attribute)
2408
2409 .. method:: module.__getattr__
2410 module.__dir__
2411
2412 Special names ``__getattr__`` and ``__dir__`` can be also used to customize
2413 access to module attributes. The ``__getattr__`` function at the module level
2414 should accept one argument which is the name of an attribute and return the
2415 computed value or raise an :exc:`AttributeError`. If an attribute is
2416 not found on a module object through the normal lookup, i.e.
2417 :meth:`object.__getattribute__`, then ``__getattr__`` is searched in
2418 the module ``__dict__`` before raising an :exc:`AttributeError`. If found,
2419 it is called with the attribute name and the result is returned.
2420
2421 The ``__dir__`` function should accept no arguments, and return an iterable of
2422 strings that represents the names accessible on module. If present, this
2423 function overrides the standard :func:`dir` search on a module.
2424
2425 .. attribute:: module.__class__
2426
2427 For a more fine grained customization of the module behavior (setting
2428 attributes, properties, etc.), one can set the ``__class__`` attribute of
2429 a module object to a subclass of :class:`types.ModuleType`. For example::
2430
2431 import sys
2432 from types import ModuleType
2433
2434 class VerboseModule(ModuleType):
2435 def __repr__(self):
2436 return f'Verbose {self.__name__}'
2437
2438 def __setattr__(self, attr, value):
2439 print(f'Setting {attr}...')
2440 super().__setattr__(attr, value)
2441
2442 sys.modules[__name__].__class__ = VerboseModule
2443
2444 .. note::
2445 Defining module ``__getattr__`` and setting module ``__class__`` only
2446 affect lookups made using the attribute access syntax -- directly accessing
2447 the module globals (whether by code within the module, or via a reference
2448 to the module's globals dictionary) is unaffected.
2449
2450 .. versionchanged:: 3.5
2451 ``__class__`` module attribute is now writable.
2452
2453 .. versionadded:: 3.7
2454 ``__getattr__`` and ``__dir__`` module attributes.
2455
2456 .. seealso::
2457
2458 :pep:`562` - Module __getattr__ and __dir__
2459 Describes the ``__getattr__`` and ``__dir__`` functions on modules.
2460
2461
2462 .. _descriptors:
2463
2464 Implementing Descriptors
2465 ^^^^^^^^^^^^^^^^^^^^^^^^
2466
2467 The following methods only apply when an instance of the class containing the
2468 method (a so-called *descriptor* class) appears in an *owner* class (the
2469 descriptor must be in either the owner's class dictionary or in the class
2470 dictionary for one of its parents). In the examples below, "the attribute"
2471 refers to the attribute whose name is the key of the property in the owner
2472 class' :attr:`~object.__dict__`. The :class:`object` class itself does not
2473 implement any of these protocols.
2474
2475 .. method:: object.__get__(self, instance, owner=None)
2476
2477 Called to get the attribute of the owner class (class attribute access) or
2478 of an instance of that class (instance attribute access). The optional
2479 *owner* argument is the owner class, while *instance* is the instance that
2480 the attribute was accessed through, or ``None`` when the attribute is
2481 accessed through the *owner*.
2482
2483 This method should return the computed attribute value or raise an
2484 :exc:`AttributeError` exception.
2485
2486 :PEP:`252` specifies that :meth:`__get__` is callable with one or two
2487 arguments. Python's own built-in descriptors support this specification;
2488 however, it is likely that some third-party tools have descriptors
2489 that require both arguments. Python's own :meth:`__getattribute__`
2490 implementation always passes in both arguments whether they are required
2491 or not.
2492
2493 .. method:: object.__set__(self, instance, value)
2494
2495 Called to set the attribute on an instance *instance* of the owner class to a
2496 new value, *value*.
2497
2498 Note, adding :meth:`__set__` or :meth:`__delete__` changes the kind of
2499 descriptor to a "data descriptor". See :ref:`descriptor-invocation` for
2500 more details.
2501
2502 .. method:: object.__delete__(self, instance)
2503
2504 Called to delete the attribute on an instance *instance* of the owner class.
2505
2506 Instances of descriptors may also have the :attr:`!__objclass__` attribute
2507 present:
2508
2509 .. attribute:: object.__objclass__
2510
2511 The attribute :attr:`!__objclass__` is interpreted by the :mod:`inspect` module
2512 as specifying the class where this object was defined (setting this
2513 appropriately can assist in runtime introspection of dynamic class attributes).
2514 For callables, it may indicate that an instance of the given type (or a
2515 subclass) is expected or required as the first positional argument (for example,
2516 CPython sets this attribute for unbound methods that are implemented in C).
2517
2518
2519 .. _descriptor-invocation:
2520
2521 Invoking Descriptors
2522 ^^^^^^^^^^^^^^^^^^^^
2523
2524 In general, a descriptor is an object attribute with "binding behavior", one
2525 whose attribute access has been overridden by methods in the descriptor
2526 protocol: :meth:`~object.__get__`, :meth:`~object.__set__`, and
2527 :meth:`~object.__delete__`. If any of
2528 those methods are defined for an object, it is said to be a descriptor.
2529
2530 The default behavior for attribute access is to get, set, or delete the
2531 attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
2532 starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
2533 continuing through the base classes of ``type(a)`` excluding metaclasses.
2534
2535 However, if the looked-up value is an object defining one of the descriptor
2536 methods, then Python may override the default behavior and invoke the descriptor
2537 method instead. Where this occurs in the precedence chain depends on which
2538 descriptor methods were defined and how they were called.
2539
2540 The starting point for descriptor invocation is a binding, ``a.x``. How the
2541 arguments are assembled depends on ``a``:
2542
2543 Direct Call
2544 The simplest and least common call is when user code directly invokes a
2545 descriptor method: ``x.__get__(a)``.
2546
2547 Instance Binding
2548 If binding to an object instance, ``a.x`` is transformed into the call:
2549 ``type(a).__dict__['x'].__get__(a, type(a))``.
2550
2551 Class Binding
2552 If binding to a class, ``A.x`` is transformed into the call:
2553 ``A.__dict__['x'].__get__(None, A)``.
2554
2555 Super Binding
2556 A dotted lookup such as ``super(A, a).x`` searches
2557 ``a.__class__.__mro__`` for a base class ``B`` following ``A`` and then
2558 returns ``B.__dict__['x'].__get__(a, A)``. If not a descriptor, ``x`` is
2559 returned unchanged.
2560
2561 .. testcode::
2562 :hide:
2563
2564 class Desc:
2565 def __get__(*args):
2566 return args
2567
2568 class B:
2569
2570 x = Desc()
2571
2572 class A(B):
2573
2574 x = 999
2575
2576 def m(self):
2577 'Demonstrate these two descriptor invocations are equivalent'
2578 result1 = super(A, self).x
2579 result2 = B.__dict__['x'].__get__(self, A)
2580 return result1 == result2
2581
2582 .. doctest::
2583 :hide:
2584
2585 >>> a = A()
2586 >>> a.__class__.__mro__.index(B) > a.__class__.__mro__.index(A)
2587 True
2588 >>> super(A, a).x == B.__dict__['x'].__get__(a, A)
2589 True
2590 >>> a.m()
2591 True
2592
2593 For instance bindings, the precedence of descriptor invocation depends on
2594 which descriptor methods are defined. A descriptor can define any combination
2595 of :meth:`~object.__get__`, :meth:`~object.__set__` and
2596 :meth:`~object.__delete__`. If it does not
2597 define :meth:`!__get__`, then accessing the attribute will return the descriptor
2598 object itself unless there is a value in the object's instance dictionary. If
2599 the descriptor defines :meth:`!__set__` and/or :meth:`!__delete__`, it is a data
2600 descriptor; if it defines neither, it is a non-data descriptor. Normally, data
2601 descriptors define both :meth:`!__get__` and :meth:`!__set__`, while non-data
2602 descriptors have just the :meth:`!__get__` method. Data descriptors with
2603 :meth:`!__get__` and :meth:`!__set__` (and/or :meth:`!__delete__`) defined
2604 always override a redefinition in an
2605 instance dictionary. In contrast, non-data descriptors can be overridden by
2606 instances.
2607
2608 Python methods (including those decorated with
2609 :deco:`staticmethod` and :deco:`classmethod`) are
2610 implemented as non-data descriptors. Accordingly, instances can redefine and
2611 override methods. This allows individual instances to acquire behaviors that
2612 differ from other instances of the same class.
2613
2614 The :func:`property` function is implemented as a data descriptor. Accordingly,
2615 instances cannot override the behavior of a property.
2616
2617
2618 .. _slots:
2619
2620 __slots__
2621 ^^^^^^^^^
2622
2623 *__slots__* allow us to explicitly declare data members (like
2624 properties) and deny the creation of :attr:`~object.__dict__` and *__weakref__*
2625 (unless explicitly declared in *__slots__* or available in a parent.)
2626
2627 The space saved over using :attr:`~object.__dict__` can be significant.
2628 Attribute lookup speed can be significantly improved as well.
2629
2630 .. data:: object.__slots__
2631
2632 This class variable can be assigned a string, iterable, or sequence of
2633 strings with variable names used by instances. *__slots__* reserves space
2634 for the declared variables and prevents the automatic creation of
2635 :attr:`~object.__dict__`
2636 and *__weakref__* for each instance.
2637
2638
2639 .. _datamodel-note-slots:
2640
2641 Notes on using *__slots__*:
2642
2643 * When inheriting from a class without *__slots__*, the
2644 :attr:`~object.__dict__` and
2645 *__weakref__* attribute of the instances will always be accessible.
2646
2647 * Without a :attr:`~object.__dict__` variable, instances cannot be assigned new
2648 variables not
2649 listed in the *__slots__* definition. Attempts to assign to an unlisted
2650 variable name raises :exc:`AttributeError`. If dynamic assignment of new
2651 variables is desired, then add ``'__dict__'`` to the sequence of strings in
2652 the *__slots__* declaration.
2653
2654 * Without a *__weakref__* variable for each instance, classes defining
2655 *__slots__* do not support :mod:`weak references <weakref>` to its instances.
2656 If weak reference
2657 support is needed, then add ``'__weakref__'`` to the sequence of strings in the
2658 *__slots__* declaration.
2659
2660 * *__slots__* are implemented at the class level by creating :ref:`descriptors <descriptors>`
2661 for each variable name. As a result, class attributes
2662 cannot be used to set default values for instance variables defined by
2663 *__slots__*; otherwise, the class attribute would overwrite the descriptor
2664 assignment.
2665
2666 * The action of a *__slots__* declaration is not limited to the class
2667 where it is defined. *__slots__* declared in parents are available in
2668 child classes. However, instances of a child subclass will get a
2669 :attr:`~object.__dict__` and *__weakref__* unless the subclass also defines
2670 *__slots__* (which should only contain names of any *additional* slots).
2671
2672 * If a class defines a slot also defined in a base class, the instance variable
2673 defined by the base class slot is inaccessible (except by retrieving its
2674 descriptor directly from the base class). This renders the meaning of the
2675 program undefined. In the future, a check may be added to prevent this.
2676
2677 * :exc:`TypeError` will be raised if nonempty *__slots__* are defined for a
2678 class derived from a
2679 :c:member:`"variable-length" built-in type <PyTypeObject.tp_itemsize>` such as
2680 :class:`int`, :class:`bytes`, and :class:`tuple`.
2681
2682 * Any non-string :term:`iterable` may be assigned to *__slots__*.
2683
2684 * If a :class:`dictionary <dict>` is used to assign *__slots__*, the dictionary
2685 keys will be used as the slot names. The values of the dictionary can be used
2686 to provide per-attribute docstrings that will be recognised by
2687 :func:`inspect.getdoc` and displayed in the output of :func:`help`.
2688
2689 * :attr:`~object.__class__` assignment works only if both classes have the
2690 same *__slots__*.
2691
2692 * :ref:`Multiple inheritance <tut-multiple>` with multiple slotted parent
2693 classes can be used,
2694 but only one parent is allowed to have attributes created by slots
2695 (the other bases must have empty slot layouts) - violations raise
2696 :exc:`TypeError`.
2697
2698 * If an :term:`iterator` is used for *__slots__* then a :term:`descriptor` is
2699 created for each
2700 of the iterator's values. However, the *__slots__* attribute will be an empty
2701 iterator.
2702
2703 .. _class-customization:
2704
2705 Customizing class creation
2706 --------------------------
2707
2708 Whenever a class inherits from another class, :meth:`~object.__init_subclass__` is
2709 called on the parent class. This way, it is possible to write classes which
2710 change the behavior of subclasses. This is closely related to class
2711 decorators, but where class decorators only affect the specific class they're
2712 applied to, ``__init_subclass__`` solely applies to future subclasses of the
2713 class defining the method.
2714
2715 .. classmethod:: object.__init_subclass__(cls)
2716
2717 This method is called whenever the containing class is subclassed.
2718 *cls* is then the new subclass. If defined as a normal instance method,
2719 this method is implicitly converted to a class method.
2720
2721 Keyword arguments which are given to a new class are passed to
2722 the parent class's ``__init_subclass__``. For compatibility with
2723 other classes using ``__init_subclass__``, one should take out the
2724 needed keyword arguments and pass the others over to the base
2725 class, as in::
2726
2727 class Philosopher:
2728 def __init_subclass__(cls, /, default_name, **kwargs):
2729 super().__init_subclass__(**kwargs)
2730 cls.default_name = default_name
2731
2732 class AustralianPhilosopher(Philosopher, default_name="Bruce"):
2733 pass
2734
2735 The default implementation ``object.__init_subclass__`` does
2736 nothing, but raises an error if it is called with any arguments.
2737
2738 .. note::
2739
2740 The metaclass hint ``metaclass`` is consumed by the rest of the type
2741 machinery, and is never passed to ``__init_subclass__`` implementations.
2742 The actual metaclass (rather than the explicit hint) can be accessed as
2743 ``type(cls)``.
2744
2745 .. versionadded:: 3.6
2746
2747
2748 When a class is created, :meth:`!type.__new__` scans the class variables
2749 and makes callbacks to those with a :meth:`~object.__set_name__` hook.
2750
2751 .. method:: object.__set_name__(self, owner, name)
2752
2753 Automatically called at the time the owning class *owner* is
2754 created. The object has been assigned to *name* in that class::
2755
2756 class A:
2757 x = C() # Automatically calls: x.__set_name__(A, 'x')
2758
2759 If the class variable is assigned after the class is created,
2760 :meth:`__set_name__` will not be called automatically.
2761 If needed, :meth:`__set_name__` can be called directly::
2762
2763 class A:
2764 pass
2765
2766 c = C()
2767 A.x = c # The hook is not called
2768 c.__set_name__(A, 'x') # Manually invoke the hook
2769
2770 See :ref:`class-object-creation` for more details.
2771
2772 .. versionadded:: 3.6
2773
2774
2775 .. _metaclasses:
2776
2777 Metaclasses
2778 ^^^^^^^^^^^
2779
2780 .. index::
2781 single: metaclass
2782 pair: built-in function; type
2783 single: = (equals); class definition
2784
2785 By default, classes are constructed using :func:`type`. The class body is
2786 executed in a new namespace and the class name is bound locally to the
2787 result of ``type(name, bases, namespace)``.
2788
2789 The class creation process can be customized by passing the ``metaclass``
2790 keyword argument in the class definition line, or by inheriting from an
2791 existing class that included such an argument. In the following example,
2792 both ``MyClass`` and ``MySubclass`` are instances of ``Meta``::
2793
2794 class Meta(type):
2795 pass
2796
2797 class MyClass(metaclass=Meta):
2798 pass
2799
2800 class MySubclass(MyClass):
2801 pass
2802
2803 Any other keyword arguments that are specified in the class definition are
2804 passed through to all metaclass operations described below.
2805
2806 When a class definition is executed, the following steps occur:
2807
2808 * MRO entries are resolved;
2809 * the appropriate metaclass is determined;
2810 * the class namespace is prepared;
2811 * the class body is executed;
2812 * the class object is created.
2813
2814
2815 Resolving MRO entries
2816 ^^^^^^^^^^^^^^^^^^^^^
2817
2818 .. method:: object.__mro_entries__(self, bases)
2819
2820 If a base that appears in a class definition is not an instance of
2821 :class:`type`, then an :meth:`!__mro_entries__` method is searched on the base.
2822 If an :meth:`!__mro_entries__` method is found, the base is substituted with the
2823 result of a call to :meth:`!__mro_entries__` when creating the class.
2824 The method is called with the original bases tuple
2825 passed to the *bases* parameter, and must return a tuple
2826 of classes that will be used instead of the base. The returned tuple may be
2827 empty: in these cases, the original base is ignored.
2828
2829 .. seealso::
2830
2831 :func:`types.resolve_bases`
2832 Dynamically resolve bases that are not instances of :class:`type`.
2833
2834 :func:`types.get_original_bases`
2835 Retrieve a class's "original bases" prior to modifications by
2836 :meth:`~object.__mro_entries__`.
2837
2838 :pep:`560`
2839 Core support for typing module and generic types.
2840
2841
2842 Determining the appropriate metaclass
2843 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2844 .. index::
2845 single: metaclass hint
2846
2847 The appropriate metaclass for a class definition is determined as follows:
2848
2849 * if no bases and no explicit metaclass are given, then :func:`type` is used;
2850 * if an explicit metaclass is given and it is *not* an instance of
2851 :func:`type`, then it is used directly as the metaclass;
2852 * if an instance of :func:`type` is given as the explicit metaclass, or
2853 bases are defined, then the most derived metaclass is used.
2854
2855 The most derived metaclass is selected from the explicitly specified
2856 metaclass (if any) and the metaclasses (i.e. ``type(cls)``) of all specified
2857 base classes. The most derived metaclass is one which is a subtype of *all*
2858 of these candidate metaclasses. If none of the candidate metaclasses meets
2859 that criterion, then the class definition will fail with ``TypeError``.
2860
2861
2862 .. _prepare:
2863
2864 Preparing the class namespace
2865 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2866
2867 .. index::
2868 single: __prepare__ (metaclass method)
2869
2870 Once the appropriate metaclass has been identified, then the class namespace
2871 is prepared. If the metaclass has a ``__prepare__`` attribute, it is called
2872 as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the
2873 additional keyword arguments, if any, come from the class definition). The
2874 ``__prepare__`` method should be implemented as a
2875 :func:`classmethod <classmethod>`. The
2876 namespace returned by ``__prepare__`` is passed in to ``__new__``, but when
2877 the final class object is created the namespace is copied into a new ``dict``.
2878
2879 If the metaclass has no ``__prepare__`` attribute, then the class namespace
2880 is initialised as an empty ordered mapping.
2881
2882 .. seealso::
2883
2884 :pep:`3115` - Metaclasses in Python 3000
2885 Introduced the ``__prepare__`` namespace hook
2886
2887
2888 Executing the class body
2889 ^^^^^^^^^^^^^^^^^^^^^^^^
2890
2891 .. index::
2892 single: class; body
2893
2894 The class body is executed (approximately) as
2895 ``exec(body, globals(), namespace)``. The key difference from a normal
2896 call to :func:`exec` is that lexical scoping allows the class body (including
2897 any methods) to reference names from the current and outer scopes when the
2898 class definition occurs inside a function.
2899
2900 However, even when the class definition occurs inside the function, methods
2901 defined inside the class still cannot see names defined at the class scope.
2902 Class variables must be accessed through the first parameter of instance or
2903 class methods, or through the implicit lexically scoped ``__class__`` reference
2904 described in the next section.
2905
2906 .. _class-object-creation:
2907
2908 Creating the class object
2909 ^^^^^^^^^^^^^^^^^^^^^^^^^
2910
2911 .. index::
2912 single: __class__ (method cell)
2913 single: __classcell__ (class namespace entry)
2914
2915
2916 Once the class namespace has been populated by executing the class body,
2917 the class object is created by calling
2918 ``metaclass(name, bases, namespace, **kwds)`` (the additional keywords
2919 passed here are the same as those passed to ``__prepare__``).
2920
2921 This class object is the one that will be referenced by the zero-argument
2922 form of :func:`super`. ``__class__`` is an implicit closure reference
2923 created by the compiler if any methods in a class body refer to either
2924 ``__class__`` or ``super``. This allows the zero argument form of
2925 :func:`super` to correctly identify the class being defined based on
2926 lexical scoping, while the class or instance that was used to make the
2927 current call is identified based on the first argument passed to the method.
2928
2929 .. impl-detail::
2930
2931 In CPython 3.6 and later, the ``__class__`` cell is passed to the metaclass
2932 as a ``__classcell__`` entry in the class namespace. If present, this must
2933 be propagated up to the ``type.__new__`` call in order for the class to be
2934 initialised correctly.
2935 Failing to do so will result in a :exc:`RuntimeError` in Python 3.8.
2936
2937 When using the default metaclass :class:`type`, or any metaclass that ultimately
2938 calls ``type.__new__``, the following additional customization steps are
2939 invoked after creating the class object:
2940
2941 1) The ``type.__new__`` method collects all of the attributes in the class
2942 namespace that define a :meth:`~object.__set_name__` method;
2943 2) Those ``__set_name__`` methods are called with the class
2944 being defined and the assigned name of that particular attribute;
2945 3) The :meth:`~object.__init_subclass__` hook is called on the
2946 immediate parent of the new class in its method resolution order.
2947
2948 After the class object is created, it is passed to the class decorators
2949 included in the class definition (if any) and the resulting object is bound
2950 in the local namespace as the defined class.
2951
2952 When a new class is created by ``type.__new__``, the object provided as the
2953 namespace parameter is copied to a new ordered mapping and the original
2954 object is discarded. The new copy is wrapped in a read-only proxy, which
2955 becomes the :attr:`~type.__dict__` attribute of the class object.
2956
2957 .. seealso::
2958
2959 :pep:`3135` - New super
2960 Describes the implicit ``__class__`` closure reference
2961
2962
2963 Uses for metaclasses
2964 ^^^^^^^^^^^^^^^^^^^^
2965
2966 The potential uses for metaclasses are boundless. Some ideas that have been
2967 explored include enum, logging, interface checking, automatic delegation,
2968 automatic property creation, proxies, frameworks, and automatic resource
2969 locking/synchronization.
2970
2971
2972 Customizing instance and subclass checks
2973 ----------------------------------------
2974
2975 The following methods are used to override the default behavior of the
2976 :func:`isinstance` and :func:`issubclass` built-in functions.
2977
2978 In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
2979 order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
2980 classes" to any class or type (including built-in types), including other
2981 ABCs.
2982
2983 .. method:: type.__instancecheck__(self, instance)
2984
2985 Return true if *instance* should be considered a (direct or indirect)
2986 instance of *class*. If defined, called to implement ``isinstance(instance,
2987 class)``.
2988
2989
2990 .. method:: type.__subclasscheck__(self, subclass)
2991
2992 Return true if *subclass* should be considered a (direct or indirect)
2993 subclass of *class*. If defined, called to implement ``issubclass(subclass,
2994 class)``.
2995
2996
2997 Note that these methods are looked up on the type (metaclass) of a class. They
2998 cannot be defined as class methods in the actual class. This is consistent with
2999 the lookup of special methods that are called on instances, only in this
3000 case the instance is itself a class.
3001
3002 .. seealso::
3003
3004 :pep:`3119` - Introducing Abstract Base Classes
3005 Includes the specification for customizing :func:`isinstance` and
3006 :func:`issubclass` behavior through :meth:`~type.__instancecheck__` and
3007 :meth:`~type.__subclasscheck__`, with motivation for this functionality
3008 in the context of adding Abstract Base Classes (see the :mod:`abc`
3009 module) to the language.
3010
3011
3012 Emulating generic types
3013 -----------------------
3014
3015 When using :term:`type annotations<annotation>`, it is often useful to
3016 *parameterize* a :term:`generic type` using Python's square-brackets notation.
3017 For example, the annotation ``list[int]`` might be used to signify a
3018 :class:`list` in which all the elements are of type :class:`int`.
3019
3020 .. seealso::
3021
3022 :pep:`484` - Type Hints
3023 Introducing Python's framework for type annotations
3024
3025 :ref:`Generic Alias Types<types-genericalias>`
3026 Documentation for objects representing parameterized generic classes
3027
3028 :ref:`Generics`, :ref:`user-defined generics<user-defined-generics>` and :class:`typing.Generic`
3029 Documentation on how to implement generic classes that can be
3030 parameterized at runtime and understood by static type-checkers.
3031
3032 A class can *generally* only be parameterized if it defines the special
3033 class method ``__class_getitem__()``.
3034
3035 .. classmethod:: object.__class_getitem__(cls, key)
3036
3037 Return an object representing the specialization of a generic class
3038 by type arguments found in *key*.
3039
3040 When defined on a class, ``__class_getitem__()`` is automatically a class
3041 method. As such, there is no need for it to be decorated with
3042 :deco:`classmethod` when it is defined.
3043
3044
3045 The purpose of *__class_getitem__*
3046 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3047
3048 The purpose of :meth:`~object.__class_getitem__` is to allow runtime
3049 parameterization of standard-library generic classes in order to more easily
3050 apply :term:`type hints<type hint>` to these classes.
3051
3052 To implement custom generic classes that can be parameterized at runtime and
3053 understood by static type-checkers, users should either inherit from a standard
3054 library class that already implements :meth:`~object.__class_getitem__`, or
3055 inherit from :class:`typing.Generic`, which has its own implementation of
3056 ``__class_getitem__()``.
3057
3058 Custom implementations of :meth:`~object.__class_getitem__` on classes defined
3059 outside of the standard library may not be understood by third-party
3060 type-checkers such as mypy. Using ``__class_getitem__()`` on any class for
3061 purposes other than type hinting is discouraged.
3062
3063
3064 .. _classgetitem-versus-getitem:
3065
3066
3067 *__class_getitem__* versus *__getitem__*
3068 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3069
3070 Usually, the :ref:`subscription<subscriptions>` of an object using square
3071 brackets will call the :meth:`~object.__getitem__` instance method defined on
3072 the object's class. However, if the object being subscribed is itself a class,
3073 the class method :meth:`~object.__class_getitem__` may be called instead.
3074 ``__class_getitem__()`` should return a :ref:`GenericAlias<types-genericalias>`
3075 object if it is properly defined.
3076
3077 Presented with the :term:`expression` ``obj[x]``, the Python interpreter
3078 follows something like the following process to decide whether
3079 :meth:`~object.__getitem__` or :meth:`~object.__class_getitem__` should be
3080 called::
3081
3082 from inspect import isclass
3083
3084 def subscribe(obj, x):
3085 """Return the result of the expression 'obj[x]'"""
3086
3087 class_of_obj = type(obj)
3088
3089 # If the class of obj defines __getitem__,
3090 # call class_of_obj.__getitem__(obj, x)
3091 if hasattr(class_of_obj, '__getitem__'):
3092 return class_of_obj.__getitem__(obj, x)
3093
3094 # Else, if obj is a class and defines __class_getitem__,
3095 # call obj.__class_getitem__(x)
3096 elif isclass(obj) and hasattr(obj, '__class_getitem__'):
3097 return obj.__class_getitem__(x)
3098
3099 # Else, raise an exception
3100 else:
3101 raise TypeError(
3102 f"'{class_of_obj.__name__}' object is not subscriptable"
3103 )
3104
3105 In Python, all classes are themselves instances of other classes. The class of
3106 a class is known as that class's :term:`metaclass`, and most classes have the
3107 :class:`type` class as their metaclass. :class:`type` does not define
3108 :meth:`~object.__getitem__`, meaning that expressions such as ``list[int]``,
3109 ``dict[str, float]`` and ``tuple[str, bytes]`` all result in
3110 :meth:`~object.__class_getitem__` being called::
3111
3112 >>> # list has class "type" as its metaclass, like most classes:
3113 >>> type(list)
3114 <class 'type'>
3115 >>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
3116 True
3117 >>> # "list[int]" calls "list.__class_getitem__(int)"
3118 >>> list[int]
3119 list[int]
3120 >>> # list.__class_getitem__ returns a GenericAlias object:
3121 >>> type(list[int])
3122 <class 'types.GenericAlias'>
3123
3124 However, if a class has a custom metaclass that defines
3125 :meth:`~object.__getitem__`, subscribing the class may result in different
3126 behaviour. An example of this can be found in the :mod:`enum` module::
3127
3128 >>> from enum import Enum
3129 >>> class Menu(Enum):
3130 ... """A breakfast menu"""
3131 ... SPAM = 'spam'
3132 ... BACON = 'bacon'
3133 ...
3134 >>> # Enum classes have a custom metaclass:
3135 >>> type(Menu)
3136 <class 'enum.EnumMeta'>
3137 >>> # EnumMeta defines __getitem__,
3138 >>> # so __class_getitem__ is not called,
3139 >>> # and the result is not a GenericAlias object:
3140 >>> Menu['SPAM']
3141 <Menu.SPAM: 'spam'>
3142 >>> type(Menu['SPAM'])
3143 <enum 'Menu'>
3144
3145
3146 .. seealso::
3147 :pep:`560` - Core Support for typing module and generic types
3148 Introducing :meth:`~object.__class_getitem__`, and outlining when a
3149 :ref:`subscription<subscriptions>` results in ``__class_getitem__()``
3150 being called instead of :meth:`~object.__getitem__`
3151
3152
3153 .. _callable-types:
3154
3155 Emulating callable objects
3156 --------------------------
3157
3158
3159 .. method:: object.__call__(self[, args...])
3160
3161 .. index:: pair: call; instance
3162
3163 Called when the instance is "called" as a function; if this method is defined,
3164 ``x(arg1, arg2, ...)`` roughly translates to ``type(x).__call__(x, arg1, ...)``.
3165 The :class:`object` class itself does not provide this method.
3166
3167
3168 .. _sequence-types:
3169
3170 Emulating container types
3171 -------------------------
3172
3173 The following methods can be defined to implement container objects. None of them
3174 are provided by the :class:`object` class itself. Containers usually are
3175 :term:`sequences <sequence>` (such as :class:`lists <list>` or
3176 :class:`tuples <tuple>`) or :term:`mappings <mapping>` (like
3177 :term:`dictionaries <dictionary>`),
3178 but can represent other containers as well. The first set of methods is used
3179 either to emulate a sequence or to emulate a mapping; the difference is that for
3180 a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
3181 N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a
3182 range of items. It is also recommended that mappings provide the methods
3183 :meth:`!keys`, :meth:`!values`, :meth:`!items`, :meth:`!get`, :meth:`!clear`,
3184 :meth:`!setdefault`, :meth:`!pop`, :meth:`!popitem`, :meth:`!copy`, and
3185 :meth:`!update` behaving similar to those for Python's standard :class:`dictionary <dict>`
3186 objects. The :mod:`collections.abc` module provides a
3187 :class:`~collections.abc.MutableMapping`
3188 :term:`abstract base class` to help create those methods from a base set of
3189 :meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
3190 :meth:`~object.__delitem__`, and :meth:`!keys`.
3191
3192 Mutable sequences should provide methods
3193 :meth:`~sequence.append`, :meth:`~sequence.clear`, :meth:`~sequence.count`,
3194 :meth:`~sequence.extend`, :meth:`~sequence.index`, :meth:`~sequence.insert`,
3195 :meth:`~sequence.pop`, :meth:`~sequence.remove`, and :meth:`~sequence.reverse`,
3196 like Python standard :class:`list` objects.
3197 Finally, sequence types should implement addition (meaning concatenation) and
3198 multiplication (meaning repetition) by defining the methods
3199 :meth:`~object.__add__`, :meth:`~object.__radd__`, :meth:`~object.__iadd__`,
3200 :meth:`~object.__mul__`, :meth:`~object.__rmul__` and :meth:`~object.__imul__`
3201 described below; they should not define other numerical
3202 operators.
3203
3204 It is recommended that both mappings and sequences implement the
3205 :meth:`~object.__contains__` method to allow efficient use of the ``in``
3206 operator; for
3207 mappings, ``in`` should search the mapping's keys; for sequences, it should
3208 search through the values. It is further recommended that both mappings and
3209 sequences implement the :meth:`~object.__iter__` method to allow efficient iteration
3210 through the container; for mappings, :meth:`!__iter__` should iterate
3211 through the object's keys; for sequences, it should iterate through the values.
3212
3213 .. method:: object.__len__(self)
3214
3215 .. index::
3216 pair: built-in function; len
3217 single: __bool__() (object method)
3218
3219 Called to implement the built-in function :func:`len`. Should return the length
3220 of the object, an integer ``>=`` 0. Also, an object that doesn't define a
3221 :meth:`~object.__bool__` method and whose :meth:`!__len__` method returns zero is
3222 considered to be false in a Boolean context.
3223
3224 .. impl-detail::
3225
3226 In CPython, the length is required to be at most :data:`sys.maxsize`.
3227 If the length is larger than :data:`!sys.maxsize` some features (such as
3228 :func:`len`) may raise :exc:`OverflowError`. To prevent raising
3229 :exc:`!OverflowError` by truth value testing, an object must define a
3230 :meth:`~object.__bool__` method.
3231
3232
3233 .. method:: object.__length_hint__(self)
3234
3235 Called to implement :func:`operator.length_hint`. Should return an estimated
3236 length for the object (which may be greater or less than the actual length).
3237 The length must be an integer ``>=`` 0. The return value may also be
3238 :data:`NotImplemented`, which is treated the same as if the
3239 ``__length_hint__`` method didn't exist at all. This method is purely an
3240 optimization and is never required for correctness.
3241
3242 .. versionadded:: 3.4
3243
3244
3245 .. method:: object.__getitem__(self, subscript)
3246
3247 Called to implement *subscription*, that is, ``self[subscript]``.
3248 See :ref:`subscriptions` for details on the syntax.
3249
3250 There are two types of built-in objects that support subscription
3251 via :meth:`!__getitem__`:
3252
3253 - **sequences**, where *subscript* (also called
3254 :term:`index`) should be an integer or a :class:`slice` object.
3255 See the :ref:`sequence documentation <datamodel-sequences>` for the expected
3256 behavior, including handling :class:`slice` objects and negative indices.
3257 - **mappings**, where *subscript* is also called the :term:`key`.
3258 See :ref:`mapping documentation <datamodel-mappings>` for the expected
3259 behavior.
3260
3261 If *subscript* is of an inappropriate type, :meth:`!__getitem__`
3262 should raise :exc:`TypeError`.
3263 If *subscript* has an inappropriate value, :meth:`!__getitem__`
3264 should raise an :exc:`LookupError` or one of its subclasses
3265 (:exc:`IndexError` for sequences; :exc:`KeyError` for mappings).
3266
3267 .. index:: pair: object; slice
3268
3269 .. note::
3270
3271 Slicing is handled by :meth:`!__getitem__`, :meth:`~object.__setitem__`,
3272 and :meth:`~object.__delitem__`.
3273 A call like ::
3274
3275 a[1:2] = b
3276
3277 is translated to ::
3278
3279 a[slice(1, 2, None)] = b
3280
3281 and so forth. Missing slice items are always filled in with ``None``.
3282
3283 .. note::
3284
3285 The sequence iteration protocol (used, for example, in :keyword:`for`
3286 loops), expects that an :exc:`IndexError` will be raised for illegal
3287 indexes to allow proper detection of the end of a sequence.
3288
3289 .. note::
3290
3291 When :ref:`subscripting <subscriptions>` a *class*, the special
3292 class method :meth:`~object.__class_getitem__` may be called instead of
3293 :meth:`!__getitem__`. See :ref:`classgetitem-versus-getitem` for more
3294 details.
3295
3296
3297 .. method:: object.__setitem__(self, key, value)
3298
3299 Called to implement assignment to ``self[key]``. Same note as for
3300 :meth:`__getitem__`. This should only be implemented for mappings if the
3301 objects support changes to the values for keys, or if new keys can be added, or
3302 for sequences if elements can be replaced. The same exceptions should be raised
3303 for improper *key* values as for the :meth:`__getitem__` method.
3304
3305
3306 .. method:: object.__delitem__(self, key)
3307
3308 Called to implement deletion of ``self[key]``. Same note as for
3309 :meth:`__getitem__`. This should only be implemented for mappings if the
3310 objects support removal of keys, or for sequences if elements can be removed
3311 from the sequence. The same exceptions should be raised for improper *key*
3312 values as for the :meth:`__getitem__` method.
3313
3314
3315 .. method:: object.__missing__(self, key)
3316
3317 Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses
3318 when key is not in the dictionary.
3319
3320
3321 .. method:: object.__iter__(self)
3322
3323 This method is called when an :term:`iterator` is required for a container.
3324 This method should return a new iterator object that can iterate over all the
3325 objects in the container. For mappings, it should iterate over the keys of
3326 the container.
3327
3328
3329 .. method:: object.__reversed__(self)
3330
3331 Called (if present) by the :func:`reversed` built-in to implement
3332 reverse iteration. It should return a new iterator object that iterates
3333 over all the objects in the container in reverse order.
3334
3335 If the :meth:`__reversed__` method is not provided, the :func:`reversed`
3336 built-in will fall back to using the sequence protocol (:meth:`__len__` and
3337 :meth:`__getitem__`). Objects that support the sequence protocol should
3338 only provide :meth:`__reversed__` if they can provide an implementation
3339 that is more efficient than the one provided by :func:`reversed`.
3340
3341
3342 The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
3343 implemented as an iteration through a container. However, container objects can
3344 supply the following special method with a more efficient implementation, which
3345 also does not require the object be iterable.
3346
3347 .. method:: object.__contains__(self, item)
3348
3349 Called to implement membership test operators. Should return true if *item*
3350 is in *self*, false otherwise. For mapping objects, this should consider the
3351 keys of the mapping rather than the values or the key-item pairs.
3352
3353 For objects that don't define :meth:`__contains__`, the membership test first
3354 tries iteration via :meth:`__iter__`, then the old sequence iteration
3355 protocol via :meth:`__getitem__`, see :ref:`this section in the language
3356 reference <membership-test-details>`.
3357
3358
3359 .. _numeric-types:
3360
3361 Emulating numeric types
3362 -----------------------
3363
3364 The following methods can be defined to emulate numeric objects. Methods
3365 corresponding to operations that are not supported by the particular kind of
3366 number implemented (e.g., bitwise operations for non-integral numbers) should be
3367 left undefined.
3368
3369
3370 .. method:: object.__add__(self, other)
3371 object.__sub__(self, other)
3372 object.__mul__(self, other)
3373 object.__matmul__(self, other)
3374 object.__truediv__(self, other)
3375 object.__floordiv__(self, other)
3376 object.__mod__(self, other)
3377 object.__divmod__(self, other)
3378 object.__pow__(self, other[, modulo])
3379 object.__lshift__(self, other)
3380 object.__rshift__(self, other)
3381 object.__and__(self, other)
3382 object.__xor__(self, other)
3383 object.__or__(self, other)
3384
3385 .. index::
3386 pair: built-in function; divmod
3387 pair: built-in function; pow
3388 pair: built-in function; pow
3389
3390 These methods are called to implement the binary arithmetic operations
3391 (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
3392 :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``). For instance, to
3393 evaluate the expression ``x + y``, where *x* is an instance of a class that
3394 has an :meth:`__add__` method, ``type(x).__add__(x, y)`` is called. The
3395 :meth:`__divmod__` method should be the equivalent to using
3396 :meth:`__floordiv__` and :meth:`__mod__`; it should not be related to
3397 :meth:`__truediv__`. Note that :meth:`__pow__` should be defined to accept
3398 an optional third argument if the three-argument version of the built-in :func:`pow`
3399 function is to be supported.
3400
3401 If one of those methods does not support the operation with the supplied
3402 arguments, it should return :data:`NotImplemented`.
3403
3404
3405 .. method:: object.__radd__(self, other)
3406 object.__rsub__(self, other)
3407 object.__rmul__(self, other)
3408 object.__rmatmul__(self, other)
3409 object.__rtruediv__(self, other)
3410 object.__rfloordiv__(self, other)
3411 object.__rmod__(self, other)
3412 object.__rdivmod__(self, other)
3413 object.__rpow__(self, other[, modulo])
3414 object.__rlshift__(self, other)
3415 object.__rrshift__(self, other)
3416 object.__rand__(self, other)
3417 object.__rxor__(self, other)
3418 object.__ror__(self, other)
3419
3420 .. index::
3421 pair: built-in function; divmod
3422 pair: built-in function; pow
3423
3424 These methods are called to implement the binary arithmetic operations
3425 (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
3426 :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected
3427 (swapped) operands. These functions are only called if the operands
3428 are of different types, when the left operand does not support the corresponding
3429 operation [#]_, or the right operand's class is derived from the left operand's
3430 class. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
3431 an instance of a class that has an :meth:`__rsub__` method, ``type(y).__rsub__(y, x)``
3432 is called if ``type(x).__sub__(x, y)`` returns :data:`NotImplemented` or ``type(y)``
3433 is a subclass of ``type(x)``. [#]_
3434
3435 Note that :meth:`__rpow__` should be defined to accept an optional third
3436 argument if the three-argument version of the built-in :func:`pow` function
3437 is to be supported.
3438
3439 .. versionchanged:: 3.14
3440
3441 Three-argument :func:`pow` now try calling :meth:`~object.__rpow__` if necessary.
3442 Previously it was only called in two-argument :func:`!pow` and the binary
3443 power operator.
3444
3445 .. note::
3446
3447 If the right operand's type is a subclass of the left operand's type and
3448 that subclass provides a different implementation of the reflected method
3449 for the operation, this method will be called before the left operand's
3450 non-reflected method. This behavior allows subclasses to override their
3451 ancestors' operations.
3452
3453 .. method:: object.__iadd__(self, other)
3454 object.__isub__(self, other)
3455 object.__imul__(self, other)
3456 object.__imatmul__(self, other)
3457 object.__itruediv__(self, other)
3458 object.__ifloordiv__(self, other)
3459 object.__imod__(self, other)
3460 object.__ipow__(self, other[, modulo])
3461 object.__ilshift__(self, other)
3462 object.__irshift__(self, other)
3463 object.__iand__(self, other)
3464 object.__ixor__(self, other)
3465 object.__ior__(self, other)
3466
3467 These methods are called to implement the augmented arithmetic assignments
3468 (``+=``, ``-=``, ``*=``, ``@=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``,
3469 ``>>=``, ``&=``, ``^=``, ``|=``). These methods should attempt to do the
3470 operation in-place (modifying *self*) and return the result (which could be,
3471 but does not have to be, *self*). If a specific method is not defined, or if
3472 that method returns :data:`NotImplemented`, the
3473 augmented assignment falls back to the normal methods. For instance, if *x*
3474 is an instance of a class with an :meth:`__iadd__` method, ``x += y`` is
3475 equivalent to ``x = x.__iadd__(y)`` . If :meth:`__iadd__` does not exist, or if ``x.__iadd__(y)``
3476 returns :data:`!NotImplemented`, ``x.__add__(y)`` and
3477 ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``. In
3478 certain situations, augmented assignment can result in unexpected errors (see
3479 :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in fact
3480 part of the data model.
3481
3482
3483 .. method:: object.__neg__(self)
3484 object.__pos__(self)
3485 object.__abs__(self)
3486 object.__invert__(self)
3487
3488 .. index:: pair: built-in function; abs
3489
3490 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
3491 and ``~``).
3492
3493
3494 .. method:: object.__complex__(self)
3495 object.__int__(self)
3496 object.__float__(self)
3497
3498 .. index::
3499 pair: built-in function; complex
3500 pair: built-in function; int
3501 pair: built-in function; float
3502
3503 Called to implement the built-in functions :func:`complex`,
3504 :func:`int` and :func:`float`. Should return a value
3505 of the appropriate type.
3506
3507
3508 .. method:: object.__index__(self)
3509
3510 Called to implement :func:`operator.index`, and whenever Python needs to
3511 losslessly convert the numeric object to an integer object (such as in
3512 slicing, or in the built-in :func:`bin`, :func:`hex` and :func:`oct`
3513 functions). Presence of this method indicates that the numeric object is
3514 an integer type. Must return an integer.
3515
3516 If :meth:`__int__`, :meth:`__float__` and :meth:`__complex__` are not
3517 defined then corresponding built-in functions :func:`int`, :func:`float`
3518 and :func:`complex` fall back to :meth:`__index__`.
3519
3520
3521 .. method:: object.__round__(self, [,ndigits])
3522 object.__trunc__(self)
3523 object.__floor__(self)
3524 object.__ceil__(self)
3525
3526 .. index:: pair: built-in function; round
3527
3528 Called to implement the built-in function :func:`round` and :mod:`math`
3529 functions :func:`~math.trunc`, :func:`~math.floor` and :func:`~math.ceil`.
3530 Unless *ndigits* is passed to :meth:`!__round__` all these methods should
3531 return the value of the object truncated to an :class:`~numbers.Integral`
3532 (typically an :class:`int`).
3533
3534 .. versionchanged:: 3.14
3535 :func:`int` no longer delegates to the :meth:`~object.__trunc__` method.
3536
3537
3538 .. _context-managers:
3539
3540 With Statement Context Managers
3541 -------------------------------
3542
3543 A :dfn:`context manager` is an object that defines the runtime context to be
3544 established when executing a :keyword:`with` statement. The context manager
3545 handles the entry into, and the exit from, the desired runtime context for the
3546 execution of the block of code. Context managers are normally invoked using the
3547 :keyword:`!with` statement (described in section :ref:`with`), but can also be
3548 used by directly invoking their methods.
3549
3550 .. index::
3551 pair: statement; with
3552 single: context manager
3553
3554 Typical uses of context managers include saving and restoring various kinds of
3555 global state, locking and unlocking resources, closing opened files, etc.
3556
3557 For more information on context managers, see :ref:`typecontextmanager`.
3558 The :class:`object` class itself does not provide the context manager methods.
3559
3560
3561 .. method:: object.__enter__(self)
3562
3563 Enter the runtime context related to this object. The :keyword:`with` statement
3564 will bind this method's return value to the target(s) specified in the
3565 :keyword:`!as` clause of the statement, if any.
3566
3567
3568 .. method:: object.__exit__(self, exc_type, exc_value, traceback)
3569
3570 Exit the runtime context related to this object. The parameters describe the
3571 exception that caused the context to be exited. If the context was exited
3572 without an exception, all three arguments will be :const:`None`.
3573
3574 If an exception is supplied, and the method wishes to suppress the exception
3575 (i.e., prevent it from being propagated), it should return a true value.
3576 Otherwise, the exception will be processed normally upon exit from this method.
3577
3578 Note that :meth:`~object.__exit__` methods should not reraise the passed-in exception;
3579 this is the caller's responsibility.
3580
3581
3582 .. seealso::
3583
3584 :pep:`343` - The "with" statement
3585 The specification, background, and examples for the Python :keyword:`with`
3586 statement.
3587
3588
3589 .. _class-pattern-matching:
3590
3591 Customizing positional arguments in class pattern matching
3592 ----------------------------------------------------------
3593
3594 When using a class name in a pattern, positional arguments in the pattern are not
3595 allowed by default, i.e. ``case MyClass(x, y)`` is typically invalid without special
3596 support in ``MyClass``. To be able to use that kind of pattern, the class needs to
3597 define a *__match_args__* attribute.
3598
3599 .. data:: object.__match_args__
3600
3601 This class variable can be assigned a tuple of strings. When this class is
3602 used in a class pattern with positional arguments, each positional argument will
3603 be converted into a keyword argument, using the corresponding value in
3604 *__match_args__* as the keyword. The absence of this attribute is equivalent to
3605 setting it to ``()``.
3606
3607 For example, if ``MyClass.__match_args__`` is ``("left", "center", "right")`` that means
3608 that ``case MyClass(x, y)`` is equivalent to ``case MyClass(left=x, center=y)``. Note
3609 that the number of arguments in the pattern must be smaller than or equal to the number
3610 of elements in *__match_args__*; if it is larger, the pattern match attempt will raise
3611 a :exc:`TypeError`.
3612
3613 .. versionadded:: 3.10
3614
3615 .. seealso::
3616
3617 :pep:`634` - Structural Pattern Matching
3618 The specification for the Python ``match`` statement.
3619
3620
3621 .. _python-buffer-protocol:
3622
3623 Emulating buffer types
3624 ----------------------
3625
3626 The :ref:`buffer protocol <bufferobjects>` provides a way for Python
3627 objects to expose efficient access to a low-level memory array. This protocol
3628 is implemented by builtin types such as :class:`bytes` and :class:`memoryview`,
3629 and third-party libraries may define additional buffer types.
3630
3631 While buffer types are usually implemented in C, it is also possible to
3632 implement the protocol in Python.
3633
3634 .. method:: object.__buffer__(self, flags)
3635
3636 Called when a buffer is requested from *self* (for example, by the
3637 :class:`memoryview` constructor). The *flags* argument is an integer
3638 representing the kind of buffer requested, affecting for example whether
3639 the returned buffer is read-only or writable. :class:`inspect.BufferFlags`
3640 provides a convenient way to interpret the flags. The method must return
3641 a :class:`memoryview` object.
3642
3643 **Thread safety:** In :term:`free-threaded <free threading>` Python,
3644 implementations must manage any internal export counter using atomic
3645 operations. The method must be safe to call concurrently from multiple
3646 threads, and the returned buffer's underlying data must remain valid
3647 until the corresponding :meth:`~object.__release_buffer__` call
3648 completes. See :ref:`thread-safety-memoryview` for details.
3649
3650 .. method:: object.__release_buffer__(self, buffer)
3651
3652 Called when a buffer is no longer needed. The *buffer* argument is a
3653 :class:`memoryview` object that was previously returned by
3654 :meth:`~object.__buffer__`. The method must release any resources associated
3655 with the buffer. This method should return ``None``.
3656
3657 **Thread safety:** In :term:`free-threaded <free threading>` Python,
3658 any export counter decrement must use atomic operations. Resource
3659 cleanup must be thread-safe, as the final release may race with
3660 concurrent releases from other threads.
3661
3662 Buffer objects that do not need to perform any cleanup are not required
3663 to implement this method.
3664
3665 .. versionadded:: 3.12
3666
3667 .. seealso::
3668
3669 :pep:`688` - Making the buffer protocol accessible in Python
3670 Introduces the Python ``__buffer__`` and ``__release_buffer__`` methods.
3671
3672 :class:`collections.abc.Buffer`
3673 ABC for buffer types.
3674
3675 Annotations
3676 -----------
3677
3678 Functions, classes, and modules may contain :term:`annotations <annotation>`,
3679 which are a way to associate information (usually :term:`type hints <type hint>`)
3680 with a symbol.
3681
3682 .. attribute:: object.__annotations__
3683
3684 This attribute contains the annotations for an object. It is
3685 :ref:`lazily evaluated <lazy-evaluation>`, so accessing the attribute may
3686 execute arbitrary code and raise exceptions. If evaluation is successful, the
3687 attribute is set to a dictionary mapping from variable names to annotations.
3688
3689 .. versionchanged:: 3.14
3690 Annotations are now lazily evaluated.
3691
3692 .. method:: object.__annotate__(format)
3693
3694 An :term:`annotate function`.
3695 Returns a new dictionary object mapping attribute/parameter names to their annotation values.
3696
3697 Takes a format parameter specifying the format in which annotations values should be provided.
3698 It must be a member of the :class:`annotationlib.Format` enum, or an integer with
3699 a value corresponding to a member of the enum.
3700
3701 If an annotate function doesn't support the requested format, it must raise
3702 :exc:`NotImplementedError`. Annotate functions must always support
3703 :attr:`~annotationlib.Format.VALUE` format; they must not raise
3704 :exc:`NotImplementedError()` when called with this format.
3705
3706 When called with :attr:`~annotationlib.Format.VALUE` format, an annotate function may raise
3707 :exc:`NameError`; it must not raise :exc:`!NameError` when called requesting any other format.
3708
3709 If an object does not have any annotations, :attr:`~object.__annotate__` should preferably be set
3710 to ``None`` (it can’t be deleted), rather than set to a function that returns an empty dict.
3711
3712 .. versionadded:: 3.14
3713
3714 .. seealso::
3715
3716 :pep:`649` --- Deferred evaluation of annotation using descriptors
3717 Introduces lazy evaluation of annotations and the ``__annotate__`` function.
3718
3719
3720 .. _special-lookup:
3721
3722 Special method lookup
3723 ---------------------
3724
3725 For custom classes, implicit invocations of special methods are only guaranteed
3726 to work correctly if defined on an object's type, not in the object's instance
3727 dictionary. That behaviour is the reason why the following code raises an
3728 exception::
3729
3730 >>> class C:
3731 ... pass
3732 ...
3733 >>> c = C()
3734 >>> c.__len__ = lambda: 5
3735 >>> len(c)
3736 Traceback (most recent call last):
3737 File "<stdin>", line 1, in <module>
3738 TypeError: object of type 'C' has no len()
3739
3740 The rationale behind this behaviour lies with a number of special methods such
3741 as :meth:`~object.__hash__` and :meth:`~object.__repr__` that are implemented
3742 by all objects,
3743 including type objects. If the implicit lookup of these methods used the
3744 conventional lookup process, they would fail when invoked on the type object
3745 itself::
3746
3747 >>> 1 .__hash__() == hash(1)
3748 True
3749 >>> int.__hash__() == hash(int)
3750 Traceback (most recent call last):
3751 File "<stdin>", line 1, in <module>
3752 TypeError: descriptor '__hash__' of 'int' object needs an argument
3753
3754 Incorrectly attempting to invoke an unbound method of a class in this way is
3755 sometimes referred to as 'metaclass confusion', and is avoided by bypassing
3756 the instance when looking up special methods::
3757
3758 >>> type(1).__hash__(1) == hash(1)
3759 True
3760 >>> type(int).__hash__(int) == hash(int)
3761 True
3762
3763 In addition to bypassing any instance attributes in the interest of
3764 correctness, implicit special method lookup generally also bypasses the
3765 :meth:`~object.__getattribute__` method even of the object's metaclass::
3766
3767 >>> class Meta(type):
3768 ... def __getattribute__(*args):
3769 ... print("Metaclass getattribute invoked")
3770 ... return type.__getattribute__(*args)
3771 ...
3772 >>> class C(object, metaclass=Meta):
3773 ... def __len__(self):
3774 ... return 10
3775 ... def __getattribute__(*args):
3776 ... print("Class getattribute invoked")
3777 ... return object.__getattribute__(*args)
3778 ...
3779 >>> c = C()
3780 >>> c.__len__() # Explicit lookup via instance
3781 Class getattribute invoked
3782 10
3783 >>> type(c).__len__(c) # Explicit lookup via type
3784 Metaclass getattribute invoked
3785 10
3786 >>> len(c) # Implicit lookup
3787 10
3788
3789 Bypassing the :meth:`~object.__getattribute__` machinery in this fashion
3790 provides significant scope for speed optimisations within the
3791 interpreter, at the cost of some flexibility in the handling of
3792 special methods (the special method *must* be set on the class
3793 object itself in order to be consistently invoked by the interpreter).
3794
3795
3796 .. index::
3797 single: coroutine
3798
3799 Coroutines
3800 ==========
3801
3802
3803 Awaitable Objects
3804 -----------------
3805
3806 An :term:`awaitable` object generally implements an :meth:`~object.__await__` method.
3807 :term:`Coroutine objects <coroutine>` returned from :keyword:`async def` functions
3808 are awaitable.
3809
3810 .. note::
3811
3812 The :term:`generator iterator` objects returned from generators
3813 decorated with :func:`types.coroutine`
3814 are also awaitable, but they do not implement :meth:`~object.__await__`.
3815
3816 .. method:: object.__await__(self)
3817
3818 Must return an :term:`iterator`. Should be used to implement
3819 :term:`awaitable` objects. For instance, :class:`asyncio.Future` implements
3820 this method to be compatible with the :keyword:`await` expression.
3821 The :class:`object` class itself is not awaitable and does not provide
3822 this method.
3823
3824 .. note::
3825
3826 The language doesn't place any restriction on the type or value of the
3827 objects yielded by the iterator returned by ``__await__``, as this is
3828 specific to the implementation of the asynchronous execution framework
3829 (e.g. :mod:`asyncio`) that will be managing the :term:`awaitable` object.
3830
3831
3832 .. versionadded:: 3.5
3833
3834 .. seealso:: :pep:`492` for additional information about awaitable objects.
3835
3836
3837 .. _coroutine-objects:
3838
3839 Coroutine Objects
3840 -----------------
3841
3842 :term:`Coroutine objects <coroutine>` are :term:`awaitable` objects.
3843 A coroutine's execution can be controlled by calling :meth:`~object.__await__` and
3844 iterating over the result. When the coroutine has finished executing and
3845 returns, the iterator raises :exc:`StopIteration`, and the exception's
3846 :attr:`~StopIteration.value` attribute holds the return value. If the
3847 coroutine raises an exception, it is propagated by the iterator. Coroutines
3848 should not directly raise unhandled :exc:`StopIteration` exceptions.
3849
3850 Coroutines also have the methods listed below, which are analogous to
3851 those of generators (see :ref:`generator-methods`). However, unlike
3852 generators, coroutines do not directly support iteration.
3853
3854 .. versionchanged:: 3.5.2
3855 It is a :exc:`RuntimeError` to await on a coroutine more than once.
3856
3857
3858 .. method:: coroutine.send(value)
3859
3860 Starts or resumes execution of the coroutine. If *value* is ``None``,
3861 this is equivalent to advancing the iterator returned by
3862 :meth:`~object.__await__`. If *value* is not ``None``, this method delegates
3863 to the :meth:`~generator.send` method of the iterator that caused
3864 the coroutine to suspend. The result (return value,
3865 :exc:`StopIteration`, or other exception) is the same as when
3866 iterating over the :meth:`!__await__` return value, described above.
3867
3868 .. method:: coroutine.throw(value)
3869 coroutine.throw(type[, value[, traceback]])
3870
3871 Raises the specified exception in the coroutine. This method delegates
3872 to the :meth:`~generator.throw` method of the iterator that caused
3873 the coroutine to suspend, if it has such a method. Otherwise,
3874 the exception is raised at the suspension point. The result
3875 (return value, :exc:`StopIteration`, or other exception) is the same as
3876 when iterating over the :meth:`~object.__await__` return value, described
3877 above. If the exception is not caught in the coroutine, it propagates
3878 back to the caller.
3879
3880 .. versionchanged:: 3.12
3881
3882 The second signature \(type\[, value\[, traceback\]\]\) is deprecated and
3883 may be removed in a future version of Python.
3884
3885 .. method:: coroutine.close()
3886
3887 Causes the coroutine to clean itself up and exit. If the coroutine
3888 is suspended, this method first delegates to the :meth:`~generator.close`
3889 method of the iterator that caused the coroutine to suspend, if it
3890 has such a method. Then it raises :exc:`GeneratorExit` at the
3891 suspension point, causing the coroutine to immediately clean itself up.
3892 Finally, the coroutine is marked as having finished executing, even if
3893 it was never started.
3894
3895 Coroutine objects are automatically closed using the above process when
3896 they are about to be destroyed.
3897
3898 .. _async-iterators:
3899
3900 Asynchronous Iterators
3901 ----------------------
3902
3903 An *asynchronous iterator* can call asynchronous code in
3904 its ``__anext__`` method.
3905
3906 Asynchronous iterators can be used in an :keyword:`async for` statement.
3907
3908 The :class:`object` class itself does not provide these methods.
3909
3910
3911 .. method:: object.__aiter__(self)
3912
3913 Must return an *asynchronous iterator* object.
3914
3915 .. method:: object.__anext__(self)
3916
3917 Must return an *awaitable* resulting in a next value of the iterator. Should
3918 raise a :exc:`StopAsyncIteration` error when the iteration is over.
3919
3920 An example of an asynchronous iterable object::
3921
3922 class Reader:
3923 async def readline(self):
3924 ...
3925
3926 def __aiter__(self):
3927 return self
3928
3929 async def __anext__(self):
3930 val = await self.readline()
3931 if val == b'':
3932 raise StopAsyncIteration
3933 return val
3934
3935 .. versionadded:: 3.5
3936
3937 .. versionchanged:: 3.7
3938 Prior to Python 3.7, :meth:`~object.__aiter__` could return an *awaitable*
3939 that would resolve to an
3940 :term:`asynchronous iterator <asynchronous iterator>`.
3941
3942 Starting with Python 3.7, :meth:`~object.__aiter__` must return an
3943 asynchronous iterator object. Returning anything else
3944 will result in a :exc:`TypeError` error.
3945
3946
3947 .. _async-context-managers:
3948
3949 Asynchronous Context Managers
3950 -----------------------------
3951
3952 An *asynchronous context manager* is a *context manager* that is able to
3953 suspend execution in its ``__aenter__`` and ``__aexit__`` methods.
3954
3955 Asynchronous context managers can be used in an :keyword:`async with` statement.
3956
3957 The :class:`object` class itself does not provide these methods.
3958
3959 .. method:: object.__aenter__(self)
3960
3961 Semantically similar to :meth:`~object.__enter__`, the only
3962 difference being that it must return an *awaitable*.
3963
3964 .. method:: object.__aexit__(self, exc_type, exc_value, traceback)
3965
3966 Semantically similar to :meth:`~object.__exit__`, the only
3967 difference being that it must return an *awaitable*.
3968
3969 An example of an asynchronous context manager class::
3970
3971 class AsyncContextManager:
3972 async def __aenter__(self):
3973 await log('entering context')
3974
3975 async def __aexit__(self, exc_type, exc, tb):
3976 await log('exiting context')
3977
3978 .. versionadded:: 3.5
3979
3980
3981 .. rubric:: Footnotes
3982
3983 .. [#] It *is* possible in some cases to change an object's type, under certain
3984 controlled conditions. It generally isn't a good idea though, since it can
3985 lead to some very strange behaviour if it is handled incorrectly.
3986
3987 .. [#] The :meth:`~object.__hash__`, :meth:`~object.__iter__`,
3988 :meth:`~object.__reversed__`, :meth:`~object.__contains__`,
3989 :meth:`~object.__class_getitem__` and :meth:`~os.PathLike.__fspath__`
3990 methods have special handling for this. Others
3991 will still raise a :exc:`TypeError`, but may do so by relying on
3992 the behavior that ``None`` is not callable.
3993
3994 .. [#] "Does not support" here means that the class has no such method, or
3995 the method returns :data:`NotImplemented`. Do not set the method to
3996 ``None`` if you want to force fallback to the right operand's reflected
3997 method—that will instead have the opposite effect of explicitly
3998 *blocking* such fallback.
3999
4000 .. [#] For operands of the same type, it is assumed that if the non-reflected method
4001 (such as :meth:`~object.__add__`) fails then the operation is not supported, which is why the
4002 reflected method is not called.
4003
4004 .. [#] If the right operand's type is a subclass of the left operand's type, the
4005 reflected method having precedence allows subclasses to override their ancestors'
4006 operations.