| 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. |
| |
n | Numbers |
n | :class:`numbers.Number` |
| .. 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: |
| |
n | Integers |
n | :class:`numbers.Integral` |
| .. 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) |
| |
n | These represent numbers in the range -2147483648 through 2147483647. (The range |
n | These represent numbers in the range -2147483648 through 2147483647. |
| may be larger on machines with a larger natural word size, but not smaller.) |
| (The range may be larger on machines with a larger natural word size, |
| When the result of an operation would fall outside this range, the result is |
| but not smaller.) When the result of an operation would fall outside |
| normally returned as a long integer (in some cases, the exception |
| this range, the result is normally returned as a long integer (in some |
| :exc:`OverflowError` is raised instead). For the purpose of shift and mask |
| cases, the exception :exc:`OverflowError` is raised instead). For the |
| operations, integers are assumed to have a binary, 2's complement notation using |
| purpose of shift and mask operations, integers are assumed to have a |
| 32 or more bits, and hiding no bits from the user (i.e., all 4294967296 |
| binary, 2's complement notation using 32 or more bits, and hiding no |
| bits from the user (i.e., all 4294967296 different bit patterns |
| different bit patterns correspond to different values). |
| correspond to different values). |
| |
| Long integers |
| .. index:: object: long integer |
| |
n | These represent numbers in an unlimited range, subject to available (virtual) |
n | These represent numbers in an unlimited range, subject to available |
| memory only. For the purpose of shift and mask operations, a binary |
| (virtual) memory only. For the purpose of shift and mask operations, a |
| representation is assumed, and negative numbers are represented in a variant of |
| binary representation is assumed, and negative numbers are represented |
| 2's complement which gives the illusion of an infinite string of sign bits |
| in a variant of 2's complement which gives the illusion of an infinite |
| extending to the left. |
| string of sign bits extending to the left. |
| |
| Booleans |
| .. index:: |
| object: Boolean |
| single: False |
| single: True |
| |
n | These represent the truth values False and True. The two objects representing |
n | These represent the truth values False and True. The two objects |
| the values False and True are the only Boolean objects. The Boolean type is a |
| representing the values False and True are the only Boolean objects. |
| subtype of plain integers, and Boolean values behave like the values 0 and 1, |
| The Boolean type is a subtype of plain integers, and Boolean values |
| respectively, in almost all contexts, the exception being that when converted to |
| behave like the values 0 and 1, respectively, in almost all contexts, |
| the exception being that when converted to a string, the strings |
| a string, the strings ``"False"`` or ``"True"`` are returned, respectively. |
| ``"False"`` or ``"True"`` are returned, respectively. |
| |
| .. index:: pair: integer; representation |
| |
n | The rules for integer representation are intended to give the most meaningful |
n | The rules for integer representation are intended to give the most |
| interpretation of shift and mask operations involving negative integers and the |
| meaningful interpretation of shift and mask operations involving negative |
| least surprises when switching between the plain and long integer domains. Any |
| integers and the least surprises when switching between the plain and long |
| operation except left shift, if it yields a result in the plain integer domain |
| integer domains. Any operation, if it yields a result in the plain |
| without causing overflow, will yield the same result in the long integer domain |
| integer domain, will yield the same result in the long integer domain or |
| or when using mixed operands. |
| when using mixed operands. The switch between domains is transparent to |
| the programmer. |
| |
n | .. % Integers |
n | :class:`numbers.Real` (:class:`float`) |
| |
| Floating point numbers |
| .. index:: |
| object: floating point |
| pair: floating point; number |
| pair: C; language |
| pair: Java; language |
| |
n | These represent machine-level double precision floating point numbers. You are |
n | 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. |
| |
n | Complex numbers |
n | :class:`numbers.Complex` |
| .. 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``. |
n | |
| .. % Numbers |
| |
| Sequences |
| .. index:: |
| builtin: len |
| object: sequence |
| single: index operation |
| single: item selection |
| single: subscription |
| |
n | These represent finite ordered sets indexed by non-negative numbers. The built- |
n | These represent finite ordered sets indexed by non-negative numbers. The |
| in function :func:`len` returns the number of items of a sequence. When the |
| built-in function :func:`len` returns the number of items of a sequence. When |
| length of a sequence is *n*, the index set contains the numbers 0, 1, ..., |
| 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]``. |
| ..., *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. |
| |
| :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 |
n | Class objects are created by class definitions (see section :ref:`class`, "Class |
n | Both class types (new-style classes) and class objects (old-style/classic |
| classes) are typically created by class definitions (see section |
| definitions"). A class has a namespace implemented by a dictionary object. Class |
| :ref:`class`). A class has a namespace implemented by a dictionary object. |
| attribute references are translated to lookups in this dictionary, e.g., ``C.x`` |
| Class attribute references are translated to lookups in this dictionary, e.g., |
| is translated to ``C.__dict__["x"]``. When the attribute name is not found |
| ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes |
| there, the attribute search continues in the base classes. The search is depth- |
| in particular there are a number of hooks which allow for other means of |
| locating attributes). When the attribute name is not found there, the |
| attribute search continues in the base classes. For old-style classes, the |
| first, left-to-right in the order of occurrence in the base class list. |
| search is depth-first, left-to-right in the order of occurrence in the base |
| class list. New-style classes use the more complex C3 method resolution |
| order which behaves correctly even in the presence of 'diamond' |
| inheritance structures where there are multiple inheritance paths |
| leading back to a common ancestor. Additional details on the C3 MRO used by |
| new-style classes can be found in the documentation accompanying the |
| 2.3 release at http://www.python.org/download/releases/2.3/mro/. |
| |
| .. XXX: Could we add that MRO doc as an appendix to the language ref? |
| |
| .. index:: |
| object: class |
| object: class instance |
| object: instance |
| pair: class object; call |
| single: container |
| object: dictionary |
| pair: class; attribute |
| |
n | When a class attribute reference (for class :class:`C`, say) would yield a user- |
n | When a class attribute reference (for class :class:`C`, say) would yield a |
| defined function object or an unbound user-defined method object whose |
| 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 |
n | transformed into a bound user-defined method object whose :attr:`im_class` and |
n | transformed into a bound user-defined method object whose :attr:`im_class` |
| :attr:`im_self` attributes are both :class:`C`. When it would yield a static |
| and :attr:`im_self` attributes are both :class:`C`. When it would yield a |
| method object, it is transformed into the object wrapped by the static method |
| static method object, it is transformed into the object wrapped by the static |
| object. See section :ref:`descriptors` for another way in which attributes |
| method object. See section :ref:`descriptors` for another way in which |
| retrieved from a class may differ from those actually contained in its |
| attributes retrieved from a class may differ from those actually contained in |
| :attr:`__dict__`. |
| its :attr:`__dict__` (note that only new-style classes support descriptors). |
| |
| .. 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 |
| |
| 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 |
n | :func:`open` built-in function, and also by :func:`os.popen`, :func:`os.fdopen`, |
n | :func:`open` built-in function, and also by :func:`os.popen`, |
| and the :meth:`makefile` method of socket objects (and perhaps by other |
| :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and |
| functions or methods provided by extension modules). The objects ``sys.stdin``, |
| perhaps by other functions or methods provided by extension modules). The |
| ``sys.stdout`` and ``sys.stderr`` are initialized to file objects corresponding |
| objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to |
| to the interpreter's standard input, output and error streams. See the Python |
| file objects corresponding to the interpreter's standard input, output and |
| Library Reference (XXX reference: ../lib/lib.html) for complete documentation of |
| 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 |
| |
n | Code objects represent *byte-compiled* executable Python code, or *bytecode*. |
n | Code objects represent *byte-compiled* executable Python code, or :term:`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 |
n | which it was defined), while a code object contains no context; also the |
n | which it was defined), while a code object contains no context; also the default |
| default argument values are stored in the function object, not in the code |
| argument values are stored in the function object, not in the code object |
| object (because they represent values calculated at run-time). Unlike function |
| (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; |
n | :attr:`co_lnotab` is a string encoding the mapping from byte code offsets to |
n | :attr:`co_lnotab` is a string encoding the mapping from bytecode 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) |
| |
| 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. |
| |
n | .. % Internal types |
| |
n | .. % Types |
n | .. _newstyle: |
| .. % ========================================================================= |
| |
| |
| New-style and classic classes |
| ============================= |
| |
n | Classes and instances come in two flavors: old-style or classic, and new-style. |
n | 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 |
n | new-style class neither more nor less than a user-defined type. If *x* is an |
n | new-style class is 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__``. |
| instance of a new-style class, then ``type(x)`` is typically the same as |
| ``x.__class__`` (although this is not guaranteed - a new-style class instance is |
| permitted to override the value returned for ``x.__class__``). |
| |
| The major motivation for introducing new-style classes is to provide a unified |
n | object model with a full meta-model. It also has a number of immediate |
n | object model with a full meta-model. It also has a number of practical |
| 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. |
| |
n | This manual is not up-to-date with respect to new-style classes. For now, |
n | While this manual aims to provide comprehensive coverage of Python's class |
| please see `<http://www.python.org/doc/newstyle.html>`_ for more information. |
| mechanics, it may still be lacking in some areas when it comes to its coverage |
| of new-style classes. Please see http://www.python.org/doc/newstyle/ for |
| sources of additional information. |
| |
| .. index:: |
n | single: class; new-style |
| single: class |
| single: class; classic |
| single: class |
| single: class; old-style |
| single: class |
| |
n | The plan is to eventually drop old-style classes, leaving only the semantics of |
n | Old-style classes are removed in Python 3.0, leaving only the semantics of |
| new-style classes. This change will probably only be feasible in Python 3.0. |
| new-style classes. |
| 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__`, |
n | and ``x`` is an instance of this class, then ``x[i]`` is equivalent [#]_ to |
n | and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent |
| ``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation |
| to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)`` |
| for new-style classes. Except where mentioned, attempts to execute an |
| raise an exception when no appropriate method is defined. |
| operation raise an exception when no appropriate method is defined (typically |
| :exc:`AttributeError` or :exc:`TypeError`). |
| |
| 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 |
| ------------------- |
| |
n | |
| .. method:: object.__new__(cls[, ...]) |
n | |
| .. index:: pair: subclassing; immutable types |
| |
| 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*). |
| |
| (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:: |
| |
n | ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the |
n | ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements |
| reference count for ``x`` by one, and the latter is only called when ``x``'s |
| the reference count for ``x`` by one, and the latter is only called when |
| reference count reaches zero. Some common situations that may prevent the |
| ``x``'s reference count reaches zero. Some common situations that may |
| reference count of an object from going to zero include: circular references |
| prevent the reference count of an object from going to zero include: |
| between objects (e.g., a doubly-linked list or a tree data structure with parent |
| circular references between objects (e.g., a doubly-linked list or a tree |
| and child pointers); a reference to the object on the stack frame of a function |
| data structure with parent and child pointers); a reference to the object |
| that caught an exception (the traceback stored in ``sys.exc_traceback`` keeps |
| on the stack frame of a function that caught an exception (the traceback |
| the stack frame alive); or a reference to the object on the stack frame that |
| stored in ``sys.exc_traceback`` keeps the stack frame alive); or a |
| reference to the object on the stack frame that raised an unhandled |
| raised an unhandled exception in interactive mode (the traceback stored in |
| exception in interactive mode (the traceback stored in |
| ``sys.last_traceback`` keeps the stack frame alive). The first situation can |
| ``sys.last_traceback`` keeps the stack frame alive). The first situation |
| only be remedied by explicitly breaking the cycles; the latter two situations |
| can only be remedied by explicitly breaking the cycles; the latter two |
| can be resolved by storing ``None`` in ``sys.exc_traceback`` or |
| situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or |
| ``sys.last_traceback``. Circular references which are garbage are detected when |
| ``sys.last_traceback``. Circular references which are garbage are |
| the option cycle detector is enabled (it's on by default), but can only be |
| detected when the option cycle detector is enabled (it's on by default), |
| cleaned up if there are no Python-level :meth:`__del__` methods involved. Refer |
| but can only be cleaned up if there are no Python-level :meth:`__del__` |
| to the documentation for the :mod:`gc` module (XXX reference: ../lib/module- |
| methods involved. Refer to the documentation for the :mod:`gc` module for |
| gc.html) for more information about how :meth:`__del__` methods are handled by |
| more information about how :meth:`__del__` methods are handled by the |
| the cycle detector, particularly the description of the ``garbage`` value. |
| 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 |
n | been deleted. For this reason, :meth:`__del__` methods should do the absolute |
n | been deleted or in the process of being torn down (e.g. the import |
| machinery shutting down). 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. |
| |
| |
| object.__le__(self, other) |
| object.__eq__(self, other) |
| object.__ne__(self, other) |
| object.__gt__(self, other) |
| object.__ge__(self, other) |
| |
| .. versionadded:: 2.1 |
| |
n | .. index:: |
| single: comparisons |
| |
| 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 |
n | ``x.__ge__(y)``. These methods can return any value, but if the comparison |
n | ``x.__ge__(y)``. |
| operator is used in a Boolean context, the return value should be interpretable |
| as a Boolean value, else a :exc:`TypeError` will be raised. By convention, |
| ``False`` is used for false and ``True`` for true. |
| |
n | 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 |
| There are no implied relationships among the comparison operators. The truth |
| ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when defining |
| of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when |
| :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will |
| defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the |
| behave as expected. |
| operators will behave as expected. See the paragraph on :meth:`__hash__` for |
| some important notes on creating :term:`hashable` objects which support |
| custom comparison operations and are usable as dictionary keys. |
| |
n | There are no reflected (swapped-argument) versions of these methods (to be used |
n | There are no swapped-argument versions of these methods (to be used when the |
| when the left argument does not support the operation but the right argument |
| left argument does not support the operation but the right argument does); |
| does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection, |
| 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. |
| |
n | Arguments to rich comparison methods are never coerced. A rich comparison |
n | Arguments to rich comparison methods are never coerced. |
| method may return ``NotImplemented`` if it does not implement the operation for |
| a given pair of arguments. |
| |
| |
| .. method:: object.__cmp__(self, other) |
| |
| .. index:: |
| builtin: cmp |
| single: comparisons |
| |
n | Called by comparison operations if rich comparison (see above) is not defined. |
n | Called by comparison operations if rich comparison (see above) is not |
| Should return a negative integer if ``self < other``, zero if ``self == other``, |
| defined. Should return a negative integer if ``self < other``, zero if |
| a positive integer if ``self > other``. If no :meth:`__cmp__`, :meth:`__eq__` |
| ``self == other``, a positive integer if ``self > other``. If no |
| or :meth:`__ne__` operation is defined, class instances are compared by object |
| :meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class |
| identity ("address"). See also the description of :meth:`__hash__` for some |
| instances are compared by object identity ("address"). See also the |
| important notes on creating objects which support custom comparison operations |
| description of :meth:`__hash__` for some important notes on creating |
| :term:`hashable` objects which support custom comparison operations and are |
| and are usable as dictionary keys. (Note: the restriction that exceptions are |
| usable as dictionary keys. (Note: the restriction that exceptions are not |
| not propagated by :meth:`__cmp__` has been removed since Python 1.5.) |
| 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 |
| |
n | Called for the key object for dictionary operations, and by the built-in |
n | Called by built-in function :func:`hash` and for operations on members of |
| function :func:`hash`. Should return a 32-bit integer usable as a hash value |
| hashed collections including :class:`set`, :class:`frozenset`, and |
| for dictionary operations. The only required property is that objects which |
| :class:`dict`. :meth:`__hash__` should return an integer. The only required |
| compare equal have the same hash value; it is advised to somehow mix together |
| property is that objects which compare equal have the same hash value; it is |
| (e.g., using exclusive or) the hash values for the components of the object that |
| advised to somehow mix together (e.g. using exclusive or) the hash values for |
| also play a part in comparison of objects. If a class does not define a |
| the components of the object that also play a part in comparison of objects. |
| :meth:`__cmp__` method it should not define a :meth:`__hash__` operation either; |
| |
| If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it |
| should not define a :meth:`__hash__` operation either; if it defines |
| if it defines :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its |
| :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances |
| instances will not be usable as dictionary keys. If a class defines mutable |
| will not be usable in hashed collections. If a class defines mutable objects |
| objects and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not |
| and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not |
| implement :meth:`__hash__`, since the dictionary implementation requires that a |
| implement :meth:`__hash__`, since hashable collection implementations require |
| key's hash value is immutable (if the object's hash value changes, it will be in |
| that a object's hash value is immutable (if the object's hash value changes, |
| the wrong hash bucket). |
| it will be in the wrong hash bucket). |
| |
| User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods |
| by default; with them, all objects compare unequal (except with themselves) |
| and ``x.__hash__()`` returns ``id(x)``. |
| |
| Classes which inherit a :meth:`__hash__` method from a parent class but |
| change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash |
| value returned is no longer appropriate (e.g. by switching to a value-based |
| concept of equality instead of the default identity based equality) can |
| explicitly flag themselves as being unhashable by setting ``__hash__ = None`` |
| in the class definition. Doing so means that not only will instances of the |
| class raise an appropriate :exc:`TypeError` when a program attempts to |
| retrieve their hash value, but they will also be correctly identified as |
| unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike |
| classes which define their own :meth:`__hash__` to explicitly raise |
| :exc:`TypeError`). |
| |
| .. versionchanged:: 2.5 |
n | :meth:`__hash__` may now also return a long integer object; the 32-bit integer |
n | :meth:`__hash__` may now also return a long integer object; the 32-bit |
| is then derived from the hash of that object. |
| integer is then derived from the hash of that object. |
| |
n | .. index:: single: __cmp__() (object method) |
n | .. versionchanged:: 2.6 |
| :attr:`__hash__` may now be set to :const:`None` to explicitly flag |
| instances of a class as unhashable. |
| |
| |
| .. method:: object.__nonzero__(self) |
| |
| .. index:: single: __len__() (mapping object method) |
| |
n | Called to implement truth value testing, and the built-in operation ``bool()``; |
n | Called to implement truth value testing and the built-in operation ``bool()``; |
| should return ``False`` or ``True``, or their integer equivalents ``0`` or |
n | ``1``. When this method is not defined, :meth:`__len__` is called, if it is |
n | ``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 |
| defined, and the object is considered true if its result is nonzero. |
| :meth:`__nonzero__`, all its instances are considered true. |
| 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 |
| 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__*. |
| |
n | * *__slots__* do not work for classes derived from "variable-length" built-in |
n | * Nonempty *__slots__* does not work for classes derived from "variable-length" |
| types such as :class:`long`, :class:`str` and :class:`tuple`. |
| 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. |
| |
n | * *__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 |
n | callable assigned to it will be called instead of :func:`type`. The allows |
n | callable assigned to it will be called instead of :func:`type`. This 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. |
n | |
| These steps will have to be performed in the metaclass's :meth:`__new__` method |
| -- :meth:`type.__new__` can then be called from this method to create a class |
| with different properties. This example adds a new element to the class |
| dictionary before creating the class:: |
| |
| class metacls(type): |
| def __new__(mcs, name, bases, dict): |
| dict['foo'] = 'metacls was here' |
| return type.__new__(mcs, name, bases, dict) |
| |
| You can of course also override other class methods (or add new methods); for |
| example defining a custom :meth:`__call__` method in the metaclass allows custom |
| behavior when the class is called, e.g. not always creating a new instance. |
| |
| |
| .. 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`. |
| |
| 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 |
| ------------------------- |
n | |
| .. index:: |
| single: keys() (mapping object method) |
| single: values() (mapping object method) |
| single: items() (mapping object method) |
| single: iterkeys() (mapping object method) |
| single: itervalues() (mapping object method) |
| single: iteritems() (mapping object method) |
| single: has_key() (mapping object method) |
| single: get() (mapping object method) |
| single: setdefault() (mapping object method) |
| single: pop() (mapping object method) |
| single: popitem() (mapping object method) |
| single: clear() (mapping object method) |
| single: copy() (mapping object method) |
| single: update() (mapping object method) |
| single: __contains__() (mapping object method) |
| single: append() (sequence object method) |
| single: count() (sequence object method) |
| single: extend() (sequence object method) |
| single: index() (sequence object method) |
| single: insert() (sequence object method) |
| single: pop() (sequence object method) |
| single: remove() (sequence object method) |
| single: reverse() (sequence object method) |
| single: sort() (sequence object method) |
| single: __add__() (sequence object method) |
| single: __radd__() (sequence object method) |
| single: __iadd__() (sequence object method) |
| single: __mul__() (sequence object method) |
| single: __rmul__() (sequence object method) |
| single: __imul__() (sequence object method) |
| single: __contains__() (sequence object method) |
| single: __iter__() (sequence object method) |
| single: __coerce__() (numeric object method) |
| |
| 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`, |
n | :meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` |
n | :meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar |
| behaving similar to those for Python's standard dictionary objects. The |
| to those for Python's standard dictionary objects. The :mod:`UserDict` module |
| :mod:`UserDict` module provides a :class:`DictMixin` class to help create those |
| provides a :class:`DictMixin` class to help create those methods from a base set |
| methods from a base set of :meth:`__getitem__`, :meth:`__setitem__`, |
| of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and |
| :meth:`__delitem__`, and :meth:`keys`. Mutable sequences |
| :meth:`keys`. Mutable sequences should provide methods :meth:`append`, |
| should provide methods :meth:`append`, :meth:`count`, :meth:`index`, |
| :meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, |
| :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, |
| :meth:`reverse` and :meth:`sort`, like Python standard list objects. Finally, |
| :meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list |
| sequence types should implement addition (meaning concatenation) and |
| objects. Finally, sequence types should implement addition (meaning |
| multiplication (meaning repetition) by defining the methods :meth:`__add__`, |
| concatenation) and multiplication (meaning repetition) by defining the methods |
| :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and |
| :meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, |
| :meth:`__imul__` described below; they should not define :meth:`__coerce__` or |
| :meth:`__rmul__` and :meth:`__imul__` described below; they should not define |
| other numerical operators. It is recommended that both mappings and sequences |
| :meth:`__coerce__` or other numerical operators. It is recommended that both |
| 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 |
| mappings and sequences implement the :meth:`__contains__` method to allow |
| efficient iteration through the container; for mappings, :meth:`__iter__` should |
| efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent |
| be the same as :meth:`iterkeys`; for sequences, it should iterate through the |
| of :meth:`has_key`; for sequences, it should search through the values. It is |
| values. |
| 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. |
| |
| |
n | .. method:: container object.__len__(self) |
n | .. 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. |
| |
| |
n | .. method:: container object.__getitem__(self, key) |
n | .. 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 |
| 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. |
| |
| |
n | .. method:: container object.__setitem__(self, key, value) |
n | .. 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. |
| |
| |
n | .. method:: container object.__delitem__(self, key) |
n | .. 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. |
| |
| |
n | .. method:: container object.__iter__(self) |
n | .. 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 |
n | themselves. For more information on iterator objects, see "Iterator Types (XXX |
n | themselves. For more information on iterator objects, see :ref:`typeiter`. |
| reference: ../lib/typeiter.html)" in the Python Library Reference (XXX |
| |
| reference: ../lib/lib.html). |
| |
| .. method:: object.__reversed__(self) |
| |
| Called (if present) by the :func:`reversed` builtin to implement |
| reverse iteration. It should return a new iterator object that iterates |
| over all the objects in the container in reverse order. |
| |
| If the :meth:`__reversed__` method is not provided, the |
| :func:`reversed` builtin will fall back to using the sequence protocol |
| (:meth:`__len__` and :meth:`__getitem__`). Objects should normally |
| only provide :meth:`__reversed__` if they do not support the sequence |
| protocol and an efficient implementation of reverse iteration is possible. |
| |
| .. versionadded:: 2.6 |
| |
| |
| 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. |
| |
| |
n | .. method:: container object.__contains__(self, item) |
n | .. 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. |
| |
| |
n | .. method:: sequence object.__getslice__(self, i, j) |
n | .. method:: object.__getslice__(self, i, j) |
| |
| .. deprecated:: 2.0 |
| Support slice objects as parameters to the :meth:`__getitem__` method. |
n | (However, built-in types in CPython currently still implement |
| :meth:`__getslice__`. Therefore, you have to override it in derived |
| classes when implementing slicing.) |
| |
| 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. |
| |
| |
n | .. method:: sequence object.__setslice__(self, i, j, sequence) |
n | .. 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. |
| |
| |
n | .. method:: sequence object.__delslice__(self, i, j) |
n | .. 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 |
| ----------------------- |
| |
| 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. |
| |
| |
n | .. method:: numeric object.__add__(self, other) |
n | .. method:: object.__add__(self, other) |
| numeric object.__sub__(self, other) |
| object.__sub__(self, other) |
| numeric object.__mul__(self, other) |
| object.__mul__(self, other) |
| numeric object.__floordiv__(self, other) |
| object.__floordiv__(self, other) |
| numeric object.__mod__(self, other) |
| object.__mod__(self, other) |
| numeric object.__divmod__(self, other) |
| object.__divmod__(self, other) |
| numeric object.__pow__(self, other[, modulo]) |
| object.__pow__(self, other[, modulo]) |
| numeric object.__lshift__(self, other) |
| object.__lshift__(self, other) |
| numeric object.__rshift__(self, other) |
| object.__rshift__(self, other) |
| numeric object.__and__(self, other) |
| object.__and__(self, other) |
| numeric object.__xor__(self, other) |
| object.__xor__(self, other) |
| numeric object.__or__(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 |
n | *x*``+``*y*, where *x* is an instance of a class that has an :meth:`__add__` |
n | ``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``. |
| |
| |
n | .. method:: numeric object.__div__(self, other) |
n | .. method:: object.__div__(self, other) |
| numeric object.__truediv__(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. |
| |
| |
n | .. method:: numeric object.__radd__(self, other) |
n | .. method:: object.__radd__(self, other) |
| numeric object.__rsub__(self, other) |
| object.__rsub__(self, other) |
| numeric object.__rmul__(self, other) |
| object.__rmul__(self, other) |
| numeric object.__rdiv__(self, other) |
| object.__rdiv__(self, other) |
| numeric object.__rtruediv__(self, other) |
| object.__rtruediv__(self, other) |
| numeric object.__rfloordiv__(self, other) |
| object.__rfloordiv__(self, other) |
| numeric object.__rmod__(self, other) |
| object.__rmod__(self, other) |
| numeric object.__rdivmod__(self, other) |
| object.__rdivmod__(self, other) |
| numeric object.__rpow__(self, other) |
| object.__rpow__(self, other) |
| numeric object.__rlshift__(self, other) |
| object.__rlshift__(self, other) |
| numeric object.__rrshift__(self, other) |
| object.__rrshift__(self, other) |
| numeric object.__rand__(self, other) |
| object.__rand__(self, other) |
| numeric object.__rxor__(self, other) |
| object.__rxor__(self, other) |
| numeric object.__ror__(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 |
n | the operands are of different types. [#]_ For instance, to evaluate the |
n | 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 |
| 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. |
| |
| |
n | .. method:: numeric object.__iadd__(self, other) |
n | .. method:: object.__iadd__(self, other) |
| numeric object.__isub__(self, other) |
| object.__isub__(self, other) |
| numeric object.__imul__(self, other) |
| object.__imul__(self, other) |
| numeric object.__idiv__(self, other) |
| object.__idiv__(self, other) |
| numeric object.__itruediv__(self, other) |
| object.__itruediv__(self, other) |
| numeric object.__ifloordiv__(self, other) |
| object.__ifloordiv__(self, other) |
| numeric object.__imod__(self, other) |
| object.__imod__(self, other) |
| numeric object.__ipow__(self, other[, modulo]) |
| object.__ipow__(self, other[, modulo]) |
| numeric object.__ilshift__(self, other) |
| object.__ilshift__(self, other) |
| numeric object.__irshift__(self, other) |
| object.__irshift__(self, other) |
| numeric object.__iand__(self, other) |
| object.__iand__(self, other) |
| numeric object.__ixor__(self, other) |
| object.__ixor__(self, other) |
| numeric object.__ior__(self, other) |
| object.__ior__(self, other) |
| |
n | These methods are called to implement the augmented arithmetic operations |
n | These methods are called to implement the augmented arithmetic assignments |
| (``+=``, ``-=``, ``*=``, ``/=``, ``%=``, ``**=``, ``<<=``, ``>>=``, ``&=``, |
| (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, |
| ``^=``, ``|=``). These methods should attempt to do the operation in-place |
| ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation |
| (modifying *self*) and return the result (which could be, but does not have to |
| in-place (modifying *self*) and return the result (which could be, but does |
| be, *self*). If a specific method is not defined, the augmented operation falls |
| not have to be, *self*). If a specific method is not defined, the augmented |
| back to the normal methods. For instance, to evaluate the expression |
| assignment falls back to the normal methods. For instance, to execute the |
| *x*``+=``*y*, where *x* is an instance of a class that has an :meth:`__iadd__` |
| statement ``x += y``, where *x* is an instance of a class that has an |
| method, ``x.__iadd__(y)`` is called. If *x* is an instance of a class that does |
| :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance |
| not define a :meth:`__iadd__` method, ``x.__add__(y)`` and ``y.__radd__(x)`` are |
| of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` |
| considered, as with the evaluation of *x*``+``*y*. |
| and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``. |
| |
| |
n | .. method:: numeric object.__neg__(self) |
n | .. method:: object.__neg__(self) |
| numeric object.__pos__(self) |
| object.__pos__(self) |
| numeric object.__abs__(self) |
| object.__abs__(self) |
| numeric object.__invert__(self) |
| object.__invert__(self) |
| |
| .. index:: builtin: abs |
| |
| Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs` |
| and ``~``). |
| |
| |
n | .. method:: numeric object.__complex__(self) |
n | .. method:: object.__complex__(self) |
| numeric object.__int__(self) |
| object.__int__(self) |
| numeric object.__long__(self) |
| object.__long__(self) |
| numeric object.__float__(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. |
| |
| |
n | .. method:: numeric object.__oct__(self) |
n | .. method:: object.__oct__(self) |
| numeric object.__hex__(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. |
| |
| |
n | .. method:: numeric object.__index__(self) |
n | .. 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 |
| |
| |
n | .. method:: numeric object.__coerce__(self, other) |
n | .. 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 |
| |
| |
| .. seealso:: |
| |
| :pep:`0343` - The "with" statement |
| The specification, background, and examples for the Python :keyword:`with` |
| statement. |
| |
n | |
| .. _old-style-special-lookup: |
| |
| Special method lookup for old-style classes |
| ------------------------------------------- |
| |
| For old-style classes, special methods are always looked up in exactly the |
| same way as any other method or attribute. This is the case regardless of |
| whether the method is being looked up explicitly as in ``x.__getitem__(i)`` |
| or implicitly as in ``x[i]``. |
| |
| This behaviour means that special methods may exhibit different behaviour |
| for different instances of a single old-style class if the appropriate |
| special attributes are set differently:: |
| |
| >>> class C: |
| ... pass |
| ... |
| >>> c1 = C() |
| >>> c2 = C() |
| >>> c1.__len__ = lambda: 5 |
| >>> c2.__len__ = lambda: 9 |
| >>> len(c1) |
| 5 |
| >>> len(c2) |
| 9 |
| |
| |
| .. _new-style-special-lookup: |
| |
| Special method lookup for new-style classes |
| ------------------------------------------- |
| |
| For new-style classes, implicit invocations of special methods are only guaranteed |
| to work correctly if defined on an object's type, not in the object's instance |
| dictionary. That behaviour is the reason why the following code raises an |
| exception (unlike the equivalent example with old-style classes):: |
| |
| >>> class C(object): |
| ... pass |
| ... |
| >>> c = C() |
| >>> c.__len__ = lambda: 5 |
| >>> len(c) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in <module> |
| TypeError: object of type 'C' has no len() |
| |
| The rationale behind this behaviour lies with a number of special methods such |
| as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects, |
| including type objects. If the implicit lookup of these methods used the |
| conventional lookup process, they would fail when invoked on the type object |
| itself:: |
| |
| >>> 1 .__hash__() == hash(1) |
| True |
| >>> int.__hash__() == hash(int) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in <module> |
| TypeError: descriptor '__hash__' of 'int' object needs an argument |
| |
| Incorrectly attempting to invoke an unbound method of a class in this way is |
| sometimes referred to as 'metaclass confusion', and is avoided by bypassing |
| the instance when looking up special methods:: |
| |
| >>> type(1).__hash__(1) == hash(1) |
| True |
| >>> type(int).__hash__(int) == hash(int) |
| True |
| |
| In addition to bypassing any instance attributes in the interest of |
| correctness, implicit special method lookup generally also bypasses the |
| :meth:`__getattribute__` method even of the object's metaclass:: |
| |
| >>> class Meta(type): |
| ... def __getattribute__(*args): |
| ... print "Metaclass getattribute invoked" |
| ... return type.__getattribute__(*args) |
| ... |
| >>> class C(object): |
| ... __metaclass__ = Meta |
| ... def __len__(self): |
| ... return 10 |
| ... def __getattribute__(*args): |
| ... print "Class getattribute invoked" |
| ... return object.__getattribute__(*args) |
| ... |
| >>> c = C() |
| >>> c.__len__() # Explicit lookup via instance |
| Class getattribute invoked |
| 10 |
| >>> type(c).__len__(c) # Explicit lookup via type |
| Metaclass getattribute invoked |
| 10 |
| >>> len(c) # Implicit lookup |
| 10 |
| |
| Bypassing the :meth:`__getattribute__` machinery in this fashion |
| provides significant scope for speed optimisations within the |
| interpreter, at the cost of some flexibility in the handling of |
| special methods (the special method *must* be set on the class |
| object itself in order to be consistently invoked by the interpreter). |
| |
| |
| .. rubric:: Footnotes |
| |
n | .. [#] Since Python 2.2, a gradual merging of types and classes has been started that |
n | .. [#] It *is* possible in some cases to change an object's type, under certain |
| makes this and a few other assertions made in this manual not 100% accurate and |
| controlled conditions. It generally isn't a good idea though, since it can |
| complete: for example, it *is* now possible in some cases to change an object's |
| lead to some very strange behaviour if it is handled incorrectly. |
| 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>`_. |
| |
t | .. [#] This, and other statements, are only roughly true for instances of new-style |
t | .. [#] A descriptor can define any combination of :meth:`__get__`, |
| classes. |
| :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`, |
| then accessing the attribute even on an instance will return the descriptor |
| object itself. If the descriptor defines :meth:`__set__` and/or |
| :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a |
| non-data descriptor. |
| |
| .. [#] 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. |
| |