[Python-checkins] python/dist/src/Doc/ref ref2.tex,1.46,1.47 ref3.tex,1.96,1.97 ref6.tex,1.60,1.61
rhettinger@users.sourceforge.net
rhettinger@users.sourceforge.net
Sun, 19 Jan 2003 05:08:21 -0800
Update of /cvsroot/python/python/dist/src/Doc/ref
In directory sc8-pr-cvs1:/tmp/cvs-serv31488
Modified Files:
ref2.tex ref3.tex ref6.tex
Log Message:
SF patch #634866: Alex Martelli's corrections to the ref manual.
Backport candidate. All but one or two of these changes
are applicable to 2.2.2.
Index: ref2.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref2.tex,v
retrieving revision 1.46
retrieving revision 1.47
diff -C2 -d -r1.46 -r1.47
*** ref2.tex 24 Oct 2002 19:57:37 -0000 1.46
--- ref2.tex 19 Jan 2003 13:08:18 -0000 1.47
***************
*** 327,331 ****
\end{tableiii}
! (XXX need section references here.)
Note:
--- 327,333 ----
\end{tableiii}
! See sections: \ref{import}, ``The \keyword{import} statement'';
! \ref{specialnames}, ``Special method names'';
! \ref{atom-identifiers}, ``Identifiers (Names)''.
Note:
***************
*** 563,578 ****
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:
\begin{verbatim}
7 2147483647 0177 0x80000000
3L 79228162514264337593543950336L 0377L 0x100000000L
\end{verbatim}
--- 565,587 ----
digit \character{1}.
! 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}
Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.96
retrieving revision 1.97
diff -C2 -d -r1.96 -r1.97
*** ref3.tex 17 Dec 2002 16:15:12 -0000 1.96
--- ref3.tex 19 Jan 2003 13:08:18 -0000 1.97
***************
*** 18,22 ****
representing its identity (currently implemented as its address).
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
--- 18,30 ----
representing its identity (currently implemented as its address).
An object's \dfn{type} is
! 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
***************
*** 48,52 ****
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
become unreachable, but is not guaranteed to collect garbage
containing circular references. See the
--- 56,60 ----
reachable. (Implementation note: the current implementation uses a
reference-counting scheme with (optional) delayed detection of
! 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
***************
*** 101,105 ****
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
numbers, efficiently stored arrays of integers, etc.).
--- 109,114 ----
Below is a list of the types that are built into Python. Extension
! 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.).
***************
*** 171,175 ****
size, but not smaller.)
When the result of an operation would fall 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
--- 180,185 ----
size, but not smaller.)
When the result of an operation would fall outside this range, the
! 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
***************
*** 203,209 ****
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}
--- 213,219 ----
meaningful interpretation of shift and mask operations involving
negative integers and the least surprises when switching between the
! plain and long integer domains. Any operation except left shift,
if it yields a result in the plain integer domain without causing
! overflow, will yield the same result in the long integer domain or
when using mixed operands.
\indexii{integer}{representation}
***************
*** 211,216 ****
\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.
Python does not support single-precision floating point numbers; the
savings in processor and memory usage that are usually the reason for using
--- 221,226 ----
\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 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
***************
*** 221,231 ****
\indexii{floating point}{number}
\indexii{C}{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}.
\obindex{complex}
\indexii{complex}{number}
--- 231,242 ----
\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 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}
***************
*** 350,354 ****
\index{slicing}
! There is currently a single mutable sequence type:
\begin{description}
--- 361,365 ----
\index{slicing}
! There is currently a single intrinsic mutable sequence type:
\begin{description}
***************
*** 396,400 ****
dictionary entry.
! Dictionaries are mutable; they are created by the
\code{\{...\}} notation (see section \ref{dict}, ``Dictionary
Displays'').
--- 407,411 ----
dictionary entry.
! Dictionaries are mutable; they can be created by the
\code{\{...\}} notation (see section \ref{dict}, ``Dictionary
Displays'').
***************
*** 552,559 ****
\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()}, assuming
! \var{list} is a list object.
In this case, the special read-only attribute \member{__self__} is set
to the object denoted by \var{list}.
--- 563,570 ----
\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{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}.
***************
*** 941,946 ****
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
initialization of the base class part of the instance; for example:
\samp{BaseClass.__init__(\var{self}, [\var{args}...])}. As a special
--- 952,957 ----
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, 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
***************
*** 953,957 ****
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
must explicitly call it to ensure proper deletion of the base class
part of the instance. Note that it is possible (though not recommended!)
--- 964,969 ----
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, 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!)
***************
*** 967,973 ****
\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
count reaches zero. Some common situations that may prevent the
! reference count of an object to go 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
--- 979,985 ----
\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 \code{x}'s reference
count reaches zero. Some common situations that may prevent the
! 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
***************
*** 1015,1018 ****
--- 1027,1033 ----
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
***************
*** 1054,1058 ****
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.
There are no reflected (swapped-argument) versions of these methods
--- 1069,1073 ----
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{False} is used for false and \code{True} for true.
There are no reflected (swapped-argument) versions of these methods
***************
*** 1079,1083 ****
keys.
(Note: the restriction that exceptions are not propagated by
! \method{__cmp__()} has been removed in Python 1.5.)
\bifuncindex{cmp}
\index{comparisons}
--- 1094,1098 ----
keys.
(Note: the restriction that exceptions are not propagated by
! \method{__cmp__()} has been removed since Python 1.5.)
\bifuncindex{cmp}
\index{comparisons}
***************
*** 1201,1207 ****
that mappings provide the methods \method{keys()}, \method{values()},
\method{items()}, \method{has_key()}, \method{get()}, \method{clear()},
\method{copy()}, 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()}
and \method{sort()}, like Python standard list objects. Finally,
--- 1216,1229 ----
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. 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,
***************
*** 1215,1225 ****
the \code{in} operator; for mappings, \code{in} should be equivalent
of \method{has_key()}; for sequences, it should search through the
! values.
\withsubitem{(mapping object method)}{
\ttindex{keys()}
\ttindex{values()}
\ttindex{items()}
\ttindex{has_key()}
\ttindex{get()}
\ttindex{clear()}
\ttindex{copy()}
--- 1237,1257 ----
the \code{in} operator; for mappings, \code{in} should be equivalent
of \method{has_key()}; for sequences, it should search through the
! 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()}
***************
*** 1229,1232 ****
--- 1261,1265 ----
\ttindex{append()}
\ttindex{count()}
+ \ttindex{extend()}
\ttindex{index()}
\ttindex{insert()}
***************
*** 1241,1245 ****
\ttindex{__rmul__()}
\ttindex{__imul__()}
! \ttindex{__contains__()}}
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
--- 1274,1279 ----
\ttindex{__rmul__()}
\ttindex{__imul__()}
! \ttindex{__contains__()}
! \ttindex{__iter__()}}
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
***************
*** 1316,1322 ****
\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.
--- 1350,1356 ----
\label{sequence-methods}}
! 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.
***************
*** 1342,1348 ****
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}
--- 1376,1384 ----
Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
! 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}
***************
*** 1350,1356 ****
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}
--- 1386,1394 ----
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,
! 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}
***************
*** 1388,1393 ****
\end{verbatim}
! Note the calls to \function{max()}; these are actually necessary due
! to 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
--- 1426,1431 ----
\end{verbatim}
! 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
Index: ref6.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref6.tex,v
retrieving revision 1.60
retrieving revision 1.61
diff -C2 -d -r1.60 -r1.61
*** ref6.tex 16 Jan 2003 11:30:08 -0000 1.60
--- ref6.tex 19 Jan 2003 13:08:18 -0000 1.61
***************
*** 639,645 ****
\indexii{name}{binding}
\kwindex{from}
- % XXX Need to define what ``initialize'' means here
! The system maintains a table of modules that have been initialized,
indexed by module name. This table is
accessible as \code{sys.modules}. When a module name is found in
--- 639,651 ----
\indexii{name}{binding}
\kwindex{from}
! 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