<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"ref.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"ref.html" title='Python Reference Manual'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"numeric-types.html" />
<link rel=
"parent" href=
"specialnames.html" />
<link rel=
"next" href=
"execmodel.html" />
<meta name='aesop' content='information'
/>
<title>3.3.8 Coercion rules
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"3.3.7 Emulating numeric types"
href=
"numeric-types.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"3.3 Special method names"
href=
"specialnames.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"4. Execution model"
href=
"execmodel.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"numeric-types.html">3.3.7 Emulating numeric types
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"specialnames.html">3.3 Special method names
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"execmodel.html">4. Execution model
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION005380000000000000000"></A><A NAME=
"coercion-rules"></A>
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
If the left operand of a % operator is a string or Unicode object, no
coercion takes place and the string formatting operation is invoked
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
<tt class=
"class">object
</tt>) never invoke the
<tt class=
"method">__coerce__()
</tt> method in response to a binary operator; the only
time
<tt class=
"method">__coerce__()
</tt> is invoked is when the built-in function
<tt class=
"function">coerce()
</tt> is called.
For most intents and purposes, an operator that returns
<code>NotImplemented
</code> is treated the same as one that is not
Below,
<tt class=
"method">__op__()
</tt> and
<tt class=
"method">__rop__()
</tt> are used to signify
the generic method names corresponding to an operator;
<tt class=
"method">__iop__()
</tt> is used for the corresponding in-place operator. For
example, for the operator `
<code>+
</code>',
<tt class=
"method">__add__()
</tt> and
<tt class=
"method">__radd__()
</tt> are used for the left and right variant of the
binary operator, and
<tt class=
"method">__iadd__()
</tt> for the in-place variant.
For objects
<var>x
</var> and
<var>y
</var>, first
<code><var>x
</var>.__op__(
<var>y
</var>)
</code>
is tried. If this is not implemented or returns
<code>NotImplemented
</code>,
<code><var>y
</var>.__rop__(
<var>x
</var>)
</code> is tried. If this is also not
implemented or returns
<code>NotImplemented
</code>, a
<tt class=
"exception">TypeError
</tt>
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
<tt class=
"method">__rop__()
</tt> method is tried
<em>before
</em> the left
operand's
<tt class=
"method">__op__()
</tt> 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
When either operand type defines a coercion, this coercion is called
before that type's
<tt class=
"method">__op__()
</tt> or
<tt class=
"method">__rop__()
</tt> 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 `
<code>+=
</code>') is used, if the left
operand implements
<tt class=
"method">__iop__()
</tt>, it is invoked without any
coercion. When the operation falls back to
<tt class=
"method">__op__()
</tt> and/or
<tt class=
"method">__rop__()
</tt>, the normal coercion rules apply.
In
<var>x
</var><code>+
</code><var>y
</var>, if
<var>x
</var> is a sequence that implements
sequence concatenation, sequence concatenation is invoked.
In
<var>x
</var><code>*
</code><var>y
</var>, if one operator is a sequence that
implements sequence repetition, and the other is an integer
(
<tt class=
"class">int
</tt> or
<tt class=
"class">long
</tt>), sequence repetition is invoked.
Rich comparisons (implemented by methods
<tt class=
"method">__eq__()
</tt> and so on)
never use coercion. Three-way comparison (implemented by
<tt class=
"method">__cmp__()
</tt>) does use coercion under the same conditions as
other binary operations use it.
In the current implementation, the built-in numeric types
<tt class=
"class">int
</tt>,
<tt class=
"class">long
</tt> and
<tt class=
"class">float
</tt> do not use coercion; the type
<tt class=
"class">complex
</tt> however does use it. The difference can become
apparent when subclassing these types. Over time, the type
<tt class=
"class">complex
</tt> may be fixed to avoid coercion. All these types
implement a
<tt class=
"method">__coerce__()
</tt> method, for use by the built-in
<tt class=
"function">coerce()
</tt> function.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"3.3.7 Emulating numeric types"
href=
"numeric-types.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"3.3 Special method names"
href=
"specialnames.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"4. Execution model"
href=
"execmodel.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"numeric-types.html">3.3.7 Emulating numeric types
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"specialnames.html">3.3 Special method names
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"execmodel.html">4. Execution model
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.