Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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. (In a sense, and in |
| 20 | conformance to Von Neumann's model of a "stored program computer," code is also |
| 21 | represented by objects.) |
| 22 | |
| 23 | .. index:: |
| 24 | builtin: id |
| 25 | builtin: type |
| 26 | single: identity of an object |
| 27 | single: value of an object |
| 28 | single: type of an object |
| 29 | single: mutable object |
| 30 | single: immutable object |
| 31 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 32 | .. XXX it *is* now possible in some cases to change an object's |
| 33 | type, under certain controlled conditions |
| 34 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | Every object has an identity, a type and a value. An object's *identity* never |
| 36 | changes once it has been created; you may think of it as the object's address in |
| 37 | memory. The ':keyword:`is`' operator compares the identity of two objects; the |
| 38 | :func:`id` function returns an integer representing its identity (currently |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 39 | implemented as its address). An object's :dfn:`type` is also unchangeable. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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). The *value* of some objects can change. Objects whose value can |
| 44 | change are said to be *mutable*; objects whose value is unchangeable once they |
| 45 | are created are called *immutable*. (The value of an immutable container object |
| 46 | that contains a reference to a mutable object can change when the latter's value |
| 47 | is changed; however the container is still considered immutable, because the |
| 48 | collection of objects it contains cannot be changed. So, immutability is not |
| 49 | strictly the same as having an unchangeable value, it is more subtle.) An |
| 50 | object's mutability is determined by its type; for instance, numbers, strings |
| 51 | and tuples are immutable, while dictionaries and lists are mutable. |
| 52 | |
| 53 | .. index:: |
| 54 | single: garbage collection |
| 55 | single: reference counting |
| 56 | single: unreachable object |
| 57 | |
| 58 | Objects are never explicitly destroyed; however, when they become unreachable |
| 59 | they may be garbage-collected. An implementation is allowed to postpone garbage |
| 60 | collection or omit it altogether --- it is a matter of implementation quality |
| 61 | how garbage collection is implemented, as long as no objects are collected that |
| 62 | are still reachable. (Implementation note: the current implementation uses a |
| 63 | reference-counting scheme with (optional) delayed detection of cyclically linked |
| 64 | garbage, which collects most objects as soon as they become unreachable, but is |
| 65 | not guaranteed to collect garbage containing circular references. See the |
| 66 | documentation of the :mod:`gc` module for information on controlling the |
| 67 | collection of cyclic garbage.) |
| 68 | |
| 69 | Note that the use of the implementation's tracing or debugging facilities may |
| 70 | keep objects alive that would normally be collectable. Also note that catching |
| 71 | an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep |
| 72 | objects alive. |
| 73 | |
| 74 | Some objects contain references to "external" resources such as open files or |
| 75 | windows. It is understood that these resources are freed when the object is |
| 76 | garbage-collected, but since garbage collection is not guaranteed to happen, |
| 77 | such objects also provide an explicit way to release the external resource, |
| 78 | usually a :meth:`close` method. Programs are strongly recommended to explicitly |
| 79 | close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement |
| 80 | provides a convenient way to do this. |
| 81 | |
| 82 | .. index:: single: container |
| 83 | |
| 84 | Some objects contain references to other objects; these are called *containers*. |
| 85 | Examples of containers are tuples, lists and dictionaries. The references are |
| 86 | part of a container's value. In most cases, when we talk about the value of a |
| 87 | container, we imply the values, not the identities of the contained objects; |
| 88 | however, when we talk about the mutability of a container, only the identities |
| 89 | of the immediately contained objects are implied. So, if an immutable container |
| 90 | (like a tuple) contains a reference to a mutable object, its value changes if |
| 91 | that mutable object is changed. |
| 92 | |
| 93 | Types affect almost all aspects of object behavior. Even the importance of |
| 94 | object identity is affected in some sense: for immutable types, operations that |
| 95 | compute new values may actually return a reference to any existing object with |
| 96 | the same type and value, while for mutable objects this is not allowed. E.g., |
| 97 | after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object |
| 98 | with the value one, depending on the implementation, but after ``c = []; d = |
| 99 | []``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly |
| 100 | created empty lists. (Note that ``c = d = []`` assigns the same object to both |
| 101 | ``c`` and ``d``.) |
| 102 | |
| 103 | |
| 104 | .. _types: |
| 105 | |
| 106 | The standard type hierarchy |
| 107 | =========================== |
| 108 | |
| 109 | .. index:: |
| 110 | single: type |
| 111 | pair: data; type |
| 112 | pair: type; hierarchy |
| 113 | pair: extension; module |
| 114 | pair: C; language |
| 115 | |
| 116 | Below is a list of the types that are built into Python. Extension modules |
| 117 | (written in C, Java, or other languages, depending on the implementation) can |
| 118 | define additional types. Future versions of Python may add types to the type |
| 119 | hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.). |
| 120 | |
| 121 | .. index:: |
| 122 | single: attribute |
| 123 | pair: special; attribute |
| 124 | triple: generic; special; attribute |
| 125 | |
| 126 | Some of the type descriptions below contain a paragraph listing 'special |
| 127 | attributes.' These are attributes that provide access to the implementation and |
| 128 | are not intended for general use. Their definition may change in the future. |
| 129 | |
| 130 | None |
| 131 | .. index:: object: None |
| 132 | |
| 133 | This type has a single value. There is a single object with this value. This |
| 134 | object is accessed through the built-in name ``None``. It is used to signify the |
| 135 | absence of a value in many situations, e.g., it is returned from functions that |
| 136 | don't explicitly return anything. Its truth value is false. |
| 137 | |
| 138 | NotImplemented |
| 139 | .. index:: object: NotImplemented |
| 140 | |
| 141 | This type has a single value. There is a single object with this value. This |
| 142 | object is accessed through the built-in name ``NotImplemented``. Numeric methods |
| 143 | and rich comparison methods may return this value if they do not implement the |
| 144 | operation for the operands provided. (The interpreter will then try the |
| 145 | reflected operation, or some other fallback, depending on the operator.) Its |
| 146 | truth value is true. |
| 147 | |
| 148 | Ellipsis |
| 149 | .. index:: object: Ellipsis |
| 150 | |
| 151 | This type has a single value. There is a single object with this value. This |
| 152 | object is accessed through the literal ``...`` or the built-in name |
| 153 | ``Ellipsis``. Its truth value is true. |
| 154 | |
| 155 | Numbers |
| 156 | .. index:: object: numeric |
| 157 | |
| 158 | These are created by numeric literals and returned as results by arithmetic |
| 159 | operators and arithmetic built-in functions. Numeric objects are immutable; |
| 160 | once created their value never changes. Python numbers are of course strongly |
| 161 | related to mathematical numbers, but subject to the limitations of numerical |
| 162 | representation in computers. |
| 163 | |
| 164 | Python distinguishes between integers, floating point numbers, and complex |
| 165 | numbers: |
| 166 | |
| 167 | Integers |
| 168 | .. index:: object: integer |
| 169 | |
| 170 | These represent elements from the mathematical set of integers (positive and |
| 171 | negative). |
| 172 | |
| 173 | There are three types of integers: |
| 174 | |
| 175 | Plain integers |
| 176 | .. index:: |
| 177 | object: plain integer |
| 178 | single: OverflowError (built-in exception) |
| 179 | |
| 180 | These represent numbers in the range -2147483648 through 2147483647. (The range |
| 181 | may be larger on machines with a larger natural word size, but not smaller.) |
| 182 | When the result of an operation would fall outside this range, the result is |
| 183 | normally returned as a long integer (in some cases, the exception |
| 184 | :exc:`OverflowError` is raised instead). For the purpose of shift and mask |
| 185 | operations, integers are assumed to have a binary, 2's complement notation using |
| 186 | 32 or more bits, and hiding no bits from the user (i.e., all 4294967296 |
| 187 | different bit patterns correspond to different values). |
| 188 | |
| 189 | Long integers |
| 190 | .. index:: object: long integer |
| 191 | |
| 192 | These represent numbers in an unlimited range, subject to available (virtual) |
| 193 | memory only. For the purpose of shift and mask operations, a binary |
| 194 | representation is assumed, and negative numbers are represented in a variant of |
| 195 | 2's complement which gives the illusion of an infinite string of sign bits |
| 196 | extending to the left. |
| 197 | |
| 198 | Booleans |
| 199 | .. index:: |
| 200 | object: Boolean |
| 201 | single: False |
| 202 | single: True |
| 203 | |
| 204 | These represent the truth values False and True. The two objects representing |
| 205 | the values False and True are the only Boolean objects. The Boolean type is a |
| 206 | subtype of plain integers, and Boolean values behave like the values 0 and 1, |
| 207 | respectively, in almost all contexts, the exception being that when converted to |
| 208 | a string, the strings ``"False"`` or ``"True"`` are returned, respectively. |
| 209 | |
| 210 | .. index:: pair: integer; representation |
| 211 | |
| 212 | The rules for integer representation are intended to give the most meaningful |
| 213 | interpretation of shift and mask operations involving negative integers and the |
| 214 | least surprises when switching between the plain and long integer domains. Any |
| 215 | operation except left shift, if it yields a result in the plain integer domain |
| 216 | without causing overflow, will yield the same result in the long integer domain |
| 217 | or when using mixed operands. |
| 218 | |
| 219 | .. % Integers |
| 220 | |
| 221 | Floating point numbers |
| 222 | .. index:: |
| 223 | object: floating point |
| 224 | pair: floating point; number |
| 225 | pair: C; language |
| 226 | pair: Java; language |
| 227 | |
| 228 | These represent machine-level double precision floating point numbers. You are |
| 229 | at the mercy of the underlying machine architecture (and C or Java |
| 230 | implementation) for the accepted range and handling of overflow. Python does not |
| 231 | support single-precision floating point numbers; the savings in processor and |
| 232 | memory usage that are usually the reason for using these is dwarfed by the |
| 233 | overhead of using objects in Python, so there is no reason to complicate the |
| 234 | language with two kinds of floating point numbers. |
| 235 | |
| 236 | Complex numbers |
| 237 | .. index:: |
| 238 | object: complex |
| 239 | pair: complex; number |
| 240 | |
| 241 | These represent complex numbers as a pair of machine-level double precision |
| 242 | floating point numbers. The same caveats apply as for floating point numbers. |
| 243 | The real and imaginary parts of a complex number ``z`` can be retrieved through |
| 244 | the read-only attributes ``z.real`` and ``z.imag``. |
| 245 | |
| 246 | .. % Numbers |
| 247 | |
| 248 | Sequences |
| 249 | .. index:: |
| 250 | builtin: len |
| 251 | object: sequence |
| 252 | single: index operation |
| 253 | single: item selection |
| 254 | single: subscription |
| 255 | |
| 256 | These represent finite ordered sets indexed by non-negative numbers. The |
| 257 | built-in function :func:`len` returns the number of items of a sequence. When |
| 258 | the length of a sequence is *n*, the index set contains the numbers 0, 1, |
| 259 | ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. |
| 260 | |
| 261 | .. index:: single: slicing |
| 262 | |
| 263 | Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such |
| 264 | that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a |
| 265 | sequence of the same type. This implies that the index set is renumbered so |
| 266 | that it starts at 0. |
| 267 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 268 | Some sequences also support "extended slicing" with a third "step" parameter: |
| 269 | ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n* |
| 270 | ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*. |
| 271 | |
| 272 | Sequences are distinguished according to their mutability: |
| 273 | |
| 274 | Immutable sequences |
| 275 | .. index:: |
| 276 | object: immutable sequence |
| 277 | object: immutable |
| 278 | |
| 279 | An object of an immutable sequence type cannot change once it is created. (If |
| 280 | the object contains references to other objects, these other objects may be |
| 281 | mutable and may be changed; however, the collection of objects directly |
| 282 | referenced by an immutable object cannot change.) |
| 283 | |
| 284 | The following types are immutable sequences: |
| 285 | |
| 286 | Strings |
| 287 | .. index:: |
| 288 | builtin: chr |
| 289 | builtin: ord |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 290 | builtin: str |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 291 | single: character |
| 292 | single: integer |
| 293 | single: Unicode |
| 294 | |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 295 | The items of a string object are Unicode code units. A Unicode code |
| 296 | unit is represented by a string object of one item and can hold either |
| 297 | a 16-bit or 32-bit value representing a Unicode ordinal (the maximum |
| 298 | value for the ordinal is given in ``sys.maxunicode``, and depends on |
| 299 | how Python is configured at compile time). Surrogate pairs may be |
| 300 | present in the Unicode object, and will be reported as two separate |
| 301 | items. The built-in functions :func:`chr` and :func:`ord` convert |
| 302 | between code units and nonnegative integers representing the Unicode |
| 303 | ordinals as defined in the Unicode Standard 3.0. Conversion from and to |
| 304 | other encodings are possible through the string method :meth:`encode`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 305 | |
| 306 | Tuples |
| 307 | .. index:: |
| 308 | object: tuple |
| 309 | pair: singleton; tuple |
| 310 | pair: empty; tuple |
| 311 | |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 312 | The items of a tuple are arbitrary Python objects. Tuples of two or |
| 313 | more items are formed by comma-separated lists of expressions. A tuple |
| 314 | of one item (a 'singleton') can be formed by affixing a comma to an |
| 315 | expression (an expression by itself does not create a tuple, since |
| 316 | parentheses must be usable for grouping of expressions). An empty |
| 317 | tuple can be formed by an empty pair of parentheses. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 318 | |
| 319 | .. % Immutable sequences |
| 320 | |
| 321 | Mutable sequences |
| 322 | .. index:: |
| 323 | object: mutable sequence |
| 324 | object: mutable |
| 325 | pair: assignment; statement |
| 326 | single: delete |
| 327 | statement: del |
| 328 | single: subscription |
| 329 | single: slicing |
| 330 | |
| 331 | Mutable sequences can be changed after they are created. The subscription and |
| 332 | slicing notations can be used as the target of assignment and :keyword:`del` |
| 333 | (delete) statements. |
| 334 | |
| 335 | There is currently a single intrinsic mutable sequence type: |
| 336 | |
| 337 | Lists |
| 338 | .. index:: object: list |
| 339 | |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 340 | The items of a list are arbitrary Python objects. Lists are formed by |
| 341 | placing a comma-separated list of expressions in square brackets. (Note |
| 342 | that there are no special cases needed to form lists of length 0 or 1.) |
| 343 | |
| 344 | Bytes |
| 345 | .. index:: bytes, byte |
| 346 | |
| 347 | A bytes object is a mutable array. The items are 8-bit bytes, |
| 348 | represented by integers in the range 0 <= x < 256. Bytes literals |
| 349 | (like ``b'abc'`` and the built-in function :func:`bytes` can be used to |
| 350 | construct bytes objects. Also, bytes objects can be decoded to strings |
| 351 | via the :meth:`decode` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | |
| 353 | .. index:: module: array |
| 354 | |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 355 | The extension module :mod:`array` provides an additional example of a |
| 356 | mutable sequence type. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 357 | |
| 358 | .. % Mutable sequences |
| 359 | |
| 360 | .. % Sequences |
| 361 | |
| 362 | Set types |
| 363 | .. index:: |
| 364 | builtin: len |
| 365 | object: set type |
| 366 | |
| 367 | These represent unordered, finite sets of unique, immutable objects. As such, |
| 368 | they cannot be indexed by any subscript. However, they can be iterated over, and |
| 369 | the built-in function :func:`len` returns the number of items in a set. Common |
| 370 | uses for sets are fast membership testing, removing duplicates from a sequence, |
| 371 | and computing mathematical operations such as intersection, union, difference, |
| 372 | and symmetric difference. |
| 373 | |
| 374 | For set elements, the same immutability rules apply as for dictionary keys. Note |
| 375 | that numeric types obey the normal rules for numeric comparison: if two numbers |
| 376 | compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a |
| 377 | set. |
| 378 | |
| 379 | There are currently two intrinsic set types: |
| 380 | |
| 381 | Sets |
| 382 | .. index:: object: set |
| 383 | |
| 384 | These represent a mutable set. They are created by the built-in :func:`set` |
| 385 | constructor and can be modified afterwards by several methods, such as |
| 386 | :meth:`add`. |
| 387 | |
| 388 | Frozen sets |
| 389 | .. index:: object: frozenset |
| 390 | |
| 391 | These represent an immutable set. They are created by the built-in |
| 392 | :func:`frozenset` constructor. As a frozenset is immutable and hashable, it can |
| 393 | be used again as an element of another set, or as a dictionary key. |
| 394 | |
| 395 | .. % Set types |
| 396 | |
| 397 | Mappings |
| 398 | .. index:: |
| 399 | builtin: len |
| 400 | single: subscription |
| 401 | object: mapping |
| 402 | |
| 403 | These represent finite sets of objects indexed by arbitrary index sets. The |
| 404 | subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping |
| 405 | ``a``; this can be used in expressions and as the target of assignments or |
| 406 | :keyword:`del` statements. The built-in function :func:`len` returns the number |
| 407 | of items in a mapping. |
| 408 | |
| 409 | There is currently a single intrinsic mapping type: |
| 410 | |
| 411 | Dictionaries |
| 412 | .. index:: object: dictionary |
| 413 | |
| 414 | These represent finite sets of objects indexed by nearly arbitrary values. The |
| 415 | only types of values not acceptable as keys are values containing lists or |
| 416 | dictionaries or other mutable types that are compared by value rather than by |
| 417 | object identity, the reason being that the efficient implementation of |
| 418 | dictionaries requires a key's hash value to remain constant. Numeric types used |
| 419 | for keys obey the normal rules for numeric comparison: if two numbers compare |
| 420 | equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index |
| 421 | the same dictionary entry. |
| 422 | |
| 423 | Dictionaries are mutable; they can be created by the ``{...}`` notation (see |
| 424 | section :ref:`dict`). |
| 425 | |
| 426 | .. index:: |
| 427 | module: dbm |
| 428 | module: gdbm |
| 429 | module: bsddb |
| 430 | |
| 431 | The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide |
| 432 | additional examples of mapping types. |
| 433 | |
| 434 | .. % Mapping types |
| 435 | |
| 436 | Callable types |
| 437 | .. index:: |
| 438 | object: callable |
| 439 | pair: function; call |
| 440 | single: invocation |
| 441 | pair: function; argument |
| 442 | |
| 443 | These are the types to which the function call operation (see section |
| 444 | :ref:`calls`) can be applied: |
| 445 | |
| 446 | User-defined functions |
| 447 | .. index:: |
| 448 | pair: user-defined; function |
| 449 | object: function |
| 450 | object: user-defined function |
| 451 | |
| 452 | A user-defined function object is created by a function definition (see |
| 453 | section :ref:`function`). It should be called with an argument list |
| 454 | containing the same number of items as the function's formal parameter |
| 455 | list. |
| 456 | |
| 457 | Special attributes: |
| 458 | |
| 459 | +-------------------------+-------------------------------+-----------+ |
| 460 | | Attribute | Meaning | | |
| 461 | +=========================+===============================+===========+ |
| 462 | | :attr:`__doc__` | The function's documentation | Writable | |
| 463 | | | string, or ``None`` if | | |
| 464 | | | unavailable | | |
| 465 | +-------------------------+-------------------------------+-----------+ |
| 466 | | :attr:`__name__` | The function's name | Writable | |
| 467 | +-------------------------+-------------------------------+-----------+ |
| 468 | | :attr:`__module__` | The name of the module the | Writable | |
| 469 | | | function was defined in, or | | |
| 470 | | | ``None`` if unavailable. | | |
| 471 | +-------------------------+-------------------------------+-----------+ |
| 472 | | :attr:`__defaults__` | A tuple containing default | Writable | |
| 473 | | | argument values for those | | |
| 474 | | | arguments that have defaults, | | |
| 475 | | | or ``None`` if no arguments | | |
| 476 | | | have a default value | | |
| 477 | +-------------------------+-------------------------------+-----------+ |
| 478 | | :attr:`__code__` | The code object representing | Writable | |
| 479 | | | the compiled function body. | | |
| 480 | +-------------------------+-------------------------------+-----------+ |
| 481 | | :attr:`__globals__` | A reference to the dictionary | Read-only | |
| 482 | | | that holds the function's | | |
| 483 | | | global variables --- the | | |
| 484 | | | global namespace of the | | |
| 485 | | | module in which the function | | |
| 486 | | | was defined. | | |
| 487 | +-------------------------+-------------------------------+-----------+ |
| 488 | | :attr:`__dict__` | The namespace supporting | Writable | |
| 489 | | | arbitrary function | | |
| 490 | | | attributes. | | |
| 491 | +-------------------------+-------------------------------+-----------+ |
| 492 | | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only | |
| 493 | | | that contain bindings for the | | |
| 494 | | | function's free variables. | | |
| 495 | +-------------------------+-------------------------------+-----------+ |
| 496 | | :attr:`__annotations__` | A dict containing annotations | Writable | |
| 497 | | | of parameters. The keys of | | |
| 498 | | | the dict are the parameter | | |
| 499 | | | names, or ``'return'`` for | | |
| 500 | | | the return annotation, if | | |
| 501 | | | provided. | | |
| 502 | +-------------------------+-------------------------------+-----------+ |
| 503 | | :attr:`__kwdefaults__` | A dict containing defaults | Writable | |
| 504 | | | for keyword-only parameters. | | |
| 505 | +-------------------------+-------------------------------+-----------+ |
| 506 | |
| 507 | Most of the attributes labelled "Writable" check the type of the assigned value. |
| 508 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 509 | Function objects also support getting and setting arbitrary attributes, which |
| 510 | can be used, for example, to attach metadata to functions. Regular attribute |
| 511 | dot-notation is used to get and set such attributes. *Note that the current |
| 512 | implementation only supports function attributes on user-defined functions. |
| 513 | Function attributes on built-in functions may be supported in the future.* |
| 514 | |
| 515 | Additional information about a function's definition can be retrieved from its |
| 516 | code object; see the description of internal types below. |
| 517 | |
| 518 | .. index:: |
| 519 | single: __doc__ (function attribute) |
| 520 | single: __name__ (function attribute) |
| 521 | single: __module__ (function attribute) |
| 522 | single: __dict__ (function attribute) |
| 523 | single: __defaults__ (function attribute) |
| 524 | single: __closure__ (function attribute) |
| 525 | single: __code__ (function attribute) |
| 526 | single: __globals__ (function attribute) |
| 527 | single: __annotations__ (function attribute) |
| 528 | single: __kwdefaults__ (function attribute) |
| 529 | pair: global; namespace |
| 530 | |
| 531 | User-defined methods |
| 532 | .. index:: |
| 533 | object: method |
| 534 | object: user-defined method |
| 535 | pair: user-defined; method |
| 536 | |
| 537 | A user-defined method object combines a class, a class instance (or ``None``) |
| 538 | and any callable object (normally a user-defined function). |
| 539 | |
| 540 | Special read-only attributes: :attr:`im_self` is the class instance object, |
| 541 | :attr:`im_func` is the function object; :attr:`im_class` is the class of |
| 542 | :attr:`im_self` for bound methods or the class that asked for the method for |
| 543 | unbound methods; :attr:`__doc__` is the method's documentation (same as |
| 544 | ``im_func.__doc__``); :attr:`__name__` is the method name (same as |
| 545 | ``im_func.__name__``); :attr:`__module__` is the name of the module the method |
| 546 | was defined in, or ``None`` if unavailable. |
| 547 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 548 | .. index:: |
| 549 | single: __doc__ (method attribute) |
| 550 | single: __name__ (method attribute) |
| 551 | single: __module__ (method attribute) |
| 552 | single: im_func (method attribute) |
| 553 | single: im_self (method attribute) |
| 554 | |
| 555 | Methods also support accessing (but not setting) the arbitrary function |
| 556 | attributes on the underlying function object. |
| 557 | |
| 558 | User-defined method objects may be created when getting an attribute of a class |
| 559 | (perhaps via an instance of that class), if that attribute is a user-defined |
| 560 | function object, an unbound user-defined method object, or a class method |
| 561 | object. When the attribute is a user-defined method object, a new method object |
| 562 | is only created if the class from which it is being retrieved is the same as, or |
| 563 | a derived class of, the class stored in the original method object; otherwise, |
| 564 | the original method object is used as it is. |
| 565 | |
| 566 | .. index:: |
| 567 | single: im_class (method attribute) |
| 568 | single: im_func (method attribute) |
| 569 | single: im_self (method attribute) |
| 570 | |
| 571 | When a user-defined method object is created by retrieving a user-defined |
| 572 | function object from a class, its :attr:`im_self` attribute is ``None`` |
| 573 | and the method object is said to be unbound. When one is created by |
| 574 | retrieving a user-defined function object from a class via one of its |
| 575 | instances, its :attr:`im_self` attribute is the instance, and the method |
| 576 | object is said to be bound. In either case, the new method's |
| 577 | :attr:`im_class` attribute is the class from which the retrieval takes |
| 578 | place, and its :attr:`im_func` attribute is the original function object. |
| 579 | |
| 580 | .. index:: single: im_func (method attribute) |
| 581 | |
| 582 | When a user-defined method object is created by retrieving another method object |
| 583 | from a class or instance, the behaviour is the same as for a function object, |
| 584 | except that the :attr:`im_func` attribute of the new instance is not the |
| 585 | original method object but its :attr:`im_func` attribute. |
| 586 | |
| 587 | .. index:: |
| 588 | single: im_class (method attribute) |
| 589 | single: im_func (method attribute) |
| 590 | single: im_self (method attribute) |
| 591 | |
| 592 | When a user-defined method object is created by retrieving a class method object |
| 593 | from a class or instance, its :attr:`im_self` attribute is the class itself (the |
| 594 | same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is |
| 595 | the function object underlying the class method. |
| 596 | |
| 597 | When an unbound user-defined method object is called, the underlying function |
| 598 | (:attr:`im_func`) is called, with the restriction that the first argument must |
| 599 | be an instance of the proper class (:attr:`im_class`) or of a derived class |
| 600 | thereof. |
| 601 | |
| 602 | When a bound user-defined method object is called, the underlying function |
| 603 | (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in |
| 604 | front of the argument list. For instance, when :class:`C` is a class which |
| 605 | contains a definition for a function :meth:`f`, and ``x`` is an instance of |
| 606 | :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``. |
| 607 | |
| 608 | When a user-defined method object is derived from a class method object, the |
| 609 | "class instance" stored in :attr:`im_self` will actually be the class itself, so |
| 610 | that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)`` |
| 611 | where ``f`` is the underlying function. |
| 612 | |
| 613 | Note that the transformation from function object to (unbound or bound) method |
| 614 | object happens each time the attribute is retrieved from the class or instance. |
| 615 | In some cases, a fruitful optimization is to assign the attribute to a local |
| 616 | variable and call that local variable. Also notice that this transformation only |
| 617 | happens for user-defined functions; other callable objects (and all non-callable |
| 618 | objects) are retrieved without transformation. It is also important to note |
| 619 | that user-defined functions which are attributes of a class instance are not |
| 620 | converted to bound methods; this *only* happens when the function is an |
| 621 | attribute of the class. |
| 622 | |
| 623 | Generator functions |
| 624 | .. index:: |
| 625 | single: generator; function |
| 626 | single: generator; iterator |
| 627 | |
| 628 | A function or method which uses the :keyword:`yield` statement (see section |
| 629 | :ref:`yield`) is called a :dfn:`generator |
| 630 | function`. Such a function, when called, always returns an iterator object |
| 631 | which can be used to execute the body of the function: calling the iterator's |
| 632 | :meth:`__next__` method will cause the function to execute until it provides a |
| 633 | value using the :keyword:`yield` statement. When the function executes a |
| 634 | :keyword:`return` statement or falls off the end, a :exc:`StopIteration` |
| 635 | exception is raised and the iterator will have reached the end of the set of |
| 636 | values to be returned. |
| 637 | |
| 638 | Built-in functions |
| 639 | .. index:: |
| 640 | object: built-in function |
| 641 | object: function |
| 642 | pair: C; language |
| 643 | |
| 644 | A built-in function object is a wrapper around a C function. Examples of |
| 645 | built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a |
| 646 | standard built-in module). The number and type of the arguments are |
| 647 | determined by the C function. Special read-only attributes: |
| 648 | :attr:`__doc__` is the function's documentation string, or ``None`` if |
| 649 | unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is |
| 650 | set to ``None`` (but see the next item); :attr:`__module__` is the name of |
| 651 | the module the function was defined in or ``None`` if unavailable. |
| 652 | |
| 653 | Built-in methods |
| 654 | .. index:: |
| 655 | object: built-in method |
| 656 | object: method |
| 657 | pair: built-in; method |
| 658 | |
| 659 | This is really a different disguise of a built-in function, this time containing |
| 660 | an object passed to the C function as an implicit extra argument. An example of |
| 661 | a built-in method is ``alist.append()``, assuming *alist* is a list object. In |
| 662 | this case, the special read-only attribute :attr:`__self__` is set to the object |
| 663 | denoted by *list*. |
| 664 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 665 | Classes |
| 666 | Classes are callable. These objects normally act as factories for new |
| 667 | instances of themselves, but variations are possible for class types that |
| 668 | override :meth:`__new__`. The arguments of the call are passed to |
| 669 | :meth:`__new__` and, in the typical case, to :meth:`__init__` to |
| 670 | initialize the new instance. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 671 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 672 | Class Instances |
| 673 | Instances of arbitrary classes can be made callable by defining a |
| 674 | :meth:`__call__` method in their class. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 675 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 676 | |
| 677 | Modules |
| 678 | .. index:: |
| 679 | statement: import |
| 680 | object: module |
| 681 | |
| 682 | Modules are imported by the :keyword:`import` statement (see section |
| 683 | :ref:`import`). A module object has a |
| 684 | namespace implemented by a dictionary object (this is the dictionary referenced |
| 685 | by the __globals__ attribute of functions defined in the module). Attribute |
| 686 | references are translated to lookups in this dictionary, e.g., ``m.x`` is |
| 687 | equivalent to ``m.__dict__["x"]``. A module object does not contain the code |
| 688 | object used to initialize the module (since it isn't needed once the |
| 689 | initialization is done). |
| 690 | |
| 691 | .. % |
| 692 | |
| 693 | Attribute assignment updates the module's namespace dictionary, e.g., ``m.x = |
| 694 | 1`` is equivalent to ``m.__dict__["x"] = 1``. |
| 695 | |
| 696 | .. index:: single: __dict__ (module attribute) |
| 697 | |
| 698 | Special read-only attribute: :attr:`__dict__` is the module's namespace as a |
| 699 | dictionary object. |
| 700 | |
| 701 | .. index:: |
| 702 | single: __name__ (module attribute) |
| 703 | single: __doc__ (module attribute) |
| 704 | single: __file__ (module attribute) |
| 705 | pair: module; namespace |
| 706 | |
| 707 | Predefined (writable) attributes: :attr:`__name__` is the module's name; |
| 708 | :attr:`__doc__` is the module's documentation string, or ``None`` if |
| 709 | unavailable; :attr:`__file__` is the pathname of the file from which the module |
| 710 | was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not |
| 711 | present for C modules that are statically linked into the interpreter; for |
| 712 | extension modules loaded dynamically from a shared library, it is the pathname |
| 713 | of the shared library file. |
| 714 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 715 | .. XXX "Classes" and "Instances" is outdated! |
| 716 | see http://www.python.org/doc/newstyle.html for newstyle information |
| 717 | |
| 718 | Custom classes |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 719 | Class objects are created by class definitions (see section :ref:`class`). A |
| 720 | class has a namespace implemented by a dictionary object. Class attribute |
| 721 | references are translated to lookups in this dictionary, e.g., ``C.x`` is |
| 722 | translated to ``C.__dict__["x"]``. When the attribute name is not found |
| 723 | there, the attribute search continues in the base classes. The search is |
| 724 | depth-first, left-to-right in the order of occurrence in the base class list. |
| 725 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 726 | .. XXX document descriptors and new MRO |
| 727 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 728 | .. index:: |
| 729 | object: class |
| 730 | object: class instance |
| 731 | object: instance |
| 732 | pair: class object; call |
| 733 | single: container |
| 734 | object: dictionary |
| 735 | pair: class; attribute |
| 736 | |
| 737 | When a class attribute reference (for class :class:`C`, say) would yield a |
| 738 | user-defined function object or an unbound user-defined method object whose |
| 739 | associated class is either :class:`C` or one of its base classes, it is |
| 740 | transformed into an unbound user-defined method object whose :attr:`im_class` |
| 741 | attribute is :class:`C`. When it would yield a class method object, it is |
| 742 | transformed into a bound user-defined method object whose :attr:`im_class` |
| 743 | and :attr:`im_self` attributes are both :class:`C`. When it would yield a |
| 744 | static method object, it is transformed into the object wrapped by the static |
| 745 | method object. See section :ref:`descriptors` for another way in which |
| 746 | attributes retrieved from a class may differ from those actually contained in |
| 747 | its :attr:`__dict__`. |
| 748 | |
| 749 | .. index:: triple: class; attribute; assignment |
| 750 | |
| 751 | Class attribute assignments update the class's dictionary, never the dictionary |
| 752 | of a base class. |
| 753 | |
| 754 | .. index:: pair: class object; call |
| 755 | |
| 756 | A class object can be called (see above) to yield a class instance (see below). |
| 757 | |
| 758 | .. index:: |
| 759 | single: __name__ (class attribute) |
| 760 | single: __module__ (class attribute) |
| 761 | single: __dict__ (class attribute) |
| 762 | single: __bases__ (class attribute) |
| 763 | single: __doc__ (class attribute) |
| 764 | |
| 765 | Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is |
| 766 | the module name in which the class was defined; :attr:`__dict__` is the |
| 767 | dictionary containing the class's namespace; :attr:`__bases__` is a tuple |
| 768 | (possibly empty or a singleton) containing the base classes, in the order of |
| 769 | their occurrence in the base class list; :attr:`__doc__` is the class's |
| 770 | documentation string, or None if undefined. |
| 771 | |
| 772 | Class instances |
| 773 | .. index:: |
| 774 | object: class instance |
| 775 | object: instance |
| 776 | pair: class; instance |
| 777 | pair: class instance; attribute |
| 778 | |
| 779 | A class instance is created by calling a class object (see above). A class |
| 780 | instance has a namespace implemented as a dictionary which is the first place in |
| 781 | which attribute references are searched. When an attribute is not found there, |
| 782 | and the instance's class has an attribute by that name, the search continues |
| 783 | with the class attributes. If a class attribute is found that is a user-defined |
| 784 | function object or an unbound user-defined method object whose associated class |
| 785 | is the class (call it :class:`C`) of the instance for which the attribute |
| 786 | reference was initiated or one of its bases, it is transformed into a bound |
| 787 | user-defined method object whose :attr:`im_class` attribute is :class:`C` and |
| 788 | whose :attr:`im_self` attribute is the instance. Static method and class method |
| 789 | objects are also transformed, as if they had been retrieved from class |
| 790 | :class:`C`; see above under "Classes". See section :ref:`descriptors` for |
| 791 | another way in which attributes of a class retrieved via its instances may |
| 792 | differ from the objects actually stored in the class's :attr:`__dict__`. If no |
| 793 | class attribute is found, and the object's class has a :meth:`__getattr__` |
| 794 | method, that is called to satisfy the lookup. |
| 795 | |
| 796 | .. index:: triple: class instance; attribute; assignment |
| 797 | |
| 798 | Attribute assignments and deletions update the instance's dictionary, never a |
| 799 | class's dictionary. If the class has a :meth:`__setattr__` or |
| 800 | :meth:`__delattr__` method, this is called instead of updating the instance |
| 801 | dictionary directly. |
| 802 | |
| 803 | .. index:: |
| 804 | object: numeric |
| 805 | object: sequence |
| 806 | object: mapping |
| 807 | |
| 808 | Class instances can pretend to be numbers, sequences, or mappings if they have |
| 809 | methods with certain special names. See section :ref:`specialnames`. |
| 810 | |
| 811 | .. index:: |
| 812 | single: __dict__ (instance attribute) |
| 813 | single: __class__ (instance attribute) |
| 814 | |
| 815 | Special attributes: :attr:`__dict__` is the attribute dictionary; |
| 816 | :attr:`__class__` is the instance's class. |
| 817 | |
| 818 | Files |
| 819 | .. index:: |
| 820 | object: file |
| 821 | builtin: open |
| 822 | single: popen() (in module os) |
| 823 | single: makefile() (socket method) |
| 824 | single: sys.stdin |
| 825 | single: sys.stdout |
| 826 | single: sys.stderr |
| 827 | single: stdio |
| 828 | single: stdin (in module sys) |
| 829 | single: stdout (in module sys) |
| 830 | single: stderr (in module sys) |
| 831 | |
| 832 | A file object represents an open file. File objects are created by the |
| 833 | :func:`open` built-in function, and also by :func:`os.popen`, |
| 834 | :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and |
| 835 | perhaps by other functions or methods provided by extension modules). The |
| 836 | objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to |
| 837 | file objects corresponding to the interpreter's standard input, output and |
| 838 | error streams. See :ref:`bltin-file-objects` for complete documentation of |
| 839 | file objects. |
| 840 | |
| 841 | Internal types |
| 842 | .. index:: |
| 843 | single: internal type |
| 844 | single: types, internal |
| 845 | |
| 846 | A few types used internally by the interpreter are exposed to the user. Their |
| 847 | definitions may change with future versions of the interpreter, but they are |
| 848 | mentioned here for completeness. |
| 849 | |
| 850 | Code objects |
| 851 | .. index:: |
| 852 | single: bytecode |
| 853 | object: code |
| 854 | |
| 855 | Code objects represent *byte-compiled* executable Python code, or *bytecode*. |
| 856 | The difference between a code object and a function object is that the function |
| 857 | object contains an explicit reference to the function's globals (the module in |
| 858 | which it was defined), while a code object contains no context; also the default |
| 859 | argument values are stored in the function object, not in the code object |
| 860 | (because they represent values calculated at run-time). Unlike function |
| 861 | objects, code objects are immutable and contain no references (directly or |
| 862 | indirectly) to mutable objects. |
| 863 | |
| 864 | Special read-only attributes: :attr:`co_name` gives the function name; |
| 865 | :attr:`co_argcount` is the number of positional arguments (including arguments |
| 866 | with default values); :attr:`co_nlocals` is the number of local variables used |
| 867 | by the function (including arguments); :attr:`co_varnames` is a tuple containing |
| 868 | the names of the local variables (starting with the argument names); |
| 869 | :attr:`co_cellvars` is a tuple containing the names of local variables that are |
| 870 | referenced by nested functions; :attr:`co_freevars` is a tuple containing the |
| 871 | names of free variables; :attr:`co_code` is a string representing the sequence |
| 872 | of bytecode instructions; :attr:`co_consts` is a tuple containing the literals |
| 873 | used by the bytecode; :attr:`co_names` is a tuple containing the names used by |
| 874 | the bytecode; :attr:`co_filename` is the filename from which the code was |
| 875 | compiled; :attr:`co_firstlineno` is the first line number of the function; |
| 876 | :attr:`co_lnotab` is a string encoding the mapping from byte code offsets to |
| 877 | line numbers (for details see the source code of the interpreter); |
| 878 | :attr:`co_stacksize` is the required stack size (including local variables); |
| 879 | :attr:`co_flags` is an integer encoding a number of flags for the interpreter. |
| 880 | |
| 881 | .. index:: |
| 882 | single: co_argcount (code object attribute) |
| 883 | single: co_code (code object attribute) |
| 884 | single: co_consts (code object attribute) |
| 885 | single: co_filename (code object attribute) |
| 886 | single: co_firstlineno (code object attribute) |
| 887 | single: co_flags (code object attribute) |
| 888 | single: co_lnotab (code object attribute) |
| 889 | single: co_name (code object attribute) |
| 890 | single: co_names (code object attribute) |
| 891 | single: co_nlocals (code object attribute) |
| 892 | single: co_stacksize (code object attribute) |
| 893 | single: co_varnames (code object attribute) |
| 894 | single: co_cellvars (code object attribute) |
| 895 | single: co_freevars (code object attribute) |
| 896 | |
| 897 | .. index:: object: generator |
| 898 | |
| 899 | The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if |
| 900 | the function uses the ``*arguments`` syntax to accept an arbitrary number of |
| 901 | positional arguments; bit ``0x08`` is set if the function uses the |
| 902 | ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set |
| 903 | if the function is a generator. |
| 904 | |
| 905 | Future feature declarations (``from __future__ import division``) also use bits |
| 906 | in :attr:`co_flags` to indicate whether a code object was compiled with a |
| 907 | particular feature enabled: bit ``0x2000`` is set if the function was compiled |
| 908 | with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier |
| 909 | versions of Python. |
| 910 | |
| 911 | Other bits in :attr:`co_flags` are reserved for internal use. |
| 912 | |
| 913 | .. index:: single: documentation string |
| 914 | |
| 915 | If a code object represents a function, the first item in :attr:`co_consts` is |
| 916 | the documentation string of the function, or ``None`` if undefined. |
| 917 | |
| 918 | Frame objects |
| 919 | .. index:: object: frame |
| 920 | |
| 921 | Frame objects represent execution frames. They may occur in traceback objects |
| 922 | (see below). |
| 923 | |
| 924 | .. index:: |
| 925 | single: f_back (frame attribute) |
| 926 | single: f_code (frame attribute) |
| 927 | single: f_globals (frame attribute) |
| 928 | single: f_locals (frame attribute) |
| 929 | single: f_lasti (frame attribute) |
| 930 | single: f_builtins (frame attribute) |
| 931 | |
| 932 | Special read-only attributes: :attr:`f_back` is to the previous stack frame |
| 933 | (towards the caller), or ``None`` if this is the bottom stack frame; |
| 934 | :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals` |
| 935 | is the dictionary used to look up local variables; :attr:`f_globals` is used for |
| 936 | global variables; :attr:`f_builtins` is used for built-in (intrinsic) names; |
| 937 | :attr:`f_lasti` gives the precise instruction (this is an index into the |
| 938 | bytecode string of the code object). |
| 939 | |
| 940 | .. index:: |
| 941 | single: f_trace (frame attribute) |
| 942 | single: f_exc_type (frame attribute) |
| 943 | single: f_exc_value (frame attribute) |
| 944 | single: f_exc_traceback (frame attribute) |
| 945 | single: f_lineno (frame attribute) |
| 946 | |
| 947 | Special writable attributes: :attr:`f_trace`, if not ``None``, is a function |
| 948 | called at the start of each source code line (this is used by the debugger); |
| 949 | :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the |
| 950 | last exception raised in the parent frame provided another exception was ever |
| 951 | raised in the current frame (in all other cases they are None); :attr:`f_lineno` |
| 952 | is the current line number of the frame --- writing to this from within a trace |
| 953 | function jumps to the given line (only for the bottom-most frame). A debugger |
| 954 | can implement a Jump command (aka Set Next Statement) by writing to f_lineno. |
| 955 | |
| 956 | Traceback objects |
| 957 | .. index:: |
| 958 | object: traceback |
| 959 | pair: stack; trace |
| 960 | pair: exception; handler |
| 961 | pair: execution; stack |
| 962 | single: exc_info (in module sys) |
| 963 | single: exc_traceback (in module sys) |
| 964 | single: last_traceback (in module sys) |
| 965 | single: sys.exc_info |
| 966 | single: sys.last_traceback |
| 967 | |
| 968 | Traceback objects represent a stack trace of an exception. A traceback object |
| 969 | is created when an exception occurs. When the search for an exception handler |
| 970 | unwinds the execution stack, at each unwound level a traceback object is |
| 971 | inserted in front of the current traceback. When an exception handler is |
| 972 | entered, the stack trace is made available to the program. (See section |
| 973 | :ref:`try`.) It is accessible as the third item of the |
| 974 | tuple returned by ``sys.exc_info()``. When the program contains no suitable |
| 975 | handler, the stack trace is written (nicely formatted) to the standard error |
| 976 | stream; if the interpreter is interactive, it is also made available to the user |
| 977 | as ``sys.last_traceback``. |
| 978 | |
| 979 | .. index:: |
| 980 | single: tb_next (traceback attribute) |
| 981 | single: tb_frame (traceback attribute) |
| 982 | single: tb_lineno (traceback attribute) |
| 983 | single: tb_lasti (traceback attribute) |
| 984 | statement: try |
| 985 | |
| 986 | Special read-only attributes: :attr:`tb_next` is the next level in the stack |
| 987 | trace (towards the frame where the exception occurred), or ``None`` if there is |
| 988 | no next level; :attr:`tb_frame` points to the execution frame of the current |
| 989 | level; :attr:`tb_lineno` gives the line number where the exception occurred; |
| 990 | :attr:`tb_lasti` indicates the precise instruction. The line number and last |
| 991 | instruction in the traceback may differ from the line number of its frame object |
| 992 | if the exception occurred in a :keyword:`try` statement with no matching except |
| 993 | clause or with a finally clause. |
| 994 | |
| 995 | Slice objects |
| 996 | .. index:: builtin: slice |
| 997 | |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 998 | Slice objects are used to represent slices for :meth:`__getitem__` |
| 999 | methods. They are also created by the built-in :func:`slice` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1000 | |
| 1001 | .. index:: |
| 1002 | single: start (slice object attribute) |
| 1003 | single: stop (slice object attribute) |
| 1004 | single: step (slice object attribute) |
| 1005 | |
| 1006 | Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is |
| 1007 | the upper bound; :attr:`step` is the step value; each is ``None`` if omitted. |
| 1008 | These attributes can have any type. |
| 1009 | |
| 1010 | Slice objects support one method: |
| 1011 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1012 | .. method:: slice.indices(self, length) |
| 1013 | |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 1014 | This method takes a single integer argument *length* and computes |
| 1015 | information about the slice that the slice object would describe if |
| 1016 | applied to a sequence of *length* items. It returns a tuple of three |
| 1017 | integers; respectively these are the *start* and *stop* indices and the |
| 1018 | *step* or stride length of the slice. Missing or out-of-bounds indices |
| 1019 | are handled in a manner consistent with regular slices. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1020 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1021 | Static method objects |
| 1022 | Static method objects provide a way of defeating the transformation of function |
| 1023 | objects to method objects described above. A static method object is a wrapper |
| 1024 | around any other object, usually a user-defined method object. When a static |
| 1025 | method object is retrieved from a class or a class instance, the object actually |
| 1026 | returned is the wrapped object, which is not subject to any further |
| 1027 | transformation. Static method objects are not themselves callable, although the |
| 1028 | objects they wrap usually are. Static method objects are created by the built-in |
| 1029 | :func:`staticmethod` constructor. |
| 1030 | |
| 1031 | Class method objects |
| 1032 | A class method object, like a static method object, is a wrapper around another |
| 1033 | object that alters the way in which that object is retrieved from classes and |
| 1034 | class instances. The behaviour of class method objects upon such retrieval is |
| 1035 | described above, under "User-defined methods". Class method objects are created |
| 1036 | by the built-in :func:`classmethod` constructor. |
| 1037 | |
| 1038 | .. % Internal types |
| 1039 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1040 | .. % ========================================================================= |
| 1041 | |
| 1042 | |
| 1043 | .. _specialnames: |
| 1044 | |
| 1045 | Special method names |
| 1046 | ==================== |
| 1047 | |
| 1048 | .. index:: |
| 1049 | pair: operator; overloading |
| 1050 | single: __getitem__() (mapping object method) |
| 1051 | |
| 1052 | A class can implement certain operations that are invoked by special syntax |
| 1053 | (such as arithmetic operations or subscripting and slicing) by defining methods |
| 1054 | with special names. This is Python's approach to :dfn:`operator overloading`, |
| 1055 | allowing classes to define their own behavior with respect to language |
| 1056 | operators. For instance, if a class defines a method named :meth:`__getitem__`, |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1057 | and ``x`` is an instance of this class, then ``x[i]`` is equivalent to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1058 | ``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation |
| 1059 | raise an exception when no appropriate method is defined. |
| 1060 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1061 | .. XXX above translation is not correct for new-style classes! |
| 1062 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1063 | When implementing a class that emulates any built-in type, it is important that |
| 1064 | the emulation only be implemented to the degree that it makes sense for the |
| 1065 | object being modelled. For example, some sequences may work well with retrieval |
| 1066 | of individual elements, but extracting a slice may not make sense. (One example |
| 1067 | of this is the :class:`NodeList` interface in the W3C's Document Object Model.) |
| 1068 | |
| 1069 | |
| 1070 | .. _customization: |
| 1071 | |
| 1072 | Basic customization |
| 1073 | ------------------- |
| 1074 | |
| 1075 | |
| 1076 | .. method:: object.__new__(cls[, ...]) |
| 1077 | |
| 1078 | Called to create a new instance of class *cls*. :meth:`__new__` is a static |
| 1079 | method (special-cased so you need not declare it as such) that takes the class |
| 1080 | of which an instance was requested as its first argument. The remaining |
| 1081 | arguments are those passed to the object constructor expression (the call to the |
| 1082 | class). The return value of :meth:`__new__` should be the new object instance |
| 1083 | (usually an instance of *cls*). |
| 1084 | |
| 1085 | Typical implementations create a new instance of the class by invoking the |
| 1086 | superclass's :meth:`__new__` method using ``super(currentclass, |
| 1087 | cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the |
| 1088 | newly-created instance as necessary before returning it. |
| 1089 | |
| 1090 | If :meth:`__new__` returns an instance of *cls*, then the new instance's |
| 1091 | :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where |
| 1092 | *self* is the new instance and the remaining arguments are the same as were |
| 1093 | passed to :meth:`__new__`. |
| 1094 | |
| 1095 | If :meth:`__new__` does not return an instance of *cls*, then the new instance's |
| 1096 | :meth:`__init__` method will not be invoked. |
| 1097 | |
| 1098 | :meth:`__new__` is intended mainly to allow subclasses of immutable types (like |
| 1099 | int, str, or tuple) to customize instance creation. |
| 1100 | |
| 1101 | |
| 1102 | .. method:: object.__init__(self[, ...]) |
| 1103 | |
| 1104 | .. index:: pair: class; constructor |
| 1105 | |
| 1106 | Called when the instance is created. The arguments are those passed to the |
| 1107 | class constructor expression. If a base class has an :meth:`__init__` method, |
| 1108 | the derived class's :meth:`__init__` method, if any, must explicitly call it to |
| 1109 | ensure proper initialization of the base class part of the instance; for |
| 1110 | example: ``BaseClass.__init__(self, [args...])``. As a special constraint on |
| 1111 | constructors, no value may be returned; doing so will cause a :exc:`TypeError` |
| 1112 | to be raised at runtime. |
| 1113 | |
| 1114 | |
| 1115 | .. method:: object.__del__(self) |
| 1116 | |
| 1117 | .. index:: |
| 1118 | single: destructor |
| 1119 | statement: del |
| 1120 | |
| 1121 | Called when the instance is about to be destroyed. This is also called a |
| 1122 | destructor. If a base class has a :meth:`__del__` method, the derived class's |
| 1123 | :meth:`__del__` method, if any, must explicitly call it to ensure proper |
| 1124 | deletion of the base class part of the instance. Note that it is possible |
| 1125 | (though not recommended!) for the :meth:`__del__` method to postpone destruction |
| 1126 | of the instance by creating a new reference to it. It may then be called at a |
| 1127 | later time when this new reference is deleted. It is not guaranteed that |
| 1128 | :meth:`__del__` methods are called for objects that still exist when the |
| 1129 | interpreter exits. |
| 1130 | |
| 1131 | .. note:: |
| 1132 | |
| 1133 | ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements |
| 1134 | the reference count for ``x`` by one, and the latter is only called when |
| 1135 | ``x``'s reference count reaches zero. Some common situations that may |
| 1136 | prevent the reference count of an object from going to zero include: |
| 1137 | circular references between objects (e.g., a doubly-linked list or a tree |
| 1138 | data structure with parent and child pointers); a reference to the object |
| 1139 | on the stack frame of a function that caught an exception (the traceback |
| 1140 | stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a |
| 1141 | reference to the object on the stack frame that raised an unhandled |
| 1142 | exception in interactive mode (the traceback stored in |
| 1143 | ``sys.last_traceback`` keeps the stack frame alive). The first situation |
| 1144 | can only be remedied by explicitly breaking the cycles; the latter two |
| 1145 | situations can be resolved by storing ``None`` in ``sys.last_traceback``. |
| 1146 | Circular references which are garbage are detected when the option cycle |
| 1147 | detector is enabled (it's on by default), but can only be cleaned up if |
| 1148 | there are no Python- level :meth:`__del__` methods involved. Refer to the |
| 1149 | documentation for the :mod:`gc` module for more information about how |
| 1150 | :meth:`__del__` methods are handled by the cycle detector, particularly |
| 1151 | the description of the ``garbage`` value. |
| 1152 | |
| 1153 | .. warning:: |
| 1154 | |
| 1155 | Due to the precarious circumstances under which :meth:`__del__` methods are |
| 1156 | invoked, exceptions that occur during their execution are ignored, and a warning |
| 1157 | is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in |
| 1158 | response to a module being deleted (e.g., when execution of the program is |
| 1159 | done), other globals referenced by the :meth:`__del__` method may already have |
| 1160 | been deleted. For this reason, :meth:`__del__` methods should do the absolute |
| 1161 | minimum needed to maintain external invariants. Starting with version 1.5, |
| 1162 | Python guarantees that globals whose name begins with a single underscore are |
| 1163 | deleted from their module before other globals are deleted; if no other |
| 1164 | references to such globals exist, this may help in assuring that imported |
| 1165 | modules are still available at the time when the :meth:`__del__` method is |
| 1166 | called. |
| 1167 | |
| 1168 | |
| 1169 | .. method:: object.__repr__(self) |
| 1170 | |
| 1171 | .. index:: builtin: repr |
| 1172 | |
| 1173 | Called by the :func:`repr` built-in function and by string conversions (reverse |
| 1174 | quotes) to compute the "official" string representation of an object. If at all |
| 1175 | possible, this should look like a valid Python expression that could be used to |
| 1176 | recreate an object with the same value (given an appropriate environment). If |
| 1177 | this is not possible, a string of the form ``<...some useful description...>`` |
| 1178 | should be returned. The return value must be a string object. If a class |
| 1179 | defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also |
| 1180 | used when an "informal" string representation of instances of that class is |
| 1181 | required. |
| 1182 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1183 | This is typically used for debugging, so it is important that the representation |
| 1184 | is information-rich and unambiguous. |
| 1185 | |
| 1186 | |
| 1187 | .. method:: object.__str__(self) |
| 1188 | |
| 1189 | .. index:: |
| 1190 | builtin: str |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1191 | builtin: print |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1192 | |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 1193 | Called by the :func:`str` built-in function and by the :func:`print` function |
| 1194 | to compute the "informal" string representation of an object. This differs |
| 1195 | from :meth:`__repr__` in that it does not have to be a valid Python |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1196 | expression: a more convenient or concise representation may be used instead. |
| 1197 | The return value must be a string object. |
| 1198 | |
Georg Brandl | dcc56f8 | 2007-08-31 16:41:12 +0000 | [diff] [blame] | 1199 | .. XXX what about subclasses of string? |
| 1200 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1201 | |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1202 | .. method:: object.__format__(self, format_spec) |
| 1203 | |
| 1204 | .. index:: |
| 1205 | pair: string; conversion |
| 1206 | builtin: str |
| 1207 | builtin: print |
| 1208 | |
| 1209 | Called by the :func:`format` built-in function (and by extension, the |
| 1210 | :meth:`format` method of class :class:`str`) to produce a "formatted" |
| 1211 | string representation of an object. The ``format_spec`` argument is |
| 1212 | a string that contains a description of the formatting options desired. |
| 1213 | The interpretation of the ``format_spec`` argument is up to the type |
| 1214 | implementing :meth:`__format__`, however most classes will either |
| 1215 | delegate formatting to one of the built-in types, or use a similar |
| 1216 | formatting option syntax. |
| 1217 | |
| 1218 | See :ref:`formatspec` for a description of the standard formatting syntax. |
| 1219 | |
| 1220 | The return value must be a string object. |
| 1221 | |
| 1222 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1223 | .. method:: object.__lt__(self, other) |
| 1224 | object.__le__(self, other) |
| 1225 | object.__eq__(self, other) |
| 1226 | object.__ne__(self, other) |
| 1227 | object.__gt__(self, other) |
| 1228 | object.__ge__(self, other) |
| 1229 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1230 | These are the so-called "rich comparison" methods, and are called for comparison |
| 1231 | operators in preference to :meth:`__cmp__` below. The correspondence between |
| 1232 | operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``, |
| 1233 | ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls |
| 1234 | ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls |
| 1235 | ``x.__ge__(y)``. |
| 1236 | |
| 1237 | A rich comparison method may return the singleton ``NotImplemented`` if it does |
| 1238 | not implement the operation for a given pair of arguments. By convention, |
| 1239 | ``False`` and ``True`` are returned for a successful comparison. However, these |
| 1240 | methods can return any value, so if the comparison operator is used in a Boolean |
| 1241 | context (e.g., in the condition of an ``if`` statement), Python will call |
| 1242 | :func:`bool` on the value to determine if the result is true or false. |
| 1243 | |
| 1244 | There are no implied relationships among the comparison operators. The truth of |
| 1245 | ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when defining |
| 1246 | :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will |
| 1247 | behave as expected. |
| 1248 | |
| 1249 | There are no reflected (swapped-argument) versions of these methods (to be used |
| 1250 | when the left argument does not support the operation but the right argument |
| 1251 | does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection, |
| 1252 | :meth:`__le__` and :meth:`__ge__` are each other's reflection, and |
| 1253 | :meth:`__eq__` and :meth:`__ne__` are their own reflection. |
| 1254 | |
| 1255 | Arguments to rich comparison methods are never coerced. |
| 1256 | |
| 1257 | |
| 1258 | .. method:: object.__cmp__(self, other) |
| 1259 | |
| 1260 | .. index:: |
| 1261 | builtin: cmp |
| 1262 | single: comparisons |
| 1263 | |
| 1264 | Called by comparison operations if rich comparison (see above) is not defined. |
| 1265 | Should return a negative integer if ``self < other``, zero if ``self == other``, |
| 1266 | a positive integer if ``self > other``. If no :meth:`__cmp__`, :meth:`__eq__` |
| 1267 | or :meth:`__ne__` operation is defined, class instances are compared by object |
| 1268 | identity ("address"). See also the description of :meth:`__hash__` for some |
| 1269 | important notes on creating objects which support custom comparison operations |
| 1270 | and are usable as dictionary keys. (Note: the restriction that exceptions are |
| 1271 | not propagated by :meth:`__cmp__` has been removed since Python 1.5.) |
| 1272 | |
| 1273 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1274 | .. method:: object.__hash__(self) |
| 1275 | |
| 1276 | .. index:: |
| 1277 | object: dictionary |
| 1278 | builtin: hash |
Georg Brandl | 1617457 | 2007-09-01 12:38:06 +0000 | [diff] [blame] | 1279 | single: __cmp__() (object method) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1280 | |
| 1281 | Called for the key object for dictionary operations, and by the built-in |
| 1282 | function :func:`hash`. Should return a 32-bit integer usable as a hash value |
| 1283 | for dictionary operations. The only required property is that objects which |
| 1284 | compare equal have the same hash value; it is advised to somehow mix together |
| 1285 | (e.g., using exclusive or) the hash values for the components of the object that |
| 1286 | also play a part in comparison of objects. If a class does not define a |
| 1287 | :meth:`__cmp__` method it should not define a :meth:`__hash__` operation either; |
| 1288 | if it defines :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its |
| 1289 | instances will not be usable as dictionary keys. If a class defines mutable |
| 1290 | objects and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not |
| 1291 | implement :meth:`__hash__`, since the dictionary implementation requires that a |
| 1292 | key's hash value is immutable (if the object's hash value changes, it will be in |
| 1293 | the wrong hash bucket). |
| 1294 | |
Georg Brandl | 1617457 | 2007-09-01 12:38:06 +0000 | [diff] [blame] | 1295 | :meth:`__hash__` may also return a long integer object; the 32-bit integer is |
| 1296 | then derived from the hash of that object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1297 | |
| 1298 | |
| 1299 | .. method:: object.__bool__(self) |
| 1300 | |
| 1301 | .. index:: single: __len__() (mapping object method) |
| 1302 | |
| 1303 | Called to implement truth value testing, and the built-in operation ``bool()``; |
| 1304 | should return ``False`` or ``True``. When this method is not defined, |
| 1305 | :meth:`__len__` is called, if it is defined (see below) and ``True`` is returned |
| 1306 | when the length is not zero. If a class defines neither :meth:`__len__` nor |
| 1307 | :meth:`__bool__`, all its instances are considered true. |
| 1308 | |
| 1309 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1310 | .. _attribute-access: |
| 1311 | |
| 1312 | Customizing attribute access |
| 1313 | ---------------------------- |
| 1314 | |
| 1315 | The following methods can be defined to customize the meaning of attribute |
| 1316 | access (use of, assignment to, or deletion of ``x.name``) for class instances. |
| 1317 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1318 | .. XXX explain how descriptors interfere here! |
| 1319 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1320 | |
| 1321 | .. method:: object.__getattr__(self, name) |
| 1322 | |
| 1323 | Called when an attribute lookup has not found the attribute in the usual places |
| 1324 | (i.e. it is not an instance attribute nor is it found in the class tree for |
| 1325 | ``self``). ``name`` is the attribute name. This method should return the |
| 1326 | (computed) attribute value or raise an :exc:`AttributeError` exception. |
| 1327 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1328 | Note that if the attribute is found through the normal mechanism, |
| 1329 | :meth:`__getattr__` is not called. (This is an intentional asymmetry between |
| 1330 | :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency |
| 1331 | reasons and because otherwise :meth:`__setattr__` would have no way to access |
| 1332 | other attributes of the instance. Note that at least for instance variables, |
| 1333 | you can fake total control by not inserting any values in the instance attribute |
| 1334 | dictionary (but instead inserting them in another object). See the |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1335 | :meth:`__getattribute__` method below for a way to actually get total control |
| 1336 | over attribute access. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1337 | |
| 1338 | |
| 1339 | .. method:: object.__getattribute__(self, name) |
| 1340 | |
| 1341 | Called unconditionally to implement attribute accesses for instances of the |
| 1342 | class. If the class also defines :meth:`__getattr__`, the latter will not be |
| 1343 | called unless :meth:`__getattribute__` either calls it explicitly or raises an |
| 1344 | :exc:`AttributeError`. This method should return the (computed) attribute value |
| 1345 | or raise an :exc:`AttributeError` exception. In order to avoid infinite |
| 1346 | recursion in this method, its implementation should always call the base class |
| 1347 | method with the same name to access any attributes it needs, for example, |
| 1348 | ``object.__getattribute__(self, name)``. |
| 1349 | |
| 1350 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1351 | .. method:: object.__setattr__(self, name, value) |
| 1352 | |
| 1353 | Called when an attribute assignment is attempted. This is called instead of |
| 1354 | the normal mechanism (i.e. store the value in the instance dictionary). |
| 1355 | *name* is the attribute name, *value* is the value to be assigned to it. |
| 1356 | |
| 1357 | If :meth:`__setattr__` wants to assign to an instance attribute, it should |
| 1358 | call the base class method with the same name, for example, |
| 1359 | ``object.__setattr__(self, name, value)``. |
| 1360 | |
| 1361 | |
| 1362 | .. method:: object.__delattr__(self, name) |
| 1363 | |
| 1364 | Like :meth:`__setattr__` but for attribute deletion instead of assignment. This |
| 1365 | should only be implemented if ``del obj.name`` is meaningful for the object. |
| 1366 | |
| 1367 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1368 | .. _descriptors: |
| 1369 | |
| 1370 | Implementing Descriptors |
| 1371 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1372 | |
| 1373 | The following methods only apply when an instance of the class containing the |
| 1374 | method (a so-called *descriptor* class) appears in the class dictionary of |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1375 | another class, known as the *owner* class. In the examples below, "the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1376 | attribute" refers to the attribute whose name is the key of the property in the |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1377 | owner class' :attr:`__dict__`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1378 | |
| 1379 | |
| 1380 | .. method:: object.__get__(self, instance, owner) |
| 1381 | |
| 1382 | Called to get the attribute of the owner class (class attribute access) or of an |
| 1383 | instance of that class (instance attribute access). *owner* is always the owner |
| 1384 | class, while *instance* is the instance that the attribute was accessed through, |
| 1385 | or ``None`` when the attribute is accessed through the *owner*. This method |
| 1386 | should return the (computed) attribute value or raise an :exc:`AttributeError` |
| 1387 | exception. |
| 1388 | |
| 1389 | |
| 1390 | .. method:: object.__set__(self, instance, value) |
| 1391 | |
| 1392 | Called to set the attribute on an instance *instance* of the owner class to a |
| 1393 | new value, *value*. |
| 1394 | |
| 1395 | |
| 1396 | .. method:: object.__delete__(self, instance) |
| 1397 | |
| 1398 | Called to delete the attribute on an instance *instance* of the owner class. |
| 1399 | |
| 1400 | |
| 1401 | .. _descriptor-invocation: |
| 1402 | |
| 1403 | Invoking Descriptors |
| 1404 | ^^^^^^^^^^^^^^^^^^^^ |
| 1405 | |
| 1406 | In general, a descriptor is an object attribute with "binding behavior", one |
| 1407 | whose attribute access has been overridden by methods in the descriptor |
| 1408 | protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of |
| 1409 | those methods are defined for an object, it is said to be a descriptor. |
| 1410 | |
| 1411 | The default behavior for attribute access is to get, set, or delete the |
| 1412 | attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain |
| 1413 | starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and |
| 1414 | continuing through the base classes of ``type(a)`` excluding metaclasses. |
| 1415 | |
| 1416 | However, if the looked-up value is an object defining one of the descriptor |
| 1417 | methods, then Python may override the default behavior and invoke the descriptor |
| 1418 | method instead. Where this occurs in the precedence chain depends on which |
| 1419 | descriptor methods were defined and how they were called. Note that descriptors |
| 1420 | are only invoked for new style objects or classes (ones that subclass |
| 1421 | :class:`object()` or :class:`type()`). |
| 1422 | |
| 1423 | The starting point for descriptor invocation is a binding, ``a.x``. How the |
| 1424 | arguments are assembled depends on ``a``: |
| 1425 | |
| 1426 | Direct Call |
| 1427 | The simplest and least common call is when user code directly invokes a |
| 1428 | descriptor method: ``x.__get__(a)``. |
| 1429 | |
| 1430 | Instance Binding |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1431 | If binding to an object instance, ``a.x`` is transformed into the call: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1432 | ``type(a).__dict__['x'].__get__(a, type(a))``. |
| 1433 | |
| 1434 | Class Binding |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1435 | If binding to a class, ``A.x`` is transformed into the call: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1436 | ``A.__dict__['x'].__get__(None, A)``. |
| 1437 | |
| 1438 | Super Binding |
| 1439 | If ``a`` is an instance of :class:`super`, then the binding ``super(B, |
| 1440 | obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` |
| 1441 | immediately preceding ``B`` and then invokes the descriptor with the call: |
| 1442 | ``A.__dict__['m'].__get__(obj, A)``. |
| 1443 | |
| 1444 | For instance bindings, the precedence of descriptor invocation depends on the |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 1445 | which descriptor methods are defined. Normally, data descriptors define both |
| 1446 | :meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1447 | :meth:`__get__` method. Data descriptors always override a redefinition in an |
| 1448 | instance dictionary. In contrast, non-data descriptors can be overridden by |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 1449 | instances. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1450 | |
| 1451 | Python methods (including :func:`staticmethod` and :func:`classmethod`) are |
| 1452 | implemented as non-data descriptors. Accordingly, instances can redefine and |
| 1453 | override methods. This allows individual instances to acquire behaviors that |
| 1454 | differ from other instances of the same class. |
| 1455 | |
| 1456 | The :func:`property` function is implemented as a data descriptor. Accordingly, |
| 1457 | instances cannot override the behavior of a property. |
| 1458 | |
| 1459 | |
| 1460 | .. _slots: |
| 1461 | |
| 1462 | __slots__ |
| 1463 | ^^^^^^^^^ |
| 1464 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1465 | By default, instances of classes have a dictionary for attribute storage. This |
| 1466 | wastes space for objects having very few instance variables. The space |
| 1467 | consumption can become acute when creating large numbers of instances. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1468 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1469 | The default can be overridden by defining *__slots__* in a class definition. |
| 1470 | The *__slots__* declaration takes a sequence of instance variables and reserves |
| 1471 | just enough space in each instance to hold a value for each variable. Space is |
| 1472 | saved because *__dict__* is not created for each instance. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1473 | |
| 1474 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1475 | .. data:: object.__slots__ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1476 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1477 | This class variable can be assigned a string, iterable, or sequence of |
| 1478 | strings with variable names used by instances. If defined in a new-style |
| 1479 | class, *__slots__* reserves space for the declared variables and prevents the |
| 1480 | automatic creation of *__dict__* and *__weakref__* for each instance. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1481 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1482 | |
| 1483 | Notes on using *__slots__* |
Georg Brandl | 1617457 | 2007-09-01 12:38:06 +0000 | [diff] [blame] | 1484 | """""""""""""""""""""""""" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1485 | |
| 1486 | * Without a *__dict__* variable, instances cannot be assigned new variables not |
| 1487 | listed in the *__slots__* definition. Attempts to assign to an unlisted |
| 1488 | variable name raises :exc:`AttributeError`. If dynamic assignment of new |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1489 | variables is desired, then add ``'__dict__'`` to the sequence of strings in |
| 1490 | the *__slots__* declaration. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1491 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1492 | * Without a *__weakref__* variable for each instance, classes defining |
| 1493 | *__slots__* do not support weak references to its instances. If weak reference |
| 1494 | support is needed, then add ``'__weakref__'`` to the sequence of strings in the |
| 1495 | *__slots__* declaration. |
| 1496 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1497 | * *__slots__* are implemented at the class level by creating descriptors |
| 1498 | (:ref:`descriptors`) for each variable name. As a result, class attributes |
| 1499 | cannot be used to set default values for instance variables defined by |
| 1500 | *__slots__*; otherwise, the class attribute would overwrite the descriptor |
| 1501 | assignment. |
| 1502 | |
| 1503 | * If a class defines a slot also defined in a base class, the instance variable |
| 1504 | defined by the base class slot is inaccessible (except by retrieving its |
| 1505 | descriptor directly from the base class). This renders the meaning of the |
| 1506 | program undefined. In the future, a check may be added to prevent this. |
| 1507 | |
| 1508 | * The action of a *__slots__* declaration is limited to the class where it is |
| 1509 | defined. As a result, subclasses will have a *__dict__* unless they also define |
| 1510 | *__slots__*. |
| 1511 | |
| 1512 | * *__slots__* do not work for classes derived from "variable-length" built-in |
| 1513 | types such as :class:`long`, :class:`str` and :class:`tuple`. |
| 1514 | |
| 1515 | * Any non-string iterable may be assigned to *__slots__*. Mappings may also be |
| 1516 | used; however, in the future, special meaning may be assigned to the values |
| 1517 | corresponding to each key. |
| 1518 | |
| 1519 | * *__class__* assignment works only if both classes have the same *__slots__*. |
| 1520 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1521 | |
| 1522 | .. _metaclasses: |
| 1523 | |
| 1524 | Customizing class creation |
| 1525 | -------------------------- |
| 1526 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1527 | By default, classes are constructed using :func:`type`. A class definition is |
| 1528 | read into a separate namespace and the value of class name is bound to the |
| 1529 | result of ``type(name, bases, dict)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1530 | |
| 1531 | When the class definition is read, if *__metaclass__* is defined then the |
| 1532 | callable assigned to it will be called instead of :func:`type`. The allows |
| 1533 | classes or functions to be written which monitor or alter the class creation |
| 1534 | process: |
| 1535 | |
| 1536 | * Modifying the class dictionary prior to the class being created. |
| 1537 | |
| 1538 | * Returning an instance of another class -- essentially performing the role of a |
| 1539 | factory function. |
| 1540 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1541 | .. XXX needs to be updated for the "new metaclasses" PEP |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1542 | .. data:: __metaclass__ |
| 1543 | |
| 1544 | This variable can be any callable accepting arguments for ``name``, ``bases``, |
| 1545 | and ``dict``. Upon class creation, the callable is used instead of the built-in |
| 1546 | :func:`type`. |
| 1547 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1548 | The appropriate metaclass is determined by the following precedence rules: |
| 1549 | |
| 1550 | * If ``dict['__metaclass__']`` exists, it is used. |
| 1551 | |
| 1552 | * Otherwise, if there is at least one base class, its metaclass is used (this |
| 1553 | looks for a *__class__* attribute first and if not found, uses its type). |
| 1554 | |
| 1555 | * Otherwise, if a global variable named __metaclass__ exists, it is used. |
| 1556 | |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 1557 | * Otherwise, the default metaclass (:class:`type`) is used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1558 | |
| 1559 | The potential uses for metaclasses are boundless. Some ideas that have been |
| 1560 | explored including logging, interface checking, automatic delegation, automatic |
| 1561 | property creation, proxies, frameworks, and automatic resource |
| 1562 | locking/synchronization. |
| 1563 | |
| 1564 | |
| 1565 | .. _callable-types: |
| 1566 | |
| 1567 | Emulating callable objects |
| 1568 | -------------------------- |
| 1569 | |
| 1570 | |
| 1571 | .. method:: object.__call__(self[, args...]) |
| 1572 | |
| 1573 | .. index:: pair: call; instance |
| 1574 | |
| 1575 | Called when the instance is "called" as a function; if this method is defined, |
| 1576 | ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``. |
| 1577 | |
| 1578 | |
| 1579 | .. _sequence-types: |
| 1580 | |
| 1581 | Emulating container types |
| 1582 | ------------------------- |
| 1583 | |
| 1584 | The following methods can be defined to implement container objects. Containers |
| 1585 | usually are sequences (such as lists or tuples) or mappings (like dictionaries), |
| 1586 | but can represent other containers as well. The first set of methods is used |
| 1587 | either to emulate a sequence or to emulate a mapping; the difference is that for |
| 1588 | a sequence, the allowable keys should be the integers *k* for which ``0 <= k < |
| 1589 | N`` where *N* is the length of the sequence, or slice objects, which define a |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 1590 | range of items. It is also recommended that mappings provide the methods |
| 1591 | :meth:`keys`, :meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, |
Fred Drake | 2e74878 | 2007-09-04 17:33:11 +0000 | [diff] [blame] | 1592 | :meth:`clear`, :meth:`setdefault`, |
| 1593 | :meth:`pop`, :meth:`popitem`, :meth:`copy`, and |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 1594 | :meth:`update` behaving similar to those for Python's standard dictionary |
| 1595 | objects. The :mod:`UserDict` module provides a :class:`DictMixin` class to help |
| 1596 | create those methods from a base set of :meth:`__getitem__`, |
| 1597 | :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`. Mutable sequences |
| 1598 | should provide methods :meth:`append`, :meth:`count`, :meth:`index`, |
| 1599 | :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, :meth:`reverse` and |
| 1600 | :meth:`sort`, like Python standard list objects. Finally, sequence types should |
| 1601 | implement addition (meaning concatenation) and multiplication (meaning |
| 1602 | repetition) by defining the methods :meth:`__add__`, :meth:`__radd__`, |
| 1603 | :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and :meth:`__imul__` |
| 1604 | described below; they should not define other numerical operators. It is |
| 1605 | recommended that both mappings and sequences implement the :meth:`__contains__` |
| 1606 | method to allow efficient use of the ``in`` operator; for mappings, ``in`` |
| 1607 | should be equivalent of :meth:`has_key`; for sequences, it should search through |
| 1608 | the values. It is further recommended that both mappings and sequences |
| 1609 | implement the :meth:`__iter__` method to allow efficient iteration through the |
| 1610 | container; for mappings, :meth:`__iter__` should be the same as |
Fred Drake | 2e74878 | 2007-09-04 17:33:11 +0000 | [diff] [blame] | 1611 | :meth:`keys`; for sequences, it should iterate through the values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1612 | |
| 1613 | .. method:: object.__len__(self) |
| 1614 | |
| 1615 | .. index:: |
| 1616 | builtin: len |
| 1617 | single: __bool__() (object method) |
| 1618 | |
| 1619 | Called to implement the built-in function :func:`len`. Should return the length |
| 1620 | of the object, an integer ``>=`` 0. Also, an object that doesn't define a |
| 1621 | :meth:`__bool__` method and whose :meth:`__len__` method returns zero is |
| 1622 | considered to be false in a Boolean context. |
| 1623 | |
| 1624 | |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 1625 | .. note:: |
| 1626 | |
| 1627 | Slicing is done exclusively with the following three methods. A call like :: |
| 1628 | |
| 1629 | a[1:2] = b |
| 1630 | |
| 1631 | is translated to :: |
| 1632 | |
| 1633 | a[slice(1, 2, None)] = b |
| 1634 | |
| 1635 | and so forth. Missing slice items are always filled in with ``None``. |
| 1636 | |
| 1637 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1638 | .. method:: object.__getitem__(self, key) |
| 1639 | |
| 1640 | .. index:: object: slice |
| 1641 | |
| 1642 | Called to implement evaluation of ``self[key]``. For sequence types, the |
| 1643 | accepted keys should be integers and slice objects. Note that the special |
| 1644 | interpretation of negative indexes (if the class wishes to emulate a sequence |
| 1645 | type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate |
| 1646 | type, :exc:`TypeError` may be raised; if of a value outside the set of indexes |
| 1647 | for the sequence (after any special interpretation of negative values), |
| 1648 | :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not |
| 1649 | in the container), :exc:`KeyError` should be raised. |
| 1650 | |
| 1651 | .. note:: |
| 1652 | |
| 1653 | :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal |
| 1654 | indexes to allow proper detection of the end of the sequence. |
| 1655 | |
| 1656 | |
| 1657 | .. method:: object.__setitem__(self, key, value) |
| 1658 | |
| 1659 | Called to implement assignment to ``self[key]``. Same note as for |
| 1660 | :meth:`__getitem__`. This should only be implemented for mappings if the |
| 1661 | objects support changes to the values for keys, or if new keys can be added, or |
| 1662 | for sequences if elements can be replaced. The same exceptions should be raised |
| 1663 | for improper *key* values as for the :meth:`__getitem__` method. |
| 1664 | |
| 1665 | |
| 1666 | .. method:: object.__delitem__(self, key) |
| 1667 | |
| 1668 | Called to implement deletion of ``self[key]``. Same note as for |
| 1669 | :meth:`__getitem__`. This should only be implemented for mappings if the |
| 1670 | objects support removal of keys, or for sequences if elements can be removed |
| 1671 | from the sequence. The same exceptions should be raised for improper *key* |
| 1672 | values as for the :meth:`__getitem__` method. |
| 1673 | |
| 1674 | |
| 1675 | .. method:: object.__iter__(self) |
| 1676 | |
| 1677 | This method is called when an iterator is required for a container. This method |
| 1678 | should return a new iterator object that can iterate over all the objects in the |
| 1679 | container. For mappings, it should iterate over the keys of the container, and |
Fred Drake | 2e74878 | 2007-09-04 17:33:11 +0000 | [diff] [blame] | 1680 | should also be made available as the method :meth:`keys`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1681 | |
| 1682 | Iterator objects also need to implement this method; they are required to return |
| 1683 | themselves. For more information on iterator objects, see :ref:`typeiter`. |
| 1684 | |
| 1685 | The membership test operators (:keyword:`in` and :keyword:`not in`) are normally |
| 1686 | implemented as an iteration through a sequence. However, container objects can |
| 1687 | supply the following special method with a more efficient implementation, which |
| 1688 | also does not require the object be a sequence. |
| 1689 | |
| 1690 | |
| 1691 | .. method:: object.__contains__(self, item) |
| 1692 | |
| 1693 | Called to implement membership test operators. Should return true if *item* is |
| 1694 | in *self*, false otherwise. For mapping objects, this should consider the keys |
| 1695 | of the mapping rather than the values or the key-item pairs. |
| 1696 | |
| 1697 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1698 | .. _numeric-types: |
| 1699 | |
| 1700 | Emulating numeric types |
| 1701 | ----------------------- |
| 1702 | |
| 1703 | The following methods can be defined to emulate numeric objects. Methods |
| 1704 | corresponding to operations that are not supported by the particular kind of |
| 1705 | number implemented (e.g., bitwise operations for non-integral numbers) should be |
| 1706 | left undefined. |
| 1707 | |
| 1708 | |
| 1709 | .. method:: object.__add__(self, other) |
| 1710 | object.__sub__(self, other) |
| 1711 | object.__mul__(self, other) |
| 1712 | object.__floordiv__(self, other) |
| 1713 | object.__mod__(self, other) |
| 1714 | object.__divmod__(self, other) |
| 1715 | object.__pow__(self, other[, modulo]) |
| 1716 | object.__lshift__(self, other) |
| 1717 | object.__rshift__(self, other) |
| 1718 | object.__and__(self, other) |
| 1719 | object.__xor__(self, other) |
| 1720 | object.__or__(self, other) |
| 1721 | |
| 1722 | .. index:: |
| 1723 | builtin: divmod |
| 1724 | builtin: pow |
| 1725 | builtin: pow |
| 1726 | |
| 1727 | These methods are called to implement the binary arithmetic operations (``+``, |
| 1728 | ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, |
| 1729 | ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression |
| 1730 | *x*``+``*y*, where *x* is an instance of a class that has an :meth:`__add__` |
| 1731 | method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the |
| 1732 | equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be |
| 1733 | related to :meth:`__truediv__` (described below). Note that :meth:`__pow__` |
| 1734 | should be defined to accept an optional third argument if the ternary version of |
| 1735 | the built-in :func:`pow` function is to be supported. |
| 1736 | |
| 1737 | If one of those methods does not support the operation with the supplied |
| 1738 | arguments, it should return ``NotImplemented``. |
| 1739 | |
| 1740 | |
| 1741 | .. method:: object.__div__(self, other) |
| 1742 | object.__truediv__(self, other) |
| 1743 | |
| 1744 | The division operator (``/``) is implemented by these methods. The |
| 1745 | :meth:`__truediv__` method is used when ``__future__.division`` is in effect, |
| 1746 | otherwise :meth:`__div__` is used. If only one of these two methods is defined, |
| 1747 | the object will not support division in the alternate context; :exc:`TypeError` |
| 1748 | will be raised instead. |
| 1749 | |
| 1750 | |
| 1751 | .. method:: object.__radd__(self, other) |
| 1752 | object.__rsub__(self, other) |
| 1753 | object.__rmul__(self, other) |
| 1754 | object.__rdiv__(self, other) |
| 1755 | object.__rtruediv__(self, other) |
| 1756 | object.__rfloordiv__(self, other) |
| 1757 | object.__rmod__(self, other) |
| 1758 | object.__rdivmod__(self, other) |
| 1759 | object.__rpow__(self, other) |
| 1760 | object.__rlshift__(self, other) |
| 1761 | object.__rrshift__(self, other) |
| 1762 | object.__rand__(self, other) |
| 1763 | object.__rxor__(self, other) |
| 1764 | object.__ror__(self, other) |
| 1765 | |
| 1766 | .. index:: |
| 1767 | builtin: divmod |
| 1768 | builtin: pow |
| 1769 | |
| 1770 | These methods are called to implement the binary arithmetic operations (``+``, |
| 1771 | ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``, |
| 1772 | ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are |
| 1773 | only called if the left operand does not support the corresponding operation and |
| 1774 | the operands are of different types. [#]_ For instance, to evaluate the |
| 1775 | expression *x*``-``*y*, where *y* is an instance of a class that has an |
| 1776 | :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns |
| 1777 | *NotImplemented*. |
| 1778 | |
| 1779 | .. index:: builtin: pow |
| 1780 | |
| 1781 | Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the |
| 1782 | coercion rules would become too complicated). |
| 1783 | |
| 1784 | .. note:: |
| 1785 | |
| 1786 | If the right operand's type is a subclass of the left operand's type and that |
| 1787 | subclass provides the reflected method for the operation, this method will be |
| 1788 | called before the left operand's non-reflected method. This behavior allows |
| 1789 | subclasses to override their ancestors' operations. |
| 1790 | |
| 1791 | |
| 1792 | .. method:: object.__iadd__(self, other) |
| 1793 | object.__isub__(self, other) |
| 1794 | object.__imul__(self, other) |
| 1795 | object.__idiv__(self, other) |
| 1796 | object.__itruediv__(self, other) |
| 1797 | object.__ifloordiv__(self, other) |
| 1798 | object.__imod__(self, other) |
| 1799 | object.__ipow__(self, other[, modulo]) |
| 1800 | object.__ilshift__(self, other) |
| 1801 | object.__irshift__(self, other) |
| 1802 | object.__iand__(self, other) |
| 1803 | object.__ixor__(self, other) |
| 1804 | object.__ior__(self, other) |
| 1805 | |
| 1806 | These methods are called to implement the augmented arithmetic operations |
| 1807 | (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, |
| 1808 | ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation |
| 1809 | in-place (modifying *self*) and return the result (which could be, but does |
| 1810 | not have to be, *self*). If a specific method is not defined, the augmented |
| 1811 | operation falls back to the normal methods. For instance, to evaluate the |
| 1812 | expression *x*``+=``*y*, where *x* is an instance of a class that has an |
| 1813 | :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance |
| 1814 | of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` |
| 1815 | and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. |
| 1816 | |
| 1817 | |
| 1818 | .. method:: object.__neg__(self) |
| 1819 | object.__pos__(self) |
| 1820 | object.__abs__(self) |
| 1821 | object.__invert__(self) |
| 1822 | |
| 1823 | .. index:: builtin: abs |
| 1824 | |
| 1825 | Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs` |
| 1826 | and ``~``). |
| 1827 | |
| 1828 | |
| 1829 | .. method:: object.__complex__(self) |
| 1830 | object.__int__(self) |
| 1831 | object.__long__(self) |
| 1832 | object.__float__(self) |
| 1833 | |
| 1834 | .. index:: |
| 1835 | builtin: complex |
| 1836 | builtin: int |
| 1837 | builtin: long |
| 1838 | builtin: float |
| 1839 | |
| 1840 | Called to implement the built-in functions :func:`complex`, :func:`int`, |
| 1841 | :func:`long`, and :func:`float`. Should return a value of the appropriate type. |
| 1842 | |
| 1843 | |
| 1844 | .. method:: object.__index__(self) |
| 1845 | |
| 1846 | Called to implement :func:`operator.index`. Also called whenever Python needs |
| 1847 | an integer object (such as in slicing, or in the built-in :func:`bin`, |
| 1848 | :func:`hex` and :func:`oct` functions). Must return an integer (int or long). |
| 1849 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1850 | |
| 1851 | .. _context-managers: |
| 1852 | |
| 1853 | With Statement Context Managers |
| 1854 | ------------------------------- |
| 1855 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1856 | A :dfn:`context manager` is an object that defines the runtime context to be |
| 1857 | established when executing a :keyword:`with` statement. The context manager |
| 1858 | handles the entry into, and the exit from, the desired runtime context for the |
| 1859 | execution of the block of code. Context managers are normally invoked using the |
| 1860 | :keyword:`with` statement (described in section :ref:`with`), but can also be |
| 1861 | used by directly invoking their methods. |
| 1862 | |
| 1863 | .. index:: |
| 1864 | statement: with |
| 1865 | single: context manager |
| 1866 | |
| 1867 | Typical uses of context managers include saving and restoring various kinds of |
| 1868 | global state, locking and unlocking resources, closing opened files, etc. |
| 1869 | |
| 1870 | For more information on context managers, see :ref:`typecontextmanager`. |
| 1871 | |
| 1872 | |
| 1873 | .. method:: object.__enter__(self) |
| 1874 | |
| 1875 | Enter the runtime context related to this object. The :keyword:`with` statement |
| 1876 | will bind this method's return value to the target(s) specified in the |
| 1877 | :keyword:`as` clause of the statement, if any. |
| 1878 | |
| 1879 | |
| 1880 | .. method:: object.__exit__(self, exc_type, exc_value, traceback) |
| 1881 | |
| 1882 | Exit the runtime context related to this object. The parameters describe the |
| 1883 | exception that caused the context to be exited. If the context was exited |
| 1884 | without an exception, all three arguments will be :const:`None`. |
| 1885 | |
| 1886 | If an exception is supplied, and the method wishes to suppress the exception |
| 1887 | (i.e., prevent it from being propagated), it should return a true value. |
| 1888 | Otherwise, the exception will be processed normally upon exit from this method. |
| 1889 | |
| 1890 | Note that :meth:`__exit__` methods should not reraise the passed-in exception; |
| 1891 | this is the caller's responsibility. |
| 1892 | |
| 1893 | |
| 1894 | .. seealso:: |
| 1895 | |
| 1896 | :pep:`0343` - The "with" statement |
| 1897 | The specification, background, and examples for the Python :keyword:`with` |
| 1898 | statement. |
| 1899 | |
| 1900 | .. rubric:: Footnotes |
| 1901 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 1902 | .. [#] A descriptor can define any combination of :meth:`__get__`, |
| 1903 | :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`, |
| 1904 | then accessing the attribute even on an instance will return the descriptor |
| 1905 | object itself. If the descriptor defines :meth:`__set__` and/or |
| 1906 | :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a |
| 1907 | non-data descriptor. |
| 1908 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1909 | .. [#] For operands of the same type, it is assumed that if the non-reflected method |
| 1910 | (such as :meth:`__add__`) fails the operation is not supported, which is why the |
| 1911 | reflected method is not called. |
| 1912 | |