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