path: root/doc/mod1.tex

\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}