3.3.8 Coercion rules
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, 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.
|
