From a19a216bc60160c162e616145ef091dd18ce4e61 Mon Sep 17 00:00:00 2001
From: Skip Montanaro <skip.montanaro@gmail.com>
Date: Tue, 16 Feb 2021 14:40:46 -0600
Subject: Python 0.9.1 as posted in alt.sources

---
 doc/mod1.tex | 521 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 521 insertions(+)
 create mode 100644 doc/mod1.tex

(limited to 'doc/mod1.tex')

diff --git a/doc/mod1.tex b/doc/mod1.tex
new file mode 100644
index 0000000..2dac554
--- /dev/null
+++ b/doc/mod1.tex
@@ -0,0 +1,521 @@
+\section{Introduction}
+
+The {\Python} library consists of three parts, with different levels of
+integration with the interpreter.
+Closest to the interpreter are built-in types, exceptions and functions.
+Next are built-in modules, which are written in C and linked statically
+with the interpreter.
+Finally there are standard modules that are implemented entirely in
+{\Python}, but are always available.
+For efficiency, some standard modules may become built-in modules in
+future versions of the interpreter.
+
+\section{Built-in Types, Exceptions and Functions}
+
+Names for built-in exceptions and functions are found in a separate
+read-only symbol table which cannot be modified.
+This table is searched last, so local and global user-defined names can
+override built-in names.
+Built-in types have no names but are created by syntactic constructs
+(such as constants) or built-in functions.
+They are described together here for easy reference.%
+\footnote{
+The descriptions sorely lack explanations of the exceptions that
+may be raised---this will be fixed in a future version of this
+document.
+}
+
+\subsection{Built-in Types}
+
+The following sections describe the standard types that are built into the
+interpreter.
+\subsubsection{Numeric Types}
+
+There are two numeric types: integers and floating point numbers.
+Integers are implemented using {\tt long} in C, so they have at least 32
+bits of precision.
+Floating point numbers are implemented using {\tt double} in C.
+All bets on precision are off.
+Numbers are created by numeric constants or as the result of built-in
+functions and operators.
+
+Numeric types support the following operations:
+
+\begin{center}
+\begin{tabular}{|c|l|c|}
+\hline
+Operation & Result & Notes \\
+\hline
+{\tt abs}({\em x}) & absolute value of {\em x} & \\
+{\tt int}({\em x}) & {\em x} converted to integer & (1) \\
+{\tt float}({\em x}) & {\em x} converted to floating point & \\
+{\tt -}{\em x} & {\em x} negated & \\
+{\tt +}{\em x} & {\em x} unchanged & \\
+{\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\
+{\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\
+{\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\
+{\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\
+{\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\
+\hline
+\end{tabular}
+\end{center}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)]
+This may round or truncate as in C; see functions {\tt floor} and
+{\tt ceil} in module {\tt math}.
+\item[(2)]
+Integer division is defined as in C: the result is an integer; with
+positive operands, it truncates towards zero; with a negative operand,
+the result is unspecified.
+\item[(3)]
+Only defined for integers.
+\end{description}
+
+Mixed arithmetic is not supported; both operands must have the same type.
+Mixed comparisons return the wrong result (floats always compare smaller
+than integers).%
+\footnote{
+These restrictions are bugs in the language definitions and will be
+fixed in the future.
+}
+\subsubsection{Sequence Types}
+
+There are three sequence types: strings, lists and tuples.
+Strings constants are written in single quotes: {\tt 'xyzzy'}.
+Lists are constructed with square brackets: {\tt [a,~b,~c]}.
+Tuples are constructed by the comma operator or with an empty set of
+parentheses: {\tt a,~b,~c} or {\tt ()}.
+
+Sequence types support the following operations ({\em s} and {\em t} are
+sequences of the same type; {\em n}, {\em i} and {\em j} are integers):
+
+\begin{center}
+\begin{tabular}{|c|l|c|}
+\hline
+Operation & Result & Notes \\
+\hline
+{\tt len}({\em s}) & length of {\em s} & \\
+{\tt min}({\em s}) & smallest item of {\em s} & \\
+{\tt max}({\em s}) & largest item of {\em s} & \\
+{\em x} {\tt in} {\em s} &
+ true if an item of {\em s} is equal to {\em x} & \\
+{\em x} {\tt not} {\tt in} {\em s} &
+ false if an item of {\em s} is equal to {\em x} & \\
+{\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\
+{\em s}{\tt *}{\em n}, {\em n}*{\em s} &
+ {\em n} copies of {\em s} concatenated & (1) \\
+{\em s}[{\em i}] & {\em i}'th item of {\em s} & \\
+{\em s}[{\em i}:{\em j}] &
+ slice of {\em s} from {\em i} to {\em j} & (2) \\
+\hline
+\end{tabular}
+\end{center}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)]
+Sequence repetition is only supported for strings.
+\item[(2)]
+The slice of $s$ from $i$ to $j$ is defined as the sequence
+of items with index $k$ such that $i \leq k < j$.
+Special rules apply for negative and omitted indices; see the Tutorial
+or the Reference Manual.
+\end{description}
+
+\paragraph{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
+{\em x} is an arbitrary object):
+
+\begin{center}
+\begin{tabular}{|c|l|}
+\hline
+Operation & Result \\
+\hline
+{\em s}[{\em i}] = {\em x} &
+ item {\em i} of {\em s} is replaced by {\em x} \\
+{\em s}[{\em i}:{\em j}] = {\em t} &
+ slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\
+{\tt del} {\em s}[{\em i}:{\em j}] &
+ same as {\em s}[{\em i}:{\em j}] = [] \\
+{\em s}.{\tt append}({\em x}) &
+ same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\
+{\em s}.{\tt insert}({\em i}, {\em x}) &
+ same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\
+{\em s}.{\tt sort}() &
+ the items of {\em s} are permuted to satisfy \\
+ &
+ $s[i] \leq s[j]$ for $i < j$\\
+\hline
+\end{tabular}
+\end{center}
+
+\subsubsection{Mapping Types}
+
+A
+{\em 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
+{\em dictionary}.
+A dictionary's keys are strings.
+An empty dictionary is created by the expression \verb"{}".
+An extension of this notation is used to display dictionaries when
+written (see the example below).
+
+The following operations are defined on mappings (where {\em a} is a
+mapping, {\em k} is a key and {\em x} is an arbitrary object):
+
+\begin{center}
+\begin{tabular}{|c|l|c|}
+\hline
+Operation & Result & Notes\\
+\hline
+{\tt len}({\em a}) & the number of elements in {\em a} & \\
+{\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\
+{\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\
+{\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\
+{\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\
+{\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\
+\hline
+\end{tabular}
+\end{center}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)]
+Keys are listed in random order.
+\end{description}
+
+A small example using a dictionary:
+\bcode\begin{verbatim}
+>>> tel = {}
+>>> tel['jack'] = 4098
+>>> tel['sape'] = 4139
+>>> tel['guido'] = 4127
+>>> tel['jack']
+4098
+>>> tel
+{'sape': 4139; 'guido': 4127; 'jack': 4098}
+>>> del tel['sape']
+>>> tel['irv'] = 4127
+>>> tel
+{'guido': 4127; 'irv': 4127; 'jack': 4098}
+>>> tel.keys()
+['guido', 'irv', 'jack']
+>>> tel.has_key('guido')
+1
+>>>
+\end{verbatim}\ecode
+\subsubsection{Other Built-in Types}
+
+The interpreter supports several other kinds of objects.
+Most of these support only one or two operations.
+
+\paragraph{Modules.}
+
+The only operation on a module is member acces: {\em m}{\tt .}{\em name},
+where {\em m} is a module and {\em name} accesses a name defined in
+{\em m}'s symbol table.
+Module members can be assigned to.
+
+\paragraph{Classes and Class Objects.}
+
+XXX Classes will be explained at length in a later version of this
+document.
+
+\paragraph{Functions.}
+
+Function objects are created by function definitions.
+The only operation on a function object is to call it:
+{\em func}({\em optional-arguments}).
+
+Built-in functions have a different type than user-defined functions,
+but they support the same operation.
+
+\paragraph{Methods.}
+
+Methods are functions that are called using the member acces notation.
+There are two flavors: built-in methods (such as {\tt append()} on
+lists) and class member methods.
+Built-in methods are described with the types that support them.
+XXX Class member methods will be described in a later version of this
+document.
+
+\paragraph{Type Objects.}
+
+Type objects represent the various object types.
+An object's type is accessed by the built-in function
+{\tt type()}.
+There are no operations on type objects.
+
+\paragraph{The Null Object.}
+
+This object is returned by functions that don't explicitly return a
+value.
+It supports no operations.
+There is exactly one null object, named {\tt None}
+(a built-in name).
+
+\paragraph{File Objects.}
+
+File objects are implemented using C's
+{\em stdio}
+package and can be created with the built-in function
+{\tt open()}.
+They have the following methods:
+\begin{description}
+\funcitem{close}{}
+Closes the file.
+A closed file cannot be read or written anymore.
+\funcitem{read}{size}
+Reads at most
+{\tt size}
+bytes from the file (less if the read hits EOF).
+The bytes are returned as a string object.
+An empty string is returned when EOF is hit immediately.
+(For certain files, like ttys, it makes sense to continue reading after
+an EOF is hit.)
+\funcitem{readline}{size}
+Reads a line of at most
+{\tt size}
+bytes from the file.
+A trailing newline character, if present, is kept in the string.
+The size is optional and defaults to a large number (but not infinity).
+EOF is reported as by
+{\tt read().}
+\funcitem{write}{str}
+Writes a string to the file.
+Returns no value.
+\end{description}
+
+\subsection{Built-in Exceptions}
+
+The following exceptions can be generated by the interpreter or
+built-in functions.
+Except where mentioned, they have a string argument (also known as the
+`associated value' of an exception) indicating the detailed cause of the
+error.
+The strings listed with the exception names are their values when used
+in an expression or printed.
+\begin{description}
+\excitem{EOFError}{end-of-file read}
+(No argument.)
+Raised when a built-in function ({\tt input()} or {\tt raw\_input()})
+hits an end-of-file condition (EOF) without reading any data.
+(N.B.: the {\tt read()} and {\tt readline()} methods of file objects
+return an empty string when they hit EOF.)
+\excitem{KeyboardInterrupt}{end-of-file read}
+(No argument.)
+Raised when the user hits the interrupt key (normally Control-C or DEL).
+During execution, a check for interrupts is made regularly.
+Interrupts typed when a built-in function ({\tt input()} or
+{\tt raw\_input()}) is waiting for input also raise this exception.
+\excitem{MemoryError}{out of memory}
+%.br
+Raised when an operation runs out of memory but the situation
+may still be rescued (by deleting some objects).
+\excitem{NameError}{undefined name}
+%.br
+Raised when a name is not found.
+This applies to unqualified names, module names (on {\tt import}),
+module members and object methods.
+The string argument is the name that could not be found.
+\excitem{RuntimeError}{run-time error}
+%.br
+Raised for a variety of reasons, e.g., division by zero or index out of
+range.
+\excitem{SystemError}{system error}
+%.br
+Raised when the interpreter finds an internal error, but the situation
+does not look so serious to cause it to abandon all hope.
+\excitem{TypeError}{type error}
+%.br
+Raised when an operation or built-in function is applied to an object of
+inappropriate type.
+\end{description}
+
+\subsection{Built-in Functions}
+
+The {\Python} interpreter has a small number of functions built into it that
+are always available.
+They are listed here in alphabetical order.
+\begin{description}
+\funcitem{abs}{x}
+Returns the absolute value of a number.
+The argument may be an integer or floating point number.
+\funcitem{chr}{i}
+Returns a string of one character
+whose ASCII code is the integer {\tt i},
+e.g., {\tt chr(97)} returns the string {\tt 'a'}.
+This is the inverse of {\tt ord()}.
+\funcitem{dir}{}
+Without arguments, this function returns the list of names in the
+current local symbol table, sorted alphabetically.
+With a module object as argument, it returns the sorted list of names in
+that module's global symbol table.
+For example:
+\bcode\begin{verbatim}
+>>> import sys
+>>> dir()
+['sys']
+>>> dir(sys)
+['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
+>>>
+\end{verbatim}\ecode
+\funcitem{divmod}{a, b}
+%.br
+Takes two integers as arguments and returns a pair of integers
+consisting of their quotient and remainder.
+For
+\bcode\begin{verbatim}
+q, r = divmod(a, b)
+\end{verbatim}\ecode
+the invariants are:
+\bcode\begin{verbatim}
+a = q*b + r
+abs(r) < abs(b)
+r has the same sign as b
+\end{verbatim}\ecode
+For example:
+\bcode\begin{verbatim}
+>>> divmod(100, 7)
+(14, 2)
+>>> divmod(-100, 7)
+(-15, 5)
+>>> divmod(100, -7)
+(-15, -5)
+>>> divmod(-100, -7)
+(14, -2)
+>>>
+\end{verbatim}\ecode
+\funcitem{eval}{s}
+Takes a string as argument and parses and evaluates it as a {\Python}
+expression.
+The expression is executed using the current local and global symbol
+tables.
+Syntax errors are reported as exceptions.
+For example:
+\bcode\begin{verbatim}
+>>> x = 1
+>>> eval('x+1')
+2
+>>>
+\end{verbatim}\ecode
+\funcitem{exec}{s}
+Takes a string as argument and parses and evaluates it as a sequence of
+{\Python} statements.
+The string should end with a newline (\verb"'\n'").
+The statement is executed using the current local and global symbol
+tables.
+Syntax errors are reported as exceptions.
+For example:
+\bcode\begin{verbatim}
+>>> x = 1
+>>> exec('x = x+1\n')
+>>> x
+2
+>>>
+\end{verbatim}\ecode
+\funcitem{float}{x}
+Converts a number to floating point.
+The argument may be an integer or floating point number.
+\funcitem{input}{s}
+Equivalent to
+{\tt eval(raw\_input(s))}.
+As for
+{\tt raw\_input()},
+the argument is optional.
+\funcitem{int}{x}
+Converts a number to integer.
+The argument may be an integer or floating point number.
+\funcitem{len}{s}
+Returns the length (the number of items) of an object.
+The argument may be a sequence (string, tuple or list) or a mapping
+(dictionary).
+\funcitem{max}{s}
+Returns the largest item of a non-empty sequence (string, tuple or list).
+\funcitem{min}{s}
+Returns the smallest item of a non-empty sequence (string, tuple or list).
+\funcitem{open}{name, mode}
+%.br
+Returns a file object (described earlier under Built-in Types).
+The string arguments are the same as for stdio's
+{\tt fopen()}:
+{\tt 'r'}
+opens the file for reading,
+{\tt 'w'}
+opens it for writing (truncating an existing file),
+{\tt 'a'}
+opens it for appending.%
+\footnote{
+This function should go into a built-in module
+{\tt io}.
+}
+\funcitem{ord}{c}
+Takes a string of one character and returns its
+ASCII value, e.g., {\tt ord('a')} returns the integer {\tt 97}.
+This is the inverse of {\tt chr()}.
+\funcitem{range}{}
+This is a versatile function to create lists containing arithmetic
+progressions of integers.
+With two integer arguments, it returns the ascending sequence of
+integers starting at the first and ending one before the second
+argument.
+A single argument is used as the end point of the sequence, with 0 used
+as the starting point.
+A third argument specifies the step size; negative steps are allowed and
+work as expected, but don't specify a zero step.
+The resulting list may be empty.
+For example:
+\bcode\begin{verbatim}
+>>> range(10)
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+>>> range(1, 1+10)
+[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+>>> range(0, 30, 5)
+[0, 5, 10, 15, 20, 25]
+>>> range(0, 10, 3)
+[0, 3, 6, 9]
+>>> range(0, -10, -1)
+[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
+>>> range(0)
+[]
+>>> range(1, 0)
+[]
+>>>
+\end{verbatim}\ecode
+\funcitem{raw\_input}{s}
+%.br
+The argument is optional; if present, it is written to standard output
+without a trailing newline.
+The function then reads a line from input, converts it to a string
+(stripping a trailing newline), and returns that.
+EOF is reported as an exception.
+For example:
+\bcode\begin{verbatim}
+>>> raw_input('Type anything: ')
+Type anything: Mutant Teenage Ninja Turtles
+'Mutant Teenage Ninja Turtles'
+>>>
+\end{verbatim}\ecode
+\funcitem{reload}{module}
+Causes an already imported module to be re-parsed and re-initialized.
+This is useful if you have edited the module source file and want to
+try out the new version without leaving {\Python}.
+\funcitem{type}{x}
+Returns the type of an object.
+Types are objects themselves:
+the type of a type object is its own type.
+\end{description}
-- 
cgit v1.2.3