Info Node: (python2.1-ref.info)Basic customization
(python2.1-ref.info)Basic customization
Basic customization
-------------------
`__init__(self[, args...])'
Called when the instance is created. The arguments are those
passed to the class constructor expression. If a base class has an
`__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. This is also
called a destructor . 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.
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. If at all possible, this should look
like a valid Python expression that could be used to recreate an
object with the same value (given an appropriate environment). If
this is not possible, a string of the form `<...SOME USEFUL
DESCRIPTION...>' should be returned. The return value must be a
string object.
This is typically used for debugging, so it is important that the
representation is information-rich and unambiguous.
`__str__(self)'
Called by the `str()' built-in function and by the `print'
statement to compute the "informal" string representation of an
object. This differs from `__repr__()' in that it does not have
to be a valid Python expression: a more convenient or concise
representation may be used instead. The return value must be a
string object.
`__lt__(self, other)'
`__le__(self, other)'
`__eq__(self, other)'
`__ne__(self, other)'
`__gt__(self, other)'
`__ge__(self, other)'
_Added in Python version 2.1_ These are the so-called "rich
comparison" methods, and are called for comparison operators in
preference to `__cmp__()' below. The correspondence between
operator symbols and method names is as follows: `X<Y' calls
`X.__lt__(Y)', `X<=Y' calls `X.__le__(Y)', `X==Y' calls
`X.__eq__(Y)', `X!=Y' and `X<>Y' call `X.__ne__(Y)', `X>Y' calls
`X.__gt__(Y)', and `X>=Y' calls `X.__ge__(Y)'. These methods can
return any value, but if the comparison operator is used in a
Boolean context, the return value should be interpretable as a
Boolean value, else a `TypeError' will be raised. By convention,
`0' is used for false and `1' for true.
There are no reflected (swapped-argument) versions of these methods
(to be used when the left argument does not support the operation
but the right argument does); rather, `__lt__()' and `__gt__()'
are each other's reflection, `__le__()' and `__ge__()' are each
other's reflection, and `__eq__()' and `__ne__()' are their own
reflection.
Arguments to rich comparison methods are never coerced. A rich
comparison method may return `NotImplemented' if it does not
implement the operation for a given pair of arguments.
`__cmp__(self, other)'
Called by comparison operations if rich comparison (see above) is
not defined. Should return a negative integer if `self < other',
zero if `self == other', a positive integer if `self > other'. If
no `__cmp__()', `__eq__()' or `__ne__()' operation is defined,
class instances are compared by object identity ("address"). See
also the description of `__hash__()' for some important notes on
creating objects which support custom comparison operations and
are usable as dictionary keys. (Note: the restriction that
exceptions are not propagated by `__cmp__()' has been removed in
Python 1.5.)
`__rcmp__(self, other)'
_Changed in Python version 2.1_
`__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 a class
does not define a `__cmp__()' method it should not define a
`__hash__()' operation either; if it defines `__cmp__()' or
`__eq__()' but not `__hash__()', its instances will not be usable
as dictionary keys. If a class defines mutable objects and
implements a `__cmp__()' or `__eq__()' 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.