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