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