Restructured library documentation

1 files changed, 618 insertions, 0 deletions

diff --git a/Doc/libtypes.tex b/Doc/libtypes.tex
new file mode 100644
index 0000000..be8d990
--- /dev/null
+++ b/Doc/libtypes.tex
@@ -0,0 +1,618 @@
+\section{Built-in Types}
+
+The following sections describe the standard types that are built into
+the interpreter.  These are the numeric types, sequence types, and
+several others, including types themselves.  There is no explicit
+Boolean type; use integers instead.
+\indexii{built-in}{types}
+\indexii{Boolean}{type}
+
+Some operations are supported by several object types; in particular,
+all objects can be compared, tested for truth value, and converted to
+a string (with the \code{`{\rm \ldots}`} notation).  The latter conversion is
+implicitly used when an object is written by the \code{print} statement.
+\stindex{print}
+
+\subsection{Truth Value Testing}
+
+Any object can be tested for truth value, for use in an \code{if} or
+\code{while} condition or as operand of the Boolean operations below.
+The following values are false:
+\stindex{if}
+\stindex{while}
+\indexii{truth}{value}
+\indexii{Boolean}{operations}
+\index{false}
+
+\begin{itemize}
+\renewcommand{\indexsubitem}{(Built-in object)}
+
+\item	\code{None}
+	\ttindex{None}
+
+\item	zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}.
+
+\item	any empty sequence, e.g., \code{''}, \code{()}, \code{[]}.
+
+\item	any empty mapping, e.g., \code{\{\}}.
+
+\end{itemize}
+
+\emph{All} other values are true --- so objects of many types are
+always true.
+\index{true}
+
+\subsection{Boolean Operations}
+
+These are the Boolean operations:
+\indexii{Boolean}{operations}
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes}
+  \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)}
+  \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)}
+  \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{}
+\end{tableiii}
+\opindex{and}
+\opindex{or}
+\opindex{not}
+
+\noindent
+Notes:
+
+\begin{description}
+
+\item[(1)]
+These only evaluate their second argument if needed for their outcome.
+
+\end{description}
+
+\subsection{Comparisons}
+
+Comparison operations are supported by all objects:
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Meaning}{Notes}
+  \lineiii{<}{strictly less than}{}
+  \lineiii{<=}{less than or equal}{}
+  \lineiii{>}{strictly greater than}{}
+  \lineiii{>=}{greater than or equal}{}
+  \lineiii{==}{equal}{}
+  \lineiii{<>}{not equal}{(1)}
+  \lineiii{!=}{not equal}{(1)}
+  \lineiii{is}{object identity}{}
+  \lineiii{is not}{negated object identity}{}
+\end{tableiii}
+\indexii{operator}{comparison}
+\opindex{==} % XXX *All* others have funny characters < ! >
+\opindex{is}
+\opindex{is not}
+
+\noindent
+Notes:
+
+\begin{description}
+
+\item[(1)]
+\code{<>} and \code{!=} are alternate spellings for the same operator.
+(I couldn't choose between \ABC{} and \C{}! :-)
+\indexii{\ABC{}}{language}
+\indexii{\C{}}{language}
+
+\end{description}
+
+Objects of different types, except different numeric types, never
+compare equal; such objects are ordered consistently but arbitrarily
+(so that sorting a heterogeneous array yields a consistent result).
+Furthermore, some types (e.g., windows) support only a degenerate
+notion of comparison where any two objects of that type are unequal.
+Again, such objects are ordered arbitrarily but consistently.
+\indexii{types}{numeric}
+\indexii{objects}{comparing}
+
+(Implementation note: objects of different types except numbers are
+ordered by their type names; objects of the same types that don't
+support proper comparison are ordered by their address.)
+
+Two more operations with the same syntactic priority, \code{in} and
+\code{not in}, are supported only by sequence types (below).
+\opindex{in}
+\opindex{not in}
+
+\subsection{Numeric Types}
+
+There are three numeric types: \dfn{plain integers}, \dfn{long integers}, and
+\dfn{floating point numbers}.  Plain integers (also just called \dfn{integers})
+are implemented using \code{long} in \C{}, which gives them at least 32
+bits of precision.  Long integers have unlimited precision.  Floating
+point numbers are implemented using \code{double} in \C{}.  All bets on
+their precision are off unless you happen to know the machine you are
+working with.
+\indexii{numeric}{types}
+\indexii{integer}{types}
+\indexii{integer}{type}
+\indexiii{long}{integer}{type}
+\indexii{floating point}{type}
+\indexii{\C{}}{language}
+
+Numbers are created by numeric literals or as the result of built-in
+functions and operators.  Unadorned integer literals (including hex
+and octal numbers) yield plain integers.  Integer literals with an \samp{L}
+or \samp{l} suffix yield long integers
+(\samp{L} is preferred because \code{1l} looks too much like eleven!).
+Numeric literals containing a decimal point or an exponent sign yield
+floating point numbers.
+\indexii{numeric}{literals}
+\indexii{integer}{literals}
+\indexiii{long}{integer}{literals}
+\indexii{floating point}{literals}
+\indexii{hexadecimal}{literals}
+\indexii{octal}{literals}
+
+Python fully supports mixed arithmetic: when a binary arithmetic
+operator has operands of different numeric types, the operand with the
+``smaller'' type is converted to that of the other, where plain
+integer is smaller than long integer is smaller than floating point.
+Comparisons between numbers of mixed type use the same rule.%
+\footnote{As a consequence, the list \code{[1, 2]} is considered equal
+	to \code{[1.0, 2.0]}, and similar for tuples.}
+The functions \code{int()}, \code{long()} and \code{float()} can be used
+to coerce numbers to a specific type.
+\index{arithmetic}
+\bifuncindex{int}
+\bifuncindex{long}
+\bifuncindex{float}
+
+All numeric types support the following operations:
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes}
+  \lineiii{abs(\var{x})}{absolute value of \var{x}}{}
+  \lineiii{int(\var{x})}{\var{x} converted to integer}{(1)}
+  \lineiii{long(\var{x})}{\var{x} converted to long integer}{(1)}
+  \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
+  \lineiii{-\var{x}}{\var{x} negated}{}
+  \lineiii{+\var{x}}{\var{x} unchanged}{}
+  \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
+  \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
+  \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
+  \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(2)}
+  \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{}
+  \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)}
+  \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
+\end{tableiii}
+\indexiii{operations on}{numeric}{types}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)]
+Conversion from floating point to (long or plain) integer may round or
+% XXXJH xref here
+truncate as in \C{}; see functions \code{floor} and \code{ceil} in module
+\code{math} for well-defined conversions.
+\indexii{numeric}{conversions}
+\ttindex{math}
+\indexii{\C{}}{language}
+
+\item[(2)]
+For (plain or long) integer division, the result is an integer; it
+always truncates towards zero.
+% XXXJH integer division is better defined nowadays
+\indexii{integer}{division}
+\indexiii{long}{integer}{division}
+
+\item[(3)]
+See the section on built-in functions for an exact definition.
+
+\end{description}
+% XXXJH exceptions: overflow (when? what operations?) zerodivision
+
+\subsubsection{Bit-string Operations on Integer Types.}
+
+Plain and long integer types support additional operations that make
+sense only for bit-strings.  Negative numbers are treated as their 2's
+complement value:
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes}
+  \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
+  \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
+  \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
+  \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
+  \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{}
+  \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{}
+\end{tableiii}
+% XXXJH what's `left'? `right'? maybe better use lsb or msb or something
+\indexiii{operations on}{integer}{types}
+\indexii{bit-string}{operations}
+\indexii{shifting}{operations}
+\indexii{masking}{operations}
+
+\subsection{Sequence Types}
+
+There are three sequence types: strings, lists and tuples.
+Strings literals are written in single quotes: \code{'xyzzy'}.
+Lists are constructed with square brackets,
+separating items with commas:
+\code{[a, b, c]}.
+Tuples are constructed by the comma operator
+(not within square brackets), with or without enclosing parentheses,
+but an empty tuple must have the enclosing parentheses, e.g.,
+\code{a, b, c} or \code{()}.  A single item tuple must have a trailing comma,
+e.g., \code{(d,)}.
+\indexii{sequence}{types}
+\indexii{string}{type}
+\indexii{tuple}{type}
+\indexii{list}{type}
+
+Sequence types support the following operations (\var{s} and \var{t} are
+sequences of the same type; \var{n}, \var{i} and \var{j} are integers):
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes}
+  \lineiii{len(\var{s})}{length of \var{s}}{}
+  \lineiii{min(\var{s})}{smallest item of \var{s}}{}
+  \lineiii{max(\var{s})}{largest item of \var{s}}{}
+  \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{}
+  \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is equal to \var{x}, else \code{1}}{}
+  \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
+  \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{}
+  \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)}
+  \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)}
+\end{tableiii}
+\indexiii{operations on}{sequence}{types}
+\bifuncindex{len}
+\bifuncindex{min}
+\bifuncindex{max}
+\indexii{concatenation}{operation}
+\indexii{repetition}{operation}
+\indexii{subscript}{operation}
+\indexii{slice}{operation}
+\opindex{in}
+\opindex{not in}
+
+\noindent
+Notes:
+
+% XXXJH all TeX-math expressions replaced by python-syntax expressions
+\begin{description}
+  
+\item[(1)] If \var{i} or \var{j} is negative, the index is relative to
+  the end of the string, i.e., \code{len(\var{s}) + \var{i}} or
+  \code{len(\var{s}) + \var{j}} is substituted.  But note that \code{-0} is
+  still \code{0}.
+  
+\item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as
+  the sequence of items with index \var{k} such that \code{\var{i} <=
+  \var{k} < \var{j}}.  If \var{i} or \var{j} is greater than
+  \code{len(\var{s})}, use \code{len(\var{s})}.  If \var{i} is omitted,
+  use \code{0}.  If \var{j} is omitted, use \code{len(\var{s})}.  If
+  \var{i} is greater than or equal to \var{j}, the slice is empty.
+
+\end{description}
+
+\subsubsection{More String Operations.}
+
+String objects have one unique built-in operation: the \code{\%}
+operator (modulo) with a string left argument interprets this string
+as a C sprintf format string to be applied to the right argument, and
+returns the string resulting from this formatting operation.
+
+Unless the format string requires exactly one argument, the right
+argument should be a tuple of the correct size.  The following format
+characters are understood: \%, c, s, i, d, u, o, x, X, e, E, f, g, G.
+Width and precision may be a * to specify that an integer argument
+specifies the actual width or precision.  The flag characters -, +,
+blank, \# and 0 are understood.  The size specifiers h, l or L may be
+present but are ignored.  The ANSI features \code{\%p} and \code{\%n}
+are not supported.  Since Python strings have an explicit length,
+\code{\%s} conversions don't assume that \code{'\\0'} is the end of
+the string.
+
+For safety reasons, huge floating point precisions are truncated;
+\code{\%f} conversions for huge numbers are replaced by
+\code{\%g} conversions.  All other errors raise exceptions.
+
+Additional string operations are defined in standard module
+\code{string} and in built-in module \code{regex}.
+\index{string}
+\index{regex}
+
+\subsubsection{Mutable Sequence Types.}
+
+List objects support additional operations that allow in-place
+modification of the object.
+These operations would be supported by other mutable sequence types
+(when added to the language) as well.
+Strings and tuples are immutable sequence types and such objects cannot
+be modified once created.
+The following operations are defined on mutable sequence types (where
+\var{x} is an arbitrary object):
+\indexiii{mutable}{sequence}{types}
+\indexii{list}{type}
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes}
+  \lineiii{\var{s}[\var{i}] = \var{x}}
+	{item \var{i} of \var{s} is replaced by \var{x}}{}
+  \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
+  	{slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
+  \lineiii{del \var{s}[\var{i}:\var{j}]}
+	{same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
+  \lineiii{\var{s}.append(\var{x})}
+	{same as \code{\var{s}[len(\var{x}):len(\var{x})] = [\var{x}]}}{}
+  \lineiii{\var{s}.count(\var{x})}
+	{return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
+  \lineiii{\var{s}.index(\var{x})}
+	{return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)}
+  \lineiii{\var{s}.insert(\var{i}, \var{x})}
+	{same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{}
+  \lineiii{\var{s}.remove(\var{x})}
+	{same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)}
+  \lineiii{\var{s}.reverse()}
+	{reverses the items of \var{s} in place}{}
+  \lineiii{\var{s}.sort()}
+	{permutes the items of \var{s} to satisfy
+        \code{\var{s}[\var{i}] <= \var{s}[\var{j}]},
+        for \code{\var{i} < \var{j}}}{(2)}
+\end{tableiii}
+\indexiv{operations on}{mutable}{sequence}{types}
+\indexiii{operations on}{sequence}{types}
+\indexiii{operations on}{list}{type}
+\indexii{subscript}{assignment}
+\indexii{slice}{assignment}
+\stindex{del}
+\renewcommand{\indexsubitem}{(list method)}
+\ttindex{append}
+\ttindex{count}
+\ttindex{index}
+\ttindex{insert}
+\ttindex{remove}
+\ttindex{reverse}
+\ttindex{sort}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)] Raises an exception when \var{x} is not found in \var{s}.
+  
+\item[(2)] The \code{sort()} method takes an optional argument
+  specifying a comparison function of two arguments (list items) which
+  should return \code{-1}, \code{0} or \code{1} depending on whether the
+  first argument is considered smaller than, equal to, or larger than the
+  second argument.  Note that this slows the sorting process down
+  considerably; e.g. to sort an array in reverse order it is much faster
+  to use calls to \code{sort()} and \code{reverse()} than to use
+  \code{sort()} with a comparison function that reverses the ordering of
+  the elements.
+\end{description}
+
+\subsection{Mapping Types}
+
+A \dfn{mapping} object maps values of one type (the key type) to
+arbitrary objects.  Mappings are mutable objects.  There is currently
+only one mapping type, the \dfn{dictionary}.  A dictionary's keys are
+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.
+Numeric types used for keys obey the normal rules for numeric
+comparison: if two numbers compare equal (e.g. 1 and 1.0) then they
+can be used interchangeably to index the same dictionary entry.
+
+\indexii{mapping}{types}
+\indexii{dictionary}{type}
+
+Dictionaries are created by placing a comma-separated list of
+\code{\var{key}: \var{value}} pairs within braces, for example:
+\code{\{'jack': 4098, 'sjoerd: 4127\}} or
+\code{\{4098: 'jack', 4127: 'sjoerd\}}.
+
+The following operations are defined on mappings (where \var{a} is a
+mapping, \var{k} is a key and \var{x} is an arbitrary object):
+
+\begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes}
+  \lineiii{len(\var{a})}{the number of items in \var{a}}{}
+  \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)}
+  \lineiii{\var{a}[\var{k}] = \var{x}}{set \code{\var{a}[\var{k}]} to \var{x}}{}
+  \lineiii{del \var{a}[\var{k}]}{remove \code{\var{a}[\var{k}]} from \var{a}}{(1)}
+  \lineiii{\var{a}.items()}{a copy of \var{a}'s list of (key, item) pairs}{(2)}
+  \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)}
+  \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)}
+  \lineiii{\var{a}.has_key(\var{k})}{\code{1} if \var{a} has a key \var{k}, else \code{0}}{}
+\end{tableiii}
+\indexiii{operations on}{mapping}{types}
+\indexiii{operations on}{dictionary}{type}
+\stindex{del}
+\bifuncindex{len}
+\renewcommand{\indexsubitem}{(dictionary method)}
+\ttindex{keys}
+\ttindex{has_key}
+
+% XXXJH some lines above, you talk about `true', elsewhere you
+% explicitely states \code{0} or \code{1}.
+\noindent
+Notes:
+\begin{description}
+\item[(1)] Raises an exception if \var{k} is not in the map.
+
+\item[(2)] Keys and values are listed in random order, but at any
+moment the ordering of the \code{keys()}, \code{values()} and
+\code{items()} lists is the consistent with each other.
+\end{description}
+
+\subsection{Other Built-in Types}
+
+The interpreter supports several other kinds of objects.
+Most of these support only one or two operations.
+
+\subsubsection{Modules.}
+
+The only special operation on a module is attribute access:
+\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} accesses
+a name defined in \var{m}'s symbol table.  Module attributes can be
+assigned to.  (Note that the \code{import} statement is not, strictly
+spoken, an operation on a module object; \code{import \var{foo}} does not
+require a module object named \var{foo} to exist, rather it requires
+an (external) \emph{definition} for a module named \var{foo}
+somewhere.)
+
+A special member of every module is \code{__dict__}.
+This is the dictionary containing the module's symbol table.
+Modifying this dictionary will actually change the module's symbol
+table, but direct assignment to the \code{__dict__} attribute is not
+possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which
+defines \code{\var{m}.a} to be \code{1}, but you can't write \code{\var{m}.__dict__ = \{\}}.
+
+Modules are written like this: \code{<module 'sys'>}.
+
+\subsubsection{Classes and Class Instances.}
+% XXXJH cross ref here
+(See the Python Reference Manual for these.)
+
+\subsubsection{Functions.}
+
+Function objects are created by function definitions.  The only
+operation on a function object is to call it:
+\code{\var{func}(\var{argument-list})}.
+
+There are really two flavors of function objects: built-in functions
+and user-defined functions.  Both support the same operation (to call
+the function), but the implementation is different, hence the
+different object types.
+
+The implementation adds two special read-only attributes:
+\code{\var{f}.func_code} is a function's \dfn{code object} (see below) and
+\code{\var{f}.func_globals} is the dictionary used as the function's
+global name space (this is the same as \code{\var{m}.__dict__} where
+\var{m} is the module in which the function \var{f} was defined).
+
+\subsubsection{Methods.}
+
+Methods are functions that are called using the attribute notation.
+There are two flavors: built-in methods (such as \code{append()} on
+lists) and class instance methods.  Built-in methods are described
+with the types that support them.
+
+The implementation adds two special read-only attributes to class
+instance methods: \code{\var{m}.im_self} is the object whose method this
+is, and \code{\var{m}.im_func} is the function implementing the method.
+Calling \code{\var{m}(\var{arg-1}, \var{arg-2}, {\rm \ldots},
+\var{arg-n})} is completely equivalent to calling
+\code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, \var{arg-2}, {\rm
+\ldots}, \var{arg-n})}.
+
+(See the Python Reference Manual for more info.)
+
+\subsubsection{Type Objects.}
+
+Type objects represent the various object types.  An object's type is
+% XXXJH xref here
+accessed by the built-in function \code{type()}.  There are no special
+operations on types.
+
+Types are written like this: \code{<type 'int'>}.
+
+\subsubsection{The Null Object.}
+
+This object is returned by functions that don't explicitly return a
+value.  It supports no special operations.  There is exactly one null
+object, named \code{None} (a built-in name).
+
+It is written as \code{None}.
+
+\subsubsection{File Objects.}
+
+File objects are implemented using \C{}'s \code{stdio} package and can be
+% XXXJH xref here
+created with the built-in function \code{open()} described under
+Built-in Functions below.
+
+When a file operation fails for an I/O-related reason, the exception
+\code{IOError} is raised.  This includes situations where the
+operation is not defined for some reason, like \code{seek()} on a tty
+device or writing a file opened for reading.
+
+Files have the following methods:
+
+
+\renewcommand{\indexsubitem}{(file method)}
+
+\begin{funcdesc}{close}{}
+  Close the file.  A closed file cannot be read or written anymore.
+\end{funcdesc}
+
+\begin{funcdesc}{flush}{}
+  Flush the internal buffer, like \code{stdio}'s \code{fflush()}.
+\end{funcdesc}
+
+\begin{funcdesc}{isatty}{}
+  Return \code{1} if the file is connected to a tty(-like) device, else
+  \code{0}.
+\end{funcdesc}
+
+\begin{funcdesc}{read}{size}
+  Read at most \var{size} bytes from the file (less if the read hits
+  \EOF{} or no more data is immediately available on a pipe, tty or
+  similar device).  If the \var{size} argument is omitted, read all
+  data until \EOF{} is reached.  The bytes are returned as a string
+  object.  An empty string is returned when \EOF{} is encountered
+  immediately.  (For certain files, like ttys, it makes sense to
+  continue reading after an \EOF{} is hit.)
+\end{funcdesc}
+
+\begin{funcdesc}{readline}{}
+  Read one entire line from the file.  A trailing newline character is
+  kept in the string (but may be absent when a file ends with an
+  incomplete line).  An empty string is returned when \EOF{} is hit
+  immediately.  Note: unlike \code{stdio}'s \code{fgets()}, the returned
+  string contains null characters (\code{'\e 0'}) if they occurred in the
+  input.
+\end{funcdesc}
+
+\begin{funcdesc}{readlines}{}
+  Read until \EOF{} using \code{readline()} and return a list containing
+  the lines thus read.
+\end{funcdesc}
+
+\begin{funcdesc}{seek}{offset\, whence}
+  Set the file's current position, like \code{stdio}'s \code{fseek()}.
+  The \var{whence} argument is optional and defaults to \code{0}
+  (absolute file positioning); other values are \code{1} (seek
+  relative to the current position) and \code{2} (seek relative to the
+  file's end).  There is no return value.
+\end{funcdesc}
+
+\begin{funcdesc}{tell}{}
+  Return the file's current position, like \code{stdio}'s \code{ftell()}.
+\end{funcdesc}
+
+\begin{funcdesc}{write}{str}
+  Write a string to the file.  There is no return value.
+\end{funcdesc}
+
+\subsubsection{Internal Objects.}
+
+(See the Python Reference Manual for these.)
+
+\subsection{Special Attributes}
+
+The implementation adds a few special read-only attributes to several
+object types, where they are relevant:
+
+\begin{itemize}
+
+\item
+\code{\var{x}.__dict__} is a dictionary of some sort used to store an
+object's (writable) attributes;
+
+\item
+\code{\var{x}.__methods__} lists the methods of many built-in object types,
+e.g., \code{[].__methods__} is
+% XXXJH results in?, yields?, written down as an example
+\code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']};
+
+\item
+\code{\var{x}.__members__} lists data attributes;
+
+\item
+\code{\var{x}.__class__} is the class to which a class instance belongs;
+
+\item
+\code{\var{x}.__bases__} is the tuple of base classes of a class object.
+
+\end{itemize}