blob: 4bad2d536ead4afc0b914d83e0e23248ad55726f [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 Brandl495f7b52009-10-27 15:28:25 +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.
Gregory P. Smithc5425472011-03-10 11:28:50 -080072 Do not depend on immediate finalization of objects when they become
73 unreachable (ex: always close files).
Georg Brandl116aa622007-08-15 14:28:22 +000074
75Note that the use of the implementation's tracing or debugging facilities may
76keep objects alive that would normally be collectable. Also note that catching
77an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
78objects alive.
79
80Some objects contain references to "external" resources such as open files or
81windows. It is understood that these resources are freed when the object is
82garbage-collected, but since garbage collection is not guaranteed to happen,
83such objects also provide an explicit way to release the external resource,
84usually a :meth:`close` method. Programs are strongly recommended to explicitly
85close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
Nick Coghlan3a5d7e32008-08-31 12:40:14 +000086and the ':keyword:`with`' statement provide convenient ways to do this.
Georg Brandl116aa622007-08-15 14:28:22 +000087
88.. index:: single: container
89
90Some objects contain references to other objects; these are called *containers*.
91Examples of containers are tuples, lists and dictionaries. The references are
92part of a container's value. In most cases, when we talk about the value of a
93container, we imply the values, not the identities of the contained objects;
94however, when we talk about the mutability of a container, only the identities
95of the immediately contained objects are implied. So, if an immutable container
96(like a tuple) contains a reference to a mutable object, its value changes if
97that mutable object is changed.
98
99Types affect almost all aspects of object behavior. Even the importance of
100object identity is affected in some sense: for immutable types, operations that
101compute new values may actually return a reference to any existing object with
102the same type and value, while for mutable objects this is not allowed. E.g.,
103after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
104with the value one, depending on the implementation, but after ``c = []; d =
105[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
106created empty lists. (Note that ``c = d = []`` assigns the same object to both
107``c`` and ``d``.)
108
109
110.. _types:
111
112The standard type hierarchy
113===========================
114
115.. index::
116 single: type
117 pair: data; type
118 pair: type; hierarchy
119 pair: extension; module
120 pair: C; language
121
122Below is a list of the types that are built into Python. Extension modules
123(written in C, Java, or other languages, depending on the implementation) can
124define additional types. Future versions of Python may add types to the type
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000125hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.),
126although such additions will often be provided via the standard library instead.
Georg Brandl116aa622007-08-15 14:28:22 +0000127
128.. index::
129 single: attribute
130 pair: special; attribute
131 triple: generic; special; attribute
132
133Some of the type descriptions below contain a paragraph listing 'special
134attributes.' These are attributes that provide access to the implementation and
135are not intended for general use. Their definition may change in the future.
136
137None
138 .. index:: object: None
139
140 This type has a single value. There is a single object with this value. This
141 object is accessed through the built-in name ``None``. It is used to signify the
142 absence of a value in many situations, e.g., it is returned from functions that
143 don't explicitly return anything. Its truth value is false.
144
145NotImplemented
146 .. index:: object: NotImplemented
147
148 This type has a single value. There is a single object with this value. This
149 object is accessed through the built-in name ``NotImplemented``. Numeric methods
150 and rich comparison methods may return this value if they do not implement the
151 operation for the operands provided. (The interpreter will then try the
152 reflected operation, or some other fallback, depending on the operator.) Its
153 truth value is true.
154
155Ellipsis
156 .. index:: object: Ellipsis
157
158 This type has a single value. There is a single object with this value. This
159 object is accessed through the literal ``...`` or the built-in name
160 ``Ellipsis``. Its truth value is true.
161
Christian Heimes072c0f12008-01-03 23:01:04 +0000162:class:`numbers.Number`
Georg Brandl116aa622007-08-15 14:28:22 +0000163 .. index:: object: numeric
164
165 These are created by numeric literals and returned as results by arithmetic
166 operators and arithmetic built-in functions. Numeric objects are immutable;
167 once created their value never changes. Python numbers are of course strongly
168 related to mathematical numbers, but subject to the limitations of numerical
169 representation in computers.
170
171 Python distinguishes between integers, floating point numbers, and complex
172 numbers:
173
Christian Heimes072c0f12008-01-03 23:01:04 +0000174 :class:`numbers.Integral`
Georg Brandl116aa622007-08-15 14:28:22 +0000175 .. index:: object: integer
176
177 These represent elements from the mathematical set of integers (positive and
178 negative).
179
Georg Brandl59d69162008-01-07 09:27:36 +0000180 There are two types of integers:
Georg Brandl116aa622007-08-15 14:28:22 +0000181
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000182 Integers (:class:`int`)
Georg Brandl116aa622007-08-15 14:28:22 +0000183
Georg Brandl116aa622007-08-15 14:28:22 +0000184 These represent numbers in an unlimited range, subject to available (virtual)
185 memory only. For the purpose of shift and mask operations, a binary
186 representation is assumed, and negative numbers are represented in a variant of
187 2's complement which gives the illusion of an infinite string of sign bits
188 extending to the left.
189
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000190 Booleans (:class:`bool`)
Georg Brandl116aa622007-08-15 14:28:22 +0000191 .. index::
192 object: Boolean
193 single: False
194 single: True
195
196 These represent the truth values False and True. The two objects representing
197 the values False and True are the only Boolean objects. The Boolean type is a
Georg Brandl95817b32008-05-11 14:30:18 +0000198 subtype of the integer type, and Boolean values behave like the values 0 and 1,
Georg Brandl116aa622007-08-15 14:28:22 +0000199 respectively, in almost all contexts, the exception being that when converted to
200 a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
201
202 .. index:: pair: integer; representation
203
204 The rules for integer representation are intended to give the most meaningful
Georg Brandlbb74a782008-05-11 10:53:16 +0000205 interpretation of shift and mask operations involving negative integers.
Georg Brandl116aa622007-08-15 14:28:22 +0000206
Christian Heimes072c0f12008-01-03 23:01:04 +0000207 :class:`numbers.Real` (:class:`float`)
Georg Brandl116aa622007-08-15 14:28:22 +0000208 .. index::
209 object: floating point
210 pair: floating point; number
211 pair: C; language
212 pair: Java; language
213
214 These represent machine-level double precision floating point numbers. You are
215 at the mercy of the underlying machine architecture (and C or Java
216 implementation) for the accepted range and handling of overflow. Python does not
217 support single-precision floating point numbers; the savings in processor and
218 memory usage that are usually the reason for using these is dwarfed by the
219 overhead of using objects in Python, so there is no reason to complicate the
220 language with two kinds of floating point numbers.
221
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000222 :class:`numbers.Complex` (:class:`complex`)
Georg Brandl116aa622007-08-15 14:28:22 +0000223 .. index::
224 object: complex
225 pair: complex; number
226
227 These represent complex numbers as a pair of machine-level double precision
228 floating point numbers. The same caveats apply as for floating point numbers.
229 The real and imaginary parts of a complex number ``z`` can be retrieved through
230 the read-only attributes ``z.real`` and ``z.imag``.
231
Georg Brandl116aa622007-08-15 14:28:22 +0000232Sequences
233 .. index::
234 builtin: len
235 object: sequence
236 single: index operation
237 single: item selection
238 single: subscription
239
240 These represent finite ordered sets indexed by non-negative numbers. The
241 built-in function :func:`len` returns the number of items of a sequence. When
242 the length of a sequence is *n*, the index set contains the numbers 0, 1,
243 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
244
245 .. index:: single: slicing
246
247 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
248 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
249 sequence of the same type. This implies that the index set is renumbered so
250 that it starts at 0.
251
Georg Brandl116aa622007-08-15 14:28:22 +0000252 Some sequences also support "extended slicing" with a third "step" parameter:
253 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
254 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
255
256 Sequences are distinguished according to their mutability:
257
258 Immutable sequences
259 .. index::
260 object: immutable sequence
261 object: immutable
262
263 An object of an immutable sequence type cannot change once it is created. (If
264 the object contains references to other objects, these other objects may be
265 mutable and may be changed; however, the collection of objects directly
266 referenced by an immutable object cannot change.)
267
268 The following types are immutable sequences:
269
270 Strings
271 .. index::
272 builtin: chr
273 builtin: ord
Georg Brandldcc56f82007-08-31 16:41:12 +0000274 builtin: str
Georg Brandl116aa622007-08-15 14:28:22 +0000275 single: character
276 single: integer
277 single: Unicode
278
Georg Brandldcc56f82007-08-31 16:41:12 +0000279 The items of a string object are Unicode code units. A Unicode code
280 unit is represented by a string object of one item and can hold either
281 a 16-bit or 32-bit value representing a Unicode ordinal (the maximum
282 value for the ordinal is given in ``sys.maxunicode``, and depends on
283 how Python is configured at compile time). Surrogate pairs may be
284 present in the Unicode object, and will be reported as two separate
285 items. The built-in functions :func:`chr` and :func:`ord` convert
286 between code units and nonnegative integers representing the Unicode
287 ordinals as defined in the Unicode Standard 3.0. Conversion from and to
288 other encodings are possible through the string method :meth:`encode`.
Georg Brandl116aa622007-08-15 14:28:22 +0000289
290 Tuples
291 .. index::
292 object: tuple
293 pair: singleton; tuple
294 pair: empty; tuple
295
Georg Brandldcc56f82007-08-31 16:41:12 +0000296 The items of a tuple are arbitrary Python objects. Tuples of two or
297 more items are formed by comma-separated lists of expressions. A tuple
298 of one item (a 'singleton') can be formed by affixing a comma to an
299 expression (an expression by itself does not create a tuple, since
300 parentheses must be usable for grouping of expressions). An empty
301 tuple can be formed by an empty pair of parentheses.
Georg Brandl116aa622007-08-15 14:28:22 +0000302
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000303 Bytes
304 .. index:: bytes, byte
305
306 A bytes object is an immutable array. The items are 8-bit bytes,
307 represented by integers in the range 0 <= x < 256. Bytes literals
Andrew Svetlovf5320352012-10-02 18:39:25 +0300308 (like ``b'abc'``) and the built-in function :func:`bytes` can be used to
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000309 construct bytes objects. Also, bytes objects can be decoded to strings
310 via the :meth:`decode` method.
311
Georg Brandl116aa622007-08-15 14:28:22 +0000312 Mutable sequences
313 .. index::
314 object: mutable sequence
315 object: mutable
316 pair: assignment; statement
317 single: delete
318 statement: del
319 single: subscription
320 single: slicing
321
322 Mutable sequences can be changed after they are created. The subscription and
323 slicing notations can be used as the target of assignment and :keyword:`del`
324 (delete) statements.
325
Benjamin Petersonb58dda72009-01-18 22:27:04 +0000326 There are currently two intrinsic mutable sequence types:
Georg Brandl116aa622007-08-15 14:28:22 +0000327
328 Lists
329 .. index:: object: list
330
Georg Brandldcc56f82007-08-31 16:41:12 +0000331 The items of a list are arbitrary Python objects. Lists are formed by
332 placing a comma-separated list of expressions in square brackets. (Note
333 that there are no special cases needed to form lists of length 0 or 1.)
334
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000335 Byte Arrays
336 .. index:: bytearray
Georg Brandldcc56f82007-08-31 16:41:12 +0000337
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000338 A bytearray object is a mutable array. They are created by the built-in
339 :func:`bytearray` constructor. Aside from being mutable (and hence
340 unhashable), byte arrays otherwise provide the same interface and
341 functionality as immutable bytes objects.
Georg Brandl116aa622007-08-15 14:28:22 +0000342
343 .. index:: module: array
344
Georg Brandldcc56f82007-08-31 16:41:12 +0000345 The extension module :mod:`array` provides an additional example of a
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000346 mutable sequence type, as does the :mod:`collections` module.
Georg Brandl116aa622007-08-15 14:28:22 +0000347
Georg Brandl116aa622007-08-15 14:28:22 +0000348Set types
349 .. index::
350 builtin: len
351 object: set type
352
353 These represent unordered, finite sets of unique, immutable objects. As such,
354 they cannot be indexed by any subscript. However, they can be iterated over, and
355 the built-in function :func:`len` returns the number of items in a set. Common
356 uses for sets are fast membership testing, removing duplicates from a sequence,
357 and computing mathematical operations such as intersection, union, difference,
358 and symmetric difference.
359
360 For set elements, the same immutability rules apply as for dictionary keys. Note
361 that numeric types obey the normal rules for numeric comparison: if two numbers
362 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
363 set.
364
365 There are currently two intrinsic set types:
366
367 Sets
368 .. index:: object: set
369
370 These represent a mutable set. They are created by the built-in :func:`set`
371 constructor and can be modified afterwards by several methods, such as
372 :meth:`add`.
373
374 Frozen sets
375 .. index:: object: frozenset
376
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000377 These represent an immutable set. They are created by the built-in
378 :func:`frozenset` constructor. As a frozenset is immutable and
379 :term:`hashable`, it can be used again as an element of another set, or as
380 a dictionary key.
Georg Brandl116aa622007-08-15 14:28:22 +0000381
Georg Brandl116aa622007-08-15 14:28:22 +0000382Mappings
383 .. index::
384 builtin: len
385 single: subscription
386 object: mapping
387
388 These represent finite sets of objects indexed by arbitrary index sets. The
389 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
390 ``a``; this can be used in expressions and as the target of assignments or
391 :keyword:`del` statements. The built-in function :func:`len` returns the number
392 of items in a mapping.
393
394 There is currently a single intrinsic mapping type:
395
396 Dictionaries
397 .. index:: object: dictionary
398
399 These represent finite sets of objects indexed by nearly arbitrary values. The
400 only types of values not acceptable as keys are values containing lists or
401 dictionaries or other mutable types that are compared by value rather than by
402 object identity, the reason being that the efficient implementation of
403 dictionaries requires a key's hash value to remain constant. Numeric types used
404 for keys obey the normal rules for numeric comparison: if two numbers compare
405 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
406 the same dictionary entry.
407
408 Dictionaries are mutable; they can be created by the ``{...}`` notation (see
409 section :ref:`dict`).
410
411 .. index::
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000412 module: dbm.ndbm
413 module: dbm.gnu
Georg Brandl116aa622007-08-15 14:28:22 +0000414
Benjamin Peterson9a46cab2008-09-08 02:49:30 +0000415 The extension modules :mod:`dbm.ndbm` and :mod:`dbm.gnu` provide
416 additional examples of mapping types, as does the :mod:`collections`
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000417 module.
Georg Brandl116aa622007-08-15 14:28:22 +0000418
Georg Brandl116aa622007-08-15 14:28:22 +0000419Callable types
420 .. index::
421 object: callable
422 pair: function; call
423 single: invocation
424 pair: function; argument
425
426 These are the types to which the function call operation (see section
427 :ref:`calls`) can be applied:
428
429 User-defined functions
430 .. index::
431 pair: user-defined; function
432 object: function
433 object: user-defined function
434
435 A user-defined function object is created by a function definition (see
436 section :ref:`function`). It should be called with an argument list
437 containing the same number of items as the function's formal parameter
438 list.
439
440 Special attributes:
441
442 +-------------------------+-------------------------------+-----------+
443 | Attribute | Meaning | |
444 +=========================+===============================+===========+
445 | :attr:`__doc__` | The function's documentation | Writable |
446 | | string, or ``None`` if | |
447 | | unavailable | |
448 +-------------------------+-------------------------------+-----------+
449 | :attr:`__name__` | The function's name | Writable |
450 +-------------------------+-------------------------------+-----------+
451 | :attr:`__module__` | The name of the module the | Writable |
452 | | function was defined in, or | |
453 | | ``None`` if unavailable. | |
454 +-------------------------+-------------------------------+-----------+
455 | :attr:`__defaults__` | A tuple containing default | Writable |
456 | | argument values for those | |
457 | | arguments that have defaults, | |
458 | | or ``None`` if no arguments | |
459 | | have a default value | |
460 +-------------------------+-------------------------------+-----------+
461 | :attr:`__code__` | The code object representing | Writable |
462 | | the compiled function body. | |
463 +-------------------------+-------------------------------+-----------+
464 | :attr:`__globals__` | A reference to the dictionary | Read-only |
465 | | that holds the function's | |
466 | | global variables --- the | |
467 | | global namespace of the | |
468 | | module in which the function | |
469 | | was defined. | |
470 +-------------------------+-------------------------------+-----------+
471 | :attr:`__dict__` | The namespace supporting | Writable |
472 | | arbitrary function | |
473 | | attributes. | |
474 +-------------------------+-------------------------------+-----------+
475 | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
476 | | that contain bindings for the | |
477 | | function's free variables. | |
478 +-------------------------+-------------------------------+-----------+
479 | :attr:`__annotations__` | A dict containing annotations | Writable |
480 | | of parameters. The keys of | |
481 | | the dict are the parameter | |
482 | | names, or ``'return'`` for | |
483 | | the return annotation, if | |
484 | | provided. | |
485 +-------------------------+-------------------------------+-----------+
486 | :attr:`__kwdefaults__` | A dict containing defaults | Writable |
487 | | for keyword-only parameters. | |
488 +-------------------------+-------------------------------+-----------+
489
490 Most of the attributes labelled "Writable" check the type of the assigned value.
491
Georg Brandl116aa622007-08-15 14:28:22 +0000492 Function objects also support getting and setting arbitrary attributes, which
493 can be used, for example, to attach metadata to functions. Regular attribute
494 dot-notation is used to get and set such attributes. *Note that the current
495 implementation only supports function attributes on user-defined functions.
496 Function attributes on built-in functions may be supported in the future.*
497
498 Additional information about a function's definition can be retrieved from its
499 code object; see the description of internal types below.
500
501 .. index::
502 single: __doc__ (function attribute)
503 single: __name__ (function attribute)
504 single: __module__ (function attribute)
505 single: __dict__ (function attribute)
506 single: __defaults__ (function attribute)
507 single: __closure__ (function attribute)
508 single: __code__ (function attribute)
509 single: __globals__ (function attribute)
510 single: __annotations__ (function attribute)
511 single: __kwdefaults__ (function attribute)
512 pair: global; namespace
513
Georg Brandl2e0b7552007-11-27 12:43:08 +0000514 Instance methods
Georg Brandl116aa622007-08-15 14:28:22 +0000515 .. index::
516 object: method
517 object: user-defined method
518 pair: user-defined; method
519
Georg Brandl2e0b7552007-11-27 12:43:08 +0000520 An instance method object combines a class, a class instance and any
521 callable object (normally a user-defined function).
522
523 .. index::
524 single: __func__ (method attribute)
525 single: __self__ (method attribute)
526 single: __doc__ (method attribute)
527 single: __name__ (method attribute)
528 single: __module__ (method attribute)
Georg Brandl116aa622007-08-15 14:28:22 +0000529
Christian Heimesff737952007-11-27 10:40:20 +0000530 Special read-only attributes: :attr:`__self__` is the class instance object,
531 :attr:`__func__` is the function object; :attr:`__doc__` is the method's
532 documentation (same as ``__func__.__doc__``); :attr:`__name__` is the
533 method name (same as ``__func__.__name__``); :attr:`__module__` is the
534 name of the module the method was defined in, or ``None`` if unavailable.
Georg Brandl116aa622007-08-15 14:28:22 +0000535
Georg Brandl116aa622007-08-15 14:28:22 +0000536 Methods also support accessing (but not setting) the arbitrary function
537 attributes on the underlying function object.
538
Georg Brandl2e0b7552007-11-27 12:43:08 +0000539 User-defined method objects may be created when getting an attribute of a
540 class (perhaps via an instance of that class), if that attribute is a
541 user-defined function object or a class method object.
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000542
Georg Brandl2e0b7552007-11-27 12:43:08 +0000543 When an instance method object is created by retrieving a user-defined
544 function object from a class via one of its instances, its
545 :attr:`__self__` attribute is the instance, and the method object is said
546 to be bound. The new method's :attr:`__func__` attribute is the original
547 function object.
Georg Brandl116aa622007-08-15 14:28:22 +0000548
Georg Brandl2e0b7552007-11-27 12:43:08 +0000549 When a user-defined method object is created by retrieving another method
550 object from a class or instance, the behaviour is the same as for a
551 function object, except that the :attr:`__func__` attribute of the new
552 instance is not the original method object but its :attr:`__func__`
553 attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000554
Georg Brandl2e0b7552007-11-27 12:43:08 +0000555 When an instance method object is created by retrieving a class method
556 object from a class or instance, its :attr:`__self__` attribute is the
557 class itself, and its :attr:`__func__` attribute is the function object
558 underlying the class method.
Georg Brandl116aa622007-08-15 14:28:22 +0000559
Georg Brandl2e0b7552007-11-27 12:43:08 +0000560 When an instance method object is called, the underlying function
561 (:attr:`__func__`) is called, inserting the class instance
562 (:attr:`__self__`) in front of the argument list. For instance, when
563 :class:`C` is a class which contains a definition for a function
564 :meth:`f`, and ``x`` is an instance of :class:`C`, calling ``x.f(1)`` is
565 equivalent to calling ``C.f(x, 1)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000566
Georg Brandl2e0b7552007-11-27 12:43:08 +0000567 When an instance method object is derived from a class method object, the
568 "class instance" stored in :attr:`__self__` will actually be the class
569 itself, so that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to
570 calling ``f(C,1)`` where ``f`` is the underlying function.
Georg Brandl116aa622007-08-15 14:28:22 +0000571
Georg Brandl2e0b7552007-11-27 12:43:08 +0000572 Note that the transformation from function object to instance method
573 object happens each time the attribute is retrieved from the instance. In
574 some cases, a fruitful optimization is to assign the attribute to a local
575 variable and call that local variable. Also notice that this
576 transformation only happens for user-defined functions; other callable
577 objects (and all non-callable objects) are retrieved without
578 transformation. It is also important to note that user-defined functions
579 which are attributes of a class instance are not converted to bound
580 methods; this *only* happens when the function is an attribute of the
581 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000582
583 Generator functions
584 .. index::
585 single: generator; function
586 single: generator; iterator
587
588 A function or method which uses the :keyword:`yield` statement (see section
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000589 :ref:`yield`) is called a :dfn:`generator function`. Such a function, when
590 called, always returns an iterator object which can be used to execute the
Ezio Melotti7fa82222012-10-12 13:42:08 +0300591 body of the function: calling the iterator's :meth:`iterator__next__`
592 method will cause the function to execute until it provides a value
593 using the :keyword:`yield` statement. When the function executes a
Georg Brandl116aa622007-08-15 14:28:22 +0000594 :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
595 exception is raised and the iterator will have reached the end of the set of
596 values to be returned.
597
598 Built-in functions
599 .. index::
600 object: built-in function
601 object: function
602 pair: C; language
603
604 A built-in function object is a wrapper around a C function. Examples of
605 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
606 standard built-in module). The number and type of the arguments are
607 determined by the C function. Special read-only attributes:
608 :attr:`__doc__` is the function's documentation string, or ``None`` if
609 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
610 set to ``None`` (but see the next item); :attr:`__module__` is the name of
611 the module the function was defined in or ``None`` if unavailable.
612
613 Built-in methods
614 .. index::
615 object: built-in method
616 object: method
617 pair: built-in; method
618
619 This is really a different disguise of a built-in function, this time containing
620 an object passed to the C function as an implicit extra argument. An example of
621 a built-in method is ``alist.append()``, assuming *alist* is a list object. In
622 this case, the special read-only attribute :attr:`__self__` is set to the object
Éric Araujoc9562f32010-12-26 02:18:49 +0000623 denoted by *alist*.
Georg Brandl116aa622007-08-15 14:28:22 +0000624
Georg Brandl85eb8c12007-08-31 16:33:38 +0000625 Classes
626 Classes are callable. These objects normally act as factories for new
627 instances of themselves, but variations are possible for class types that
628 override :meth:`__new__`. The arguments of the call are passed to
629 :meth:`__new__` and, in the typical case, to :meth:`__init__` to
630 initialize the new instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000631
Georg Brandl85eb8c12007-08-31 16:33:38 +0000632 Class Instances
633 Instances of arbitrary classes can be made callable by defining a
634 :meth:`__call__` method in their class.
Georg Brandl116aa622007-08-15 14:28:22 +0000635
Georg Brandl116aa622007-08-15 14:28:22 +0000636
637Modules
638 .. index::
639 statement: import
640 object: module
641
642 Modules are imported by the :keyword:`import` statement (see section
643 :ref:`import`). A module object has a
644 namespace implemented by a dictionary object (this is the dictionary referenced
645 by the __globals__ attribute of functions defined in the module). Attribute
646 references are translated to lookups in this dictionary, e.g., ``m.x`` is
647 equivalent to ``m.__dict__["x"]``. A module object does not contain the code
648 object used to initialize the module (since it isn't needed once the
649 initialization is done).
650
Georg Brandl116aa622007-08-15 14:28:22 +0000651 Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
652 1`` is equivalent to ``m.__dict__["x"] = 1``.
653
654 .. index:: single: __dict__ (module attribute)
655
656 Special read-only attribute: :attr:`__dict__` is the module's namespace as a
657 dictionary object.
658
Benjamin Peterson5c4bfc42010-10-12 22:57:59 +0000659 .. impl-detail::
660
661 Because of the way CPython clears module dictionaries, the module
662 dictionary will be cleared when the module falls out of scope even if the
663 dictionary still has live references. To avoid this, copy the dictionary
664 or keep the module around while using its dictionary directly.
665
Georg Brandl116aa622007-08-15 14:28:22 +0000666 .. index::
667 single: __name__ (module attribute)
668 single: __doc__ (module attribute)
669 single: __file__ (module attribute)
670 pair: module; namespace
671
672 Predefined (writable) attributes: :attr:`__name__` is the module's name;
673 :attr:`__doc__` is the module's documentation string, or ``None`` if
674 unavailable; :attr:`__file__` is the pathname of the file from which the module
675 was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
676 present for C modules that are statically linked into the interpreter; for
677 extension modules loaded dynamically from a shared library, it is the pathname
678 of the shared library file.
679
Georg Brandl85eb8c12007-08-31 16:33:38 +0000680Custom classes
Georg Brandl5dbb84a2009-09-02 20:31:26 +0000681 Custom class types are typically created by class definitions (see section
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000682 :ref:`class`). A class has a namespace implemented by a dictionary object.
683 Class attribute references are translated to lookups in this dictionary, e.g.,
684 ``C.x`` is translated to ``C.__dict__["x"]`` (although there are a number of
685 hooks which allow for other means of locating attributes). When the attribute
686 name is not found there, the attribute search continues in the base classes.
687 This search of the base classes uses the C3 method resolution order which
688 behaves correctly even in the presence of 'diamond' inheritance structures
689 where there are multiple inheritance paths leading back to a common ancestor.
690 Additional details on the C3 MRO used by Python can be found in the
691 documentation accompanying the 2.3 release at
692 http://www.python.org/download/releases/2.3/mro/.
Georg Brandl116aa622007-08-15 14:28:22 +0000693
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000694 .. XXX: Could we add that MRO doc as an appendix to the language ref?
Georg Brandl85eb8c12007-08-31 16:33:38 +0000695
Georg Brandl116aa622007-08-15 14:28:22 +0000696 .. index::
697 object: class
698 object: class instance
699 object: instance
700 pair: class object; call
701 single: container
702 object: dictionary
703 pair: class; attribute
704
705 When a class attribute reference (for class :class:`C`, say) would yield a
Georg Brandl2e0b7552007-11-27 12:43:08 +0000706 class method object, it is transformed into an instance method object whose
707 :attr:`__self__` attributes is :class:`C`. When it would yield a static
708 method object, it is transformed into the object wrapped by the static method
709 object. See section :ref:`descriptors` for another way in which attributes
710 retrieved from a class may differ from those actually contained in its
711 :attr:`__dict__`.
Georg Brandl116aa622007-08-15 14:28:22 +0000712
713 .. index:: triple: class; attribute; assignment
714
715 Class attribute assignments update the class's dictionary, never the dictionary
716 of a base class.
717
718 .. index:: pair: class object; call
719
720 A class object can be called (see above) to yield a class instance (see below).
721
722 .. index::
723 single: __name__ (class attribute)
724 single: __module__ (class attribute)
725 single: __dict__ (class attribute)
726 single: __bases__ (class attribute)
727 single: __doc__ (class attribute)
728
729 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
730 the module name in which the class was defined; :attr:`__dict__` is the
731 dictionary containing the class's namespace; :attr:`__bases__` is a tuple
732 (possibly empty or a singleton) containing the base classes, in the order of
733 their occurrence in the base class list; :attr:`__doc__` is the class's
734 documentation string, or None if undefined.
735
736Class instances
737 .. index::
738 object: class instance
739 object: instance
740 pair: class; instance
741 pair: class instance; attribute
742
Georg Brandl2e0b7552007-11-27 12:43:08 +0000743 A class instance is created by calling a class object (see above). A class
744 instance has a namespace implemented as a dictionary which is the first place
745 in which attribute references are searched. When an attribute is not found
746 there, and the instance's class has an attribute by that name, the search
747 continues with the class attributes. If a class attribute is found that is a
748 user-defined function object, it is transformed into an instance method
749 object whose :attr:`__self__` attribute is the instance. Static method and
750 class method objects are also transformed; see above under "Classes". See
751 section :ref:`descriptors` for another way in which attributes of a class
752 retrieved via its instances may differ from the objects actually stored in
753 the class's :attr:`__dict__`. If no class attribute is found, and the
754 object's class has a :meth:`__getattr__` method, that is called to satisfy
755 the lookup.
Georg Brandl116aa622007-08-15 14:28:22 +0000756
757 .. index:: triple: class instance; attribute; assignment
758
759 Attribute assignments and deletions update the instance's dictionary, never a
760 class's dictionary. If the class has a :meth:`__setattr__` or
761 :meth:`__delattr__` method, this is called instead of updating the instance
762 dictionary directly.
763
764 .. index::
765 object: numeric
766 object: sequence
767 object: mapping
768
769 Class instances can pretend to be numbers, sequences, or mappings if they have
770 methods with certain special names. See section :ref:`specialnames`.
771
772 .. index::
773 single: __dict__ (instance attribute)
774 single: __class__ (instance attribute)
775
776 Special attributes: :attr:`__dict__` is the attribute dictionary;
777 :attr:`__class__` is the instance's class.
778
Antoine Pitrou4adb2882010-01-04 18:50:53 +0000779I/O objects (also known as file objects)
Georg Brandl116aa622007-08-15 14:28:22 +0000780 .. index::
Georg Brandl116aa622007-08-15 14:28:22 +0000781 builtin: open
Antoine Pitrou4adb2882010-01-04 18:50:53 +0000782 module: io
Georg Brandl116aa622007-08-15 14:28:22 +0000783 single: popen() (in module os)
784 single: makefile() (socket method)
785 single: sys.stdin
786 single: sys.stdout
787 single: sys.stderr
788 single: stdio
789 single: stdin (in module sys)
790 single: stdout (in module sys)
791 single: stderr (in module sys)
792
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000793 A :term:`file object` represents an open file. Various shortcuts are
794 available to create file objects: the :func:`open` built-in function, and
795 also :func:`os.popen`, :func:`os.fdopen`, and the :meth:`makefile` method
Antoine Pitrou4adb2882010-01-04 18:50:53 +0000796 of socket objects (and perhaps by other functions or methods provided
797 by extension modules).
798
799 The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are
800 initialized to file objects corresponding to the interpreter's standard
801 input, output and error streams; they are all open in text mode and
802 therefore follow the interface defined by the :class:`io.TextIOBase`
803 abstract class.
Georg Brandl116aa622007-08-15 14:28:22 +0000804
805Internal types
806 .. index::
807 single: internal type
808 single: types, internal
809
810 A few types used internally by the interpreter are exposed to the user. Their
811 definitions may change with future versions of the interpreter, but they are
812 mentioned here for completeness.
813
814 Code objects
815 .. index::
816 single: bytecode
817 object: code
818
Georg Brandl9afde1c2007-11-01 20:32:30 +0000819 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
Georg Brandl116aa622007-08-15 14:28:22 +0000820 The difference between a code object and a function object is that the function
821 object contains an explicit reference to the function's globals (the module in
822 which it was defined), while a code object contains no context; also the default
823 argument values are stored in the function object, not in the code object
824 (because they represent values calculated at run-time). Unlike function
825 objects, code objects are immutable and contain no references (directly or
826 indirectly) to mutable objects.
827
Senthil Kumaran7cafd262010-10-02 03:16:04 +0000828 .. index::
829 single: co_argcount (code object attribute)
830 single: co_code (code object attribute)
831 single: co_consts (code object attribute)
832 single: co_filename (code object attribute)
833 single: co_firstlineno (code object attribute)
834 single: co_flags (code object attribute)
835 single: co_lnotab (code object attribute)
836 single: co_name (code object attribute)
837 single: co_names (code object attribute)
838 single: co_nlocals (code object attribute)
839 single: co_stacksize (code object attribute)
840 single: co_varnames (code object attribute)
841 single: co_cellvars (code object attribute)
842 single: co_freevars (code object attribute)
843
Georg Brandl116aa622007-08-15 14:28:22 +0000844 Special read-only attributes: :attr:`co_name` gives the function name;
845 :attr:`co_argcount` is the number of positional arguments (including arguments
846 with default values); :attr:`co_nlocals` is the number of local variables used
847 by the function (including arguments); :attr:`co_varnames` is a tuple containing
848 the names of the local variables (starting with the argument names);
849 :attr:`co_cellvars` is a tuple containing the names of local variables that are
850 referenced by nested functions; :attr:`co_freevars` is a tuple containing the
851 names of free variables; :attr:`co_code` is a string representing the sequence
852 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
853 used by the bytecode; :attr:`co_names` is a tuple containing the names used by
854 the bytecode; :attr:`co_filename` is the filename from which the code was
855 compiled; :attr:`co_firstlineno` is the first line number of the function;
Georg Brandl9afde1c2007-11-01 20:32:30 +0000856 :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to
Georg Brandl116aa622007-08-15 14:28:22 +0000857 line numbers (for details see the source code of the interpreter);
858 :attr:`co_stacksize` is the required stack size (including local variables);
859 :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
860
Georg Brandl116aa622007-08-15 14:28:22 +0000861 .. index:: object: generator
862
863 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
864 the function uses the ``*arguments`` syntax to accept an arbitrary number of
865 positional arguments; bit ``0x08`` is set if the function uses the
866 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
867 if the function is a generator.
868
869 Future feature declarations (``from __future__ import division``) also use bits
870 in :attr:`co_flags` to indicate whether a code object was compiled with a
871 particular feature enabled: bit ``0x2000`` is set if the function was compiled
872 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
873 versions of Python.
874
875 Other bits in :attr:`co_flags` are reserved for internal use.
876
877 .. index:: single: documentation string
878
879 If a code object represents a function, the first item in :attr:`co_consts` is
880 the documentation string of the function, or ``None`` if undefined.
881
Georg Brandla6053b42009-09-01 08:11:14 +0000882 .. _frame-objects:
883
Georg Brandl116aa622007-08-15 14:28:22 +0000884 Frame objects
885 .. index:: object: frame
886
887 Frame objects represent execution frames. They may occur in traceback objects
888 (see below).
889
890 .. index::
891 single: f_back (frame attribute)
892 single: f_code (frame attribute)
893 single: f_globals (frame attribute)
894 single: f_locals (frame attribute)
895 single: f_lasti (frame attribute)
896 single: f_builtins (frame attribute)
897
898 Special read-only attributes: :attr:`f_back` is to the previous stack frame
899 (towards the caller), or ``None`` if this is the bottom stack frame;
900 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
901 is the dictionary used to look up local variables; :attr:`f_globals` is used for
902 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
903 :attr:`f_lasti` gives the precise instruction (this is an index into the
904 bytecode string of the code object).
905
906 .. index::
907 single: f_trace (frame attribute)
Georg Brandl116aa622007-08-15 14:28:22 +0000908 single: f_lineno (frame attribute)
909
910 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
911 called at the start of each source code line (this is used by the debugger);
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000912 :attr:`f_lineno` is the current line number of the frame --- writing to this
913 from within a trace function jumps to the given line (only for the bottom-most
914 frame). A debugger can implement a Jump command (aka Set Next Statement)
915 by writing to f_lineno.
Georg Brandl116aa622007-08-15 14:28:22 +0000916
917 Traceback objects
918 .. index::
919 object: traceback
920 pair: stack; trace
921 pair: exception; handler
922 pair: execution; stack
923 single: exc_info (in module sys)
Georg Brandl116aa622007-08-15 14:28:22 +0000924 single: last_traceback (in module sys)
925 single: sys.exc_info
926 single: sys.last_traceback
927
928 Traceback objects represent a stack trace of an exception. A traceback object
929 is created when an exception occurs. When the search for an exception handler
930 unwinds the execution stack, at each unwound level a traceback object is
931 inserted in front of the current traceback. When an exception handler is
932 entered, the stack trace is made available to the program. (See section
933 :ref:`try`.) It is accessible as the third item of the
934 tuple returned by ``sys.exc_info()``. When the program contains no suitable
935 handler, the stack trace is written (nicely formatted) to the standard error
936 stream; if the interpreter is interactive, it is also made available to the user
937 as ``sys.last_traceback``.
938
939 .. index::
940 single: tb_next (traceback attribute)
941 single: tb_frame (traceback attribute)
942 single: tb_lineno (traceback attribute)
943 single: tb_lasti (traceback attribute)
944 statement: try
945
946 Special read-only attributes: :attr:`tb_next` is the next level in the stack
947 trace (towards the frame where the exception occurred), or ``None`` if there is
948 no next level; :attr:`tb_frame` points to the execution frame of the current
949 level; :attr:`tb_lineno` gives the line number where the exception occurred;
950 :attr:`tb_lasti` indicates the precise instruction. The line number and last
951 instruction in the traceback may differ from the line number of its frame object
952 if the exception occurred in a :keyword:`try` statement with no matching except
953 clause or with a finally clause.
954
955 Slice objects
956 .. index:: builtin: slice
957
Georg Brandlcb8ecb12007-09-04 06:35:14 +0000958 Slice objects are used to represent slices for :meth:`__getitem__`
959 methods. They are also created by the built-in :func:`slice` function.
Georg Brandl116aa622007-08-15 14:28:22 +0000960
961 .. index::
962 single: start (slice object attribute)
963 single: stop (slice object attribute)
964 single: step (slice object attribute)
965
966 Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is
967 the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.
968 These attributes can have any type.
969
970 Slice objects support one method:
971
Georg Brandl116aa622007-08-15 14:28:22 +0000972 .. method:: slice.indices(self, length)
973
Georg Brandlcb8ecb12007-09-04 06:35:14 +0000974 This method takes a single integer argument *length* and computes
975 information about the slice that the slice object would describe if
976 applied to a sequence of *length* items. It returns a tuple of three
977 integers; respectively these are the *start* and *stop* indices and the
978 *step* or stride length of the slice. Missing or out-of-bounds indices
979 are handled in a manner consistent with regular slices.
Georg Brandl116aa622007-08-15 14:28:22 +0000980
Georg Brandl116aa622007-08-15 14:28:22 +0000981 Static method objects
982 Static method objects provide a way of defeating the transformation of function
983 objects to method objects described above. A static method object is a wrapper
984 around any other object, usually a user-defined method object. When a static
985 method object is retrieved from a class or a class instance, the object actually
986 returned is the wrapped object, which is not subject to any further
987 transformation. Static method objects are not themselves callable, although the
988 objects they wrap usually are. Static method objects are created by the built-in
989 :func:`staticmethod` constructor.
990
991 Class method objects
992 A class method object, like a static method object, is a wrapper around another
993 object that alters the way in which that object is retrieved from classes and
994 class instances. The behaviour of class method objects upon such retrieval is
995 described above, under "User-defined methods". Class method objects are created
996 by the built-in :func:`classmethod` constructor.
997
Georg Brandl116aa622007-08-15 14:28:22 +0000998
Georg Brandl116aa622007-08-15 14:28:22 +0000999.. _specialnames:
1000
1001Special method names
1002====================
1003
1004.. index::
1005 pair: operator; overloading
1006 single: __getitem__() (mapping object method)
1007
1008A class can implement certain operations that are invoked by special syntax
1009(such as arithmetic operations or subscripting and slicing) by defining methods
1010with special names. This is Python's approach to :dfn:`operator overloading`,
1011allowing classes to define their own behavior with respect to language
1012operators. For instance, if a class defines a method named :meth:`__getitem__`,
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001013and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
1014to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an
1015operation raise an exception when no appropriate method is defined (typically
1016:exc:`AttributeError` or :exc:`TypeError`).
Georg Brandl65ea9bd2007-09-05 13:36:27 +00001017
Georg Brandl116aa622007-08-15 14:28:22 +00001018When implementing a class that emulates any built-in type, it is important that
1019the emulation only be implemented to the degree that it makes sense for the
1020object being modelled. For example, some sequences may work well with retrieval
1021of individual elements, but extracting a slice may not make sense. (One example
1022of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
1023
1024
1025.. _customization:
1026
1027Basic customization
1028-------------------
1029
Georg Brandl116aa622007-08-15 14:28:22 +00001030.. method:: object.__new__(cls[, ...])
1031
Georg Brandlaf265f42008-12-07 15:06:20 +00001032 .. index:: pair: subclassing; immutable types
1033
Georg Brandl116aa622007-08-15 14:28:22 +00001034 Called to create a new instance of class *cls*. :meth:`__new__` is a static
1035 method (special-cased so you need not declare it as such) that takes the class
1036 of which an instance was requested as its first argument. The remaining
1037 arguments are those passed to the object constructor expression (the call to the
1038 class). The return value of :meth:`__new__` should be the new object instance
1039 (usually an instance of *cls*).
1040
1041 Typical implementations create a new instance of the class by invoking the
1042 superclass's :meth:`__new__` method using ``super(currentclass,
1043 cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
1044 newly-created instance as necessary before returning it.
1045
1046 If :meth:`__new__` returns an instance of *cls*, then the new instance's
1047 :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
1048 *self* is the new instance and the remaining arguments are the same as were
1049 passed to :meth:`__new__`.
1050
1051 If :meth:`__new__` does not return an instance of *cls*, then the new instance's
1052 :meth:`__init__` method will not be invoked.
1053
1054 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
Christian Heimes790c8232008-01-07 21:14:23 +00001055 int, str, or tuple) to customize instance creation. It is also commonly
1056 overridden in custom metaclasses in order to customize class creation.
Georg Brandl116aa622007-08-15 14:28:22 +00001057
1058
1059.. method:: object.__init__(self[, ...])
1060
1061 .. index:: pair: class; constructor
1062
1063 Called when the instance is created. The arguments are those passed to the
1064 class constructor expression. If a base class has an :meth:`__init__` method,
1065 the derived class's :meth:`__init__` method, if any, must explicitly call it to
1066 ensure proper initialization of the base class part of the instance; for
1067 example: ``BaseClass.__init__(self, [args...])``. As a special constraint on
1068 constructors, no value may be returned; doing so will cause a :exc:`TypeError`
1069 to be raised at runtime.
1070
1071
1072.. method:: object.__del__(self)
1073
1074 .. index::
1075 single: destructor
1076 statement: del
1077
1078 Called when the instance is about to be destroyed. This is also called a
1079 destructor. If a base class has a :meth:`__del__` method, the derived class's
1080 :meth:`__del__` method, if any, must explicitly call it to ensure proper
1081 deletion of the base class part of the instance. Note that it is possible
1082 (though not recommended!) for the :meth:`__del__` method to postpone destruction
1083 of the instance by creating a new reference to it. It may then be called at a
1084 later time when this new reference is deleted. It is not guaranteed that
1085 :meth:`__del__` methods are called for objects that still exist when the
1086 interpreter exits.
1087
1088 .. note::
1089
1090 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
1091 the reference count for ``x`` by one, and the latter is only called when
1092 ``x``'s reference count reaches zero. Some common situations that may
1093 prevent the reference count of an object from going to zero include:
1094 circular references between objects (e.g., a doubly-linked list or a tree
1095 data structure with parent and child pointers); a reference to the object
1096 on the stack frame of a function that caught an exception (the traceback
1097 stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a
1098 reference to the object on the stack frame that raised an unhandled
1099 exception in interactive mode (the traceback stored in
1100 ``sys.last_traceback`` keeps the stack frame alive). The first situation
1101 can only be remedied by explicitly breaking the cycles; the latter two
1102 situations can be resolved by storing ``None`` in ``sys.last_traceback``.
1103 Circular references which are garbage are detected when the option cycle
1104 detector is enabled (it's on by default), but can only be cleaned up if
1105 there are no Python- level :meth:`__del__` methods involved. Refer to the
1106 documentation for the :mod:`gc` module for more information about how
1107 :meth:`__del__` methods are handled by the cycle detector, particularly
1108 the description of the ``garbage`` value.
1109
1110 .. warning::
1111
1112 Due to the precarious circumstances under which :meth:`__del__` methods are
1113 invoked, exceptions that occur during their execution are ignored, and a warning
1114 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
1115 response to a module being deleted (e.g., when execution of the program is
1116 done), other globals referenced by the :meth:`__del__` method may already have
Brett Cannone1327f72009-01-29 04:10:21 +00001117 been deleted or in the process of being torn down (e.g. the import
1118 machinery shutting down). For this reason, :meth:`__del__` methods
1119 should do the absolute
Georg Brandl116aa622007-08-15 14:28:22 +00001120 minimum needed to maintain external invariants. Starting with version 1.5,
1121 Python guarantees that globals whose name begins with a single underscore are
1122 deleted from their module before other globals are deleted; if no other
1123 references to such globals exist, this may help in assuring that imported
1124 modules are still available at the time when the :meth:`__del__` method is
1125 called.
1126
Chris Jerdonek17fc44c2012-11-20 17:31:02 -08001127 .. index::
1128 single: repr() (built-in function); __repr__() (object method)
1129
Georg Brandl116aa622007-08-15 14:28:22 +00001130
1131.. method:: object.__repr__(self)
1132
Benjamin Peterson1c9313f2008-10-12 12:51:12 +00001133 Called by the :func:`repr` built-in function to compute the "official" string
1134 representation of an object. If at all possible, this should look like a
1135 valid Python expression that could be used to recreate an object with the
1136 same value (given an appropriate environment). If this is not possible, a
1137 string of the form ``<...some useful description...>`` should be returned.
1138 The return value must be a string object. If a class defines :meth:`__repr__`
1139 but not :meth:`__str__`, then :meth:`__repr__` is also used when an
1140 "informal" string representation of instances of that class is required.
Georg Brandl116aa622007-08-15 14:28:22 +00001141
Georg Brandl116aa622007-08-15 14:28:22 +00001142 This is typically used for debugging, so it is important that the representation
1143 is information-rich and unambiguous.
1144
Chris Jerdonek17fc44c2012-11-20 17:31:02 -08001145 .. index::
1146 single: string; __str__() (object method)
1147 single: format() (built-in function); __str__() (object method)
1148 single: print() (built-in function); __str__() (object method)
1149
Georg Brandl116aa622007-08-15 14:28:22 +00001150
1151.. method:: object.__str__(self)
1152
Chris Jerdonek17fc44c2012-11-20 17:31:02 -08001153 Called by :func:`str(object) <str>` and the built-in functions
1154 :func:`format` and :func:`print` to compute the "informal" or nicely
1155 printable string representation of an object. The return value must be a
Chris Jerdonek777db2d2012-11-21 05:32:44 -08001156 :ref:`string <typesseq>` object.
Georg Brandl116aa622007-08-15 14:28:22 +00001157
Chris Jerdonek17fc44c2012-11-20 17:31:02 -08001158 This method differs from :meth:`object.__repr__` in that there is no
1159 expectation that :meth:`__str__` return a valid Python expression: a more
1160 convenient or concise representation can be used.
1161
1162 The default implementation defined by the built-in type :class:`object`
1163 calls :meth:`object.__repr__`.
Georg Brandl116aa622007-08-15 14:28:22 +00001164
Georg Brandldcc56f82007-08-31 16:41:12 +00001165 .. XXX what about subclasses of string?
1166
Georg Brandl116aa622007-08-15 14:28:22 +00001167
Benjamin Peterson1fafc1a2011-10-25 00:03:51 -04001168.. method:: object.__bytes__(self)
1169
1170 .. index:: builtin: bytes
1171
1172 Called by :func:`bytes` to compute a byte-string representation of an
1173 object. This should return a ``bytes`` object.
1174
1175
Georg Brandl4b491312007-08-31 09:22:56 +00001176.. method:: object.__format__(self, format_spec)
1177
1178 .. index::
1179 pair: string; conversion
1180 builtin: str
1181 builtin: print
1182
1183 Called by the :func:`format` built-in function (and by extension, the
Chris Jerdonekaf947242012-10-11 18:47:54 -07001184 :meth:`str.format` method of class :class:`str`) to produce a "formatted"
Georg Brandl4b491312007-08-31 09:22:56 +00001185 string representation of an object. The ``format_spec`` argument is
1186 a string that contains a description of the formatting options desired.
1187 The interpretation of the ``format_spec`` argument is up to the type
1188 implementing :meth:`__format__`, however most classes will either
1189 delegate formatting to one of the built-in types, or use a similar
1190 formatting option syntax.
Georg Brandl48310cd2009-01-03 21:18:54 +00001191
Georg Brandl4b491312007-08-31 09:22:56 +00001192 See :ref:`formatspec` for a description of the standard formatting syntax.
1193
1194 The return value must be a string object.
1195
1196
Georg Brandl33413cb2009-03-31 19:06:37 +00001197.. _richcmpfuncs:
Georg Brandl116aa622007-08-15 14:28:22 +00001198.. method:: object.__lt__(self, other)
1199 object.__le__(self, other)
1200 object.__eq__(self, other)
1201 object.__ne__(self, other)
1202 object.__gt__(self, other)
1203 object.__ge__(self, other)
1204
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001205 .. index::
1206 single: comparisons
1207
Georg Brandl05f5ab72008-09-24 09:11:47 +00001208 These are the so-called "rich comparison" methods. The correspondence between
Georg Brandl116aa622007-08-15 14:28:22 +00001209 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
1210 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls
1211 ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
1212 ``x.__ge__(y)``.
1213
1214 A rich comparison method may return the singleton ``NotImplemented`` if it does
1215 not implement the operation for a given pair of arguments. By convention,
1216 ``False`` and ``True`` are returned for a successful comparison. However, these
1217 methods can return any value, so if the comparison operator is used in a Boolean
1218 context (e.g., in the condition of an ``if`` statement), Python will call
1219 :func:`bool` on the value to determine if the result is true or false.
1220
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001221 There are no implied relationships among the comparison operators. The truth
1222 of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when
1223 defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
1224 operators will behave as expected. See the paragraph on :meth:`__hash__` for
1225 some important notes on creating :term:`hashable` objects which support
1226 custom comparison operations and are usable as dictionary keys.
Georg Brandl116aa622007-08-15 14:28:22 +00001227
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001228 There are no swapped-argument versions of these methods (to be used when the
1229 left argument does not support the operation but the right argument does);
1230 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
Georg Brandl116aa622007-08-15 14:28:22 +00001231 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
1232 :meth:`__eq__` and :meth:`__ne__` are their own reflection.
1233
1234 Arguments to rich comparison methods are never coerced.
1235
Raymond Hettinger6c4b4b22009-03-12 00:25:29 +00001236 To automatically generate ordering operations from a single root operation,
Raymond Hettingerc50846a2010-04-05 18:56:31 +00001237 see :func:`functools.total_ordering`.
Georg Brandl116aa622007-08-15 14:28:22 +00001238
Georg Brandl116aa622007-08-15 14:28:22 +00001239.. method:: object.__hash__(self)
1240
1241 .. index::
1242 object: dictionary
1243 builtin: hash
1244
Benjamin Peterson6cadba72008-11-19 22:38:29 +00001245 Called by built-in function :func:`hash` and for operations on members of
1246 hashed collections including :class:`set`, :class:`frozenset`, and
1247 :class:`dict`. :meth:`__hash__` should return an integer. The only required
1248 property is that objects which compare equal have the same hash value; it is
1249 advised to somehow mix together (e.g. using exclusive or) the hash values for
1250 the components of the object that also play a part in comparison of objects.
Georg Brandl116aa622007-08-15 14:28:22 +00001251
Georg Brandl05f5ab72008-09-24 09:11:47 +00001252 If a class does not define an :meth:`__eq__` method it should not define a
1253 :meth:`__hash__` operation either; if it defines :meth:`__eq__` but not
Benjamin Peterson6cadba72008-11-19 22:38:29 +00001254 :meth:`__hash__`, its instances will not be usable as items in hashable
1255 collections. If a class defines mutable objects and implements an
1256 :meth:`__eq__` method, it should not implement :meth:`__hash__`, since the
1257 implementation of hashable collections requires that a key's hash value is
1258 immutable (if the object's hash value changes, it will be in the wrong hash
1259 bucket).
1260
Georg Brandldb629672007-11-03 08:44:43 +00001261
Georg Brandl05f5ab72008-09-24 09:11:47 +00001262 User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods
Nick Coghlan73c96db2008-08-31 13:21:24 +00001263 by default; with them, all objects compare unequal (except with themselves)
1264 and ``x.__hash__()`` returns ``id(x)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001265
R David Murrayd8bbde32012-09-11 13:01:43 -04001266 A class that overrides :meth:`__eq__` and does not define :meth:`__hash__`
1267 will have its :meth:`__hash__` implicitly set to ``None``. When the
1268 :meth:`__hash__` method of a class is ``None``, instances of the class will
1269 raise an appropriate :exc:`TypeError` when a program attempts to retrieve
1270 their hash value, and will also be correctly identified as unhashable when
1271 checking ``isinstance(obj, collections.Hashable``).
Nick Coghlan73c96db2008-08-31 13:21:24 +00001272
Georg Brandlae2dbe22009-03-13 19:04:40 +00001273 If a class that overrides :meth:`__eq__` needs to retain the implementation
Georg Brandl05f5ab72008-09-24 09:11:47 +00001274 of :meth:`__hash__` from a parent class, the interpreter must be told this
R David Murrayd8bbde32012-09-11 13:01:43 -04001275 explicitly by setting ``__hash__ = <ParentClass>.__hash__``.
1276
1277 If a class that does not override :meth:`__eq__` wishes to suppress hash
1278 support, it should include ``__hash__ = None`` in the class definition.
1279 A class which defines its own :meth:`__hash__` that explicitly raises
1280 a :exc:`TypeError` would be incorrectly identified as hashable by
1281 an ``isinstance(obj, collections.Hashable)`` call.
Georg Brandl05f5ab72008-09-24 09:11:47 +00001282
Georg Brandl2daf6ae2012-02-20 19:54:16 +01001283 See also the :option:`-R` command-line option.
1284
Georg Brandl116aa622007-08-15 14:28:22 +00001285
1286.. method:: object.__bool__(self)
Georg Brandl1aeaadd2008-09-06 17:42:52 +00001287
Georg Brandl116aa622007-08-15 14:28:22 +00001288 .. index:: single: __len__() (mapping object method)
1289
Benjamin Petersonf07d0022009-03-21 17:31:58 +00001290 Called to implement truth value testing and the built-in operation
Amaury Forgeot d'Arc097cd072009-07-07 00:43:08 +00001291 ``bool()``; should return ``False`` or ``True``. When this method is not
1292 defined, :meth:`__len__` is called, if it is defined, and the object is
1293 considered true if its result is nonzero. If a class defines neither
1294 :meth:`__len__` nor :meth:`__bool__`, all its instances are considered
1295 true.
Georg Brandl116aa622007-08-15 14:28:22 +00001296
1297
Georg Brandl116aa622007-08-15 14:28:22 +00001298.. _attribute-access:
1299
1300Customizing attribute access
1301----------------------------
1302
1303The following methods can be defined to customize the meaning of attribute
1304access (use of, assignment to, or deletion of ``x.name``) for class instances.
1305
Georg Brandl85eb8c12007-08-31 16:33:38 +00001306.. XXX explain how descriptors interfere here!
1307
Georg Brandl116aa622007-08-15 14:28:22 +00001308
1309.. method:: object.__getattr__(self, name)
1310
1311 Called when an attribute lookup has not found the attribute in the usual places
1312 (i.e. it is not an instance attribute nor is it found in the class tree for
1313 ``self``). ``name`` is the attribute name. This method should return the
1314 (computed) attribute value or raise an :exc:`AttributeError` exception.
1315
Georg Brandl116aa622007-08-15 14:28:22 +00001316 Note that if the attribute is found through the normal mechanism,
1317 :meth:`__getattr__` is not called. (This is an intentional asymmetry between
1318 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001319 reasons and because otherwise :meth:`__getattr__` would have no way to access
Georg Brandl116aa622007-08-15 14:28:22 +00001320 other attributes of the instance. Note that at least for instance variables,
1321 you can fake total control by not inserting any values in the instance attribute
1322 dictionary (but instead inserting them in another object). See the
Georg Brandl85eb8c12007-08-31 16:33:38 +00001323 :meth:`__getattribute__` method below for a way to actually get total control
1324 over attribute access.
Georg Brandl116aa622007-08-15 14:28:22 +00001325
1326
1327.. method:: object.__getattribute__(self, name)
1328
1329 Called unconditionally to implement attribute accesses for instances of the
1330 class. If the class also defines :meth:`__getattr__`, the latter will not be
1331 called unless :meth:`__getattribute__` either calls it explicitly or raises an
1332 :exc:`AttributeError`. This method should return the (computed) attribute value
1333 or raise an :exc:`AttributeError` exception. In order to avoid infinite
1334 recursion in this method, its implementation should always call the base class
1335 method with the same name to access any attributes it needs, for example,
1336 ``object.__getattribute__(self, name)``.
1337
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001338 .. note::
1339
1340 This method may still be bypassed when looking up special methods as the
Georg Brandl22b34312009-07-26 14:54:51 +00001341 result of implicit invocation via language syntax or built-in functions.
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001342 See :ref:`special-lookup`.
1343
Georg Brandl116aa622007-08-15 14:28:22 +00001344
Georg Brandl85eb8c12007-08-31 16:33:38 +00001345.. method:: object.__setattr__(self, name, value)
1346
1347 Called when an attribute assignment is attempted. This is called instead of
1348 the normal mechanism (i.e. store the value in the instance dictionary).
1349 *name* is the attribute name, *value* is the value to be assigned to it.
1350
1351 If :meth:`__setattr__` wants to assign to an instance attribute, it should
1352 call the base class method with the same name, for example,
1353 ``object.__setattr__(self, name, value)``.
1354
1355
1356.. method:: object.__delattr__(self, name)
1357
1358 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
1359 should only be implemented if ``del obj.name`` is meaningful for the object.
1360
1361
Benjamin Peterson1cef37c2008-07-02 14:44:54 +00001362.. method:: object.__dir__(self)
1363
1364 Called when :func:`dir` is called on the object. A list must be returned.
1365
1366
Georg Brandl116aa622007-08-15 14:28:22 +00001367.. _descriptors:
1368
1369Implementing Descriptors
1370^^^^^^^^^^^^^^^^^^^^^^^^
1371
1372The following methods only apply when an instance of the class containing the
Raymond Hettinger3b654be2011-03-22 16:27:02 -07001373method (a so-called *descriptor* class) appears in an *owner* class (the
1374descriptor must be in either the owner's class dictionary or in the class
1375dictionary for one of its parents). In the examples below, "the attribute"
1376refers to the attribute whose name is the key of the property in the owner
1377class' :attr:`__dict__`.
Georg Brandl116aa622007-08-15 14:28:22 +00001378
1379
1380.. method:: object.__get__(self, instance, owner)
1381
1382 Called to get the attribute of the owner class (class attribute access) or of an
1383 instance of that class (instance attribute access). *owner* is always the owner
1384 class, while *instance* is the instance that the attribute was accessed through,
1385 or ``None`` when the attribute is accessed through the *owner*. This method
1386 should return the (computed) attribute value or raise an :exc:`AttributeError`
1387 exception.
1388
1389
1390.. method:: object.__set__(self, instance, value)
1391
1392 Called to set the attribute on an instance *instance* of the owner class to a
1393 new value, *value*.
1394
1395
1396.. method:: object.__delete__(self, instance)
1397
1398 Called to delete the attribute on an instance *instance* of the owner class.
1399
1400
1401.. _descriptor-invocation:
1402
1403Invoking Descriptors
1404^^^^^^^^^^^^^^^^^^^^
1405
1406In general, a descriptor is an object attribute with "binding behavior", one
1407whose attribute access has been overridden by methods in the descriptor
1408protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
1409those methods are defined for an object, it is said to be a descriptor.
1410
1411The default behavior for attribute access is to get, set, or delete the
1412attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
1413starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
1414continuing through the base classes of ``type(a)`` excluding metaclasses.
1415
1416However, if the looked-up value is an object defining one of the descriptor
1417methods, then Python may override the default behavior and invoke the descriptor
1418method instead. Where this occurs in the precedence chain depends on which
Georg Brandl23e8db52008-04-07 19:17:06 +00001419descriptor methods were defined and how they were called.
Georg Brandl116aa622007-08-15 14:28:22 +00001420
1421The starting point for descriptor invocation is a binding, ``a.x``. How the
1422arguments are assembled depends on ``a``:
1423
1424Direct Call
1425 The simplest and least common call is when user code directly invokes a
1426 descriptor method: ``x.__get__(a)``.
1427
1428Instance Binding
Georg Brandl85eb8c12007-08-31 16:33:38 +00001429 If binding to an object instance, ``a.x`` is transformed into the call:
Georg Brandl116aa622007-08-15 14:28:22 +00001430 ``type(a).__dict__['x'].__get__(a, type(a))``.
1431
1432Class Binding
Georg Brandl85eb8c12007-08-31 16:33:38 +00001433 If binding to a class, ``A.x`` is transformed into the call:
Georg Brandl116aa622007-08-15 14:28:22 +00001434 ``A.__dict__['x'].__get__(None, A)``.
1435
1436Super Binding
1437 If ``a`` is an instance of :class:`super`, then the binding ``super(B,
1438 obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
1439 immediately preceding ``B`` and then invokes the descriptor with the call:
Raymond Hettingerb199b222011-03-22 15:28:45 -07001440 ``A.__dict__['m'].__get__(obj, obj.__class__)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001441
1442For instance bindings, the precedence of descriptor invocation depends on the
Benjamin Peterson5e55b3e2010-02-03 02:35:45 +00001443which descriptor methods are defined. A descriptor can define any combination
1444of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not
1445define :meth:`__get__`, then accessing the attribute will return the descriptor
1446object itself unless there is a value in the object's instance dictionary. If
1447the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data
1448descriptor; if it defines neither, it is a non-data descriptor. Normally, data
1449descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data
1450descriptors have just the :meth:`__get__` method. Data descriptors with
1451:meth:`__set__` and :meth:`__get__` defined always override a redefinition in an
Georg Brandl116aa622007-08-15 14:28:22 +00001452instance dictionary. In contrast, non-data descriptors can be overridden by
Benjamin Peterson5e55b3e2010-02-03 02:35:45 +00001453instances.
Georg Brandl116aa622007-08-15 14:28:22 +00001454
1455Python methods (including :func:`staticmethod` and :func:`classmethod`) are
1456implemented as non-data descriptors. Accordingly, instances can redefine and
1457override methods. This allows individual instances to acquire behaviors that
1458differ from other instances of the same class.
1459
1460The :func:`property` function is implemented as a data descriptor. Accordingly,
1461instances cannot override the behavior of a property.
1462
1463
1464.. _slots:
1465
1466__slots__
1467^^^^^^^^^
1468
Georg Brandl85eb8c12007-08-31 16:33:38 +00001469By default, instances of classes have a dictionary for attribute storage. This
1470wastes space for objects having very few instance variables. The space
1471consumption can become acute when creating large numbers of instances.
Georg Brandl116aa622007-08-15 14:28:22 +00001472
Georg Brandl85eb8c12007-08-31 16:33:38 +00001473The default can be overridden by defining *__slots__* in a class definition.
1474The *__slots__* declaration takes a sequence of instance variables and reserves
1475just enough space in each instance to hold a value for each variable. Space is
1476saved because *__dict__* is not created for each instance.
Georg Brandl116aa622007-08-15 14:28:22 +00001477
1478
Georg Brandl85eb8c12007-08-31 16:33:38 +00001479.. data:: object.__slots__
Georg Brandl116aa622007-08-15 14:28:22 +00001480
Georg Brandl85eb8c12007-08-31 16:33:38 +00001481 This class variable can be assigned a string, iterable, or sequence of
Georg Brandl23e8db52008-04-07 19:17:06 +00001482 strings with variable names used by instances. If defined in a
Georg Brandl85eb8c12007-08-31 16:33:38 +00001483 class, *__slots__* reserves space for the declared variables and prevents the
1484 automatic creation of *__dict__* and *__weakref__* for each instance.
Georg Brandl116aa622007-08-15 14:28:22 +00001485
Georg Brandl116aa622007-08-15 14:28:22 +00001486
1487Notes on using *__slots__*
Georg Brandl16174572007-09-01 12:38:06 +00001488""""""""""""""""""""""""""
Georg Brandl116aa622007-08-15 14:28:22 +00001489
Georg Brandl3dbca812008-07-23 16:10:53 +00001490* When inheriting from a class without *__slots__*, the *__dict__* attribute of
1491 that class will always be accessible, so a *__slots__* definition in the
1492 subclass is meaningless.
1493
Georg Brandl116aa622007-08-15 14:28:22 +00001494* Without a *__dict__* variable, instances cannot be assigned new variables not
1495 listed in the *__slots__* definition. Attempts to assign to an unlisted
1496 variable name raises :exc:`AttributeError`. If dynamic assignment of new
Georg Brandl85eb8c12007-08-31 16:33:38 +00001497 variables is desired, then add ``'__dict__'`` to the sequence of strings in
1498 the *__slots__* declaration.
Georg Brandl116aa622007-08-15 14:28:22 +00001499
Georg Brandl116aa622007-08-15 14:28:22 +00001500* Without a *__weakref__* variable for each instance, classes defining
1501 *__slots__* do not support weak references to its instances. If weak reference
1502 support is needed, then add ``'__weakref__'`` to the sequence of strings in the
1503 *__slots__* declaration.
1504
Georg Brandl116aa622007-08-15 14:28:22 +00001505* *__slots__* are implemented at the class level by creating descriptors
1506 (:ref:`descriptors`) for each variable name. As a result, class attributes
1507 cannot be used to set default values for instance variables defined by
1508 *__slots__*; otherwise, the class attribute would overwrite the descriptor
1509 assignment.
1510
Georg Brandl495f7b52009-10-27 15:28:25 +00001511* The action of a *__slots__* declaration is limited to the class where it is
1512 defined. As a result, subclasses will have a *__dict__* unless they also define
1513 *__slots__* (which must only contain names of any *additional* slots).
1514
Georg Brandl116aa622007-08-15 14:28:22 +00001515* If a class defines a slot also defined in a base class, the instance variable
1516 defined by the base class slot is inaccessible (except by retrieving its
1517 descriptor directly from the base class). This renders the meaning of the
1518 program undefined. In the future, a check may be added to prevent this.
1519
Benjamin Peterson1a6e0d02008-10-25 15:49:17 +00001520* Nonempty *__slots__* does not work for classes derived from "variable-length"
1521 built-in types such as :class:`int`, :class:`str` and :class:`tuple`.
Georg Brandl116aa622007-08-15 14:28:22 +00001522
1523* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
1524 used; however, in the future, special meaning may be assigned to the values
1525 corresponding to each key.
1526
1527* *__class__* assignment works only if both classes have the same *__slots__*.
1528
Georg Brandl116aa622007-08-15 14:28:22 +00001529
1530.. _metaclasses:
1531
1532Customizing class creation
1533--------------------------
1534
Georg Brandl85eb8c12007-08-31 16:33:38 +00001535By default, classes are constructed using :func:`type`. A class definition is
1536read into a separate namespace and the value of class name is bound to the
1537result of ``type(name, bases, dict)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001538
Benjamin Petersone348d1a2008-10-19 21:29:05 +00001539When the class definition is read, if a callable ``metaclass`` keyword argument
1540is passed after the bases in the class definition, the callable given will be
1541called instead of :func:`type`. If other keyword arguments are passed, they
1542will also be passed to the metaclass. This allows classes or functions to be
1543written which monitor or alter the class creation process:
Georg Brandl116aa622007-08-15 14:28:22 +00001544
1545* Modifying the class dictionary prior to the class being created.
1546
1547* Returning an instance of another class -- essentially performing the role of a
1548 factory function.
1549
Christian Heimes790c8232008-01-07 21:14:23 +00001550These steps will have to be performed in the metaclass's :meth:`__new__` method
1551-- :meth:`type.__new__` can then be called from this method to create a class
1552with different properties. This example adds a new element to the class
1553dictionary before creating the class::
1554
1555 class metacls(type):
1556 def __new__(mcs, name, bases, dict):
1557 dict['foo'] = 'metacls was here'
1558 return type.__new__(mcs, name, bases, dict)
1559
1560You can of course also override other class methods (or add new methods); for
1561example defining a custom :meth:`__call__` method in the metaclass allows custom
1562behavior when the class is called, e.g. not always creating a new instance.
1563
Benjamin Petersone348d1a2008-10-19 21:29:05 +00001564If the metaclass has a :meth:`__prepare__` attribute (usually implemented as a
1565class or static method), it is called before the class body is evaluated with
1566the name of the class and a tuple of its bases for arguments. It should return
1567an object that supports the mapping interface that will be used to store the
1568namespace of the class. The default is a plain dictionary. This could be used,
1569for example, to keep track of the order that class attributes are declared in by
1570returning an ordered dictionary.
Georg Brandl116aa622007-08-15 14:28:22 +00001571
Georg Brandl116aa622007-08-15 14:28:22 +00001572The appropriate metaclass is determined by the following precedence rules:
1573
Georg Brandlf43713f2009-10-22 16:08:10 +00001574* If the ``metaclass`` keyword argument is passed with the bases, it is used.
Georg Brandl116aa622007-08-15 14:28:22 +00001575
Benjamin Petersone348d1a2008-10-19 21:29:05 +00001576* Otherwise, if there is at least one base class, its metaclass is used.
Georg Brandl116aa622007-08-15 14:28:22 +00001577
Georg Brandl85eb8c12007-08-31 16:33:38 +00001578* Otherwise, the default metaclass (:class:`type`) is used.
Georg Brandl116aa622007-08-15 14:28:22 +00001579
1580The potential uses for metaclasses are boundless. Some ideas that have been
1581explored including logging, interface checking, automatic delegation, automatic
1582property creation, proxies, frameworks, and automatic resource
1583locking/synchronization.
1584
Raymond Hettinger15efcb62009-04-07 02:09:15 +00001585Here is an example of a metaclass that uses an :class:`collections.OrderedDict`
1586to remember the order that class members were defined::
Raymond Hettinger958e3682009-04-07 02:08:23 +00001587
1588 class OrderedClass(type):
1589
1590 @classmethod
1591 def __prepare__(metacls, name, bases, **kwds):
1592 return collections.OrderedDict()
1593
1594 def __new__(cls, name, bases, classdict):
1595 result = type.__new__(cls, name, bases, dict(classdict))
1596 result.members = tuple(classdict)
1597 return result
1598
1599 class A(metaclass=OrderedClass):
1600 def one(self): pass
1601 def two(self): pass
1602 def three(self): pass
1603 def four(self): pass
1604
1605 >>> A.members
1606 ('__module__', 'one', 'two', 'three', 'four')
1607
Raymond Hettingerc4faeea2009-04-07 02:31:14 +00001608When the class definition for *A* gets executed, the process begins with
1609calling the metaclass's :meth:`__prepare__` method which returns an empty
Raymond Hettinger958e3682009-04-07 02:08:23 +00001610:class:`collections.OrderedDict`. That mapping records the methods and
1611attributes of *A* as they are defined within the body of the class statement.
Raymond Hettingerc4faeea2009-04-07 02:31:14 +00001612Once those definitions are executed, the ordered dictionary is fully populated
Hirokazu Yamamotoae9eb5c2009-04-26 03:34:06 +00001613and the metaclass's :meth:`__new__` method gets invoked. That method builds
Raymond Hettingerc4faeea2009-04-07 02:31:14 +00001614the new type and it saves the ordered dictionary keys in an attribute
Fred Drake11c49a52010-11-13 04:24:26 +00001615called ``members``.
Raymond Hettinger958e3682009-04-07 02:08:23 +00001616
Georg Brandl116aa622007-08-15 14:28:22 +00001617
Georg Brandl8569e582010-05-19 20:57:08 +00001618Customizing instance and subclass checks
1619----------------------------------------
1620
1621The following methods are used to override the default behavior of the
1622:func:`isinstance` and :func:`issubclass` built-in functions.
1623
1624In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
1625order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
Benjamin Petersond7c3ed52010-06-27 22:32:30 +00001626classes" to any class or type (including built-in types), including other
Georg Brandl8569e582010-05-19 20:57:08 +00001627ABCs.
1628
1629.. method:: class.__instancecheck__(self, instance)
1630
1631 Return true if *instance* should be considered a (direct or indirect)
1632 instance of *class*. If defined, called to implement ``isinstance(instance,
1633 class)``.
1634
1635
1636.. method:: class.__subclasscheck__(self, subclass)
1637
1638 Return true if *subclass* should be considered a (direct or indirect)
1639 subclass of *class*. If defined, called to implement ``issubclass(subclass,
1640 class)``.
1641
1642
1643Note that these methods are looked up on the type (metaclass) of a class. They
1644cannot be defined as class methods in the actual class. This is consistent with
Benjamin Petersond7c3ed52010-06-27 22:32:30 +00001645the lookup of special methods that are called on instances, only in this
Georg Brandl8569e582010-05-19 20:57:08 +00001646case the instance is itself a class.
1647
1648.. seealso::
1649
1650 :pep:`3119` - Introducing Abstract Base Classes
1651 Includes the specification for customizing :func:`isinstance` and
1652 :func:`issubclass` behavior through :meth:`__instancecheck__` and
1653 :meth:`__subclasscheck__`, with motivation for this functionality in the
1654 context of adding Abstract Base Classes (see the :mod:`abc` module) to the
1655 language.
1656
1657
Georg Brandl116aa622007-08-15 14:28:22 +00001658.. _callable-types:
1659
1660Emulating callable objects
1661--------------------------
1662
1663
1664.. method:: object.__call__(self[, args...])
1665
1666 .. index:: pair: call; instance
1667
1668 Called when the instance is "called" as a function; if this method is defined,
1669 ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
1670
1671
1672.. _sequence-types:
1673
1674Emulating container types
1675-------------------------
1676
1677The following methods can be defined to implement container objects. Containers
1678usually are sequences (such as lists or tuples) or mappings (like dictionaries),
1679but can represent other containers as well. The first set of methods is used
1680either to emulate a sequence or to emulate a mapping; the difference is that for
1681a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
1682N`` where *N* is the length of the sequence, or slice objects, which define a
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001683range of items. It is also recommended that mappings provide the methods
Georg Brandlc7723722008-05-26 17:47:11 +00001684:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`,
1685:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`copy`, and
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001686:meth:`update` behaving similar to those for Python's standard dictionary
Georg Brandlc7723722008-05-26 17:47:11 +00001687objects. The :mod:`collections` module provides a :class:`MutableMapping`
1688abstract base class to help create those methods from a base set of
1689:meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`.
1690Mutable sequences should provide methods :meth:`append`, :meth:`count`,
1691:meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`,
1692:meth:`reverse` and :meth:`sort`, like Python standard list objects. Finally,
1693sequence types should implement addition (meaning concatenation) and
1694multiplication (meaning repetition) by defining the methods :meth:`__add__`,
1695:meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and
1696:meth:`__imul__` described below; they should not define other numerical
1697operators. It is recommended that both mappings and sequences implement the
1698:meth:`__contains__` method to allow efficient use of the ``in`` operator; for
1699mappings, ``in`` should search the mapping's keys; for sequences, it should
1700search through the values. It is further recommended that both mappings and
1701sequences implement the :meth:`__iter__` method to allow efficient iteration
1702through the container; for mappings, :meth:`__iter__` should be the same as
Fred Drake2e748782007-09-04 17:33:11 +00001703:meth:`keys`; for sequences, it should iterate through the values.
Georg Brandl116aa622007-08-15 14:28:22 +00001704
1705.. method:: object.__len__(self)
1706
1707 .. index::
1708 builtin: len
1709 single: __bool__() (object method)
1710
1711 Called to implement the built-in function :func:`len`. Should return the length
1712 of the object, an integer ``>=`` 0. Also, an object that doesn't define a
1713 :meth:`__bool__` method and whose :meth:`__len__` method returns zero is
1714 considered to be false in a Boolean context.
1715
1716
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001717.. note::
1718
1719 Slicing is done exclusively with the following three methods. A call like ::
1720
1721 a[1:2] = b
1722
1723 is translated to ::
1724
1725 a[slice(1, 2, None)] = b
1726
1727 and so forth. Missing slice items are always filled in with ``None``.
1728
1729
Georg Brandl116aa622007-08-15 14:28:22 +00001730.. method:: object.__getitem__(self, key)
1731
1732 .. index:: object: slice
1733
1734 Called to implement evaluation of ``self[key]``. For sequence types, the
1735 accepted keys should be integers and slice objects. Note that the special
1736 interpretation of negative indexes (if the class wishes to emulate a sequence
1737 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
1738 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
1739 for the sequence (after any special interpretation of negative values),
1740 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
1741 in the container), :exc:`KeyError` should be raised.
1742
1743 .. note::
1744
1745 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
1746 indexes to allow proper detection of the end of the sequence.
1747
1748
1749.. method:: object.__setitem__(self, key, value)
1750
1751 Called to implement assignment to ``self[key]``. Same note as for
1752 :meth:`__getitem__`. This should only be implemented for mappings if the
1753 objects support changes to the values for keys, or if new keys can be added, or
1754 for sequences if elements can be replaced. The same exceptions should be raised
1755 for improper *key* values as for the :meth:`__getitem__` method.
1756
1757
1758.. method:: object.__delitem__(self, key)
1759
1760 Called to implement deletion of ``self[key]``. Same note as for
1761 :meth:`__getitem__`. This should only be implemented for mappings if the
1762 objects support removal of keys, or for sequences if elements can be removed
1763 from the sequence. The same exceptions should be raised for improper *key*
1764 values as for the :meth:`__getitem__` method.
1765
1766
1767.. method:: object.__iter__(self)
1768
1769 This method is called when an iterator is required for a container. This method
1770 should return a new iterator object that can iterate over all the objects in the
1771 container. For mappings, it should iterate over the keys of the container, and
Fred Drake2e748782007-09-04 17:33:11 +00001772 should also be made available as the method :meth:`keys`.
Georg Brandl116aa622007-08-15 14:28:22 +00001773
1774 Iterator objects also need to implement this method; they are required to return
1775 themselves. For more information on iterator objects, see :ref:`typeiter`.
1776
Christian Heimes7f044312008-01-06 17:05:40 +00001777
1778.. method:: object.__reversed__(self)
1779
Georg Brandl22b34312009-07-26 14:54:51 +00001780 Called (if present) by the :func:`reversed` built-in to implement
Christian Heimes7f044312008-01-06 17:05:40 +00001781 reverse iteration. It should return a new iterator object that iterates
1782 over all the objects in the container in reverse order.
1783
Georg Brandl8a1e4c42009-05-25 21:13:36 +00001784 If the :meth:`__reversed__` method is not provided, the :func:`reversed`
Georg Brandl22b34312009-07-26 14:54:51 +00001785 built-in will fall back to using the sequence protocol (:meth:`__len__` and
Georg Brandl8a1e4c42009-05-25 21:13:36 +00001786 :meth:`__getitem__`). Objects that support the sequence protocol should
1787 only provide :meth:`__reversed__` if they can provide an implementation
1788 that is more efficient than the one provided by :func:`reversed`.
Christian Heimes7f044312008-01-06 17:05:40 +00001789
1790
Georg Brandl116aa622007-08-15 14:28:22 +00001791The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
1792implemented as an iteration through a sequence. However, container objects can
1793supply the following special method with a more efficient implementation, which
1794also does not require the object be a sequence.
1795
Georg Brandl116aa622007-08-15 14:28:22 +00001796.. method:: object.__contains__(self, item)
1797
Georg Brandl495f7b52009-10-27 15:28:25 +00001798 Called to implement membership test operators. Should return true if *item*
1799 is in *self*, false otherwise. For mapping objects, this should consider the
1800 keys of the mapping rather than the values or the key-item pairs.
1801
1802 For objects that don't define :meth:`__contains__`, the membership test first
1803 tries iteration via :meth:`__iter__`, then the old sequence iteration
1804 protocol via :meth:`__getitem__`, see :ref:`this section in the language
1805 reference <membership-test-details>`.
Georg Brandl116aa622007-08-15 14:28:22 +00001806
1807
Georg Brandl116aa622007-08-15 14:28:22 +00001808.. _numeric-types:
1809
1810Emulating numeric types
1811-----------------------
1812
1813The following methods can be defined to emulate numeric objects. Methods
1814corresponding to operations that are not supported by the particular kind of
1815number implemented (e.g., bitwise operations for non-integral numbers) should be
1816left undefined.
1817
1818
1819.. method:: object.__add__(self, other)
1820 object.__sub__(self, other)
1821 object.__mul__(self, other)
Georg Brandlae55dc02008-09-06 17:43:49 +00001822 object.__truediv__(self, other)
Georg Brandl116aa622007-08-15 14:28:22 +00001823 object.__floordiv__(self, other)
1824 object.__mod__(self, other)
1825 object.__divmod__(self, other)
1826 object.__pow__(self, other[, modulo])
1827 object.__lshift__(self, other)
1828 object.__rshift__(self, other)
1829 object.__and__(self, other)
1830 object.__xor__(self, other)
1831 object.__or__(self, other)
1832
1833 .. index::
1834 builtin: divmod
1835 builtin: pow
1836 builtin: pow
1837
1838 These methods are called to implement the binary arithmetic operations (``+``,
Georg Brandlae55dc02008-09-06 17:43:49 +00001839 ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
Georg Brandl116aa622007-08-15 14:28:22 +00001840 ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
Brett Cannon3a954da2008-08-14 05:59:39 +00001841 ``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
Georg Brandl116aa622007-08-15 14:28:22 +00001842 method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
1843 equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
Georg Brandlae55dc02008-09-06 17:43:49 +00001844 related to :meth:`__truediv__`. Note that :meth:`__pow__` should be defined
1845 to accept an optional third argument if the ternary version of the built-in
1846 :func:`pow` function is to be supported.
Georg Brandl116aa622007-08-15 14:28:22 +00001847
1848 If one of those methods does not support the operation with the supplied
1849 arguments, it should return ``NotImplemented``.
1850
1851
Georg Brandl116aa622007-08-15 14:28:22 +00001852.. method:: object.__radd__(self, other)
1853 object.__rsub__(self, other)
1854 object.__rmul__(self, other)
Georg Brandl116aa622007-08-15 14:28:22 +00001855 object.__rtruediv__(self, other)
1856 object.__rfloordiv__(self, other)
1857 object.__rmod__(self, other)
1858 object.__rdivmod__(self, other)
1859 object.__rpow__(self, other)
1860 object.__rlshift__(self, other)
1861 object.__rrshift__(self, other)
1862 object.__rand__(self, other)
1863 object.__rxor__(self, other)
1864 object.__ror__(self, other)
1865
1866 .. index::
1867 builtin: divmod
1868 builtin: pow
1869
1870 These methods are called to implement the binary arithmetic operations (``+``,
Georg Brandlae55dc02008-09-06 17:43:49 +00001871 ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``,
1872 ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected (swapped) operands.
1873 These functions are only called if the left operand does not support the
1874 corresponding operation and the operands are of different types. [#]_ For
1875 instance, to evaluate the expression ``x - y``, where *y* is an instance of
1876 a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if
1877 ``x.__sub__(y)`` returns *NotImplemented*.
Georg Brandl116aa622007-08-15 14:28:22 +00001878
1879 .. index:: builtin: pow
1880
1881 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
1882 coercion rules would become too complicated).
1883
1884 .. note::
1885
1886 If the right operand's type is a subclass of the left operand's type and that
1887 subclass provides the reflected method for the operation, this method will be
1888 called before the left operand's non-reflected method. This behavior allows
1889 subclasses to override their ancestors' operations.
1890
1891
1892.. method:: object.__iadd__(self, other)
1893 object.__isub__(self, other)
1894 object.__imul__(self, other)
Georg Brandl116aa622007-08-15 14:28:22 +00001895 object.__itruediv__(self, other)
1896 object.__ifloordiv__(self, other)
1897 object.__imod__(self, other)
1898 object.__ipow__(self, other[, modulo])
1899 object.__ilshift__(self, other)
1900 object.__irshift__(self, other)
1901 object.__iand__(self, other)
1902 object.__ixor__(self, other)
1903 object.__ior__(self, other)
1904
Benjamin Petersonb58dda72009-01-18 22:27:04 +00001905 These methods are called to implement the augmented arithmetic assignments
Georg Brandl116aa622007-08-15 14:28:22 +00001906 (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
1907 ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
1908 in-place (modifying *self*) and return the result (which could be, but does
1909 not have to be, *self*). If a specific method is not defined, the augmented
Benjamin Petersonb58dda72009-01-18 22:27:04 +00001910 assignment falls back to the normal methods. For instance, to execute the
1911 statement ``x += y``, where *x* is an instance of a class that has an
Georg Brandl116aa622007-08-15 14:28:22 +00001912 :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
1913 of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
Brett Cannon3a954da2008-08-14 05:59:39 +00001914 and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
Georg Brandl116aa622007-08-15 14:28:22 +00001915
1916
1917.. method:: object.__neg__(self)
1918 object.__pos__(self)
1919 object.__abs__(self)
1920 object.__invert__(self)
1921
1922 .. index:: builtin: abs
1923
1924 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
1925 and ``~``).
1926
1927
1928.. method:: object.__complex__(self)
1929 object.__int__(self)
Georg Brandl116aa622007-08-15 14:28:22 +00001930 object.__float__(self)
Mark Summerfield9557f602008-07-01 14:42:30 +00001931 object.__round__(self, [,n])
Georg Brandl116aa622007-08-15 14:28:22 +00001932
1933 .. index::
1934 builtin: complex
1935 builtin: int
Georg Brandl116aa622007-08-15 14:28:22 +00001936 builtin: float
Mark Summerfield9557f602008-07-01 14:42:30 +00001937 builtin: round
Georg Brandl116aa622007-08-15 14:28:22 +00001938
Mark Summerfield9557f602008-07-01 14:42:30 +00001939 Called to implement the built-in functions :func:`complex`,
1940 :func:`int`, :func:`float` and :func:`round`. Should return a value
1941 of the appropriate type.
Georg Brandl116aa622007-08-15 14:28:22 +00001942
1943
1944.. method:: object.__index__(self)
1945
1946 Called to implement :func:`operator.index`. Also called whenever Python needs
1947 an integer object (such as in slicing, or in the built-in :func:`bin`,
Georg Brandl5c106642007-11-29 17:41:05 +00001948 :func:`hex` and :func:`oct` functions). Must return an integer.
Georg Brandl116aa622007-08-15 14:28:22 +00001949
Georg Brandl116aa622007-08-15 14:28:22 +00001950
1951.. _context-managers:
1952
1953With Statement Context Managers
1954-------------------------------
1955
Georg Brandl116aa622007-08-15 14:28:22 +00001956A :dfn:`context manager` is an object that defines the runtime context to be
1957established when executing a :keyword:`with` statement. The context manager
1958handles the entry into, and the exit from, the desired runtime context for the
1959execution of the block of code. Context managers are normally invoked using the
1960:keyword:`with` statement (described in section :ref:`with`), but can also be
1961used by directly invoking their methods.
1962
1963.. index::
1964 statement: with
1965 single: context manager
1966
1967Typical uses of context managers include saving and restoring various kinds of
1968global state, locking and unlocking resources, closing opened files, etc.
1969
1970For more information on context managers, see :ref:`typecontextmanager`.
1971
1972
1973.. method:: object.__enter__(self)
1974
1975 Enter the runtime context related to this object. The :keyword:`with` statement
1976 will bind this method's return value to the target(s) specified in the
1977 :keyword:`as` clause of the statement, if any.
1978
1979
1980.. method:: object.__exit__(self, exc_type, exc_value, traceback)
1981
1982 Exit the runtime context related to this object. The parameters describe the
1983 exception that caused the context to be exited. If the context was exited
1984 without an exception, all three arguments will be :const:`None`.
1985
1986 If an exception is supplied, and the method wishes to suppress the exception
1987 (i.e., prevent it from being propagated), it should return a true value.
1988 Otherwise, the exception will be processed normally upon exit from this method.
1989
1990 Note that :meth:`__exit__` methods should not reraise the passed-in exception;
1991 this is the caller's responsibility.
1992
1993
1994.. seealso::
1995
1996 :pep:`0343` - The "with" statement
1997 The specification, background, and examples for the Python :keyword:`with`
1998 statement.
1999
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002000
2001.. _special-lookup:
2002
2003Special method lookup
2004---------------------
2005
2006For custom classes, implicit invocations of special methods are only guaranteed
2007to work correctly if defined on an object's type, not in the object's instance
2008dictionary. That behaviour is the reason why the following code raises an
2009exception::
2010
Éric Araujo28053fb2010-11-22 03:09:19 +00002011 >>> class C:
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002012 ... pass
2013 ...
2014 >>> c = C()
2015 >>> c.__len__ = lambda: 5
2016 >>> len(c)
2017 Traceback (most recent call last):
2018 File "<stdin>", line 1, in <module>
2019 TypeError: object of type 'C' has no len()
2020
2021The rationale behind this behaviour lies with a number of special methods such
2022as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
2023including type objects. If the implicit lookup of these methods used the
2024conventional lookup process, they would fail when invoked on the type object
2025itself::
2026
2027 >>> 1 .__hash__() == hash(1)
2028 True
2029 >>> int.__hash__() == hash(int)
2030 Traceback (most recent call last):
2031 File "<stdin>", line 1, in <module>
2032 TypeError: descriptor '__hash__' of 'int' object needs an argument
2033
2034Incorrectly attempting to invoke an unbound method of a class in this way is
2035sometimes referred to as 'metaclass confusion', and is avoided by bypassing
2036the instance when looking up special methods::
2037
2038 >>> type(1).__hash__(1) == hash(1)
2039 True
2040 >>> type(int).__hash__(int) == hash(int)
2041 True
2042
2043In addition to bypassing any instance attributes in the interest of
Georg Brandlaf265f42008-12-07 15:06:20 +00002044correctness, implicit special method lookup generally also bypasses the
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002045:meth:`__getattribute__` method even of the object's metaclass::
2046
2047 >>> class Meta(type):
2048 ... def __getattribute__(*args):
Benjamin Peterson64106fb2008-10-29 20:35:35 +00002049 ... print("Metaclass getattribute invoked")
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002050 ... return type.__getattribute__(*args)
2051 ...
Benjamin Petersone348d1a2008-10-19 21:29:05 +00002052 >>> class C(object, metaclass=Meta):
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002053 ... def __len__(self):
2054 ... return 10
2055 ... def __getattribute__(*args):
Benjamin Peterson64106fb2008-10-29 20:35:35 +00002056 ... print("Class getattribute invoked")
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002057 ... return object.__getattribute__(*args)
2058 ...
2059 >>> c = C()
2060 >>> c.__len__() # Explicit lookup via instance
2061 Class getattribute invoked
2062 10
2063 >>> type(c).__len__(c) # Explicit lookup via type
2064 Metaclass getattribute invoked
2065 10
2066 >>> len(c) # Implicit lookup
2067 10
2068
2069Bypassing the :meth:`__getattribute__` machinery in this fashion
2070provides significant scope for speed optimisations within the
2071interpreter, at the cost of some flexibility in the handling of
2072special methods (the special method *must* be set on the class
2073object itself in order to be consistently invoked by the interpreter).
2074
2075
Georg Brandl116aa622007-08-15 14:28:22 +00002076.. rubric:: Footnotes
2077
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002078.. [#] It *is* possible in some cases to change an object's type, under certain
2079 controlled conditions. It generally isn't a good idea though, since it can
2080 lead to some very strange behaviour if it is handled incorrectly.
2081
Georg Brandl116aa622007-08-15 14:28:22 +00002082.. [#] For operands of the same type, it is assumed that if the non-reflected method
2083 (such as :meth:`__add__`) fails the operation is not supported, which is why the
2084 reflected method is not called.