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