This section used to document the rules for coercion. As the language
has evolved, the coercion rules have become hard to document
precisely; documenting what one version of one particular
implementation does is undesirable. Instead, here are some informal
guidelines regarding coercion. In Python 3.0, coercion will not be
supported.
If the left operand of a % operator is a string or Unicode object, no
coercion takes place and the string formatting operation is invoked
instead.
It is no longer recommended to define a coercion operation.
Mixed-mode operations on types that don't define coercion pass the
original arguments to the operation.
New-style classes (those derived from object) never invoke the
__coerce__() method in response to a binary operator; the only
time __coerce__() is invoked is when the built-in function
coerce() is called.
For most intents and purposes, an operator that returns
NotImplemented
is treated the same as one that is not
implemented at all.
Below, __op__() and __rop__() are used to signify
the generic method names corresponding to an operator;
__iop__() is used for the corresponding in-place operator. For
example, for the operator `+
', __add__() and
__radd__() are used for the left and right variant of the
binary operator, and __iadd__() for the in-place variant.
For objects x and y, first x.__op__(y)
is tried. If this is not implemented or returns NotImplemented
,
y.__rop__(x)
is tried. If this is also not
implemented or returns NotImplemented
, a TypeError
exception is raised. But see the following exception:
Exception to the previous item: if the left operand is an instance of
a built-in type or a new-style class, and the right operand is an instance
of a proper subclass of that type or class and overrides the base's
__rop__() method, the right operand's __rop__() method
is tried before the left operand's __op__() method.
This is done so that a subclass can completely override binary operators.
Otherwise, the left operand's __op__() method would always
accept the right operand: when an instance of a given class is expected,
an instance of a subclass of that class is always acceptable.
When either operand type defines a coercion, this coercion is called
before that type's __op__() or __rop__() method is
called, but no sooner. If the coercion returns an object of a
different type for the operand whose coercion is invoked, part of the
process is redone using the new object.
When an in-place operator (like `+=
') is used, if the left
operand implements __iop__(), it is invoked without any
coercion. When the operation falls back to __op__() and/or
__rop__(), the normal coercion rules apply.
In x+
y, if x is a sequence that implements
sequence concatenation, sequence concatenation is invoked.
In x*
y, if one operator is a sequence that
implements sequence repetition, and the other is an integer
(int or long), sequence repetition is invoked.
Rich comparisons (implemented by methods __eq__() and so on)
never use coercion. Three-way comparison (implemented by
__cmp__()) does use coercion under the same conditions as
other binary operations use it.
In the current implementation, the built-in numeric types int,
long and float do not use coercion; the type
complex however does use it. The difference can become
apparent when subclassing these types. Over time, the type
complex may be fixed to avoid coercion. All these types
implement a __coerce__() method, for use by the built-in
coerce() function.