diff options
Diffstat (limited to 'doc/mod1.tex')
| -rw-r--r-- | doc/mod1.tex | 521 |
1 files changed, 521 insertions, 0 deletions
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} |