A
class may define or inherit special methods (i.e., methods whose
names begin and end with double underscores). Each special method
relates to a specific operation. Python implicitly invokes a special
method whenever you perform the related operation on an instance
object. In most cases, the method's return value is
the operation's result, and attempting an operation
when its related method is not present raises an exception.
Throughout this section, I will point out the cases in which these
general rules do not apply. In the following,
x is the instance of class
C on which you perform the operation, and
y is the other operand, if any. The formal
argument self of each method also refers to
instance object
x.
5.3.1 General-Purpose Special Methods
Some special methods relate to
general-purpose operations. A class that defines or inherits these
methods allows its instances to control such operations. These
operations can be divided into the following categories:
- Initialization and finalization
-
An instance can control its initialization (a frequent need) via
special method _ _init_ _, and/or its finalization
(a rare need) via _ _del_ _.
- Representation as string
-
An instance can control how Python represents it as a string via
special methods _ _repr_ _, _ _str_
_, and _ _unicode_ _.
- Comparison, hashing, and use in a Boolean context
-
An instance can control how it compares with other objects (methods
_ _lt_ _ and _ _cmp_ _), how
dictionaries use it as a key (_ _hash_ _), and
whether it evaluates to true or false in Boolean contexts (_
_nonzero_ _).
- Attribute reference, binding, and unbinding
-
An instance can control access to its attributes (reference, binding,
unbinding) by defining special methods _ _getattribute_
_, _ _getattr_ _, _ _setattr_
_, and _ _delattr_ _.
- Callable instances
-
An instance is callable, just like a function object, if it has the
special method _ _call_ _.
The rest of this section documents the general-purpose special
methods.
_ _call_ _(self[,args...])
|
|
When you call
x([args...]),
Python translates the operation into a call to
x._ _call_
_([args...]).
The formal arguments for the call operation are the same as for the
_ _call_ _ method, minus the first argument. The
first argument, conventionally called self, refers
to x, and Python supplies it implicitly
and automatically, just as in any other call to a bound method.
Any comparison, when its specific special method (_ _lt_
_, _ _gt_ _, etc.) is absent or returns
NotImplemented, calls
x._ _cmp_
_(y) instead,
as do built-in function
cmp(x,y)
and the sort method of list objects. _
_cmp_ _ should return -1 if
x is less than
y, 0 if
x is equal to
y, or 1 if
x is greater than
y. When _ _cmp_ _ is
also absent, order comparisons (<,
<=, >,
>=) raise exceptions. Equality comparisons
(= =, !=), in this case, become
identity checks: x=
=y evaluates
id(x)=
=id(y) (i.e.,
x is
y).
Just before x disappears because of
garbage collection, Python calls
x._ _del_ _( ) to let
x finalize itself. If _ _del_
_ is absent, Python performs no special finalization upon
garbage-collecting x (this is the usual
case, as very few classes need to define _ _del_
_). Python ignores the return value of _ _del_
_. Python performs no implicit call to _ _del_
_ methods of class
C's superclasses.
C._ _del_ _ must
explicitly perform any needed finalization.
For example, when class C has a base class
B to finalize, the code in
C._ _del_ _ must call
B._ _del_ _(self) (or
better, for new-style classes,
super(C,
self)._ _del_ _( )). _ _del_ _
is generally not the best approach when you need timely and
guaranteed finalization. For such needs, use the
try/finally statement covered
in Chapter 6.
At every request to unbind attribute
x.y
(typically, a del statement del
x.y),
Python calls x._ _delattr_
_('y'). All
the considerations discussed for _ _setattr_ _
also apply to _ _delattr_ _. Python ignores the
return value of _ _delattr_ _. If _
_delattr_ _ is absent, Python usually translates
del
x.y
into del x._
_dict_
_['y'].
_ _eq_ _, _ _ge_ _, _ _gt_ _, _ _le_ _, _ _lt_ _, _ _ne_ _ |
|
_ _eq_ _(self,other)
_ _ge_ _(self,other)
_ _gt_ _(self,other)
_ _le_ _(self,other)
_ _lt_ _(self,other)
_ _ne_ _(self,other)
|
|
Comparisons x=
=y,
x>=y, x>y, x<=y, x<y, and
x!=y,
respectively, call the special methods listed here, which should
return False or True (in Python
2.2.1 and later; 0 or 1 in
Python 2.2, 2.1, and earlier). Each method may return
NotImplemented to tell Python to handle the
comparison in alternative ways (e.g., Python may then try
y>x
in lieu of
x<y).
When attribute
x.y
is accessed but not found by the usual procedure (i.e., where
AttributeError would normally be raised), Python
calls x._ _getattr_
_('y')
instead. Python does not call _ _getattr_ _ for
attributes found by normal means (i.e., as keys in
x._ _dict_ _ or via
x._ _class_ _). If you
want Python to call _ _getattr_ _ on every
attribute reference, keep the attributes elsewhere (e.g., in another
dictionary referenced by an attribute with a private name, as shown
earlier in this chapter), or else write a new-style class and
override _ _getattribute_ _ instead. _
_getattr_ _ should raise AttributeError
if it cannot find y.
_ _getattribute_ _
|
Python 2.2 and later |
_ _getattribute_ _(self,name)
|
|
At every request to access attribute
x.y,
if x is an instance of new-style class
C, Python calls
x._ _getattribute_
_('y'), which
must obtain and return the attribute value or else raise
AttributeError. The normal semantics of attribute
access (using x._ _dict_
_, C._ _slots_
_, C's class
attributes, x._ _getattr_
_) are all due to object._ _getattribute_
_.
If class C overrides _
_getattribute_ _, it must implement all of the attribute
access semantics it wants to offer. Most often, the most convenient
way to implement attribute access semantics is by delegating (e.g.,
calling object._ _getattribute_ _(self,
...) as part of the operation of your override of
_ _getattribute_ _). Note that a class that
overrides _ _getattribute_ _ makes attribute
access on instances of the class quite slow, since your overriding
code is called on every such attribute access.
The
hash(x)
built-in function call, and using x as a
dictionary key (typically,
D[x]
where D is a dictionary), call
x._ _hash_ _( ).
_ _hash_ _ must return a 32-bit
int such that
x=
=y implies
hash(x)=
=hash(y), and
must always return the same value for a given object.
When _ _hash_ _ is absent,
hash(x)
and using x as a dictionary key call
id(x)
instead, as long as _ _cmp_ _ and _ _eq_
_ are also absent.
Any x such that
hash(x)
returns a result, rather than raising an exception, is known as a
hashable object. When
_ _hash_ _ is absent, but _ _cmp_
_ or _ _eq_ _ is present,
hash(x)
and using x as a dictionary key raise an
exception. In this case, x is not hashable
and cannot be a dictionary key.
You normally define _ _hash_ _ only for immutable
objects that also define _ _cmp_ _ and/or
_ _eq_ _. Note that, if there exists any
y such that
x=
=y, even if
y is of a different type, and both
x and y are
hashable, you must ensure that
hash(x)=
=hash(y).
_ _init_ _(self[,args...])
|
|
When a call
C([args...])
creates instance x of class
C Python calls
x._ _init_
_([args...])
to let x initialize itself. If _
_init_ _ is absent, you must call class
C without arguments,
C( ), and
x has no instance-specific attributes upon
creation (note that _ _init_ _ is never absent for
a new-style class, since such a class inherits _ _init_
_ from object unless it redefines it).
_ _init_ _ must return None.
Python performs no implicit call to _ _init_ _
methods of class C's
superclasses. C._ _init_
_ must explicitly perform any needed initialization. For
example, when class C has a base class
B to initialize without arguments, the
code in C._ _init_ _
must explicitly call B._ _init_
_(self) (or better, for new-style classes, call
super(C,
self)._ _init_ _( )).
_ _new_ _
|
Python 2.2 and later |
When you call
C([args...])
and C is a new-style class, Python will
obtain the new instance x that you are
creating by invoking C._ _new_
_(C,[args...]).
_ _new_ _ is a static method that every new-style
class has (often simply inheriting it from object)
and it can return any value x. In other
words, _ _new_ _ is not constrained to returning a
new instance of C, although normally it is
expected to do so. If, and only if, the value
x that _ _new_ _
returns is indeed an instance of C
(whether a new or previously existing one), Python continues after
calling _ _new_ _ by implicitly calling _
_init_ _ on x.
When evaluating x as true or false (see Section 4.2.6), for example on a call to
bool(x)
in Python 2.2.1 and later, Python calls
x._ _nonzero_ _( ),
which should return True or
False. When _ _nonzero_ _ is
not present, Python calls _ _len_ _ instead, and
takes x as false when
x._ _len_ _( ) returns
0. When neither _ _nonzero_ _
nor _ _len_ _ is present, Python always takes
x as true.
The
repr(x)
built-in function call, the `x` expression form,
and the interactive interpreter (when x is
the result of an expression statement) call
x._ _repr_ _( ) to
obtain an official, complete string representation of
x. If _ _repr_ _ is
absent, Python uses a default string representation. _
_repr_ _ should return a string with unambiguous
information on x. Ideally, when feasible,
the string should be an expression such that
eval(repr(x))=
=x.
_ _setattr_ _(self, name, value)
|
|
At every request to bind attribute
x.y
(typically, an assignment statement
x.y=value),
Python calls x._ _setattr_
_('y',value).
Python always calls _ _setattr_ _ for any
attribute binding on x; a major difference
from _ _getattr_ _ (_ _setattr_
_ is closer to new-style classes'
_ _getattribute_ _ in this sense). To avoid
recursion, when x._ _setattr_
_ binds x's
attributes, it must modify x._
_dict_ _ directly (e.g., by
x._ _dict_
_[name]=value),
or better, for a new-style class, delegate (e.g., call
super(C, x)._ _setattr_
_('y',value)).
Python ignores the return value of _ _setattr_ _.
If _ _setattr_ _ is absent, Python usually
translates
x.y=z
into x._ _dict_
_['y']=z.
The
str(x)
built-in type and the print
x statement call
x._ _str_ _( ) to
obtain an informal, concise string representation of
x. If _ _str_ _ is
absent, Python calls x._ _repr_
_ instead. _ _str_ _ should return a
conveniently human-readable string, even if it entails some
approximation.
_ _unicode_ _ |
Python 2.2 and later |
The
unicode(x)
built-in type call, in Python 2.2 and later, invokes
x._ _unicode_ _( ), if
present, in preference to x._
_str_ _( ). If a class supplies both special methods
_ _unicode_ _ and _ _str_ _,
the two should return equivalent strings (of Unicode and plain string
type respectively).
5.3.2 Special Methods for Containers
An instance can be a
container (either a sequence or a mapping, but
not both, as they are mutually exclusive concepts). For maximum
usefulness, containers should provide not just special methods
_ _getitem_ _, _ _setitem_ _,
_ _delitem_ _, _ _len_ _,
_ _contains_ _, and _ _iter_ _,
but also a few non-special methods, as discussed in the following
sections.
5.3.2.1 Sequences
In each item access special method, a
sequence that has L items should accept
any integer key, such that
0<=key<L.
For compatibility with built-in sequences, a negative index
key,
0>key>=-L,
should be equivalent to
key+L.
When key has an invalid type, the method
should raise TypeError. When
key is a value of a valid type, but out of
range, the method should raise IndexError. In
Python 2.1, and also in later Python versions for classes that do not
define _ _iter_ _, the for
statement relies on these requirements, as do built-in functions that
take sequences as arguments.
A sequence should also allow concatenation by +
and repetition by *. A sequence should therefore
have special methods _ _add_ _, _ _mul_
_, _ _radd_ _, and _ _rmul_
_, covered in Section 5.3.3 later in this chapter.
Mutable sequences should also have _ _iadd_ _ and
_ _imul_ _, and the non-special methods covered in
Section 4.6.4.3: append,
count, index,
insert, extend,
pop, remove,
reverse, and sort.
5.3.2.2 Mappings
A mapping's item access
special methods should raise KeyError, rather than
IndexError, when they receive an invalid
key argument value of a valid type. A
mapping should define the non-special methods covered in Section 4.7.3: copy,
get, has_key,
items, keys,
values, iteritems,
iterkeys, and itervalues.
Special method _ _iter_ _ should be equivalent to
iterkeys. A mutable mapping should also define
methods clear, popitem,
setdefault, and update.
5.3.2.3 Sets
Sets, scheduled to be introduced in Python
2.3, can be seen as rather peculiar kinds of
containerscontainers that are neither sequences nor mappings,
and cannot be indexed, but do have a length (number of elements) and
are iterable. Unfortunately, the interface of sets (and even the
final decision about introducing them in Python 2.3) is still not
stable as of this writing. Therefore, I do not consider sets in this
book.
5.3.2.4 Container slicing
When you
reference, bind, or unbind a slicing such as
x[i:j]
or
x[i:j:k]
on a container x, Python calls
x's applicable item
access special method, passing as key an
object of a built-in type called a slice object.
A slice object has attributes start,
stop, and step. Each attribute
is None if the corresponding value is omitted in
the slice syntax. For example, del
x[:3] calls
x._ _delitem_
_(y), and
y is a slice object such that
y.stop is
3,
y.start is
None, and
y.step is
None. It is up to container object
x to appropriately interpret the slice
object argument passed to
x's special methods.
Some built-in types, such as list and
tuple, define now-deprecated special methods
_ _getslice_ _, _ _setslice_ _,
and _ _delslice_ _. For an instance
x of such a type, slicing
x with only one colon, as in
x[i:j],
calls a slice-specific special method. Slicing
x with two colons, as in
x[i:j:k],
calls an item access special method with a slice object argument. For
example:
class C:
def _ _getslice_ _(self, i, j): print 'getslice', i, j
def _ _getitem_ _(self, index): print 'getitem', index
x = C( )
x[12:34]
x[56:78:9]
The first slicing calls x._
_getslice_ _(12,34), and the second calls
x._ _getitem_
_(slice(56,78,9)). It's best to avoid
defining the slice-specific special methods in your classes, but you
may need to override them if your class subclasses
list or tuple and you want to
provide special functionality when an instance of your class is
sliced. Note that built-in sequences do not yet support slicing with
two colons up to Python 2.2: this functionality is scheduled to be
introduced in Python 2.3.
5.3.2.5 Container methods
Special methods _ _getitem_ _, _
_setitem_ _, _ _delitem_ _, _
_iter_ _, _ _len_ _, and _
_contains_ _ expose container functionality.
_ _contains_ _(self,item)
|
|
The Boolean test y in
x calls
x._ _contains_
_(y). When
x is a sequence, _ _contains_
_ should return True when
y equals the value of an item in the
sequence. When x is a mapping, _
_contains_ _ should return True when
y equals the value of a key in the
mapping. Otherwise, _ _contains_ _ should return
False. If _ _contains_ _ is
absent, Python performs y
in x as follows, taking
time proportional to
len(x):
for z in x:
if y= =z: return True
return False
For a request to unbind an item or slice of
x (typically del
x[key]),
Python will call x._ _delitem_
_(key). A
container x should have _
_delitem_ _ only if x is
mutable, so that items (and possibly slices) can be removed.
When
x[key]
is accessed (i.e., when container x is
indexed or sliced), Python calls
x._ _getitem_
_(key). All
containers should have _ _getitem_ _.
For a request to loop on all items of x
(typically for item
in x), Python calls
x._ _iter_ _( ) to
obtain an iterator on x. The built-in
function
iter(x)
also calls x._ _iter_ _(
). If _ _iter_ _ is absent and
x is a sequence,
iter(x)
synthesizes and returns an iterator object that wraps
x and returns
x[0],
x[1], and so on, until
one of these item accesses raises IndexError to
indicate the end of the sequence.
The
len(x)
built-in function call, and other built-in functions that need to
know how many items are in container x,
call x._ _len_ _( ).
_ _len_ _ should return an int,
the number of items in x. Python also
calls x._ _len_ _( ) to
evaluate x in a Boolean context, if
_ _nonzero_ _ is absent. Absent _
_nonzero_ _, a container is taken as false if and only if
the container is empty (i.e., the container's length
is 0).
_ _setitem_ _(self,key,value)
|
|
For a request to bind an item or slice of
x (typically an assignment
x[key]=value),
Python calls x._ _setitem_
_(key,value).
A container x should have _
_setitem_ _ only if x is
mutable, so that items, and possibly slices, can be added and/or
rebound.
5.3.3 Special Methods for Numeric Objects
An instance may support numeric operations
by means of many special methods. Some classes that are not numbers
also support some of the following special methods, in order to
overload operators such as + and
*. For example, sequences should have special
methods _ _add_ _, _ _mul_ _,
_ _radd_ _, and _ _rmul_ _, as
mentioned earlier in this chapter.
_ _abs_ _, _ _invert_ _, _ _neg_ _, _ _pos_ _ |
|
_ _abs_ _(self)
_ _invert_ _(self)
_ _neg_ _(self)
_ _pos_ _(self)
|
|
Unary operators
abs(x),
~x,
-x, and
+x, respectively, call
these methods.
_ _add_ _, _ _div_ _, _ _floordiv_ _, _ _mod_ _, _ _mul_ _, _ _sub_ _,_ _truediv_ _ |
|
_ _add_ _(self,other)
_ _div_ _(self,other)
_ _floordiv_ _(self,other)
_ _mod_ _(self,other)
_ _mul_ _(self,other)
_ _sub_ _(self,other)
_ _truediv_ _(self,other)
|
|
Operators
x+y,
x/y,
x//y,
x%y,
x*y,
x-y,
and x/y,
respectively, call these methods. The operator /
calls _ _truediv_ _, if present, instead of
_ _div_ _, in the situations where division is
non-truncating, as covered in Section 4.5.2.
_ _and_ _, _ _lshift_ _, _ _or_ _, _ _rshift_ _, _ _xor_ _ |
|
_ _and_ _(self,other)
_ _lshift_ _(self,other)
_ _or_ _(self,other)
_ _rshift_ _(self,other)
_ _xor_ _(self,other)
|
|
Operators
x&y,
x<<y,
x|y,
x>>y,
and
x^y,
respectively, call these methods.
For any numeric operation with two operands
x and y, Python
invokes x._ _coerce_
_(y).
_ _coerce_ _ should return a pair with
x and y
converted to acceptable types. _ _coerce_ _
returns None when it cannot perform the
conversion. In such cases, Python will call
y._ _coerce_
_(x). This
special method is now deprecated: new Python classes should not
implement it, but instead deal with whatever types they can accept
directly in the special methods of the relevant numeric operations.
However, if a class does supply _ _coerce_ _,
Python still calls it for backward compatibility.
_ _complex_ _, _ _float_ _, _ _int_ _, _ _long_ _ |
|
_ _complex_ _(self)
_ _float_ _(self)
_ _int_ _(self)
_ _long_ _(self)
|
|
Built-in types
complex(x),
float(x),
int(x),
and
long(x),
respectively, call these methods.
Built-in function
divmod(x,y)
calls x._ _divmod_
_(y).
_ _divmod_ _ should return a pair
(quotient,remainder)
equal to
(x//y,x%y).
_ _hex_ _(self)
_ _oct_ _(self)
|
|
Built-in function
hex(x)
calls x._ _hex_ _( ).
Built-in function
oct(x)
calls x._ _oct_ _( ).
Each of these special methods should return a string representing the
value of x, in base 16 and 8 respectively.
_ _iadd_ _, _ _idiv_ _, _ _ifloordiv_ _, _ _imod_ _, _ _imul_ _, _ _isub_ _, _ _itruediv_ _ |
|
_ _iadd_ _(self,other)
_ _idiv_ _(self,other)
_ _ifloordiv_ _(self,other)
_ _imod_ _(self,other)
_ _imul_ _(self,other)
_ _isub_ _(self,other)
_ _itruediv_ _(self,other)
|
|
The augmented assignments
x+=y,
x/=y,
x//=y,
x%=y,
x*=y,
x-=y,
and
x/=y,
respectively, call these methods. Each method should modify
x in-place and return
self. Define these methods when
x is mutable (i.e.,
when x can change in-place).
_ _iand_ _, _ _ilshift_ _, _ _ior_ _, _ _irshift_ _, _ _ixor_ _ |
|
_ _iand_ _(self,other)
_ _ilshift_ _(self,other)
_ _ior_ _(self,other)
_ _irshift_ _(self,other)
_ _ixor_ _(self,other)
|
|
Augmented assignments
x&=y,
x<<=y,
x|=y,
x>>=y,
and
x^=y,
respectively, call these methods. Each method should modify
x in-place and return
self.
Augmented assignment
x**=y
calls x._ _ipow_
_(y).
_ _ipow_ _ should modify
x in-place and return
self.
_ _pow_ _(self,other[,modulo])
|
|
x**y
and
pow(x,y)
both call x._ _pow_
_(y), while
pow(x,y,z)
calls x._ _pow_
_(y,z).
x._ _pow_
_(y,z)
should return a value equal to the expression
x._ _pow_
_(y)%z.
_ _radd_ _, _ _rdiv_ _, _ _rmod_ _, _ _rmul_ _, _ _rsub_ _ |
|
_ _radd_ _(self,other)
_ _rdiv_ _(self,other)
_ _rmod_ _(self,other)
_ _rmul_ _(self,other)
_ _rsub_ _(self,other)
|
|
Operators
y+x,
y/x,
y%x,
y*x,
and
y-x,
respectively, call these methods when y
doesn't have a needed method _ _add_
_, _ _div_ _, and so on.
_ _rand_ _, _ _rlshift_ _, _ _ror_ _, _ _rrshift_ _, _ _rxor_ _ |
|
_ _rand_ _(self,other)
_ _rlshift_ _(self,other)
_ _ror_ _(self,other)
_ _rrshift_ _(self,other)
_ _rxor_ _(self,other)
|
|
Operators
y&x,
y<<x,
y|x,
y>>x,
and
y^x,
respectively, call these methods when y
doesn't have needed method _ _and_
_, _ _lshift_ _, and so on.
_ _rdivmod_ _(self,other)
|
|
Built-in function
divmod(y,x)
calls x._ _rdivmod_
_(y) when
y doesn't have _
_divmod_ _. _ _rdivmod_ _ should return
a pair
(remainder,quotient).
y**x
and
pow(y,x)
call x._ _rpow_
_(y), when
y doesn't have _
_pow_ _. There is no three-argument form in this
case.