Python 1.5 Reference Manual
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 'is' operator compares the identity of two objects; the 'id()' function returns an integer representing its identity (currently implemented as its address). An object's type is also unchangeable. It determines the operations that an object supports (e.g. "does it have a length?") and also defines the possible values for objects of that type. The 'type()' function returns an object's type (which is an object itself). The value of some objects can change. The '==' operator compares the value of two objects. Objects whose value can change are said to be mutable; objects whose value is unchangeable once they are created are called immutable. An object's (im)mutability is determined by its type; for instance, numbers, strings and tuples are immutable, while dictionaries and lists are mutable.
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 which collects most objects as soon as they become unreachable, but never collects garbage containing circular references.)
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 'try...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 close() method. Programs are strongly recommended to always explicitly close such objects. The 'try...finally' statement provides a convenient way to do this.
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 (im)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.)
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. There are also some 'generic' special attributes, not listed with the individual objects: __methods__ is a list of the method names of a built-in object, if it has any; __members__ is a list of the data attribute names of a built-in object, if it has any.
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.
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 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 and floating point numbers:
Integers These represent elements from the mathematical set of whole numbers
There are two types of integers:
Plain integers 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 falls outside this range, the exception OverflowError is raised. 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 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.
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. For any operation except left shift, if it yields a result in the plain integer domain without causing overflow, it will yield the same result in the long integer domain or when using mixed operands.
Floating point numbers These represent machine-level double precision floating point numbers. You are at the mercy of the underlying machine architecture and C implementation for the accepted range and handling of overflow. Python does not support single-precision floating point numbers; the savings in CPU 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 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 value of a complex number z can be retrieved through the attributes z.real and z.imag.
Sequences These represent finite ordered sets indexed by natural numbers. The built-in function 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. Item i of sequence a is selected by a[i].
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 again.
Sequences are distinguished according to their mutability:
Immutable sequences 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 array of objects directly referenced by an immutable object cannot change.)
The following types are immutable sequences:
Strings 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 chr() and 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.
(What should be done on systems whose native character set is not ASCII???)
Tuples 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 enclosing 'nothing' in parentheses: ''()''.
Mutable sequences Mutable sequences can be changed after they are created. The subscription and slicing notations can be used as the target of assignment and del (delete) statements.
There is currently a single mutable sequence type:
Lists 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.)
The optional module array provides an additional example of a mutable sequence type.
Mappings 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 del statements. The built-in function len() returns the number of items in a mapping.
There is currently a single intrinsic mapping type:
Dictionaries 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 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 are created by the {...} notation. (See "Dictionary displays" on page 28.)
The optional library modules dbm, gdbm and bsddb provide additional examples of mapping types.
Callable types These are the types to which the function call operation (for invocation, See "Calls" on page 31.) is applied:
User-defined functions A user-defined function object is created by a function definition. (See "Function definitions" on page 50.)
Special read-only attributes: func_doc or __doc__ is the function's documentation string, or None if unavailable; func_name or __name__ is the function's name; func_defaults is a tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value; func_code is the code object representing the compiled function body; func_globals is (a reference to) the dictionary that holds the function's global variables -- it defines the global name space of the module in which the function was defined. Additional information about a function's definition can be retrieved from its code object; see the description of internal types below.
User-defined methods A user-defined method object (a.k.a. object closure) combines a class, a class instance (or None) and a user-defined function.
Special read-only attributes: im_self is the instance object; im_func is the function object; im_class is the class that defined the method (which may be a base class of the class of which im_self is an instance); __doc__ is the method's documentation (same as im_func.__doc__); __name__ is the method name (same as im_func.__name__).
User-defined method objects are created in two ways: when getting an attribute of a class that is a user-defined function object, or when getting an attributes of a class instance that is a user-defined function object. In the former case (class attribute), the im_self attribute is None, and the method object is said to be unbound; in the latter case (instance attribute), im_self is the instance, and the method object is said to be bound. For instance, when C is a class which contains a definition for a function f, C.f does not yield the function object f; rather, it yields an unbound method object m where m.im_class is C, m.im_function is f, and m.im_self is None. When x is a C instance, x.f yields a bound method object m where m.im_class is C, m.im_function is f, and m.im_self is x.
When an unbound user-defined method object is called, the underlying function (im_func) is called, with the restriction that the first argument must be an instance of the proper class (im_class) or of a derived class thereof.
When a bound user-defined method object is called, the underlying function (im_func) is called, inserting the class instance (im_self) in front of the argument list. For instance, when C is a class which contains a definition for a function f, and x is an instance of C, calling x.f(1) is equivalent to calling C.f(x, 1).
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.
Built-in functions A built-in function object is a wrapper around a C function. Examples of built-in functions are len and math.sin (math is a standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes: __doc__ is the function's documentation string, or None if unavailable; __name__ is the function's name; __self__ is set to None (but see the next paragraph).
Built-in methods 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 list.append, assuming list is a list object. In this case, the special read-only attribute __self__ is set to the object denoted by list.
Classes 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 __init__ method if it has one. Any arguments are passed on to the __init__ method -- if there is no __init__ method, the class must be called without arguments.
Class instances Class instances are described below. Class instances can be called as a function only when the class has a __call__ method; in this case, x(arguments) is a shorthand for x.__call__(arguments).
Modules Modules are imported by the import statement. (See "The import statement" on page 43.) A module object has a name space 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 update the module's name space dictionary, e.g. ''m.x = 1'' is equivalent to ''m.__dict__["x"] = 1''.
Special read-only attribute: __dict__ is the dictionary object that is the module's name space.
Predefined (writable) attributes: __name__ is the module name; __doc__ is the module's documentation string, or None if unavailable; __file__ is the pathname of the file from which the module was loaded, if it was loaded from a file. The __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 "Class definitions" on page 51.). A class has a name space 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 their occurrence in the base class list. When a class attribute reference would yield a user-defined function object, it is transformed into an unbound user-defined method object (see above). The im_class attribute of this method object is the class in which the function object was found, not necessarily the class for which the attribute reference was initiated.
Class attribute assignments update the class's dictionary, never the dictionary of a base class.
A class object can be called as a function (see above) to yield a class instance (see below).
Special read-only attributes: __dict__ is the dictionary that is the class's name space; __name__ is the class name; __bases__ is a tuple (possibly empty or a singleton) containing the base classes, in the order of their occurrence in the base class list.
Predefined (writable) attribute: __doc__ is the class's documentation string, or None if undefined.
Class instances A class instance is created by calling a class object as a function (see above). A class instance has a name space implemented as a dictionary, which is the first place where instance attributes are searched. When an attribute is not found there, the search continues with the class attributes. If a class attribute is found that is a user-defined function object (and in no other case), it is transformed into an unbound user-defined method object (see above). The im_class attribute of this method object is the class in which the function object was found, not necessarily the class of the instance for which the attribute reference was initiated. If no class attribute is found, and the object's class has a __getattr__ method, that is called to satisfy the lookup.
Attribute assignments and deletions update the instance's dictionary, never a class's dictionary. If the class has a __setattr__ or __delattr__ method, this is called instead of updating the instance dictionary directly.
Class instances can pretend to be numbers, sequences, mappings, or callable objects, and override various other special operations, if they have methods with certain special names. See "Special method names" on page 18.
Special attributes: __dict__ yields the attribute dictionary; __class__ yields the instance's class. In some implementations these may be assigned a new value; the new value must have the same type as the old value.
Files A file object represents an open file. File objects are created by the open() built-in function, and also by os.popen(), os.fdopen() and the 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 the Python Library Reference for complete documentation of file objects.
Internal types 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 Code objects represent byte-compile 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 name space dictionary of 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: co_argcount is the number of positional arguments (including arguments with default values); co_nlocals is the number of local variables used by the function (including arguments); co_varnames is a tuple containing the names of the local variables (starting with the argument names); co_code is a string representing the sequence of bytecode instructions; co_consts is a tuple containing the literals used by the bytecode; co_names is a tuple containing the names used by the bytecode; co_filename is the filename from which the code was compiled; co_flags is an integer encoding a number of flags for the interpreter. The following flag bits are defined: bit 2 is set if the function uses the "*arguments'' syntax to accept an arbitrary number of positional arguments; bit 3 is set if the function uses the ''**keywords'' syntax to accept arbitrary keyword arguments; other bits are used internally or reserved for future use. The first item in co_consts is the documentation string of the function, or None if undefined. To find out the first line number of a function, you have to disassemble the bytecode instructions; the standard library module codehack defines a function getlineno() that returns the first line number of a code object.
Frame objects Frame objects represent execution frames. They may occur in traceback objects (see below).
Special read-only attributes: f_back is to the previous stack frame (towards the caller), or None if this is the bottom stack frame; f_code is the code object being executed in this frame; f_locals is the dictionary used to look up locals variables; f_globals is used for global variables; f_builtins is used for built-in (intrinsic) names; f_restricted is a flag indicating whether the function is executing in restricted execution mode; f_lineno gives the current line number and f_lasti gives the precise instruction (this is an index into the instruction string of the code object).
Special writable attributes: f_trace, if not None, is a function called at the start of each source code line (this is used by the debugger).
Traceback objects 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 "The try statement" on page 49.) 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 exception handler, the stack trace is printed on the standard error stream; if the interpreter is interactive, it is also made available to the user as sys.last_traceback.
Special read-only attributes: 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; tb_frame points to the execution frame of the current level; tb_lineno gives the line number where the exception occurred; 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 try statement with no matching except clause or with a finally clause.
Slice objects 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 slice() function.
Special read-only attributes: start is the lowerbound; stop is the upperbound; step is the step value; each is None if omitted. These attributes can have any type.
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. For instance, if a class defines a method named __getitem__, and x is an instance of this class, then x[i] is equivalent to x.__getitem__(i). (The reverse is not true; e.g. if x is a list object, x.__getitem__(i) is not equivalent to x[i].) Except where mentioned, attempts to execute an operation raise an exception when no appropriate method is defined.
__init__ method the derived class's __init__ method must explicitly call it to ensure proper initialization of the base class part of the instance, e.g.BaseClass.__init__(self, [args...])''.
__del__(self) Called when the instance is about to be destroyed. If a base class has a __del__ method the derived class's __del__ method must explicitly call it to ensure proper deletion of the base class part of the instance. e.g. ''BaseClass.__del__(self)''. Note that it is possible (though not recommended!) for the __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 __del__ methods are called for objects that still exist when the interpreter exits.
Programmer's 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 its reference count reaches zero. Some common situations that may prevent the reference count of an object to go 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.
Warning: due to the precarious circumstances under which __del__ methods are invoked, exceptions that occur during their execution are ignored, and a warning is printed to sys.stderr instead. Also, when __del__ is invoked is response to a module being deleted (e.g. when execution of the program is done), other globals referenced by the __del__ method may already have been deleted. For this reason, __del__ methods should do the absolute minimum needed to maintain external invariants. Python 1.5 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 __del__ method is called.
__repr__(self) Called by the repr() built-in function and by string conversions (reverse quotes) to compute the "official" string representation of an object. This should normally look like a valid Python expression that can be used to recreate an object with the same value.
__str__(self) Called by the str() built-in function and by the print statement compute the ''informal'' string representation of an object. This differs from __repr__ in that it doesn't have to look like a valid Python expression: a more convenient or concise representation may be used instead.
__cmp__(self, other) Called by all comparison operations. Should return a negative integer if self < other, zero if self == other, a positive integer if self > other. If no __cmp__ method is defined, class instances are compared by object identity ("address"). (Note: the restriction that exceptions are not propagated by __cmp__ has been removed in Python 1.5)
__hash__(self) Called for the key object for dictionary operations, and by the built-in function 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 no __hash__ method is defined, class instances are hashed by object identity (''address''). If a class does not define a __cmp__ method it should not define a __hash__ method either; if it defines __cmp__ but not __hash__ its instances will not be usable as dictionary keys. If a class defines mutable objects and implements a __cmp__ method it should not implement __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).
__nonzero__(self) Called to implement truth value testing; should return 0 or 1. When this method is not defined, __len__ is called, if it is defined (see below). If a class defines neither __len__ nor __nonzero__, all its instances are considered true.
x.name) for class instances. For performance reasons, these methods are cached in the class object at class definition time; therefore, they cannot be changed after the class definition is executed.
__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 AttributeError exception.
Note that if the attribute is found through the normal mechanism, __getattr__ is not called. (This is an intentional asymmetry between __getattr__ and __setattr__.) This is done both for efficiency reasons and because otherwise __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).
__setattr__(self, name, value) Called whenever an attribute assignment is attempted. This is called instead of the normal mechanism (i.e. instead of storing the value in the instance dictionary). name is the attribute name, value is the value to be assigned to it.
If __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''.
__delattr__(self, name) Like __setattr__ but for attribute deletion instead of assignment.
x(arg1, arg2, ...) is a shorthand for x.__call__(arg1, arg2, ...).<= k < N where N is the length of the sequence, and the method __getslice__ (see below) should be defined. It is also recommended that mappings provide methods keys, values and items behaving similar to those for Python's standard dictionary objects; mutable sequences should provide methods append, count, index, insert, sort, remove and reverse like Python standard list objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods __add__, __radd__, __mul__ and __rmul__ described below; they should not define __coerce__ or other numerical operators.
__len__(self) Called to implement the built-in function len(). Should return the length of the object, an integer >= 0. Also, an object that doesn't define a __nonzero__() method and whose __len__() method returns zero is considered to be false in a Boolean context.
__getitem__(self, key) Called to implement evaluation of self[key]. Note that the special interpretation of negative keys (if the class wishes to emulate a sequence type) is up to the __getitem__ method.
__setitem__(self, key, value) Called to implement assignment to self[key]. Same note as for __getitem__.
__delitem__(self, key) Called to implement deletion of self[key]. Same note as for __getitem__.
__getslice__ should be defined; for mutable sequences, all three methods should be defined.
__getslice__(self, i, j) 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 0 or len(self), respectively, and len(self) has been added (once) to originally negative i or j by the time this function is called (unlike for __getitem__).
__setslice__(self, i, j, sequence) Called to implement assignment to self[i:j]. The sequence argument can have any type. The return value should be None. Same notes for i and j as for __getslice__.
__delslice__(self, i, j) Called to implement deletion of self[i:j]. Same notes for i and j as for __getslice__.
Notice that these methods are only invoked when a single slice with a single colon is used. For slice operations involving extended slice notation, __getitem__, __setitem__ or __delitem__ is called.
__or__(self, right)These functions are called to implement the binary arithmetic operations (+, -, *, /, %, divmod(), pow(), <<, >>, &, ^, |). For instance: to evaluate the expression x+y, where x is an instance of a class that has an __add__ method, x.__add__(y) is called.
__ror__(self, left) These functions are called to implement the binary arithmetic operations (+, -, *, /, %, divmod(), pow(), <<, >>, &, ^, |) with reversed operands. These functions are only called if the left operand does not support the corresponding operation (possibly after coercion). For instance: to evaluate the expression x+y, where x is an instance of a class that does not have an __add__ method, y.__radd(x) is called. If the class defines a __coerce__ method that coerces its arguments to a common type, these methods will never be called and thus needn't be defined. They are useful for classes that implement semi-numerical data types (types that have some numerical behavior but don't adhere to all invariants usually assumed about numbers).
__invert__(self) Called to implement the unary arithmetic operations (-, +, abs() and ~).
__float__(self) Called to implement the built-in functions int(), long() and float(). Should return a value of the appropriate type.
__hex__(self) Called to implement the built-in functions oct() and hex(). Should return a string value.
__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 no conversion is possible. 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).
Coercion rules: to evaluate x op y, the following steps are taken (where __op__ and __rop__ are the method names corresponding to op, e.g. if op is '+', __add__ and __radd__ are used). If an exception occurs at any point, the evaluation is abandoned and exception handling takes over.
0. If x is a string object and op is the modulo operator (%), the string formatting operation (see [Ref:XXX]) is invoked and the remaining steps are skipped.
1. If x is a class instance:
1a. If x has a __coerce__ method: replace x and y with the 2-tuple returned by x.__coerce__(y); skip to step 2 if the coercion returns None.
1b. If neither x nor y is a class instance after coercion, go to step 3.
1c. If x has a method __op__, return x.__op__(y); otherwise, restore x and y to their value before step 1a.
2. If y is a class instance:
2a. If y has a __coerce__ method: replace y and x with the 2-tuple returned by y.__coerce__(x); skip to step 3 if the coercion returns None.
2b. If neither x nor y is a class instance after coercion, go to step 3.
2b. If y has a method __rop__, return y.__rop__(x); otherwise, restore x and y to their value before step 2a.
3. We only get here if neither x nor y is a class instance.
3a. If op is '+' and x is a sequence, sequence concatenation is invoked.
3b. If op is '*' and one operand is a sequence and the other an integer, sequence repetition is invoked.
3c. Otherwise, both operands must be numbers; they are coerced to a common type if possible, and the numeric operation is invoked for that type.
Generated with Harlequin WebMaker