1 2.. _datamodel: 3 4********** 5Data model 6********** 7 8 9.. _objects: 10 11Objects, 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 19is represented by objects or by relations between objects. (In a sense, and in 20conformance to Von Neumann's model of a "stored program computer", code is also 21represented by objects.) 22 23.. index:: 24 builtin: id 25 builtin: type 26 single: identity of an object 27 single: value of an object 28 single: type of an object 29 single: mutable object 30 single: immutable object 31 32.. XXX it *is* now possible in some cases to change an object's 33 type, under certain controlled conditions 34 35Every object has an identity, a type and a value. An object's *identity* never 36changes once it has been created; you may think of it as the object's address in 37memory. The ':keyword:`is`' operator compares the identity of two objects; the 38:func:`id` function returns an integer representing its identity. 39 40.. impl-detail:: 41 42 For CPython, ``id(x)`` is the memory address where ``x`` is stored. 43 44An object's type determines the operations that the object supports (e.g., "does 45it have a length?") and also defines the possible values for objects of that 46type. The :func:`type` function returns an object's type (which is an object 47itself). Like its identity, an object's :dfn:`type` is also unchangeable. 48[#]_ 49 50The *value* of some objects can change. Objects whose value can 51change are said to be *mutable*; objects whose value is unchangeable once they 52are created are called *immutable*. (The value of an immutable container object 53that contains a reference to a mutable object can change when the latter's value 54is changed; however the container is still considered immutable, because the 55collection of objects it contains cannot be changed. So, immutability is not 56strictly the same as having an unchangeable value, it is more subtle.) An 57object's mutability is determined by its type; for instance, numbers, strings 58and tuples are immutable, while dictionaries and lists are mutable. 59 60.. index:: 61 single: garbage collection 62 single: reference counting 63 single: unreachable object 64 65Objects are never explicitly destroyed; however, when they become unreachable 66they may be garbage-collected. An implementation is allowed to postpone garbage 67collection or omit it altogether --- it is a matter of implementation quality 68how garbage collection is implemented, as long as no objects are collected that 69are still reachable. 70 71.. impl-detail:: 72 73 CPython currently uses a reference-counting scheme with (optional) delayed 74 detection of cyclically linked garbage, which collects most objects as soon 75 as they become unreachable, but is not guaranteed to collect garbage 76 containing circular references. See the documentation of the :mod:`gc` 77 module for information on controlling the collection of cyclic garbage. 78 Other implementations act differently and CPython may change. 79 Do not depend on immediate finalization of objects when they become 80 unreachable (so you should always close files explicitly). 81 82Note that the use of the implementation's tracing or debugging facilities may 83keep objects alive that would normally be collectable. Also note that catching 84an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep 85objects alive. 86 87Some objects contain references to "external" resources such as open files or 88windows. It is understood that these resources are freed when the object is 89garbage-collected, but since garbage collection is not guaranteed to happen, 90such objects also provide an explicit way to release the external resource, 91usually a :meth:`close` method. Programs are strongly recommended to explicitly 92close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement 93and the ':keyword:`with`' statement provide convenient ways to do this. 94 95.. index:: single: container 96 97Some objects contain references to other objects; these are called *containers*. 98Examples of containers are tuples, lists and dictionaries. The references are 99part of a container's value. In most cases, when we talk about the value of a 100container, we imply the values, not the identities of the contained objects; 101however, when we talk about the mutability of a container, only the identities 102of the immediately contained objects are implied. So, if an immutable container 103(like a tuple) contains a reference to a mutable object, its value changes if 104that mutable object is changed. 105 106Types affect almost all aspects of object behavior. Even the importance of 107object identity is affected in some sense: for immutable types, operations that 108compute new values may actually return a reference to any existing object with 109the same type and value, while for mutable objects this is not allowed. E.g., 110after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object 111with the value one, depending on the implementation, but after ``c = []; d = 112[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly 113created empty lists. (Note that ``c = d = []`` assigns the same object to both 114``c`` and ``d``.) 115 116 117.. _types: 118 119The 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 129Below 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 131define additional types. Future versions of Python may add types to the type 132hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.), 133although 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 140Some of the type descriptions below contain a paragraph listing 'special 141attributes.' These are attributes that provide access to the implementation and 142are not intended for general use. Their definition may change in the future. 143 144None 145 .. index:: object: None 146 147 This type has a single value. There is a single object with this value. This 148 object is accessed through the built-in name ``None``. It is used to signify the 149 absence of a value in many situations, e.g., it is returned from functions that 150 don't explicitly return anything. Its truth value is false. 151 152NotImplemented 153 .. index:: object: NotImplemented 154 155 This type has a single value. There is a single object with this value. This 156 object is accessed through the built-in name ``NotImplemented``. Numeric methods 157 and rich comparison methods should return this value if they do not implement the 158 operation for the operands provided. (The interpreter will then try the 159 reflected operation, or some other fallback, depending on the operator.) Its 160 truth value is true. 161 162 See 163 :ref:`implementing-the-arithmetic-operations` 164 for more details. 165 166 167Ellipsis 168 .. index:: 169 object: Ellipsis 170 single: ...; ellipsis literal 171 172 This type has a single value. There is a single object with this value. This 173 object is accessed through the literal ``...`` or the built-in name 174 ``Ellipsis``. Its truth value is true. 175 176:class:`numbers.Number` 177 .. index:: object: numeric 178 179 These are created by numeric literals and returned as results by arithmetic 180 operators and arithmetic built-in functions. Numeric objects are immutable; 181 once created their value never changes. Python numbers are of course strongly 182 related to mathematical numbers, but subject to the limitations of numerical 183 representation in computers. 184 185 The string representations of the numeric classes, computed by 186 :meth:`__repr__` and :meth:`__str__`, have the following 187 properties: 188 189 * They are valid numeric literals which, when passed to their 190 class constructor, produce an object having the value of the 191 original numeric. 192 193 * The representation is in base 10, when possible. 194 195 * Leading zeros, possibly excepting a single zero before a 196 decimal point, are not shown. 197 198 * Trailing zeros, possibly excepting a single zero after a 199 decimal point, are not shown. 200 201 * A sign is shown only when the number is negative. 202 203 Python distinguishes between integers, floating point numbers, and complex 204 numbers: 205 206 :class:`numbers.Integral` 207 .. index:: object: integer 208 209 These represent elements from the mathematical set of integers (positive and 210 negative). 211 212 There are two types of integers: 213 214 Integers (:class:`int`) 215 These represent numbers in an unlimited range, subject to available (virtual) 216 memory only. For the purpose of shift and mask operations, a binary 217 representation is assumed, and negative numbers are represented in a variant of 218 2's complement which gives the illusion of an infinite string of sign bits 219 extending to the left. 220 221 Booleans (:class:`bool`) 222 .. index:: 223 object: Boolean 224 single: False 225 single: True 226 227 These represent the truth values False and True. The two objects representing 228 the values ``False`` and ``True`` are the only Boolean objects. The Boolean type is a 229 subtype of the integer type, and Boolean values behave like the values 0 and 1, 230 respectively, in almost all contexts, the exception being that when converted to 231 a string, the strings ``"False"`` or ``"True"`` are returned, respectively. 232 233 .. index:: pair: integer; representation 234 235 The rules for integer representation are intended to give the most meaningful 236 interpretation of shift and mask operations involving negative integers. 237 238 :class:`numbers.Real` (:class:`float`) 239 .. index:: 240 object: floating point 241 pair: floating point; number 242 pair: C; language 243 pair: Java; language 244 245 These represent machine-level double precision floating point numbers. You are 246 at the mercy of the underlying machine architecture (and C or Java 247 implementation) for the accepted range and handling of overflow. Python does not 248 support single-precision floating point numbers; the savings in processor and 249 memory usage that are usually the reason for using these are dwarfed by the 250 overhead of using objects in Python, so there is no reason to complicate the 251 language with two kinds of floating point numbers. 252 253 :class:`numbers.Complex` (:class:`complex`) 254 .. index:: 255 object: complex 256 pair: complex; number 257 258 These represent complex numbers as a pair of machine-level double precision 259 floating point numbers. The same caveats apply as for floating point numbers. 260 The real and imaginary parts of a complex number ``z`` can be retrieved through 261 the read-only attributes ``z.real`` and ``z.imag``. 262 263Sequences 264 .. index:: 265 builtin: len 266 object: sequence 267 single: index operation 268 single: item selection 269 single: subscription 270 271 These represent finite ordered sets indexed by non-negative numbers. The 272 built-in function :func:`len` returns the number of items of a sequence. When 273 the length of a sequence is *n*, the index set contains the numbers 0, 1, 274 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. 275 276 .. index:: single: slicing 277 278 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such 279 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a 280 sequence of the same type. This implies that the index set is renumbered so 281 that it starts at 0. 282 283 Some sequences also support "extended slicing" with a third "step" parameter: 284 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n* 285 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*. 286 287 Sequences are distinguished according to their mutability: 288 289 Immutable sequences 290 .. index:: 291 object: immutable sequence 292 object: immutable 293 294 An object of an immutable sequence type cannot change once it is created. (If 295 the object contains references to other objects, these other objects may be 296 mutable and may be changed; however, the collection of objects directly 297 referenced by an immutable object cannot change.) 298 299 The following types are immutable sequences: 300 301 .. index:: 302 single: string; immutable sequences 303 304 Strings 305 .. index:: 306 builtin: chr 307 builtin: ord 308 single: character 309 single: integer 310 single: Unicode 311 312 A string is a sequence of values that represent Unicode code points. 313 All the code points in the range ``U+0000 - U+10FFFF`` can be 314 represented in a string. Python doesn't have a :c:type:`char` type; 315 instead, every code point in the string is represented as a string 316 object with length ``1``. The built-in function :func:`ord` 317 converts a code point from its string form to an integer in the 318 range ``0 - 10FFFF``; :func:`chr` converts an integer in the range 319 ``0 - 10FFFF`` to the corresponding length ``1`` string object. 320 :meth:`str.encode` can be used to convert a :class:`str` to 321 :class:`bytes` using the given text encoding, and 322 :meth:`bytes.decode` can be used to achieve the opposite. 323 324 Tuples 325 .. index:: 326 object: tuple 327 pair: singleton; tuple 328 pair: empty; tuple 329 330 The items of a tuple are arbitrary Python objects. Tuples of two or 331 more items are formed by comma-separated lists of expressions. A tuple 332 of one item (a 'singleton') can be formed by affixing a comma to an 333 expression (an expression by itself does not create a tuple, since 334 parentheses must be usable for grouping of expressions). An empty 335 tuple can be formed by an empty pair of parentheses. 336 337 Bytes 338 .. index:: bytes, byte 339 340 A bytes object is an immutable array. The items are 8-bit bytes, 341 represented by integers in the range 0 <= x < 256. Bytes literals 342 (like ``b'abc'``) and the built-in :func:`bytes()` constructor 343 can be used to create bytes objects. Also, bytes objects can be 344 decoded to strings via the :meth:`~bytes.decode` method. 345 346 Mutable sequences 347 .. index:: 348 object: mutable sequence 349 object: mutable 350 pair: assignment; statement 351 single: subscription 352 single: slicing 353 354 Mutable sequences can be changed after they are created. The subscription and 355 slicing notations can be used as the target of assignment and :keyword:`del` 356 (delete) statements. 357 358 There are currently two intrinsic mutable sequence types: 359 360 Lists 361 .. index:: object: list 362 363 The items of a list are arbitrary Python objects. Lists are formed by 364 placing a comma-separated list of expressions in square brackets. (Note 365 that there are no special cases needed to form lists of length 0 or 1.) 366 367 Byte Arrays 368 .. index:: bytearray 369 370 A bytearray object is a mutable array. They are created by the built-in 371 :func:`bytearray` constructor. Aside from being mutable 372 (and hence unhashable), byte arrays otherwise provide the same interface 373 and functionality as immutable :class:`bytes` objects. 374 375 .. index:: module: array 376 377 The extension module :mod:`array` provides an additional example of a 378 mutable sequence type, as does the :mod:`collections` module. 379 380Set types 381 .. index:: 382 builtin: len 383 object: set type 384 385 These represent unordered, finite sets of unique, immutable objects. As such, 386 they cannot be indexed by any subscript. However, they can be iterated over, and 387 the built-in function :func:`len` returns the number of items in a set. Common 388 uses for sets are fast membership testing, removing duplicates from a sequence, 389 and computing mathematical operations such as intersection, union, difference, 390 and symmetric difference. 391 392 For set elements, the same immutability rules apply as for dictionary keys. Note 393 that numeric types obey the normal rules for numeric comparison: if two numbers 394 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a 395 set. 396 397 There are currently two intrinsic set types: 398 399 Sets 400 .. index:: object: set 401 402 These represent a mutable set. They are created by the built-in :func:`set` 403 constructor and can be modified afterwards by several methods, such as 404 :meth:`~set.add`. 405 406 Frozen sets 407 .. index:: object: frozenset 408 409 These represent an immutable set. They are created by the built-in 410 :func:`frozenset` constructor. As a frozenset is immutable and 411 :term:`hashable`, it can be used again as an element of another set, or as 412 a dictionary key. 413 414Mappings 415 .. index:: 416 builtin: len 417 single: subscription 418 object: mapping 419 420 These represent finite sets of objects indexed by arbitrary index sets. The 421 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping 422 ``a``; this can be used in expressions and as the target of assignments or 423 :keyword:`del` statements. The built-in function :func:`len` returns the number 424 of items in a mapping. 425 426 There is currently a single intrinsic mapping type: 427 428 Dictionaries 429 .. index:: object: dictionary 430 431 These represent finite sets of objects indexed by nearly arbitrary values. The 432 only types of values not acceptable as keys are values containing lists or 433 dictionaries or other mutable types that are compared by value rather than by 434 object identity, the reason being that the efficient implementation of 435 dictionaries requires a key's hash value to remain constant. Numeric types used 436 for keys obey the normal rules for numeric comparison: if two numbers compare 437 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index 438 the same dictionary entry. 439 440 Dictionaries preserve insertion order, meaning that keys will be produced 441 in the same order they were added sequentially over the dictionary. 442 Replacing an existing key does not change the order, however removing a key 443 and re-inserting it will add it to the end instead of keeping its old place. 444 445 Dictionaries are mutable; they can be created by the ``{...}`` notation (see 446 section :ref:`dict`). 447 448 .. index:: 449 module: dbm.ndbm 450 module: dbm.gnu 451 452 The extension modules :mod:`dbm.ndbm` and :mod:`dbm.gnu` provide 453 additional examples of mapping types, as does the :mod:`collections` 454 module. 455 456 .. versionchanged:: 3.7 457 Dictionaries did not preserve insertion order in versions of Python before 3.6. 458 In CPython 3.6, insertion order was preserved, but it was considered 459 an implementation detail at that time rather than a language guarantee. 460 461Callable types 462 .. index:: 463 object: callable 464 pair: function; call 465 single: invocation 466 pair: function; argument 467 468 These are the types to which the function call operation (see section 469 :ref:`calls`) can be applied: 470 471 User-defined functions 472 .. index:: 473 pair: user-defined; function 474 object: function 475 object: user-defined function 476 477 A user-defined function object is created by a function definition (see 478 section :ref:`function`). It should be called with an argument list 479 containing the same number of items as the function's formal parameter 480 list. 481 482 Special attributes: 483 484 .. tabularcolumns:: |l|L|l| 485 486 .. index:: 487 single: __doc__ (function attribute) 488 single: __name__ (function attribute) 489 single: __module__ (function attribute) 490 single: __dict__ (function attribute) 491 single: __defaults__ (function attribute) 492 single: __closure__ (function attribute) 493 single: __code__ (function attribute) 494 single: __globals__ (function attribute) 495 single: __annotations__ (function attribute) 496 single: __kwdefaults__ (function attribute) 497 pair: global; namespace 498 499 +-------------------------+-------------------------------+-----------+ 500 | Attribute | Meaning | | 501 +=========================+===============================+===========+ 502 | :attr:`__doc__` | The function's documentation | Writable | 503 | | string, or ``None`` if | | 504 | | unavailable; not inherited by | | 505 | | subclasses. | | 506 +-------------------------+-------------------------------+-----------+ 507 | :attr:`~definition.\ | The function's name. | Writable | 508 | __name__` | | | 509 +-------------------------+-------------------------------+-----------+ 510 | :attr:`~definition.\ | The function's | Writable | 511 | __qualname__` | :term:`qualified name`. | | 512 | | | | 513 | | .. versionadded:: 3.3 | | 514 +-------------------------+-------------------------------+-----------+ 515 | :attr:`__module__` | The name of the module the | Writable | 516 | | function was defined in, or | | 517 | | ``None`` if unavailable. | | 518 +-------------------------+-------------------------------+-----------+ 519 | :attr:`__defaults__` | A tuple containing default | Writable | 520 | | argument values for those | | 521 | | arguments that have defaults, | | 522 | | or ``None`` if no arguments | | 523 | | have a default value. | | 524 +-------------------------+-------------------------------+-----------+ 525 | :attr:`__code__` | The code object representing | Writable | 526 | | the compiled function body. | | 527 +-------------------------+-------------------------------+-----------+ 528 | :attr:`__globals__` | A reference to the dictionary | Read-only | 529 | | that holds the function's | | 530 | | global variables --- the | | 531 | | global namespace of the | | 532 | | module in which the function | | 533 | | was defined. | | 534 +-------------------------+-------------------------------+-----------+ 535 | :attr:`~object.__dict__`| The namespace supporting | Writable | 536 | | arbitrary function | | 537 | | attributes. | | 538 +-------------------------+-------------------------------+-----------+ 539 | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only | 540 | | that contain bindings for the | | 541 | | function's free variables. | | 542 | | See below for information on | | 543 | | the ``cell_contents`` | | 544 | | attribute. | | 545 +-------------------------+-------------------------------+-----------+ 546 | :attr:`__annotations__` | A dict containing annotations | Writable | 547 | | of parameters. The keys of | | 548 | | the dict are the parameter | | 549 | | names, and ``'return'`` for | | 550 | | the return annotation, if | | 551 | | provided. | | 552 +-------------------------+-------------------------------+-----------+ 553 | :attr:`__kwdefaults__` | A dict containing defaults | Writable | 554 | | for keyword-only parameters. | | 555 +-------------------------+-------------------------------+-----------+ 556 557 Most of the attributes labelled "Writable" check the type of the assigned value. 558 559 Function objects also support getting and setting arbitrary attributes, which 560 can be used, for example, to attach metadata to functions. Regular attribute 561 dot-notation is used to get and set such attributes. *Note that the current 562 implementation only supports function attributes on user-defined functions. 563 Function attributes on built-in functions may be supported in the future.* 564 565 A cell object has the attribute ``cell_contents``. This can be used to get 566 the value of the cell, as well as set the value. 567 568 Additional information about a function's definition can be retrieved from its 569 code object; see the description of internal types below. The 570 :data:`cell <types.CellType>` type can be accessed in the :mod:`types` 571 module. 572 573 Instance methods 574 .. index:: 575 object: method 576 object: user-defined method 577 pair: user-defined; method 578 579 An instance method object combines a class, a class instance and any 580 callable object (normally a user-defined function). 581 582 .. index:: 583 single: __func__ (method attribute) 584 single: __self__ (method attribute) 585 single: __doc__ (method attribute) 586 single: __name__ (method attribute) 587 single: __module__ (method attribute) 588 589 Special read-only attributes: :attr:`__self__` is the class instance object, 590 :attr:`__func__` is the function object; :attr:`__doc__` is the method's 591 documentation (same as ``__func__.__doc__``); :attr:`~definition.__name__` is the 592 method name (same as ``__func__.__name__``); :attr:`__module__` is the 593 name of the module the method was defined in, or ``None`` if unavailable. 594 595 Methods also support accessing (but not setting) the arbitrary function 596 attributes on the underlying function object. 597 598 User-defined method objects may be created when getting an attribute of a 599 class (perhaps via an instance of that class), if that attribute is a 600 user-defined function object or a class method object. 601 602 When an instance method object is created by retrieving a user-defined 603 function object from a class via one of its instances, its 604 :attr:`__self__` attribute is the instance, and the method object is said 605 to be bound. The new method's :attr:`__func__` attribute is the original 606 function object. 607 608 When an instance method object is created by retrieving a class method 609 object from a class or instance, its :attr:`__self__` attribute is the 610 class itself, and its :attr:`__func__` attribute is the function object 611 underlying the class method. 612 613 When an instance method object is called, the underlying function 614 (:attr:`__func__`) is called, inserting the class instance 615 (:attr:`__self__`) in front of the argument list. For instance, when 616 :class:`C` is a class which contains a definition for a function 617 :meth:`f`, and ``x`` is an instance of :class:`C`, calling ``x.f(1)`` is 618 equivalent to calling ``C.f(x, 1)``. 619 620 When an instance method object is derived from a class method object, the 621 "class instance" stored in :attr:`__self__` will actually be the class 622 itself, so that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to 623 calling ``f(C,1)`` where ``f`` is the underlying function. 624 625 Note that the transformation from function object to instance method 626 object happens each time the attribute is retrieved from the instance. In 627 some cases, a fruitful optimization is to assign the attribute to a local 628 variable and call that local variable. Also notice that this 629 transformation only happens for user-defined functions; other callable 630 objects (and all non-callable objects) are retrieved without 631 transformation. It is also important to note that user-defined functions 632 which are attributes of a class instance are not converted to bound 633 methods; this *only* happens when the function is an attribute of the 634 class. 635 636 Generator functions 637 .. index:: 638 single: generator; function 639 single: generator; iterator 640 641 A function or method which uses the :keyword:`yield` statement (see section 642 :ref:`yield`) is called a :dfn:`generator function`. Such a function, when 643 called, always returns an iterator object which can be used to execute the 644 body of the function: calling the iterator's :meth:`iterator.__next__` 645 method will cause the function to execute until it provides a value 646 using the :keyword:`!yield` statement. When the function executes a 647 :keyword:`return` statement or falls off the end, a :exc:`StopIteration` 648 exception is raised and the iterator will have reached the end of the set of 649 values to be returned. 650 651 Coroutine functions 652 .. index:: 653 single: coroutine; function 654 655 A function or method which is defined using :keyword:`async def` is called 656 a :dfn:`coroutine function`. Such a function, when called, returns a 657 :term:`coroutine` object. It may contain :keyword:`await` expressions, 658 as well as :keyword:`async with` and :keyword:`async for` statements. See 659 also the :ref:`coroutine-objects` section. 660 661 Asynchronous generator functions 662 .. index:: 663 single: asynchronous generator; function 664 single: asynchronous generator; asynchronous iterator 665 666 A function or method which is defined using :keyword:`async def` and 667 which uses the :keyword:`yield` statement is called a 668 :dfn:`asynchronous generator function`. Such a function, when called, 669 returns an asynchronous iterator object which can be used in an 670 :keyword:`async for` statement to execute the body of the function. 671 672 Calling the asynchronous iterator's :meth:`aiterator.__anext__` method 673 will return an :term:`awaitable` which when awaited 674 will execute until it provides a value using the :keyword:`yield` 675 expression. When the function executes an empty :keyword:`return` 676 statement or falls off the end, a :exc:`StopAsyncIteration` exception 677 is raised and the asynchronous iterator will have reached the end of 678 the set of values to be yielded. 679 680 Built-in functions 681 .. index:: 682 object: built-in function 683 object: function 684 pair: C; language 685 686 A built-in function object is a wrapper around a C function. Examples of 687 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a 688 standard built-in module). The number and type of the arguments are 689 determined by the C function. Special read-only attributes: 690 :attr:`__doc__` is the function's documentation string, or ``None`` if 691 unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is 692 set to ``None`` (but see the next item); :attr:`__module__` is the name of 693 the module the function was defined in or ``None`` if unavailable. 694 695 Built-in methods 696 .. index:: 697 object: built-in method 698 object: method 699 pair: built-in; method 700 701 This is really a different disguise of a built-in function, this time containing 702 an object passed to the C function as an implicit extra argument. An example of 703 a built-in method is ``alist.append()``, assuming *alist* is a list object. In 704 this case, the special read-only attribute :attr:`__self__` is set to the object 705 denoted by *alist*. 706 707 Classes 708 Classes are callable. These objects normally act as factories for new 709 instances of themselves, but variations are possible for class types that 710 override :meth:`__new__`. The arguments of the call are passed to 711 :meth:`__new__` and, in the typical case, to :meth:`__init__` to 712 initialize the new instance. 713 714 Class Instances 715 Instances of arbitrary classes can be made callable by defining a 716 :meth:`__call__` method in their class. 717 718 719Modules 720 .. index:: 721 statement: import 722 object: module 723 724 Modules are a basic organizational unit of Python code, and are created by 725 the :ref:`import system <importsystem>` as invoked either by the 726 :keyword:`import` statement, or by calling 727 functions such as :func:`importlib.import_module` and built-in 728 :func:`__import__`. A module object has a namespace implemented by a 729 dictionary object (this is the dictionary referenced by the ``__globals__`` 730 attribute of functions defined in the module). Attribute references are 731 translated to lookups in this dictionary, e.g., ``m.x`` is equivalent to 732 ``m.__dict__["x"]``. A module object does not contain the code object used 733 to initialize the module (since it isn't needed once the initialization is 734 done). 735 736 Attribute assignment updates the module's namespace dictionary, e.g., 737 ``m.x = 1`` is equivalent to ``m.__dict__["x"] = 1``. 738 739 .. index:: 740 single: __name__ (module attribute) 741 single: __doc__ (module attribute) 742 single: __file__ (module attribute) 743 single: __annotations__ (module attribute) 744 pair: module; namespace 745 746 Predefined (writable) attributes: :attr:`__name__` is the module's name; 747 :attr:`__doc__` is the module's documentation string, or ``None`` if 748 unavailable; :attr:`__annotations__` (optional) is a dictionary containing 749 :term:`variable annotations <variable annotation>` collected during module 750 body execution; :attr:`__file__` is the pathname of the file from which the 751 module was loaded, if it was loaded from a file. The :attr:`__file__` 752 attribute may be missing for certain types of modules, such as C modules 753 that are statically linked into the interpreter; for extension modules 754 loaded dynamically from a shared library, it is the pathname of the shared 755 library file. 756 757 .. index:: single: __dict__ (module attribute) 758 759 Special read-only attribute: :attr:`~object.__dict__` is the module's 760 namespace as a dictionary object. 761 762 .. impl-detail:: 763 764 Because of the way CPython clears module dictionaries, the module 765 dictionary will be cleared when the module falls out of scope even if the 766 dictionary still has live references. To avoid this, copy the dictionary 767 or keep the module around while using its dictionary directly. 768 769Custom classes 770 Custom class types are typically created by class definitions (see section 771 :ref:`class`). A class has a namespace implemented by a dictionary object. 772 Class attribute references are translated to lookups in this dictionary, e.g., 773 ``C.x`` is translated to ``C.__dict__["x"]`` (although there are a number of 774 hooks which allow for other means of locating attributes). When the attribute 775 name is not found there, the attribute search continues in the base classes. 776 This search of the base classes uses the C3 method resolution order which 777 behaves correctly even in the presence of 'diamond' inheritance structures 778 where there are multiple inheritance paths leading back to a common ancestor. 779 Additional details on the C3 MRO used by Python can be found in the 780 documentation accompanying the 2.3 release at 781 https://www.python.org/download/releases/2.3/mro/. 782 783 .. XXX: Could we add that MRO doc as an appendix to the language ref? 784 785 .. index:: 786 object: class 787 object: class instance 788 object: instance 789 pair: class object; call 790 single: container 791 object: dictionary 792 pair: class; attribute 793 794 When a class attribute reference (for class :class:`C`, say) would yield a 795 class method object, it is transformed into an instance method object whose 796 :attr:`__self__` attribute is :class:`C`. When it would yield a static 797 method object, it is transformed into the object wrapped by the static method 798 object. See section :ref:`descriptors` for another way in which attributes 799 retrieved from a class may differ from those actually contained in its 800 :attr:`~object.__dict__`. 801 802 .. index:: triple: class; attribute; assignment 803 804 Class attribute assignments update the class's dictionary, never the dictionary 805 of a base class. 806 807 .. index:: pair: class object; call 808 809 A class object can be called (see above) to yield a class instance (see below). 810 811 .. index:: 812 single: __name__ (class attribute) 813 single: __module__ (class attribute) 814 single: __dict__ (class attribute) 815 single: __bases__ (class attribute) 816 single: __doc__ (class attribute) 817 single: __annotations__ (class attribute) 818 819 Special attributes: :attr:`~definition.__name__` is the class name; :attr:`__module__` is 820 the module name in which the class was defined; :attr:`~object.__dict__` is the 821 dictionary containing the class's namespace; :attr:`~class.__bases__` is a 822 tuple containing the base classes, in the order of their occurrence in the 823 base class list; :attr:`__doc__` is the class's documentation string, 824 or ``None`` if undefined; :attr:`__annotations__` (optional) is a dictionary 825 containing :term:`variable annotations <variable annotation>` collected during 826 class body execution. 827 828Class instances 829 .. index:: 830 object: class instance 831 object: instance 832 pair: class; instance 833 pair: class instance; attribute 834 835 A class instance is created by calling a class object (see above). A class 836 instance has a namespace implemented as a dictionary which is the first place 837 in which attribute references are searched. When an attribute is not found 838 there, and the instance's class has an attribute by that name, the search 839 continues with the class attributes. If a class attribute is found that is a 840 user-defined function object, it is transformed into an instance method 841 object whose :attr:`__self__` attribute is the instance. Static method and 842 class method objects are also transformed; see above under "Classes". See 843 section :ref:`descriptors` for another way in which attributes of a class 844 retrieved via its instances may differ from the objects actually stored in 845 the class's :attr:`~object.__dict__`. If no class attribute is found, and the 846 object's class has a :meth:`__getattr__` method, that is called to satisfy 847 the lookup. 848 849 .. index:: triple: class instance; attribute; assignment 850 851 Attribute assignments and deletions update the instance's dictionary, never a 852 class's dictionary. If the class has a :meth:`__setattr__` or 853 :meth:`__delattr__` method, this is called instead of updating the instance 854 dictionary directly. 855 856 .. index:: 857 object: numeric 858 object: sequence 859 object: mapping 860 861 Class instances can pretend to be numbers, sequences, or mappings if they have 862 methods with certain special names. See section :ref:`specialnames`. 863 864 .. index:: 865 single: __dict__ (instance attribute) 866 single: __class__ (instance attribute) 867 868 Special attributes: :attr:`~object.__dict__` is the attribute dictionary; 869 :attr:`~instance.__class__` is the instance's class. 870 871I/O objects (also known as file objects) 872 .. index:: 873 builtin: open 874 module: io 875 single: popen() (in module os) 876 single: makefile() (socket method) 877 single: sys.stdin 878 single: sys.stdout 879 single: sys.stderr 880 single: stdio 881 single: stdin (in module sys) 882 single: stdout (in module sys) 883 single: stderr (in module sys) 884 885 A :term:`file object` represents an open file. Various shortcuts are 886 available to create file objects: the :func:`open` built-in function, and 887 also :func:`os.popen`, :func:`os.fdopen`, and the 888 :meth:`~socket.socket.makefile` method of socket objects (and perhaps by 889 other functions or methods provided by extension modules). 890 891 The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are 892 initialized to file objects corresponding to the interpreter's standard 893 input, output and error streams; they are all open in text mode and 894 therefore follow the interface defined by the :class:`io.TextIOBase` 895 abstract class. 896 897Internal types 898 .. index:: 899 single: internal type 900 single: types, internal 901 902 A few types used internally by the interpreter are exposed to the user. Their 903 definitions may change with future versions of the interpreter, but they are 904 mentioned here for completeness. 905 906 .. index:: bytecode, object; code, code object 907 908 Code objects 909 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`. 910 The difference between a code object and a function object is that the function 911 object contains an explicit reference to the function's globals (the module in 912 which it was defined), while a code object contains no context; also the default 913 argument values are stored in the function object, not in the code object 914 (because they represent values calculated at run-time). Unlike function 915 objects, code objects are immutable and contain no references (directly or 916 indirectly) to mutable objects. 917 918 .. index:: 919 single: co_argcount (code object attribute) 920 single: co_posonlyargcount (code object attribute) 921 single: co_kwonlyargcount (code object attribute) 922 single: co_code (code object attribute) 923 single: co_consts (code object attribute) 924 single: co_filename (code object attribute) 925 single: co_firstlineno (code object attribute) 926 single: co_flags (code object attribute) 927 single: co_lnotab (code object attribute) 928 single: co_name (code object attribute) 929 single: co_names (code object attribute) 930 single: co_nlocals (code object attribute) 931 single: co_stacksize (code object attribute) 932 single: co_varnames (code object attribute) 933 single: co_cellvars (code object attribute) 934 single: co_freevars (code object attribute) 935 936 Special read-only attributes: :attr:`co_name` gives the function name; 937 :attr:`co_argcount` is the total number of positional arguments 938 (including positional-only arguments and arguments with default values); 939 :attr:`co_posonlyargcount` is the number of positional-only arguments 940 (including arguments with default values); :attr:`co_kwonlyargcount` is 941 the number of keyword-only arguments (including arguments with default 942 values); :attr:`co_nlocals` is the number of local variables used by the 943 function (including arguments); :attr:`co_varnames` is a tuple containing 944 the names of the local variables (starting with the argument names); 945 :attr:`co_cellvars` is a tuple containing the names of local variables 946 that are referenced by nested functions; :attr:`co_freevars` is a tuple 947 containing the names of free variables; :attr:`co_code` is a string 948 representing the sequence of bytecode instructions; :attr:`co_consts` is 949 a tuple containing the literals used by the bytecode; :attr:`co_names` is 950 a tuple containing the names used by the bytecode; :attr:`co_filename` is 951 the filename from which the code was compiled; :attr:`co_firstlineno` is 952 the first line number of the function; :attr:`co_lnotab` is a string 953 encoding the mapping from bytecode offsets to line numbers (for details 954 see the source code of the interpreter); :attr:`co_stacksize` is the 955 required stack size; :attr:`co_flags` is an integer encoding a number 956 of flags for the interpreter. 957 958 .. index:: object: generator 959 960 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if 961 the function uses the ``*arguments`` syntax to accept an arbitrary number of 962 positional arguments; bit ``0x08`` is set if the function uses the 963 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set 964 if the function is a generator. 965 966 Future feature declarations (``from __future__ import division``) also use bits 967 in :attr:`co_flags` to indicate whether a code object was compiled with a 968 particular feature enabled: bit ``0x2000`` is set if the function was compiled 969 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier 970 versions of Python. 971 972 Other bits in :attr:`co_flags` are reserved for internal use. 973 974 .. index:: single: documentation string 975 976 If a code object represents a function, the first item in :attr:`co_consts` is 977 the documentation string of the function, or ``None`` if undefined. 978 979 .. _frame-objects: 980 981 Frame objects 982 .. index:: object: frame 983 984 Frame objects represent execution frames. They may occur in traceback objects 985 (see below), and are also passed to registered trace functions. 986 987 .. index:: 988 single: f_back (frame attribute) 989 single: f_code (frame attribute) 990 single: f_globals (frame attribute) 991 single: f_locals (frame attribute) 992 single: f_lasti (frame attribute) 993 single: f_builtins (frame attribute) 994 995 Special read-only attributes: :attr:`f_back` is to the previous stack frame 996 (towards the caller), or ``None`` if this is the bottom stack frame; 997 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals` 998 is the dictionary used to look up local variables; :attr:`f_globals` is used for 999 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names; 1000 :attr:`f_lasti` gives the precise instruction (this is an index into the 1001 bytecode string of the code object). 1002 1003 Accessing ``f_code`` raises an :ref:`auditing event <auditing>` 1004 ``object.__getattr__`` with arguments ``obj`` and ``"f_code"``. 1005 1006 .. index:: 1007 single: f_trace (frame attribute) 1008 single: f_trace_lines (frame attribute) 1009 single: f_trace_opcodes (frame attribute) 1010 single: f_lineno (frame attribute) 1011 1012 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function 1013 called for various events during code execution (this is used by the debugger). 1014 Normally an event is triggered for each new source line - this can be 1015 disabled by setting :attr:`f_trace_lines` to :const:`False`. 1016 1017 Implementations *may* allow per-opcode events to be requested by setting 1018 :attr:`f_trace_opcodes` to :const:`True`. Note that this may lead to 1019 undefined interpreter behaviour if exceptions raised by the trace 1020 function escape to the function being traced. 1021 1022 :attr:`f_lineno` is the current line number of the frame --- writing to this 1023 from within a trace function jumps to the given line (only for the bottom-most 1024 frame). A debugger can implement a Jump command (aka Set Next Statement) 1025 by writing to f_lineno. 1026 1027 Frame objects support one method: 1028 1029 .. method:: frame.clear() 1030 1031 This method clears all references to local variables held by the 1032 frame. Also, if the frame belonged to a generator, the generator 1033 is finalized. This helps break reference cycles involving frame 1034 objects (for example when catching an exception and storing its 1035 traceback for later use). 1036 1037 :exc:`RuntimeError` is raised if the frame is currently executing. 1038 1039 .. versionadded:: 3.4 1040 1041 .. _traceback-objects: 1042 1043 Traceback objects 1044 .. index:: 1045 object: traceback 1046 pair: stack; trace 1047 pair: exception; handler 1048 pair: execution; stack 1049 single: exc_info (in module sys) 1050 single: last_traceback (in module sys) 1051 single: sys.exc_info 1052 single: sys.last_traceback 1053 1054 Traceback objects represent a stack trace of an exception. A traceback object 1055 is implicitly created when an exception occurs, and may also be explicitly 1056 created by calling :class:`types.TracebackType`. 1057 1058 For implicitly created tracebacks, when the search for an exception handler 1059 unwinds the execution stack, at each unwound level a traceback object is 1060 inserted in front of the current traceback. When an exception handler is 1061 entered, the stack trace is made available to the program. (See section 1062 :ref:`try`.) It is accessible as the third item of the 1063 tuple returned by ``sys.exc_info()``, and as the ``__traceback__`` attribute 1064 of the caught exception. 1065 1066 When the program contains no suitable 1067 handler, the stack trace is written (nicely formatted) to the standard error 1068 stream; if the interpreter is interactive, it is also made available to the user 1069 as ``sys.last_traceback``. 1070 1071 For explicitly created tracebacks, it is up to the creator of the traceback 1072 to determine how the ``tb_next`` attributes should be linked to form a 1073 full stack trace. 1074 1075 .. index:: 1076 single: tb_frame (traceback attribute) 1077 single: tb_lineno (traceback attribute) 1078 single: tb_lasti (traceback attribute) 1079 statement: try 1080 1081 Special read-only attributes: 1082 :attr:`tb_frame` points to the execution frame of the current level; 1083 :attr:`tb_lineno` gives the line number where the exception occurred; 1084 :attr:`tb_lasti` indicates the precise instruction. 1085 The line number and last instruction in the traceback may differ from the 1086 line number of its frame object if the exception occurred in a 1087 :keyword:`try` statement with no matching except clause or with a 1088 finally clause. 1089 1090 Accessing ``tb_frame`` raises an :ref:`auditing event <auditing>` 1091 ``object.__getattr__`` with arguments ``obj`` and ``"tb_frame"``. 1092 1093 .. index:: 1094 single: tb_next (traceback attribute) 1095 1096 Special writable attribute: :attr:`tb_next` is the next level in the stack 1097 trace (towards the frame where the exception occurred), or ``None`` if 1098 there is no next level. 1099 1100 .. versionchanged:: 3.7 1101 Traceback objects can now be explicitly instantiated from Python code, 1102 and the ``tb_next`` attribute of existing instances can be updated. 1103 1104 Slice objects 1105 .. index:: builtin: slice 1106 1107 Slice objects are used to represent slices for :meth:`__getitem__` 1108 methods. They are also created by the built-in :func:`slice` function. 1109 1110 .. index:: 1111 single: start (slice object attribute) 1112 single: stop (slice object attribute) 1113 single: step (slice object attribute) 1114 1115 Special read-only attributes: :attr:`~slice.start` is the lower bound; 1116 :attr:`~slice.stop` is the upper bound; :attr:`~slice.step` is the step 1117 value; each is ``None`` if omitted. These attributes can have any type. 1118 1119 Slice objects support one method: 1120 1121 .. method:: slice.indices(self, length) 1122 1123 This method takes a single integer argument *length* and computes 1124 information about the slice that the slice object would describe if 1125 applied to a sequence of *length* items. It returns a tuple of three 1126 integers; respectively these are the *start* and *stop* indices and the 1127 *step* or stride length of the slice. Missing or out-of-bounds indices 1128 are handled in a manner consistent with regular slices. 1129 1130 Static method objects 1131 Static method objects provide a way of defeating the transformation of function 1132 objects to method objects described above. A static method object is a wrapper 1133 around any other object, usually a user-defined method object. When a static 1134 method object is retrieved from a class or a class instance, the object actually 1135 returned is the wrapped object, which is not subject to any further 1136 transformation. Static method objects are not themselves callable, although the 1137 objects they wrap usually are. Static method objects are created by the built-in 1138 :func:`staticmethod` constructor. 1139 1140 Class method objects 1141 A class method object, like a static method object, is a wrapper around another 1142 object that alters the way in which that object is retrieved from classes and 1143 class instances. The behaviour of class method objects upon such retrieval is 1144 described above, under "User-defined methods". Class method objects are created 1145 by the built-in :func:`classmethod` constructor. 1146 1147 1148.. _specialnames: 1149 1150Special method names 1151==================== 1152 1153.. index:: 1154 pair: operator; overloading 1155 single: __getitem__() (mapping object method) 1156 1157A class can implement certain operations that are invoked by special syntax 1158(such as arithmetic operations or subscripting and slicing) by defining methods 1159with special names. This is Python's approach to :dfn:`operator overloading`, 1160allowing classes to define their own behavior with respect to language 1161operators. For instance, if a class defines a method named :meth:`__getitem__`, 1162and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent 1163to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an 1164operation raise an exception when no appropriate method is defined (typically 1165:exc:`AttributeError` or :exc:`TypeError`). 1166 1167Setting a special method to ``None`` indicates that the corresponding 1168operation is not available. For example, if a class sets 1169:meth:`__iter__` to ``None``, the class is not iterable, so calling 1170:func:`iter` on its instances will raise a :exc:`TypeError` (without 1171falling back to :meth:`__getitem__`). [#]_ 1172 1173When implementing a class that emulates any built-in type, it is important that 1174the emulation only be implemented to the degree that it makes sense for the 1175object being modelled. For example, some sequences may work well with retrieval 1176of individual elements, but extracting a slice may not make sense. (One example 1177of this is the :class:`~xml.dom.NodeList` interface in the W3C's Document 1178Object Model.) 1179 1180 1181.. _customization: 1182 1183Basic customization 1184------------------- 1185 1186.. method:: object.__new__(cls[, ...]) 1187 1188 .. index:: pair: subclassing; immutable types 1189 1190 Called to create a new instance of class *cls*. :meth:`__new__` is a static 1191 method (special-cased so you need not declare it as such) that takes the class 1192 of which an instance was requested as its first argument. The remaining 1193 arguments are those passed to the object constructor expression (the call to the 1194 class). The return value of :meth:`__new__` should be the new object instance 1195 (usually an instance of *cls*). 1196 1197 Typical implementations create a new instance of the class by invoking the 1198 superclass's :meth:`__new__` method using ``super().__new__(cls[, ...])`` 1199 with appropriate arguments and then modifying the newly-created instance 1200 as necessary before returning it. 1201 1202 If :meth:`__new__` is invoked during object construction and it returns an 1203 instance or subclass of *cls*, then the new instance’s :meth:`__init__` method 1204 will be invoked like ``__init__(self[, ...])``, where *self* is the new instance 1205 and the remaining arguments are the same as were passed to the object constructor. 1206 1207 If :meth:`__new__` does not return an instance of *cls*, then the new instance's 1208 :meth:`__init__` method will not be invoked. 1209 1210 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like 1211 int, str, or tuple) to customize instance creation. It is also commonly 1212 overridden in custom metaclasses in order to customize class creation. 1213 1214 1215.. method:: object.__init__(self[, ...]) 1216 1217 .. index:: pair: class; constructor 1218 1219 Called after the instance has been created (by :meth:`__new__`), but before 1220 it is returned to the caller. The arguments are those passed to the 1221 class constructor expression. If a base class has an :meth:`__init__` 1222 method, the derived class's :meth:`__init__` method, if any, must explicitly 1223 call it to ensure proper initialization of the base class part of the 1224 instance; for example: ``super().__init__([args...])``. 1225 1226 Because :meth:`__new__` and :meth:`__init__` work together in constructing 1227 objects (:meth:`__new__` to create it, and :meth:`__init__` to customize it), 1228 no non-``None`` value may be returned by :meth:`__init__`; doing so will 1229 cause a :exc:`TypeError` to be raised at runtime. 1230 1231 1232.. method:: object.__del__(self) 1233 1234 .. index:: 1235 single: destructor 1236 single: finalizer 1237 statement: del 1238 1239 Called when the instance is about to be destroyed. This is also called a 1240 finalizer or (improperly) a destructor. If a base class has a 1241 :meth:`__del__` method, the derived class's :meth:`__del__` method, 1242 if any, must explicitly call it to ensure proper deletion of the base 1243 class part of the instance. 1244 1245 It is possible (though not recommended!) for the :meth:`__del__` method 1246 to postpone destruction of the instance by creating a new reference to 1247 it. This is called object *resurrection*. It is implementation-dependent 1248 whether :meth:`__del__` is called a second time when a resurrected object 1249 is about to be destroyed; the current :term:`CPython` implementation 1250 only calls it once. 1251 1252 It is not guaranteed that :meth:`__del__` methods are called for objects 1253 that still exist when the interpreter exits. 1254 1255 .. note:: 1256 1257 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements 1258 the reference count for ``x`` by one, and the latter is only called when 1259 ``x``'s reference count reaches zero. 1260 1261 .. impl-detail:: 1262 It is possible for a reference cycle to prevent the reference count 1263 of an object from going to zero. In this case, the cycle will be 1264 later detected and deleted by the :term:`cyclic garbage collector 1265 <garbage collection>`. A common cause of reference cycles is when 1266 an exception has been caught in a local variable. The frame's 1267 locals then reference the exception, which references its own 1268 traceback, which references the locals of all frames caught in the 1269 traceback. 1270 1271 .. seealso:: 1272 Documentation for the :mod:`gc` module. 1273 1274 .. warning:: 1275 1276 Due to the precarious circumstances under which :meth:`__del__` methods are 1277 invoked, exceptions that occur during their execution are ignored, and a warning 1278 is printed to ``sys.stderr`` instead. In particular: 1279 1280 * :meth:`__del__` can be invoked when arbitrary code is being executed, 1281 including from any arbitrary thread. If :meth:`__del__` needs to take 1282 a lock or invoke any other blocking resource, it may deadlock as 1283 the resource may already be taken by the code that gets interrupted 1284 to execute :meth:`__del__`. 1285 1286 * :meth:`__del__` can be executed during interpreter shutdown. As a 1287 consequence, the global variables it needs to access (including other 1288 modules) may already have been deleted or set to ``None``. Python 1289 guarantees that globals whose name begins with a single underscore 1290 are deleted from their module before other globals are deleted; if 1291 no other references to such globals exist, this may help in assuring 1292 that imported modules are still available at the time when the 1293 :meth:`__del__` method is called. 1294 1295 1296 .. index:: 1297 single: repr() (built-in function); __repr__() (object method) 1298 1299.. method:: object.__repr__(self) 1300 1301 Called by the :func:`repr` built-in function to compute the "official" string 1302 representation of an object. If at all possible, this should look like a 1303 valid Python expression that could be used to recreate an object with the 1304 same value (given an appropriate environment). If this is not possible, a 1305 string of the form ``<...some useful description...>`` should be returned. 1306 The return value must be a string object. If a class defines :meth:`__repr__` 1307 but not :meth:`__str__`, then :meth:`__repr__` is also used when an 1308 "informal" string representation of instances of that class is required. 1309 1310 This is typically used for debugging, so it is important that the representation 1311 is information-rich and unambiguous. 1312 1313 .. index:: 1314 single: string; __str__() (object method) 1315 single: format() (built-in function); __str__() (object method) 1316 single: print() (built-in function); __str__() (object method) 1317 1318 1319.. method:: object.__str__(self) 1320 1321 Called by :func:`str(object) <str>` and the built-in functions 1322 :func:`format` and :func:`print` to compute the "informal" or nicely 1323 printable string representation of an object. The return value must be a 1324 :ref:`string <textseq>` object. 1325 1326 This method differs from :meth:`object.__repr__` in that there is no 1327 expectation that :meth:`__str__` return a valid Python expression: a more 1328 convenient or concise representation can be used. 1329 1330 The default implementation defined by the built-in type :class:`object` 1331 calls :meth:`object.__repr__`. 1332 1333 .. XXX what about subclasses of string? 1334 1335 1336.. method:: object.__bytes__(self) 1337 1338 .. index:: builtin: bytes 1339 1340 Called by :ref:`bytes <func-bytes>` to compute a byte-string representation 1341 of an object. This should return a :class:`bytes` object. 1342 1343 .. index:: 1344 single: string; __format__() (object method) 1345 pair: string; conversion 1346 builtin: print 1347 1348 1349.. method:: object.__format__(self, format_spec) 1350 1351 Called by the :func:`format` built-in function, 1352 and by extension, evaluation of :ref:`formatted string literals 1353 <f-strings>` and the :meth:`str.format` method, to produce a "formatted" 1354 string representation of an object. The *format_spec* argument is 1355 a string that contains a description of the formatting options desired. 1356 The interpretation of the *format_spec* argument is up to the type 1357 implementing :meth:`__format__`, however most classes will either 1358 delegate formatting to one of the built-in types, or use a similar 1359 formatting option syntax. 1360 1361 See :ref:`formatspec` for a description of the standard formatting syntax. 1362 1363 The return value must be a string object. 1364 1365 .. versionchanged:: 3.4 1366 The __format__ method of ``object`` itself raises a :exc:`TypeError` 1367 if passed any non-empty string. 1368 1369 .. versionchanged:: 3.7 1370 ``object.__format__(x, '')`` is now equivalent to ``str(x)`` rather 1371 than ``format(str(self), '')``. 1372 1373 1374.. _richcmpfuncs: 1375.. method:: object.__lt__(self, other) 1376 object.__le__(self, other) 1377 object.__eq__(self, other) 1378 object.__ne__(self, other) 1379 object.__gt__(self, other) 1380 object.__ge__(self, other) 1381 1382 .. index:: 1383 single: comparisons 1384 1385 These are the so-called "rich comparison" methods. The correspondence between 1386 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``, 1387 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls 1388 ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls 1389 ``x.__ge__(y)``. 1390 1391 A rich comparison method may return the singleton ``NotImplemented`` if it does 1392 not implement the operation for a given pair of arguments. By convention, 1393 ``False`` and ``True`` are returned for a successful comparison. However, these 1394 methods can return any value, so if the comparison operator is used in a Boolean 1395 context (e.g., in the condition of an ``if`` statement), Python will call 1396 :func:`bool` on the value to determine if the result is true or false. 1397 1398 By default, ``object`` implements :meth:`__eq__` by using ``is``, returning 1399 ``NotImplemented`` in the case of a false comparison: 1400 ``True if x is y else NotImplemented``. For :meth:`__ne__`, by default it 1401 delegates to :meth:`__eq__` and inverts the result unless it is 1402 ``NotImplemented``. There are no other implied relationships among the 1403 comparison operators or default implementations; for example, the truth of 1404 ``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering 1405 operations from a single root operation, see :func:`functools.total_ordering`. 1406 1407 See the paragraph on :meth:`__hash__` for 1408 some important notes on creating :term:`hashable` objects which support 1409 custom comparison operations and are usable as dictionary keys. 1410 1411 There are no swapped-argument versions of these methods (to be used when the 1412 left argument does not support the operation but the right argument does); 1413 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection, 1414 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and 1415 :meth:`__eq__` and :meth:`__ne__` are their own reflection. 1416 If the operands are of different types, and right operand's type is 1417 a direct or indirect subclass of the left operand's type, 1418 the reflected method of the right operand has priority, otherwise 1419 the left operand's method has priority. Virtual subclassing is 1420 not considered. 1421 1422.. method:: object.__hash__(self) 1423 1424 .. index:: 1425 object: dictionary 1426 builtin: hash 1427 1428 Called by built-in function :func:`hash` and for operations on members of 1429 hashed collections including :class:`set`, :class:`frozenset`, and 1430 :class:`dict`. :meth:`__hash__` should return an integer. The only required 1431 property is that objects which compare equal have the same hash value; it is 1432 advised to mix together the hash values of the components of the object that 1433 also play a part in comparison of objects by packing them into a tuple and 1434 hashing the tuple. Example:: 1435 1436 def __hash__(self): 1437 return hash((self.name, self.nick, self.color)) 1438 1439 .. note:: 1440 1441 :func:`hash` truncates the value returned from an object's custom 1442 :meth:`__hash__` method to the size of a :c:type:`Py_ssize_t`. This is 1443 typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds. If an 1444 object's :meth:`__hash__` must interoperate on builds of different bit 1445 sizes, be sure to check the width on all supported builds. An easy way 1446 to do this is with 1447 ``python -c "import sys; print(sys.hash_info.width)"``. 1448 1449 If a class does not define an :meth:`__eq__` method it should not define a 1450 :meth:`__hash__` operation either; if it defines :meth:`__eq__` but not 1451 :meth:`__hash__`, its instances will not be usable as items in hashable 1452 collections. If a class defines mutable objects and implements an 1453 :meth:`__eq__` method, it should not implement :meth:`__hash__`, since the 1454 implementation of hashable collections requires that a key's hash value is 1455 immutable (if the object's hash value changes, it will be in the wrong hash 1456 bucket). 1457 1458 User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods 1459 by default; with them, all objects compare unequal (except with themselves) 1460 and ``x.__hash__()`` returns an appropriate value such that ``x == y`` 1461 implies both that ``x is y`` and ``hash(x) == hash(y)``. 1462 1463 A class that overrides :meth:`__eq__` and does not define :meth:`__hash__` 1464 will have its :meth:`__hash__` implicitly set to ``None``. When the 1465 :meth:`__hash__` method of a class is ``None``, instances of the class will 1466 raise an appropriate :exc:`TypeError` when a program attempts to retrieve 1467 their hash value, and will also be correctly identified as unhashable when 1468 checking ``isinstance(obj, collections.abc.Hashable)``. 1469 1470 If a class that overrides :meth:`__eq__` needs to retain the implementation 1471 of :meth:`__hash__` from a parent class, the interpreter must be told this 1472 explicitly by setting ``__hash__ = <ParentClass>.__hash__``. 1473 1474 If a class that does not override :meth:`__eq__` wishes to suppress hash 1475 support, it should include ``__hash__ = None`` in the class definition. 1476 A class which defines its own :meth:`__hash__` that explicitly raises 1477 a :exc:`TypeError` would be incorrectly identified as hashable by 1478 an ``isinstance(obj, collections.abc.Hashable)`` call. 1479 1480 1481 .. note:: 1482 1483 By default, the :meth:`__hash__` values of str and bytes objects are 1484 "salted" with an unpredictable random value. Although they 1485 remain constant within an individual Python process, they are not 1486 predictable between repeated invocations of Python. 1487 1488 This is intended to provide protection against a denial-of-service caused 1489 by carefully-chosen inputs that exploit the worst case performance of a 1490 dict insertion, O(n^2) complexity. See 1491 http://www.ocert.org/advisories/ocert-2011-003.html for details. 1492 1493 Changing hash values affects the iteration order of sets. 1494 Python has never made guarantees about this ordering 1495 (and it typically varies between 32-bit and 64-bit builds). 1496 1497 See also :envvar:`PYTHONHASHSEED`. 1498 1499 .. versionchanged:: 3.3 1500 Hash randomization is enabled by default. 1501 1502 1503.. method:: object.__bool__(self) 1504 1505 .. index:: single: __len__() (mapping object method) 1506 1507 Called to implement truth value testing and the built-in operation 1508 ``bool()``; should return ``False`` or ``True``. When this method is not 1509 defined, :meth:`__len__` is called, if it is defined, and the object is 1510 considered true if its result is nonzero. If a class defines neither 1511 :meth:`__len__` nor :meth:`__bool__`, all its instances are considered 1512 true. 1513 1514 1515.. _attribute-access: 1516 1517Customizing attribute access 1518---------------------------- 1519 1520The following methods can be defined to customize the meaning of attribute 1521access (use of, assignment to, or deletion of ``x.name``) for class instances. 1522 1523.. XXX explain how descriptors interfere here! 1524 1525 1526.. method:: object.__getattr__(self, name) 1527 1528 Called when the default attribute access fails with an :exc:`AttributeError` 1529 (either :meth:`__getattribute__` raises an :exc:`AttributeError` because 1530 *name* is not an instance attribute or an attribute in the class tree 1531 for ``self``; or :meth:`__get__` of a *name* property raises 1532 :exc:`AttributeError`). This method should either return the (computed) 1533 attribute value or raise an :exc:`AttributeError` exception. 1534 1535 Note that if the attribute is found through the normal mechanism, 1536 :meth:`__getattr__` is not called. (This is an intentional asymmetry between 1537 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency 1538 reasons and because otherwise :meth:`__getattr__` would have no way to access 1539 other attributes of the instance. Note that at least for instance variables, 1540 you can fake total control by not inserting any values in the instance attribute 1541 dictionary (but instead inserting them in another object). See the 1542 :meth:`__getattribute__` method below for a way to actually get total control 1543 over attribute access. 1544 1545 1546.. method:: object.__getattribute__(self, name) 1547 1548 Called unconditionally to implement attribute accesses for instances of the 1549 class. If the class also defines :meth:`__getattr__`, the latter will not be 1550 called unless :meth:`__getattribute__` either calls it explicitly or raises an 1551 :exc:`AttributeError`. This method should return the (computed) attribute value 1552 or raise an :exc:`AttributeError` exception. In order to avoid infinite 1553 recursion in this method, its implementation should always call the base class 1554 method with the same name to access any attributes it needs, for example, 1555 ``object.__getattribute__(self, name)``. 1556 1557 .. note:: 1558 1559 This method may still be bypassed when looking up special methods as the 1560 result of implicit invocation via language syntax or built-in functions. 1561 See :ref:`special-lookup`. 1562 1563 .. audit-event:: object.__getattr__ obj,name object.__getattribute__ 1564 1565 For certain sensitive attribute accesses, raises an 1566 :ref:`auditing event <auditing>` ``object.__getattr__`` with arguments 1567 ``obj`` and ``name``. 1568 1569 1570.. method:: object.__setattr__(self, name, value) 1571 1572 Called when an attribute assignment is attempted. This is called instead of 1573 the normal mechanism (i.e. store the value in the instance dictionary). 1574 *name* is the attribute name, *value* is the value to be assigned to it. 1575 1576 If :meth:`__setattr__` wants to assign to an instance attribute, it should 1577 call the base class method with the same name, for example, 1578 ``object.__setattr__(self, name, value)``. 1579 1580 .. audit-event:: object.__setattr__ obj,name,value object.__setattr__ 1581 1582 For certain sensitive attribute assignments, raises an 1583 :ref:`auditing event <auditing>` ``object.__setattr__`` with arguments 1584 ``obj``, ``name``, ``value``. 1585 1586 1587.. method:: object.__delattr__(self, name) 1588 1589 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This 1590 should only be implemented if ``del obj.name`` is meaningful for the object. 1591 1592 .. audit-event:: object.__delattr__ obj,name object.__delattr__ 1593 1594 For certain sensitive attribute deletions, raises an 1595 :ref:`auditing event <auditing>` ``object.__delattr__`` with arguments 1596 ``obj`` and ``name``. 1597 1598 1599.. method:: object.__dir__(self) 1600 1601 Called when :func:`dir` is called on the object. A sequence must be 1602 returned. :func:`dir` converts the returned sequence to a list and sorts it. 1603 1604 1605Customizing module attribute access 1606^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1607 1608.. index:: 1609 single: __getattr__ (module attribute) 1610 single: __dir__ (module attribute) 1611 single: __class__ (module attribute) 1612 1613Special names ``__getattr__`` and ``__dir__`` can be also used to customize 1614access to module attributes. The ``__getattr__`` function at the module level 1615should accept one argument which is the name of an attribute and return the 1616computed value or raise an :exc:`AttributeError`. If an attribute is 1617not found on a module object through the normal lookup, i.e. 1618:meth:`object.__getattribute__`, then ``__getattr__`` is searched in 1619the module ``__dict__`` before raising an :exc:`AttributeError`. If found, 1620it is called with the attribute name and the result is returned. 1621 1622The ``__dir__`` function should accept no arguments, and return a sequence of 1623strings that represents the names accessible on module. If present, this 1624function overrides the standard :func:`dir` search on a module. 1625 1626For a more fine grained customization of the module behavior (setting 1627attributes, properties, etc.), one can set the ``__class__`` attribute of 1628a module object to a subclass of :class:`types.ModuleType`. For example:: 1629 1630 import sys 1631 from types import ModuleType 1632 1633 class VerboseModule(ModuleType): 1634 def __repr__(self): 1635 return f'Verbose {self.__name__}' 1636 1637 def __setattr__(self, attr, value): 1638 print(f'Setting {attr}...') 1639 super().__setattr__(attr, value) 1640 1641 sys.modules[__name__].__class__ = VerboseModule 1642 1643.. note:: 1644 Defining module ``__getattr__`` and setting module ``__class__`` only 1645 affect lookups made using the attribute access syntax -- directly accessing 1646 the module globals (whether by code within the module, or via a reference 1647 to the module's globals dictionary) is unaffected. 1648 1649.. versionchanged:: 3.5 1650 ``__class__`` module attribute is now writable. 1651 1652.. versionadded:: 3.7 1653 ``__getattr__`` and ``__dir__`` module attributes. 1654 1655.. seealso:: 1656 1657 :pep:`562` - Module __getattr__ and __dir__ 1658 Describes the ``__getattr__`` and ``__dir__`` functions on modules. 1659 1660 1661.. _descriptors: 1662 1663Implementing Descriptors 1664^^^^^^^^^^^^^^^^^^^^^^^^ 1665 1666The following methods only apply when an instance of the class containing the 1667method (a so-called *descriptor* class) appears in an *owner* class (the 1668descriptor must be in either the owner's class dictionary or in the class 1669dictionary for one of its parents). In the examples below, "the attribute" 1670refers to the attribute whose name is the key of the property in the owner 1671class' :attr:`~object.__dict__`. 1672 1673 1674.. method:: object.__get__(self, instance, owner=None) 1675 1676 Called to get the attribute of the owner class (class attribute access) or 1677 of an instance of that class (instance attribute access). The optional 1678 *owner* argument is the owner class, while *instance* is the instance that 1679 the attribute was accessed through, or ``None`` when the attribute is 1680 accessed through the *owner*. 1681 1682 This method should return the computed attribute value or raise an 1683 :exc:`AttributeError` exception. 1684 1685 :PEP:`252` specifies that :meth:`__get__` is callable with one or two 1686 arguments. Python's own built-in descriptors support this specification; 1687 however, it is likely that some third-party tools have descriptors 1688 that require both arguments. Python's own :meth:`__getattribute__` 1689 implementation always passes in both arguments whether they are required 1690 or not. 1691 1692.. method:: object.__set__(self, instance, value) 1693 1694 Called to set the attribute on an instance *instance* of the owner class to a 1695 new value, *value*. 1696 1697 Note, adding :meth:`__set__` or :meth:`__delete__` changes the kind of 1698 descriptor to a "data descriptor". See :ref:`descriptor-invocation` for 1699 more details. 1700 1701.. method:: object.__delete__(self, instance) 1702 1703 Called to delete the attribute on an instance *instance* of the owner class. 1704 1705 1706.. method:: object.__set_name__(self, owner, name) 1707 1708 Called at the time the owning class *owner* is created. The 1709 descriptor has been assigned to *name*. 1710 1711 .. note:: 1712 1713 :meth:`__set_name__` is only called implicitly as part of the 1714 :class:`type` constructor, so it will need to be called explicitly with 1715 the appropriate parameters when a descriptor is added to a class after 1716 initial creation:: 1717 1718 class A: 1719 pass 1720 descr = custom_descriptor() 1721 A.attr = descr 1722 descr.__set_name__(A, 'attr') 1723 1724 See :ref:`class-object-creation` for more details. 1725 1726 .. versionadded:: 3.6 1727 1728The attribute :attr:`__objclass__` is interpreted by the :mod:`inspect` module 1729as specifying the class where this object was defined (setting this 1730appropriately can assist in runtime introspection of dynamic class attributes). 1731For callables, it may indicate that an instance of the given type (or a 1732subclass) is expected or required as the first positional argument (for example, 1733CPython sets this attribute for unbound methods that are implemented in C). 1734 1735 1736.. _descriptor-invocation: 1737 1738Invoking Descriptors 1739^^^^^^^^^^^^^^^^^^^^ 1740 1741In general, a descriptor is an object attribute with "binding behavior", one 1742whose attribute access has been overridden by methods in the descriptor 1743protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of 1744those methods are defined for an object, it is said to be a descriptor. 1745 1746The default behavior for attribute access is to get, set, or delete the 1747attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain 1748starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and 1749continuing through the base classes of ``type(a)`` excluding metaclasses. 1750 1751However, if the looked-up value is an object defining one of the descriptor 1752methods, then Python may override the default behavior and invoke the descriptor 1753method instead. Where this occurs in the precedence chain depends on which 1754descriptor methods were defined and how they were called. 1755 1756The starting point for descriptor invocation is a binding, ``a.x``. How the 1757arguments are assembled depends on ``a``: 1758 1759Direct Call 1760 The simplest and least common call is when user code directly invokes a 1761 descriptor method: ``x.__get__(a)``. 1762 1763Instance Binding 1764 If binding to an object instance, ``a.x`` is transformed into the call: 1765 ``type(a).__dict__['x'].__get__(a, type(a))``. 1766 1767Class Binding 1768 If binding to a class, ``A.x`` is transformed into the call: 1769 ``A.__dict__['x'].__get__(None, A)``. 1770 1771Super Binding 1772 If ``a`` is an instance of :class:`super`, then the binding ``super(B, obj).m()`` 1773 searches ``obj.__class__.__mro__`` for the base class ``A`` 1774 immediately preceding ``B`` and then invokes the descriptor with the call: 1775 ``A.__dict__['m'].__get__(obj, obj.__class__)``. 1776 1777For instance bindings, the precedence of descriptor invocation depends on 1778which descriptor methods are defined. A descriptor can define any combination 1779of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not 1780define :meth:`__get__`, then accessing the attribute will return the descriptor 1781object itself unless there is a value in the object's instance dictionary. If 1782the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data 1783descriptor; if it defines neither, it is a non-data descriptor. Normally, data 1784descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data 1785descriptors have just the :meth:`__get__` method. Data descriptors with 1786:meth:`__set__` and :meth:`__get__` defined always override a redefinition in an 1787instance dictionary. In contrast, non-data descriptors can be overridden by 1788instances. 1789 1790Python methods (including :func:`staticmethod` and :func:`classmethod`) are 1791implemented as non-data descriptors. Accordingly, instances can redefine and 1792override methods. This allows individual instances to acquire behaviors that 1793differ from other instances of the same class. 1794 1795The :func:`property` function is implemented as a data descriptor. Accordingly, 1796instances cannot override the behavior of a property. 1797 1798 1799.. _slots: 1800 1801__slots__ 1802^^^^^^^^^ 1803 1804*__slots__* allow us to explicitly declare data members (like 1805properties) and deny the creation of *__dict__* and *__weakref__* 1806(unless explicitly declared in *__slots__* or available in a parent.) 1807 1808The space saved over using *__dict__* can be significant. 1809Attribute lookup speed can be significantly improved as well. 1810 1811.. data:: object.__slots__ 1812 1813 This class variable can be assigned a string, iterable, or sequence of 1814 strings with variable names used by instances. *__slots__* reserves space 1815 for the declared variables and prevents the automatic creation of *__dict__* 1816 and *__weakref__* for each instance. 1817 1818 1819Notes on using *__slots__* 1820"""""""""""""""""""""""""" 1821 1822* When inheriting from a class without *__slots__*, the *__dict__* and 1823 *__weakref__* attribute of the instances will always be accessible. 1824 1825* Without a *__dict__* variable, instances cannot be assigned new variables not 1826 listed in the *__slots__* definition. Attempts to assign to an unlisted 1827 variable name raises :exc:`AttributeError`. If dynamic assignment of new 1828 variables is desired, then add ``'__dict__'`` to the sequence of strings in 1829 the *__slots__* declaration. 1830 1831* Without a *__weakref__* variable for each instance, classes defining 1832 *__slots__* do not support weak references to its instances. If weak reference 1833 support is needed, then add ``'__weakref__'`` to the sequence of strings in the 1834 *__slots__* declaration. 1835 1836* *__slots__* are implemented at the class level by creating descriptors 1837 (:ref:`descriptors`) for each variable name. As a result, class attributes 1838 cannot be used to set default values for instance variables defined by 1839 *__slots__*; otherwise, the class attribute would overwrite the descriptor 1840 assignment. 1841 1842* The action of a *__slots__* declaration is not limited to the class 1843 where it is defined. *__slots__* declared in parents are available in 1844 child classes. However, child subclasses will get a *__dict__* and 1845 *__weakref__* unless they also define *__slots__* (which should only 1846 contain names of any *additional* slots). 1847 1848* If a class defines a slot also defined in a base class, the instance variable 1849 defined by the base class slot is inaccessible (except by retrieving its 1850 descriptor directly from the base class). This renders the meaning of the 1851 program undefined. In the future, a check may be added to prevent this. 1852 1853* Nonempty *__slots__* does not work for classes derived from "variable-length" 1854 built-in types such as :class:`int`, :class:`bytes` and :class:`tuple`. 1855 1856* Any non-string iterable may be assigned to *__slots__*. Mappings may also be 1857 used; however, in the future, special meaning may be assigned to the values 1858 corresponding to each key. 1859 1860* *__class__* assignment works only if both classes have the same *__slots__*. 1861 1862* Multiple inheritance with multiple slotted parent classes can be used, 1863 but only one parent is allowed to have attributes created by slots 1864 (the other bases must have empty slot layouts) - violations raise 1865 :exc:`TypeError`. 1866 1867* If an iterator is used for *__slots__* then a descriptor is created for each 1868 of the iterator's values. However, the *__slots__* attribute will be an empty 1869 iterator. 1870 1871.. _class-customization: 1872 1873Customizing class creation 1874-------------------------- 1875 1876Whenever a class inherits from another class, *__init_subclass__* is 1877called on that class. This way, it is possible to write classes which 1878change the behavior of subclasses. This is closely related to class 1879decorators, but where class decorators only affect the specific class they're 1880applied to, ``__init_subclass__`` solely applies to future subclasses of the 1881class defining the method. 1882 1883.. classmethod:: object.__init_subclass__(cls) 1884 1885 This method is called whenever the containing class is subclassed. 1886 *cls* is then the new subclass. If defined as a normal instance method, 1887 this method is implicitly converted to a class method. 1888 1889 Keyword arguments which are given to a new class are passed to 1890 the parent's class ``__init_subclass__``. For compatibility with 1891 other classes using ``__init_subclass__``, one should take out the 1892 needed keyword arguments and pass the others over to the base 1893 class, as in:: 1894 1895 class Philosopher: 1896 def __init_subclass__(cls, /, default_name, **kwargs): 1897 super().__init_subclass__(**kwargs) 1898 cls.default_name = default_name 1899 1900 class AustralianPhilosopher(Philosopher, default_name="Bruce"): 1901 pass 1902 1903 The default implementation ``object.__init_subclass__`` does 1904 nothing, but raises an error if it is called with any arguments. 1905 1906 .. note:: 1907 1908 The metaclass hint ``metaclass`` is consumed by the rest of the type 1909 machinery, and is never passed to ``__init_subclass__`` implementations. 1910 The actual metaclass (rather than the explicit hint) can be accessed as 1911 ``type(cls)``. 1912 1913 .. versionadded:: 3.6 1914 1915 1916.. _metaclasses: 1917 1918Metaclasses 1919^^^^^^^^^^^ 1920 1921.. index:: 1922 single: metaclass 1923 builtin: type 1924 single: = (equals); class definition 1925 1926By default, classes are constructed using :func:`type`. The class body is 1927executed in a new namespace and the class name is bound locally to the 1928result of ``type(name, bases, namespace)``. 1929 1930The class creation process can be customized by passing the ``metaclass`` 1931keyword argument in the class definition line, or by inheriting from an 1932existing class that included such an argument. In the following example, 1933both ``MyClass`` and ``MySubclass`` are instances of ``Meta``:: 1934 1935 class Meta(type): 1936 pass 1937 1938 class MyClass(metaclass=Meta): 1939 pass 1940 1941 class MySubclass(MyClass): 1942 pass 1943 1944Any other keyword arguments that are specified in the class definition are 1945passed through to all metaclass operations described below. 1946 1947When a class definition is executed, the following steps occur: 1948 1949* MRO entries are resolved; 1950* the appropriate metaclass is determined; 1951* the class namespace is prepared; 1952* the class body is executed; 1953* the class object is created. 1954 1955 1956Resolving MRO entries 1957^^^^^^^^^^^^^^^^^^^^^ 1958 1959If a base that appears in class definition is not an instance of :class:`type`, 1960then an ``__mro_entries__`` method is searched on it. If found, it is called 1961with the original bases tuple. This method must return a tuple of classes that 1962will be used instead of this base. The tuple may be empty, in such case 1963the original base is ignored. 1964 1965.. seealso:: 1966 1967 :pep:`560` - Core support for typing module and generic types 1968 1969 1970Determining the appropriate metaclass 1971^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1972.. index:: 1973 single: metaclass hint 1974 1975The appropriate metaclass for a class definition is determined as follows: 1976 1977* if no bases and no explicit metaclass are given, then :func:`type` is used; 1978* if an explicit metaclass is given and it is *not* an instance of 1979 :func:`type`, then it is used directly as the metaclass; 1980* if an instance of :func:`type` is given as the explicit metaclass, or 1981 bases are defined, then the most derived metaclass is used. 1982 1983The most derived metaclass is selected from the explicitly specified 1984metaclass (if any) and the metaclasses (i.e. ``type(cls)``) of all specified 1985base classes. The most derived metaclass is one which is a subtype of *all* 1986of these candidate metaclasses. If none of the candidate metaclasses meets 1987that criterion, then the class definition will fail with ``TypeError``. 1988 1989 1990.. _prepare: 1991 1992Preparing the class namespace 1993^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1994 1995.. index:: 1996 single: __prepare__ (metaclass method) 1997 1998Once the appropriate metaclass has been identified, then the class namespace 1999is prepared. If the metaclass has a ``__prepare__`` attribute, it is called 2000as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the 2001additional keyword arguments, if any, come from the class definition). The 2002``__prepare__`` method should be implemented as a :func:`classmethod`. The 2003namespace returned by ``__prepare__`` is passed in to ``__new__``, but when 2004the final class object is created the namespace is copied into a new ``dict``. 2005 2006If the metaclass has no ``__prepare__`` attribute, then the class namespace 2007is initialised as an empty ordered mapping. 2008 2009.. seealso:: 2010 2011 :pep:`3115` - Metaclasses in Python 3000 2012 Introduced the ``__prepare__`` namespace hook 2013 2014 2015Executing the class body 2016^^^^^^^^^^^^^^^^^^^^^^^^ 2017 2018.. index:: 2019 single: class; body 2020 2021The class body is executed (approximately) as 2022``exec(body, globals(), namespace)``. The key difference from a normal 2023call to :func:`exec` is that lexical scoping allows the class body (including 2024any methods) to reference names from the current and outer scopes when the 2025class definition occurs inside a function. 2026 2027However, even when the class definition occurs inside the function, methods 2028defined inside the class still cannot see names defined at the class scope. 2029Class variables must be accessed through the first parameter of instance or 2030class methods, or through the implicit lexically scoped ``__class__`` reference 2031described in the next section. 2032 2033.. _class-object-creation: 2034 2035Creating the class object 2036^^^^^^^^^^^^^^^^^^^^^^^^^ 2037 2038.. index:: 2039 single: __class__ (method cell) 2040 single: __classcell__ (class namespace entry) 2041 2042 2043Once the class namespace has been populated by executing the class body, 2044the class object is created by calling 2045``metaclass(name, bases, namespace, **kwds)`` (the additional keywords 2046passed here are the same as those passed to ``__prepare__``). 2047 2048This class object is the one that will be referenced by the zero-argument 2049form of :func:`super`. ``__class__`` is an implicit closure reference 2050created by the compiler if any methods in a class body refer to either 2051``__class__`` or ``super``. This allows the zero argument form of 2052:func:`super` to correctly identify the class being defined based on 2053lexical scoping, while the class or instance that was used to make the 2054current call is identified based on the first argument passed to the method. 2055 2056.. impl-detail:: 2057 2058 In CPython 3.6 and later, the ``__class__`` cell is passed to the metaclass 2059 as a ``__classcell__`` entry in the class namespace. If present, this must 2060 be propagated up to the ``type.__new__`` call in order for the class to be 2061 initialised correctly. 2062 Failing to do so will result in a :exc:`RuntimeError` in Python 3.8. 2063 2064When using the default metaclass :class:`type`, or any metaclass that ultimately 2065calls ``type.__new__``, the following additional customisation steps are 2066invoked after creating the class object: 2067 2068* first, ``type.__new__`` collects all of the descriptors in the class 2069 namespace that define a :meth:`~object.__set_name__` method; 2070* second, all of these ``__set_name__`` methods are called with the class 2071 being defined and the assigned name of that particular descriptor; 2072* finally, the :meth:`~object.__init_subclass__` hook is called on the 2073 immediate parent of the new class in its method resolution order. 2074 2075After the class object is created, it is passed to the class decorators 2076included in the class definition (if any) and the resulting object is bound 2077in the local namespace as the defined class. 2078 2079When a new class is created by ``type.__new__``, the object provided as the 2080namespace parameter is copied to a new ordered mapping and the original 2081object is discarded. The new copy is wrapped in a read-only proxy, which 2082becomes the :attr:`~object.__dict__` attribute of the class object. 2083 2084.. seealso:: 2085 2086 :pep:`3135` - New super 2087 Describes the implicit ``__class__`` closure reference 2088 2089 2090Uses for metaclasses 2091^^^^^^^^^^^^^^^^^^^^ 2092 2093The potential uses for metaclasses are boundless. Some ideas that have been 2094explored include enum, logging, interface checking, automatic delegation, 2095automatic property creation, proxies, frameworks, and automatic resource 2096locking/synchronization. 2097 2098 2099Customizing instance and subclass checks 2100---------------------------------------- 2101 2102The following methods are used to override the default behavior of the 2103:func:`isinstance` and :func:`issubclass` built-in functions. 2104 2105In particular, the metaclass :class:`abc.ABCMeta` implements these methods in 2106order to allow the addition of Abstract Base Classes (ABCs) as "virtual base 2107classes" to any class or type (including built-in types), including other 2108ABCs. 2109 2110.. method:: class.__instancecheck__(self, instance) 2111 2112 Return true if *instance* should be considered a (direct or indirect) 2113 instance of *class*. If defined, called to implement ``isinstance(instance, 2114 class)``. 2115 2116 2117.. method:: class.__subclasscheck__(self, subclass) 2118 2119 Return true if *subclass* should be considered a (direct or indirect) 2120 subclass of *class*. If defined, called to implement ``issubclass(subclass, 2121 class)``. 2122 2123 2124Note that these methods are looked up on the type (metaclass) of a class. They 2125cannot be defined as class methods in the actual class. This is consistent with 2126the lookup of special methods that are called on instances, only in this 2127case the instance is itself a class. 2128 2129.. seealso:: 2130 2131 :pep:`3119` - Introducing Abstract Base Classes 2132 Includes the specification for customizing :func:`isinstance` and 2133 :func:`issubclass` behavior through :meth:`~class.__instancecheck__` and 2134 :meth:`~class.__subclasscheck__`, with motivation for this functionality 2135 in the context of adding Abstract Base Classes (see the :mod:`abc` 2136 module) to the language. 2137 2138 2139Emulating generic types 2140----------------------- 2141 2142One can implement the generic class syntax as specified by :pep:`484` 2143(for example ``List[int]``) by defining a special method: 2144 2145.. classmethod:: object.__class_getitem__(cls, key) 2146 2147 Return an object representing the specialization of a generic class 2148 by type arguments found in *key*. 2149 2150This method is looked up on the class object itself, and when defined in 2151the class body, this method is implicitly a class method. Note, this 2152mechanism is primarily reserved for use with static type hints, other usage 2153is discouraged. 2154 2155.. seealso:: 2156 2157 :pep:`560` - Core support for typing module and generic types 2158 2159 2160.. _callable-types: 2161 2162Emulating callable objects 2163-------------------------- 2164 2165 2166.. method:: object.__call__(self[, args...]) 2167 2168 .. index:: pair: call; instance 2169 2170 Called when the instance is "called" as a function; if this method is defined, 2171 ``x(arg1, arg2, ...)`` roughly translates to ``type(x).__call__(x, arg1, ...)``. 2172 2173 2174.. _sequence-types: 2175 2176Emulating container types 2177------------------------- 2178 2179The following methods can be defined to implement container objects. Containers 2180usually are sequences (such as lists or tuples) or mappings (like dictionaries), 2181but can represent other containers as well. The first set of methods is used 2182either to emulate a sequence or to emulate a mapping; the difference is that for 2183a sequence, the allowable keys should be the integers *k* for which ``0 <= k < 2184N`` where *N* is the length of the sequence, or slice objects, which define a 2185range of items. It is also recommended that mappings provide the methods 2186:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, 2187:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and 2188:meth:`update` behaving similar to those for Python's standard dictionary 2189objects. The :mod:`collections.abc` module provides a 2190:class:`~collections.abc.MutableMapping` 2191abstract base class to help create those methods from a base set of 2192:meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`. 2193Mutable sequences should provide methods :meth:`append`, :meth:`count`, 2194:meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, 2195:meth:`reverse` and :meth:`sort`, like Python standard list objects. Finally, 2196sequence types should implement addition (meaning concatenation) and 2197multiplication (meaning repetition) by defining the methods :meth:`__add__`, 2198:meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and 2199:meth:`__imul__` described below; they should not define other numerical 2200operators. It is recommended that both mappings and sequences implement the 2201:meth:`__contains__` method to allow efficient use of the ``in`` operator; for 2202mappings, ``in`` should search the mapping's keys; for sequences, it should 2203search through the values. It is further recommended that both mappings and 2204sequences implement the :meth:`__iter__` method to allow efficient iteration 2205through the container; for mappings, :meth:`__iter__` should iterate 2206through the object's keys; for sequences, it should iterate through the values. 2207 2208.. method:: object.__len__(self) 2209 2210 .. index:: 2211 builtin: len 2212 single: __bool__() (object method) 2213 2214 Called to implement the built-in function :func:`len`. Should return the length 2215 of the object, an integer ``>=`` 0. Also, an object that doesn't define a 2216 :meth:`__bool__` method and whose :meth:`__len__` method returns zero is 2217 considered to be false in a Boolean context. 2218 2219 .. impl-detail:: 2220 2221 In CPython, the length is required to be at most :attr:`sys.maxsize`. 2222 If the length is larger than :attr:`!sys.maxsize` some features (such as 2223 :func:`len`) may raise :exc:`OverflowError`. To prevent raising 2224 :exc:`!OverflowError` by truth value testing, an object must define a 2225 :meth:`__bool__` method. 2226 2227 2228.. method:: object.__length_hint__(self) 2229 2230 Called to implement :func:`operator.length_hint`. Should return an estimated 2231 length for the object (which may be greater or less than the actual length). 2232 The length must be an integer ``>=`` 0. The return value may also be 2233 :const:`NotImplemented`, which is treated the same as if the 2234 ``__length_hint__`` method didn't exist at all. This method is purely an 2235 optimization and is never required for correctness. 2236 2237 .. versionadded:: 3.4 2238 2239 2240.. index:: object: slice 2241 2242.. note:: 2243 2244 Slicing is done exclusively with the following three methods. A call like :: 2245 2246 a[1:2] = b 2247 2248 is translated to :: 2249 2250 a[slice(1, 2, None)] = b 2251 2252 and so forth. Missing slice items are always filled in with ``None``. 2253 2254 2255.. method:: object.__getitem__(self, key) 2256 2257 Called to implement evaluation of ``self[key]``. For sequence types, the 2258 accepted keys should be integers and slice objects. Note that the special 2259 interpretation of negative indexes (if the class wishes to emulate a sequence 2260 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate 2261 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes 2262 for the sequence (after any special interpretation of negative values), 2263 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not 2264 in the container), :exc:`KeyError` should be raised. 2265 2266 .. note:: 2267 2268 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal 2269 indexes to allow proper detection of the end of the sequence. 2270 2271 2272.. method:: object.__setitem__(self, key, value) 2273 2274 Called to implement assignment to ``self[key]``. Same note as for 2275 :meth:`__getitem__`. This should only be implemented for mappings if the 2276 objects support changes to the values for keys, or if new keys can be added, or 2277 for sequences if elements can be replaced. The same exceptions should be raised 2278 for improper *key* values as for the :meth:`__getitem__` method. 2279 2280 2281.. method:: object.__delitem__(self, key) 2282 2283 Called to implement deletion of ``self[key]``. Same note as for 2284 :meth:`__getitem__`. This should only be implemented for mappings if the 2285 objects support removal of keys, or for sequences if elements can be removed 2286 from the sequence. The same exceptions should be raised for improper *key* 2287 values as for the :meth:`__getitem__` method. 2288 2289 2290.. method:: object.__missing__(self, key) 2291 2292 Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses 2293 when key is not in the dictionary. 2294 2295 2296.. method:: object.__iter__(self) 2297 2298 This method is called when an iterator is required for a container. This method 2299 should return a new iterator object that can iterate over all the objects in the 2300 container. For mappings, it should iterate over the keys of the container. 2301 2302 Iterator objects also need to implement this method; they are required to return 2303 themselves. For more information on iterator objects, see :ref:`typeiter`. 2304 2305 2306.. method:: object.__reversed__(self) 2307 2308 Called (if present) by the :func:`reversed` built-in to implement 2309 reverse iteration. It should return a new iterator object that iterates 2310 over all the objects in the container in reverse order. 2311 2312 If the :meth:`__reversed__` method is not provided, the :func:`reversed` 2313 built-in will fall back to using the sequence protocol (:meth:`__len__` and 2314 :meth:`__getitem__`). Objects that support the sequence protocol should 2315 only provide :meth:`__reversed__` if they can provide an implementation 2316 that is more efficient than the one provided by :func:`reversed`. 2317 2318 2319The membership test operators (:keyword:`in` and :keyword:`not in`) are normally 2320implemented as an iteration through a container. However, container objects can 2321supply the following special method with a more efficient implementation, which 2322also does not require the object be iterable. 2323 2324.. method:: object.__contains__(self, item) 2325 2326 Called to implement membership test operators. Should return true if *item* 2327 is in *self*, false otherwise. For mapping objects, this should consider the 2328 keys of the mapping rather than the values or the key-item pairs. 2329 2330 For objects that don't define :meth:`__contains__`, the membership test first 2331 tries iteration via :meth:`__iter__`, then the old sequence iteration 2332 protocol via :meth:`__getitem__`, see :ref:`this section in the language 2333 reference <membership-test-details>`. 2334 2335 2336.. _numeric-types: 2337 2338Emulating numeric types 2339----------------------- 2340 2341The following methods can be defined to emulate numeric objects. Methods 2342corresponding to operations that are not supported by the particular kind of 2343number implemented (e.g., bitwise operations for non-integral numbers) should be 2344left undefined. 2345 2346 2347.. method:: object.__add__(self, other) 2348 object.__sub__(self, other) 2349 object.__mul__(self, other) 2350 object.__matmul__(self, other) 2351 object.__truediv__(self, other) 2352 object.__floordiv__(self, other) 2353 object.__mod__(self, other) 2354 object.__divmod__(self, other) 2355 object.__pow__(self, other[, modulo]) 2356 object.__lshift__(self, other) 2357 object.__rshift__(self, other) 2358 object.__and__(self, other) 2359 object.__xor__(self, other) 2360 object.__or__(self, other) 2361 2362 .. index:: 2363 builtin: divmod 2364 builtin: pow 2365 builtin: pow 2366 2367 These methods are called to implement the binary arithmetic operations 2368 (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`, 2369 :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``). For instance, to 2370 evaluate the expression ``x + y``, where *x* is an instance of a class that 2371 has an :meth:`__add__` method, ``x.__add__(y)`` is called. The 2372 :meth:`__divmod__` method should be the equivalent to using 2373 :meth:`__floordiv__` and :meth:`__mod__`; it should not be related to 2374 :meth:`__truediv__`. Note that :meth:`__pow__` should be defined to accept 2375 an optional third argument if the ternary version of the built-in :func:`pow` 2376 function is to be supported. 2377 2378 If one of those methods does not support the operation with the supplied 2379 arguments, it should return ``NotImplemented``. 2380 2381 2382.. method:: object.__radd__(self, other) 2383 object.__rsub__(self, other) 2384 object.__rmul__(self, other) 2385 object.__rmatmul__(self, other) 2386 object.__rtruediv__(self, other) 2387 object.__rfloordiv__(self, other) 2388 object.__rmod__(self, other) 2389 object.__rdivmod__(self, other) 2390 object.__rpow__(self, other[, modulo]) 2391 object.__rlshift__(self, other) 2392 object.__rrshift__(self, other) 2393 object.__rand__(self, other) 2394 object.__rxor__(self, other) 2395 object.__ror__(self, other) 2396 2397 .. index:: 2398 builtin: divmod 2399 builtin: pow 2400 2401 These methods are called to implement the binary arithmetic operations 2402 (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`, 2403 :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected 2404 (swapped) operands. These functions are only called if the left operand does 2405 not support the corresponding operation [#]_ and the operands are of different 2406 types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is 2407 an instance of a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)`` 2408 is called if ``x.__sub__(y)`` returns *NotImplemented*. 2409 2410 .. index:: builtin: pow 2411 2412 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the 2413 coercion rules would become too complicated). 2414 2415 .. note:: 2416 2417 If the right operand's type is a subclass of the left operand's type and 2418 that subclass provides a different implementation of the reflected method 2419 for the operation, this method will be called before the left operand's 2420 non-reflected method. This behavior allows subclasses to override their 2421 ancestors' operations. 2422 2423 2424.. method:: object.__iadd__(self, other) 2425 object.__isub__(self, other) 2426 object.__imul__(self, other) 2427 object.__imatmul__(self, other) 2428 object.__itruediv__(self, other) 2429 object.__ifloordiv__(self, other) 2430 object.__imod__(self, other) 2431 object.__ipow__(self, other[, modulo]) 2432 object.__ilshift__(self, other) 2433 object.__irshift__(self, other) 2434 object.__iand__(self, other) 2435 object.__ixor__(self, other) 2436 object.__ior__(self, other) 2437 2438 These methods are called to implement the augmented arithmetic assignments 2439 (``+=``, ``-=``, ``*=``, ``@=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, 2440 ``>>=``, ``&=``, ``^=``, ``|=``). These methods should attempt to do the 2441 operation in-place (modifying *self*) and return the result (which could be, 2442 but does not have to be, *self*). If a specific method is not defined, the 2443 augmented assignment falls back to the normal methods. For instance, if *x* 2444 is an instance of a class with an :meth:`__iadd__` method, ``x += y`` is 2445 equivalent to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and 2446 ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``. In 2447 certain situations, augmented assignment can result in unexpected errors (see 2448 :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in fact 2449 part of the data model. 2450 2451 .. note:: 2452 2453 Due to a bug in the dispatching mechanism for ``**=``, a class that 2454 defines :meth:`__ipow__` but returns ``NotImplemented`` would fail to 2455 fall back to ``x.__pow__(y)`` and ``y.__rpow__(x)``. This bug is fixed 2456 in Python 3.10. 2457 2458 2459.. method:: object.__neg__(self) 2460 object.__pos__(self) 2461 object.__abs__(self) 2462 object.__invert__(self) 2463 2464 .. index:: builtin: abs 2465 2466 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs` 2467 and ``~``). 2468 2469 2470.. method:: object.__complex__(self) 2471 object.__int__(self) 2472 object.__float__(self) 2473 2474 .. index:: 2475 builtin: complex 2476 builtin: int 2477 builtin: float 2478 2479 Called to implement the built-in functions :func:`complex`, 2480 :func:`int` and :func:`float`. Should return a value 2481 of the appropriate type. 2482 2483 2484.. method:: object.__index__(self) 2485 2486 Called to implement :func:`operator.index`, and whenever Python needs to 2487 losslessly convert the numeric object to an integer object (such as in 2488 slicing, or in the built-in :func:`bin`, :func:`hex` and :func:`oct` 2489 functions). Presence of this method indicates that the numeric object is 2490 an integer type. Must return an integer. 2491 2492 If :meth:`__int__`, :meth:`__float__` and :meth:`__complex__` are not 2493 defined then corresponding built-in functions :func:`int`, :func:`float` 2494 and :func:`complex` fall back to :meth:`__index__`. 2495 2496 2497.. method:: object.__round__(self, [,ndigits]) 2498 object.__trunc__(self) 2499 object.__floor__(self) 2500 object.__ceil__(self) 2501 2502 .. index:: builtin: round 2503 2504 Called to implement the built-in function :func:`round` and :mod:`math` 2505 functions :func:`~math.trunc`, :func:`~math.floor` and :func:`~math.ceil`. 2506 Unless *ndigits* is passed to :meth:`!__round__` all these methods should 2507 return the value of the object truncated to an :class:`~numbers.Integral` 2508 (typically an :class:`int`). 2509 2510 If :meth:`__int__` is not defined then the built-in function :func:`int` 2511 falls back to :meth:`__trunc__`. 2512 2513 2514.. _context-managers: 2515 2516With Statement Context Managers 2517------------------------------- 2518 2519A :dfn:`context manager` is an object that defines the runtime context to be 2520established when executing a :keyword:`with` statement. The context manager 2521handles the entry into, and the exit from, the desired runtime context for the 2522execution of the block of code. Context managers are normally invoked using the 2523:keyword:`!with` statement (described in section :ref:`with`), but can also be 2524used by directly invoking their methods. 2525 2526.. index:: 2527 statement: with 2528 single: context manager 2529 2530Typical uses of context managers include saving and restoring various kinds of 2531global state, locking and unlocking resources, closing opened files, etc. 2532 2533For more information on context managers, see :ref:`typecontextmanager`. 2534 2535 2536.. method:: object.__enter__(self) 2537 2538 Enter the runtime context related to this object. The :keyword:`with` statement 2539 will bind this method's return value to the target(s) specified in the 2540 :keyword:`!as` clause of the statement, if any. 2541 2542 2543.. method:: object.__exit__(self, exc_type, exc_value, traceback) 2544 2545 Exit the runtime context related to this object. The parameters describe the 2546 exception that caused the context to be exited. If the context was exited 2547 without an exception, all three arguments will be :const:`None`. 2548 2549 If an exception is supplied, and the method wishes to suppress the exception 2550 (i.e., prevent it from being propagated), it should return a true value. 2551 Otherwise, the exception will be processed normally upon exit from this method. 2552 2553 Note that :meth:`__exit__` methods should not reraise the passed-in exception; 2554 this is the caller's responsibility. 2555 2556 2557.. seealso:: 2558 2559 :pep:`343` - The "with" statement 2560 The specification, background, and examples for the Python :keyword:`with` 2561 statement. 2562 2563 2564.. _special-lookup: 2565 2566Special method lookup 2567--------------------- 2568 2569For custom classes, implicit invocations of special methods are only guaranteed 2570to work correctly if defined on an object's type, not in the object's instance 2571dictionary. That behaviour is the reason why the following code raises an 2572exception:: 2573 2574 >>> class C: 2575 ... pass 2576 ... 2577 >>> c = C() 2578 >>> c.__len__ = lambda: 5 2579 >>> len(c) 2580 Traceback (most recent call last): 2581 File "<stdin>", line 1, in <module> 2582 TypeError: object of type 'C' has no len() 2583 2584The rationale behind this behaviour lies with a number of special methods such 2585as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects, 2586including type objects. If the implicit lookup of these methods used the 2587conventional lookup process, they would fail when invoked on the type object 2588itself:: 2589 2590 >>> 1 .__hash__() == hash(1) 2591 True 2592 >>> int.__hash__() == hash(int) 2593 Traceback (most recent call last): 2594 File "<stdin>", line 1, in <module> 2595 TypeError: descriptor '__hash__' of 'int' object needs an argument 2596 2597Incorrectly attempting to invoke an unbound method of a class in this way is 2598sometimes referred to as 'metaclass confusion', and is avoided by bypassing 2599the instance when looking up special methods:: 2600 2601 >>> type(1).__hash__(1) == hash(1) 2602 True 2603 >>> type(int).__hash__(int) == hash(int) 2604 True 2605 2606In addition to bypassing any instance attributes in the interest of 2607correctness, implicit special method lookup generally also bypasses the 2608:meth:`__getattribute__` method even of the object's metaclass:: 2609 2610 >>> class Meta(type): 2611 ... def __getattribute__(*args): 2612 ... print("Metaclass getattribute invoked") 2613 ... return type.__getattribute__(*args) 2614 ... 2615 >>> class C(object, metaclass=Meta): 2616 ... def __len__(self): 2617 ... return 10 2618 ... def __getattribute__(*args): 2619 ... print("Class getattribute invoked") 2620 ... return object.__getattribute__(*args) 2621 ... 2622 >>> c = C() 2623 >>> c.__len__() # Explicit lookup via instance 2624 Class getattribute invoked 2625 10 2626 >>> type(c).__len__(c) # Explicit lookup via type 2627 Metaclass getattribute invoked 2628 10 2629 >>> len(c) # Implicit lookup 2630 10 2631 2632Bypassing the :meth:`__getattribute__` machinery in this fashion 2633provides significant scope for speed optimisations within the 2634interpreter, at the cost of some flexibility in the handling of 2635special methods (the special method *must* be set on the class 2636object itself in order to be consistently invoked by the interpreter). 2637 2638 2639.. index:: 2640 single: coroutine 2641 2642Coroutines 2643========== 2644 2645 2646Awaitable Objects 2647----------------- 2648 2649An :term:`awaitable` object generally implements an :meth:`__await__` method. 2650:term:`Coroutine objects <coroutine>` returned from :keyword:`async def` functions 2651are awaitable. 2652 2653.. note:: 2654 2655 The :term:`generator iterator` objects returned from generators 2656 decorated with :func:`types.coroutine` or :func:`asyncio.coroutine` 2657 are also awaitable, but they do not implement :meth:`__await__`. 2658 2659.. method:: object.__await__(self) 2660 2661 Must return an :term:`iterator`. Should be used to implement 2662 :term:`awaitable` objects. For instance, :class:`asyncio.Future` implements 2663 this method to be compatible with the :keyword:`await` expression. 2664 2665.. versionadded:: 3.5 2666 2667.. seealso:: :pep:`492` for additional information about awaitable objects. 2668 2669 2670.. _coroutine-objects: 2671 2672Coroutine Objects 2673----------------- 2674 2675:term:`Coroutine objects <coroutine>` are :term:`awaitable` objects. 2676A coroutine's execution can be controlled by calling :meth:`__await__` and 2677iterating over the result. When the coroutine has finished executing and 2678returns, the iterator raises :exc:`StopIteration`, and the exception's 2679:attr:`~StopIteration.value` attribute holds the return value. If the 2680coroutine raises an exception, it is propagated by the iterator. Coroutines 2681should not directly raise unhandled :exc:`StopIteration` exceptions. 2682 2683Coroutines also have the methods listed below, which are analogous to 2684those of generators (see :ref:`generator-methods`). However, unlike 2685generators, coroutines do not directly support iteration. 2686 2687.. versionchanged:: 3.5.2 2688 It is a :exc:`RuntimeError` to await on a coroutine more than once. 2689 2690 2691.. method:: coroutine.send(value) 2692 2693 Starts or resumes execution of the coroutine. If *value* is ``None``, 2694 this is equivalent to advancing the iterator returned by 2695 :meth:`__await__`. If *value* is not ``None``, this method delegates 2696 to the :meth:`~generator.send` method of the iterator that caused 2697 the coroutine to suspend. The result (return value, 2698 :exc:`StopIteration`, or other exception) is the same as when 2699 iterating over the :meth:`__await__` return value, described above. 2700 2701.. method:: coroutine.throw(type[, value[, traceback]]) 2702 2703 Raises the specified exception in the coroutine. This method delegates 2704 to the :meth:`~generator.throw` method of the iterator that caused 2705 the coroutine to suspend, if it has such a method. Otherwise, 2706 the exception is raised at the suspension point. The result 2707 (return value, :exc:`StopIteration`, or other exception) is the same as 2708 when iterating over the :meth:`__await__` return value, described 2709 above. If the exception is not caught in the coroutine, it propagates 2710 back to the caller. 2711 2712.. method:: coroutine.close() 2713 2714 Causes the coroutine to clean itself up and exit. If the coroutine 2715 is suspended, this method first delegates to the :meth:`~generator.close` 2716 method of the iterator that caused the coroutine to suspend, if it 2717 has such a method. Then it raises :exc:`GeneratorExit` at the 2718 suspension point, causing the coroutine to immediately clean itself up. 2719 Finally, the coroutine is marked as having finished executing, even if 2720 it was never started. 2721 2722 Coroutine objects are automatically closed using the above process when 2723 they are about to be destroyed. 2724 2725.. _async-iterators: 2726 2727Asynchronous Iterators 2728---------------------- 2729 2730An *asynchronous iterator* can call asynchronous code in 2731its ``__anext__`` method. 2732 2733Asynchronous iterators can be used in an :keyword:`async for` statement. 2734 2735.. method:: object.__aiter__(self) 2736 2737 Must return an *asynchronous iterator* object. 2738 2739.. method:: object.__anext__(self) 2740 2741 Must return an *awaitable* resulting in a next value of the iterator. Should 2742 raise a :exc:`StopAsyncIteration` error when the iteration is over. 2743 2744An example of an asynchronous iterable object:: 2745 2746 class Reader: 2747 async def readline(self): 2748 ... 2749 2750 def __aiter__(self): 2751 return self 2752 2753 async def __anext__(self): 2754 val = await self.readline() 2755 if val == b'': 2756 raise StopAsyncIteration 2757 return val 2758 2759.. versionadded:: 3.5 2760 2761.. versionchanged:: 3.7 2762 Prior to Python 3.7, ``__aiter__`` could return an *awaitable* 2763 that would resolve to an 2764 :term:`asynchronous iterator <asynchronous iterator>`. 2765 2766 Starting with Python 3.7, ``__aiter__`` must return an 2767 asynchronous iterator object. Returning anything else 2768 will result in a :exc:`TypeError` error. 2769 2770 2771.. _async-context-managers: 2772 2773Asynchronous Context Managers 2774----------------------------- 2775 2776An *asynchronous context manager* is a *context manager* that is able to 2777suspend execution in its ``__aenter__`` and ``__aexit__`` methods. 2778 2779Asynchronous context managers can be used in an :keyword:`async with` statement. 2780 2781.. method:: object.__aenter__(self) 2782 2783 Semantically similar to :meth:`__enter__`, the only 2784 difference being that it must return an *awaitable*. 2785 2786.. method:: object.__aexit__(self, exc_type, exc_value, traceback) 2787 2788 Semantically similar to :meth:`__exit__`, the only 2789 difference being that it must return an *awaitable*. 2790 2791An example of an asynchronous context manager class:: 2792 2793 class AsyncContextManager: 2794 async def __aenter__(self): 2795 await log('entering context') 2796 2797 async def __aexit__(self, exc_type, exc, tb): 2798 await log('exiting context') 2799 2800.. versionadded:: 3.5 2801 2802 2803.. rubric:: Footnotes 2804 2805.. [#] It *is* possible in some cases to change an object's type, under certain 2806 controlled conditions. It generally isn't a good idea though, since it can 2807 lead to some very strange behaviour if it is handled incorrectly. 2808 2809.. [#] The :meth:`__hash__`, :meth:`__iter__`, :meth:`__reversed__`, and 2810 :meth:`__contains__` methods have special handling for this; others 2811 will still raise a :exc:`TypeError`, but may do so by relying on 2812 the behavior that ``None`` is not callable. 2813 2814.. [#] "Does not support" here means that the class has no such method, or 2815 the method returns ``NotImplemented``. Do not set the method to 2816 ``None`` if you want to force fallback to the right operand's reflected 2817 method—that will instead have the opposite effect of explicitly 2818 *blocking* such fallback. 2819 2820.. [#] For operands of the same type, it is assumed that if the non-reflected 2821 method -- such as :meth:`__add__` -- fails then the overall operation is not 2822 supported, which is why the reflected method is not called. 2823