From d82575d5bf2bcf1f47f1e4945072c013d1d59afb Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 28 Aug 1998 20:03:12 +0000 Subject: Markup changes in the section on disciplines to match method descriptions a little better, and produce better HTML. Add some index entries. --- Doc/ref/ref3.tex | 336 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 171 insertions(+), 165 deletions(-) (limited to 'Doc') diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index 4ca8d69f729..39fee2b308f 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -784,32 +784,32 @@ Special read-only attributes: \code{start} is the lowerbound; \section{Special method names\label{specialnames}} A class can implement certain operations that are invoked by special -syntax (such as arithmetic operations or subscripting and slicing) 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]}.) -Except where mentioned, attempts to execute an +syntax (such as arithmetic operations or subscripting and slicing) 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]}.) Except where mentioned, attempts to execute an operation raise an exception when no appropriate method is defined. \ttindex{__getitem__} \subsection{Basic customization\label{customization}} -\begin{description} - -\item[{\tt __init__(self, [args...])}] +\begin{methoddescni}{__init__}{self\optional{, 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, e.g., ``\code{BaseClass.__init__(self, [args...])}''. +part of the instance, e.g., \samp{BaseClass.__init__(\var{self}, +[\var{args}...])}. \ttindex{__init__} \indexii{class}{constructor} +\end{methoddescni} -\item[{\tt __del__(self)}] +\begin{methoddescni}{__del__}{self} Called when the instance is about to be destroyed. This is also called a destructor\index{destructor}. If a base class has a \method{__del__()} method, the derived class's \method{__del__()} method @@ -841,20 +841,21 @@ latter two situations can be resolved by storing None in \code{sys.exc_traceback} or \code{sys.last_traceback}. \strong{Warning:} due to the precarious circumstances under which -\code{__del__} methods are invoked, exceptions that occur during their +\method{__del__()} methods are invoked, exceptions that occur during their execution are ignored, and a warning is printed to \code{sys.stderr} -instead. Also, when \code{__del__} is invoked is response to a module +instead. Also, when \method{__del__()} is invoked is response to a module being deleted (e.g., when execution of the program is done), other -globals referenced by the \code{__del__} method may already have been -deleted. For this reason, \code{__del__} methods should do the +globals referenced by the \method{__del__()} method may already have been +deleted. For this reason, \method{__del__()} methods should do the absolute minimum needed to maintain external invariants. Python 1.5 guarantees that globals whose name begins with a single underscore are deleted from their module before other globals are deleted; if no other references to such globals exist, this may help in assuring that imported modules are still available at the time when the -\code{__del__} method is called. +\method{__del__()} method is called. +\end{methoddescni} -\item[{\tt __repr__(self)}] +\begin{methoddescni}{__repr__}{self} Called by the \function{repr()} built-in function and by string conversions (reverse quotes) to compute the ``official'' string representation of an object. This should normally look like a valid Python expression @@ -868,15 +869,16 @@ may be used instead. \indexii{reverse}{quotes} \indexii{backward}{quotes} \index{back-quotes} +\end{methoddescni} -\item[{\tt __str__(self)}] -Called by the \function{str()} built-in function and by the \keyword{print} -statement to compute the ``informal'' string representation of an object. +\begin{methoddescni}{__str__}{self} +Called by the \function{str()}\bifuncindex{str} built-in function and +by the \keyword{print}\stindex{print} statement to compute the +``informal'' string representation of an object. \ttindex{__str__} -\bifuncindex{str} -\stindex{print} +\end{methoddescni} -\item[{\tt __cmp__(self, other)}] +\begin{methoddescni}{__cmp__}{self, other} Called by all comparison operations. Should return a negative integer if \code{self < other}, zero if \code{self == other}, a positive integer if \code{self > other}. If no \method{__cmp__()} operation is defined, class @@ -886,10 +888,11 @@ instances are compared by object identity (``address''). \ttindex{__cmp__} \bifuncindex{cmp} \index{comparisons} +\end{methoddescni} -\item[{\tt __hash__(self)}] -Called for the key object for dictionary operations, -and by the built-in function +\begin{methoddescni}{__hash__}{self} +Called for the key object for dictionary\obindex{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 @@ -904,17 +907,18 @@ implements a \method{__cmp__()} method it should not implement \method{__hash__()}, since the dictionary implementation requires that a key's hash value is immutable (if the object's hash value changes, it will be in the wrong hash bucket). -\obindex{dictionary} \ttindex{__cmp__} \ttindex{__hash__} - -\item[__nonzero__(self)] -Called to implement truth value testing; should return 0 or 1. When -this method is not defined, \code{__len__} is called, if it is defined -(see below). If a class defines neither \code{__len__} nor -\code{__nonzero__}, all its instances are considered true. - -\end{description} +\end{methoddescni} + +\begin{methoddescni}{__nonzero__}{self} +Called to implement truth value testing; should return \code{0} or +\code{1}. When this method is not defined, \method{__len__()} is +called, if it is defined (see below). If a class defines neither +\method{__len__()} nor \method{__nonzero__()}, all its instances are +considered true. +\ttindex{__nonzero__} +\end{methoddescni} \subsection{Customizing attribute access\label{attribute-access}} @@ -926,61 +930,57 @@ For performance reasons, these methods are cached in the class object at class definition time; therefore, they cannot be changed after the class definition is executed. -\begin{description} - -\item[{\tt __getattr__(self, name)}] +\begin{methoddescni}{__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. This method should return the (computed) attribute value or raise an -\code{AttributeError} exception. +\exception{AttributeError} exception. \ttindex{__getattr__} Note that if the attribute is found through the normal mechanism, -\code{__getattr__} is not called. (This is an intentional asymmetry between -\code{__getattr__} and \code{__setattr__}.) +\method{__getattr__()} is not called. (This is an intentional +asymmetry between \method{__getattr__()} and \method{__setattr__()}.) This is done both for efficiency reasons and because otherwise -\code{__setattr__} would have no way to access other attributes of the -instance. +\method{__setattr__()} would have no way to access other attributes of +the instance. Note that at least for instance variables, you can fake total control by not inserting any values in the instance attribute dictionary (but instead inserting them in another object). \ttindex{__setattr__} +\end{methoddescni} -\item[{\tt __setattr__(self, name, value)}] +\begin{methoddescni}{__setattr__}{self, name, value} Called when an attribute assignment is attempted. This is called -instead of the normal mechanism (i.e. store the value in the instance -dictionary). \code{name} is the attribute name, \code{value} is the +instead of the normal mechanism (i.e.\ store the value in the instance +dictionary). \var{name} is the attribute name, \var{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 to itself. Instead, it should insert the value in the -dictionary of instance attributes, e.g., -``\code{self.__dict__[name] = value}.'' +If \method{__setattr__()} wants to assign to an instance attribute, it +should not simply execute \samp{self.\var{name} = value} --- this +would cause a recursive call to itself. Instead, it should insert the +value in the dictionary of instance attributes, e.g., +\samp{self.__dict__[\var{name}] = value}. \ttindex{__dict__} +\end{methoddescni} -\item[{\tt __delattr__(self, name)}] -Like \code{__setattr__} but for attribute deletion instead of +\begin{methoddescni}{__delattr__}{self, name} +Like \method{__setattr__()} but for attribute deletion instead of assignment. \ttindex{__delattr__} - -\end{description} +\end{methoddescni} \subsection{Emulating callable objects\label{callable-types}} -\begin{description} - -\item[{\tt __call__(self, [args...])}] +\begin{methoddescni}{__call__}{self\optional{, args...}} Called when the instance is ``called'' as a function; if this method -is defined, \code{x(arg1, arg2, ...)} is a shorthand for -\code{x.__call__(arg1, arg2, ...)}. +is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for +\code{\var{x}.__call__(arg1, arg2, ...)}. \ttindex{__call__} \indexii{call}{instance} - -\end{description} +\end{methoddescni} \subsection{Emulating sequence and mapping types\label{sequence-types}} @@ -994,7 +994,7 @@ sequence, and the method \method{__getslice__()} (see below) should be defined. It is also recommended that mappings provide methods \method{keys()}, \method{values()}, \method{items()}, \method{has_key()}, \method{get()}, \method{clear()}, \method{copy()}, - and \method{update()} behaving similar to those for +and \method{update()} behaving similar to those for Python's standard dictionary objects; mutable sequences should provide methods \method{append()}, \method{count()}, \method{index()}, \method{insert()}, \method{pop()}, \method{remove()}, \method{reverse()} @@ -1026,35 +1026,35 @@ multiplication (meaning repetition) by defining the methods \ttindex{__rmul__} \ttindex{__coerce__} -\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 -that doesn't define a \method{__nonzero__()} method and -whose \method{__len__()} method returns zero is considered to be false in a -Boolean context. +\begin{methoddescni}{__len__}{self} +Called to implement the built-in function +\function{len()}\bifuncindex{len}. Should return the length of the +object, an integer \code{>=} 0. Also, an object that doesn't define a +\method{__nonzero__()} method and whose \method{__len__()} method +returns zero is considered to be false in a Boolean context. \ttindex{__len__} \ttindex{__nonzero__} +\end{methoddescni} -\item[{\tt __getitem__(self, key)}] -Called to implement evaluation of \code{self[key]}. +\begin{methoddescni}{__getitem__}{self, key} +Called to implement evaluation of \code{\var{self}[\var{key}]}. For a sequence types, the accepted keys should be integers. Note that the special interpretation of negative indices (if the class wishes to emulate a sequence type) is up to the \method{__getitem__()} method. \ttindex{__getitem__} +\end{methoddescni} -\item[{\tt __setitem__(self, key, value)}] -Called to implement assignment to \code{self[key]}. Same note as for -\method{__getitem__()}. +\begin{methoddescni}{__setitem__}{self, key, value} +Called to implement assignment to \code{\var{self}[\var{key}]}. Same +note as for \method{__getitem__()}. \ttindex{__setitem__} +\end{methoddescni} -\item[{\tt __delitem__(self, key)}] -Called to implement deletion of \code{self[key]}. Same note as for -\method{__getitem__()}. +\begin{methoddescni}{__delitem__}{self, key} +Called to implement deletion of \code{\var{self}[\var{key}]}. Same +note as for \method{__getitem__()}. \ttindex{__delitem__} - -\end{description} +\end{methoddescni} \subsection{Additional methods for emulation of sequence types% @@ -1065,28 +1065,28 @@ objects. Immutable sequences methods should only define \method{__getslice__()}; mutable sequences, should define all three three methods. -\begin{description} - -\item[{\tt __getslice__(self, i, j)}] -Called to implement evaluation of \code{self[i:j]}. The returned -object should be of the same type as \code{self}. Note that missing -\var{i} or \var{j} in the slice expression are replaced by zero or -\code{sys.maxint}, respectively, and no further transformations on the -indices is performed. The interpretation of negative indices and -indices larger than the length of the sequence is up to the method. +\begin{methoddescni}{__getslice__}{self, i, j} +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, and no further +transformations on the indices is performed. The interpretation of +negative indices and indices larger than the length of the sequence is +up to the method. \ttindex{__getslice__} +\end{methoddescni} -\item[{\tt __setslice__(self, i, j, sequence)}] -Called to implement assignment to \code{self[i:j]}. Same notes for -\var{i} and \var{j} as for \method{__getslice__()}. +\begin{methoddescni}{__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__()}. \ttindex{__setslice__} +\end{methoddescni} -\item[{\tt __delslice__(self, i, j)}] -Called to implement deletion of \code{self[i:j]}. Same notes for -\var{i} and \var{j} as for \method{__getslice__()}. +\begin{methoddescni}{__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__()}. \ttindex{__delslice__} - -\end{description} +\end{methoddescni} Notice that these methods are only invoked when a single slice with a single colon is used. For slice operations involving extended slice @@ -1100,31 +1100,30 @@ 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{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 \optional{, modulo})}]\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 +\begin{methoddescni}{__add__}{self, other} +\methodlineni{__sub__}{self, other} +\methodlineni{__mul__}{self, other} +\methodlineni{__div__}{self, other} +\methodlineni{__mod__}{self, other} +\methodlineni{__divmod__}{self, other} +\methodlineni{__pow__}{self, other\optional{, modulo}} +\methodlineni{__lshift__}{self, other} +\methodlineni{__rshift__}{self, other} +\methodlineni{__and__}{self, other} +\methodlineni{__xor__}{self, other} +\methodlineni{__or__}{self, other} These functions are called to implement the binary arithmetic operations (\code{+}, -\code{-}, \code{*}, \code{/}, \code{\%}, \function{divmod()}, \function{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 \function{__pow__()} should be defined to accept an optional -third argument if the ternary version of the built-in \function{pow()} -function is to be supported. +\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. \ttindex{__or__} \ttindex{__xor__} \ttindex{__and__} @@ -1137,31 +1136,32 @@ function is to be supported. \ttindex{__mul__} \ttindex{__sub__} \ttindex{__add__} - -\item[{\tt __radd__(self, other)}]\itemjoin -\item[{\tt __rsub__(self, other)}]\itemjoin -\item[{\tt __rmul__(self, other)}]\itemjoin -\item[{\tt __rdiv__(self, other)}]\itemjoin -\item[{\tt __rmod__(self, other)}]\itemjoin -\item[{\tt __rdivmod__(self, other)}]\itemjoin -\item[{\tt __rpow__(self, other)}]\itemjoin -\item[{\tt __rlshift__(self, other)}]\itemjoin -\item[{\tt __rrshift__(self, other)}]\itemjoin -\item[{\tt __rand__(self, other)}]\itemjoin -\item[{\tt __rxor__(self, other)}]\itemjoin -\item[{\tt __ror__(self, other)}]\itembreak +\end{methoddescni} + +\begin{methoddescni}{__radd__}{self, other} +\methodlineni{__rsub__}{self, other} +\methodlineni{__rmul__}{self, other} +\methodlineni{__rdiv__}{self, other} +\methodlineni{__rmod__}{self, other} +\methodlineni{__rdivmod__}{self, other} +\methodlineni{__rpow__}{self, other} +\methodlineni{__rlshift__}{self, other} +\methodlineni{__rrshift__}{self, other} +\methodlineni{__rand__}{self, other} +\methodlineni{__rxor__}{self, other} +\methodlineni{__ror__}{self, other} These functions are called to implement the binary arithmetic operations (\code{+}, -\code{-}, \code{*}, \code{/}, \code{\%}, \function{divmod()}, \function{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()} will not try calling -\method{__rpow__()} (the coercion rules would become too +\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). \ttindex{__or__} \ttindex{__xor__} @@ -1175,44 +1175,52 @@ complicated). \ttindex{__mul__} \ttindex{__sub__} \ttindex{__add__} +\end{methoddescni} -\item[{\tt __neg__(self)}]\itemjoin -\item[{\tt __pos__(self)}]\itemjoin -\item[{\tt __abs__(self)}]\itemjoin -\item[{\tt __invert__(self)}]\itembreak +\begin{methoddescni}{__neg__}{self} +\methodlineni{__pos__}{self} +\methodlineni{__abs__}{self} +\methodlineni{__invert__}{self} Called to implement the unary arithmetic operations (\code{-}, \code{+}, -\function{abs()} and \code{~}). +\function{abs()}\bifuncindex{abs} and \code{~}). \ttindex{__invert__} \ttindex{__abs__} \ttindex{__pos__} \ttindex{__neg__} - -\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. +\end{methoddescni} + +\begin{methoddescni}{__int__}{self} +\methodlineni{__long__}{self} +\methodlineni{__float__}{self} +Called to implement the built-in functions +\function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long} +and \function{float()}\bifuncindex{float}. Should return a value of +the appropriate type. \ttindex{__float__} \ttindex{__long__} \ttindex{__int__} +\end{methoddescni} -\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. +\begin{methoddescni}{__oct__}{self} +\methodlineni{__hex__}{self} +Called to implement the built-in functions +\function{oct()}\bifuncindex{oct} and +\function{hex()}\bifuncindex{hex}. Should return a string value. \ttindex{__hex__} \ttindex{__oct__} +\end{methoddescni} -\item[{\tt __coerce__(self, other)}] +\begin{methoddescni}{__coerce__}{self, other} +\ttindex{__coerce__} Called to implement ``mixed-mode'' numeric arithmetic. Should either -return a 2-tuple containing \code{self} and \code{other} converted to +return a 2-tuple containing \var{self} and \var{other} converted to a common numeric type, or \code{None} if conversion is possible. 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). -\ttindex{__coerce__} +\end{methoddescni} \strong{Coercion rules}: to evaluate \var{x} \var{op} \var{y}, the following steps are taken (where \method{__op__()} and @@ -1281,5 +1289,3 @@ instance. \end{itemize} \end{itemize} - -\end{description} -- cgit v1.2.3-65-gdbad