should be raised for improper \var{key} values as for the
\method{__getitem__()} method.
\end{methoddesc}


\subsection{Additional methods for emulation of sequence types
  \label{sequence-methods}}

The following methods can be defined to further emulate sequence
objects.  Immutable sequences methods should only define
\method{__getslice__()}; mutable sequences, should define all three
three methods.

\begin{methoddesc}[sequence object]{__getslice__}{self, i, j}
\deprecated{2.0}{Support slice objects as parameters to the
\method{__getitem__()} method.}
Called to implement evaluation of \code{\var{self}[\var{i}:\var{j}]}.
The returned object should be of the same type as \var{self}.  Note
that missing \var{i} or \var{j} in the slice expression are replaced
by zero or \code{sys.maxint}, respectively.  If negative indexes are
used in the slice, the length of the sequence is added to that index.
If the instance does not implement the \method{__len__()} method, an
\exception{AttributeError} is raised.
No guarantee is made that indexes adjusted this way are not still
negative.  Indexes which are greater than the length of the sequence
are not modified.
If no \method{__getslice__()} is found, a slice
object is created instead, and passed to \method{__getitem__()} instead.
\end{methoddesc}

\begin{methoddesc}[sequence object]{__setslice__}{self, i, j, sequence}
Called to implement assignment to \code{\var{self}[\var{i}:\var{j}]}.
Same notes for \var{i} and \var{j} as for \method{__getslice__()}.

This method is deprecated. If no \method{__setslice__()} is found, a slice
object is created instead, and passed to \method{__setitem__()} instead.
\end{methoddesc}

\begin{methoddesc}[sequence object]{__delslice__}{self, i, j}
Called to implement deletion of \code{\var{self}[\var{i}:\var{j}]}.
Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
This method is deprecated. If no \method{__delslice__()} is found, a slice
object is created instead, and passed to \method{__delitem__()} instead.
\end{methoddesc}

Notice that these methods are only invoked when a single slice with a single
colon is used, and the slice method is available.  For slice operations
involving extended slice notation, or in absence of the slice methods,
\method{__getitem__()}, \method{__setitem__()} or \method{__delitem__()} is
called with a slice object as argument.


\subsection{Emulating numeric types\label{numeric-types}}

The following methods can be defined to emulate numeric objects.
Methods corresponding to operations that are not supported by the
particular kind of number implemented (e.g., bitwise operations for
non-integral numbers) should be left undefined.

\begin{methoddesc}[numeric object]{__add__}{self, other}
\methodline[numeric object]{__sub__}{self, other}
\methodline[numeric object]{__mul__}{self, other}
\methodline[numeric object]{__div__}{self, other}
\methodline[numeric object]{__mod__}{self, other}
\methodline[numeric object]{__divmod__}{self, other}
\methodline[numeric object]{__pow__}{self, other\optional{, modulo}}
\methodline[numeric object]{__lshift__}{self, other}
\methodline[numeric object]{__rshift__}{self, other}
\methodline[numeric object]{__and__}{self, other}
\methodline[numeric object]{__xor__}{self, other}
\methodline[numeric object]{__or__}{self, other}
These functions are
called to implement the binary arithmetic operations (\code{+},
\code{-}, \code{*}, \code{/}, \code{\%},
\function{divmod()}\bifuncindex{divmod},
\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>},
\code{\&}, \code{\^}, \code{|}).  For instance, to evaluate the
expression \var{x}\code{+}\var{y}, where \var{x} is an instance of a
class that has an \method{__add__()} method,
\code{\var{x}.__add__(\var{y})} is called.  Note that
\method{__pow__()} should be defined to accept an optional third
argument if the ternary version of the built-in
\function{pow()}\bifuncindex{pow} function is to be supported.
\end{methoddesc}

\begin{methoddesc}[numeric object]{__radd__}{self, other}
\methodline[numeric object]{__rsub__}{self, other}
\methodline[numeric object]{__rmul__}{self, other}
\methodline[numeric object]{__rdiv__}{self, other}
\methodline[numeric object]{__rmod__}{self, other}
\methodline[numeric object]{__rdivmod__}{self, other}
\methodline[numeric object]{__rpow__}{self, other}
\methodline[numeric object]{__rlshift__}{self, other}
\methodline[numeric object]{__rrshift__}{self, other}
\methodline[numeric object]{__rand__}{self, other}
\methodline[numeric object]{__rxor__}{self, other}
\methodline[numeric object]{__ror__}{self, other}
These functions are
called to implement the binary arithmetic operations (\code{+},
\code{-}, \code{*}, \code{/}, \code{\%},
\function{divmod()}\bifuncindex{divmod},
\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>},
\code{\&}, \code{\^}, \code{|}) with reversed operands.  These
functions are only called if the left operand does not support the
corresponding operation.  For instance, to evaluate the expression
\var{x}\code{-}\var{y}, where \var{y} is an instance of a class that
has an \method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})} is
called.  Note that ternary \function{pow()}\bifuncindex{pow} will not
try calling \method{__rpow__()} (the coercion rules would become too
complicated).
\end{methoddesc}

\begin{methoddesc}[numeric object]{__neg__}{self}
\methodline[numeric object]{__pos__}{self}
\methodline[numeric object]{__abs__}{self}
\methodline[numeric object]{__invert__}{self}
Called to implement the unary arithmetic operations (\code{-}, \code{+},
\function{abs()}\bifuncindex{abs} and \code{\~{}}).
\end{methoddesc}

\begin{methoddesc}[numeric object]{__complex__}{self}
\methodline[numeric object]{__int__}{self}
\methodline[numeric object]{__long__}{self}
\methodline[numeric object]{__float__}{self}
Called to implement the built-in functions
\function{complex()}\bifuncindex{complex},
\function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long},
and \function{float()}\bifuncindex{float}.  Should return a value of
the appropriate type.
\end{methoddesc}

\begin{methoddesc}[numeric object]{__oct__}{self}
\methodline[numeric object]{__hex__}{self}
Called to implement the built-in functions
\function{oct()}\bifuncindex{oct} and
\function{hex()}\bifuncindex{hex}.  Should return a string value.
\end{methoddesc}

\begin{methoddesc}[numeric object]{__coerce__}{self, other}
Called to implement ``mixed-mode'' numeric arithmetic.  Should either
return a 2-tuple containing \var{self} and \var{other} converted to
a common numeric type, or \code{None} if conversion is impossible.  When
the common type would be the type of \code{other}, it is sufficient to
return \code{None}, since the interpreter will also ask the other
object to attempt a coercion (but sometimes, if the implementation of
the other type cannot be changed, it is useful to do the conversion to
the other type here).
\end{methoddesc}

\strong{Coercion rules}: to evaluate \var{x} \var{op} \var{y}, the
following steps are taken (where \method{__op__()} and
\method{__rop__()} are the method names corresponding to \var{op},
e.g., if var{op} is `\code{+}', \method{__add__()} and
\method{__radd__()} are used).  If an exception occurs at any point,
the evaluation is abandoned and exception handling takes over.

\begin{itemize}

\item[0.] If \var{x} is a string object and op is the modulo operator (\%),
the string formatting operation is invoked and the remaining steps are
skipped.

\item[1.] If \var{x} is a class instance:

	\begin{itemize}

	\item[1a.] If \var{x} has a \method{__coerce__()} method:
	replace \var{x} and \var{y} with the 2-tuple returned by
	\code{\var{x}.__coerce__(\var{y})}; skip to step 2 if the
	coercion returns \code{None}.

	\item[1b.] If neither \var{x} nor \var{y} is a class instance
	after coercion, go to step 3.

	\item[1c.] If \var{x} has a method \method{__op__()}, return
	\code{\var{x}.__op__(\var{y})}; otherwise, restore \var{x} and
	\var{y} to their value before step 1a.

	\end{itemize}

\item[2.] If \var{y} is a class instance:

	\begin{itemize}

	\item[2a.] If \var{y} has a \method{__coerce__()} method:
	replace \var{y} and \var{x} with the 2-tuple returned by
	\code{\var{y}.__coerce__(\var{x})}; skip to step 3 if the
	coercion returns \code{None}.

	\item[2b.] If neither \var{x} nor \var{y} is a class instance
	after coercion, go to step 3.

	\item[2b.] If \var{y} has a method \method{__rop__()}, return
	\code{\var{y}.__rop__(\var{x})}; otherwise, restore \var{x}
	and \var{y} to their value before step 2a.

	\end{itemize}

\item[3.] We only get here if neither \var{x} nor \var{y} is a class
instance.

	\begin{itemize}

	\item[3a.] If op is `\code{+}' and \var{x} is a sequence,
	sequence concatenation is invoked.

	\item[3b.] If op is `\code{*}' and one operand is a sequence
	and the other an integer, sequence repetition is invoked.

	\item[3c.] Otherwise, both operands must be numbers; they are
	coerced to a common type if possible, and the numeric
	operation is invoked for that type.

	\end{itemize}

\end{itemize}