11 Objects, values and types
12 =========================
18 :dfn:`Objects` are Python's abstraction for data. All data in a Python program
19 is represented by objects or by relations between objects. (In a sense, and in
20 conformance to Von Neumann's model of a "stored program computer," code is also
21 represented by objects.)
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
32 Every object has an identity, a type and a value. An object's *identity* never
33 changes once it has been created; you may think of it as the object's address in
34 memory. The ':keyword:`is`' operator compares the identity of two objects; the
35 :func:`id` function returns an integer representing its identity (currently
36 implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_
37 An object's type determines the operations that the object supports (e.g., "does
38 it have a length?") and also defines the possible values for objects of that
39 type. The :func:`type` function returns an object's type (which is an object
40 itself). The *value* of some objects can change. Objects whose value can
41 change are said to be *mutable*; objects whose value is unchangeable once they
42 are created are called *immutable*. (The value of an immutable container object
43 that contains a reference to a mutable object can change when the latter's value
44 is changed; however the container is still considered immutable, because the
45 collection of objects it contains cannot be changed. So, immutability is not
46 strictly the same as having an unchangeable value, it is more subtle.) An
47 object's mutability is determined by its type; for instance, numbers, strings
48 and tuples are immutable, while dictionaries and lists are mutable.
51 single: garbage collection
52 single: reference counting
53 single: unreachable object
55 Objects are never explicitly destroyed; however, when they become unreachable
56 they may be garbage-collected. An implementation is allowed to postpone garbage
57 collection or omit it altogether --- it is a matter of implementation quality
58 how garbage collection is implemented, as long as no objects are collected that
63 CPython currently uses a reference-counting scheme with (optional) delayed
64 detection of cyclically linked garbage, which collects most objects as soon
65 as they become unreachable, but is not guaranteed to collect garbage
66 containing circular references. See the documentation of the :mod:`gc`
67 module for information on controlling the collection of cyclic garbage.
68 Other implementations act differently and CPython may change.
70 Note that the use of the implementation's tracing or debugging facilities may
71 keep objects alive that would normally be collectable. Also note that catching
72 an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
75 Some objects contain references to "external" resources such as open files or
76 windows. It is understood that these resources are freed when the object is
77 garbage-collected, but since garbage collection is not guaranteed to happen,
78 such objects also provide an explicit way to release the external resource,
79 usually a :meth:`close` method. Programs are strongly recommended to explicitly
80 close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
81 provides a convenient way to do this.
83 .. index:: single: container
85 Some objects contain references to other objects; these are called *containers*.
86 Examples of containers are tuples, lists and dictionaries. The references are
87 part of a container's value. In most cases, when we talk about the value of a
88 container, we imply the values, not the identities of the contained objects;
89 however, when we talk about the mutability of a container, only the identities
90 of the immediately contained objects are implied. So, if an immutable container
91 (like a tuple) contains a reference to a mutable object, its value changes if
92 that mutable object is changed.
94 Types affect almost all aspects of object behavior. Even the importance of
95 object identity is affected in some sense: for immutable types, operations that
96 compute new values may actually return a reference to any existing object with
97 the same type and value, while for mutable objects this is not allowed. E.g.,
98 after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
99 with the value one, depending on the implementation, but after ``c = []; d =
100 []``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
101 created empty lists. (Note that ``c = d = []`` assigns the same object to both
107 The standard type hierarchy
108 ===========================
113 pair: type; hierarchy
114 pair: extension; module
117 Below is a list of the types that are built into Python. Extension modules
118 (written in C, Java, or other languages, depending on the implementation) can
119 define additional types. Future versions of Python may add types to the type
120 hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).
124 pair: special; attribute
125 triple: generic; special; attribute
127 Some of the type descriptions below contain a paragraph listing 'special
128 attributes.' These are attributes that provide access to the implementation and
129 are not intended for general use. Their definition may change in the future.
132 .. index:: object: None
134 This type has a single value. There is a single object with this value. This
135 object is accessed through the built-in name ``None``. It is used to signify the
136 absence of a value in many situations, e.g., it is returned from functions that
137 don't explicitly return anything. Its truth value is false.
140 .. index:: object: NotImplemented
142 This type has a single value. There is a single object with this value. This
143 object is accessed through the built-in name ``NotImplemented``. Numeric methods
144 and rich comparison methods may return this value if they do not implement the
145 operation for the operands provided. (The interpreter will then try the
146 reflected operation, or some other fallback, depending on the operator.) Its
150 .. index:: object: Ellipsis
152 This type has a single value. There is a single object with this value. This
153 object is accessed through the built-in name ``Ellipsis``. It is used to
154 indicate the presence of the ``...`` syntax in a slice. Its truth value is
157 :class:`numbers.Number`
158 .. index:: object: numeric
160 These are created by numeric literals and returned as results by arithmetic
161 operators and arithmetic built-in functions. Numeric objects are immutable;
162 once created their value never changes. Python numbers are of course strongly
163 related to mathematical numbers, but subject to the limitations of numerical
164 representation in computers.
166 Python distinguishes between integers, floating point numbers, and complex
169 :class:`numbers.Integral`
170 .. index:: object: integer
172 These represent elements from the mathematical set of integers (positive and
175 There are three types of integers:
179 object: plain integer
180 single: OverflowError (built-in exception)
182 These represent numbers in the range -2147483648 through 2147483647.
183 (The range may be larger on machines with a larger natural word size,
184 but not smaller.) When the result of an operation would fall outside
185 this range, the result is normally returned as a long integer (in some
186 cases, the exception :exc:`OverflowError` is raised instead). For the
187 purpose of shift and mask operations, integers are assumed to have a
188 binary, 2's complement notation using 32 or more bits, and hiding no
189 bits from the user (i.e., all 4294967296 different bit patterns
190 correspond to different values).
193 .. index:: object: long integer
195 These represent numbers in an unlimited range, subject to available
196 (virtual) memory only. For the purpose of shift and mask operations, a
197 binary representation is assumed, and negative numbers are represented
198 in a variant of 2's complement which gives the illusion of an infinite
199 string of sign bits extending to the left.
207 These represent the truth values False and True. The two objects
208 representing the values False and True are the only Boolean objects.
209 The Boolean type is a subtype of plain integers, and Boolean values
210 behave like the values 0 and 1, respectively, in almost all contexts,
211 the exception being that when converted to a string, the strings
212 ``"False"`` or ``"True"`` are returned, respectively.
214 .. index:: pair: integer; representation
216 The rules for integer representation are intended to give the most
217 meaningful interpretation of shift and mask operations involving negative
218 integers and the least surprises when switching between the plain and long
219 integer domains. Any operation, if it yields a result in the plain
220 integer domain, will yield the same result in the long integer domain or
221 when using mixed operands. The switch between domains is transparent to
224 :class:`numbers.Real` (:class:`float`)
226 object: floating point
227 pair: floating point; number
231 These represent machine-level double precision floating point numbers. You are
232 at the mercy of the underlying machine architecture (and C or Java
233 implementation) for the accepted range and handling of overflow. Python does not
234 support single-precision floating point numbers; the savings in processor and
235 memory usage that are usually the reason for using these is dwarfed by the
236 overhead of using objects in Python, so there is no reason to complicate the
237 language with two kinds of floating point numbers.
239 :class:`numbers.Complex`
242 pair: complex; number
244 These represent complex numbers as a pair of machine-level double precision
245 floating point numbers. The same caveats apply as for floating point numbers.
246 The real and imaginary parts of a complex number ``z`` can be retrieved through
247 the read-only attributes ``z.real`` and ``z.imag``.
253 single: index operation
254 single: item selection
257 These represent finite ordered sets indexed by non-negative numbers. The
258 built-in function :func:`len` returns the number of items of a sequence. When
259 the length of a sequence is *n*, the index set contains the numbers 0, 1,
260 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
262 .. index:: single: slicing
264 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
265 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
266 sequence of the same type. This implies that the index set is renumbered so
269 .. index:: single: extended slicing
271 Some sequences also support "extended slicing" with a third "step" parameter:
272 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
273 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
275 Sequences are distinguished according to their mutability:
279 object: immutable sequence
282 An object of an immutable sequence type cannot change once it is created. (If
283 the object contains references to other objects, these other objects may be
284 mutable and may be changed; however, the collection of objects directly
285 referenced by an immutable object cannot change.)
287 The following types are immutable sequences:
298 The items of a string are characters. There is no separate character type; a
299 character is represented by a string of one item. Characters represent (at
300 least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert
301 between characters and nonnegative integers representing the byte values. Bytes
302 with the values 0-127 usually represent the corresponding ASCII values, but the
303 interpretation of values is up to the program. The string data type is also
304 used to represent arrays of bytes, e.g., to hold data read from a file.
309 single: character set
310 pair: string; comparison
314 (On systems whose native character set is not ASCII, strings may use EBCDIC in
315 their internal representation, provided the functions :func:`chr` and
316 :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison
317 preserves the ASCII order. Or perhaps someone can propose a better rule?)
329 The items of a Unicode object are Unicode code units. A Unicode code unit is
330 represented by a Unicode object of one item and can hold either a 16-bit or
331 32-bit value representing a Unicode ordinal (the maximum value for the ordinal
332 is given in ``sys.maxunicode``, and depends on how Python is configured at
333 compile time). Surrogate pairs may be present in the Unicode object, and will
334 be reported as two separate items. The built-in functions :func:`unichr` and
335 :func:`ord` convert between code units and nonnegative integers representing the
336 Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to
337 other encodings are possible through the Unicode method :meth:`encode` and the
338 built-in function :func:`unicode`.
343 pair: singleton; tuple
346 The items of a tuple are arbitrary Python objects. Tuples of two or more items
347 are formed by comma-separated lists of expressions. A tuple of one item (a
348 'singleton') can be formed by affixing a comma to an expression (an expression
349 by itself does not create a tuple, since parentheses must be usable for grouping
350 of expressions). An empty tuple can be formed by an empty pair of parentheses.
354 object: mutable sequence
356 pair: assignment; statement
362 Mutable sequences can be changed after they are created. The subscription and
363 slicing notations can be used as the target of assignment and :keyword:`del`
366 There are currently two intrinsic mutable sequence types:
369 .. index:: object: list
371 The items of a list are arbitrary Python objects. Lists are formed by placing a
372 comma-separated list of expressions in square brackets. (Note that there are no
373 special cases needed to form lists of length 0 or 1.)
378 A bytearray object is a mutable array. They are created by the built-in
379 :func:`bytearray` constructor. Aside from being mutable (and hence
380 unhashable), byte arrays otherwise provide the same interface and
381 functionality as immutable bytes objects.
383 .. index:: module: array
385 The extension module :mod:`array` provides an additional example of a mutable
393 These represent unordered, finite sets of unique, immutable objects. As such,
394 they cannot be indexed by any subscript. However, they can be iterated over, and
395 the built-in function :func:`len` returns the number of items in a set. Common
396 uses for sets are fast membership testing, removing duplicates from a sequence,
397 and computing mathematical operations such as intersection, union, difference,
398 and symmetric difference.
400 For set elements, the same immutability rules apply as for dictionary keys. Note
401 that numeric types obey the normal rules for numeric comparison: if two numbers
402 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
405 There are currently two intrinsic set types:
408 .. index:: object: set
410 These represent a mutable set. They are created by the built-in :func:`set`
411 constructor and can be modified afterwards by several methods, such as
415 .. index:: object: frozenset
417 These represent an immutable set. They are created by the built-in
418 :func:`frozenset` constructor. As a frozenset is immutable and
419 :term:`hashable`, it can be used again as an element of another set, or as
428 These represent finite sets of objects indexed by arbitrary index sets. The
429 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
430 ``a``; this can be used in expressions and as the target of assignments or
431 :keyword:`del` statements. The built-in function :func:`len` returns the number
432 of items in a mapping.
434 There is currently a single intrinsic mapping type:
437 .. index:: object: dictionary
439 These represent finite sets of objects indexed by nearly arbitrary values. The
440 only types of values not acceptable as keys are values containing lists or
441 dictionaries or other mutable types that are compared by value rather than by
442 object identity, the reason being that the efficient implementation of
443 dictionaries requires a key's hash value to remain constant. Numeric types used
444 for keys obey the normal rules for numeric comparison: if two numbers compare
445 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
446 the same dictionary entry.
448 Dictionaries are mutable; they can be created by the ``{...}`` notation (see
449 section :ref:`dict`).
456 The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
457 additional examples of mapping types.
464 pair: function; argument
466 These are the types to which the function call operation (see section
467 :ref:`calls`) can be applied:
469 User-defined functions
471 pair: user-defined; function
473 object: user-defined function
475 A user-defined function object is created by a function definition (see
476 section :ref:`function`). It should be called with an argument list
477 containing the same number of items as the function's formal parameter
482 +-----------------------+-------------------------------+-----------+
483 | Attribute | Meaning | |
484 +=======================+===============================+===========+
485 | :attr:`func_doc` | The function's documentation | Writable |
486 | | string, or ``None`` if | |
488 +-----------------------+-------------------------------+-----------+
489 | :attr:`__doc__` | Another way of spelling | Writable |
490 | | :attr:`func_doc` | |
491 +-----------------------+-------------------------------+-----------+
492 | :attr:`func_name` | The function's name | Writable |
493 +-----------------------+-------------------------------+-----------+
494 | :attr:`__name__` | Another way of spelling | Writable |
495 | | :attr:`func_name` | |
496 +-----------------------+-------------------------------+-----------+
497 | :attr:`__module__` | The name of the module the | Writable |
498 | | function was defined in, or | |
499 | | ``None`` if unavailable. | |
500 +-----------------------+-------------------------------+-----------+
501 | :attr:`func_defaults` | A tuple containing default | Writable |
502 | | argument values for those | |
503 | | arguments that have defaults, | |
504 | | or ``None`` if no arguments | |
505 | | have a default value | |
506 +-----------------------+-------------------------------+-----------+
507 | :attr:`func_code` | The code object representing | Writable |
508 | | the compiled function body. | |
509 +-----------------------+-------------------------------+-----------+
510 | :attr:`func_globals` | A reference to the dictionary | Read-only |
511 | | that holds the function's | |
512 | | global variables --- the | |
513 | | global namespace of the | |
514 | | module in which the function | |
516 +-----------------------+-------------------------------+-----------+
517 | :attr:`func_dict` | The namespace supporting | Writable |
518 | | arbitrary function | |
520 +-----------------------+-------------------------------+-----------+
521 | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only |
522 | | that contain bindings for the | |
523 | | function's free variables. | |
524 +-----------------------+-------------------------------+-----------+
526 Most of the attributes labelled "Writable" check the type of the assigned value.
528 .. versionchanged:: 2.4
529 ``func_name`` is now writable.
531 Function objects also support getting and setting arbitrary attributes, which
532 can be used, for example, to attach metadata to functions. Regular attribute
533 dot-notation is used to get and set such attributes. *Note that the current
534 implementation only supports function attributes on user-defined functions.
535 Function attributes on built-in functions may be supported in the future.*
537 Additional information about a function's definition can be retrieved from its
538 code object; see the description of internal types below.
541 single: func_doc (function attribute)
542 single: __doc__ (function attribute)
543 single: __name__ (function attribute)
544 single: __module__ (function attribute)
545 single: __dict__ (function attribute)
546 single: func_defaults (function attribute)
547 single: func_closure (function attribute)
548 single: func_code (function attribute)
549 single: func_globals (function attribute)
550 single: func_dict (function attribute)
551 pair: global; namespace
556 object: user-defined method
557 pair: user-defined; method
559 A user-defined method object combines a class, a class instance (or ``None``)
560 and any callable object (normally a user-defined function).
562 Special read-only attributes: :attr:`im_self` is the class instance object,
563 :attr:`im_func` is the function object; :attr:`im_class` is the class of
564 :attr:`im_self` for bound methods or the class that asked for the method for
565 unbound methods; :attr:`__doc__` is the method's documentation (same as
566 ``im_func.__doc__``); :attr:`__name__` is the method name (same as
567 ``im_func.__name__``); :attr:`__module__` is the name of the module the method
568 was defined in, or ``None`` if unavailable.
570 .. versionchanged:: 2.2
571 :attr:`im_self` used to refer to the class that defined the method.
573 .. versionchanged:: 2.6
574 For 3.0 forward-compatibility, :attr:`im_func` is also available as
575 :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.
578 single: __doc__ (method attribute)
579 single: __name__ (method attribute)
580 single: __module__ (method attribute)
581 single: im_func (method attribute)
582 single: im_self (method attribute)
584 Methods also support accessing (but not setting) the arbitrary function
585 attributes on the underlying function object.
587 User-defined method objects may be created when getting an attribute of a class
588 (perhaps via an instance of that class), if that attribute is a user-defined
589 function object, an unbound user-defined method object, or a class method
590 object. When the attribute is a user-defined method object, a new method object
591 is only created if the class from which it is being retrieved is the same as, or
592 a derived class of, the class stored in the original method object; otherwise,
593 the original method object is used as it is.
596 single: im_class (method attribute)
597 single: im_func (method attribute)
598 single: im_self (method attribute)
600 When a user-defined method object is created by retrieving a user-defined
601 function object from a class, its :attr:`im_self` attribute is ``None``
602 and the method object is said to be unbound. When one is created by
603 retrieving a user-defined function object from a class via one of its
604 instances, its :attr:`im_self` attribute is the instance, and the method
605 object is said to be bound. In either case, the new method's
606 :attr:`im_class` attribute is the class from which the retrieval takes
607 place, and its :attr:`im_func` attribute is the original function object.
609 .. index:: single: im_func (method attribute)
611 When a user-defined method object is created by retrieving another method object
612 from a class or instance, the behaviour is the same as for a function object,
613 except that the :attr:`im_func` attribute of the new instance is not the
614 original method object but its :attr:`im_func` attribute.
617 single: im_class (method attribute)
618 single: im_func (method attribute)
619 single: im_self (method attribute)
621 When a user-defined method object is created by retrieving a class method object
622 from a class or instance, its :attr:`im_self` attribute is the class itself (the
623 same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is
624 the function object underlying the class method.
626 When an unbound user-defined method object is called, the underlying function
627 (:attr:`im_func`) is called, with the restriction that the first argument must
628 be an instance of the proper class (:attr:`im_class`) or of a derived class
631 When a bound user-defined method object is called, the underlying function
632 (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in
633 front of the argument list. For instance, when :class:`C` is a class which
634 contains a definition for a function :meth:`f`, and ``x`` is an instance of
635 :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.
637 When a user-defined method object is derived from a class method object, the
638 "class instance" stored in :attr:`im_self` will actually be the class itself, so
639 that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``
640 where ``f`` is the underlying function.
642 Note that the transformation from function object to (unbound or bound) method
643 object happens each time the attribute is retrieved from the class or instance.
644 In some cases, a fruitful optimization is to assign the attribute to a local
645 variable and call that local variable. Also notice that this transformation only
646 happens for user-defined functions; other callable objects (and all non-callable
647 objects) are retrieved without transformation. It is also important to note
648 that user-defined functions which are attributes of a class instance are not
649 converted to bound methods; this *only* happens when the function is an
650 attribute of the class.
654 single: generator; function
655 single: generator; iterator
657 A function or method which uses the :keyword:`yield` statement (see section
658 :ref:`yield`) is called a :dfn:`generator
659 function`. Such a function, when called, always returns an iterator object
660 which can be used to execute the body of the function: calling the iterator's
661 :meth:`next` method will cause the function to execute until it provides a value
662 using the :keyword:`yield` statement. When the function executes a
663 :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
664 exception is raised and the iterator will have reached the end of the set of
665 values to be returned.
669 object: built-in function
673 A built-in function object is a wrapper around a C function. Examples of
674 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
675 standard built-in module). The number and type of the arguments are
676 determined by the C function. Special read-only attributes:
677 :attr:`__doc__` is the function's documentation string, or ``None`` if
678 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
679 set to ``None`` (but see the next item); :attr:`__module__` is the name of
680 the module the function was defined in or ``None`` if unavailable.
684 object: built-in method
686 pair: built-in; method
688 This is really a different disguise of a built-in function, this time containing
689 an object passed to the C function as an implicit extra argument. An example of
690 a built-in method is ``alist.append()``, assuming *alist* is a list object. In
691 this case, the special read-only attribute :attr:`__self__` is set to the object
695 Class types, or "new-style classes," are callable. These objects normally act
696 as factories for new instances of themselves, but variations are possible for
697 class types that override :meth:`__new__`. The arguments of the call are passed
698 to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize
703 single: __init__() (object method)
705 object: class instance
707 pair: class object; call
709 Class objects are described below. When a class object is called, a new class
710 instance (also described below) is created and returned. This implies a call to
711 the class's :meth:`__init__` method if it has one. Any arguments are passed on
712 to the :meth:`__init__` method. If there is no :meth:`__init__` method, the
713 class must be called without arguments.
716 Class instances are described below. Class instances are callable only when the
717 class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for
718 ``x.__call__(arguments)``.
725 Modules are imported by the :keyword:`import` statement (see section
726 :ref:`import`). A module object has a
727 namespace implemented by a dictionary object (this is the dictionary referenced
728 by the func_globals attribute of functions defined in the module). Attribute
729 references are translated to lookups in this dictionary, e.g., ``m.x`` is
730 equivalent to ``m.__dict__["x"]``. A module object does not contain the code
731 object used to initialize the module (since it isn't needed once the
732 initialization is done).
734 Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
735 1`` is equivalent to ``m.__dict__["x"] = 1``.
737 .. index:: single: __dict__ (module attribute)
739 Special read-only attribute: :attr:`__dict__` is the module's namespace as a
743 single: __name__ (module attribute)
744 single: __doc__ (module attribute)
745 single: __file__ (module attribute)
746 pair: module; namespace
748 Predefined (writable) attributes: :attr:`__name__` is the module's name;
749 :attr:`__doc__` is the module's documentation string, or ``None`` if
750 unavailable; :attr:`__file__` is the pathname of the file from which the module
751 was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
752 present for C modules that are statically linked into the interpreter; for
753 extension modules loaded dynamically from a shared library, it is the pathname
754 of the shared library file.
757 Both class types (new-style classes) and class objects (old-style/classic
758 classes) are typically created by class definitions (see section
759 :ref:`class`). A class has a namespace implemented by a dictionary object.
760 Class attribute references are translated to lookups in this dictionary, e.g.,
761 ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes
762 in particular there are a number of hooks which allow for other means of
763 locating attributes). When the attribute name is not found there, the
764 attribute search continues in the base classes. For old-style classes, the
765 search is depth-first, left-to-right in the order of occurrence in the base
766 class list. New-style classes use the more complex C3 method resolution
767 order which behaves correctly even in the presence of 'diamond'
768 inheritance structures where there are multiple inheritance paths
769 leading back to a common ancestor. Additional details on the C3 MRO used by
770 new-style classes can be found in the documentation accompanying the
771 2.3 release at http://www.python.org/download/releases/2.3/mro/.
773 .. XXX: Could we add that MRO doc as an appendix to the language ref?
777 object: class instance
779 pair: class object; call
782 pair: class; attribute
784 When a class attribute reference (for class :class:`C`, say) would yield a
785 user-defined function object or an unbound user-defined method object whose
786 associated class is either :class:`C` or one of its base classes, it is
787 transformed into an unbound user-defined method object whose :attr:`im_class`
788 attribute is :class:`C`. When it would yield a class method object, it is
789 transformed into a bound user-defined method object whose :attr:`im_class`
790 and :attr:`im_self` attributes are both :class:`C`. When it would yield a
791 static method object, it is transformed into the object wrapped by the static
792 method object. See section :ref:`descriptors` for another way in which
793 attributes retrieved from a class may differ from those actually contained in
794 its :attr:`__dict__` (note that only new-style classes support descriptors).
796 .. index:: triple: class; attribute; assignment
798 Class attribute assignments update the class's dictionary, never the dictionary
801 .. index:: pair: class object; call
803 A class object can be called (see above) to yield a class instance (see below).
806 single: __name__ (class attribute)
807 single: __module__ (class attribute)
808 single: __dict__ (class attribute)
809 single: __bases__ (class attribute)
810 single: __doc__ (class attribute)
812 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
813 the module name in which the class was defined; :attr:`__dict__` is the
814 dictionary containing the class's namespace; :attr:`__bases__` is a tuple
815 (possibly empty or a singleton) containing the base classes, in the order of
816 their occurrence in the base class list; :attr:`__doc__` is the class's
817 documentation string, or None if undefined.
821 object: class instance
823 pair: class; instance
824 pair: class instance; attribute
826 A class instance is created by calling a class object (see above). A class
827 instance has a namespace implemented as a dictionary which is the first place in
828 which attribute references are searched. When an attribute is not found there,
829 and the instance's class has an attribute by that name, the search continues
830 with the class attributes. If a class attribute is found that is a user-defined
831 function object or an unbound user-defined method object whose associated class
832 is the class (call it :class:`C`) of the instance for which the attribute
833 reference was initiated or one of its bases, it is transformed into a bound
834 user-defined method object whose :attr:`im_class` attribute is :class:`C` and
835 whose :attr:`im_self` attribute is the instance. Static method and class method
836 objects are also transformed, as if they had been retrieved from class
837 :class:`C`; see above under "Classes". See section :ref:`descriptors` for
838 another way in which attributes of a class retrieved via its instances may
839 differ from the objects actually stored in the class's :attr:`__dict__`. If no
840 class attribute is found, and the object's class has a :meth:`__getattr__`
841 method, that is called to satisfy the lookup.
843 .. index:: triple: class instance; attribute; assignment
845 Attribute assignments and deletions update the instance's dictionary, never a
846 class's dictionary. If the class has a :meth:`__setattr__` or
847 :meth:`__delattr__` method, this is called instead of updating the instance
855 Class instances can pretend to be numbers, sequences, or mappings if they have
856 methods with certain special names. See section :ref:`specialnames`.
859 single: __dict__ (instance attribute)
860 single: __class__ (instance attribute)
862 Special attributes: :attr:`__dict__` is the attribute dictionary;
863 :attr:`__class__` is the instance's class.
869 single: popen() (in module os)
870 single: makefile() (socket method)
875 single: stdin (in module sys)
876 single: stdout (in module sys)
877 single: stderr (in module sys)
879 A file object represents an open file. File objects are created by the
880 :func:`open` built-in function, and also by :func:`os.popen`,
881 :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
882 perhaps by other functions or methods provided by extension modules). The
883 objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
884 file objects corresponding to the interpreter's standard input, output and
885 error streams. See :ref:`bltin-file-objects` for complete documentation of
890 single: internal type
891 single: types, internal
893 A few types used internally by the interpreter are exposed to the user. Their
894 definitions may change with future versions of the interpreter, but they are
895 mentioned here for completeness.
902 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
903 The difference between a code object and a function object is that the function
904 object contains an explicit reference to the function's globals (the module in
905 which it was defined), while a code object contains no context; also the default
906 argument values are stored in the function object, not in the code object
907 (because they represent values calculated at run-time). Unlike function
908 objects, code objects are immutable and contain no references (directly or
909 indirectly) to mutable objects.
911 Special read-only attributes: :attr:`co_name` gives the function name;
912 :attr:`co_argcount` is the number of positional arguments (including arguments
913 with default values); :attr:`co_nlocals` is the number of local variables used
914 by the function (including arguments); :attr:`co_varnames` is a tuple containing
915 the names of the local variables (starting with the argument names);
916 :attr:`co_cellvars` is a tuple containing the names of local variables that are
917 referenced by nested functions; :attr:`co_freevars` is a tuple containing the
918 names of free variables; :attr:`co_code` is a string representing the sequence
919 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
920 used by the bytecode; :attr:`co_names` is a tuple containing the names used by
921 the bytecode; :attr:`co_filename` is the filename from which the code was
922 compiled; :attr:`co_firstlineno` is the first line number of the function;
923 :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to
924 line numbers (for details see the source code of the interpreter);
925 :attr:`co_stacksize` is the required stack size (including local variables);
926 :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
929 single: co_argcount (code object attribute)
930 single: co_code (code object attribute)
931 single: co_consts (code object attribute)
932 single: co_filename (code object attribute)
933 single: co_firstlineno (code object attribute)
934 single: co_flags (code object attribute)
935 single: co_lnotab (code object attribute)
936 single: co_name (code object attribute)
937 single: co_names (code object attribute)
938 single: co_nlocals (code object attribute)
939 single: co_stacksize (code object attribute)
940 single: co_varnames (code object attribute)
941 single: co_cellvars (code object attribute)
942 single: co_freevars (code object attribute)
944 .. index:: object: generator
946 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
947 the function uses the ``*arguments`` syntax to accept an arbitrary number of
948 positional arguments; bit ``0x08`` is set if the function uses the
949 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
950 if the function is a generator.
952 Future feature declarations (``from __future__ import division``) also use bits
953 in :attr:`co_flags` to indicate whether a code object was compiled with a
954 particular feature enabled: bit ``0x2000`` is set if the function was compiled
955 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
958 Other bits in :attr:`co_flags` are reserved for internal use.
960 .. index:: single: documentation string
962 If a code object represents a function, the first item in :attr:`co_consts` is
963 the documentation string of the function, or ``None`` if undefined.
968 .. index:: object: frame
970 Frame objects represent execution frames. They may occur in traceback objects
974 single: f_back (frame attribute)
975 single: f_code (frame attribute)
976 single: f_globals (frame attribute)
977 single: f_locals (frame attribute)
978 single: f_lasti (frame attribute)
979 single: f_builtins (frame attribute)
980 single: f_restricted (frame attribute)
982 Special read-only attributes: :attr:`f_back` is to the previous stack frame
983 (towards the caller), or ``None`` if this is the bottom stack frame;
984 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
985 is the dictionary used to look up local variables; :attr:`f_globals` is used for
986 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
987 :attr:`f_restricted` is a flag indicating whether the function is executing in
988 restricted execution mode; :attr:`f_lasti` gives the precise instruction (this
989 is an index into the bytecode string of the code object).
992 single: f_trace (frame attribute)
993 single: f_exc_type (frame attribute)
994 single: f_exc_value (frame attribute)
995 single: f_exc_traceback (frame attribute)
996 single: f_lineno (frame attribute)
998 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
999 called at the start of each source code line (this is used by the debugger);
1000 :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
1001 last exception raised in the parent frame provided another exception was ever
1002 raised in the current frame (in all other cases they are None); :attr:`f_lineno`
1003 is the current line number of the frame --- writing to this from within a trace
1004 function jumps to the given line (only for the bottom-most frame). A debugger
1005 can implement a Jump command (aka Set Next Statement) by writing to f_lineno.
1011 pair: exception; handler
1012 pair: execution; stack
1013 single: exc_info (in module sys)
1014 single: exc_traceback (in module sys)
1015 single: last_traceback (in module sys)
1016 single: sys.exc_info
1017 single: sys.exc_traceback
1018 single: sys.last_traceback
1020 Traceback objects represent a stack trace of an exception. A traceback object
1021 is created when an exception occurs. When the search for an exception handler
1022 unwinds the execution stack, at each unwound level a traceback object is
1023 inserted in front of the current traceback. When an exception handler is
1024 entered, the stack trace is made available to the program. (See section
1025 :ref:`try`.) It is accessible as ``sys.exc_traceback``,
1026 and also as the third item of the tuple returned by ``sys.exc_info()``. The
1027 latter is the preferred interface, since it works correctly when the program is
1028 using multiple threads. When the program contains no suitable handler, the stack
1029 trace is written (nicely formatted) to the standard error stream; if the
1030 interpreter is interactive, it is also made available to the user as
1031 ``sys.last_traceback``.
1034 single: tb_next (traceback attribute)
1035 single: tb_frame (traceback attribute)
1036 single: tb_lineno (traceback attribute)
1037 single: tb_lasti (traceback attribute)
1040 Special read-only attributes: :attr:`tb_next` is the next level in the stack
1041 trace (towards the frame where the exception occurred), or ``None`` if there is
1042 no next level; :attr:`tb_frame` points to the execution frame of the current
1043 level; :attr:`tb_lineno` gives the line number where the exception occurred;
1044 :attr:`tb_lasti` indicates the precise instruction. The line number and last
1045 instruction in the traceback may differ from the line number of its frame object
1046 if the exception occurred in a :keyword:`try` statement with no matching except
1047 clause or with a finally clause.
1050 .. index:: builtin: slice
1052 Slice objects are used to represent slices when *extended slice syntax* is used.
1053 This is a slice using two colons, or multiple slices or ellipses separated by
1054 commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are
1055 also created by the built-in :func:`slice` function.
1058 single: start (slice object attribute)
1059 single: stop (slice object attribute)
1060 single: step (slice object attribute)
1062 Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is
1063 the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.
1064 These attributes can have any type.
1066 Slice objects support one method:
1069 .. method:: slice.indices(self, length)
1071 This method takes a single integer argument *length* and computes information
1072 about the extended slice that the slice object would describe if applied to a
1073 sequence of *length* items. It returns a tuple of three integers; respectively
1074 these are the *start* and *stop* indices and the *step* or stride length of the
1075 slice. Missing or out-of-bounds indices are handled in a manner consistent with
1078 .. versionadded:: 2.3
1080 Static method objects
1081 Static method objects provide a way of defeating the transformation of function
1082 objects to method objects described above. A static method object is a wrapper
1083 around any other object, usually a user-defined method object. When a static
1084 method object is retrieved from a class or a class instance, the object actually
1085 returned is the wrapped object, which is not subject to any further
1086 transformation. Static method objects are not themselves callable, although the
1087 objects they wrap usually are. Static method objects are created by the built-in
1088 :func:`staticmethod` constructor.
1090 Class method objects
1091 A class method object, like a static method object, is a wrapper around another
1092 object that alters the way in which that object is retrieved from classes and
1093 class instances. The behaviour of class method objects upon such retrieval is
1094 described above, under "User-defined methods". Class method objects are created
1095 by the built-in :func:`classmethod` constructor.
1100 New-style and classic classes
1101 =============================
1103 Classes and instances come in two flavors: old-style (or classic) and new-style.
1105 Up to Python 2.1, old-style classes were the only flavour available to the user.
1106 The concept of (old-style) class is unrelated to the concept of type: if *x* is
1107 an instance of an old-style class, then ``x.__class__`` designates the class of
1108 *x*, but ``type(x)`` is always ``<type 'instance'>``. This reflects the fact
1109 that all old-style instances, independently of their class, are implemented with
1110 a single built-in type, called ``instance``.
1112 New-style classes were introduced in Python 2.2 to unify classes and types. A
1113 new-style class is neither more nor less than a user-defined type. If *x* is an
1114 instance of a new-style class, then ``type(x)`` is typically the same as
1115 ``x.__class__`` (although this is not guaranteed - a new-style class instance is
1116 permitted to override the value returned for ``x.__class__``).
1118 The major motivation for introducing new-style classes is to provide a unified
1119 object model with a full meta-model. It also has a number of practical
1120 benefits, like the ability to subclass most built-in types, or the introduction
1121 of "descriptors", which enable computed properties.
1123 For compatibility reasons, classes are still old-style by default. New-style
1124 classes are created by specifying another new-style class (i.e. a type) as a
1125 parent class, or the "top-level type" :class:`object` if no other parent is
1126 needed. The behaviour of new-style classes differs from that of old-style
1127 classes in a number of important details in addition to what :func:`type`
1128 returns. Some of these changes are fundamental to the new object model, like
1129 the way special methods are invoked. Others are "fixes" that could not be
1130 implemented before for compatibility concerns, like the method resolution order
1131 in case of multiple inheritance.
1133 While this manual aims to provide comprehensive coverage of Python's class
1134 mechanics, it may still be lacking in some areas when it comes to its coverage
1135 of new-style classes. Please see http://www.python.org/doc/newstyle/ for
1136 sources of additional information.
1139 single: class; new-style
1140 single: class; classic
1141 single: class; old-style
1143 Old-style classes are removed in Python 3.0, leaving only the semantics of
1149 Special method names
1150 ====================
1153 pair: operator; overloading
1154 single: __getitem__() (mapping object method)
1156 A class can implement certain operations that are invoked by special syntax
1157 (such as arithmetic operations or subscripting and slicing) by defining methods
1158 with special names. This is Python's approach to :dfn:`operator overloading`,
1159 allowing classes to define their own behavior with respect to language
1160 operators. For instance, if a class defines a method named :meth:`__getitem__`,
1161 and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
1162 to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)``
1163 for new-style classes. Except where mentioned, attempts to execute an
1164 operation raise an exception when no appropriate method is defined (typically
1165 :exc:`AttributeError` or :exc:`TypeError`).
1167 When implementing a class that emulates any built-in type, it is important that
1168 the emulation only be implemented to the degree that it makes sense for the
1169 object being modelled. For example, some sequences may work well with retrieval
1170 of individual elements, but extracting a slice may not make sense. (One example
1171 of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
1179 .. method:: object.__new__(cls[, ...])
1181 .. index:: pair: subclassing; immutable types
1183 Called to create a new instance of class *cls*. :meth:`__new__` is a static
1184 method (special-cased so you need not declare it as such) that takes the class
1185 of which an instance was requested as its first argument. The remaining
1186 arguments are those passed to the object constructor expression (the call to the
1187 class). The return value of :meth:`__new__` should be the new object instance
1188 (usually an instance of *cls*).
1190 Typical implementations create a new instance of the class by invoking the
1191 superclass's :meth:`__new__` method using ``super(currentclass,
1192 cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
1193 newly-created instance as necessary before returning it.
1195 If :meth:`__new__` returns an instance of *cls*, then the new instance's
1196 :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
1197 *self* is the new instance and the remaining arguments are the same as were
1198 passed to :meth:`__new__`.
1200 If :meth:`__new__` does not return an instance of *cls*, then the new instance's
1201 :meth:`__init__` method will not be invoked.
1203 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
1204 int, str, or tuple) to customize instance creation. It is also commonly
1205 overridden in custom metaclasses in order to customize class creation.
1208 .. method:: object.__init__(self[, ...])
1210 .. index:: pair: class; constructor
1212 Called when the instance is created. The arguments are those passed to the
1213 class constructor expression. If a base class has an :meth:`__init__` method,
1214 the derived class's :meth:`__init__` method, if any, must explicitly call it to
1215 ensure proper initialization of the base class part of the instance; for
1216 example: ``BaseClass.__init__(self, [args...])``. As a special constraint on
1217 constructors, no value may be returned; doing so will cause a :exc:`TypeError`
1218 to be raised at runtime.
1221 .. method:: object.__del__(self)
1227 Called when the instance is about to be destroyed. This is also called a
1228 destructor. If a base class has a :meth:`__del__` method, the derived class's
1229 :meth:`__del__` method, if any, must explicitly call it to ensure proper
1230 deletion of the base class part of the instance. Note that it is possible
1231 (though not recommended!) for the :meth:`__del__` method to postpone destruction
1232 of the instance by creating a new reference to it. It may then be called at a
1233 later time when this new reference is deleted. It is not guaranteed that
1234 :meth:`__del__` methods are called for objects that still exist when the
1239 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
1240 the reference count for ``x`` by one, and the latter is only called when
1241 ``x``'s reference count reaches zero. Some common situations that may
1242 prevent the reference count of an object from going to zero include:
1243 circular references between objects (e.g., a doubly-linked list or a tree
1244 data structure with parent and child pointers); a reference to the object
1245 on the stack frame of a function that caught an exception (the traceback
1246 stored in ``sys.exc_traceback`` keeps the stack frame alive); or a
1247 reference to the object on the stack frame that raised an unhandled
1248 exception in interactive mode (the traceback stored in
1249 ``sys.last_traceback`` keeps the stack frame alive). The first situation
1250 can only be remedied by explicitly breaking the cycles; the latter two
1251 situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or
1252 ``sys.last_traceback``. Circular references which are garbage are
1253 detected when the option cycle detector is enabled (it's on by default),
1254 but can only be cleaned up if there are no Python-level :meth:`__del__`
1255 methods involved. Refer to the documentation for the :mod:`gc` module for
1256 more information about how :meth:`__del__` methods are handled by the
1257 cycle detector, particularly the description of the ``garbage`` value.
1261 Due to the precarious circumstances under which :meth:`__del__` methods are
1262 invoked, exceptions that occur during their execution are ignored, and a warning
1263 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
1264 response to a module being deleted (e.g., when execution of the program is
1265 done), other globals referenced by the :meth:`__del__` method may already have
1266 been deleted or in the process of being torn down (e.g. the import
1267 machinery shutting down). For this reason, :meth:`__del__` methods
1268 should do the absolute
1269 minimum needed to maintain external invariants. Starting with version 1.5,
1270 Python guarantees that globals whose name begins with a single underscore are
1271 deleted from their module before other globals are deleted; if no other
1272 references to such globals exist, this may help in assuring that imported
1273 modules are still available at the time when the :meth:`__del__` method is
1277 .. method:: object.__repr__(self)
1279 .. index:: builtin: repr
1281 Called by the :func:`repr` built-in function and by string conversions (reverse
1282 quotes) to compute the "official" string representation of an object. If at all
1283 possible, this should look like a valid Python expression that could be used to
1284 recreate an object with the same value (given an appropriate environment). If
1285 this is not possible, a string of the form ``<...some useful description...>``
1286 should be returned. The return value must be a string object. If a class
1287 defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also
1288 used when an "informal" string representation of instances of that class is
1292 pair: string; conversion
1293 pair: reverse; quotes
1294 pair: backward; quotes
1297 This is typically used for debugging, so it is important that the representation
1298 is information-rich and unambiguous.
1301 .. method:: object.__str__(self)
1307 Called by the :func:`str` built-in function and by the :keyword:`print`
1308 statement to compute the "informal" string representation of an object. This
1309 differs from :meth:`__repr__` in that it does not have to be a valid Python
1310 expression: a more convenient or concise representation may be used instead.
1311 The return value must be a string object.
1314 .. method:: object.__lt__(self, other)
1315 object.__le__(self, other)
1316 object.__eq__(self, other)
1317 object.__ne__(self, other)
1318 object.__gt__(self, other)
1319 object.__ge__(self, other)
1321 .. versionadded:: 2.1
1326 These are the so-called "rich comparison" methods, and are called for comparison
1327 operators in preference to :meth:`__cmp__` below. The correspondence between
1328 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
1329 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` and
1330 ``x<>y`` call ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
1333 A rich comparison method may return the singleton ``NotImplemented`` if it does
1334 not implement the operation for a given pair of arguments. By convention,
1335 ``False`` and ``True`` are returned for a successful comparison. However, these
1336 methods can return any value, so if the comparison operator is used in a Boolean
1337 context (e.g., in the condition of an ``if`` statement), Python will call
1338 :func:`bool` on the value to determine if the result is true or false.
1340 There are no implied relationships among the comparison operators. The truth
1341 of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when
1342 defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
1343 operators will behave as expected. See the paragraph on :meth:`__hash__` for
1344 some important notes on creating :term:`hashable` objects which support
1345 custom comparison operations and are usable as dictionary keys.
1347 There are no swapped-argument versions of these methods (to be used when the
1348 left argument does not support the operation but the right argument does);
1349 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
1350 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
1351 :meth:`__eq__` and :meth:`__ne__` are their own reflection.
1353 Arguments to rich comparison methods are never coerced.
1355 To automatically generate ordering operations from a single root operation,
1356 see the `Total Ordering recipe in the ASPN cookbook
1357 <http://code.activestate.com/recipes/576529/>`_\.
1359 .. method:: object.__cmp__(self, other)
1365 Called by comparison operations if rich comparison (see above) is not
1366 defined. Should return a negative integer if ``self < other``, zero if
1367 ``self == other``, a positive integer if ``self > other``. If no
1368 :meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class
1369 instances are compared by object identity ("address"). See also the
1370 description of :meth:`__hash__` for some important notes on creating
1371 :term:`hashable` objects which support custom comparison operations and are
1372 usable as dictionary keys. (Note: the restriction that exceptions are not
1373 propagated by :meth:`__cmp__` has been removed since Python 1.5.)
1376 .. method:: object.__rcmp__(self, other)
1378 .. versionchanged:: 2.1
1379 No longer supported.
1382 .. method:: object.__hash__(self)
1388 Called by built-in function :func:`hash` and for operations on members of
1389 hashed collections including :class:`set`, :class:`frozenset`, and
1390 :class:`dict`. :meth:`__hash__` should return an integer. The only required
1391 property is that objects which compare equal have the same hash value; it is
1392 advised to somehow mix together (e.g. using exclusive or) the hash values for
1393 the components of the object that also play a part in comparison of objects.
1395 If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
1396 should not define a :meth:`__hash__` operation either; if it defines
1397 :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances
1398 will not be usable in hashed collections. If a class defines mutable objects
1399 and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
1400 implement :meth:`__hash__`, since hashable collection implementations require
1401 that a object's hash value is immutable (if the object's hash value changes,
1402 it will be in the wrong hash bucket).
1404 User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
1405 by default; with them, all objects compare unequal (except with themselves)
1406 and ``x.__hash__()`` returns ``id(x)``.
1408 Classes which inherit a :meth:`__hash__` method from a parent class but
1409 change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash
1410 value returned is no longer appropriate (e.g. by switching to a value-based
1411 concept of equality instead of the default identity based equality) can
1412 explicitly flag themselves as being unhashable by setting ``__hash__ = None``
1413 in the class definition. Doing so means that not only will instances of the
1414 class raise an appropriate :exc:`TypeError` when a program attempts to
1415 retrieve their hash value, but they will also be correctly identified as
1416 unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike
1417 classes which define their own :meth:`__hash__` to explicitly raise
1420 .. versionchanged:: 2.5
1421 :meth:`__hash__` may now also return a long integer object; the 32-bit
1422 integer is then derived from the hash of that object.
1424 .. versionchanged:: 2.6
1425 :attr:`__hash__` may now be set to :const:`None` to explicitly flag
1426 instances of a class as unhashable.
1429 .. method:: object.__nonzero__(self)
1431 .. index:: single: __len__() (mapping object method)
1433 Called to implement truth value testing and the built-in operation ``bool()``;
1434 should return ``False`` or ``True``, or their integer equivalents ``0`` or
1435 ``1``. When this method is not defined, :meth:`__len__` is called, if it is
1436 defined, and the object is considered true if its result is nonzero.
1437 If a class defines neither :meth:`__len__` nor :meth:`__nonzero__`, all its
1438 instances are considered true.
1441 .. method:: object.__unicode__(self)
1443 .. index:: builtin: unicode
1445 Called to implement :func:`unicode` built-in; should return a Unicode object.
1446 When this method is not defined, string conversion is attempted, and the result
1447 of string conversion is converted to Unicode using the system default encoding.
1450 .. _attribute-access:
1452 Customizing attribute access
1453 ----------------------------
1455 The following methods can be defined to customize the meaning of attribute
1456 access (use of, assignment to, or deletion of ``x.name``) for class instances.
1459 .. method:: object.__getattr__(self, name)
1461 Called when an attribute lookup has not found the attribute in the usual places
1462 (i.e. it is not an instance attribute nor is it found in the class tree for
1463 ``self``). ``name`` is the attribute name. This method should return the
1464 (computed) attribute value or raise an :exc:`AttributeError` exception.
1466 .. index:: single: __setattr__() (object method)
1468 Note that if the attribute is found through the normal mechanism,
1469 :meth:`__getattr__` is not called. (This is an intentional asymmetry between
1470 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
1471 reasons and because otherwise :meth:`__getattr__` would have no way to access
1472 other attributes of the instance. Note that at least for instance variables,
1473 you can fake total control by not inserting any values in the instance attribute
1474 dictionary (but instead inserting them in another object). See the
1475 :meth:`__getattribute__` method below for a way to actually get total control in
1479 .. method:: object.__setattr__(self, name, value)
1481 Called when an attribute assignment is attempted. This is called instead of the
1482 normal mechanism (i.e. store the value in the instance dictionary). *name* is
1483 the attribute name, *value* is the value to be assigned to it.
1485 .. index:: single: __dict__ (instance attribute)
1487 If :meth:`__setattr__` wants to assign to an instance attribute, it should not
1488 simply execute ``self.name = value`` --- this would cause a recursive call to
1489 itself. Instead, it should insert the value in the dictionary of instance
1490 attributes, e.g., ``self.__dict__[name] = value``. For new-style classes,
1491 rather than accessing the instance dictionary, it should call the base class
1492 method with the same name, for example, ``object.__setattr__(self, name,
1496 .. method:: object.__delattr__(self, name)
1498 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
1499 should only be implemented if ``del obj.name`` is meaningful for the object.
1502 .. _new-style-attribute-access:
1504 More attribute access for new-style classes
1505 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1507 The following methods only apply to new-style classes.
1510 .. method:: object.__getattribute__(self, name)
1512 Called unconditionally to implement attribute accesses for instances of the
1513 class. If the class also defines :meth:`__getattr__`, the latter will not be
1514 called unless :meth:`__getattribute__` either calls it explicitly or raises an
1515 :exc:`AttributeError`. This method should return the (computed) attribute value
1516 or raise an :exc:`AttributeError` exception. In order to avoid infinite
1517 recursion in this method, its implementation should always call the base class
1518 method with the same name to access any attributes it needs, for example,
1519 ``object.__getattribute__(self, name)``.
1523 This method may still be bypassed when looking up special methods as the
1524 result of implicit invocation via language syntax or built-in functions.
1525 See :ref:`new-style-special-lookup`.
1530 Implementing Descriptors
1531 ^^^^^^^^^^^^^^^^^^^^^^^^
1533 The following methods only apply when an instance of the class containing the
1534 method (a so-called *descriptor* class) appears in the class dictionary of
1535 another new-style class, known as the *owner* class. In the examples below, "the
1536 attribute" refers to the attribute whose name is the key of the property in the
1537 owner class' ``__dict__``. Descriptors can only be implemented as new-style
1541 .. method:: object.__get__(self, instance, owner)
1543 Called to get the attribute of the owner class (class attribute access) or of an
1544 instance of that class (instance attribute access). *owner* is always the owner
1545 class, while *instance* is the instance that the attribute was accessed through,
1546 or ``None`` when the attribute is accessed through the *owner*. This method
1547 should return the (computed) attribute value or raise an :exc:`AttributeError`
1551 .. method:: object.__set__(self, instance, value)
1553 Called to set the attribute on an instance *instance* of the owner class to a
1557 .. method:: object.__delete__(self, instance)
1559 Called to delete the attribute on an instance *instance* of the owner class.
1562 .. _descriptor-invocation:
1564 Invoking Descriptors
1565 ^^^^^^^^^^^^^^^^^^^^
1567 In general, a descriptor is an object attribute with "binding behavior", one
1568 whose attribute access has been overridden by methods in the descriptor
1569 protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
1570 those methods are defined for an object, it is said to be a descriptor.
1572 The default behavior for attribute access is to get, set, or delete the
1573 attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
1574 starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
1575 continuing through the base classes of ``type(a)`` excluding metaclasses.
1577 However, if the looked-up value is an object defining one of the descriptor
1578 methods, then Python may override the default behavior and invoke the descriptor
1579 method instead. Where this occurs in the precedence chain depends on which
1580 descriptor methods were defined and how they were called. Note that descriptors
1581 are only invoked for new style objects or classes (ones that subclass
1582 :class:`object()` or :class:`type()`).
1584 The starting point for descriptor invocation is a binding, ``a.x``. How the
1585 arguments are assembled depends on ``a``:
1588 The simplest and least common call is when user code directly invokes a
1589 descriptor method: ``x.__get__(a)``.
1592 If binding to a new-style object instance, ``a.x`` is transformed into the call:
1593 ``type(a).__dict__['x'].__get__(a, type(a))``.
1596 If binding to a new-style class, ``A.x`` is transformed into the call:
1597 ``A.__dict__['x'].__get__(None, A)``.
1600 If ``a`` is an instance of :class:`super`, then the binding ``super(B,
1601 obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
1602 immediately preceding ``B`` and then invokes the descriptor with the call:
1603 ``A.__dict__['m'].__get__(obj, A)``.
1605 For instance bindings, the precedence of descriptor invocation depends on the
1606 which descriptor methods are defined. Normally, data descriptors define both
1607 :meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the
1608 :meth:`__get__` method. Data descriptors always override a redefinition in an
1609 instance dictionary. In contrast, non-data descriptors can be overridden by
1612 Python methods (including :func:`staticmethod` and :func:`classmethod`) are
1613 implemented as non-data descriptors. Accordingly, instances can redefine and
1614 override methods. This allows individual instances to acquire behaviors that
1615 differ from other instances of the same class.
1617 The :func:`property` function is implemented as a data descriptor. Accordingly,
1618 instances cannot override the behavior of a property.
1626 By default, instances of both old and new-style classes have a dictionary for
1627 attribute storage. This wastes space for objects having very few instance
1628 variables. The space consumption can become acute when creating large numbers
1631 The default can be overridden by defining *__slots__* in a new-style class
1632 definition. The *__slots__* declaration takes a sequence of instance variables
1633 and reserves just enough space in each instance to hold a value for each
1634 variable. Space is saved because *__dict__* is not created for each instance.
1639 This class variable can be assigned a string, iterable, or sequence of strings
1640 with variable names used by instances. If defined in a new-style class,
1641 *__slots__* reserves space for the declared variables and prevents the automatic
1642 creation of *__dict__* and *__weakref__* for each instance.
1644 .. versionadded:: 2.2
1646 Notes on using *__slots__*
1648 * When inheriting from a class without *__slots__*, the *__dict__* attribute of
1649 that class will always be accessible, so a *__slots__* definition in the
1650 subclass is meaningless.
1652 * Without a *__dict__* variable, instances cannot be assigned new variables not
1653 listed in the *__slots__* definition. Attempts to assign to an unlisted
1654 variable name raises :exc:`AttributeError`. If dynamic assignment of new
1655 variables is desired, then add ``'__dict__'`` to the sequence of strings in the
1656 *__slots__* declaration.
1658 .. versionchanged:: 2.3
1659 Previously, adding ``'__dict__'`` to the *__slots__* declaration would not
1660 enable the assignment of new attributes not specifically listed in the sequence
1661 of instance variable names.
1663 * Without a *__weakref__* variable for each instance, classes defining
1664 *__slots__* do not support weak references to its instances. If weak reference
1665 support is needed, then add ``'__weakref__'`` to the sequence of strings in the
1666 *__slots__* declaration.
1668 .. versionchanged:: 2.3
1669 Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not
1670 enable support for weak references.
1672 * *__slots__* are implemented at the class level by creating descriptors
1673 (:ref:`descriptors`) for each variable name. As a result, class attributes
1674 cannot be used to set default values for instance variables defined by
1675 *__slots__*; otherwise, the class attribute would overwrite the descriptor
1678 * The action of a *__slots__* declaration is limited to the class where it is
1679 defined. As a result, subclasses will have a *__dict__* unless they also define
1680 *__slots__* (which must only contain names of any *additional* slots).
1682 * If a class defines a slot also defined in a base class, the instance variable
1683 defined by the base class slot is inaccessible (except by retrieving its
1684 descriptor directly from the base class). This renders the meaning of the
1685 program undefined. In the future, a check may be added to prevent this.
1687 * Nonempty *__slots__* does not work for classes derived from "variable-length"
1688 built-in types such as :class:`long`, :class:`str` and :class:`tuple`.
1690 * Any non-string iterable may be assigned to *__slots__*. Mappings may also be
1691 used; however, in the future, special meaning may be assigned to the values
1692 corresponding to each key.
1694 * *__class__* assignment works only if both classes have the same *__slots__*.
1696 .. versionchanged:: 2.6
1697 Previously, *__class__* assignment raised an error if either new or old class
1703 Customizing class creation
1704 --------------------------
1706 By default, new-style classes are constructed using :func:`type`. A class
1707 definition is read into a separate namespace and the value of class name is
1708 bound to the result of ``type(name, bases, dict)``.
1710 When the class definition is read, if *__metaclass__* is defined then the
1711 callable assigned to it will be called instead of :func:`type`. This allows
1712 classes or functions to be written which monitor or alter the class creation
1715 * Modifying the class dictionary prior to the class being created.
1717 * Returning an instance of another class -- essentially performing the role of a
1720 These steps will have to be performed in the metaclass's :meth:`__new__` method
1721 -- :meth:`type.__new__` can then be called from this method to create a class
1722 with different properties. This example adds a new element to the class
1723 dictionary before creating the class::
1725 class metacls(type):
1726 def __new__(mcs, name, bases, dict):
1727 dict['foo'] = 'metacls was here'
1728 return type.__new__(mcs, name, bases, dict)
1730 You can of course also override other class methods (or add new methods); for
1731 example defining a custom :meth:`__call__` method in the metaclass allows custom
1732 behavior when the class is called, e.g. not always creating a new instance.
1735 .. data:: __metaclass__
1737 This variable can be any callable accepting arguments for ``name``, ``bases``,
1738 and ``dict``. Upon class creation, the callable is used instead of the built-in
1741 .. versionadded:: 2.2
1743 The appropriate metaclass is determined by the following precedence rules:
1745 * If ``dict['__metaclass__']`` exists, it is used.
1747 * Otherwise, if there is at least one base class, its metaclass is used (this
1748 looks for a *__class__* attribute first and if not found, uses its type).
1750 * Otherwise, if a global variable named __metaclass__ exists, it is used.
1752 * Otherwise, the old-style, classic metaclass (types.ClassType) is used.
1754 The potential uses for metaclasses are boundless. Some ideas that have been
1755 explored including logging, interface checking, automatic delegation, automatic
1756 property creation, proxies, frameworks, and automatic resource
1757 locking/synchronization.
1762 Emulating callable objects
1763 --------------------------
1766 .. method:: object.__call__(self[, args...])
1768 .. index:: pair: call; instance
1770 Called when the instance is "called" as a function; if this method is defined,
1771 ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
1776 Emulating container types
1777 -------------------------
1779 The following methods can be defined to implement container objects. Containers
1780 usually are sequences (such as lists or tuples) or mappings (like dictionaries),
1781 but can represent other containers as well. The first set of methods is used
1782 either to emulate a sequence or to emulate a mapping; the difference is that for
1783 a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
1784 N`` where *N* is the length of the sequence, or slice objects, which define a
1785 range of items. (For backwards compatibility, the method :meth:`__getslice__`
1786 (see below) can also be defined to handle simple, but not extended slices.) It
1787 is also recommended that mappings provide the methods :meth:`keys`,
1788 :meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
1789 :meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
1790 :meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar
1791 to those for Python's standard dictionary objects. The :mod:`UserDict` module
1792 provides a :class:`DictMixin` class to help create those methods from a base set
1793 of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
1794 :meth:`keys`. Mutable sequences should provide methods :meth:`append`,
1795 :meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
1796 :meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
1797 objects. Finally, sequence types should implement addition (meaning
1798 concatenation) and multiplication (meaning repetition) by defining the methods
1799 :meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
1800 :meth:`__rmul__` and :meth:`__imul__` described below; they should not define
1801 :meth:`__coerce__` or other numerical operators. It is recommended that both
1802 mappings and sequences implement the :meth:`__contains__` method to allow
1803 efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent
1804 of :meth:`has_key`; for sequences, it should search through the values. It is
1805 further recommended that both mappings and sequences implement the
1806 :meth:`__iter__` method to allow efficient iteration through the container; for
1807 mappings, :meth:`__iter__` should be the same as :meth:`iterkeys`; for
1808 sequences, it should iterate through the values.
1811 .. method:: object.__len__(self)
1815 single: __nonzero__() (object method)
1817 Called to implement the built-in function :func:`len`. Should return the length
1818 of the object, an integer ``>=`` 0. Also, an object that doesn't define a
1819 :meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is
1820 considered to be false in a Boolean context.
1823 .. method:: object.__getitem__(self, key)
1825 .. index:: object: slice
1827 Called to implement evaluation of ``self[key]``. For sequence types, the
1828 accepted keys should be integers and slice objects. Note that the special
1829 interpretation of negative indexes (if the class wishes to emulate a sequence
1830 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
1831 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
1832 for the sequence (after any special interpretation of negative values),
1833 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
1834 in the container), :exc:`KeyError` should be raised.
1838 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
1839 indexes to allow proper detection of the end of the sequence.
1842 .. method:: object.__setitem__(self, key, value)
1844 Called to implement assignment to ``self[key]``. Same note as for
1845 :meth:`__getitem__`. This should only be implemented for mappings if the
1846 objects support changes to the values for keys, or if new keys can be added, or
1847 for sequences if elements can be replaced. The same exceptions should be raised
1848 for improper *key* values as for the :meth:`__getitem__` method.
1851 .. method:: object.__delitem__(self, key)
1853 Called to implement deletion of ``self[key]``. Same note as for
1854 :meth:`__getitem__`. This should only be implemented for mappings if the
1855 objects support removal of keys, or for sequences if elements can be removed
1856 from the sequence. The same exceptions should be raised for improper *key*
1857 values as for the :meth:`__getitem__` method.
1860 .. method:: object.__iter__(self)
1862 This method is called when an iterator is required for a container. This method
1863 should return a new iterator object that can iterate over all the objects in the
1864 container. For mappings, it should iterate over the keys of the container, and
1865 should also be made available as the method :meth:`iterkeys`.
1867 Iterator objects also need to implement this method; they are required to return
1868 themselves. For more information on iterator objects, see :ref:`typeiter`.
1871 .. method:: object.__reversed__(self)
1873 Called (if present) by the :func:`reversed` built-in to implement
1874 reverse iteration. It should return a new iterator object that iterates
1875 over all the objects in the container in reverse order.
1877 If the :meth:`__reversed__` method is not provided, the :func:`reversed`
1878 built-in will fall back to using the sequence protocol (:meth:`__len__` and
1879 :meth:`__getitem__`). Objects that support the sequence protocol should
1880 only provide :meth:`__reversed__` if they can provide an implementation
1881 that is more efficient than the one provided by :func:`reversed`.
1883 .. versionadded:: 2.6
1886 The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
1887 implemented as an iteration through a sequence. However, container objects can
1888 supply the following special method with a more efficient implementation, which
1889 also does not require the object be a sequence.
1891 .. method:: object.__contains__(self, item)
1893 Called to implement membership test operators. Should return true if *item*
1894 is in *self*, false otherwise. For mapping objects, this should consider the
1895 keys of the mapping rather than the values or the key-item pairs.
1897 For objects that don't define :meth:`__contains__`, the membership test first
1898 tries iteration via :meth:`__iter__`, then the old sequence iteration
1899 protocol via :meth:`__getitem__`, see :ref:`this section in the language
1900 reference <membership-test-details>`.
1903 .. _sequence-methods:
1905 Additional methods for emulation of sequence types
1906 --------------------------------------------------
1908 The following optional methods can be defined to further emulate sequence
1909 objects. Immutable sequences methods should at most only define
1910 :meth:`__getslice__`; mutable sequences might define all three methods.
1913 .. method:: object.__getslice__(self, i, j)
1916 Support slice objects as parameters to the :meth:`__getitem__` method.
1917 (However, built-in types in CPython currently still implement
1918 :meth:`__getslice__`. Therefore, you have to override it in derived
1919 classes when implementing slicing.)
1921 Called to implement evaluation of ``self[i:j]``. The returned object should be
1922 of the same type as *self*. Note that missing *i* or *j* in the slice
1923 expression are replaced by zero or ``sys.maxint``, respectively. If negative
1924 indexes are used in the slice, the length of the sequence is added to that
1925 index. If the instance does not implement the :meth:`__len__` method, an
1926 :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this
1927 way are not still negative. Indexes which are greater than the length of the
1928 sequence are not modified. If no :meth:`__getslice__` is found, a slice object
1929 is created instead, and passed to :meth:`__getitem__` instead.
1932 .. method:: object.__setslice__(self, i, j, sequence)
1934 Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
1935 for :meth:`__getslice__`.
1937 This method is deprecated. If no :meth:`__setslice__` is found, or for extended
1938 slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
1939 :meth:`__setitem__`, instead of :meth:`__setslice__` being called.
1942 .. method:: object.__delslice__(self, i, j)
1944 Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
1945 :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
1946 found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
1947 created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
1950 Notice that these methods are only invoked when a single slice with a single
1951 colon is used, and the slice method is available. For slice operations
1952 involving extended slice notation, or in absence of the slice methods,
1953 :meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
1954 slice object as argument.
1956 The following example demonstrate how to make your program or module compatible
1957 with earlier versions of Python (assuming that methods :meth:`__getitem__`,
1958 :meth:`__setitem__` and :meth:`__delitem__` support slice objects as
1963 def __getitem__(self, index):
1965 def __setitem__(self, index, value):
1967 def __delitem__(self, index):
1970 if sys.version_info < (2, 0):
1971 # They won't be defined if version is at least 2.0 final
1973 def __getslice__(self, i, j):
1974 return self[max(0, i):max(0, j):]
1975 def __setslice__(self, i, j, seq):
1976 self[max(0, i):max(0, j):] = seq
1977 def __delslice__(self, i, j):
1978 del self[max(0, i):max(0, j):]
1981 Note the calls to :func:`max`; these are necessary because of the handling of
1982 negative indices before the :meth:`__\*slice__` methods are called. When
1983 negative indexes are used, the :meth:`__\*item__` methods receive them as
1984 provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index
1985 values. For each negative index value, the length of the sequence is added to
1986 the index before calling the method (which may still result in a negative
1987 index); this is the customary handling of negative indexes by the built-in
1988 sequence types, and the :meth:`__\*item__` methods are expected to do this as
1989 well. However, since they should already be doing that, negative indexes cannot
1990 be passed in; they must be constrained to the bounds of the sequence before
1991 being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)``
1992 conveniently returns the proper value.
1997 Emulating numeric types
1998 -----------------------
2000 The following methods can be defined to emulate numeric objects. Methods
2001 corresponding to operations that are not supported by the particular kind of
2002 number implemented (e.g., bitwise operations for non-integral numbers) should be
2006 .. method:: object.__add__(self, other)
2007 object.__sub__(self, other)
2008 object.__mul__(self, other)
2009 object.__floordiv__(self, other)
2010 object.__mod__(self, other)
2011 object.__divmod__(self, other)
2012 object.__pow__(self, other[, modulo])
2013 object.__lshift__(self, other)
2014 object.__rshift__(self, other)
2015 object.__and__(self, other)
2016 object.__xor__(self, other)
2017 object.__or__(self, other)
2024 These methods are called to implement the binary arithmetic operations (``+``,
2025 ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
2026 ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
2027 ``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
2028 method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
2029 equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
2030 related to :meth:`__truediv__` (described below). Note that :meth:`__pow__`
2031 should be defined to accept an optional third argument if the ternary version of
2032 the built-in :func:`pow` function is to be supported.
2034 If one of those methods does not support the operation with the supplied
2035 arguments, it should return ``NotImplemented``.
2038 .. method:: object.__div__(self, other)
2039 object.__truediv__(self, other)
2041 The division operator (``/``) is implemented by these methods. The
2042 :meth:`__truediv__` method is used when ``__future__.division`` is in effect,
2043 otherwise :meth:`__div__` is used. If only one of these two methods is defined,
2044 the object will not support division in the alternate context; :exc:`TypeError`
2045 will be raised instead.
2048 .. method:: object.__radd__(self, other)
2049 object.__rsub__(self, other)
2050 object.__rmul__(self, other)
2051 object.__rdiv__(self, other)
2052 object.__rtruediv__(self, other)
2053 object.__rfloordiv__(self, other)
2054 object.__rmod__(self, other)
2055 object.__rdivmod__(self, other)
2056 object.__rpow__(self, other)
2057 object.__rlshift__(self, other)
2058 object.__rrshift__(self, other)
2059 object.__rand__(self, other)
2060 object.__rxor__(self, other)
2061 object.__ror__(self, other)
2067 These methods are called to implement the binary arithmetic operations (``+``,
2068 ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``,
2069 ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are
2070 only called if the left operand does not support the corresponding operation and
2071 the operands are of different types. [#]_ For instance, to evaluate the
2072 expression ``x - y``, where *y* is an instance of a class that has an
2073 :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns
2076 .. index:: builtin: pow
2078 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
2079 coercion rules would become too complicated).
2083 If the right operand's type is a subclass of the left operand's type and that
2084 subclass provides the reflected method for the operation, this method will be
2085 called before the left operand's non-reflected method. This behavior allows
2086 subclasses to override their ancestors' operations.
2089 .. method:: object.__iadd__(self, other)
2090 object.__isub__(self, other)
2091 object.__imul__(self, other)
2092 object.__idiv__(self, other)
2093 object.__itruediv__(self, other)
2094 object.__ifloordiv__(self, other)
2095 object.__imod__(self, other)
2096 object.__ipow__(self, other[, modulo])
2097 object.__ilshift__(self, other)
2098 object.__irshift__(self, other)
2099 object.__iand__(self, other)
2100 object.__ixor__(self, other)
2101 object.__ior__(self, other)
2103 These methods are called to implement the augmented arithmetic assignments
2104 (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
2105 ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
2106 in-place (modifying *self*) and return the result (which could be, but does
2107 not have to be, *self*). If a specific method is not defined, the augmented
2108 assignment falls back to the normal methods. For instance, to execute the
2109 statement ``x += y``, where *x* is an instance of a class that has an
2110 :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
2111 of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
2112 and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
2115 .. method:: object.__neg__(self)
2116 object.__pos__(self)
2117 object.__abs__(self)
2118 object.__invert__(self)
2120 .. index:: builtin: abs
2122 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
2126 .. method:: object.__complex__(self)
2127 object.__int__(self)
2128 object.__long__(self)
2129 object.__float__(self)
2137 Called to implement the built-in functions :func:`complex`, :func:`int`,
2138 :func:`long`, and :func:`float`. Should return a value of the appropriate type.
2141 .. method:: object.__oct__(self)
2142 object.__hex__(self)
2148 Called to implement the built-in functions :func:`oct` and :func:`hex`. Should
2149 return a string value.
2152 .. method:: object.__index__(self)
2154 Called to implement :func:`operator.index`. Also called whenever Python needs
2155 an integer object (such as in slicing). Must return an integer (int or long).
2157 .. versionadded:: 2.5
2160 .. method:: object.__coerce__(self, other)
2162 Called to implement "mixed-mode" numeric arithmetic. Should either return a
2163 2-tuple containing *self* and *other* converted to a common numeric type, or
2164 ``None`` if conversion is impossible. When the common type would be the type of
2165 ``other``, it is sufficient to return ``None``, since the interpreter will also
2166 ask the other object to attempt a coercion (but sometimes, if the implementation
2167 of the other type cannot be changed, it is useful to do the conversion to the
2168 other type here). A return value of ``NotImplemented`` is equivalent to
2177 This section used to document the rules for coercion. As the language has
2178 evolved, the coercion rules have become hard to document precisely; documenting
2179 what one version of one particular implementation does is undesirable. Instead,
2180 here are some informal guidelines regarding coercion. In Python 3.0, coercion
2181 will not be supported.
2185 If the left operand of a % operator is a string or Unicode object, no coercion
2186 takes place and the string formatting operation is invoked instead.
2190 It is no longer recommended to define a coercion operation. Mixed-mode
2191 operations on types that don't define coercion pass the original arguments to
2196 New-style classes (those derived from :class:`object`) never invoke the
2197 :meth:`__coerce__` method in response to a binary operator; the only time
2198 :meth:`__coerce__` is invoked is when the built-in function :func:`coerce` is
2203 For most intents and purposes, an operator that returns ``NotImplemented`` is
2204 treated the same as one that is not implemented at all.
2208 Below, :meth:`__op__` and :meth:`__rop__` are used to signify the generic method
2209 names corresponding to an operator; :meth:`__iop__` is used for the
2210 corresponding in-place operator. For example, for the operator '``+``',
2211 :meth:`__add__` and :meth:`__radd__` are used for the left and right variant of
2212 the binary operator, and :meth:`__iadd__` for the in-place variant.
2216 For objects *x* and *y*, first ``x.__op__(y)`` is tried. If this is not
2217 implemented or returns ``NotImplemented``, ``y.__rop__(x)`` is tried. If this
2218 is also not implemented or returns ``NotImplemented``, a :exc:`TypeError`
2219 exception is raised. But see the following exception:
2223 Exception to the previous item: if the left operand is an instance of a built-in
2224 type or a new-style class, and the right operand is an instance of a proper
2225 subclass of that type or class and overrides the base's :meth:`__rop__` method,
2226 the right operand's :meth:`__rop__` method is tried *before* the left operand's
2227 :meth:`__op__` method.
2229 This is done so that a subclass can completely override binary operators.
2230 Otherwise, the left operand's :meth:`__op__` method would always accept the
2231 right operand: when an instance of a given class is expected, an instance of a
2232 subclass of that class is always acceptable.
2236 When either operand type defines a coercion, this coercion is called before that
2237 type's :meth:`__op__` or :meth:`__rop__` method is called, but no sooner. If
2238 the coercion returns an object of a different type for the operand whose
2239 coercion is invoked, part of the process is redone using the new object.
2243 When an in-place operator (like '``+=``') is used, if the left operand
2244 implements :meth:`__iop__`, it is invoked without any coercion. When the
2245 operation falls back to :meth:`__op__` and/or :meth:`__rop__`, the normal
2246 coercion rules apply.
2250 In ``x + y``, if *x* is a sequence that implements sequence concatenation,
2251 sequence concatenation is invoked.
2255 In ``x * y``, if one operator is a sequence that implements sequence
2256 repetition, and the other is an integer (:class:`int` or :class:`long`),
2257 sequence repetition is invoked.
2261 Rich comparisons (implemented by methods :meth:`__eq__` and so on) never use
2262 coercion. Three-way comparison (implemented by :meth:`__cmp__`) does use
2263 coercion under the same conditions as other binary operations use it.
2267 In the current implementation, the built-in numeric types :class:`int`,
2268 :class:`long` and :class:`float` do not use coercion; the type :class:`complex`
2269 however does use coercion for binary operators and rich comparisons, despite
2270 the above rules. The difference can become apparent when subclassing these
2271 types. Over time, the type :class:`complex` may be fixed to avoid coercion.
2272 All these types implement a :meth:`__coerce__` method, for use by the built-in
2273 :func:`coerce` function.
2276 .. _context-managers:
2278 With Statement Context Managers
2279 -------------------------------
2281 .. versionadded:: 2.5
2283 A :dfn:`context manager` is an object that defines the runtime context to be
2284 established when executing a :keyword:`with` statement. The context manager
2285 handles the entry into, and the exit from, the desired runtime context for the
2286 execution of the block of code. Context managers are normally invoked using the
2287 :keyword:`with` statement (described in section :ref:`with`), but can also be
2288 used by directly invoking their methods.
2292 single: context manager
2294 Typical uses of context managers include saving and restoring various kinds of
2295 global state, locking and unlocking resources, closing opened files, etc.
2297 For more information on context managers, see :ref:`typecontextmanager`.
2300 .. method:: object.__enter__(self)
2302 Enter the runtime context related to this object. The :keyword:`with` statement
2303 will bind this method's return value to the target(s) specified in the
2304 :keyword:`as` clause of the statement, if any.
2307 .. method:: object.__exit__(self, exc_type, exc_value, traceback)
2309 Exit the runtime context related to this object. The parameters describe the
2310 exception that caused the context to be exited. If the context was exited
2311 without an exception, all three arguments will be :const:`None`.
2313 If an exception is supplied, and the method wishes to suppress the exception
2314 (i.e., prevent it from being propagated), it should return a true value.
2315 Otherwise, the exception will be processed normally upon exit from this method.
2317 Note that :meth:`__exit__` methods should not reraise the passed-in exception;
2318 this is the caller's responsibility.
2323 :pep:`0343` - The "with" statement
2324 The specification, background, and examples for the Python :keyword:`with`
2328 .. _old-style-special-lookup:
2330 Special method lookup for old-style classes
2331 -------------------------------------------
2333 For old-style classes, special methods are always looked up in exactly the
2334 same way as any other method or attribute. This is the case regardless of
2335 whether the method is being looked up explicitly as in ``x.__getitem__(i)``
2336 or implicitly as in ``x[i]``.
2338 This behaviour means that special methods may exhibit different behaviour
2339 for different instances of a single old-style class if the appropriate
2340 special attributes are set differently::
2347 >>> c1.__len__ = lambda: 5
2348 >>> c2.__len__ = lambda: 9
2355 .. _new-style-special-lookup:
2357 Special method lookup for new-style classes
2358 -------------------------------------------
2360 For new-style classes, implicit invocations of special methods are only guaranteed
2361 to work correctly if defined on an object's type, not in the object's instance
2362 dictionary. That behaviour is the reason why the following code raises an
2363 exception (unlike the equivalent example with old-style classes)::
2365 >>> class C(object):
2369 >>> c.__len__ = lambda: 5
2371 Traceback (most recent call last):
2372 File "<stdin>", line 1, in <module>
2373 TypeError: object of type 'C' has no len()
2375 The rationale behind this behaviour lies with a number of special methods such
2376 as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
2377 including type objects. If the implicit lookup of these methods used the
2378 conventional lookup process, they would fail when invoked on the type object
2381 >>> 1 .__hash__() == hash(1)
2383 >>> int.__hash__() == hash(int)
2384 Traceback (most recent call last):
2385 File "<stdin>", line 1, in <module>
2386 TypeError: descriptor '__hash__' of 'int' object needs an argument
2388 Incorrectly attempting to invoke an unbound method of a class in this way is
2389 sometimes referred to as 'metaclass confusion', and is avoided by bypassing
2390 the instance when looking up special methods::
2392 >>> type(1).__hash__(1) == hash(1)
2394 >>> type(int).__hash__(int) == hash(int)
2397 In addition to bypassing any instance attributes in the interest of
2398 correctness, implicit special method lookup generally also bypasses the
2399 :meth:`__getattribute__` method even of the object's metaclass::
2401 >>> class Meta(type):
2402 ... def __getattribute__(*args):
2403 ... print "Metaclass getattribute invoked"
2404 ... return type.__getattribute__(*args)
2406 >>> class C(object):
2407 ... __metaclass__ = Meta
2408 ... def __len__(self):
2410 ... def __getattribute__(*args):
2411 ... print "Class getattribute invoked"
2412 ... return object.__getattribute__(*args)
2415 >>> c.__len__() # Explicit lookup via instance
2416 Class getattribute invoked
2418 >>> type(c).__len__(c) # Explicit lookup via type
2419 Metaclass getattribute invoked
2421 >>> len(c) # Implicit lookup
2424 Bypassing the :meth:`__getattribute__` machinery in this fashion
2425 provides significant scope for speed optimisations within the
2426 interpreter, at the cost of some flexibility in the handling of
2427 special methods (the special method *must* be set on the class
2428 object itself in order to be consistently invoked by the interpreter).
2431 .. rubric:: Footnotes
2433 .. [#] It *is* possible in some cases to change an object's type, under certain
2434 controlled conditions. It generally isn't a good idea though, since it can
2435 lead to some very strange behaviour if it is handled incorrectly.
2437 .. [#] A descriptor can define any combination of :meth:`__get__`,
2438 :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`,
2439 then accessing the attribute even on an instance will return the descriptor
2440 object itself. If the descriptor defines :meth:`__set__` and/or
2441 :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a
2442 non-data descriptor.
2444 .. [#] For operands of the same type, it is assumed that if the non-reflected method
2445 (such as :meth:`__add__`) fails the operation is not supported, which is why the
2446 reflected method is not called.