diff options
Diffstat (limited to 'Doc/reference/datamodel.rst')
| -rw-r--r-- | Doc/reference/datamodel.rst | 2245 |
1 files changed, 2245 insertions, 0 deletions
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst new file mode 100644 index 0000000..3e55372 --- /dev/null +++ b/Doc/reference/datamodel.rst @@ -0,0 +1,2245 @@ + +.. _datamodel: + +********** +Data model +********** + + +.. _objects: + +Objects, values and types +========================= + +.. index:: + single: object + single: data + +:dfn:`Objects` are Python's abstraction for data. All data in a Python program +is represented by objects or by relations between objects. (In a sense, and in +conformance to Von Neumann's model of a "stored program computer," code is also +represented by objects.) + +.. index:: + builtin: id + builtin: type + single: identity of an object + single: value of an object + single: type of an object + single: mutable object + single: immutable object + +Every object has an identity, a type and a value. An object's *identity* never +changes once it has been created; you may think of it as the object's address in +memory. The ':keyword:`is`' operator compares the identity of two objects; the +:func:`id` function returns an integer representing its identity (currently +implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_ +An object's type determines the operations that the object supports (e.g., "does +it have a length?") and also defines the possible values for objects of that +type. The :func:`type` function returns an object's type (which is an object +itself). The *value* of some objects can change. Objects whose value can +change are said to be *mutable*; objects whose value is unchangeable once they +are created are called *immutable*. (The value of an immutable container object +that contains a reference to a mutable object can change when the latter's value +is changed; however the container is still considered immutable, because the +collection of objects it contains cannot be changed. So, immutability is not +strictly the same as having an unchangeable value, it is more subtle.) An +object's mutability is determined by its type; for instance, numbers, strings +and tuples are immutable, while dictionaries and lists are mutable. + +.. index:: + single: garbage collection + single: reference counting + single: unreachable object + +Objects are never explicitly destroyed; however, when they become unreachable +they may be garbage-collected. An implementation is allowed to postpone garbage +collection or omit it altogether --- it is a matter of implementation quality +how garbage collection is implemented, as long as no objects are collected that +are still reachable. (Implementation note: the current implementation uses a +reference-counting scheme with (optional) delayed detection of cyclically linked +garbage, which collects most objects as soon as they become unreachable, but is +not guaranteed to collect garbage containing circular references. See the +documentation of the :mod:`gc` module for information on controlling the +collection of cyclic garbage.) + +Note that the use of the implementation's tracing or debugging facilities may +keep objects alive that would normally be collectable. Also note that catching +an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep +objects alive. + +Some objects contain references to "external" resources such as open files or +windows. It is understood that these resources are freed when the object is +garbage-collected, but since garbage collection is not guaranteed to happen, +such objects also provide an explicit way to release the external resource, +usually a :meth:`close` method. Programs are strongly recommended to explicitly +close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement +provides a convenient way to do this. + +.. index:: single: container + +Some objects contain references to other objects; these are called *containers*. +Examples of containers are tuples, lists and dictionaries. The references are +part of a container's value. In most cases, when we talk about the value of a +container, we imply the values, not the identities of the contained objects; +however, when we talk about the mutability of a container, only the identities +of the immediately contained objects are implied. So, if an immutable container +(like a tuple) contains a reference to a mutable object, its value changes if +that mutable object is changed. + +Types affect almost all aspects of object behavior. Even the importance of +object identity is affected in some sense: for immutable types, operations that +compute new values may actually return a reference to any existing object with +the same type and value, while for mutable objects this is not allowed. E.g., +after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object +with the value one, depending on the implementation, but after ``c = []; d = +[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly +created empty lists. (Note that ``c = d = []`` assigns the same object to both +``c`` and ``d``.) + + +.. _types: + +The standard type hierarchy +=========================== + +.. index:: + single: type + pair: data; type + pair: type; hierarchy + pair: extension; module + pair: C; language + +Below is a list of the types that are built into Python. Extension modules +(written in C, Java, or other languages, depending on the implementation) can +define additional types. Future versions of Python may add types to the type +hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.). + +.. index:: + single: attribute + pair: special; attribute + triple: generic; special; attribute + +Some of the type descriptions below contain a paragraph listing 'special +attributes.' These are attributes that provide access to the implementation and +are not intended for general use. Their definition may change in the future. + +None + .. index:: object: None + + This type has a single value. There is a single object with this value. This + object is accessed through the built-in name ``None``. It is used to signify the + absence of a value in many situations, e.g., it is returned from functions that + don't explicitly return anything. Its truth value is false. + +NotImplemented + .. index:: object: NotImplemented + + This type has a single value. There is a single object with this value. This + object is accessed through the built-in name ``NotImplemented``. Numeric methods + and rich comparison methods may return this value if they do not implement the + operation for the operands provided. (The interpreter will then try the + reflected operation, or some other fallback, depending on the operator.) Its + truth value is true. + +Ellipsis + .. index:: object: Ellipsis + + This type has a single value. There is a single object with this value. This + object is accessed through the built-in name ``Ellipsis``. It is used to + indicate the presence of the ``...`` syntax in a slice. Its truth value is + true. + +Numbers + .. index:: object: numeric + + These are created by numeric literals and returned as results by arithmetic + operators and arithmetic built-in functions. Numeric objects are immutable; + once created their value never changes. Python numbers are of course strongly + related to mathematical numbers, but subject to the limitations of numerical + representation in computers. + + Python distinguishes between integers, floating point numbers, and complex + numbers: + + Integers + .. index:: object: integer + + These represent elements from the mathematical set of integers (positive and + negative). + + There are three types of integers: + + Plain integers + .. index:: + object: plain integer + single: OverflowError (built-in exception) + + These represent numbers in the range -2147483648 through 2147483647. (The range + may be larger on machines with a larger natural word size, but not smaller.) + When the result of an operation would fall outside this range, the result is + normally returned as a long integer (in some cases, the exception + :exc:`OverflowError` is raised instead). For the purpose of shift and mask + operations, integers are assumed to have a binary, 2's complement notation using + 32 or more bits, and hiding no bits from the user (i.e., all 4294967296 + different bit patterns correspond to different values). + + Long integers + .. index:: object: long integer + + These represent numbers in an unlimited range, subject to available (virtual) + memory only. For the purpose of shift and mask operations, a binary + representation is assumed, and negative numbers are represented in a variant of + 2's complement which gives the illusion of an infinite string of sign bits + extending to the left. + + Booleans + .. index:: + object: Boolean + single: False + single: True + + These represent the truth values False and True. The two objects representing + the values False and True are the only Boolean objects. The Boolean type is a + subtype of plain integers, and Boolean values behave like the values 0 and 1, + respectively, in almost all contexts, the exception being that when converted to + a string, the strings ``"False"`` or ``"True"`` are returned, respectively. + + .. index:: pair: integer; representation + + The rules for integer representation are intended to give the most meaningful + interpretation of shift and mask operations involving negative integers and the + least surprises when switching between the plain and long integer domains. Any + operation except left shift, if it yields a result in the plain integer domain + without causing overflow, will yield the same result in the long integer domain + or when using mixed operands. + + .. % Integers + + Floating point numbers + .. index:: + object: floating point + pair: floating point; number + pair: C; language + pair: Java; language + + These represent machine-level double precision floating point numbers. You are + at the mercy of the underlying machine architecture (and C or Java + implementation) for the accepted range and handling of overflow. Python does not + support single-precision floating point numbers; the savings in processor and + memory usage that are usually the reason for using these is dwarfed by the + overhead of using objects in Python, so there is no reason to complicate the + language with two kinds of floating point numbers. + + Complex numbers + .. index:: + object: complex + pair: complex; number + + These represent complex numbers as a pair of machine-level double precision + floating point numbers. The same caveats apply as for floating point numbers. + The real and imaginary parts of a complex number ``z`` can be retrieved through + the read-only attributes ``z.real`` and ``z.imag``. + + .. % Numbers + +Sequences + .. index:: + builtin: len + object: sequence + single: index operation + single: item selection + single: subscription + + These represent finite ordered sets indexed by non-negative numbers. The + built-in function :func:`len` returns the number of items of a sequence. When + the length of a sequence is *n*, the index set contains the numbers 0, 1, + ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. + + .. index:: single: slicing + + Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such + that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a + sequence of the same type. This implies that the index set is renumbered so + that it starts at 0. + + .. index:: single: extended slicing + + Some sequences also support "extended slicing" with a third "step" parameter: + ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n* + ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*. + + Sequences are distinguished according to their mutability: + + Immutable sequences + .. index:: + object: immutable sequence + object: immutable + + An object of an immutable sequence type cannot change once it is created. (If + the object contains references to other objects, these other objects may be + mutable and may be changed; however, the collection of objects directly + referenced by an immutable object cannot change.) + + The following types are immutable sequences: + + Strings + .. index:: + builtin: chr + builtin: ord + object: string + single: character + single: byte + single: ASCII@ASCII + + The items of a string are characters. There is no separate character type; a + character is represented by a string of one item. Characters represent (at + least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert + between characters and nonnegative integers representing the byte values. Bytes + with the values 0-127 usually represent the corresponding ASCII values, but the + interpretation of values is up to the program. The string data type is also + used to represent arrays of bytes, e.g., to hold data read from a file. + + .. index:: + single: ASCII@ASCII + single: EBCDIC + single: character set + pair: string; comparison + builtin: chr + builtin: ord + + (On systems whose native character set is not ASCII, strings may use EBCDIC in + their internal representation, provided the functions :func:`chr` and + :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison + preserves the ASCII order. Or perhaps someone can propose a better rule?) + + Unicode + .. index:: + builtin: unichr + builtin: ord + builtin: unicode + object: unicode + single: character + single: integer + single: Unicode + + The items of a Unicode object are Unicode code units. A Unicode code unit is + represented by a Unicode object of one item and can hold either a 16-bit or + 32-bit value representing a Unicode ordinal (the maximum value for the ordinal + is given in ``sys.maxunicode``, and depends on how Python is configured at + compile time). Surrogate pairs may be present in the Unicode object, and will + be reported as two separate items. The built-in functions :func:`unichr` and + :func:`ord` convert between code units and nonnegative integers representing the + Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to + other encodings are possible through the Unicode method :meth:`encode` and the + built-in function :func:`unicode`. + + Tuples + .. index:: + object: tuple + pair: singleton; tuple + pair: empty; tuple + + The items of a tuple are arbitrary Python objects. Tuples of two or more items + are formed by comma-separated lists of expressions. A tuple of one item (a + 'singleton') can be formed by affixing a comma to an expression (an expression + by itself does not create a tuple, since parentheses must be usable for grouping + of expressions). An empty tuple can be formed by an empty pair of parentheses. + + .. % Immutable sequences + + Mutable sequences + .. index:: + object: mutable sequence + object: mutable + pair: assignment; statement + single: delete + statement: del + single: subscription + single: slicing + + Mutable sequences can be changed after they are created. The subscription and + slicing notations can be used as the target of assignment and :keyword:`del` + (delete) statements. + + There is currently a single intrinsic mutable sequence type: + + Lists + .. index:: object: list + + The items of a list are arbitrary Python objects. Lists are formed by placing a + comma-separated list of expressions in square brackets. (Note that there are no + special cases needed to form lists of length 0 or 1.) + + .. index:: module: array + + The extension module :mod:`array` provides an additional example of a mutable + sequence type. + + .. % Mutable sequences + + .. % Sequences + +Set types + .. index:: + builtin: len + object: set type + + These represent unordered, finite sets of unique, immutable objects. As such, + they cannot be indexed by any subscript. However, they can be iterated over, and + the built-in function :func:`len` returns the number of items in a set. Common + uses for sets are fast membership testing, removing duplicates from a sequence, + and computing mathematical operations such as intersection, union, difference, + and symmetric difference. + + For set elements, the same immutability rules apply as for dictionary keys. Note + that numeric types obey the normal rules for numeric comparison: if two numbers + compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a + set. + + There are currently two intrinsic set types: + + Sets + .. index:: object: set + + These represent a mutable set. They are created by the built-in :func:`set` + constructor and can be modified afterwards by several methods, such as + :meth:`add`. + + Frozen sets + .. index:: object: frozenset + + These represent an immutable set. They are created by the built-in + :func:`frozenset` constructor. As a frozenset is immutable and hashable, it can + be used again as an element of another set, or as a dictionary key. + + .. % Set types + +Mappings + .. index:: + builtin: len + single: subscription + object: mapping + + These represent finite sets of objects indexed by arbitrary index sets. The + subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping + ``a``; this can be used in expressions and as the target of assignments or + :keyword:`del` statements. The built-in function :func:`len` returns the number + of items in a mapping. + + There is currently a single intrinsic mapping type: + + Dictionaries + .. index:: object: dictionary + + These represent finite sets of objects indexed by nearly arbitrary values. The + only types of values not acceptable as keys are values containing lists or + dictionaries or other mutable types that are compared by value rather than by + object identity, the reason being that the efficient implementation of + dictionaries requires a key's hash value to remain constant. Numeric types used + for keys obey the normal rules for numeric comparison: if two numbers compare + equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index + the same dictionary entry. + + Dictionaries are mutable; they can be created by the ``{...}`` notation (see + section :ref:`dict`). + + .. index:: + module: dbm + module: gdbm + module: bsddb + + The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide + additional examples of mapping types. + + .. % Mapping types + +Callable types + .. index:: + object: callable + pair: function; call + single: invocation + pair: function; argument + + These are the types to which the function call operation (see section + :ref:`calls`) can be applied: + + User-defined functions + .. index:: + pair: user-defined; function + object: function + object: user-defined function + + A user-defined function object is created by a function definition (see + section :ref:`function`). It should be called with an argument list + containing the same number of items as the function's formal parameter + list. + + Special attributes: + + +-----------------------+-------------------------------+-----------+ + | Attribute | Meaning | | + +=======================+===============================+===========+ + | :attr:`func_doc` | The function's documentation | Writable | + | | string, or ``None`` if | | + | | unavailable | | + +-----------------------+-------------------------------+-----------+ + | :attr:`__doc__` | Another way of spelling | Writable | + | | :attr:`func_doc` | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_name` | The function's name | Writable | + +-----------------------+-------------------------------+-----------+ + | :attr:`__name__` | Another way of spelling | Writable | + | | :attr:`func_name` | | + +-----------------------+-------------------------------+-----------+ + | :attr:`__module__` | The name of the module the | Writable | + | | function was defined in, or | | + | | ``None`` if unavailable. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_defaults` | A tuple containing default | Writable | + | | argument values for those | | + | | arguments that have defaults, | | + | | or ``None`` if no arguments | | + | | have a default value | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_code` | The code object representing | Writable | + | | the compiled function body. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_globals` | A reference to the dictionary | Read-only | + | | that holds the function's | | + | | global variables --- the | | + | | global namespace of the | | + | | module in which the function | | + | | was defined. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_dict` | The namespace supporting | Writable | + | | arbitrary function | | + | | attributes. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only | + | | that contain bindings for the | | + | | function's free variables. | | + +-----------------------+-------------------------------+-----------+ + + Most of the attributes labelled "Writable" check the type of the assigned value. + + .. versionchanged:: 2.4 + ``func_name`` is now writable. + + Function objects also support getting and setting arbitrary attributes, which + can be used, for example, to attach metadata to functions. Regular attribute + dot-notation is used to get and set such attributes. *Note that the current + implementation only supports function attributes on user-defined functions. + Function attributes on built-in functions may be supported in the future.* + + Additional information about a function's definition can be retrieved from its + code object; see the description of internal types below. + + .. index:: + single: func_doc (function attribute) + single: __doc__ (function attribute) + single: __name__ (function attribute) + single: __module__ (function attribute) + single: __dict__ (function attribute) + single: func_defaults (function attribute) + single: func_closure (function attribute) + single: func_code (function attribute) + single: func_globals (function attribute) + single: func_dict (function attribute) + pair: global; namespace + + User-defined methods + .. index:: + object: method + object: user-defined method + pair: user-defined; method + + A user-defined method object combines a class, a class instance (or ``None``) + and any callable object (normally a user-defined function). + + Special read-only attributes: :attr:`im_self` is the class instance object, + :attr:`im_func` is the function object; :attr:`im_class` is the class of + :attr:`im_self` for bound methods or the class that asked for the method for + unbound methods; :attr:`__doc__` is the method's documentation (same as + ``im_func.__doc__``); :attr:`__name__` is the method name (same as + ``im_func.__name__``); :attr:`__module__` is the name of the module the method + was defined in, or ``None`` if unavailable. + + .. versionchanged:: 2.2 + :attr:`im_self` used to refer to the class that defined the method. + + .. index:: + single: __doc__ (method attribute) + single: __name__ (method attribute) + single: __module__ (method attribute) + single: im_func (method attribute) + single: im_self (method attribute) + + Methods also support accessing (but not setting) the arbitrary function + attributes on the underlying function object. + + User-defined method objects may be created when getting an attribute of a class + (perhaps via an instance of that class), if that attribute is a user-defined + function object, an unbound user-defined method object, or a class method + object. When the attribute is a user-defined method object, a new method object + is only created if the class from which it is being retrieved is the same as, or + a derived class of, the class stored in the original method object; otherwise, + the original method object is used as it is. + + .. index:: + single: im_class (method attribute) + single: im_func (method attribute) + single: im_self (method attribute) + + When a user-defined method object is created by retrieving a user-defined + function object from a class, its :attr:`im_self` attribute is ``None`` + and the method object is said to be unbound. When one is created by + retrieving a user-defined function object from a class via one of its + instances, its :attr:`im_self` attribute is the instance, and the method + object is said to be bound. In either case, the new method's + :attr:`im_class` attribute is the class from which the retrieval takes + place, and its :attr:`im_func` attribute is the original function object. + + .. index:: single: im_func (method attribute) + + When a user-defined method object is created by retrieving another method object + from a class or instance, the behaviour is the same as for a function object, + except that the :attr:`im_func` attribute of the new instance is not the + original method object but its :attr:`im_func` attribute. + + .. index:: + single: im_class (method attribute) + single: im_func (method attribute) + single: im_self (method attribute) + + When a user-defined method object is created by retrieving a class method object + from a class or instance, its :attr:`im_self` attribute is the class itself (the + same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is + the function object underlying the class method. + + When an unbound user-defined method object is called, the underlying function + (:attr:`im_func`) is called, with the restriction that the first argument must + be an instance of the proper class (:attr:`im_class`) or of a derived class + thereof. + + When a bound user-defined method object is called, the underlying function + (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in + front of the argument list. For instance, when :class:`C` is a class which + contains a definition for a function :meth:`f`, and ``x`` is an instance of + :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``. + + When a user-defined method object is derived from a class method object, the + "class instance" stored in :attr:`im_self` will actually be the class itself, so + that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)`` + where ``f`` is the underlying function. + + Note that the transformation from function object to (unbound or bound) method + object happens each time the attribute is retrieved from the class or instance. + In some cases, a fruitful optimization is to assign the attribute to a local + variable and call that local variable. Also notice that this transformation only + happens for user-defined functions; other callable objects (and all non-callable + objects) are retrieved without transformation. It is also important to note + that user-defined functions which are attributes of a class instance are not + converted to bound methods; this *only* happens when the function is an + attribute of the class. + + Generator functions + .. index:: + single: generator; function + single: generator; iterator + + A function or method which uses the :keyword:`yield` statement (see section + :ref:`yield`) is called a :dfn:`generator + function`. Such a function, when called, always returns an iterator object + which can be used to execute the body of the function: calling the iterator's + :meth:`next` method will cause the function to execute until it provides a value + using the :keyword:`yield` statement. When the function executes a + :keyword:`return` statement or falls off the end, a :exc:`StopIteration` + exception is raised and the iterator will have reached the end of the set of + values to be returned. + + Built-in functions + .. index:: + object: built-in function + object: function + pair: C; language + + A built-in function object is a wrapper around a C function. Examples of + built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a + standard built-in module). The number and type of the arguments are + determined by the C function. Special read-only attributes: + :attr:`__doc__` is the function's documentation string, or ``None`` if + unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is + set to ``None`` (but see the next item); :attr:`__module__` is the name of + the module the function was defined in or ``None`` if unavailable. + + Built-in methods + .. index:: + object: built-in method + object: method + pair: built-in; method + + This is really a different disguise of a built-in function, this time containing + an object passed to the C function as an implicit extra argument. An example of + a built-in method is ``alist.append()``, assuming *alist* is a list object. In + this case, the special read-only attribute :attr:`__self__` is set to the object + denoted by *list*. + + Class Types + Class types, or "new-style classes," are callable. These objects normally act + as factories for new instances of themselves, but variations are possible for + class types that override :meth:`__new__`. The arguments of the call are passed + to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize + the new instance. + + Classic Classes + .. index:: + single: __init__() (object method) + object: class + object: class instance + object: instance + pair: class object; call + + Class objects are described below. When a class object is called, a new class + instance (also described below) is created and returned. This implies a call to + the class's :meth:`__init__` method if it has one. Any arguments are passed on + to the :meth:`__init__` method. If there is no :meth:`__init__` method, the + class must be called without arguments. + + Class instances + Class instances are described below. Class instances are callable only when the + class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for + ``x.__call__(arguments)``. + +Modules + .. index:: + statement: import + object: module + + Modules are imported by the :keyword:`import` statement (see section + :ref:`import`). A module object has a + namespace implemented by a dictionary object (this is the dictionary referenced + by the func_globals attribute of functions defined in the module). Attribute + references are translated to lookups in this dictionary, e.g., ``m.x`` is + equivalent to ``m.__dict__["x"]``. A module object does not contain the code + object used to initialize the module (since it isn't needed once the + initialization is done). + + .. % + + Attribute assignment updates the module's namespace dictionary, e.g., ``m.x = + 1`` is equivalent to ``m.__dict__["x"] = 1``. + + .. index:: single: __dict__ (module attribute) + + Special read-only attribute: :attr:`__dict__` is the module's namespace as a + dictionary object. + + .. index:: + single: __name__ (module attribute) + single: __doc__ (module attribute) + single: __file__ (module attribute) + pair: module; namespace + + Predefined (writable) attributes: :attr:`__name__` is the module's name; + :attr:`__doc__` is the module's documentation string, or ``None`` if + unavailable; :attr:`__file__` is the pathname of the file from which the module + was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not + present for C modules that are statically linked into the interpreter; for + extension modules loaded dynamically from a shared library, it is the pathname + of the shared library file. + +Classes + Class objects are created by class definitions (see section :ref:`class`). A + class has a namespace implemented by a dictionary object. Class attribute + references are translated to lookups in this dictionary, e.g., ``C.x`` is + translated to ``C.__dict__["x"]``. When the attribute name is not found + there, the attribute search continues in the base classes. The search is + depth-first, left-to-right in the order of occurrence in the base class list. + + .. index:: + object: class + object: class instance + object: instance + pair: class object; call + single: container + object: dictionary + pair: class; attribute + + When a class attribute reference (for class :class:`C`, say) would yield a + user-defined function object or an unbound user-defined method object whose + associated class is either :class:`C` or one of its base classes, it is + transformed into an unbound user-defined method object whose :attr:`im_class` + attribute is :class:`C`. When it would yield a class method object, it is + transformed into a bound user-defined method object whose :attr:`im_class` + and :attr:`im_self` attributes are both :class:`C`. When it would yield a + static method object, it is transformed into the object wrapped by the static + method object. See section :ref:`descriptors` for another way in which + attributes retrieved from a class may differ from those actually contained in + its :attr:`__dict__`. + + .. index:: triple: class; attribute; assignment + + Class attribute assignments update the class's dictionary, never the dictionary + of a base class. + + .. index:: pair: class object; call + + A class object can be called (see above) to yield a class instance (see below). + + .. index:: + single: __name__ (class attribute) + single: __module__ (class attribute) + single: __dict__ (class attribute) + single: __bases__ (class attribute) + single: __doc__ (class attribute) + + Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is + the module name in which the class was defined; :attr:`__dict__` is the + dictionary containing the class's namespace; :attr:`__bases__` is a tuple + (possibly empty or a singleton) containing the base classes, in the order of + their occurrence in the base class list; :attr:`__doc__` is the class's + documentation string, or None if undefined. + +Class instances + .. index:: + object: class instance + object: instance + pair: class; instance + pair: class instance; attribute + + A class instance is created by calling a class object (see above). A class + instance has a namespace implemented as a dictionary which is the first place in + which attribute references are searched. When an attribute is not found there, + and the instance's class has an attribute by that name, the search continues + with the class attributes. If a class attribute is found that is a user-defined + function object or an unbound user-defined method object whose associated class + is the class (call it :class:`C`) of the instance for which the attribute + reference was initiated or one of its bases, it is transformed into a bound + user-defined method object whose :attr:`im_class` attribute is :class:`C` and + whose :attr:`im_self` attribute is the instance. Static method and class method + objects are also transformed, as if they had been retrieved from class + :class:`C`; see above under "Classes". See section :ref:`descriptors` for + another way in which attributes of a class retrieved via its instances may + differ from the objects actually stored in the class's :attr:`__dict__`. If no + class attribute is found, and the object's class has a :meth:`__getattr__` + method, that is called to satisfy the lookup. + + .. index:: triple: class instance; attribute; assignment + + Attribute assignments and deletions update the instance's dictionary, never a + class's dictionary. If the class has a :meth:`__setattr__` or + :meth:`__delattr__` method, this is called instead of updating the instance + dictionary directly. + + .. index:: + object: numeric + object: sequence + object: mapping + + Class instances can pretend to be numbers, sequences, or mappings if they have + methods with certain special names. See section :ref:`specialnames`. + + .. index:: + single: __dict__ (instance attribute) + single: __class__ (instance attribute) + + Special attributes: :attr:`__dict__` is the attribute dictionary; + :attr:`__class__` is the instance's class. + +Files + .. index:: + object: file + builtin: open + single: popen() (in module os) + single: makefile() (socket method) + single: sys.stdin + single: sys.stdout + single: sys.stderr + single: stdio + single: stdin (in module sys) + single: stdout (in module sys) + single: stderr (in module sys) + + A file object represents an open file. File objects are created by the + :func:`open` built-in function, and also by :func:`os.popen`, + :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and + perhaps by other functions or methods provided by extension modules). The + objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to + file objects corresponding to the interpreter's standard input, output and + error streams. See :ref:`bltin-file-objects` for complete documentation of + file objects. + +Internal types + .. index:: + single: internal type + single: types, internal + + A few types used internally by the interpreter are exposed to the user. Their + definitions may change with future versions of the interpreter, but they are + mentioned here for completeness. + + Code objects + .. index:: + single: bytecode + object: code + + Code objects represent *byte-compiled* executable Python code, or *bytecode*. + The difference between a code object and a function object is that the function + object contains an explicit reference to the function's globals (the module in + which it was defined), while a code object contains no context; also the default + argument values are stored in the function object, not in the code object + (because they represent values calculated at run-time). Unlike function + objects, code objects are immutable and contain no references (directly or + indirectly) to mutable objects. + + Special read-only attributes: :attr:`co_name` gives the function name; + :attr:`co_argcount` is the number of positional arguments (including arguments + with default values); :attr:`co_nlocals` is the number of local variables used + by the function (including arguments); :attr:`co_varnames` is a tuple containing + the names of the local variables (starting with the argument names); + :attr:`co_cellvars` is a tuple containing the names of local variables that are + referenced by nested functions; :attr:`co_freevars` is a tuple containing the + names of free variables; :attr:`co_code` is a string representing the sequence + of bytecode instructions; :attr:`co_consts` is a tuple containing the literals + used by the bytecode; :attr:`co_names` is a tuple containing the names used by + the bytecode; :attr:`co_filename` is the filename from which the code was + compiled; :attr:`co_firstlineno` is the first line number of the function; + :attr:`co_lnotab` is a string encoding the mapping from byte code offsets to + line numbers (for details see the source code of the interpreter); + :attr:`co_stacksize` is the required stack size (including local variables); + :attr:`co_flags` is an integer encoding a number of flags for the interpreter. + + .. index:: + single: co_argcount (code object attribute) + single: co_code (code object attribute) + single: co_consts (code object attribute) + single: co_filename (code object attribute) + single: co_firstlineno (code object attribute) + single: co_flags (code object attribute) + single: co_lnotab (code object attribute) + single: co_name (code object attribute) + single: co_names (code object attribute) + single: co_nlocals (code object attribute) + single: co_stacksize (code object attribute) + single: co_varnames (code object attribute) + single: co_cellvars (code object attribute) + single: co_freevars (code object attribute) + + .. index:: object: generator + + The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if + the function uses the ``*arguments`` syntax to accept an arbitrary number of + positional arguments; bit ``0x08`` is set if the function uses the + ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set + if the function is a generator. + + Future feature declarations (``from __future__ import division``) also use bits + in :attr:`co_flags` to indicate whether a code object was compiled with a + particular feature enabled: bit ``0x2000`` is set if the function was compiled + with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier + versions of Python. + + Other bits in :attr:`co_flags` are reserved for internal use. + + .. index:: single: documentation string + + If a code object represents a function, the first item in :attr:`co_consts` is + the documentation string of the function, or ``None`` if undefined. + + Frame objects + .. index:: object: frame + + Frame objects represent execution frames. They may occur in traceback objects + (see below). + + .. index:: + single: f_back (frame attribute) + single: f_code (frame attribute) + single: f_globals (frame attribute) + single: f_locals (frame attribute) + single: f_lasti (frame attribute) + single: f_builtins (frame attribute) + single: f_restricted (frame attribute) + + Special read-only attributes: :attr:`f_back` is to the previous stack frame + (towards the caller), or ``None`` if this is the bottom stack frame; + :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals` + is the dictionary used to look up local variables; :attr:`f_globals` is used for + global variables; :attr:`f_builtins` is used for built-in (intrinsic) names; + :attr:`f_restricted` is a flag indicating whether the function is executing in + restricted execution mode; :attr:`f_lasti` gives the precise instruction (this + is an index into the bytecode string of the code object). + + .. index:: + single: f_trace (frame attribute) + single: f_exc_type (frame attribute) + single: f_exc_value (frame attribute) + single: f_exc_traceback (frame attribute) + single: f_lineno (frame attribute) + + Special writable attributes: :attr:`f_trace`, if not ``None``, is a function + called at the start of each source code line (this is used by the debugger); + :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the + last exception raised in the parent frame provided another exception was ever + raised in the current frame (in all other cases they are None); :attr:`f_lineno` + is the current line number of the frame --- writing to this from within a trace + function jumps to the given line (only for the bottom-most frame). A debugger + can implement a Jump command (aka Set Next Statement) by writing to f_lineno. + + Traceback objects + .. index:: + object: traceback + pair: stack; trace + pair: exception; handler + pair: execution; stack + single: exc_info (in module sys) + single: exc_traceback (in module sys) + single: last_traceback (in module sys) + single: sys.exc_info + single: sys.exc_traceback + single: sys.last_traceback + + Traceback objects represent a stack trace of an exception. A traceback object + is created when an exception occurs. When the search for an exception handler + unwinds the execution stack, at each unwound level a traceback object is + inserted in front of the current traceback. When an exception handler is + entered, the stack trace is made available to the program. (See section + :ref:`try`.) It is accessible as ``sys.exc_traceback``, + and also as the third item of the tuple returned by ``sys.exc_info()``. The + latter is the preferred interface, since it works correctly when the program is + using multiple threads. When the program contains no suitable handler, the stack + trace is written (nicely formatted) to the standard error stream; if the + interpreter is interactive, it is also made available to the user as + ``sys.last_traceback``. + + .. index:: + single: tb_next (traceback attribute) + single: tb_frame (traceback attribute) + single: tb_lineno (traceback attribute) + single: tb_lasti (traceback attribute) + statement: try + + Special read-only attributes: :attr:`tb_next` is the next level in the stack + trace (towards the frame where the exception occurred), or ``None`` if there is + no next level; :attr:`tb_frame` points to the execution frame of the current + level; :attr:`tb_lineno` gives the line number where the exception occurred; + :attr:`tb_lasti` indicates the precise instruction. The line number and last + instruction in the traceback may differ from the line number of its frame object + if the exception occurred in a :keyword:`try` statement with no matching except + clause or with a finally clause. + + Slice objects + .. index:: builtin: slice + + Slice objects are used to represent slices when *extended slice syntax* is used. + This is a slice using two colons, or multiple slices or ellipses separated by + commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are + also created by the built-in :func:`slice` function. + + .. index:: + single: start (slice object attribute) + single: stop (slice object attribute) + single: step (slice object attribute) + + Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is + the upper bound; :attr:`step` is the step value; each is ``None`` if omitted. + These attributes can have any type. + + Slice objects support one method: + + + .. method:: slice.indices(self, length) + + This method takes a single integer argument *length* and computes information + about the extended slice that the slice object would describe if applied to a + sequence of *length* items. It returns a tuple of three integers; respectively + these are the *start* and *stop* indices and the *step* or stride length of the + slice. Missing or out-of-bounds indices are handled in a manner consistent with + regular slices. + + .. versionadded:: 2.3 + + Static method objects + Static method objects provide a way of defeating the transformation of function + objects to method objects described above. A static method object is a wrapper + around any other object, usually a user-defined method object. When a static + method object is retrieved from a class or a class instance, the object actually + returned is the wrapped object, which is not subject to any further + transformation. Static method objects are not themselves callable, although the + objects they wrap usually are. Static method objects are created by the built-in + :func:`staticmethod` constructor. + + Class method objects + A class method object, like a static method object, is a wrapper around another + object that alters the way in which that object is retrieved from classes and + class instances. The behaviour of class method objects upon such retrieval is + described above, under "User-defined methods". Class method objects are created + by the built-in :func:`classmethod` constructor. + + .. % Internal types + +.. % Types +.. % ========================================================================= + + +New-style and classic classes +============================= + +Classes and instances come in two flavors: old-style or classic, and new-style. + +Up to Python 2.1, old-style classes were the only flavour available to the user. +The concept of (old-style) class is unrelated to the concept of type: if *x* is +an instance of an old-style class, then ``x.__class__`` designates the class of +*x*, but ``type(x)`` is always ``<type 'instance'>``. This reflects the fact +that all old-style instances, independently of their class, are implemented with +a single built-in type, called ``instance``. + +New-style classes were introduced in Python 2.2 to unify classes and types. A +new-style class neither more nor less than a user-defined type. If *x* is an +instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``. + +The major motivation for introducing new-style classes is to provide a unified +object model with a full meta-model. It also has a number of immediate +benefits, like the ability to subclass most built-in types, or the introduction +of "descriptors", which enable computed properties. + +For compatibility reasons, classes are still old-style by default. New-style +classes are created by specifying another new-style class (i.e. a type) as a +parent class, or the "top-level type" :class:`object` if no other parent is +needed. The behaviour of new-style classes differs from that of old-style +classes in a number of important details in addition to what :func:`type` +returns. Some of these changes are fundamental to the new object model, like +the way special methods are invoked. Others are "fixes" that could not be +implemented before for compatibility concerns, like the method resolution order +in case of multiple inheritance. + +This manual is not up-to-date with respect to new-style classes. For now, +please see http://www.python.org/doc/newstyle.html for more information. + +.. index:: + single: class + single: class + single: class + +The plan is to eventually drop old-style classes, leaving only the semantics of +new-style classes. This change will probably only be feasible in Python 3.0. +new-style classic old-style + +.. % ========================================================================= + + +.. _specialnames: + +Special method names +==================== + +.. index:: + pair: operator; overloading + single: __getitem__() (mapping object method) + +A class can implement certain operations that are invoked by special syntax +(such as arithmetic operations or subscripting and slicing) by defining methods +with special names. This is Python's approach to :dfn:`operator overloading`, +allowing classes to define their own behavior with respect to language +operators. For instance, if a class defines a method named :meth:`__getitem__`, +and ``x`` is an instance of this class, then ``x[i]`` is equivalent [#]_ to +``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation +raise an exception when no appropriate method is defined. + +When implementing a class that emulates any built-in type, it is important that +the emulation only be implemented to the degree that it makes sense for the +object being modelled. For example, some sequences may work well with retrieval +of individual elements, but extracting a slice may not make sense. (One example +of this is the :class:`NodeList` interface in the W3C's Document Object Model.) + + +.. _customization: + +Basic customization +------------------- + + +.. method:: object.__new__(cls[, ...]) + + Called to create a new instance of class *cls*. :meth:`__new__` is a static + method (special-cased so you need not declare it as such) that takes the class + of which an instance was requested as its first argument. The remaining + arguments are those passed to the object constructor expression (the call to the + class). The return value of :meth:`__new__` should be the new object instance + (usually an instance of *cls*). + + Typical implementations create a new instance of the class by invoking the + superclass's :meth:`__new__` method using ``super(currentclass, + cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the + newly-created instance as necessary before returning it. + + If :meth:`__new__` returns an instance of *cls*, then the new instance's + :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where + *self* is the new instance and the remaining arguments are the same as were + passed to :meth:`__new__`. + + If :meth:`__new__` does not return an instance of *cls*, then the new instance's + :meth:`__init__` method will not be invoked. + + :meth:`__new__` is intended mainly to allow subclasses of immutable types (like + int, str, or tuple) to customize instance creation. + + +.. method:: object.__init__(self[, ...]) + + .. index:: pair: class; constructor + + Called when the instance is created. The arguments are those passed to the + class constructor expression. If a base class has an :meth:`__init__` method, + the derived class's :meth:`__init__` method, if any, must explicitly call it to + ensure proper initialization of the base class part of the instance; for + example: ``BaseClass.__init__(self, [args...])``. As a special constraint on + constructors, no value may be returned; doing so will cause a :exc:`TypeError` + to be raised at runtime. + + +.. method:: object.__del__(self) + + .. index:: + single: destructor + statement: del + + Called when the instance is about to be destroyed. This is also called a + destructor. If a base class has a :meth:`__del__` method, the derived class's + :meth:`__del__` method, if any, must explicitly call it to ensure proper + deletion of the base class part of the instance. Note that it is possible + (though not recommended!) for the :meth:`__del__` method to postpone destruction + of the instance by creating a new reference to it. It may then be called at a + later time when this new reference is deleted. It is not guaranteed that + :meth:`__del__` methods are called for objects that still exist when the + interpreter exits. + + .. note:: + + ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements + the reference count for ``x`` by one, and the latter is only called when + ``x``'s reference count reaches zero. Some common situations that may + prevent the reference count of an object from going to zero include: + circular references between objects (e.g., a doubly-linked list or a tree + data structure with parent and child pointers); a reference to the object + on the stack frame of a function that caught an exception (the traceback + stored in ``sys.exc_traceback`` keeps the stack frame alive); or a + reference to the object on the stack frame that raised an unhandled + exception in interactive mode (the traceback stored in + ``sys.last_traceback`` keeps the stack frame alive). The first situation + can only be remedied by explicitly breaking the cycles; the latter two + situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or + ``sys.last_traceback``. Circular references which are garbage are + detected when the option cycle detector is enabled (it's on by default), + but can only be cleaned up if there are no Python-level :meth:`__del__` + methods involved. Refer to the documentation for the :mod:`gc` module for + more information about how :meth:`__del__` methods are handled by the + cycle detector, particularly the description of the ``garbage`` value. + + .. warning:: + + Due to the precarious circumstances under which :meth:`__del__` methods are + invoked, exceptions that occur during their execution are ignored, and a warning + is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in + response to a module being deleted (e.g., when execution of the program is + done), other globals referenced by the :meth:`__del__` method may already have + been deleted. For this reason, :meth:`__del__` methods should do the absolute + minimum needed to maintain external invariants. Starting with version 1.5, + Python guarantees that globals whose name begins with a single underscore are + deleted from their module before other globals are deleted; if no other + references to such globals exist, this may help in assuring that imported + modules are still available at the time when the :meth:`__del__` method is + called. + + +.. method:: object.__repr__(self) + + .. index:: builtin: repr + + Called by the :func:`repr` built-in function and by string conversions (reverse + quotes) to compute the "official" string representation of an object. If at all + possible, this should look like a valid Python expression that could be used to + recreate an object with the same value (given an appropriate environment). If + this is not possible, a string of the form ``<...some useful description...>`` + should be returned. The return value must be a string object. If a class + defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also + used when an "informal" string representation of instances of that class is + required. + + .. index:: + pair: string; conversion + pair: reverse; quotes + pair: backward; quotes + single: back-quotes + + This is typically used for debugging, so it is important that the representation + is information-rich and unambiguous. + + +.. method:: object.__str__(self) + + .. index:: + builtin: str + statement: print + + Called by the :func:`str` built-in function and by the :keyword:`print` + statement to compute the "informal" string representation of an object. This + differs from :meth:`__repr__` in that it does not have to be a valid Python + expression: a more convenient or concise representation may be used instead. + The return value must be a string object. + + +.. method:: object.__lt__(self, other) + object.__le__(self, other) + object.__eq__(self, other) + object.__ne__(self, other) + object.__gt__(self, other) + object.__ge__(self, other) + + .. versionadded:: 2.1 + + These are the so-called "rich comparison" methods, and are called for comparison + operators in preference to :meth:`__cmp__` below. The correspondence between + operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``, + ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` and + ``x<>y`` call ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls + ``x.__ge__(y)``. + + A rich comparison method may return the singleton ``NotImplemented`` if it does + not implement the operation for a given pair of arguments. By convention, + ``False`` and ``True`` are returned for a successful comparison. However, these + methods can return any value, so if the comparison operator is used in a Boolean + context (e.g., in the condition of an ``if`` statement), Python will call + :func:`bool` on the value to determine if the result is true or false. + + There are no implied relationships among the comparison operators. The truth of + ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when defining + :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will + behave as expected. + + There are no reflected (swapped-argument) versions of these methods (to be used + when the left argument does not support the operation but the right argument + does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection, + :meth:`__le__` and :meth:`__ge__` are each other's reflection, and + :meth:`__eq__` and :meth:`__ne__` are their own reflection. + + Arguments to rich comparison methods are never coerced. + + +.. method:: object.__cmp__(self, other) + + .. index:: + builtin: cmp + single: comparisons + + Called by comparison operations if rich comparison (see above) is not defined. + Should return a negative integer if ``self < other``, zero if ``self == other``, + a positive integer if ``self > other``. If no :meth:`__cmp__`, :meth:`__eq__` + or :meth:`__ne__` operation is defined, class instances are compared by object + identity ("address"). See also the description of :meth:`__hash__` for some + important notes on creating objects which support custom comparison operations + and are usable as dictionary keys. (Note: the restriction that exceptions are + not propagated by :meth:`__cmp__` has been removed since Python 1.5.) + + +.. method:: object.__rcmp__(self, other) + + .. versionchanged:: 2.1 + No longer supported. + + +.. method:: object.__hash__(self) + + .. index:: + object: dictionary + builtin: hash + + Called for the key object for dictionary operations, and by the built-in + function :func:`hash`. Should return a 32-bit integer usable as a hash value + for dictionary operations. The only required property is that objects which + compare equal have the same hash value; it is advised to somehow mix together + (e.g., using exclusive or) the hash values for the components of the object that + also play a part in comparison of objects. If a class does not define a + :meth:`__cmp__` method it should not define a :meth:`__hash__` operation either; + if it defines :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its + instances will not be usable as dictionary keys. If a class defines mutable + objects and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not + implement :meth:`__hash__`, since the dictionary implementation requires that a + key's hash value is immutable (if the object's hash value changes, it will be in + the wrong hash bucket). + + .. versionchanged:: 2.5 + :meth:`__hash__` may now also return a long integer object; the 32-bit integer + is then derived from the hash of that object. + + .. index:: single: __cmp__() (object method) + + +.. method:: object.__nonzero__(self) + + .. index:: single: __len__() (mapping object method) + + Called to implement truth value testing, and the built-in operation ``bool()``; + should return ``False`` or ``True``, or their integer equivalents ``0`` or + ``1``. When this method is not defined, :meth:`__len__` is called, if it is + defined (see below). If a class defines neither :meth:`__len__` nor + :meth:`__nonzero__`, all its instances are considered true. + + +.. method:: object.__unicode__(self) + + .. index:: builtin: unicode + + Called to implement :func:`unicode` builtin; should return a Unicode object. + When this method is not defined, string conversion is attempted, and the result + of string conversion is converted to Unicode using the system default encoding. + + +.. _attribute-access: + +Customizing attribute access +---------------------------- + +The following methods can be defined to customize the meaning of attribute +access (use of, assignment to, or deletion of ``x.name``) for class instances. + + +.. method:: object.__getattr__(self, name) + + Called when an attribute lookup has not found the attribute in the usual places + (i.e. it is not an instance attribute nor is it found in the class tree for + ``self``). ``name`` is the attribute name. This method should return the + (computed) attribute value or raise an :exc:`AttributeError` exception. + + .. index:: single: __setattr__() (object method) + + Note that if the attribute is found through the normal mechanism, + :meth:`__getattr__` is not called. (This is an intentional asymmetry between + :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency + reasons and because otherwise :meth:`__setattr__` would have no way to access + other attributes of the instance. Note that at least for instance variables, + you can fake total control by not inserting any values in the instance attribute + dictionary (but instead inserting them in another object). See the + :meth:`__getattribute__` method below for a way to actually get total control in + new-style classes. + + +.. method:: object.__setattr__(self, name, value) + + Called when an attribute assignment is attempted. This is called instead of the + normal mechanism (i.e. store the value in the instance dictionary). *name* is + the attribute name, *value* is the value to be assigned to it. + + .. index:: single: __dict__ (instance attribute) + + If :meth:`__setattr__` wants to assign to an instance attribute, it should not + simply execute ``self.name = value`` --- this would cause a recursive call to + itself. Instead, it should insert the value in the dictionary of instance + attributes, e.g., ``self.__dict__[name] = value``. For new-style classes, + rather than accessing the instance dictionary, it should call the base class + method with the same name, for example, ``object.__setattr__(self, name, + value)``. + + +.. method:: object.__delattr__(self, name) + + Like :meth:`__setattr__` but for attribute deletion instead of assignment. This + should only be implemented if ``del obj.name`` is meaningful for the object. + + +.. _new-style-attribute-access: + +More attribute access for new-style classes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following methods only apply to new-style classes. + + +.. method:: object.__getattribute__(self, name) + + Called unconditionally to implement attribute accesses for instances of the + class. If the class also defines :meth:`__getattr__`, the latter will not be + called unless :meth:`__getattribute__` either calls it explicitly or raises an + :exc:`AttributeError`. This method should return the (computed) attribute value + or raise an :exc:`AttributeError` exception. In order to avoid infinite + recursion in this method, its implementation should always call the base class + method with the same name to access any attributes it needs, for example, + ``object.__getattribute__(self, name)``. + + +.. _descriptors: + +Implementing Descriptors +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following methods only apply when an instance of the class containing the +method (a so-called *descriptor* class) appears in the class dictionary of +another new-style class, known as the *owner* class. In the examples below, "the +attribute" refers to the attribute whose name is the key of the property in the +owner class' ``__dict__``. Descriptors can only be implemented as new-style +classes themselves. + + +.. method:: object.__get__(self, instance, owner) + + Called to get the attribute of the owner class (class attribute access) or of an + instance of that class (instance attribute access). *owner* is always the owner + class, while *instance* is the instance that the attribute was accessed through, + or ``None`` when the attribute is accessed through the *owner*. This method + should return the (computed) attribute value or raise an :exc:`AttributeError` + exception. + + +.. method:: object.__set__(self, instance, value) + + Called to set the attribute on an instance *instance* of the owner class to a + new value, *value*. + + +.. method:: object.__delete__(self, instance) + + Called to delete the attribute on an instance *instance* of the owner class. + + +.. _descriptor-invocation: + +Invoking Descriptors +^^^^^^^^^^^^^^^^^^^^ + +In general, a descriptor is an object attribute with "binding behavior", one +whose attribute access has been overridden by methods in the descriptor +protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of +those methods are defined for an object, it is said to be a descriptor. + +The default behavior for attribute access is to get, set, or delete the +attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain +starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and +continuing through the base classes of ``type(a)`` excluding metaclasses. + +However, if the looked-up value is an object defining one of the descriptor +methods, then Python may override the default behavior and invoke the descriptor +method instead. Where this occurs in the precedence chain depends on which +descriptor methods were defined and how they were called. Note that descriptors +are only invoked for new style objects or classes (ones that subclass +:class:`object()` or :class:`type()`). + +The starting point for descriptor invocation is a binding, ``a.x``. How the +arguments are assembled depends on ``a``: + +Direct Call + The simplest and least common call is when user code directly invokes a + descriptor method: ``x.__get__(a)``. + +Instance Binding + If binding to a new-style object instance, ``a.x`` is transformed into the call: + ``type(a).__dict__['x'].__get__(a, type(a))``. + +Class Binding + If binding to a new-style class, ``A.x`` is transformed into the call: + ``A.__dict__['x'].__get__(None, A)``. + +Super Binding + If ``a`` is an instance of :class:`super`, then the binding ``super(B, + obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` + immediately preceding ``B`` and then invokes the descriptor with the call: + ``A.__dict__['m'].__get__(obj, A)``. + +For instance bindings, the precedence of descriptor invocation depends on the +which descriptor methods are defined. Data descriptors define both +:meth:`__get__` and :meth:`__set__`. Non-data descriptors have just the +:meth:`__get__` method. Data descriptors always override a redefinition in an +instance dictionary. In contrast, non-data descriptors can be overridden by +instances. + +Python methods (including :func:`staticmethod` and :func:`classmethod`) are +implemented as non-data descriptors. Accordingly, instances can redefine and +override methods. This allows individual instances to acquire behaviors that +differ from other instances of the same class. + +The :func:`property` function is implemented as a data descriptor. Accordingly, +instances cannot override the behavior of a property. + + +.. _slots: + +__slots__ +^^^^^^^^^ + +By default, instances of both old and new-style classes have a dictionary for +attribute storage. This wastes space for objects having very few instance +variables. The space consumption can become acute when creating large numbers +of instances. + +The default can be overridden by defining *__slots__* in a new-style class +definition. The *__slots__* declaration takes a sequence of instance variables +and reserves just enough space in each instance to hold a value for each +variable. Space is saved because *__dict__* is not created for each instance. + + +.. data:: __slots__ + + This class variable can be assigned a string, iterable, or sequence of strings + with variable names used by instances. If defined in a new-style class, + *__slots__* reserves space for the declared variables and prevents the automatic + creation of *__dict__* and *__weakref__* for each instance. + + .. versionadded:: 2.2 + +Notes on using *__slots__* + +* Without a *__dict__* variable, instances cannot be assigned new variables not + listed in the *__slots__* definition. Attempts to assign to an unlisted + variable name raises :exc:`AttributeError`. If dynamic assignment of new + variables is desired, then add ``'__dict__'`` to the sequence of strings in the + *__slots__* declaration. + + .. versionchanged:: 2.3 + Previously, adding ``'__dict__'`` to the *__slots__* declaration would not + enable the assignment of new attributes not specifically listed in the sequence + of instance variable names. + +* Without a *__weakref__* variable for each instance, classes defining + *__slots__* do not support weak references to its instances. If weak reference + support is needed, then add ``'__weakref__'`` to the sequence of strings in the + *__slots__* declaration. + + .. versionchanged:: 2.3 + Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not + enable support for weak references. + +* *__slots__* are implemented at the class level by creating descriptors + (:ref:`descriptors`) for each variable name. As a result, class attributes + cannot be used to set default values for instance variables defined by + *__slots__*; otherwise, the class attribute would overwrite the descriptor + assignment. + +* If a class defines a slot also defined in a base class, the instance variable + defined by the base class slot is inaccessible (except by retrieving its + descriptor directly from the base class). This renders the meaning of the + program undefined. In the future, a check may be added to prevent this. + +* The action of a *__slots__* declaration is limited to the class where it is + defined. As a result, subclasses will have a *__dict__* unless they also define + *__slots__*. + +* *__slots__* do not work for classes derived from "variable-length" built-in + types such as :class:`long`, :class:`str` and :class:`tuple`. + +* Any non-string iterable may be assigned to *__slots__*. Mappings may also be + used; however, in the future, special meaning may be assigned to the values + corresponding to each key. + +* *__class__* assignment works only if both classes have the same *__slots__*. + + .. versionchanged:: 2.6 + Previously, *__class__* assignment raised an error if either new or old class + had *__slots__*. + + +.. _metaclasses: + +Customizing class creation +-------------------------- + +By default, new-style classes are constructed using :func:`type`. A class +definition is read into a separate namespace and the value of class name is +bound to the result of ``type(name, bases, dict)``. + +When the class definition is read, if *__metaclass__* is defined then the +callable assigned to it will be called instead of :func:`type`. The allows +classes or functions to be written which monitor or alter the class creation +process: + +* Modifying the class dictionary prior to the class being created. + +* Returning an instance of another class -- essentially performing the role of a + factory function. + + +.. data:: __metaclass__ + + This variable can be any callable accepting arguments for ``name``, ``bases``, + and ``dict``. Upon class creation, the callable is used instead of the built-in + :func:`type`. + + .. versionadded:: 2.2 + +The appropriate metaclass is determined by the following precedence rules: + +* If ``dict['__metaclass__']`` exists, it is used. + +* Otherwise, if there is at least one base class, its metaclass is used (this + looks for a *__class__* attribute first and if not found, uses its type). + +* Otherwise, if a global variable named __metaclass__ exists, it is used. + +* Otherwise, the old-style, classic metaclass (types.ClassType) is used. + +The potential uses for metaclasses are boundless. Some ideas that have been +explored including logging, interface checking, automatic delegation, automatic +property creation, proxies, frameworks, and automatic resource +locking/synchronization. + + +.. _callable-types: + +Emulating callable objects +-------------------------- + + +.. method:: object.__call__(self[, args...]) + + .. index:: pair: call; instance + + Called when the instance is "called" as a function; if this method is defined, + ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``. + + +.. _sequence-types: + +Emulating container types +------------------------- + +The following methods can be defined to implement container objects. Containers +usually are sequences (such as lists or tuples) or mappings (like dictionaries), +but can represent other containers as well. The first set of methods is used +either to emulate a sequence or to emulate a mapping; the difference is that for +a sequence, the allowable keys should be the integers *k* for which ``0 <= k < +N`` where *N* is the length of the sequence, or slice objects, which define a +range of items. (For backwards compatibility, the method :meth:`__getslice__` +(see below) can also be defined to handle simple, but not extended slices.) It +is also recommended that mappings provide the methods :meth:`keys`, +:meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`, +:meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`, +:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar +to those for Python's standard dictionary objects. The :mod:`UserDict` module +provides a :class:`DictMixin` class to help create those methods from a base set +of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and +:meth:`keys`. Mutable sequences should provide methods :meth:`append`, +:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, +:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list +objects. Finally, sequence types should implement addition (meaning +concatenation) and multiplication (meaning repetition) by defining the methods +:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, +:meth:`__rmul__` and :meth:`__imul__` described below; they should not define +:meth:`__coerce__` or other numerical operators. It is recommended that both +mappings and sequences implement the :meth:`__contains__` method to allow +efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent +of :meth:`has_key`; for sequences, it should search through the values. It is +further recommended that both mappings and sequences implement the +:meth:`__iter__` method to allow efficient iteration through the container; for +mappings, :meth:`__iter__` should be the same as :meth:`iterkeys`; for +sequences, it should iterate through the values. + + +.. method:: object.__len__(self) + + .. index:: + builtin: len + single: __nonzero__() (object method) + + Called to implement the built-in function :func:`len`. Should return the length + of the object, an integer ``>=`` 0. Also, an object that doesn't define a + :meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is + considered to be false in a Boolean context. + + +.. method:: object.__getitem__(self, key) + + .. index:: object: slice + + Called to implement evaluation of ``self[key]``. For sequence types, the + accepted keys should be integers and slice objects. Note that the special + interpretation of negative indexes (if the class wishes to emulate a sequence + type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate + type, :exc:`TypeError` may be raised; if of a value outside the set of indexes + for the sequence (after any special interpretation of negative values), + :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not + in the container), :exc:`KeyError` should be raised. + + .. note:: + + :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal + indexes to allow proper detection of the end of the sequence. + + +.. method:: object.__setitem__(self, key, value) + + Called to implement assignment to ``self[key]``. Same note as for + :meth:`__getitem__`. This should only be implemented for mappings if the + objects support changes to the values for keys, or if new keys can be added, or + for sequences if elements can be replaced. The same exceptions should be raised + for improper *key* values as for the :meth:`__getitem__` method. + + +.. method:: object.__delitem__(self, key) + + Called to implement deletion of ``self[key]``. Same note as for + :meth:`__getitem__`. This should only be implemented for mappings if the + objects support removal of keys, or for sequences if elements can be removed + from the sequence. The same exceptions should be raised for improper *key* + values as for the :meth:`__getitem__` method. + + +.. method:: object.__iter__(self) + + This method is called when an iterator is required for a container. This method + should return a new iterator object that can iterate over all the objects in the + container. For mappings, it should iterate over the keys of the container, and + should also be made available as the method :meth:`iterkeys`. + + Iterator objects also need to implement this method; they are required to return + themselves. For more information on iterator objects, see :ref:`typeiter`. + +The membership test operators (:keyword:`in` and :keyword:`not in`) are normally +implemented as an iteration through a sequence. However, container objects can +supply the following special method with a more efficient implementation, which +also does not require the object be a sequence. + + +.. method:: object.__contains__(self, item) + + Called to implement membership test operators. Should return true if *item* is + in *self*, false otherwise. For mapping objects, this should consider the keys + of the mapping rather than the values or the key-item pairs. + + +.. _sequence-methods: + +Additional methods for emulation of sequence types +-------------------------------------------------- + +The following optional methods can be defined to further emulate sequence +objects. Immutable sequences methods should at most only define +:meth:`__getslice__`; mutable sequences might define all three methods. + + +.. method:: object.__getslice__(self, i, j) + + .. deprecated:: 2.0 + Support slice objects as parameters to the :meth:`__getitem__` method. + + Called to implement evaluation of ``self[i:j]``. The returned object should be + of the same type as *self*. Note that missing *i* or *j* in the slice + expression are replaced by zero or ``sys.maxint``, respectively. If negative + indexes are used in the slice, the length of the sequence is added to that + index. If the instance does not implement the :meth:`__len__` method, an + :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this + way are not still negative. Indexes which are greater than the length of the + sequence are not modified. If no :meth:`__getslice__` is found, a slice object + is created instead, and passed to :meth:`__getitem__` instead. + + +.. method:: object.__setslice__(self, i, j, sequence) + + Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as + for :meth:`__getslice__`. + + This method is deprecated. If no :meth:`__setslice__` is found, or for extended + slicing of the form ``self[i:j:k]``, a slice object is created, and passed to + :meth:`__setitem__`, instead of :meth:`__setslice__` being called. + + +.. method:: object.__delslice__(self, i, j) + + Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for + :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is + found, or for extended slicing of the form ``self[i:j:k]``, a slice object is + created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__` + being called. + +Notice that these methods are only invoked when a single slice with a single +colon is used, and the slice method is available. For slice operations +involving extended slice notation, or in absence of the slice methods, +:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a +slice object as argument. + +The following example demonstrate how to make your program or module compatible +with earlier versions of Python (assuming that methods :meth:`__getitem__`, +:meth:`__setitem__` and :meth:`__delitem__` support slice objects as +arguments):: + + class MyClass: + ... + def __getitem__(self, index): + ... + def __setitem__(self, index, value): + ... + def __delitem__(self, index): + ... + + if sys.version_info < (2, 0): + # They won't be defined if version is at least 2.0 final + + def __getslice__(self, i, j): + return self[max(0, i):max(0, j):] + def __setslice__(self, i, j, seq): + self[max(0, i):max(0, j):] = seq + def __delslice__(self, i, j): + del self[max(0, i):max(0, j):] + ... + +Note the calls to :func:`max`; these are necessary because of the handling of +negative indices before the :meth:`__\*slice__` methods are called. When +negative indexes are used, the :meth:`__\*item__` methods receive them as +provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index +values. For each negative index value, the length of the sequence is added to +the index before calling the method (which may still result in a negative +index); this is the customary handling of negative indexes by the built-in +sequence types, and the :meth:`__\*item__` methods are expected to do this as +well. However, since they should already be doing that, negative indexes cannot +be passed in; they must be constrained to the bounds of the sequence before +being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)`` +conveniently returns the proper value. + + +.. _numeric-types: + +Emulating numeric types +----------------------- + +The following methods can be defined to emulate numeric objects. Methods +corresponding to operations that are not supported by the particular kind of +number implemented (e.g., bitwise operations for non-integral numbers) should be +left undefined. + + +.. method:: object.__add__(self, other) + object.__sub__(self, other) + object.__mul__(self, other) + object.__floordiv__(self, other) + object.__mod__(self, other) + object.__divmod__(self, other) + object.__pow__(self, other[, modulo]) + object.__lshift__(self, other) + object.__rshift__(self, other) + object.__and__(self, other) + object.__xor__(self, other) + object.__or__(self, other) + + .. index:: + builtin: divmod + builtin: pow + builtin: pow + + These methods are called to implement the binary arithmetic operations (``+``, + ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, + ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression + *x*``+``*y*, where *x* is an instance of a class that has an :meth:`__add__` + method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the + equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be + related to :meth:`__truediv__` (described below). Note that :meth:`__pow__` + should be defined to accept an optional third argument if the ternary version of + the built-in :func:`pow` function is to be supported. + + If one of those methods does not support the operation with the supplied + arguments, it should return ``NotImplemented``. + + +.. method:: object.__div__(self, other) + object.__truediv__(self, other) + + The division operator (``/``) is implemented by these methods. The + :meth:`__truediv__` method is used when ``__future__.division`` is in effect, + otherwise :meth:`__div__` is used. If only one of these two methods is defined, + the object will not support division in the alternate context; :exc:`TypeError` + will be raised instead. + + +.. method:: object.__radd__(self, other) + object.__rsub__(self, other) + object.__rmul__(self, other) + object.__rdiv__(self, other) + object.__rtruediv__(self, other) + object.__rfloordiv__(self, other) + object.__rmod__(self, other) + object.__rdivmod__(self, other) + object.__rpow__(self, other) + object.__rlshift__(self, other) + object.__rrshift__(self, other) + object.__rand__(self, other) + object.__rxor__(self, other) + object.__ror__(self, other) + + .. index:: + builtin: divmod + builtin: pow + + These methods are called to implement the binary arithmetic operations (``+``, + ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``, + ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are + only called if the left operand does not support the corresponding operation and + the operands are of different types. [#]_ For instance, to evaluate the + expression *x*``-``*y*, where *y* is an instance of a class that has an + :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns + *NotImplemented*. + + .. index:: builtin: pow + + Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the + coercion rules would become too complicated). + + .. note:: + + If the right operand's type is a subclass of the left operand's type and that + subclass provides the reflected method for the operation, this method will be + called before the left operand's non-reflected method. This behavior allows + subclasses to override their ancestors' operations. + + +.. method:: object.__iadd__(self, other) + object.__isub__(self, other) + object.__imul__(self, other) + object.__idiv__(self, other) + object.__itruediv__(self, other) + object.__ifloordiv__(self, other) + object.__imod__(self, other) + object.__ipow__(self, other[, modulo]) + object.__ilshift__(self, other) + object.__irshift__(self, other) + object.__iand__(self, other) + object.__ixor__(self, other) + object.__ior__(self, other) + + These methods are called to implement the augmented arithmetic operations + (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, + ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation + in-place (modifying *self*) and return the result (which could be, but does + not have to be, *self*). If a specific method is not defined, the augmented + operation falls back to the normal methods. For instance, to evaluate the + expression *x*``+=``*y*, where *x* is an instance of a class that has an + :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance + of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` + and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*. + + +.. method:: object.__neg__(self) + object.__pos__(self) + object.__abs__(self) + object.__invert__(self) + + .. index:: builtin: abs + + Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs` + and ``~``). + + +.. method:: object.__complex__(self) + object.__int__(self) + object.__long__(self) + object.__float__(self) + + .. index:: + builtin: complex + builtin: int + builtin: long + builtin: float + + Called to implement the built-in functions :func:`complex`, :func:`int`, + :func:`long`, and :func:`float`. Should return a value of the appropriate type. + + +.. method:: object.__oct__(self) + object.__hex__(self) + + .. index:: + builtin: oct + builtin: hex + + Called to implement the built-in functions :func:`oct` and :func:`hex`. Should + return a string value. + + +.. method:: object.__index__(self) + + Called to implement :func:`operator.index`. Also called whenever Python needs + an integer object (such as in slicing). Must return an integer (int or long). + + .. versionadded:: 2.5 + + +.. method:: object.__coerce__(self, other) + + Called to implement "mixed-mode" numeric arithmetic. Should either return a + 2-tuple containing *self* and *other* converted to a common numeric type, or + ``None`` if conversion is impossible. When the common type would be the type of + ``other``, it is sufficient to return ``None``, since the interpreter will also + ask the other object to attempt a coercion (but sometimes, if the implementation + of the other type cannot be changed, it is useful to do the conversion to the + other type here). A return value of ``NotImplemented`` is equivalent to + returning ``None``. + + +.. _coercion-rules: + +Coercion rules +-------------- + +This section used to document the rules for coercion. As the language has +evolved, the coercion rules have become hard to document precisely; documenting +what one version of one particular implementation does is undesirable. Instead, +here are some informal guidelines regarding coercion. In Python 3.0, coercion +will not be supported. + +* + + If the left operand of a % operator is a string or Unicode object, no coercion + takes place and the string formatting operation is invoked instead. + +* + + It is no longer recommended to define a coercion operation. Mixed-mode + operations on types that don't define coercion pass the original arguments to + the operation. + +* + + New-style classes (those derived from :class:`object`) never invoke the + :meth:`__coerce__` method in response to a binary operator; the only time + :meth:`__coerce__` is invoked is when the built-in function :func:`coerce` is + called. + +* + + For most intents and purposes, an operator that returns ``NotImplemented`` is + treated the same as one that is not implemented at all. + +* + + Below, :meth:`__op__` and :meth:`__rop__` are used to signify the generic method + names corresponding to an operator; :meth:`__iop__` is used for the + corresponding in-place operator. For example, for the operator '``+``', + :meth:`__add__` and :meth:`__radd__` are used for the left and right variant of + the binary operator, and :meth:`__iadd__` for the in-place variant. + +* + + For objects *x* and *y*, first ``x.__op__(y)`` is tried. If this is not + implemented or returns ``NotImplemented``, ``y.__rop__(x)`` is tried. If this + is also not implemented or returns ``NotImplemented``, a :exc:`TypeError` + exception is raised. But see the following exception: + +* + + Exception to the previous item: if the left operand is an instance of a built-in + type or a new-style class, and the right operand is an instance of a proper + subclass of that type or class and overrides the base's :meth:`__rop__` method, + the right operand's :meth:`__rop__` method is tried *before* the left operand's + :meth:`__op__` method. + + This is done so that a subclass can completely override binary operators. + Otherwise, the left operand's :meth:`__op__` method would always accept the + right operand: when an instance of a given class is expected, an instance of a + subclass of that class is always acceptable. + +* + + When either operand type defines a coercion, this coercion is called before that + type's :meth:`__op__` or :meth:`__rop__` method is called, but no sooner. If + the coercion returns an object of a different type for the operand whose + coercion is invoked, part of the process is redone using the new object. + +* + + When an in-place operator (like '``+=``') is used, if the left operand + implements :meth:`__iop__`, it is invoked without any coercion. When the + operation falls back to :meth:`__op__` and/or :meth:`__rop__`, the normal + coercion rules apply. + +* + + In *x*``+``*y*, if *x* is a sequence that implements sequence concatenation, + sequence concatenation is invoked. + +* + + In *x*``*``*y*, if one operator is a sequence that implements sequence + repetition, and the other is an integer (:class:`int` or :class:`long`), + sequence repetition is invoked. + +* + + Rich comparisons (implemented by methods :meth:`__eq__` and so on) never use + coercion. Three-way comparison (implemented by :meth:`__cmp__`) does use + coercion under the same conditions as other binary operations use it. + +* + + In the current implementation, the built-in numeric types :class:`int`, + :class:`long` and :class:`float` do not use coercion; the type :class:`complex` + however does use it. The difference can become apparent when subclassing these + types. Over time, the type :class:`complex` may be fixed to avoid coercion. + All these types implement a :meth:`__coerce__` method, for use by the built-in + :func:`coerce` function. + + +.. _context-managers: + +With Statement Context Managers +------------------------------- + +.. versionadded:: 2.5 + +A :dfn:`context manager` is an object that defines the runtime context to be +established when executing a :keyword:`with` statement. The context manager +handles the entry into, and the exit from, the desired runtime context for the +execution of the block of code. Context managers are normally invoked using the +:keyword:`with` statement (described in section :ref:`with`), but can also be +used by directly invoking their methods. + +.. index:: + statement: with + single: context manager + +Typical uses of context managers include saving and restoring various kinds of +global state, locking and unlocking resources, closing opened files, etc. + +For more information on context managers, see :ref:`typecontextmanager`. + + +.. method:: object.__enter__(self) + + Enter the runtime context related to this object. The :keyword:`with` statement + will bind this method's return value to the target(s) specified in the + :keyword:`as` clause of the statement, if any. + + +.. method:: object.__exit__(self, exc_type, exc_value, traceback) + + Exit the runtime context related to this object. The parameters describe the + exception that caused the context to be exited. If the context was exited + without an exception, all three arguments will be :const:`None`. + + If an exception is supplied, and the method wishes to suppress the exception + (i.e., prevent it from being propagated), it should return a true value. + Otherwise, the exception will be processed normally upon exit from this method. + + Note that :meth:`__exit__` methods should not reraise the passed-in exception; + this is the caller's responsibility. + + +.. seealso:: + + :pep:`0343` - The "with" statement + The specification, background, and examples for the Python :keyword:`with` + statement. + +.. rubric:: Footnotes + +.. [#] Since Python 2.2, a gradual merging of types and classes has been started that + makes this and a few other assertions made in this manual not 100% accurate and + complete: for example, it *is* now possible in some cases to change an object's + type, under certain controlled conditions. Until this manual undergoes + extensive revision, it must now be taken as authoritative only regarding + "classic classes", that are still the default, for compatibility purposes, in + Python 2.2 and 2.3. For more information, see + http://www.python.org/doc/newstyle.html. + +.. [#] This, and other statements, are only roughly true for instances of new-style + classes. + +.. [#] For operands of the same type, it is assumed that if the non-reflected method + (such as :meth:`__add__`) fails the operation is not supported, which is why the + reflected method is not called. + |