blob: 37640e5073f369e452ebd47e787c94b07d16c6d0 [file] [log] [blame]
Georg Brandl8ec7f652007-08-15 14:28:01 +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
32Every object has an identity, a type and a value. An object's *identity* never
33changes once it has been created; you may think of it as the object's address in
34memory. The ':keyword:`is`' operator compares the identity of two objects; the
35:func:`id` function returns an integer representing its identity (currently
36implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_
37An object's type determines the operations that the object supports (e.g., "does
38it have a length?") and also defines the possible values for objects of that
39type. The :func:`type` function returns an object's type (which is an object
40itself). The *value* of some objects can change. Objects whose value can
41change are said to be *mutable*; objects whose value is unchangeable once they
42are created are called *immutable*. (The value of an immutable container object
43that contains a reference to a mutable object can change when the latter's value
44is changed; however the container is still considered immutable, because the
45collection of objects it contains cannot be changed. So, immutability is not
46strictly the same as having an unchangeable value, it is more subtle.) An
47object's mutability is determined by its type; for instance, numbers, strings
48and tuples are immutable, while dictionaries and lists are mutable.
49
50.. index::
51 single: garbage collection
52 single: reference counting
53 single: unreachable object
54
55Objects are never explicitly destroyed; however, when they become unreachable
56they may be garbage-collected. An implementation is allowed to postpone garbage
57collection or omit it altogether --- it is a matter of implementation quality
58how garbage collection is implemented, as long as no objects are collected that
59are still reachable. (Implementation note: the current implementation uses a
60reference-counting scheme with (optional) delayed detection of cyclically linked
61garbage, which collects most objects as soon as they become unreachable, but is
62not guaranteed to collect garbage containing circular references. See the
63documentation of the :mod:`gc` module for information on controlling the
64collection of cyclic garbage.)
65
66Note that the use of the implementation's tracing or debugging facilities may
67keep objects alive that would normally be collectable. Also note that catching
68an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
69objects alive.
70
71Some objects contain references to "external" resources such as open files or
72windows. It is understood that these resources are freed when the object is
73garbage-collected, but since garbage collection is not guaranteed to happen,
74such objects also provide an explicit way to release the external resource,
75usually a :meth:`close` method. Programs are strongly recommended to explicitly
76close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
77provides a convenient way to do this.
78
79.. index:: single: container
80
81Some objects contain references to other objects; these are called *containers*.
82Examples of containers are tuples, lists and dictionaries. The references are
83part of a container's value. In most cases, when we talk about the value of a
84container, we imply the values, not the identities of the contained objects;
85however, when we talk about the mutability of a container, only the identities
86of the immediately contained objects are implied. So, if an immutable container
87(like a tuple) contains a reference to a mutable object, its value changes if
88that mutable object is changed.
89
90Types affect almost all aspects of object behavior. Even the importance of
91object identity is affected in some sense: for immutable types, operations that
92compute new values may actually return a reference to any existing object with
93the same type and value, while for mutable objects this is not allowed. E.g.,
94after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
95with the value one, depending on the implementation, but after ``c = []; d =
96[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
97created empty lists. (Note that ``c = d = []`` assigns the same object to both
98``c`` and ``d``.)
99
100
101.. _types:
102
103The standard type hierarchy
104===========================
105
106.. index::
107 single: type
108 pair: data; type
109 pair: type; hierarchy
110 pair: extension; module
111 pair: C; language
112
113Below is a list of the types that are built into Python. Extension modules
114(written in C, Java, or other languages, depending on the implementation) can
115define additional types. Future versions of Python may add types to the type
116hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).
117
118.. index::
119 single: attribute
120 pair: special; attribute
121 triple: generic; special; attribute
122
123Some of the type descriptions below contain a paragraph listing 'special
124attributes.' These are attributes that provide access to the implementation and
125are not intended for general use. Their definition may change in the future.
126
127None
128 .. index:: object: None
129
130 This type has a single value. There is a single object with this value. This
131 object is accessed through the built-in name ``None``. It is used to signify the
132 absence of a value in many situations, e.g., it is returned from functions that
133 don't explicitly return anything. Its truth value is false.
134
135NotImplemented
136 .. index:: object: NotImplemented
137
138 This type has a single value. There is a single object with this value. This
139 object is accessed through the built-in name ``NotImplemented``. Numeric methods
140 and rich comparison methods may return this value if they do not implement the
141 operation for the operands provided. (The interpreter will then try the
142 reflected operation, or some other fallback, depending on the operator.) Its
143 truth value is true.
144
145Ellipsis
146 .. index:: object: Ellipsis
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 ``Ellipsis``. It is used to
150 indicate the presence of the ``...`` syntax in a slice. Its truth value is
151 true.
152
Jeffrey Yasskin2f3c16b2008-01-03 02:21:52 +0000153:class:`numbers.Number`
Georg Brandl8ec7f652007-08-15 14:28:01 +0000154 .. index:: object: numeric
155
156 These are created by numeric literals and returned as results by arithmetic
157 operators and arithmetic built-in functions. Numeric objects are immutable;
158 once created their value never changes. Python numbers are of course strongly
159 related to mathematical numbers, but subject to the limitations of numerical
160 representation in computers.
161
162 Python distinguishes between integers, floating point numbers, and complex
163 numbers:
164
Jeffrey Yasskin2f3c16b2008-01-03 02:21:52 +0000165 :class:`numbers.Integral`
Georg Brandl8ec7f652007-08-15 14:28:01 +0000166 .. index:: object: integer
167
168 These represent elements from the mathematical set of integers (positive and
169 negative).
170
171 There are three types of integers:
172
173 Plain integers
174 .. index::
175 object: plain integer
176 single: OverflowError (built-in exception)
177
Georg Brandle9135ba2008-05-11 10:55:59 +0000178 These represent numbers in the range -2147483648 through 2147483647.
179 (The range may be larger on machines with a larger natural word size,
180 but not smaller.) When the result of an operation would fall outside
181 this range, the result is normally returned as a long integer (in some
182 cases, the exception :exc:`OverflowError` is raised instead). For the
183 purpose of shift and mask operations, integers are assumed to have a
184 binary, 2's complement notation using 32 or more bits, and hiding no
185 bits from the user (i.e., all 4294967296 different bit patterns
186 correspond to different values).
Georg Brandl8ec7f652007-08-15 14:28:01 +0000187
188 Long integers
189 .. index:: object: long integer
190
Georg Brandle9135ba2008-05-11 10:55:59 +0000191 These represent numbers in an unlimited range, subject to available
192 (virtual) memory only. For the purpose of shift and mask operations, a
193 binary representation is assumed, and negative numbers are represented
194 in a variant of 2's complement which gives the illusion of an infinite
195 string of sign bits extending to the left.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000196
197 Booleans
198 .. index::
199 object: Boolean
200 single: False
201 single: True
202
Georg Brandle9135ba2008-05-11 10:55:59 +0000203 These represent the truth values False and True. The two objects
204 representing the values False and True are the only Boolean objects.
205 The Boolean type is a subtype of plain integers, and Boolean values
206 behave like the values 0 and 1, respectively, in almost all contexts,
207 the exception being that when converted to a string, the strings
208 ``"False"`` or ``"True"`` are returned, respectively.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000209
210 .. index:: pair: integer; representation
211
Georg Brandle9135ba2008-05-11 10:55:59 +0000212 The rules for integer representation are intended to give the most
213 meaningful interpretation of shift and mask operations involving negative
214 integers and the least surprises when switching between the plain and long
215 integer domains. Any operation, if it yields a result in the plain
216 integer domain, will yield the same result in the long integer domain or
217 when using mixed operands. The switch between domains is transparent to
218 the programmer.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000219
Jeffrey Yasskin2f3c16b2008-01-03 02:21:52 +0000220 :class:`numbers.Real` (:class:`float`)
Georg Brandl8ec7f652007-08-15 14:28:01 +0000221 .. index::
222 object: floating point
223 pair: floating point; number
224 pair: C; language
225 pair: Java; language
226
227 These represent machine-level double precision floating point numbers. You are
228 at the mercy of the underlying machine architecture (and C or Java
229 implementation) for the accepted range and handling of overflow. Python does not
230 support single-precision floating point numbers; the savings in processor and
231 memory usage that are usually the reason for using these is dwarfed by the
232 overhead of using objects in Python, so there is no reason to complicate the
233 language with two kinds of floating point numbers.
234
Jeffrey Yasskin2f3c16b2008-01-03 02:21:52 +0000235 :class:`numbers.Complex`
Georg Brandl8ec7f652007-08-15 14:28:01 +0000236 .. index::
237 object: complex
238 pair: complex; number
239
240 These represent complex numbers as a pair of machine-level double precision
241 floating point numbers. The same caveats apply as for floating point numbers.
242 The real and imaginary parts of a complex number ``z`` can be retrieved through
243 the read-only attributes ``z.real`` and ``z.imag``.
244
Georg Brandl8ec7f652007-08-15 14:28:01 +0000245Sequences
246 .. index::
247 builtin: len
248 object: sequence
249 single: index operation
250 single: item selection
251 single: subscription
252
253 These represent finite ordered sets indexed by non-negative numbers. The
254 built-in function :func:`len` returns the number of items of a sequence. When
255 the length of a sequence is *n*, the index set contains the numbers 0, 1,
256 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
257
258 .. index:: single: slicing
259
260 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
261 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
262 sequence of the same type. This implies that the index set is renumbered so
263 that it starts at 0.
264
265 .. index:: single: extended slicing
266
267 Some sequences also support "extended slicing" with a third "step" parameter:
268 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
269 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
270
271 Sequences are distinguished according to their mutability:
272
273 Immutable sequences
274 .. index::
275 object: immutable sequence
276 object: immutable
277
278 An object of an immutable sequence type cannot change once it is created. (If
279 the object contains references to other objects, these other objects may be
280 mutable and may be changed; however, the collection of objects directly
281 referenced by an immutable object cannot change.)
282
283 The following types are immutable sequences:
284
285 Strings
286 .. index::
287 builtin: chr
288 builtin: ord
289 object: string
290 single: character
291 single: byte
292 single: ASCII@ASCII
293
294 The items of a string are characters. There is no separate character type; a
295 character is represented by a string of one item. Characters represent (at
296 least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert
297 between characters and nonnegative integers representing the byte values. Bytes
298 with the values 0-127 usually represent the corresponding ASCII values, but the
299 interpretation of values is up to the program. The string data type is also
300 used to represent arrays of bytes, e.g., to hold data read from a file.
301
302 .. index::
303 single: ASCII@ASCII
304 single: EBCDIC
305 single: character set
306 pair: string; comparison
307 builtin: chr
308 builtin: ord
309
310 (On systems whose native character set is not ASCII, strings may use EBCDIC in
311 their internal representation, provided the functions :func:`chr` and
312 :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison
313 preserves the ASCII order. Or perhaps someone can propose a better rule?)
314
315 Unicode
316 .. index::
317 builtin: unichr
318 builtin: ord
319 builtin: unicode
320 object: unicode
321 single: character
322 single: integer
323 single: Unicode
324
325 The items of a Unicode object are Unicode code units. A Unicode code unit is
326 represented by a Unicode object of one item and can hold either a 16-bit or
327 32-bit value representing a Unicode ordinal (the maximum value for the ordinal
328 is given in ``sys.maxunicode``, and depends on how Python is configured at
329 compile time). Surrogate pairs may be present in the Unicode object, and will
330 be reported as two separate items. The built-in functions :func:`unichr` and
331 :func:`ord` convert between code units and nonnegative integers representing the
332 Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to
333 other encodings are possible through the Unicode method :meth:`encode` and the
334 built-in function :func:`unicode`.
335
336 Tuples
337 .. index::
338 object: tuple
339 pair: singleton; tuple
340 pair: empty; tuple
341
342 The items of a tuple are arbitrary Python objects. Tuples of two or more items
343 are formed by comma-separated lists of expressions. A tuple of one item (a
344 'singleton') can be formed by affixing a comma to an expression (an expression
345 by itself does not create a tuple, since parentheses must be usable for grouping
346 of expressions). An empty tuple can be formed by an empty pair of parentheses.
347
Georg Brandl8ec7f652007-08-15 14:28:01 +0000348 Mutable sequences
349 .. index::
350 object: mutable sequence
351 object: mutable
352 pair: assignment; statement
353 single: delete
354 statement: del
355 single: subscription
356 single: slicing
357
358 Mutable sequences can be changed after they are created. The subscription and
359 slicing notations can be used as the target of assignment and :keyword:`del`
360 (delete) statements.
361
Benjamin Petersonb7464482009-01-18 01:28:46 +0000362 There are currently two intrinsic mutable sequence types:
Georg Brandl8ec7f652007-08-15 14:28:01 +0000363
364 Lists
365 .. index:: object: list
366
367 The items of a list are arbitrary Python objects. Lists are formed by placing a
368 comma-separated list of expressions in square brackets. (Note that there are no
369 special cases needed to form lists of length 0 or 1.)
370
Benjamin Petersonf1a40692009-01-18 01:28:09 +0000371 Byte Arrays
372 .. index:: bytearray
373
374 A bytearray object is a mutable array. They are created by the built-in
375 :func:`bytearray` constructor. Aside from being mutable (and hence
376 unhashable), byte arrays otherwise provide the same interface and
377 functionality as immutable bytes objects.
378
Georg Brandl8ec7f652007-08-15 14:28:01 +0000379 .. index:: module: array
380
381 The extension module :mod:`array` provides an additional example of a mutable
382 sequence type.
383
Benjamin Petersonf1a40692009-01-18 01:28:09 +0000384Set types../
Georg Brandl8ec7f652007-08-15 14:28:01 +0000385 .. index::
386 builtin: len
387 object: set type
388
389 These represent unordered, finite sets of unique, immutable objects. As such,
390 they cannot be indexed by any subscript. However, they can be iterated over, and
391 the built-in function :func:`len` returns the number of items in a set. Common
392 uses for sets are fast membership testing, removing duplicates from a sequence,
393 and computing mathematical operations such as intersection, union, difference,
394 and symmetric difference.
395
396 For set elements, the same immutability rules apply as for dictionary keys. Note
397 that numeric types obey the normal rules for numeric comparison: if two numbers
398 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
399 set.
400
401 There are currently two intrinsic set types:
402
403 Sets
404 .. index:: object: set
405
406 These represent a mutable set. They are created by the built-in :func:`set`
407 constructor and can be modified afterwards by several methods, such as
408 :meth:`add`.
409
410 Frozen sets
411 .. index:: object: frozenset
412
Georg Brandl7c3e79f2007-11-02 20:06:17 +0000413 These represent an immutable set. They are created by the built-in
414 :func:`frozenset` constructor. As a frozenset is immutable and
415 :term:`hashable`, it can be used again as an element of another set, or as
416 a dictionary key.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000417
Georg Brandl8ec7f652007-08-15 14:28:01 +0000418Mappings
419 .. index::
420 builtin: len
421 single: subscription
422 object: mapping
423
424 These represent finite sets of objects indexed by arbitrary index sets. The
425 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
426 ``a``; this can be used in expressions and as the target of assignments or
427 :keyword:`del` statements. The built-in function :func:`len` returns the number
428 of items in a mapping.
429
430 There is currently a single intrinsic mapping type:
431
432 Dictionaries
433 .. index:: object: dictionary
434
435 These represent finite sets of objects indexed by nearly arbitrary values. The
436 only types of values not acceptable as keys are values containing lists or
437 dictionaries or other mutable types that are compared by value rather than by
438 object identity, the reason being that the efficient implementation of
439 dictionaries requires a key's hash value to remain constant. Numeric types used
440 for keys obey the normal rules for numeric comparison: if two numbers compare
441 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
442 the same dictionary entry.
443
444 Dictionaries are mutable; they can be created by the ``{...}`` notation (see
445 section :ref:`dict`).
446
447 .. index::
448 module: dbm
449 module: gdbm
450 module: bsddb
451
452 The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
453 additional examples of mapping types.
454
Georg Brandl8ec7f652007-08-15 14:28:01 +0000455Callable types
456 .. index::
457 object: callable
458 pair: function; call
459 single: invocation
460 pair: function; argument
461
462 These are the types to which the function call operation (see section
463 :ref:`calls`) can be applied:
464
465 User-defined functions
466 .. index::
467 pair: user-defined; function
468 object: function
469 object: user-defined function
470
471 A user-defined function object is created by a function definition (see
472 section :ref:`function`). It should be called with an argument list
473 containing the same number of items as the function's formal parameter
474 list.
475
476 Special attributes:
477
478 +-----------------------+-------------------------------+-----------+
479 | Attribute | Meaning | |
480 +=======================+===============================+===========+
481 | :attr:`func_doc` | The function's documentation | Writable |
482 | | string, or ``None`` if | |
483 | | unavailable | |
484 +-----------------------+-------------------------------+-----------+
485 | :attr:`__doc__` | Another way of spelling | Writable |
486 | | :attr:`func_doc` | |
487 +-----------------------+-------------------------------+-----------+
488 | :attr:`func_name` | The function's name | Writable |
489 +-----------------------+-------------------------------+-----------+
490 | :attr:`__name__` | Another way of spelling | Writable |
491 | | :attr:`func_name` | |
492 +-----------------------+-------------------------------+-----------+
493 | :attr:`__module__` | The name of the module the | Writable |
494 | | function was defined in, or | |
495 | | ``None`` if unavailable. | |
496 +-----------------------+-------------------------------+-----------+
497 | :attr:`func_defaults` | A tuple containing default | Writable |
498 | | argument values for those | |
499 | | arguments that have defaults, | |
500 | | or ``None`` if no arguments | |
501 | | have a default value | |
502 +-----------------------+-------------------------------+-----------+
503 | :attr:`func_code` | The code object representing | Writable |
504 | | the compiled function body. | |
505 +-----------------------+-------------------------------+-----------+
506 | :attr:`func_globals` | A reference to the dictionary | Read-only |
507 | | that holds the function's | |
508 | | global variables --- the | |
509 | | global namespace of the | |
510 | | module in which the function | |
511 | | was defined. | |
512 +-----------------------+-------------------------------+-----------+
513 | :attr:`func_dict` | The namespace supporting | Writable |
514 | | arbitrary function | |
515 | | attributes. | |
516 +-----------------------+-------------------------------+-----------+
517 | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only |
518 | | that contain bindings for the | |
519 | | function's free variables. | |
520 +-----------------------+-------------------------------+-----------+
521
522 Most of the attributes labelled "Writable" check the type of the assigned value.
523
524 .. versionchanged:: 2.4
525 ``func_name`` is now writable.
526
527 Function objects also support getting and setting arbitrary attributes, which
528 can be used, for example, to attach metadata to functions. Regular attribute
529 dot-notation is used to get and set such attributes. *Note that the current
530 implementation only supports function attributes on user-defined functions.
531 Function attributes on built-in functions may be supported in the future.*
532
533 Additional information about a function's definition can be retrieved from its
534 code object; see the description of internal types below.
535
536 .. index::
537 single: func_doc (function attribute)
538 single: __doc__ (function attribute)
539 single: __name__ (function attribute)
540 single: __module__ (function attribute)
541 single: __dict__ (function attribute)
542 single: func_defaults (function attribute)
543 single: func_closure (function attribute)
544 single: func_code (function attribute)
545 single: func_globals (function attribute)
546 single: func_dict (function attribute)
547 pair: global; namespace
548
549 User-defined methods
550 .. index::
551 object: method
552 object: user-defined method
553 pair: user-defined; method
554
555 A user-defined method object combines a class, a class instance (or ``None``)
556 and any callable object (normally a user-defined function).
557
558 Special read-only attributes: :attr:`im_self` is the class instance object,
559 :attr:`im_func` is the function object; :attr:`im_class` is the class of
560 :attr:`im_self` for bound methods or the class that asked for the method for
561 unbound methods; :attr:`__doc__` is the method's documentation (same as
562 ``im_func.__doc__``); :attr:`__name__` is the method name (same as
563 ``im_func.__name__``); :attr:`__module__` is the name of the module the method
564 was defined in, or ``None`` if unavailable.
565
566 .. versionchanged:: 2.2
567 :attr:`im_self` used to refer to the class that defined the method.
568
Georg Brandl3fbe20c2008-03-21 19:20:21 +0000569 .. versionchanged:: 2.6
570 For 3.0 forward-compatibility, :attr:`im_func` is also available as
571 :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.
572
Georg Brandl8ec7f652007-08-15 14:28:01 +0000573 .. index::
574 single: __doc__ (method attribute)
575 single: __name__ (method attribute)
576 single: __module__ (method attribute)
577 single: im_func (method attribute)
578 single: im_self (method attribute)
579
580 Methods also support accessing (but not setting) the arbitrary function
581 attributes on the underlying function object.
582
583 User-defined method objects may be created when getting an attribute of a class
584 (perhaps via an instance of that class), if that attribute is a user-defined
585 function object, an unbound user-defined method object, or a class method
586 object. When the attribute is a user-defined method object, a new method object
587 is only created if the class from which it is being retrieved is the same as, or
588 a derived class of, the class stored in the original method object; otherwise,
589 the original method object is used as it is.
590
591 .. index::
592 single: im_class (method attribute)
593 single: im_func (method attribute)
594 single: im_self (method attribute)
595
596 When a user-defined method object is created by retrieving a user-defined
597 function object from a class, its :attr:`im_self` attribute is ``None``
598 and the method object is said to be unbound. When one is created by
599 retrieving a user-defined function object from a class via one of its
600 instances, its :attr:`im_self` attribute is the instance, and the method
601 object is said to be bound. In either case, the new method's
602 :attr:`im_class` attribute is the class from which the retrieval takes
603 place, and its :attr:`im_func` attribute is the original function object.
604
605 .. index:: single: im_func (method attribute)
606
607 When a user-defined method object is created by retrieving another method object
608 from a class or instance, the behaviour is the same as for a function object,
609 except that the :attr:`im_func` attribute of the new instance is not the
610 original method object but its :attr:`im_func` attribute.
611
612 .. index::
613 single: im_class (method attribute)
614 single: im_func (method attribute)
615 single: im_self (method attribute)
616
617 When a user-defined method object is created by retrieving a class method object
618 from a class or instance, its :attr:`im_self` attribute is the class itself (the
619 same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is
620 the function object underlying the class method.
621
622 When an unbound user-defined method object is called, the underlying function
623 (:attr:`im_func`) is called, with the restriction that the first argument must
624 be an instance of the proper class (:attr:`im_class`) or of a derived class
625 thereof.
626
627 When a bound user-defined method object is called, the underlying function
628 (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in
629 front of the argument list. For instance, when :class:`C` is a class which
630 contains a definition for a function :meth:`f`, and ``x`` is an instance of
631 :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.
632
633 When a user-defined method object is derived from a class method object, the
634 "class instance" stored in :attr:`im_self` will actually be the class itself, so
635 that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``
636 where ``f`` is the underlying function.
637
638 Note that the transformation from function object to (unbound or bound) method
639 object happens each time the attribute is retrieved from the class or instance.
640 In some cases, a fruitful optimization is to assign the attribute to a local
641 variable and call that local variable. Also notice that this transformation only
642 happens for user-defined functions; other callable objects (and all non-callable
643 objects) are retrieved without transformation. It is also important to note
644 that user-defined functions which are attributes of a class instance are not
645 converted to bound methods; this *only* happens when the function is an
646 attribute of the class.
647
648 Generator functions
649 .. index::
650 single: generator; function
651 single: generator; iterator
652
653 A function or method which uses the :keyword:`yield` statement (see section
654 :ref:`yield`) is called a :dfn:`generator
655 function`. Such a function, when called, always returns an iterator object
656 which can be used to execute the body of the function: calling the iterator's
657 :meth:`next` method will cause the function to execute until it provides a value
658 using the :keyword:`yield` statement. When the function executes a
659 :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
660 exception is raised and the iterator will have reached the end of the set of
661 values to be returned.
662
663 Built-in functions
664 .. index::
665 object: built-in function
666 object: function
667 pair: C; language
668
669 A built-in function object is a wrapper around a C function. Examples of
670 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
671 standard built-in module). The number and type of the arguments are
672 determined by the C function. Special read-only attributes:
673 :attr:`__doc__` is the function's documentation string, or ``None`` if
674 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
675 set to ``None`` (but see the next item); :attr:`__module__` is the name of
676 the module the function was defined in or ``None`` if unavailable.
677
678 Built-in methods
679 .. index::
680 object: built-in method
681 object: method
682 pair: built-in; method
683
684 This is really a different disguise of a built-in function, this time containing
685 an object passed to the C function as an implicit extra argument. An example of
686 a built-in method is ``alist.append()``, assuming *alist* is a list object. In
687 this case, the special read-only attribute :attr:`__self__` is set to the object
688 denoted by *list*.
689
690 Class Types
691 Class types, or "new-style classes," are callable. These objects normally act
692 as factories for new instances of themselves, but variations are possible for
693 class types that override :meth:`__new__`. The arguments of the call are passed
694 to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize
695 the new instance.
696
697 Classic Classes
698 .. index::
699 single: __init__() (object method)
700 object: class
701 object: class instance
702 object: instance
703 pair: class object; call
704
705 Class objects are described below. When a class object is called, a new class
706 instance (also described below) is created and returned. This implies a call to
707 the class's :meth:`__init__` method if it has one. Any arguments are passed on
708 to the :meth:`__init__` method. If there is no :meth:`__init__` method, the
709 class must be called without arguments.
710
711 Class instances
712 Class instances are described below. Class instances are callable only when the
713 class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for
714 ``x.__call__(arguments)``.
715
716Modules
717 .. index::
718 statement: import
719 object: module
720
721 Modules are imported by the :keyword:`import` statement (see section
722 :ref:`import`). A module object has a
723 namespace implemented by a dictionary object (this is the dictionary referenced
724 by the func_globals attribute of functions defined in the module). Attribute
725 references are translated to lookups in this dictionary, e.g., ``m.x`` is
726 equivalent to ``m.__dict__["x"]``. A module object does not contain the code
727 object used to initialize the module (since it isn't needed once the
728 initialization is done).
729
Georg Brandl8ec7f652007-08-15 14:28:01 +0000730 Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
731 1`` is equivalent to ``m.__dict__["x"] = 1``.
732
733 .. index:: single: __dict__ (module attribute)
734
735 Special read-only attribute: :attr:`__dict__` is the module's namespace as a
736 dictionary object.
737
738 .. index::
739 single: __name__ (module attribute)
740 single: __doc__ (module attribute)
741 single: __file__ (module attribute)
742 pair: module; namespace
743
744 Predefined (writable) attributes: :attr:`__name__` is the module's name;
745 :attr:`__doc__` is the module's documentation string, or ``None`` if
746 unavailable; :attr:`__file__` is the pathname of the file from which the module
747 was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
748 present for C modules that are statically linked into the interpreter; for
749 extension modules loaded dynamically from a shared library, it is the pathname
750 of the shared library file.
751
752Classes
Nick Coghlana5107482008-08-04 12:40:59 +0000753 Both class types (new-style classes) and class objects (old-style/classic
754 classes) are typically created by class definitions (see section
755 :ref:`class`). A class has a namespace implemented by a dictionary object.
756 Class attribute references are translated to lookups in this dictionary, e.g.,
757 ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes
758 in particular there are a number of hooks which allow for other means of
759 locating attributes). When the attribute name is not found there, the
760 attribute search continues in the base classes. For old-style classes, the
761 search is depth-first, left-to-right in the order of occurrence in the base
762 class list. New-style classes use the more complex C3 method resolution
763 order which behaves correctly even in the presence of 'diamond'
764 inheritance structures where there are multiple inheritance paths
765 leading back to a common ancestor. Additional details on the C3 MRO used by
766 new-style classes can be found in the documentation accompanying the
767 2.3 release at http://www.python.org/download/releases/2.3/mro/.
768
769 .. XXX: Could we add that MRO doc as an appendix to the language ref?
Georg Brandl8ec7f652007-08-15 14:28:01 +0000770
771 .. index::
772 object: class
773 object: class instance
774 object: instance
775 pair: class object; call
776 single: container
777 object: dictionary
778 pair: class; attribute
779
780 When a class attribute reference (for class :class:`C`, say) would yield a
781 user-defined function object or an unbound user-defined method object whose
782 associated class is either :class:`C` or one of its base classes, it is
783 transformed into an unbound user-defined method object whose :attr:`im_class`
784 attribute is :class:`C`. When it would yield a class method object, it is
785 transformed into a bound user-defined method object whose :attr:`im_class`
786 and :attr:`im_self` attributes are both :class:`C`. When it would yield a
787 static method object, it is transformed into the object wrapped by the static
788 method object. See section :ref:`descriptors` for another way in which
789 attributes retrieved from a class may differ from those actually contained in
Nick Coghlana5107482008-08-04 12:40:59 +0000790 its :attr:`__dict__` (note that only new-style classes support descriptors).
Georg Brandl8ec7f652007-08-15 14:28:01 +0000791
792 .. index:: triple: class; attribute; assignment
793
794 Class attribute assignments update the class's dictionary, never the dictionary
795 of a base class.
796
797 .. index:: pair: class object; call
798
799 A class object can be called (see above) to yield a class instance (see below).
800
801 .. index::
802 single: __name__ (class attribute)
803 single: __module__ (class attribute)
804 single: __dict__ (class attribute)
805 single: __bases__ (class attribute)
806 single: __doc__ (class attribute)
807
808 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
809 the module name in which the class was defined; :attr:`__dict__` is the
810 dictionary containing the class's namespace; :attr:`__bases__` is a tuple
811 (possibly empty or a singleton) containing the base classes, in the order of
812 their occurrence in the base class list; :attr:`__doc__` is the class's
813 documentation string, or None if undefined.
814
815Class instances
816 .. index::
817 object: class instance
818 object: instance
819 pair: class; instance
820 pair: class instance; attribute
821
822 A class instance is created by calling a class object (see above). A class
823 instance has a namespace implemented as a dictionary which is the first place in
824 which attribute references are searched. When an attribute is not found there,
825 and the instance's class has an attribute by that name, the search continues
826 with the class attributes. If a class attribute is found that is a user-defined
827 function object or an unbound user-defined method object whose associated class
828 is the class (call it :class:`C`) of the instance for which the attribute
829 reference was initiated or one of its bases, it is transformed into a bound
830 user-defined method object whose :attr:`im_class` attribute is :class:`C` and
831 whose :attr:`im_self` attribute is the instance. Static method and class method
832 objects are also transformed, as if they had been retrieved from class
833 :class:`C`; see above under "Classes". See section :ref:`descriptors` for
834 another way in which attributes of a class retrieved via its instances may
835 differ from the objects actually stored in the class's :attr:`__dict__`. If no
836 class attribute is found, and the object's class has a :meth:`__getattr__`
837 method, that is called to satisfy the lookup.
838
839 .. index:: triple: class instance; attribute; assignment
840
841 Attribute assignments and deletions update the instance's dictionary, never a
842 class's dictionary. If the class has a :meth:`__setattr__` or
843 :meth:`__delattr__` method, this is called instead of updating the instance
844 dictionary directly.
845
846 .. index::
847 object: numeric
848 object: sequence
849 object: mapping
850
851 Class instances can pretend to be numbers, sequences, or mappings if they have
852 methods with certain special names. See section :ref:`specialnames`.
853
854 .. index::
855 single: __dict__ (instance attribute)
856 single: __class__ (instance attribute)
857
858 Special attributes: :attr:`__dict__` is the attribute dictionary;
859 :attr:`__class__` is the instance's class.
860
861Files
862 .. index::
863 object: file
864 builtin: open
865 single: popen() (in module os)
866 single: makefile() (socket method)
867 single: sys.stdin
868 single: sys.stdout
869 single: sys.stderr
870 single: stdio
871 single: stdin (in module sys)
872 single: stdout (in module sys)
873 single: stderr (in module sys)
874
875 A file object represents an open file. File objects are created by the
876 :func:`open` built-in function, and also by :func:`os.popen`,
877 :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
878 perhaps by other functions or methods provided by extension modules). The
879 objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
880 file objects corresponding to the interpreter's standard input, output and
881 error streams. See :ref:`bltin-file-objects` for complete documentation of
882 file objects.
883
884Internal types
885 .. index::
886 single: internal type
887 single: types, internal
888
889 A few types used internally by the interpreter are exposed to the user. Their
890 definitions may change with future versions of the interpreter, but they are
891 mentioned here for completeness.
892
893 Code objects
894 .. index::
895 single: bytecode
896 object: code
897
Georg Brandl63fa1682007-10-21 10:24:20 +0000898 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000899 The difference between a code object and a function object is that the function
900 object contains an explicit reference to the function's globals (the module in
901 which it was defined), while a code object contains no context; also the default
902 argument values are stored in the function object, not in the code object
903 (because they represent values calculated at run-time). Unlike function
904 objects, code objects are immutable and contain no references (directly or
905 indirectly) to mutable objects.
906
907 Special read-only attributes: :attr:`co_name` gives the function name;
908 :attr:`co_argcount` is the number of positional arguments (including arguments
909 with default values); :attr:`co_nlocals` is the number of local variables used
910 by the function (including arguments); :attr:`co_varnames` is a tuple containing
911 the names of the local variables (starting with the argument names);
912 :attr:`co_cellvars` is a tuple containing the names of local variables that are
913 referenced by nested functions; :attr:`co_freevars` is a tuple containing the
914 names of free variables; :attr:`co_code` is a string representing the sequence
915 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
916 used by the bytecode; :attr:`co_names` is a tuple containing the names used by
917 the bytecode; :attr:`co_filename` is the filename from which the code was
918 compiled; :attr:`co_firstlineno` is the first line number of the function;
Georg Brandl63fa1682007-10-21 10:24:20 +0000919 :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to
Georg Brandl8ec7f652007-08-15 14:28:01 +0000920 line numbers (for details see the source code of the interpreter);
921 :attr:`co_stacksize` is the required stack size (including local variables);
922 :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
923
924 .. index::
925 single: co_argcount (code object attribute)
926 single: co_code (code object attribute)
927 single: co_consts (code object attribute)
928 single: co_filename (code object attribute)
929 single: co_firstlineno (code object attribute)
930 single: co_flags (code object attribute)
931 single: co_lnotab (code object attribute)
932 single: co_name (code object attribute)
933 single: co_names (code object attribute)
934 single: co_nlocals (code object attribute)
935 single: co_stacksize (code object attribute)
936 single: co_varnames (code object attribute)
937 single: co_cellvars (code object attribute)
938 single: co_freevars (code object attribute)
939
940 .. index:: object: generator
941
942 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
943 the function uses the ``*arguments`` syntax to accept an arbitrary number of
944 positional arguments; bit ``0x08`` is set if the function uses the
945 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
946 if the function is a generator.
947
948 Future feature declarations (``from __future__ import division``) also use bits
949 in :attr:`co_flags` to indicate whether a code object was compiled with a
950 particular feature enabled: bit ``0x2000`` is set if the function was compiled
951 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
952 versions of Python.
953
954 Other bits in :attr:`co_flags` are reserved for internal use.
955
956 .. index:: single: documentation string
957
958 If a code object represents a function, the first item in :attr:`co_consts` is
959 the documentation string of the function, or ``None`` if undefined.
960
961 Frame objects
962 .. index:: object: frame
963
964 Frame objects represent execution frames. They may occur in traceback objects
965 (see below).
966
967 .. index::
968 single: f_back (frame attribute)
969 single: f_code (frame attribute)
970 single: f_globals (frame attribute)
971 single: f_locals (frame attribute)
972 single: f_lasti (frame attribute)
973 single: f_builtins (frame attribute)
974 single: f_restricted (frame attribute)
975
976 Special read-only attributes: :attr:`f_back` is to the previous stack frame
977 (towards the caller), or ``None`` if this is the bottom stack frame;
978 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
979 is the dictionary used to look up local variables; :attr:`f_globals` is used for
980 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
981 :attr:`f_restricted` is a flag indicating whether the function is executing in
982 restricted execution mode; :attr:`f_lasti` gives the precise instruction (this
983 is an index into the bytecode string of the code object).
984
985 .. index::
986 single: f_trace (frame attribute)
987 single: f_exc_type (frame attribute)
988 single: f_exc_value (frame attribute)
989 single: f_exc_traceback (frame attribute)
990 single: f_lineno (frame attribute)
991
992 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
993 called at the start of each source code line (this is used by the debugger);
994 :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
995 last exception raised in the parent frame provided another exception was ever
996 raised in the current frame (in all other cases they are None); :attr:`f_lineno`
997 is the current line number of the frame --- writing to this from within a trace
998 function jumps to the given line (only for the bottom-most frame). A debugger
999 can implement a Jump command (aka Set Next Statement) by writing to f_lineno.
1000
1001 Traceback objects
1002 .. index::
1003 object: traceback
1004 pair: stack; trace
1005 pair: exception; handler
1006 pair: execution; stack
1007 single: exc_info (in module sys)
1008 single: exc_traceback (in module sys)
1009 single: last_traceback (in module sys)
1010 single: sys.exc_info
1011 single: sys.exc_traceback
1012 single: sys.last_traceback
1013
1014 Traceback objects represent a stack trace of an exception. A traceback object
1015 is created when an exception occurs. When the search for an exception handler
1016 unwinds the execution stack, at each unwound level a traceback object is
1017 inserted in front of the current traceback. When an exception handler is
1018 entered, the stack trace is made available to the program. (See section
1019 :ref:`try`.) It is accessible as ``sys.exc_traceback``,
1020 and also as the third item of the tuple returned by ``sys.exc_info()``. The
1021 latter is the preferred interface, since it works correctly when the program is
1022 using multiple threads. When the program contains no suitable handler, the stack
1023 trace is written (nicely formatted) to the standard error stream; if the
1024 interpreter is interactive, it is also made available to the user as
1025 ``sys.last_traceback``.
1026
1027 .. index::
1028 single: tb_next (traceback attribute)
1029 single: tb_frame (traceback attribute)
1030 single: tb_lineno (traceback attribute)
1031 single: tb_lasti (traceback attribute)
1032 statement: try
1033
1034 Special read-only attributes: :attr:`tb_next` is the next level in the stack
1035 trace (towards the frame where the exception occurred), or ``None`` if there is
1036 no next level; :attr:`tb_frame` points to the execution frame of the current
1037 level; :attr:`tb_lineno` gives the line number where the exception occurred;
1038 :attr:`tb_lasti` indicates the precise instruction. The line number and last
1039 instruction in the traceback may differ from the line number of its frame object
1040 if the exception occurred in a :keyword:`try` statement with no matching except
1041 clause or with a finally clause.
1042
1043 Slice objects
1044 .. index:: builtin: slice
1045
1046 Slice objects are used to represent slices when *extended slice syntax* is used.
1047 This is a slice using two colons, or multiple slices or ellipses separated by
1048 commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are
1049 also created by the built-in :func:`slice` function.
1050
1051 .. index::
1052 single: start (slice object attribute)
1053 single: stop (slice object attribute)
1054 single: step (slice object attribute)
1055
1056 Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is
1057 the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.
1058 These attributes can have any type.
1059
1060 Slice objects support one method:
1061
1062
1063 .. method:: slice.indices(self, length)
1064
1065 This method takes a single integer argument *length* and computes information
1066 about the extended slice that the slice object would describe if applied to a
1067 sequence of *length* items. It returns a tuple of three integers; respectively
1068 these are the *start* and *stop* indices and the *step* or stride length of the
1069 slice. Missing or out-of-bounds indices are handled in a manner consistent with
1070 regular slices.
1071
1072 .. versionadded:: 2.3
1073
1074 Static method objects
1075 Static method objects provide a way of defeating the transformation of function
1076 objects to method objects described above. A static method object is a wrapper
1077 around any other object, usually a user-defined method object. When a static
1078 method object is retrieved from a class or a class instance, the object actually
1079 returned is the wrapped object, which is not subject to any further
1080 transformation. Static method objects are not themselves callable, although the
1081 objects they wrap usually are. Static method objects are created by the built-in
1082 :func:`staticmethod` constructor.
1083
1084 Class method objects
1085 A class method object, like a static method object, is a wrapper around another
1086 object that alters the way in which that object is retrieved from classes and
1087 class instances. The behaviour of class method objects upon such retrieval is
1088 described above, under "User-defined methods". Class method objects are created
1089 by the built-in :func:`classmethod` constructor.
1090
Georg Brandl8ec7f652007-08-15 14:28:01 +00001091
Georg Brandla7395032007-10-21 12:15:05 +00001092.. _newstyle:
Georg Brandl8ec7f652007-08-15 14:28:01 +00001093
1094New-style and classic classes
1095=============================
1096
Nick Coghlana5107482008-08-04 12:40:59 +00001097Classes and instances come in two flavors: old-style (or classic) and new-style.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001098
1099Up to Python 2.1, old-style classes were the only flavour available to the user.
1100The concept of (old-style) class is unrelated to the concept of type: if *x* is
1101an instance of an old-style class, then ``x.__class__`` designates the class of
1102*x*, but ``type(x)`` is always ``<type 'instance'>``. This reflects the fact
1103that all old-style instances, independently of their class, are implemented with
1104a single built-in type, called ``instance``.
1105
1106New-style classes were introduced in Python 2.2 to unify classes and types. A
Georg Brandl63cdb862008-02-03 12:29:00 +00001107new-style class is neither more nor less than a user-defined type. If *x* is an
Nick Coghlana5107482008-08-04 12:40:59 +00001108instance of a new-style class, then ``type(x)`` is typically the same as
1109``x.__class__`` (although this is not guaranteed - a new-style class instance is
1110permitted to override the value returned for ``x.__class__``).
Georg Brandl8ec7f652007-08-15 14:28:01 +00001111
1112The major motivation for introducing new-style classes is to provide a unified
Nick Coghlana5107482008-08-04 12:40:59 +00001113object model with a full meta-model. It also has a number of practical
Georg Brandl8ec7f652007-08-15 14:28:01 +00001114benefits, like the ability to subclass most built-in types, or the introduction
1115of "descriptors", which enable computed properties.
1116
1117For compatibility reasons, classes are still old-style by default. New-style
1118classes are created by specifying another new-style class (i.e. a type) as a
1119parent class, or the "top-level type" :class:`object` if no other parent is
1120needed. The behaviour of new-style classes differs from that of old-style
1121classes in a number of important details in addition to what :func:`type`
1122returns. Some of these changes are fundamental to the new object model, like
1123the way special methods are invoked. Others are "fixes" that could not be
1124implemented before for compatibility concerns, like the method resolution order
1125in case of multiple inheritance.
1126
Nick Coghlana5107482008-08-04 12:40:59 +00001127While this manual aims to provide comprehensive coverage of Python's class
1128mechanics, it may still be lacking in some areas when it comes to its coverage
1129of new-style classes. Please see http://www.python.org/doc/newstyle/ for
1130sources of additional information.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001131
1132.. index::
Georg Brandl62658332008-01-05 19:29:45 +00001133 single: class; new-style
1134 single: class; classic
1135 single: class; old-style
Georg Brandl8ec7f652007-08-15 14:28:01 +00001136
Nick Coghlana5107482008-08-04 12:40:59 +00001137Old-style classes are removed in Python 3.0, leaving only the semantics of
1138new-style classes.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001139
Georg Brandl8ec7f652007-08-15 14:28:01 +00001140
1141.. _specialnames:
1142
1143Special method names
1144====================
1145
1146.. index::
1147 pair: operator; overloading
1148 single: __getitem__() (mapping object method)
1149
1150A class can implement certain operations that are invoked by special syntax
1151(such as arithmetic operations or subscripting and slicing) by defining methods
1152with special names. This is Python's approach to :dfn:`operator overloading`,
1153allowing classes to define their own behavior with respect to language
1154operators. For instance, if a class defines a method named :meth:`__getitem__`,
Nick Coghlana5107482008-08-04 12:40:59 +00001155and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
1156to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)``
1157for new-style classes. Except where mentioned, attempts to execute an
1158operation raise an exception when no appropriate method is defined (typically
1159:exc:`AttributeError` or :exc:`TypeError`).
Georg Brandl5768d572007-09-05 13:36:44 +00001160
Georg Brandl8ec7f652007-08-15 14:28:01 +00001161When implementing a class that emulates any built-in type, it is important that
1162the emulation only be implemented to the degree that it makes sense for the
1163object being modelled. For example, some sequences may work well with retrieval
1164of individual elements, but extracting a slice may not make sense. (One example
1165of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
1166
1167
1168.. _customization:
1169
1170Basic customization
1171-------------------
1172
Georg Brandl8ec7f652007-08-15 14:28:01 +00001173.. method:: object.__new__(cls[, ...])
1174
Georg Brandl3fc42262008-12-05 08:06:57 +00001175 .. index:: pair: subclassing; immutable types
1176
Georg Brandl8ec7f652007-08-15 14:28:01 +00001177 Called to create a new instance of class *cls*. :meth:`__new__` is a static
1178 method (special-cased so you need not declare it as such) that takes the class
1179 of which an instance was requested as its first argument. The remaining
1180 arguments are those passed to the object constructor expression (the call to the
1181 class). The return value of :meth:`__new__` should be the new object instance
1182 (usually an instance of *cls*).
1183
1184 Typical implementations create a new instance of the class by invoking the
1185 superclass's :meth:`__new__` method using ``super(currentclass,
1186 cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
1187 newly-created instance as necessary before returning it.
1188
1189 If :meth:`__new__` returns an instance of *cls*, then the new instance's
1190 :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
1191 *self* is the new instance and the remaining arguments are the same as were
1192 passed to :meth:`__new__`.
1193
1194 If :meth:`__new__` does not return an instance of *cls*, then the new instance's
1195 :meth:`__init__` method will not be invoked.
1196
1197 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
Georg Brandl3ccb49a2008-01-07 19:17:10 +00001198 int, str, or tuple) to customize instance creation. It is also commonly
1199 overridden in custom metaclasses in order to customize class creation.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001200
1201
1202.. method:: object.__init__(self[, ...])
1203
1204 .. index:: pair: class; constructor
1205
1206 Called when the instance is created. The arguments are those passed to the
1207 class constructor expression. If a base class has an :meth:`__init__` method,
1208 the derived class's :meth:`__init__` method, if any, must explicitly call it to
1209 ensure proper initialization of the base class part of the instance; for
1210 example: ``BaseClass.__init__(self, [args...])``. As a special constraint on
1211 constructors, no value may be returned; doing so will cause a :exc:`TypeError`
1212 to be raised at runtime.
1213
1214
1215.. method:: object.__del__(self)
1216
1217 .. index::
1218 single: destructor
1219 statement: del
1220
1221 Called when the instance is about to be destroyed. This is also called a
1222 destructor. If a base class has a :meth:`__del__` method, the derived class's
1223 :meth:`__del__` method, if any, must explicitly call it to ensure proper
1224 deletion of the base class part of the instance. Note that it is possible
1225 (though not recommended!) for the :meth:`__del__` method to postpone destruction
1226 of the instance by creating a new reference to it. It may then be called at a
1227 later time when this new reference is deleted. It is not guaranteed that
1228 :meth:`__del__` methods are called for objects that still exist when the
1229 interpreter exits.
1230
1231 .. note::
1232
1233 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
1234 the reference count for ``x`` by one, and the latter is only called when
1235 ``x``'s reference count reaches zero. Some common situations that may
1236 prevent the reference count of an object from going to zero include:
1237 circular references between objects (e.g., a doubly-linked list or a tree
1238 data structure with parent and child pointers); a reference to the object
1239 on the stack frame of a function that caught an exception (the traceback
1240 stored in ``sys.exc_traceback`` keeps the stack frame alive); or a
1241 reference to the object on the stack frame that raised an unhandled
1242 exception in interactive mode (the traceback stored in
1243 ``sys.last_traceback`` keeps the stack frame alive). The first situation
1244 can only be remedied by explicitly breaking the cycles; the latter two
1245 situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or
1246 ``sys.last_traceback``. Circular references which are garbage are
1247 detected when the option cycle detector is enabled (it's on by default),
1248 but can only be cleaned up if there are no Python-level :meth:`__del__`
1249 methods involved. Refer to the documentation for the :mod:`gc` module for
1250 more information about how :meth:`__del__` methods are handled by the
1251 cycle detector, particularly the description of the ``garbage`` value.
1252
1253 .. warning::
1254
1255 Due to the precarious circumstances under which :meth:`__del__` methods are
1256 invoked, exceptions that occur during their execution are ignored, and a warning
1257 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
1258 response to a module being deleted (e.g., when execution of the program is
1259 done), other globals referenced by the :meth:`__del__` method may already have
Brett Cannon5b0d5532009-01-29 00:54:11 +00001260 been deleted or in the process of being torn down (e.g. the import
1261 machinery shutting down). For this reason, :meth:`__del__` methods
1262 should do the absolute
Georg Brandl8ec7f652007-08-15 14:28:01 +00001263 minimum needed to maintain external invariants. Starting with version 1.5,
1264 Python guarantees that globals whose name begins with a single underscore are
1265 deleted from their module before other globals are deleted; if no other
1266 references to such globals exist, this may help in assuring that imported
1267 modules are still available at the time when the :meth:`__del__` method is
1268 called.
1269
1270
1271.. method:: object.__repr__(self)
1272
1273 .. index:: builtin: repr
1274
1275 Called by the :func:`repr` built-in function and by string conversions (reverse
1276 quotes) to compute the "official" string representation of an object. If at all
1277 possible, this should look like a valid Python expression that could be used to
1278 recreate an object with the same value (given an appropriate environment). If
1279 this is not possible, a string of the form ``<...some useful description...>``
1280 should be returned. The return value must be a string object. If a class
1281 defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also
1282 used when an "informal" string representation of instances of that class is
1283 required.
1284
1285 .. index::
1286 pair: string; conversion
1287 pair: reverse; quotes
1288 pair: backward; quotes
1289 single: back-quotes
1290
1291 This is typically used for debugging, so it is important that the representation
1292 is information-rich and unambiguous.
1293
1294
1295.. method:: object.__str__(self)
1296
1297 .. index::
1298 builtin: str
1299 statement: print
1300
1301 Called by the :func:`str` built-in function and by the :keyword:`print`
1302 statement to compute the "informal" string representation of an object. This
1303 differs from :meth:`__repr__` in that it does not have to be a valid Python
1304 expression: a more convenient or concise representation may be used instead.
1305 The return value must be a string object.
1306
1307
1308.. method:: object.__lt__(self, other)
1309 object.__le__(self, other)
1310 object.__eq__(self, other)
1311 object.__ne__(self, other)
1312 object.__gt__(self, other)
1313 object.__ge__(self, other)
1314
1315 .. versionadded:: 2.1
1316
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001317 .. index::
1318 single: comparisons
1319
Georg Brandl8ec7f652007-08-15 14:28:01 +00001320 These are the so-called "rich comparison" methods, and are called for comparison
1321 operators in preference to :meth:`__cmp__` below. The correspondence between
1322 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
1323 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` and
1324 ``x<>y`` call ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
1325 ``x.__ge__(y)``.
1326
1327 A rich comparison method may return the singleton ``NotImplemented`` if it does
1328 not implement the operation for a given pair of arguments. By convention,
1329 ``False`` and ``True`` are returned for a successful comparison. However, these
1330 methods can return any value, so if the comparison operator is used in a Boolean
1331 context (e.g., in the condition of an ``if`` statement), Python will call
1332 :func:`bool` on the value to determine if the result is true or false.
1333
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001334 There are no implied relationships among the comparison operators. The truth
1335 of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when
1336 defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
1337 operators will behave as expected. See the paragraph on :meth:`__hash__` for
1338 some important notes on creating :term:`hashable` objects which support
1339 custom comparison operations and are usable as dictionary keys.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001340
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001341 There are no swapped-argument versions of these methods (to be used when the
1342 left argument does not support the operation but the right argument does);
1343 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
Georg Brandl8ec7f652007-08-15 14:28:01 +00001344 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
1345 :meth:`__eq__` and :meth:`__ne__` are their own reflection.
1346
1347 Arguments to rich comparison methods are never coerced.
1348
1349
1350.. method:: object.__cmp__(self, other)
1351
1352 .. index::
1353 builtin: cmp
1354 single: comparisons
1355
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001356 Called by comparison operations if rich comparison (see above) is not
1357 defined. Should return a negative integer if ``self < other``, zero if
1358 ``self == other``, a positive integer if ``self > other``. If no
1359 :meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class
1360 instances are compared by object identity ("address"). See also the
1361 description of :meth:`__hash__` for some important notes on creating
1362 :term:`hashable` objects which support custom comparison operations and are
1363 usable as dictionary keys. (Note: the restriction that exceptions are not
1364 propagated by :meth:`__cmp__` has been removed since Python 1.5.)
Georg Brandl8ec7f652007-08-15 14:28:01 +00001365
1366
1367.. method:: object.__rcmp__(self, other)
1368
1369 .. versionchanged:: 2.1
1370 No longer supported.
1371
1372
1373.. method:: object.__hash__(self)
1374
1375 .. index::
1376 object: dictionary
1377 builtin: hash
1378
Benjamin Peterson233bb002008-11-17 22:05:19 +00001379 Called by built-in function :func:`hash` and for operations on members of
1380 hashed collections including :class:`set`, :class:`frozenset`, and
1381 :class:`dict`. :meth:`__hash__` should return an integer. The only required
1382 property is that objects which compare equal have the same hash value; it is
1383 advised to somehow mix together (e.g. using exclusive or) the hash values for
1384 the components of the object that also play a part in comparison of objects.
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001385
1386 If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
1387 should not define a :meth:`__hash__` operation either; if it defines
1388 :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances
Benjamin Peterson233bb002008-11-17 22:05:19 +00001389 will not be usable in hashed collections. If a class defines mutable objects
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001390 and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
Benjamin Peterson233bb002008-11-17 22:05:19 +00001391 implement :meth:`__hash__`, since hashable collection implementations require
1392 that a object's hash value is immutable (if the object's hash value changes,
1393 it will be in the wrong hash bucket).
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001394
1395 User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
Nick Coghlan82358692008-08-31 13:10:50 +00001396 by default; with them, all objects compare unequal (except with themselves)
1397 and ``x.__hash__()`` returns ``id(x)``.
1398
1399 Classes which inherit a :meth:`__hash__` method from a parent class but
1400 change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash
1401 value returned is no longer appropriate (e.g. by switching to a value-based
1402 concept of equality instead of the default identity based equality) can
Benjamin Peterson233bb002008-11-17 22:05:19 +00001403 explicitly flag themselves as being unhashable by setting ``__hash__ = None``
1404 in the class definition. Doing so means that not only will instances of the
1405 class raise an appropriate :exc:`TypeError` when a program attempts to
1406 retrieve their hash value, but they will also be correctly identified as
1407 unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike
1408 classes which define their own :meth:`__hash__` to explicitly raise
1409 :exc:`TypeError`).
Georg Brandl8ec7f652007-08-15 14:28:01 +00001410
1411 .. versionchanged:: 2.5
Georg Brandl7c3e79f2007-11-02 20:06:17 +00001412 :meth:`__hash__` may now also return a long integer object; the 32-bit
1413 integer is then derived from the hash of that object.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001414
Nick Coghlan82358692008-08-31 13:10:50 +00001415 .. versionchanged:: 2.6
1416 :attr:`__hash__` may now be set to :const:`None` to explicitly flag
1417 instances of a class as unhashable.
1418
Georg Brandl8ec7f652007-08-15 14:28:01 +00001419
1420.. method:: object.__nonzero__(self)
1421
1422 .. index:: single: __len__() (mapping object method)
1423
1424 Called to implement truth value testing, and the built-in operation ``bool()``;
1425 should return ``False`` or ``True``, or their integer equivalents ``0`` or
1426 ``1``. When this method is not defined, :meth:`__len__` is called, if it is
1427 defined (see below). If a class defines neither :meth:`__len__` nor
1428 :meth:`__nonzero__`, all its instances are considered true.
1429
1430
1431.. method:: object.__unicode__(self)
1432
1433 .. index:: builtin: unicode
1434
1435 Called to implement :func:`unicode` builtin; should return a Unicode object.
1436 When this method is not defined, string conversion is attempted, and the result
1437 of string conversion is converted to Unicode using the system default encoding.
1438
1439
1440.. _attribute-access:
1441
1442Customizing attribute access
1443----------------------------
1444
1445The following methods can be defined to customize the meaning of attribute
1446access (use of, assignment to, or deletion of ``x.name``) for class instances.
1447
1448
1449.. method:: object.__getattr__(self, name)
1450
1451 Called when an attribute lookup has not found the attribute in the usual places
1452 (i.e. it is not an instance attribute nor is it found in the class tree for
1453 ``self``). ``name`` is the attribute name. This method should return the
1454 (computed) attribute value or raise an :exc:`AttributeError` exception.
1455
1456 .. index:: single: __setattr__() (object method)
1457
1458 Note that if the attribute is found through the normal mechanism,
1459 :meth:`__getattr__` is not called. (This is an intentional asymmetry between
1460 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
Georg Brandlc1768142008-08-30 09:52:44 +00001461 reasons and because otherwise :meth:`__getattr__` would have no way to access
Georg Brandl8ec7f652007-08-15 14:28:01 +00001462 other attributes of the instance. Note that at least for instance variables,
1463 you can fake total control by not inserting any values in the instance attribute
1464 dictionary (but instead inserting them in another object). See the
1465 :meth:`__getattribute__` method below for a way to actually get total control in
1466 new-style classes.
1467
1468
1469.. method:: object.__setattr__(self, name, value)
1470
1471 Called when an attribute assignment is attempted. This is called instead of the
1472 normal mechanism (i.e. store the value in the instance dictionary). *name* is
1473 the attribute name, *value* is the value to be assigned to it.
1474
1475 .. index:: single: __dict__ (instance attribute)
1476
1477 If :meth:`__setattr__` wants to assign to an instance attribute, it should not
1478 simply execute ``self.name = value`` --- this would cause a recursive call to
1479 itself. Instead, it should insert the value in the dictionary of instance
1480 attributes, e.g., ``self.__dict__[name] = value``. For new-style classes,
1481 rather than accessing the instance dictionary, it should call the base class
1482 method with the same name, for example, ``object.__setattr__(self, name,
1483 value)``.
1484
1485
1486.. method:: object.__delattr__(self, name)
1487
1488 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
1489 should only be implemented if ``del obj.name`` is meaningful for the object.
1490
1491
1492.. _new-style-attribute-access:
1493
1494More attribute access for new-style classes
1495^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1496
1497The following methods only apply to new-style classes.
1498
1499
1500.. method:: object.__getattribute__(self, name)
1501
1502 Called unconditionally to implement attribute accesses for instances of the
1503 class. If the class also defines :meth:`__getattr__`, the latter will not be
1504 called unless :meth:`__getattribute__` either calls it explicitly or raises an
1505 :exc:`AttributeError`. This method should return the (computed) attribute value
1506 or raise an :exc:`AttributeError` exception. In order to avoid infinite
1507 recursion in this method, its implementation should always call the base class
1508 method with the same name to access any attributes it needs, for example,
1509 ``object.__getattribute__(self, name)``.
1510
Nick Coghlana5107482008-08-04 12:40:59 +00001511 .. note::
1512
1513 This method may still be bypassed when looking up special methods as the
1514 result of implicit invocation via language syntax or builtin functions.
1515 See :ref:`new-style-special-lookup`.
1516
Georg Brandl8ec7f652007-08-15 14:28:01 +00001517
1518.. _descriptors:
1519
1520Implementing Descriptors
1521^^^^^^^^^^^^^^^^^^^^^^^^
1522
1523The following methods only apply when an instance of the class containing the
1524method (a so-called *descriptor* class) appears in the class dictionary of
1525another new-style class, known as the *owner* class. In the examples below, "the
1526attribute" refers to the attribute whose name is the key of the property in the
1527owner class' ``__dict__``. Descriptors can only be implemented as new-style
1528classes themselves.
1529
1530
1531.. method:: object.__get__(self, instance, owner)
1532
1533 Called to get the attribute of the owner class (class attribute access) or of an
1534 instance of that class (instance attribute access). *owner* is always the owner
1535 class, while *instance* is the instance that the attribute was accessed through,
1536 or ``None`` when the attribute is accessed through the *owner*. This method
1537 should return the (computed) attribute value or raise an :exc:`AttributeError`
1538 exception.
1539
1540
1541.. method:: object.__set__(self, instance, value)
1542
1543 Called to set the attribute on an instance *instance* of the owner class to a
1544 new value, *value*.
1545
1546
1547.. method:: object.__delete__(self, instance)
1548
1549 Called to delete the attribute on an instance *instance* of the owner class.
1550
1551
1552.. _descriptor-invocation:
1553
1554Invoking Descriptors
1555^^^^^^^^^^^^^^^^^^^^
1556
1557In general, a descriptor is an object attribute with "binding behavior", one
1558whose attribute access has been overridden by methods in the descriptor
1559protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
1560those methods are defined for an object, it is said to be a descriptor.
1561
1562The default behavior for attribute access is to get, set, or delete the
1563attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
1564starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
1565continuing through the base classes of ``type(a)`` excluding metaclasses.
1566
1567However, if the looked-up value is an object defining one of the descriptor
1568methods, then Python may override the default behavior and invoke the descriptor
1569method instead. Where this occurs in the precedence chain depends on which
1570descriptor methods were defined and how they were called. Note that descriptors
1571are only invoked for new style objects or classes (ones that subclass
1572:class:`object()` or :class:`type()`).
1573
1574The starting point for descriptor invocation is a binding, ``a.x``. How the
1575arguments are assembled depends on ``a``:
1576
1577Direct Call
1578 The simplest and least common call is when user code directly invokes a
1579 descriptor method: ``x.__get__(a)``.
1580
1581Instance Binding
1582 If binding to a new-style object instance, ``a.x`` is transformed into the call:
1583 ``type(a).__dict__['x'].__get__(a, type(a))``.
1584
1585Class Binding
1586 If binding to a new-style class, ``A.x`` is transformed into the call:
1587 ``A.__dict__['x'].__get__(None, A)``.
1588
1589Super Binding
1590 If ``a`` is an instance of :class:`super`, then the binding ``super(B,
1591 obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
1592 immediately preceding ``B`` and then invokes the descriptor with the call:
1593 ``A.__dict__['m'].__get__(obj, A)``.
1594
1595For instance bindings, the precedence of descriptor invocation depends on the
Georg Brandl37614222007-08-23 21:42:54 +00001596which descriptor methods are defined. Normally, data descriptors define both
1597:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the
Georg Brandl8ec7f652007-08-15 14:28:01 +00001598:meth:`__get__` method. Data descriptors always override a redefinition in an
1599instance dictionary. In contrast, non-data descriptors can be overridden by
Georg Brandl37614222007-08-23 21:42:54 +00001600instances. [#]_
Georg Brandl8ec7f652007-08-15 14:28:01 +00001601
1602Python methods (including :func:`staticmethod` and :func:`classmethod`) are
1603implemented as non-data descriptors. Accordingly, instances can redefine and
1604override methods. This allows individual instances to acquire behaviors that
1605differ from other instances of the same class.
1606
1607The :func:`property` function is implemented as a data descriptor. Accordingly,
1608instances cannot override the behavior of a property.
1609
1610
1611.. _slots:
1612
1613__slots__
1614^^^^^^^^^
1615
1616By default, instances of both old and new-style classes have a dictionary for
1617attribute storage. This wastes space for objects having very few instance
1618variables. The space consumption can become acute when creating large numbers
1619of instances.
1620
1621The default can be overridden by defining *__slots__* in a new-style class
1622definition. The *__slots__* declaration takes a sequence of instance variables
1623and reserves just enough space in each instance to hold a value for each
1624variable. Space is saved because *__dict__* is not created for each instance.
1625
1626
1627.. data:: __slots__
1628
1629 This class variable can be assigned a string, iterable, or sequence of strings
1630 with variable names used by instances. If defined in a new-style class,
1631 *__slots__* reserves space for the declared variables and prevents the automatic
1632 creation of *__dict__* and *__weakref__* for each instance.
1633
1634 .. versionadded:: 2.2
1635
1636Notes on using *__slots__*
1637
Georg Brandl3de1e692008-07-19 13:09:42 +00001638* When inheriting from a class without *__slots__*, the *__dict__* attribute of
1639 that class will always be accessible, so a *__slots__* definition in the
1640 subclass is meaningless.
1641
Georg Brandl8ec7f652007-08-15 14:28:01 +00001642* Without a *__dict__* variable, instances cannot be assigned new variables not
1643 listed in the *__slots__* definition. Attempts to assign to an unlisted
1644 variable name raises :exc:`AttributeError`. If dynamic assignment of new
1645 variables is desired, then add ``'__dict__'`` to the sequence of strings in the
1646 *__slots__* declaration.
1647
1648 .. versionchanged:: 2.3
1649 Previously, adding ``'__dict__'`` to the *__slots__* declaration would not
1650 enable the assignment of new attributes not specifically listed in the sequence
1651 of instance variable names.
1652
1653* Without a *__weakref__* variable for each instance, classes defining
1654 *__slots__* do not support weak references to its instances. If weak reference
1655 support is needed, then add ``'__weakref__'`` to the sequence of strings in the
1656 *__slots__* declaration.
1657
1658 .. versionchanged:: 2.3
1659 Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not
1660 enable support for weak references.
1661
1662* *__slots__* are implemented at the class level by creating descriptors
1663 (:ref:`descriptors`) for each variable name. As a result, class attributes
1664 cannot be used to set default values for instance variables defined by
1665 *__slots__*; otherwise, the class attribute would overwrite the descriptor
1666 assignment.
1667
1668* If a class defines a slot also defined in a base class, the instance variable
1669 defined by the base class slot is inaccessible (except by retrieving its
1670 descriptor directly from the base class). This renders the meaning of the
1671 program undefined. In the future, a check may be added to prevent this.
1672
1673* The action of a *__slots__* declaration is limited to the class where it is
1674 defined. As a result, subclasses will have a *__dict__* unless they also define
1675 *__slots__*.
1676
Benjamin Petersonc756dcd2008-10-23 21:43:48 +00001677* Nonempty *__slots__* does not work for classes derived from "variable-length"
1678 built-in types such as :class:`long`, :class:`str` and :class:`tuple`.
Georg Brandl8ec7f652007-08-15 14:28:01 +00001679
1680* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
1681 used; however, in the future, special meaning may be assigned to the values
1682 corresponding to each key.
1683
1684* *__class__* assignment works only if both classes have the same *__slots__*.
1685
1686 .. versionchanged:: 2.6
1687 Previously, *__class__* assignment raised an error if either new or old class
1688 had *__slots__*.
1689
1690
1691.. _metaclasses:
1692
1693Customizing class creation
1694--------------------------
1695
1696By default, new-style classes are constructed using :func:`type`. A class
1697definition is read into a separate namespace and the value of class name is
1698bound to the result of ``type(name, bases, dict)``.
1699
1700When the class definition is read, if *__metaclass__* is defined then the
Georg Brandl3ccb49a2008-01-07 19:17:10 +00001701callable assigned to it will be called instead of :func:`type`. This allows
Georg Brandl8ec7f652007-08-15 14:28:01 +00001702classes or functions to be written which monitor or alter the class creation
1703process:
1704
1705* Modifying the class dictionary prior to the class being created.
1706
1707* Returning an instance of another class -- essentially performing the role of a
1708 factory function.
1709
Georg Brandl3ccb49a2008-01-07 19:17:10 +00001710These steps will have to be performed in the metaclass's :meth:`__new__` method
1711-- :meth:`type.__new__` can then be called from this method to create a class
1712with different properties. This example adds a new element to the class
1713dictionary before creating the class::
1714
1715 class metacls(type):
1716 def __new__(mcs, name, bases, dict):
1717 dict['foo'] = 'metacls was here'
1718 return type.__new__(mcs, name, bases, dict)
1719
1720You can of course also override other class methods (or add new methods); for
1721example defining a custom :meth:`__call__` method in the metaclass allows custom
1722behavior when the class is called, e.g. not always creating a new instance.
1723
Georg Brandl8ec7f652007-08-15 14:28:01 +00001724
1725.. data:: __metaclass__
1726
1727 This variable can be any callable accepting arguments for ``name``, ``bases``,
1728 and ``dict``. Upon class creation, the callable is used instead of the built-in
1729 :func:`type`.
1730
1731 .. versionadded:: 2.2
1732
1733The appropriate metaclass is determined by the following precedence rules:
1734
1735* If ``dict['__metaclass__']`` exists, it is used.
1736
1737* Otherwise, if there is at least one base class, its metaclass is used (this
1738 looks for a *__class__* attribute first and if not found, uses its type).
1739
1740* Otherwise, if a global variable named __metaclass__ exists, it is used.
1741
1742* Otherwise, the old-style, classic metaclass (types.ClassType) is used.
1743
1744The potential uses for metaclasses are boundless. Some ideas that have been
1745explored including logging, interface checking, automatic delegation, automatic
1746property creation, proxies, frameworks, and automatic resource
1747locking/synchronization.
1748
1749
1750.. _callable-types:
1751
1752Emulating callable objects
1753--------------------------
1754
1755
1756.. method:: object.__call__(self[, args...])
1757
1758 .. index:: pair: call; instance
1759
1760 Called when the instance is "called" as a function; if this method is defined,
1761 ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
1762
1763
1764.. _sequence-types:
1765
1766Emulating container types
1767-------------------------
1768
1769The following methods can be defined to implement container objects. Containers
1770usually are sequences (such as lists or tuples) or mappings (like dictionaries),
1771but can represent other containers as well. The first set of methods is used
1772either to emulate a sequence or to emulate a mapping; the difference is that for
1773a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
1774N`` where *N* is the length of the sequence, or slice objects, which define a
1775range of items. (For backwards compatibility, the method :meth:`__getslice__`
1776(see below) can also be defined to handle simple, but not extended slices.) It
1777is also recommended that mappings provide the methods :meth:`keys`,
1778:meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
1779:meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
1780:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar
1781to those for Python's standard dictionary objects. The :mod:`UserDict` module
1782provides a :class:`DictMixin` class to help create those methods from a base set
1783of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
1784:meth:`keys`. Mutable sequences should provide methods :meth:`append`,
1785:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
1786:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
1787objects. Finally, sequence types should implement addition (meaning
1788concatenation) and multiplication (meaning repetition) by defining the methods
1789:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
1790:meth:`__rmul__` and :meth:`__imul__` described below; they should not define
1791:meth:`__coerce__` or other numerical operators. It is recommended that both
1792mappings and sequences implement the :meth:`__contains__` method to allow
1793efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent
1794of :meth:`has_key`; for sequences, it should search through the values. It is
1795further recommended that both mappings and sequences implement the
1796:meth:`__iter__` method to allow efficient iteration through the container; for
1797mappings, :meth:`__iter__` should be the same as :meth:`iterkeys`; for
1798sequences, it should iterate through the values.
1799
1800
1801.. method:: object.__len__(self)
1802
1803 .. index::
1804 builtin: len
1805 single: __nonzero__() (object method)
1806
1807 Called to implement the built-in function :func:`len`. Should return the length
1808 of the object, an integer ``>=`` 0. Also, an object that doesn't define a
1809 :meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is
1810 considered to be false in a Boolean context.
1811
1812
1813.. method:: object.__getitem__(self, key)
1814
1815 .. index:: object: slice
1816
1817 Called to implement evaluation of ``self[key]``. For sequence types, the
1818 accepted keys should be integers and slice objects. Note that the special
1819 interpretation of negative indexes (if the class wishes to emulate a sequence
1820 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
1821 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
1822 for the sequence (after any special interpretation of negative values),
1823 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
1824 in the container), :exc:`KeyError` should be raised.
1825
1826 .. note::
1827
1828 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
1829 indexes to allow proper detection of the end of the sequence.
1830
1831
1832.. method:: object.__setitem__(self, key, value)
1833
1834 Called to implement assignment to ``self[key]``. Same note as for
1835 :meth:`__getitem__`. This should only be implemented for mappings if the
1836 objects support changes to the values for keys, or if new keys can be added, or
1837 for sequences if elements can be replaced. The same exceptions should be raised
1838 for improper *key* values as for the :meth:`__getitem__` method.
1839
1840
1841.. method:: object.__delitem__(self, key)
1842
1843 Called to implement deletion of ``self[key]``. Same note as for
1844 :meth:`__getitem__`. This should only be implemented for mappings if the
1845 objects support removal of keys, or for sequences if elements can be removed
1846 from the sequence. The same exceptions should be raised for improper *key*
1847 values as for the :meth:`__getitem__` method.
1848
1849
1850.. method:: object.__iter__(self)
1851
1852 This method is called when an iterator is required for a container. This method
1853 should return a new iterator object that can iterate over all the objects in the
1854 container. For mappings, it should iterate over the keys of the container, and
1855 should also be made available as the method :meth:`iterkeys`.
1856
1857 Iterator objects also need to implement this method; they are required to return
1858 themselves. For more information on iterator objects, see :ref:`typeiter`.
1859
Georg Brandl81de0d22008-01-06 16:17:56 +00001860
1861.. method:: object.__reversed__(self)
1862
1863 Called (if present) by the :func:`reversed` builtin to implement
1864 reverse iteration. It should return a new iterator object that iterates
1865 over all the objects in the container in reverse order.
1866
1867 If the :meth:`__reversed__` method is not provided, the
1868 :func:`reversed` builtin will fall back to using the sequence protocol
1869 (:meth:`__len__` and :meth:`__getitem__`). Objects should normally
1870 only provide :meth:`__reversed__` if they do not support the sequence
1871 protocol and an efficient implementation of reverse iteration is possible.
1872
1873 .. versionadded:: 2.6
1874
1875
Georg Brandl8ec7f652007-08-15 14:28:01 +00001876The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
1877implemented as an iteration through a sequence. However, container objects can
1878supply the following special method with a more efficient implementation, which
1879also does not require the object be a sequence.
1880
1881
1882.. method:: object.__contains__(self, item)
1883
1884 Called to implement membership test operators. Should return true if *item* is
1885 in *self*, false otherwise. For mapping objects, this should consider the keys
1886 of the mapping rather than the values or the key-item pairs.
1887
1888
1889.. _sequence-methods:
1890
1891Additional methods for emulation of sequence types
1892--------------------------------------------------
1893
1894The following optional methods can be defined to further emulate sequence
1895objects. Immutable sequences methods should at most only define
1896:meth:`__getslice__`; mutable sequences might define all three methods.
1897
1898
1899.. method:: object.__getslice__(self, i, j)
1900
1901 .. deprecated:: 2.0
1902 Support slice objects as parameters to the :meth:`__getitem__` method.
Georg Brandl8d9e8452007-08-23 20:35:00 +00001903 (However, built-in types in CPython currently still implement
1904 :meth:`__getslice__`. Therefore, you have to override it in derived
1905 classes when implementing slicing.)
Georg Brandl8ec7f652007-08-15 14:28:01 +00001906
1907 Called to implement evaluation of ``self[i:j]``. The returned object should be
1908 of the same type as *self*. Note that missing *i* or *j* in the slice
1909 expression are replaced by zero or ``sys.maxint``, respectively. If negative
1910 indexes are used in the slice, the length of the sequence is added to that
1911 index. If the instance does not implement the :meth:`__len__` method, an
1912 :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this
1913 way are not still negative. Indexes which are greater than the length of the
1914 sequence are not modified. If no :meth:`__getslice__` is found, a slice object
1915 is created instead, and passed to :meth:`__getitem__` instead.
1916
1917
1918.. method:: object.__setslice__(self, i, j, sequence)
1919
1920 Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
1921 for :meth:`__getslice__`.
1922
1923 This method is deprecated. If no :meth:`__setslice__` is found, or for extended
1924 slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
1925 :meth:`__setitem__`, instead of :meth:`__setslice__` being called.
1926
1927
1928.. method:: object.__delslice__(self, i, j)
1929
1930 Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
1931 :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
1932 found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
1933 created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
1934 being called.
1935
1936Notice that these methods are only invoked when a single slice with a single
1937colon is used, and the slice method is available. For slice operations
1938involving extended slice notation, or in absence of the slice methods,
1939:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
1940slice object as argument.
1941
1942The following example demonstrate how to make your program or module compatible
1943with earlier versions of Python (assuming that methods :meth:`__getitem__`,
1944:meth:`__setitem__` and :meth:`__delitem__` support slice objects as
1945arguments)::
1946
1947 class MyClass:
1948 ...
1949 def __getitem__(self, index):
1950 ...
1951 def __setitem__(self, index, value):
1952 ...
1953 def __delitem__(self, index):
1954 ...
1955
1956 if sys.version_info < (2, 0):
1957 # They won't be defined if version is at least 2.0 final
1958
1959 def __getslice__(self, i, j):
1960 return self[max(0, i):max(0, j):]
1961 def __setslice__(self, i, j, seq):
1962 self[max(0, i):max(0, j):] = seq
1963 def __delslice__(self, i, j):
1964 del self[max(0, i):max(0, j):]
1965 ...
1966
1967Note the calls to :func:`max`; these are necessary because of the handling of
1968negative indices before the :meth:`__\*slice__` methods are called. When
1969negative indexes are used, the :meth:`__\*item__` methods receive them as
1970provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index
1971values. For each negative index value, the length of the sequence is added to
1972the index before calling the method (which may still result in a negative
1973index); this is the customary handling of negative indexes by the built-in
1974sequence types, and the :meth:`__\*item__` methods are expected to do this as
1975well. However, since they should already be doing that, negative indexes cannot
1976be passed in; they must be constrained to the bounds of the sequence before
1977being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)``
1978conveniently returns the proper value.
1979
1980
1981.. _numeric-types:
1982
1983Emulating numeric types
1984-----------------------
1985
1986The following methods can be defined to emulate numeric objects. Methods
1987corresponding to operations that are not supported by the particular kind of
1988number implemented (e.g., bitwise operations for non-integral numbers) should be
1989left undefined.
1990
1991
1992.. method:: object.__add__(self, other)
1993 object.__sub__(self, other)
1994 object.__mul__(self, other)
1995 object.__floordiv__(self, other)
1996 object.__mod__(self, other)
1997 object.__divmod__(self, other)
1998 object.__pow__(self, other[, modulo])
1999 object.__lshift__(self, other)
2000 object.__rshift__(self, other)
2001 object.__and__(self, other)
2002 object.__xor__(self, other)
2003 object.__or__(self, other)
2004
2005 .. index::
2006 builtin: divmod
2007 builtin: pow
2008 builtin: pow
2009
2010 These methods are called to implement the binary arithmetic operations (``+``,
2011 ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
2012 ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
Brett Cannon93298462008-08-14 05:55:18 +00002013 ``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
Georg Brandl8ec7f652007-08-15 14:28:01 +00002014 method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
2015 equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
2016 related to :meth:`__truediv__` (described below). Note that :meth:`__pow__`
2017 should be defined to accept an optional third argument if the ternary version of
2018 the built-in :func:`pow` function is to be supported.
2019
2020 If one of those methods does not support the operation with the supplied
2021 arguments, it should return ``NotImplemented``.
2022
2023
2024.. method:: object.__div__(self, other)
2025 object.__truediv__(self, other)
2026
2027 The division operator (``/``) is implemented by these methods. The
2028 :meth:`__truediv__` method is used when ``__future__.division`` is in effect,
2029 otherwise :meth:`__div__` is used. If only one of these two methods is defined,
2030 the object will not support division in the alternate context; :exc:`TypeError`
2031 will be raised instead.
2032
2033
2034.. method:: object.__radd__(self, other)
2035 object.__rsub__(self, other)
2036 object.__rmul__(self, other)
2037 object.__rdiv__(self, other)
2038 object.__rtruediv__(self, other)
2039 object.__rfloordiv__(self, other)
2040 object.__rmod__(self, other)
2041 object.__rdivmod__(self, other)
2042 object.__rpow__(self, other)
2043 object.__rlshift__(self, other)
2044 object.__rrshift__(self, other)
2045 object.__rand__(self, other)
2046 object.__rxor__(self, other)
2047 object.__ror__(self, other)
2048
2049 .. index::
2050 builtin: divmod
2051 builtin: pow
2052
2053 These methods are called to implement the binary arithmetic operations (``+``,
2054 ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``,
2055 ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are
2056 only called if the left operand does not support the corresponding operation and
2057 the operands are of different types. [#]_ For instance, to evaluate the
Brett Cannon93298462008-08-14 05:55:18 +00002058 expression ``x - y``, where *y* is an instance of a class that has an
Georg Brandl8ec7f652007-08-15 14:28:01 +00002059 :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns
2060 *NotImplemented*.
2061
2062 .. index:: builtin: pow
2063
2064 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
2065 coercion rules would become too complicated).
2066
2067 .. note::
2068
2069 If the right operand's type is a subclass of the left operand's type and that
2070 subclass provides the reflected method for the operation, this method will be
2071 called before the left operand's non-reflected method. This behavior allows
2072 subclasses to override their ancestors' operations.
2073
2074
2075.. method:: object.__iadd__(self, other)
2076 object.__isub__(self, other)
2077 object.__imul__(self, other)
2078 object.__idiv__(self, other)
2079 object.__itruediv__(self, other)
2080 object.__ifloordiv__(self, other)
2081 object.__imod__(self, other)
2082 object.__ipow__(self, other[, modulo])
2083 object.__ilshift__(self, other)
2084 object.__irshift__(self, other)
2085 object.__iand__(self, other)
2086 object.__ixor__(self, other)
2087 object.__ior__(self, other)
2088
Georg Brandlfe11f4d2009-01-18 18:25:30 +00002089 These methods are called to implement the augmented arithmetic assignments
Georg Brandl8ec7f652007-08-15 14:28:01 +00002090 (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
2091 ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
2092 in-place (modifying *self*) and return the result (which could be, but does
2093 not have to be, *self*). If a specific method is not defined, the augmented
Georg Brandlfe11f4d2009-01-18 18:25:30 +00002094 assignment falls back to the normal methods. For instance, to execute the
2095 statement ``x += y``, where *x* is an instance of a class that has an
Georg Brandl8ec7f652007-08-15 14:28:01 +00002096 :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
2097 of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
Brett Cannon93298462008-08-14 05:55:18 +00002098 and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002099
2100
2101.. method:: object.__neg__(self)
2102 object.__pos__(self)
2103 object.__abs__(self)
2104 object.__invert__(self)
2105
2106 .. index:: builtin: abs
2107
2108 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
2109 and ``~``).
2110
2111
2112.. method:: object.__complex__(self)
2113 object.__int__(self)
2114 object.__long__(self)
2115 object.__float__(self)
2116
2117 .. index::
2118 builtin: complex
2119 builtin: int
2120 builtin: long
2121 builtin: float
2122
2123 Called to implement the built-in functions :func:`complex`, :func:`int`,
2124 :func:`long`, and :func:`float`. Should return a value of the appropriate type.
2125
2126
2127.. method:: object.__oct__(self)
2128 object.__hex__(self)
2129
2130 .. index::
2131 builtin: oct
2132 builtin: hex
2133
2134 Called to implement the built-in functions :func:`oct` and :func:`hex`. Should
2135 return a string value.
2136
2137
2138.. method:: object.__index__(self)
2139
2140 Called to implement :func:`operator.index`. Also called whenever Python needs
2141 an integer object (such as in slicing). Must return an integer (int or long).
2142
2143 .. versionadded:: 2.5
2144
2145
2146.. method:: object.__coerce__(self, other)
2147
2148 Called to implement "mixed-mode" numeric arithmetic. Should either return a
2149 2-tuple containing *self* and *other* converted to a common numeric type, or
2150 ``None`` if conversion is impossible. When the common type would be the type of
2151 ``other``, it is sufficient to return ``None``, since the interpreter will also
2152 ask the other object to attempt a coercion (but sometimes, if the implementation
2153 of the other type cannot be changed, it is useful to do the conversion to the
2154 other type here). A return value of ``NotImplemented`` is equivalent to
2155 returning ``None``.
2156
2157
2158.. _coercion-rules:
2159
2160Coercion rules
2161--------------
2162
2163This section used to document the rules for coercion. As the language has
2164evolved, the coercion rules have become hard to document precisely; documenting
2165what one version of one particular implementation does is undesirable. Instead,
2166here are some informal guidelines regarding coercion. In Python 3.0, coercion
2167will not be supported.
2168
2169*
2170
2171 If the left operand of a % operator is a string or Unicode object, no coercion
2172 takes place and the string formatting operation is invoked instead.
2173
2174*
2175
2176 It is no longer recommended to define a coercion operation. Mixed-mode
2177 operations on types that don't define coercion pass the original arguments to
2178 the operation.
2179
2180*
2181
2182 New-style classes (those derived from :class:`object`) never invoke the
2183 :meth:`__coerce__` method in response to a binary operator; the only time
2184 :meth:`__coerce__` is invoked is when the built-in function :func:`coerce` is
2185 called.
2186
2187*
2188
2189 For most intents and purposes, an operator that returns ``NotImplemented`` is
2190 treated the same as one that is not implemented at all.
2191
2192*
2193
2194 Below, :meth:`__op__` and :meth:`__rop__` are used to signify the generic method
2195 names corresponding to an operator; :meth:`__iop__` is used for the
2196 corresponding in-place operator. For example, for the operator '``+``',
2197 :meth:`__add__` and :meth:`__radd__` are used for the left and right variant of
2198 the binary operator, and :meth:`__iadd__` for the in-place variant.
2199
2200*
2201
2202 For objects *x* and *y*, first ``x.__op__(y)`` is tried. If this is not
2203 implemented or returns ``NotImplemented``, ``y.__rop__(x)`` is tried. If this
2204 is also not implemented or returns ``NotImplemented``, a :exc:`TypeError`
2205 exception is raised. But see the following exception:
2206
2207*
2208
2209 Exception to the previous item: if the left operand is an instance of a built-in
2210 type or a new-style class, and the right operand is an instance of a proper
2211 subclass of that type or class and overrides the base's :meth:`__rop__` method,
2212 the right operand's :meth:`__rop__` method is tried *before* the left operand's
2213 :meth:`__op__` method.
2214
2215 This is done so that a subclass can completely override binary operators.
2216 Otherwise, the left operand's :meth:`__op__` method would always accept the
2217 right operand: when an instance of a given class is expected, an instance of a
2218 subclass of that class is always acceptable.
2219
2220*
2221
2222 When either operand type defines a coercion, this coercion is called before that
2223 type's :meth:`__op__` or :meth:`__rop__` method is called, but no sooner. If
2224 the coercion returns an object of a different type for the operand whose
2225 coercion is invoked, part of the process is redone using the new object.
2226
2227*
2228
2229 When an in-place operator (like '``+=``') is used, if the left operand
2230 implements :meth:`__iop__`, it is invoked without any coercion. When the
2231 operation falls back to :meth:`__op__` and/or :meth:`__rop__`, the normal
2232 coercion rules apply.
2233
2234*
2235
Brett Cannon93298462008-08-14 05:55:18 +00002236 In ``x + y``, if *x* is a sequence that implements sequence concatenation,
Georg Brandl8ec7f652007-08-15 14:28:01 +00002237 sequence concatenation is invoked.
2238
2239*
2240
Brett Cannon93298462008-08-14 05:55:18 +00002241 In ``x * y``, if one operator is a sequence that implements sequence
Georg Brandl8ec7f652007-08-15 14:28:01 +00002242 repetition, and the other is an integer (:class:`int` or :class:`long`),
2243 sequence repetition is invoked.
2244
2245*
2246
2247 Rich comparisons (implemented by methods :meth:`__eq__` and so on) never use
2248 coercion. Three-way comparison (implemented by :meth:`__cmp__`) does use
2249 coercion under the same conditions as other binary operations use it.
2250
2251*
2252
2253 In the current implementation, the built-in numeric types :class:`int`,
2254 :class:`long` and :class:`float` do not use coercion; the type :class:`complex`
Georg Brandl9834dd72009-02-13 10:44:17 +00002255 however does use coercion for binary operators and rich comparisons, despite
2256 the above rules. The difference can become apparent when subclassing these
Georg Brandl8ec7f652007-08-15 14:28:01 +00002257 types. Over time, the type :class:`complex` may be fixed to avoid coercion.
2258 All these types implement a :meth:`__coerce__` method, for use by the built-in
2259 :func:`coerce` function.
2260
2261
2262.. _context-managers:
2263
2264With Statement Context Managers
2265-------------------------------
2266
2267.. versionadded:: 2.5
2268
2269A :dfn:`context manager` is an object that defines the runtime context to be
2270established when executing a :keyword:`with` statement. The context manager
2271handles the entry into, and the exit from, the desired runtime context for the
2272execution of the block of code. Context managers are normally invoked using the
2273:keyword:`with` statement (described in section :ref:`with`), but can also be
2274used by directly invoking their methods.
2275
2276.. index::
2277 statement: with
2278 single: context manager
2279
2280Typical uses of context managers include saving and restoring various kinds of
2281global state, locking and unlocking resources, closing opened files, etc.
2282
2283For more information on context managers, see :ref:`typecontextmanager`.
2284
2285
2286.. method:: object.__enter__(self)
2287
2288 Enter the runtime context related to this object. The :keyword:`with` statement
2289 will bind this method's return value to the target(s) specified in the
2290 :keyword:`as` clause of the statement, if any.
2291
2292
2293.. method:: object.__exit__(self, exc_type, exc_value, traceback)
2294
2295 Exit the runtime context related to this object. The parameters describe the
2296 exception that caused the context to be exited. If the context was exited
2297 without an exception, all three arguments will be :const:`None`.
2298
2299 If an exception is supplied, and the method wishes to suppress the exception
2300 (i.e., prevent it from being propagated), it should return a true value.
2301 Otherwise, the exception will be processed normally upon exit from this method.
2302
2303 Note that :meth:`__exit__` methods should not reraise the passed-in exception;
2304 this is the caller's responsibility.
2305
2306
2307.. seealso::
2308
2309 :pep:`0343` - The "with" statement
2310 The specification, background, and examples for the Python :keyword:`with`
2311 statement.
2312
Nick Coghlana5107482008-08-04 12:40:59 +00002313
2314.. _old-style-special-lookup:
2315
2316Special method lookup for old-style classes
2317-------------------------------------------
2318
2319For old-style classes, special methods are always looked up in exactly the
2320same way as any other method or attribute. This is the case regardless of
2321whether the method is being looked up explicitly as in ``x.__getitem__(i)``
2322or implicitly as in ``x[i]``.
2323
2324This behaviour means that special methods may exhibit different behaviour
2325for different instances of a single old-style class if the appropriate
2326special attributes are set differently::
2327
2328 >>> class C:
2329 ... pass
2330 ...
2331 >>> c1 = C()
2332 >>> c2 = C()
2333 >>> c1.__len__ = lambda: 5
2334 >>> c2.__len__ = lambda: 9
2335 >>> len(c1)
2336 5
2337 >>> len(c2)
2338 9
2339
2340
2341.. _new-style-special-lookup:
2342
2343Special method lookup for new-style classes
2344-------------------------------------------
2345
2346For new-style classes, implicit invocations of special methods are only guaranteed
2347to work correctly if defined on an object's type, not in the object's instance
2348dictionary. That behaviour is the reason why the following code raises an
2349exception (unlike the equivalent example with old-style classes)::
2350
2351 >>> class C(object):
2352 ... pass
2353 ...
2354 >>> c = C()
2355 >>> c.__len__ = lambda: 5
2356 >>> len(c)
2357 Traceback (most recent call last):
2358 File "<stdin>", line 1, in <module>
2359 TypeError: object of type 'C' has no len()
2360
2361The rationale behind this behaviour lies with a number of special methods such
2362as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
2363including type objects. If the implicit lookup of these methods used the
2364conventional lookup process, they would fail when invoked on the type object
2365itself::
2366
2367 >>> 1 .__hash__() == hash(1)
2368 True
2369 >>> int.__hash__() == hash(int)
2370 Traceback (most recent call last):
2371 File "<stdin>", line 1, in <module>
2372 TypeError: descriptor '__hash__' of 'int' object needs an argument
2373
2374Incorrectly attempting to invoke an unbound method of a class in this way is
2375sometimes referred to as 'metaclass confusion', and is avoided by bypassing
2376the instance when looking up special methods::
2377
2378 >>> type(1).__hash__(1) == hash(1)
2379 True
2380 >>> type(int).__hash__(int) == hash(int)
2381 True
2382
2383In addition to bypassing any instance attributes in the interest of
Georg Brandl9a053732008-12-05 15:29:39 +00002384correctness, implicit special method lookup generally also bypasses the
Nick Coghlana5107482008-08-04 12:40:59 +00002385:meth:`__getattribute__` method even of the object's metaclass::
2386
2387 >>> class Meta(type):
2388 ... def __getattribute__(*args):
2389 ... print "Metaclass getattribute invoked"
2390 ... return type.__getattribute__(*args)
2391 ...
2392 >>> class C(object):
2393 ... __metaclass__ = Meta
2394 ... def __len__(self):
2395 ... return 10
2396 ... def __getattribute__(*args):
2397 ... print "Class getattribute invoked"
2398 ... return object.__getattribute__(*args)
2399 ...
2400 >>> c = C()
2401 >>> c.__len__() # Explicit lookup via instance
2402 Class getattribute invoked
2403 10
2404 >>> type(c).__len__(c) # Explicit lookup via type
2405 Metaclass getattribute invoked
2406 10
2407 >>> len(c) # Implicit lookup
2408 10
2409
2410Bypassing the :meth:`__getattribute__` machinery in this fashion
2411provides significant scope for speed optimisations within the
2412interpreter, at the cost of some flexibility in the handling of
2413special methods (the special method *must* be set on the class
2414object itself in order to be consistently invoked by the interpreter).
2415
2416
Georg Brandl8ec7f652007-08-15 14:28:01 +00002417.. rubric:: Footnotes
2418
Nick Coghlana5107482008-08-04 12:40:59 +00002419.. [#] It *is* possible in some cases to change an object's type, under certain
2420 controlled conditions. It generally isn't a good idea though, since it can
2421 lead to some very strange behaviour if it is handled incorrectly.
Georg Brandl8ec7f652007-08-15 14:28:01 +00002422
Georg Brandl37614222007-08-23 21:42:54 +00002423.. [#] A descriptor can define any combination of :meth:`__get__`,
2424 :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`,
2425 then accessing the attribute even on an instance will return the descriptor
2426 object itself. If the descriptor defines :meth:`__set__` and/or
2427 :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a
2428 non-data descriptor.
2429
Georg Brandl8ec7f652007-08-15 14:28:01 +00002430.. [#] For operands of the same type, it is assumed that if the non-reflected method
2431 (such as :meth:`__add__`) fails the operation is not supported, which is why the
2432 reflected method is not called.
2433