The Python Reference Manual.

1 files changed, 889 insertions, 0 deletions

diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
new file mode 100644
index 0000000..fd152c1
--- /dev/null
+++ b/Doc/ref/ref3.tex
@@ -0,0 +1,889 @@
+\chapter{Data model}
+
+\section{Objects, values and types}
+
+\dfn{Objects} are Python's abstraction for data.  All data in a Python
+program is represented by objects or by relations between objects.
+(In a sense, and in conformance to Von Neumann's model of a
+``stored program computer'', code is also represented by objects.)
+\index{object}
+\index{data}
+
+Every object has an identity, a type and a value.  An object's
+\emph{identity} never changes once it has been created; you may think
+of it as the object's address in memory.  An object's \dfn{type} is
+also unchangeable.  It determines the operations that an object
+supports (e.g.\ ``does it have a length?'') and also defines the
+possible values for objects of that type.  The \emph{value} of some
+objects can change.  Objects whose value can change are said to be
+\emph{mutable}; objects whose value is unchangeable once they are
+created are called \emph{immutable}.  The type determines an object's
+(im)mutability.
+\index{identity of an object}
+\index{value of an object}
+\index{type of an object}
+\index{mutable object}
+\index{immutable object}
+
+Objects are never explicitly destroyed; however, when they become
+unreachable they may be garbage-collected.  An implementation is
+allowed to delay garbage collection or omit it altogether --- it is a
+matter of implementation quality how garbage collection is
+implemented, as long as no objects are collected that are still
+reachable.  (Implementation note: the current implementation uses a
+reference-counting scheme which collects most objects as soon as they
+become unreachable, but never collects garbage containing circular
+references.)
+\index{garbage collection}
+\index{reference counting}
+\index{unreachable object}
+
+Note that the use of the implementation's tracing or debugging
+facilities may keep objects alive that would normally be collectable.
+
+Some objects contain references to ``external'' resources such as open
+files or windows.  It is understood that these resources are freed
+when the object is garbage-collected, but since garbage collection is
+not guaranteed to happen, such objects also provide an explicit way to
+release the external resource, usually a \method{close()} method.
+Programs are strongly recommended to always explicitly close such
+objects.
+
+Some objects contain references to other objects; these are called
+\emph{containers}.  Examples of containers are tuples, lists and
+dictionaries.  The references are part of a container's value.  In
+most cases, when we talk about the value of a container, we imply the
+values, not the identities of the contained objects; however, when we
+talk about the (im)mutability of a container, only the identities of
+the immediately contained objects are implied.  (So, if an immutable
+container contains a reference to a mutable object, its value changes
+if that mutable object is changed.)
+\index{container}
+
+Types affect almost all aspects of objects' lives.  Even the meaning
+of object identity is affected in some sense: for immutable types,
+operations that compute new values may actually return a reference to
+any existing object with the same type and value, while for mutable
+objects this is not allowed.  E.g. after
+
+\begin{verbatim}
+a = 1; b = 1; c = []; d = []
+\end{verbatim}
+
+\code{a} and \code{b} may or may not refer to the same object with the
+value one, depending on the implementation, but \code{c} and \code{d}
+are guaranteed to refer to two different, unique, newly created empty
+lists.
+
+\section{The standard type hierarchy} \label{types}
+
+Below is a list of the types that are built into Python.  Extension
+modules written in C can define additional types.  Future versions of
+Python may add types to the type hierarchy (e.g.\ rational or complex
+numbers, efficiently stored arrays of integers, etc.).
+\index{type}
+\indexii{data}{type}
+\indexii{type}{hierarchy}
+\indexii{extension}{module}
+\indexii{C}{language}
+
+Some of the type descriptions below contain a paragraph listing
+`special attributes'.  These are attributes that provide access to the
+implementation and are not intended for general use.  Their definition
+may change in the future.  There are also some `generic' special
+attributes, not listed with the individual objects: \member{__methods__}
+is a list of the method names of a built-in object, if it has any;
+\member{__members__} is a list of the data attribute names of a built-in
+object, if it has any.
+\index{attribute}
+\indexii{special}{attribute}
+\indexiii{generic}{special}{attribute}
+\ttindex{__methods__}
+\ttindex{__members__}
+
+\begin{description}
+
+\item[None]
+This type has a single value.  There is a single object with this value.
+This object is accessed through the built-in name \code{None}.
+It is returned from functions that don't explicitly return an object.
+\ttindex{None}
+\obindex{None@{\tt None}}
+
+\item[Numbers]
+These are created by numeric literals and returned as results by
+arithmetic operators and arithmetic built-in functions.  Numeric
+objects are immutable; once created their value never changes.  Python
+numbers are of course strongly related to mathematical numbers, but
+subject to the limitations of numerical representation in computers.
+\obindex{number}
+\obindex{numeric}
+
+Python distinguishes between integers and floating point numbers:
+
+\begin{description}
+\item[Integers]
+These represent elements from the mathematical set of whole numbers.
+\obindex{integer}
+
+There are two types of integers:
+
+\begin{description}
+
+\item[Plain integers]
+These represent numbers in the range -2147483648 through 2147483647.
+(The range may be larger on machines with a larger natural word
+size, but not smaller.)
+When the result of an operation falls outside this range, the
+exception \exception{OverflowError} is raised.
+For the purpose of shift and mask operations, integers are assumed to
+have a binary, 2's complement notation using 32 or more bits, and
+hiding no bits from the user (i.e., all 4294967296 different bit
+patterns correspond to different values).
+\obindex{plain integer}
+\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
+
+\item[Long integers]
+These represent numbers in an unlimited range, subject to available
+(virtual) memory only.  For the purpose of shift and mask operations,
+a binary representation is assumed, and negative numbers are
+represented in a variant of 2's complement which gives the illusion of
+an infinite string of sign bits extending to the left.
+\obindex{long integer}
+
+\end{description} % Integers
+
+The rules for integer representation are intended to give the most
+meaningful interpretation of shift and mask operations involving
+negative integers and the least surprises when switching between the
+plain and long integer domains.  For any operation except left shift,
+if it yields a result in the plain integer domain without causing
+overflow, it will yield the same result in the long integer domain or
+when using mixed operands.
+\indexii{integer}{representation}
+
+\item[Floating point numbers]
+These represent machine-level double precision floating point numbers.  
+You are at the mercy of the underlying machine architecture and
+C implementation for the accepted range and handling of overflow.
+\obindex{floating point}
+\indexii{floating point}{number}
+\indexii{C}{language}
+
+\end{description} % Numbers
+
+\item[Sequences]
+These represent finite ordered sets indexed by natural numbers.
+The built-in function \function{len()}\bifuncindex{len} returns the
+number of elements of a sequence.  When this number is \var{n}, the
+index set contains the numbers 0, 1, \ldots, \var{n}-1.  Element
+\var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}.
+\obindex{seqence}
+\index{index operation}
+\index{item selection}
+\index{subscription}
+
+Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]}
+selects all elements with index \var{k} such that \var{i} \code{<=}
+\var{k} \code{<} \var{j}.  When used as an expression, a slice is a
+sequence of the same type --- this implies that the index set is
+renumbered so that it starts at 0 again.
+\index{slicing}
+
+Sequences are distinguished according to their mutability:
+
+\begin{description}
+%
+\item[Immutable sequences]
+An object of an immutable sequence type cannot change once it is
+created.  (If the object contains references to other objects,
+these other objects may be mutable and may be changed; however
+the collection of objects directly referenced by an immutable object
+cannot change.)
+\obindex{immutable sequence}
+\obindex{immutable}
+
+The following types are immutable sequences:
+
+\begin{description}
+
+\item[Strings]
+The elements of a string are characters.  There is no separate
+character type; a character is represented by a string of one element.
+Characters represent (at least) 8-bit bytes.  The built-in
+functions \function{chr()}\bifuncindex{chr} and
+\function{ord()}\bifuncindex{ord} convert between characters and
+nonnegative integers representing the byte values.  Bytes with the
+values 0-127 represent the corresponding \ASCII{} values.  The string
+data type is also used to represent arrays of bytes, e.g.\ to hold data
+read from a file.
+\obindex{string}
+\index{character}
+\index{byte}
+\index{ASCII}
+
+(On systems whose native character set is not \ASCII{}, strings may use
+EBCDIC in their internal representation, provided the functions
+\function{chr()} and \function{ord()} implement a mapping between \ASCII{} and
+EBCDIC, and string comparison preserves the \ASCII{} order.
+Or perhaps someone can propose a better rule?)
+\index{ASCII}
+\index{EBCDIC}
+\index{character set}
+\indexii{string}{comparison}
+\bifuncindex{chr}
+\bifuncindex{ord}
+
+\item[Tuples]
+The elements of a tuple are arbitrary Python objects.
+Tuples of two or more elements are formed by comma-separated lists
+of expressions.  A tuple of one element (a `singleton') can be formed
+by affixing a comma to an expression (an expression by itself does
+not create a tuple, since parentheses must be usable for grouping of
+expressions).  An empty tuple can be formed by enclosing `nothing' in
+parentheses.
+\obindex{tuple}
+\indexii{singleton}{tuple}
+\indexii{empty}{tuple}
+
+\end{description} % Immutable sequences
+
+\item[Mutable sequences]
+Mutable sequences can be changed after they are created.  The
+subscription and slicing notations can be used as the target of
+assignment and \keyword{del} (delete) statements.
+\obindex{mutable sequece}
+\obindex{mutable}
+\indexii{assignment}{statement}
+\index{delete}
+\stindex{del}
+\index{subscription}
+\index{slicing}
+
+There is currently a single mutable sequence type:
+
+\begin{description}
+
+\item[Lists]
+The elements of a list are arbitrary Python objects.  Lists are formed
+by placing a comma-separated list of expressions in square brackets.
+(Note that there are no special cases needed to form lists of length 0
+or 1.)
+\obindex{list}
+
+\end{description} % Mutable sequences
+
+\end{description} % Sequences
+
+\item[Mapping types]
+These represent finite sets of objects indexed by arbitrary index sets.
+The subscript notation \code{a[k]} selects the element indexed
+by \code{k} from the mapping \code{a}; this can be used in
+expressions and as the target of assignments or \keyword{del} statements.
+The built-in function \function{len()} returns the number of elements
+in a mapping.
+\bifuncindex{len}
+\index{subscription}
+\obindex{mapping}
+
+There is currently a single mapping type:
+
+\begin{description}
+
+\item[Dictionaries]
+These represent finite sets of objects indexed by almost arbitrary
+values.  The only types of values not acceptable as keys are values
+containing lists or dictionaries or other mutable types that are
+compared by value rather than by object identity --- the reason being
+that the implementation requires that a key's hash value be constant.
+Numeric types used for keys obey the normal rules for numeric
+comparison: if two numbers compare equal (e.g.\ \code{1} and
+\code{1.0}) then they can be used interchangeably to index the same
+dictionary entry.
+
+Dictionaries are mutable; they are created by the \code{...}
+notation (see section \ref{dict}).
+\obindex{dictionary}
+\obindex{mutable}
+
+\end{description} % Mapping types
+
+\item[Callable types]
+These are the types to which the function call (invocation) operation,
+written as \code{function(argument, argument, ...)}, can be applied:
+\indexii{function}{call}
+\index{invocation}
+\indexii{function}{argument}
+\obindex{callable}
+
+\begin{description}
+
+\item[User-defined functions]
+A user-defined function object is created by a function definition
+(see section \ref{function}).  It should be called with an argument
+list containing the same number of items as the function's formal
+parameter list.
+\indexii{user-defined}{function}
+\obindex{function}
+\obindex{user-defined function}
+
+Special read-only attributes: \member{func_code} is the code object
+representing the compiled function body, and \member{func_globals} is (a
+reference to) the dictionary that holds the function's global
+variables --- it implements the global name space of the module in
+which the function was defined.
+\ttindex{func_code}
+\ttindex{func_globals}
+\indexii{global}{name space}
+
+\item[User-defined methods]
+A user-defined method (a.k.a. \dfn{object closure}) is a pair of a
+class instance object and a user-defined function.  It should be
+called with an argument list containing one item less than the number
+of items in the function's formal parameter list.  When called, the
+class instance becomes the first argument, and the call arguments are
+shifted one to the right.
+\obindex{method}
+\obindex{user-defined method}
+\indexii{user-defined}{method}
+\index{object closure}
+
+Special read-only attributes: \member{im_self} is the class instance
+object, \member{im_func} is the function object.
+\ttindex{im_func}
+\ttindex{im_self}
+
+\item[Built-in functions]
+A built-in function object is a wrapper around a C function.  Examples
+of built-in functions are \function{len()} and \function{math.sin()}.  There
+are no special attributes.  The number and type of the arguments are
+determined by the C function.
+\obindex{built-in function}
+\obindex{function}
+\indexii{C}{language}
+
+\item[Built-in methods]
+This is really a different disguise of a built-in function, this time
+containing an object passed to the \C{} function as an implicit extra
+argument.  An example of a built-in method is \code{\var{list}.append()} if
+\var{list} is a list object.
+\obindex{built-in method}
+\obindex{method}
+\indexii{built-in}{method}
+
+\item[Classes]
+Class objects are described below.  When a class object is called as a
+function, a new class instance (also described below) is created and
+returned.  This implies a call to the class's \method{__init__()} method
+if it has one.  Any arguments are passed on to the \method{__init__()}
+method --- if there is no \method{__init__()} method, the class must be called
+without arguments.
+\ttindex{__init__}
+\obindex{class}
+\obindex{class instance}
+\obindex{instance}
+\indexii{class object}{call}
+
+\end{description}
+
+\item[Modules]
+Modules are imported by the \keyword{import} statement (see section
+\ref{import}).  A module object is a container for a module's name
+space, which is a dictionary (the same dictionary as referenced by the
+\member{func_globals} attribute of functions defined in the module).
+Module attribute references are translated to lookups in this
+dictionary.  A module object does not contain the code object used to
+initialize the module (since it isn't needed once the initialization
+is done).
+\stindex{import}
+\obindex{module}
+
+Attribute assignment update the module's name space dictionary.
+
+Special read-only attribute: \member{__dict__} yields the module's name
+space as a dictionary object.  Predefined attributes: \member{__name__}
+yields the module's name as a string object; \member{__doc__} yields the
+module's documentation string as a string object, or
+\code{None} if no documentation string was found.
+\ttindex{__dict__}
+\ttindex{__name__}
+\ttindex{__doc__}
+\indexii{module}{name space}
+
+\item[Classes]
+Class objects are created by class definitions (see section
+\ref{class}).  A class is a container for a dictionary containing the
+class's name space.  Class attribute references are translated to
+lookups in this dictionary.  When an attribute name is not found
+there, the attribute search continues in the base classes.  The search
+is depth-first, left-to-right in the order of their occurrence in the
+base class list.
+\obindex{class}
+\obindex{class instance}
+\obindex{instance}
+\indexii{class object}{call}
+\index{container}
+\obindex{dictionary}
+\indexii{class}{attribute}
+
+Class attribute assignments update the class's dictionary, never the
+dictionary of a base class.
+\indexiii{class}{attribute}{assignment}
+
+A class can be called as a function to yield a class instance (see
+above).
+\indexii{class object}{call}
+
+Special read-only attributes: \member{__dict__} yields the dictionary
+containing the class's name space; \member{__bases__} yields a tuple
+(possibly empty or a singleton) containing the base classes, in the
+order of their occurrence in the base class list.
+\ttindex{__dict__}
+\ttindex{__bases__}
+
+\item[Class instances]
+A class instance is created by calling a class object as a
+function.  A class instance has a dictionary in which
+attribute references are searched.  When an attribute is not found
+there, and the instance's class has an attribute by that name, and
+that class attribute is a user-defined function (and in no other
+cases), the instance attribute reference yields a user-defined method
+object (see above) constructed from the instance and the function.
+\obindex{class instance}
+\obindex{instance}
+\indexii{class}{instance}
+\indexii{class instance}{attribute}
+
+Attribute assignments update the instance's dictionary.
+\indexiii{class instance}{attribute}{assignment}
+
+Class instances can pretend to be numbers, sequences, or mappings if
+they have methods with certain special names.  These are described in
+section \ref{specialnames}.
+\obindex{number}
+\obindex{sequence}
+\obindex{mapping}
+
+Special read-only attributes: \member{__dict__} yields the attribute
+dictionary; \member{__class__} yields the instance's class.
+\ttindex{__dict__}
+\ttindex{__class__}
+
+\item[Files]
+A file object represents an open file.  (It is a wrapper around a \C{}
+\code{stdio} file pointer.)  File objects are created by the
+\function{open()} built-in function, and also by \function{posix.popen()} and
+the \method{makefile()} method of socket objects.  \code{sys.stdin},
+\code{sys.stdout} and \code{sys.stderr} are file objects corresponding
+to the interpreter's standard input, output and error streams.
+See the \emph{Python Library Reference} for methods of file objects
+and other details.
+\obindex{file}
+\indexii{C}{language}
+\index{stdio}
+\bifuncindex{open}
+\bifuncindex{popen}
+\bifuncindex{makefile}
+\ttindex{stdin}
+\ttindex{stdout}
+\ttindex{stderr}
+\ttindex{sys.stdin}
+\ttindex{sys.stdout}
+\ttindex{sys.stderr}
+
+\item[Internal types]
+A few types used internally by the interpreter are exposed to the user.
+Their definition may change with future versions of the interpreter,
+but they are mentioned here for completeness.
+\index{internal type}
+\index{types, internal}
+
+\begin{description}
+
+\item[Code objects]
+Code objects represent ``pseudo-compiled'' executable Python code.
+The difference between a code
+object and a function object is that the function object contains an
+explicit reference to the function's context (the module in which it
+was defined) while a code object contains no context.
+\obindex{code}
+
+Special read-only attributes: \member{co_code} is a string representing
+the sequence of instructions; \member{co_consts} is a list of literals
+used by the code; \member{co_names} is a list of names (strings) used by
+the code; \member{co_filename} is the filename from which the code was
+compiled.  (To find out the line numbers, you would have to decode the
+instructions; the standard library module
+\module{dis}\refstmodindex{dis} contains an example of how to do
+this.)
+\ttindex{co_code}
+\ttindex{co_consts}
+\ttindex{co_names}
+\ttindex{co_filename}
+
+\item[Frame objects]
+Frame objects represent execution frames.  They may occur in traceback
+objects (see below).
+\obindex{frame}
+
+Special read-only attributes: \member{f_back} is to the previous
+stack frame (towards the caller), or \code{None} if this is the bottom
+stack frame; \member{f_code} is the code object being executed in this
+frame; \member{f_globals} is the dictionary used to look up global
+variables; \member{f_locals} is used for local variables;
+\member{f_lineno} gives the line number and \member{f_lasti} gives the
+precise instruction (this is an index into the instruction string of
+the code object).
+\ttindex{f_back}
+\ttindex{f_code}
+\ttindex{f_globals}
+\ttindex{f_locals}
+\ttindex{f_lineno}
+\ttindex{f_lasti}
+
+\item[Traceback objects] \label{traceback}
+Traceback objects represent a stack trace of an exception.  A
+traceback object is created when an exception occurs.  When the search
+for an exception handler unwinds the execution stack, at each unwound
+level a traceback object is inserted in front of the current
+traceback.  When an exception handler is entered
+(see also section \ref{try}), the stack trace is
+made available to the program as \code{sys.exc_traceback}.  When the
+program contains no suitable handler, the stack trace is written
+(nicely formatted) to the standard error stream; if the interpreter is
+interactive, it is also made available to the user as
+\code{sys.last_traceback}.
+\obindex{traceback}
+\indexii{stack}{trace}
+\indexii{exception}{handler}
+\indexii{execution}{stack}
+\ttindex{exc_traceback}
+\ttindex{last_traceback}
+\ttindex{sys.exc_traceback}
+\ttindex{sys.last_traceback}
+
+Special read-only attributes: \member{tb_next} is the next level in the
+stack trace (towards the frame where the exception occurred), or
+\code{None} if there is no next level; \member{tb_frame} points to the
+execution frame of the current level; \member{tb_lineno} gives the line
+number where the exception occurred; \member{tb_lasti} indicates the
+precise instruction.  The line number and last instruction in the
+traceback may differ from the line number of its frame object if the
+exception occurred in a \keyword{try} statement with no matching
+except clause or with a finally clause.
+\ttindex{tb_next}
+\ttindex{tb_frame}
+\ttindex{tb_lineno}
+\ttindex{tb_lasti}
+\stindex{try}
+
+\end{description} % Internal types
+
+\end{description} % Types
+
+
+\section{Special method names} \label{specialnames}
+
+A class can implement certain operations that are invoked by special
+syntax (such as subscription or arithmetic operations) by defining
+methods with special names.  For instance, if a class defines a
+method named \method{__getitem__()}, and \code{x} is an instance of this
+class, then \code{x[i]} is equivalent to \code{x.__getitem__(i)}.
+(The reverse is not true --- if \code{x} is a list object,
+\code{x.__getitem__(i)} is not equivalent to \code{x[i]}.)
+\ttindex{__getitem__}
+
+Except for \method{__repr__()}, \method{__str__()} and \method{__cmp__()},
+attempts to execute an
+operation raise an exception when no appropriate method is defined.
+For \method{__repr__()}, the default is to return a string describing the
+object's class and address.
+For \method{__cmp__()}, the default is to compare instances based on their
+address.
+For \method{__str__()}, the default is to use \method{__repr__()}.
+\ttindex{__repr__}
+\ttindex{__str__}
+\ttindex{__cmp__}
+
+
+\subsection{Special methods for any type}
+
+\begin{description}
+
+\item[{\tt __init__(self, args...)}]
+Called when the instance is created.  The arguments are those passed
+to the class constructor expression.  If a base class has an
+\code{__init__} method the derived class's \code{__init__} method must
+explicitly call it to ensure proper initialization of the base class
+part of the instance.
+\ttindex{__init__}
+\indexii{class}{constructor}
+
+
+\item[{\tt __del__(self)}]
+Called when the instance is about to be destroyed.  If a base class
+has a \method{__del__()} method the derived class's \method{__del__()} method
+must explicitly call it to ensure proper deletion of the base class
+part of the instance.  Note that it is possible for the \method{__del__()}
+method to postpone destruction of the instance by creating a new
+reference to it.  It may then be called at a later time when this new
+reference is deleted.  It is not guaranteed that
+\method{__del__()} methods are called for objects that still exist when
+the interpreter exits.
+If an exception occurs in a \method{__del__()} method, it is ignored, and
+a warning is printed on stderr.
+\ttindex{__del__}
+\stindex{del}
+
+Note that \code{del x} doesn't directly call \code{x.__del__()} --- the
+former decrements the reference count for \code{x} by one, but
+\code{x.__del__()} is only called when its reference count reaches zero.
+
+\strong{Warning:} due to the precarious circumstances under which
+\code{__del__()} methods are executed, exceptions that occur during
+their execution are \emph{ignored}.
+
+\item[{\tt __repr__(self)}]
+Called by the \function{repr()} built-in function and by string conversions
+(reverse or backward quotes) to compute the string representation of an object.
+\ttindex{__repr__}
+\bifuncindex{repr}
+\indexii{string}{conversion}
+\indexii{reverse}{quotes}
+\indexii{backward}{quotes}
+\index{back-quotes}
+
+\item[{\tt __str__(self)}]
+Called by the \function{str()} built-in function and by the \keyword{print}
+statement compute the string representation of an object.
+\ttindex{__str__}
+\bifuncindex{str}
+\stindex{print}
+
+\item[{\tt __cmp__(self, other)}]
+Called by all comparison operations.  Should return \code{-1} if
+\code{self < other},  \code{0} if \code{self == other}, \code{+1} if
+\code{self > other}.  If no \method{__cmp__()} operation is defined, class
+instances are compared by object identity (``address'').
+(Implementation note: due to limitations in the interpreter,
+exceptions raised by comparisons are ignored, and the objects will be
+considered equal in this case.)
+\ttindex{__cmp__}
+\bifuncindex{cmp}
+\index{comparisons}
+
+\item[{\tt __hash__(self)}]
+Called for the key object for dictionary operations,
+and by the built-in function
+\function{hash()}\bifuncindex{hash}.  Should return a 32-bit integer
+usable as a hash value
+for dictionary operations.  The only required property is that objects
+which compare equal have the same hash value; it is advised to somehow
+mix together (e.g.\ using exclusive or) the hash values for the
+components of the object that also play a part in comparison of
+objects.  If a class does not define a \method{__cmp__()} method it should
+not define a \method{__hash__()} operation either; if it defines
+\method{__cmp__()} but not \method{__hash__()} its instances will not be
+usable as dictionary keys.  If a class defines mutable objects and
+implements a \method{__cmp__()} method it should not implement
+\method{__hash__()}, since the dictionary implementation assumes that a
+key's hash value is a constant.
+\obindex{dictionary}
+\ttindex{__cmp__}
+\ttindex{__hash__}
+
+\item[{\tt __call__(self, *args)}]
+Called when the instance is ``called'' as a function.
+\ttindex{__call__}
+\indexii{call}{instance}
+
+\end{description}
+
+
+\subsection{Special methods for attribute access}
+
+The following methods can be used to change the meaning of attribute
+access for class instances.
+
+\begin{description}
+
+\item[{\tt __getattr__(self, name)}]
+Called when an attribute lookup has not found the attribute in the
+usual places (i.e. it is not an instance attribute nor is it found in
+the class tree for \code{self}).  \code{name} is the attribute name.
+\ttindex{__getattr__}
+
+Note that if the attribute is found through the normal mechanism,
+\code{__getattr__} is not called.  (This is an asymmetry between
+\code{__getattr__} and \code{__setattr__}.)
+This is done both for efficiency reasons and because otherwise
+\code{__getattr__} would have no way to access other attributes of the
+instance.
+Note that at least for instance variables, \code{__getattr__} can fake
+total control by simply not inserting any values in the instance
+attribute dictionary.
+\ttindex{__setattr__}
+
+\item[{\tt __setattr__(self, name, value)}]
+Called when an attribute assignment is attempted.  This is called
+instead of the normal mechanism (i.e. store the value as an instance
+attribute).  \code{name} is the attribute name, \code{value} is the
+value to be assigned to it.
+\ttindex{__setattr__}
+
+If \code{__setattr__} wants to assign to an instance attribute, it
+should not simply execute \code{self.\var{name} = value} --- this would
+cause a recursive call.  Instead, it should insert the value in the
+dictionary of instance attributes, e.g.\ \code{self.__dict__[name] =
+value}.
+\ttindex{__dict__}
+
+\item[{\tt __delattr__(self, name)}]
+Like \code{__setattr__} but for attribute deletion instead of
+assignment.
+\ttindex{__delattr__}
+
+\end{description}
+
+
+\subsection{Special methods for sequence and mapping types}
+
+\begin{description}
+
+\item[{\tt __len__(self)}]
+Called to implement the built-in function \function{len()}.  Should return
+the length of the object, an integer \code{>=} 0.  Also, an object
+whose \method{__len__()} method returns 0 is considered to be false in a
+Boolean context.
+\ttindex{__len__}
+
+\item[{\tt __getitem__(self, key)}]
+Called to implement evaluation of \code{self[key]}.  Note that the
+special interpretation of negative keys (if the class wishes to
+emulate a sequence type) is up to the \method{__getitem__()} method.
+\ttindex{__getitem__}
+
+\item[{\tt __setitem__(self, key, value)}]
+Called to implement assignment to \code{self[key]}.  Same note as for
+\method{__getitem__()}.
+\ttindex{__setitem__}
+
+\item[{\tt __delitem__(self, key)}]
+Called to implement deletion of \code{self[key]}.  Same note as for
+\method{__getitem__()}.
+\ttindex{__delitem__}
+
+\end{description}
+
+
+\subsection{Special methods for sequence types}
+
+\begin{description}
+
+\item[{\tt __getslice__(self, i, j)}]
+Called to implement evaluation of \code{self[i:j]}.  Note that missing
+\code{i} or \code{j} are replaced by 0 or \code{len(self)},
+respectively, and \code{len(self)} has been added (once) to originally
+negative \code{i} or \code{j} by the time this function is called
+(unlike for \method{__getitem__()}).
+\ttindex{__getslice__}
+
+\item[{\tt __setslice__(self, i, j, sequence)}]
+Called to implement assignment to \code{self[i:j]}.  Same notes as for
+\method{__getslice__()}.
+\ttindex{__setslice__}
+
+\item[{\tt __delslice__(self, i, j)}]
+Called to implement deletion of \code{self[i:j]}.  Same notes as for
+\method{__getslice__()}.
+\ttindex{__delslice__}
+
+\end{description}
+
+
+\subsection{Special methods for numeric types}
+
+\begin{description}
+
+\item[{\tt __add__(self, other)}]\itemjoin
+\item[{\tt __sub__(self, other)}]\itemjoin
+\item[{\tt __mul__(self, other)}]\itemjoin
+\item[{\tt __div__(self, other)}]\itemjoin
+\item[{\tt __mod__(self, other)}]\itemjoin
+\item[{\tt __divmod__(self, other)}]\itemjoin
+\item[{\tt __pow__(self, other)}]\itemjoin
+\item[{\tt __lshift__(self, other)}]\itemjoin
+\item[{\tt __rshift__(self, other)}]\itemjoin
+\item[{\tt __and__(self, other)}]\itemjoin
+\item[{\tt __xor__(self, other)}]\itemjoin
+\item[{\tt __or__(self, other)}]\itembreak
+Called to implement the binary arithmetic operations (\code{+},
+\code{-}, \code{*}, \code{/}, \code{\%}, \function{divmod()}, \function{pow()},
+\code{<<}, \code{>>}, \code{\&}, \code{\^}, \code{|}).
+\ttindex{__or__}
+\ttindex{__xor__}
+\ttindex{__and__}
+\ttindex{__rshift__}
+\ttindex{__lshift__}
+\ttindex{__pow__}
+\ttindex{__divmod__}
+\ttindex{__mod__}
+\ttindex{__div__}
+\ttindex{__mul__}
+\ttindex{__sub__}
+\ttindex{__add__}
+
+\item[{\tt __neg__(self)}]\itemjoin
+\item[{\tt __pos__(self)}]\itemjoin
+\item[{\tt __abs__(self)}]\itemjoin
+\item[{\tt __invert__(self)}]\itembreak
+Called to implement the unary arithmetic operations (\code{-}, \code{+},
+\function{abs()} and \code{~}).
+\ttindex{__invert__}
+\ttindex{__abs__}
+\ttindex{__pos__}
+\ttindex{__neg__}
+
+\item[{\tt __nonzero__(self)}]
+Called to implement boolean testing; should return 0 or 1.  An
+alternative name for this method is \method{__len__()}.
+\ttindex{__nonzero__}
+
+\item[{\tt __coerce__(self, other)}]
+Called to implement ``mixed-mode'' numeric arithmetic.  Should either
+return a tuple containing self and other converted to a common numeric
+type, or None if no way of conversion is known.  When the common type
+would be the type of other, it is sufficient to return 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).
+\ttindex{__coerce__}
+
+Note that this method is not called to coerce the arguments to \code{+}
+and \code{*}, because these are also used to implement sequence
+concatenation and repetition, respectively.  Also note that, for the
+same reason, in \code{\var{n} * \var{x}}, where \var{n} is a built-in
+number and \var{x} is an instance, a call to
+\code{\var{x}.__mul__(\var{n})} is made.%
+\footnote{The interpreter should really distinguish between
+user-defined classes implementing sequences, mappings or numbers, but
+currently it doesn't --- hence this strange exception.}
+\ttindex{__mul__}
+
+\item[{\tt __int__(self)}]\itemjoin
+\item[{\tt __long__(self)}]\itemjoin
+\item[{\tt __float__(self)}]\itembreak
+Called to implement the built-in functions \function{int()}, \function{long()}
+and \function{float()}.  Should return a value of the appropriate type.
+\ttindex{__float__}
+\ttindex{__long__}
+\ttindex{__int__}
+
+\item[{\tt __oct__(self)}]\itemjoin
+\item[{\tt __hex__(self)}]\itembreak
+Called to implement the built-in functions \function{oct()} and
+\function{hex()}.  Should return a string value.
+\ttindex{__hex__}
+\ttindex{__oct__}
+
+\end{description}