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