% Format this file with latex.

%\documentstyle[palatino,11pt,myformat]{article}

\documentstyle[11pt,myformat]{article}

% A command to force the text after an item to start on a new line

\newcommand{\itembreak}{

\mbox{}\\*[0mm]

}

\title{\bf

Python Library Reference \\

(DRAFT)

}

\author{

Guido van Rossum \\

Dept. CST, CWI, Kruislaan 413 \\

1098 SJ Amsterdam, The Netherlands \\

E-mail: {\tt [email protected]}

}

\begin{document}

\pagenumbering{roman}

\maketitle

\begin{abstract}

\noindent

This document describes the built-in types, exceptions and functions and

the standard modules that come with the {\Python} system.

It assumes basic knowledge about the {\Python} language.

For an informal introduction to the language, see the Tutorial document.

The Language Reference document (XXX not yet existing)

gives a more formal reference to the language.

\end{abstract}

\pagebreak

\tableofcontents

\pagebreak

\pagenumbering{arabic}

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

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

\item[{\tt close()}]

Closes the file.

A closed file cannot be read or written anymore.

\item[{\tt 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.)

\item[{\tt 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().}

\item[{\tt 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}

\item[{\tt EOFError = 'end-of-file read'} (no argument)]

%.br

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.)

\item[{\tt KeyboardInterrupt = 'end-of-file read'} (no argument)]

%.br

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.

\item[{\tt MemoryError = 'out of memory'}]

%.br

Raised when an operation runs out of memory but the situation

may still be rescued (by deleting some objects).

\item[{\tt 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.

\item[{\tt RuntimeError = 'run-time error'}]

%.br

Raised for a variety of reasons, e.g., division by zero or index out of

range.

\item[{\tt 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.

\item[{\tt 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}

\item[{\tt abs(x)}]

Returns the absolute value of a number.

The argument may be an integer or floating point number.

\item[{\tt 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

\item[{\tt 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

\item[{\tt 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

\item[{\tt 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

\item[{\tt float(x)}]

Converts a number to floating point.

The argument may be an integer or floating point number.

\item[{\tt input(s)}]

Equivalent to

{\tt eval(raw\_input(s))}.

As for

{\tt raw\_input()},

the argument is optional.

\item[{\tt 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).

\item[{\tt max(s)}]

Returns the largest item of a non-empty sequence (string, tuple or list).

\item[{\tt min(s)}]

Returns the smallest item of a non-empty sequence (string, tuple or list).

\item[{\tt 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}.

}

\item[{\tt 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

\item[{\tt 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: Teenage Mutant Ninja Turtles

'Teenage Mutant Ninja Turtles'

>>>

\end{verbatim}\ecode

\item[{\tt type(x)}]

Returns the type of an object.

Types are objects themselves:

the type of a type object is its own type.

\end{description}

\section{Built-in Modules}

The modules described in this section are built into the interpreter.

They must be imported using

{\tt import}.

Some modules are not always available; it is a configuration option to

provide them.

Details are listed with the descriptions, but the best way to see if

a module exists in a particular implementation is to attempt to import

it.

\subsection{Built-in Module {\tt sys}}

This module provides access to some variables used or maintained by the

interpreter and to functions that interact strongly with the interpreter.

It is always available.

\begin{description}

\item[{\tt argv}]

The list of command line arguments passed to a {\Python} script.

{\tt sys.argv[0]}

is the script name.

If no script name was passed to the {\Python} interpreter,

{\tt sys.argv}

is empty.

\item[{\tt exit(n)}]

Exits from {\Python} with numeric exit status

{\tt n}.

This closes all open files and performs other cleanup-actions required by

the interpreter (but

{\em finally clauses}

of

{\tt try}

statements are not executed!).

\item[{\tt modules}]

Gives the list of modules that have already been loaded.

This can be manipulated to force reloading of modules and other tricks.

\item[{\tt path}]

A list of strings that specifies the search path for modules.

Initialized from the environment variable {\tt PYTHONPATH}, or an

installation-dependent default.

\item[{\tt ps1,~ps2}]

Strings specifying the primary and secondary prompt of the interpreter.

These are only defined if the interpreter is in interactive mode.

Their initial values in this case are

{\tt '>>> '}

and

{\tt '... '}.

\item[{\tt stdin, stdout, stderr}]

%.br

File objects corresponding to the interpreter's standard input, output

and error streams.

{\tt sys.stdin}

is used for all interpreter input except for scripts but including calls

to

{\tt input()}

and

{\tt raw\_input()}.

{\tt sys.stdout}

is used for the output of

{\tt print} and expression statements

and for the prompts of

{\tt input()}

and

{\tt raw\_input()}.

The interpreter's own prompts and its error messages are written to

stderr.

Assigning to

{\tt sys.stderr}

has no effect on the interpreter; it can be used to write error messages

to stderr using

{\tt print}.

\end{description}

\subsection{Built-in Module {\tt math}}

This module is always available.

It provides access to the mathematical functions defined by the C

standard.

They are:

{\tt acos(x)},

{\tt asin(x)},

{\tt atan(x)},

{\tt atan2(x,y)},

{\tt ceil(x)},

{\tt cos(x)},

{\tt cosh(x)},

{\tt exp(x)},

{\tt fabs(x)},

{\tt floor(x)},

%{\tt fmod(...)} XXX not yet

%{\tt frexp(...)} XXX not yet

%{\tt ldexp(...)} XXX not yet

{\tt log(x)},

{\tt log10(x)},

%{\tt modf(...)} XXX not yet

{\tt pow(x,y)},

{\tt sin(x)},

{\tt sinh(x)},

{\tt sqrt(x)},

{\tt tan(x)},

{\tt tanh(x)}.

It also defines two mathematical constants:

{\tt pi}

and

{\tt e}.

\subsection{Built-in Module {\tt time}}

This module provides various time-related functions.

It is always available.

Functions are:

\begin{description}

\item[{\tt sleep(secs)}]

Suspends execution for the given number of seconds.

\item[{\tt time()}]

Returns the time in seconds since the Epoch (Thursday January 1,

00:00:00, 1970 UCT on \UNIX\ machines).

\end{description}

\noindent

In some versions (Amoeba, Mac) the following functions also exist:

\begin{description}

\item[{\tt millisleep(msecs)}]

Suspends execution for the given number of milliseconds.

\item[{\tt millitimer()}]

Returns the number of milliseconds of real time elapsed since some point

in the past that is fixed per execution of the python interpreter (but

may change in each following run).

\end{description}

\noindent

The granularity of the milliseconds functions may be more than a

millisecond (100 msecs on Amoeba, 1/60 sec on the Mac).

\subsection{Built-in Module {\tt posix}}

This module provides access to operating system functionality that is

standardized by the C Standard and the POSIX standard (a thinly diguised

{\UNIX} interface).

It is available in all {\Python} versions except on the Macintosh.

Errors are reported exceptions.

It defines the following items:

\begin{description}

\item[{\tt chdir(path)}]

Changes the current directory to

{\tt path}.

\item[{\tt chmod(path, mode)}]

Change the mode of

{\tt path}

to the numeric

{\tt mode}.

\item[{\tt environ}]

A dictionary representing the string environment at the time

the interpreter was started.

(Modifying this dictionary does not affect the string environment of the

interpreter.)

For example,

{\tt posix.environ['HOME']}

is the pathname of your home directory, equivalent to

{\tt getenv("HOME")}

in C.

\item[{\tt error = 'posix.error'}]

%.br

The exception raised when an POSIX function returns an error.

The value accompanying this exception is a pair containing the numeric

error code from

{\tt errno}

and the corresponding string, as would be printed by the C function

{\tt perror()}.

\item[{\tt getcwd()}]

Returns a string representing the current working directory.

\item[{\tt link(src, dst)}]

Creates a hard link pointing to

{\tt src}

named

{\tt dst}.

\item[{\tt listdir(path)}]

Returns a list containing the names of the entries in the

directory.

The list is in arbitrary order.

It includes the special entries

{\tt '.'}

and

{\tt '..'}

if they are present in the directory.

\item[{\tt mkdir(path, mode)}]

Creates a directory named

{\tt path}

with numeric mode

{\tt mode}.

\item[{\tt rename(src, dst)}]

Renames the file or directory

{\tt src}

to

{\tt dst}.

\item[{\tt rmdir(path)}]

Removes the directory

{\tt path}.

\item[{\tt stat(path)}]

Performs a

{\em stat}

system call on the given path.

The return value is a tuple of at least 10 integers giving the most

important (and portable) members of the

{\em stat}

structure, in the order

{\tt st\_mode},

{\tt st\_ino},

{\tt st\_dev},

{\tt st\_nlink},

{\tt st\_uid},

{\tt st\_gid},

{\tt st\_size},

{\tt st\_atime},

{\tt st\_mtime},

{\tt st\_ctime}.

More items may be added at the end by some implementations.

\item[{\tt system(command)}]

Executes the command (a string) in a subshell.

This is implemented by calling the Standard C function

{\tt system()},

and has the same limitations.

Changes to

{\tt posix.environ},

{\tt sys.stdin}

etc. are not reflected in the environment of the executed command.

The return value is the exit status of the process as returned by

Standard C

{\tt system()}.

\item[{\tt umask(mask)}]

Sets the current numeric umask and returns the previous umask.

\item[{\tt unlink(path)}]

Unlinks the file

{\tt path}.

\item[{\tt utimes(path, (atime, mtime))}]

%.br

Sets the access and modified time of the file to the given values.

(The second argument is a tuple of two items.)

\end{description}

The following functions are only available on systems that support

symbolic links:

\begin{description}

\item[{\tt lstat(path)}]

Like

{\tt stat()},

but does not follow symbolic links.

\item[{\tt readlink(path)}]

Returns a string representing the path to which the symbolic link

points.

\item[{\tt symlink(src, dst)}]

Creates a symbolic link pointing to

{\tt src}

named

{\tt dst}.

\end{description}

\subsection{Built-in Module {\tt stdwin}}

This module defines several new object types and functions that

provide access to the functionality of the Standard Window System

Interface, STDWIN [CWI report CR-R8817].

It is available on systems to which STDWIN has been ported (which is

most systems).

It is only available if the {\tt DISPLAY} environment variable is set

or an explicit `{\tt -display \it displayname}' argument is passed to

the interpreter.

Functions have names that usually resemble their C STDWIN counterparts

with the initial `w' dropped.

Points are represented by pairs of integers; rectangles

by pairs of points.

For a complete description of STDWIN please refer to the documentation

of STDWIN for C programmers (aforementioned CWI report).

\subsubsection{Functions Defined in Module {\tt stdwin}}

The following functions are defined in the {\tt stdwin} module:

\begin{description}

\item[{\tt open(title)}]

%.br

Opens a new window whose initial title is given by the string argument.

Returns a window object; window object methods are described below.%

\footnote{

The {\Python} version of STDWIN does not support draw procedures; all

drawing requests are reported as draw events.

}

\item[{\tt getevent()}]

%.br

Waits for and returns the next event.

An event is returned as a triple: the first element is the event

type, a small integer; the second element is the window object to which

the event applies, or

{\tt None}

if it applies to no window in particular;

the third element is type-dependent.

Names for event types and command codes are defined in the standard

module

{\tt stdwinevent}.

\item[{\tt setdefwinpos(h, v)}]

%.br

Sets the default window position.

\item[{\tt setdefwinsize(width, height)}]

%.br

Sets the default window size.

\item[{\tt menucreate(title)}]

%.br

Creates a menu object referring to a global menu (a menu that appears in

all windows).

Methods of menu objects are described below.

\item[{\tt fleep()}]

%.br

Causes a beep or bell (or perhaps a `visual bell' or flash, hence the

name).

\item[{\tt message(string)}]

%.br

Displays a dialog box containing the string.

The user must click OK before the function returns.

\item[{\tt askync(prompt, default)}]

%.br

Displays a dialog that prompts the user to answer a question with yes or

no.

The function returns 0 for no, 1 for yes.

If the user hits the Return key, the default (which must be 0 or 1) is

returned.

If the user cancels the dialog, the

{\tt KeyboardInterrupt}

exception is raised.

\item[{\tt askstr(prompt, default)}]

%.br

Displays a dialog that prompts the user for a string.

If the user hits the Return key, the default string is returned.

If the user cancels the dialog, the

{\tt KeyboardInterrupt}

exception is raised.

\item[{\tt askfile(prompt, default, new)}]

%.br

Asks the user to specify a filename.

If

{\tt new}

is zero it must be an existing file; otherwise, it must be a new file.

If the user cancels the dialog, the

{\tt KeyboardInterrupt}

exception is raised.

\item[{\tt setcutbuffer(i, string)}]

%.br

Stores the string in the system's cut buffer number

{\tt i},

where it can be found (for pasting) by other applications.

On X11, there are 8 cut buffers (numbered 0..7).

Cut buffer number 0 is the `clipboard' on the Macintosh.

\item[{\tt getcutbuffer(i)}]

%.br

Returns the contents of the system's cut buffer number

{\tt i}.

\item[{\tt rotatebutbuffers(n)}]

%.br

On X11, this rotates the 8 cut buffers by

{\tt n}.

Ignored on the Macintosh.

\item[{\tt getselection(i)}]

%.br

Returns X11 selection number

{\tt i.}

Selections are not cut buffers.

Selection numbers are defined in module

{\tt stdwinevents}.

Selection {\tt WS\_PRIMARY} is the

{\em primary}

selection (used by

xterm,

for instance);

selection {\tt WS\_SECONDARY} is the

{\em secondary}

selection; selection {\tt WS\_CLIPBOARD} is the

{\em clipboard}

selection (used by

xclipboard).

On the Macintosh, this always returns an empty string.

\item[{\tt resetselection(i)}]

%.br

Resets selection number

{\tt i},

if this process owns it.

(See window method

{\tt setselection()}).

\item[{\tt baseline()}]

%.br

Return the baseline of the current font (defined by STDWIN as the

vertical distance between the baseline and the top of the

characters).%

\footnote{

There is no way yet to set the current font.

This will change in a future version.

}

\item[{\tt lineheight()}]

%.br

Return the total line height of the current font.

\item[{\tt textbreak(str, width)}]

%.br

Return the number of characters of the string that fit into a space of

{\tt width}

bits wide when drawn in the curent font.

\item[{\tt textwidth(str)}]

%.br

Return the width in bits of the string when drawn in the current font.

\end{description}

\subsubsection{Window Object Methods}

Window objects are created by

{\tt stdwin.open()}.

There is no explicit function to close a window; windows are closed when

they are garbage-collected.

Window objects have the following methods:

\begin{description}

\item[{\tt begindrawing()}]

Returns a drawing object, whose methods (described below) allow drawing

in the window.

\item[{\tt change(rect)}]

Invalidates the given rectangle; this may cause a draw event.

\item[{\tt gettitle()}]

Returns the window's title string.

\item[{\tt getdocsize()}]

\begin{sloppypar}

Returns a pair of integers giving the size of the document as set by

{\tt setdocsize()}.

\end{sloppypar}

\item[{\tt getorigin()}]

Returns a pair of integers giving the origin of the window with respect

to the document.

\item[{\tt getwinsize()}]

Returns a pair of integers giving the size of the window.

\item[{\tt menucreate(title)}]

Creates a menu object referring to a local menu (a menu that appears

only in this window).

Methods menu objects are described below.

\item[{\tt scroll(rect,~point)}]

Scrolls the given rectangle by the vector given by the point.

\item[{\tt setwincursor(name)}]

\begin{sloppypar}

Sets the window cursor to a cursor of the given name.

It raises the

{\tt Runtime\-Error}

exception if no cursor of the given name exists.

Suitable names are

{\tt 'ibeam'},