SF patch #634866: Alex Martelli's corrections to the ref manual.

rhettinger · rhettinger · commit e701dcbabd43 · 2003-01-19T13:08:18.000Z
Backport candidate.  All but one or two of these changes
are applicable to 2.2.2.
diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex
@@ -326,7 +326,9 @@ \subsection{Reserved classes of identifiers\label{id-classes}}
 \lineiii{__*}{Class-private name mangling}{}
 \end{tableiii}
 
-(XXX need section references here.)
+See sections: \ref{import}, ``The \keyword{import} statement'';
+\ref{specialnames}, ``Special method names'';
+\ref{atom-identifiers}, ``Identifiers (Names)''.
 
 Note:
 
@@ -562,18 +564,25 @@ \subsection{Integer and long integer literals\label{integers}}
 use \character{L}, since the letter \character{l} looks too much like the
 digit \character{1}.
 
-Plain integer decimal literals must be at most 2147483647 (i.e., the
-largest positive integer, using 32-bit arithmetic).  Plain octal and
-hexadecimal literals may be as large as 4294967295, but values larger
-than 2147483647 are converted to a negative value by subtracting
-4294967296.  There is no limit for long integer literals apart from
-what can be stored in available memory.
-
-Some examples of plain and long integer literals:
+Plain integer decimal literals that are above the largest representable
+plain integer (e.g., 2147483647 when using 32-bit arithmetic) are accepted
+as if they were long integers instead.  Octal and hexadecimal literals
+behave similarly, but when in the range just above the largest representable
+plain integer but below the largest unsigned 32-bit number (on a machine
+using 32-bit arithmetic), 4294967296, they are taken as the negative plain
+integer obtained by subtracting 4294967296 from their unsigned value.  There
+is no limit for long integer literals apart from what can be stored in
+available memory.  For example, 0xdeadbeef is taken, on a 32-bit machine,
+as the value -559038737, while 0xdeadbeeffeed is taken as the value
+244837814107885L.
+
+Some examples of plain integer literals (first row) and long integer
+literals (second and third rows):
 
 \begin{verbatim}
 7     2147483647                        0177    0x80000000
 3L    79228162514264337593543950336L    0377L   0x100000000L
+      79228162514264337593543950336             0xdeadbeeffeed						    
 \end{verbatim}
 
 
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
@@ -17,7 +17,15 @@ \section{Objects, values and types\label{objects}}
 \function{id()}\bifuncindex{id} function returns an integer
 representing its identity (currently implemented as its address).
 An object's \dfn{type} is
-also unchangeable.  It determines the operations that an object
+also unchangeable.\footnote{Since Python 2.2, a gradual merging of
+types and classes has been started that makes this and a few other
+assertions made in this manual not 100\% accurate and complete:
+for example, it \emph{is} now possible in some cases to change an
+object's type, under certain controlled conditions.  Until this manual
+undergoes extensive revision, it must now be taken as authoritative
+only regarding ``classic classes'', that are still the default, for
+compatibility purposes, in Python 2.2 and 2.3.}
+An object's type determines the operations that the object
 supports (e.g., ``does it have a length?'') and also defines the
 possible values for objects of that type.  The
 \function{type()}\bifuncindex{type} function returns an object's type
@@ -47,7 +55,7 @@ \section{Objects, values and types\label{objects}}
 implemented, as long as no objects are collected that are still
 reachable.  (Implementation note: the current implementation uses a
 reference-counting scheme with (optional) delayed detection of
-cyclicly linked garbage, which collects most objects as soon as they
+cyclically linked garbage, which collects most objects as soon as they
 become unreachable, but is not guaranteed to collect garbage
 containing circular references.  See the
 \citetitle[../lib/module-gc.html]{Python Library Reference} for
@@ -100,7 +108,8 @@ \section{Objects, values and types\label{objects}}
 \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
+modules (written in C, Java, or other languages, depending on
+the implementation) can define additional types.  Future versions of
 Python may add types to the type hierarchy (e.g., rational
 numbers, efficiently stored arrays of integers, etc.).
 \index{type}
@@ -170,7 +179,8 @@ \section{The standard type hierarchy\label{types}}
 (The range may be larger on machines with a larger natural word
 size, but not smaller.)
 When the result of an operation would fall outside this range, the
-exception \exception{OverflowError} is raised.
+result is normally returned as a long integer (in some cases, the
+exception \exception{OverflowError} is raised instead).
 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
@@ -202,16 +212,16 @@ \section{The standard type hierarchy\label{types}}
 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,
+plain and long integer domains.  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
+overflow, 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.
+You are at the mercy of the underlying machine architecture (and
+C or Java implementation) for the accepted range and handling of overflow.
 Python does not support single-precision floating point numbers; the
 savings in processor and memory usage that are usually the reason for using
 these is dwarfed by the overhead of using objects in Python, so there
@@ -220,13 +230,14 @@ \section{The standard type hierarchy\label{types}}
 \obindex{floating point}
 \indexii{floating point}{number}
 \indexii{C}{language}
+\indexii{Java}{language}
 
 \item[Complex numbers]
 These represent complex numbers as a pair of machine-level double
 precision floating point numbers.  The same caveats apply as for
-floating point numbers.  The real and imaginary value of a complex
-number \code{z} can be retrieved through the attributes \code{z.real}
-and \code{z.imag}.
+floating point numbers.  The real and imaginary parts of a complex
+number \code{z} can be retrieved through the read-only attributes
+\code{z.real} and \code{z.imag}.
 \obindex{complex}
 \indexii{complex}{number}
 
@@ -349,7 +360,7 @@ \section{The standard type hierarchy\label{types}}
 \index{subscription}
 \index{slicing}
 
-There is currently a single mutable sequence type:
+There is currently a single intrinsic mutable sequence type:
 
 \begin{description}
 
@@ -395,7 +406,7 @@ \section{The standard type hierarchy\label{types}}
 \code{1.0}) then they can be used interchangeably to index the same
 dictionary entry.
 
-Dictionaries are mutable; they are created by the
+Dictionaries are mutable; they can be created by the
 \code{\{...\}} notation (see section \ref{dict}, ``Dictionary
 Displays'').
 
@@ -551,10 +562,10 @@ \section{The standard type hierarchy\label{types}}
 
 \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
+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()}, assuming
-\var{list} is a list object.
+\code{\var{alist}.append()}, assuming
+\var{alist} is a list object.
 In this case, the special read-only attribute \member{__self__} is set
 to the object denoted by \var{list}.
 \obindex{built-in method}
@@ -940,8 +951,8 @@ \subsection{Basic customization\label{customization}}
 \begin{methoddesc}[object]{__init__}{self\optional{, \moreargs}}
 Called\indexii{class}{constructor} when the instance is created.  The
 arguments are those passed to the class constructor expression.  If a
-base class has an \method{__init__()} method the derived class's
-\method{__init__()} method must explicitly call it to ensure proper
+base class has an \method{__init__()} method, the derived class's
+\method{__init__()} method, if any, must explicitly call it to ensure proper
 initialization of the base class part of the instance; for example:
 \samp{BaseClass.__init__(\var{self}, [\var{args}...])}.  As a special
 contraint on constructors, no value may be returned; doing so will
@@ -952,7 +963,8 @@ \subsection{Basic customization\label{customization}}
 \begin{methoddesc}[object]{__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
+has a \method{__del__()} method, the derived class's \method{__del__()}
+method, if any,
 must explicitly call it to ensure proper deletion of the base class
 part of the instance.  Note that it is possible (though not recommended!)
 for the \method{__del__()}
@@ -966,9 +978,9 @@ \subsection{Basic customization\label{customization}}
 \begin{notice}
 \samp{del x} doesn't directly call
 \code{x.__del__()} --- the former decrements the reference count for
-\code{x} by one, and the latter is only called when its reference
+\code{x} by one, and the latter is only called when \code{x}'s reference
 count reaches zero.  Some common situations that may prevent the
-reference count of an object to go to zero include: circular
+reference count of an object from going to zero include: circular
 references between objects (e.g., a doubly-linked list or a tree data
 structure with parent and child pointers); a reference to the object
 on the stack frame of a function that caught an exception (the
@@ -1014,6 +1026,9 @@ \subsection{Basic customization\label{customization}}
 this is not possible, a string of the form \samp{<\var{...some useful
 description...}>} should be returned.  The return value must be a
 string object.
+If a class defines \method{__repr__()} but not \method{__str__()},
+then \method{__repr__()} is also used when an ``informal'' string
+representation of instances of that class is required.		     
 
 This is typically used for debugging, so it is important that the
 representation is information-rich and unambiguous.
@@ -1053,7 +1068,7 @@ \subsection{Basic customization\label{customization}}
 These methods can return any value, but if the comparison operator is
 used in a Boolean context, the return value should be interpretable as
 a Boolean value, else a \exception{TypeError} will be raised.
-By convention, \code{0} is used for false and \code{1} for true.
+By convention, \code{False} is used for false and \code{True} for true.
 
 There are no reflected (swapped-argument) versions of these methods
 (to be used when the left argument does not support the operation but
@@ -1078,7 +1093,7 @@ \subsection{Basic customization\label{customization}}
 support custom comparison operations and are usable as dictionary
 keys.
 (Note: the restriction that exceptions are not propagated by
-\method{__cmp__()} has been removed in Python 1.5.)
+\method{__cmp__()} has been removed since Python 1.5.)
 \bifuncindex{cmp}
 \index{comparisons}
 \end{methoddesc}
@@ -1200,9 +1215,16 @@ \subsection{Emulating container types\label{sequence-types}}
 defined to handle simple, but not extended slices.) It is also recommended
 that mappings provide the methods \method{keys()}, \method{values()},
 \method{items()}, \method{has_key()}, \method{get()}, \method{clear()},
+\method{setdefault()}, \method{iterkeys()}, \method{itervalues()},
+\method{iteritems()}, \method{pop()},, \method{popitem()},		     
 \method{copy()}, and \method{update()} behaving similar to those for
-Python's standard dictionary objects; mutable sequences should provide
+Python's standard dictionary objects.  The \module{UserDict} module
+provides a \class{DictMixin} class to help create those methods
+from a base set of \method{__getitem__()}, \method{__setitem__()},
+\method{__delitem__()}, and \method{keys()}.		     
+Mutable sequences should provide
 methods \method{append()}, \method{count()}, \method{index()},
+\method{extend()},		     
 \method{insert()}, \method{pop()}, \method{remove()}, \method{reverse()}
 and \method{sort()}, like Python standard list objects.  Finally,
 sequence types should implement addition (meaning concatenation) and
@@ -1214,20 +1236,31 @@ \subsection{Emulating container types\label{sequence-types}}
 implement the \method{__contains__()} method to allow efficient use of
 the \code{in} operator; for mappings, \code{in} should be equivalent
 of \method{has_key()}; for sequences, it should search through the
-values.
+values.  It is further recommended that both mappings and sequences
+implement the \method{__iter__()} method to allow efficient iteration
+through the container; for mappings, \method{__iter__()} should be
+the same as \method{iterkeys()}; for sequences, it should iterate
+through the values.
 \withsubitem{(mapping object method)}{
   \ttindex{keys()}
   \ttindex{values()}
   \ttindex{items()}
+  \ttindex{iterkeys()}
+  \ttindex{itervalues()}
+  \ttindex{iteritems()}    
   \ttindex{has_key()}
   \ttindex{get()}
+  \ttindex{setdefault()}
+  \ttindex{pop()}      
+  \ttindex{popitem()}    
   \ttindex{clear()}
   \ttindex{copy()}
   \ttindex{update()}
   \ttindex{__contains__()}}
 \withsubitem{(sequence object method)}{
   \ttindex{append()}
   \ttindex{count()}
+  \ttindex{extend()}    
   \ttindex{index()}
   \ttindex{insert()}
   \ttindex{pop()}
@@ -1240,7 +1273,8 @@ \subsection{Emulating container types\label{sequence-types}}
   \ttindex{__mul__()}
   \ttindex{__rmul__()}
   \ttindex{__imul__()}
-  \ttindex{__contains__()}}
+  \ttindex{__contains__()}
+  \ttindex{__iter__()}}		     
 \withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
 
 \begin{methoddesc}[container object]{__len__}{self}
@@ -1315,9 +1349,9 @@ \subsection{Emulating container types\label{sequence-types}}
 \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
+The following optional methods can be defined to further emulate sequence
+objects.  Immutable sequences methods should at most only define
+\method{__getslice__()}; mutable sequences might define all three
 three methods.
 
 \begin{methoddesc}[sequence object]{__getslice__}{self, i, j}
@@ -1341,17 +1375,21 @@ \subsection{Additional methods for emulation of sequence types
 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.
+This method is deprecated. If no \method{__setslice__()} is found,
+or for extended slicing of the form
+\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a
+slice object is created, and passed to \method{__setitem__()},
+instead of \method{__setslice__()} being called.
 \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.
+This method is deprecated. If no \method{__delslice__()} is found,
+or for extended slicing of the form
+\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a
+slice object is created, and passed to \method{__delitem__()},
+instead of \method{__delslice__()} being called.
 \end{methoddesc}
 
 Notice that these methods are only invoked when a single slice with a
@@ -1387,8 +1425,8 @@ \subsection{Additional methods for emulation of sequence types
     ...
 \end{verbatim}
 
-Note the calls to \function{max()}; these are actually necessary due
-to the handling of negative indices before the
+Note the calls to \function{max()}; these are necessary because of
+the handling of negative indices before the
 \method{__*slice__()} methods are called.  When negative indexes are
 used, the \method{__*item__()} methods receive them as provided, but
 the \method{__*slice__()} methods get a ``cooked'' form of the index
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
@@ -638,9 +638,15 @@ \section{The \keyword{import} statement \label{import}}
 \indexii{importing}{module}
 \indexii{name}{binding}
 \kwindex{from}
-% XXX Need to define what ``initialize'' means here
 
-The system maintains a table of modules that have been initialized,
+In this context, to ``initialize'' a built-in or extension module means to
+call an initialization function that the module must provide for the purpose
+(in the reference implementation, the function's name is obtained by
+prepending string ``init'' to the module's name); to ``initialize'' a
+Python-coded module means to execute the module's body.
+  
+The system maintains a table of modules that have been or are being
+initialized,
 indexed by module name.  This table is
 accessible as \code{sys.modules}.  When a module name is found in
 this table, step (1) is finished.  If not, a search for a module
