aifc — Read and write AIFF and AIFC files#

Read and write audio files in AIFF or AIFC format.

This module provides support for reading and writing AIFF and AIFF-C files. AIFF is Audio Interchange File Format, a format for storing digital audio samples in a file. AIFF-C is a newer version of the format that includes the ability to compress the audio data.

Caveat: Some operations may only work under IRIX; these will raise ImportError when attempting to import the cl module, which is only available on IRIX.

Audio files have a number of parameters that describe the audio data. The sampling rate or frame rate is the number of times per second the sound is sampled. The number of channels indicate if the audio is mono, stereo, or quadro. Each frame consists of one sample per channel. The sample size is the size in bytes of each sample. Thus a frame consists of nchannels × samplesize bytes, and a second’s worth of audio consists of nchannels × samplesize × framerate bytes.

For example, CD quality audio has a sample size of two bytes (16 bits), uses two channels (stereo) and has a frame rate of 44,100 frames/second. This gives a frame size of 4 bytes (22), and a second’s worth occupies 22*44100 bytes, i.e. 176,400 bytes.

Module aifc defines the following function:

open(file)#

Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a string naming a file or a file object. mode must be ’r’ or ’rb’ when the file must be opened for reading, or ’w’ or ’wb’ when the file must be opened for writing. If omitted, file.mode is used if it exists, otherwise ’rb’ is used. When used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use writeframesraw() and setnframes().

Objects returned by open() when a file is opened for reading have the following methods:

getnchannels()#

Return the number of audio channels (1 for mono, 2 for stereo).

getsampwidth()#

Return the size in bytes of individual samples.

getframerate()#

Return the sampling rate (number of audio frames per second).

getnframes()#

Return the number of audio frames in the file.

getcomptype()#

Return a four-character string describing the type of compression used in the audio file. For AIFF files, the returned value is ’NONE’.

getcompname()#

Return a human-readable description of the type of compression used in the audio file. For AIFF files, the returned value is ’not compressed’.

getparams()#

Return a tuple consisting of all of the above values in the above order.

getmarkers()#

Return a list of markers in the audio file. A marker consists of a tuple of three elements. The first is the mark ID (an integer), the second is the mark position in frames from the beginning of the data (an integer), the third is the name of the mark (a string).

getmark(id)#

Return the tuple as described in getmarkers() for the mark with the given id.

readframes(nframes)#

Read and return the next nframes frames from the audio file. The returned data is a string containing for each frame the uncompressed samples of all channels.

rewind()#

Rewind the read pointer. The next readframes() will start from the beginning.

setpos(pos)#

Seek to the specified frame number.

tell()#

Return the current frame number.

close()#

Close the AIFF file. After calling this method, the object can no longer be used.

Objects returned by open() when a file is opened for writing have all the above methods, except for readframes() and setpos(). In addition the following methods exist. The get*() methods can only be called after the corresponding set*() methods have been called. Before the first writeframes() or writeframesraw(), all parameters except for the number of frames must be filled in.

aiff()#

Create an AIFF file. The default is that an AIFF-C file is created, unless the name of the file ends in ’.aiff’ in which case the default is an AIFF file.

aifc()#

Create an AIFF-C file. The default is that an AIFF-C file is created, unless the name of the file ends in ’.aiff’ in which case the default is an AIFF file.

setnchannels(nchannels)#

Specify the number of channels in the audio file.

setsampwidth(width)#

Specify the size in bytes of audio samples.

setframerate(rate)#

Specify the sampling frequency in frames per second.

setnframes(nframes)#

Specify the number of frames that are to be written to the audio file. If this parameter is not set, or not set correctly, the file needs to support seeking.

setcomptype(type, name)#

Specify the compression type. If not specified, the audio data will not be compressed. In AIFF files, compression is not possible. The name parameter should be a human-readable description of the compression type, the type parameter should be a four-character string. Currently the following compression types are supported: NONE, ULAW, ALAW, G722.

setparams(nchannels, sampwidth, framerate, comptype, compname)#

Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible to use the result of a getparams() call as argument to setparams().

setmark(id, pos, name)#

Add a mark with the given id (larger than 0), and the given name at the given position. This method can be called at any time before close().

tell()#

Return the current write position in the output file. Useful in combination with setmark().

writeframes(data)#

Write data to the output file. This method can only be called after the audio file parameters have been set.

writeframesraw(data)#

Like writeframes(), except that the header of the audio file is not updated.

close()#

Close the AIFF file. The header of the file is updated to reflect the actual size of the audio data. After calling this method, the object can no longer be used.

al — Audio functions on the SGI#

Audio functions on the SGI.

This module provides access to the audio facilities of the SGI Indy and Indigo workstations. See section 3A of the IRIX man pages for details. You’ll need to read those man pages to understand what these functions do! Some of the functions are not available in IRIX releases before 4.0.5. Again, see the manual to check whether a specific function is available on your platform.

All functions and methods defined in this module are equivalent to the C functions with AL prefixed to their name.

Symbolic constants from the C header file <audio.h> are defined in the standard module AL, see below.

Warning: the current version of the audio library may dump core when bad argument values are passed rather than returning an error status. Unfortunately, since the precise circumstances under which this may happen are undocumented and hard to check, the Python interface can provide no protection against this kind of problems. (One example is specifying an excessive queue size — there is no documented upper limit.)

The module defines the following functions:

openport(name, direction)#

The name and direction arguments are strings. The optional config argument is a configuration object as returned by newconfig(). The return value is an audio port object; methods of audio port objects are described below.

newconfig()#

The return value is a new audio configuration object; methods of audio configuration objects are described below.

queryparams(device)#

The device argument is an integer. The return value is a list of integers containing the data returned by .

getparams(device, list)#

The device argument is an integer. The list argument is a list such as returned by queryparams(); it is modified in place (!).

setparams(device, list)#

The device argument is an integer. The list argument is a list such as returned by queryparams().

Configuration Objects#

Configuration objects (returned by newconfig() have the following methods:

getqueuesize()#

Return the queue size.

setqueuesize(size)#

Set the queue size.

getwidth()#

Get the sample width.

setwidth(width)#

Set the sample width.

getchannels()#

Get the channel count.

setchannels(nchannels)#

Set the channel count.

getsampfmt()#

Get the sample format.

setsampfmt(sampfmt)#

Set the sample format.

getfloatmax()#

Get the maximum value for floating sample formats.

setfloatmax(floatmax)#

Set the maximum value for floating sample formats.

Port Objects#

Port objects, as returned by openport(), have the following methods:

closeport()#

Close the port.

getfd()#

Return the file descriptor as an int.

getfilled()#

Return the number of filled samples.

getfillable()#

Return the number of fillable samples.

readsamps(nsamples)#

Read a number of samples from the queue, blocking if necessary. Return the data as a string containing the raw data, (e.g., 2 bytes per sample in big-endian byte order (high byte, low byte) if you have set the sample width to 2 bytes).

writesamps(samples)#

Write samples into the queue, blocking if necessary. The samples are encoded as described for the readsamps() return value.

getfillpoint()#

Return the ‘fill point’.

setfillpoint(fillpoint)#

Set the ‘fill point’.

getconfig()#

Return a configuration object containing the current configuration of the port.

setconfig(config)#

Set the configuration from the argument, a configuration object.

getstatus(list)#

Get status information on last error.

AL — Constants used with the al module#

Constants used with the al module.

This module defines symbolic constants needed to use the built-in module al (see above); they are equivalent to those defined in the C header file <audio.h> except that the name prefix AL_ is omitted. Read the module source for a complete list of the defined names. Suggested use:

import al
from AL import *

Generic Operating System Services#

The modules described in this chapter provide interfaces to operating system features that are available on (almost) all operating systems, such as files and a clock. The interfaces are generally modeled after the Unix or C interfaces, but they are available on most other systems as well. Here’s an overview:

Amoeba Specific Services#

amoeba — Amoeba system support#

Functions for the Amoeba operating system.

This module provides some object types and operations useful for Amoeba applications. It is only available on systems that support Amoeba operations. RPC errors and other Amoeba errors are reported as the exception amoeba.error = ’amoeba.error’.

The module amoeba defines the following items:

name_append(path, cap)#

Stores a capability in the Amoeba directory tree. Arguments are the pathname (a string) and the capability (a capability object as returned by name_lookup()).

name_delete(path)#

Deletes a capability from the Amoeba directory tree. Argument is the pathname.

name_lookup(path)#

Looks up a capability. Argument is the pathname. Returns a capability object, to which various interesting operations apply, described below.

name_replace(path, cap)#

Replaces a capability in the Amoeba directory tree. Arguments are the pathname and the new capability. (This differs from name_append() in the behavior when the pathname already exists: name_append() finds this an error while name_replace() allows it, as its name suggests.)

capv#

A table representing the capability environment at the time the interpreter was started. (Alas, modifying this table does not affect the capability environment of the interpreter.) For example, amoeba.capv[’ROOT’] is the capability of your root directory, similar to getcap("ROOT") in C.

exception error#

The exception raised when an Amoeba function returns an error. The value accompanying this exception is a pair containing the numeric error code and the corresponding string, as returned by the C function .

timeout(msecs)#

Sets the transaction timeout, in milliseconds. Returns the previous timeout. Initially, the timeout is set to 2 seconds by the Python interpreter.

Capability Operations#

Capabilities are written in a convenient ASCII format, also used by the Amoeba utilities c2a(U) and a2c(U). For example:

>>> amoeba.name_lookup('/profile/cap')
aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
>>> 

The following methods are defined for capability objects.

dir_list()#

Returns a list of the names of the entries in an Amoeba directory.

b_read(offset, maxsize)#

Reads (at most) maxsize bytes from a bullet file at offset offset. The data is returned as a string. EOF is reported as an empty string.

b_size()#

Returns the size of a bullet file.

dir_append()#

Like the corresponding name_* functions, but with a path relative to the capability. (For paths beginning with a slash the capability is ignored, since this is the defined semantics for Amoeba.)

std_info()#

Returns the standard info string of the object.

tod_gettime()#

Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from a time server.

tod_settime(t)#

Sets the time kept by a time server.

anydbm — Generic access to DBM-style databases#

Generic interface to DBM-style database modules.

anydbm is a generic interface to variants of the DBM database — dbhash (requires bsddb), gdbm, or dbm. If none of these modules is installed, the slow-but-simple implementation in module dumbdbm will be used.

open(filename)#

Open the database file filename and return a corresponding object.

If the database file already exists, the whichdb module is used to determine its type and the appropriate module is used; if it does not exist, the first module listed above that can be imported is used.

The optional flag argument can be ’r’ to open an existing database for reading only, ’w’ to open an existing database for reading and writing, ’c’ to create the database if it doesn’t exist, or ’n’, which will always create a new empty database. If not specified, the default value is ’r’.

The optional mode argument is the Unix mode of the file, used only when the database has to be created. It defaults to octal 0666 (and will be modified by the prevailing umask).

exception error#

A tuple containing the exceptions that can be raised by each of the supported modules, with a unique exception anydbm.error as the first item — the latter is used when anydbm.error is raised.

The object returned by open() supports most of the same functionality as dictionaries; keys and their corresponding values can be stored, retrieved, and deleted, and the has_key() and keys() methods are available. Keys and values must always be strings.

See also:#

— anydbmGeneric interface to dbm-style databases. — dbhashBSD db database interface. — dbmStandard Unix database interface. — dumbdbmPortable implementation of the dbm interface. — gdbmGNU database interface, based on the dbm interface. — shelveGeneral object persistence built on top of the Python dbm interface. — whichdbUtility module used to determine the type of an existing database.

dumbdbm — Portable DBM implementation#

Portable implementation of the simple DBM interface.

A simple and slow database implemented entirely in Python. This should only be used when no other DBM-style database is available.

open(filename)#

Open the database file filename and return a corresponding object. The optional flag argument can be ’r’ to open an existing database for reading only, ’w’ to open an existing database for reading and writing, ’c’ to create the database if it doesn’t exist, or ’n’, which will always create a new empty database. If not specified, the default value is ’r’.

The optional mode argument is the Unix mode of the file, used only when the database has to be created. It defaults to octal 0666 (and will be modified by the prevailing umask).

exception error#

Raised for errors not reported as KeyError errors.

See also:#

— anydbmGeneric interface to dbm-style databases. — whichdbUtility module used to determine the type of an existing database.

array — Efficient arrays of numeric values#

Efficient arrays of uniformly typed numeric values.

This module defines a new object type which can efficiently represent an array of basic values: characters, integers, floating point numbers. Arrays are sequence types and behave very much like lists, except that the type of objects stored in them is constrained. The type is specified at object creation time by using a type code, which is a single character. The following type codes are defined:

The actual representation of values is determined by the machine architecture (strictly speaking, by the C implementation). The actual size can be accessed through the itemsize attribute. The values stored for ’L’ and ’I’ items will be represented as Python long integers when retrieved, because Python’s plain integer type cannot represent the full range of C’s unsigned (long) integers.

The module defines the following function and type object:

array(typecode)#

Return a new array whose items are restricted by typecode, and initialized from the optional initializer value, which must be a list or a string. The list or string is passed to the new array’s fromlist() or fromstring() method (see below) to add initial items to the array.

ArrayType#

Type object corresponding to the objects returned by array().

Array objects support the following data items and methods:

typecode#

The typecode character used to create the array.

itemsize#

The length in bytes of one array item in the internal representation.

append(x)#

Append a new item with value x to the end of the array.

buffer_info()#

Return a tuple (address, length) giving the current memory address and the length in bytes of the buffer used to hold array’s contents. This is occasionally useful when working with low-level (and inherently unsafe) I/O interfaces that require memory addresses, such as certain operations. The returned numbers are valid as long as the array exists and no length-changing operations are applied to it.

byteswap()#

“Byteswap” all items of the array. This is only supported for values which are 1, 2, 4, or 8 bytes in size; for other types of values, RuntimeError is raised. It is useful when reading data from a file written on a machine with a different byte order.

count(x)#

Return the number of occurences of x in the array.

extend(a)#

Append array items from a to the end of the array.

fromfile(f, n)#

Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array. f must be a real built-in file object; something else with a read() method won’t do.

fromlist(list)#

Append items from the list. This is equivalent to for x in list: a.append(x) except that if there is a type error, the array is unchanged.

fromstring(s)#

Appends items from the string, interpreting the string as an array of machine values (i.e. as if it had been read from a file using the fromfile() method).

index(x)#

Return the smallest i such that i is the index of the first occurence of x in the array.

insert(i, x)#

Insert a new item with value x in the array before position i.

pop()#

Removes the item with the index i from the array and returns it. The optional argument defaults to -1, so that by default the last item is removed and returned.

read(f, n)#

Deprecated since version 1.5.1: Use the fromfile() method. Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array. f must be a real built-in file object; something else with a read() method won’t do.

remove(x)#

Remove the first occurence of x from the array.

reverse()#

Reverse the order of the items in the array.

tofile(f)#

Write all items (as machine values) to the file object f.

tolist()#

Convert the array to an ordinary list with the same items.

tostring()#

Convert the array to an array of machine values and return the string representation (the same sequence of bytes that would be written to a file by the tofile() method.)

write(f)#

Deprecated since version 1.5.1: Use the tofile() method. Write all items (as machine values) to the file object f.

When an array object is printed or converted to a string, it is represented as array(typecode, initializer). The initializer is omitted if the array is empty, otherwise it is a string if the typecode is ’c’, otherwise it is a list of numbers. The string is guaranteed to be able to be converted back to an array with the same type and value using reverse quotes (‘‘), so long as the array() function has been imported using from array import array. Examples:

array('l')
array('c', 'hello world')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

See also:#

— structpacking and unpacking of heterogeneous binary data — xdrlibpacking and unpacking of XDR data The Numeric Python extension (NumPy) defines another array type; see The Numerical Python Manual for additional information (available online at ftp://ftp-icf.llnl.gov/pub/python/numericalpython.pdf). Further information about NumPy is available at http://www.python.org/topics/scicomp/numpy.html.

curses.ascii — Utilities for ASCII characters#

Constants and set-membership functions for ASCII characters.

New in version 1.6.

The curses.ascii module supplies name constants for ASCII characters and functions to test membership in various ASCII character classes. The constants supplied are names for control characters as follows:

Note that many of these have little practical use in modern usage.

The module supplies the following functions, patterned on those in the standard C library:

isalnum(c)#

Checks for an ASCII alphanumeric character; it is equivalent to isalpha(c) or isdigit(c).

isalpha(c)#

Checks for an ASCII alphabetic character; it is equivalent to isupper(c) or islower(c).

isascii(c)#

Checks for a character value that fits in the 7-bit ASCII set.

isblank(c)#

Checks for an ASCII whitespace character.

iscntrl(c)#

Checks for an ASCII control character (in the range 0x00 to 0x1f).

isdigit(c)#

Checks for an ASCII decimal digit, 0 through 9. This is equivalent to c in string.digits.

isgraph(c)#

Checks for ASCII any printable character except space.

islower(c)#

Checks for an ASCII lower-case character.

isprint(c)#

Checks for any ASCII printable character including space.

ispunct(c)#

Checks for any printable ASCII character which is not a space or an alphanumeric character.

isspace(c)#

Checks for ASCII white-space characters; space, tab, line feed, carriage return, form feed, horizontal tab, vertical tab.

isupper(c)#

Checks for an ASCII uppercase letter.

isxdigit(c)#

Checks for an ASCII hexadecimal digit. This is equivalent to c in string.hexdigits.

isctrl(c)#

Checks for an ASCII control character (ordinal values 0 to 31).

ismeta(c)#

Checks for a non-ASCII character (ordinal values 0x80 and above).

These functions accept either integers or strings; when the argument is a string, it is first converted using the built-in function ord().

Note that all these functions check ordinal bit values derived from the first character of the string you pass in; they do not actually know anything about the host machine’s character encoding. For functions that know about the character encoding (and handle internationalization properly) see the string module.

The following two functions take either a single-character string or integer byte value; they return a value of the same type.

ascii(c)#

Return the ASCII value corresponding to the low 7 bits of c.

ctrl(c)#

Return the control character corresponding to the given character (the character bit value is bitwise-anded with 0x1f).

alt(c)#

Return the 8-bit character corresponding to the given ASCII character (the character bit value is bitwise-ored with 0x80).

The following function takes either a single-character string or integer value; it returns a string.

unctrl(c)#

Return a string representation of the ASCII character c. If c is printable, this string is the character itself. If the character is a control character (0x00-0x1f) the string consists of a caret (^) followed by the corresponding uppercase letter. If the character is an ASCII delete (0x7f) the string is ’^?’. If the character has its meta bit (0x80) set, the meta bit is stripped, the preceding rules applied, and ! prepended to the result.

controlnames#

A 33-element string array that contains the ASCII mnemonics for the thirty-two ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic SP for the space character.

asyncore — Asynchronous socket handler#

A base class for developing asynchronous socket handling services.

This module provides the basic infrastructure for writing asynchronous socket service clients and servers.

There are only two ways to have a program on a single processor do “more than one thing at a time.” Multi-threaded programming is the simplest and most popular way to do it, but there is another very different technique, that lets you have nearly all the advantages of multi-threading, without actually using multiple threads. It’s really only practical if your program is largely I/O bound. If your program is CPU bound, then pre-emptive scheduled threads are probably what you really need. Network servers are rarely CPU-bound, however.

If your operating system supports the system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the “background.” Although this strategy can seem strange and complex, especially at first, it is in many ways easier to understand and control than multi-threaded programming. The module documented here solves many of the difficult problems for you, making the task of building sophisticated high-performance network servers and clients a snap.

class dispatcher()#

The first class we will introduce is the dispatcher class. This is a thin wrapper around a low-level socket object. To make it more useful, it has a few methods for event-handling on it. Otherwise, it can be treated as a normal non-blocking socket object.

The direct interface between the select loop and the socket object are the handle_read_event() and handle_write_event() methods. These are called whenever an object ‘fires’ that event.

The firing of these low-level events can tell us whether certain higher-level events have taken place, depending on the timing and the state of the connection. For example, if we have asked for a socket to connect to another host, we know that the connection has been made when the socket fires a write event (at this point you know that you may write to it with the expectation of success). The implied higher-level events are:

This set of user-level events is larger than the basics. The full set of methods that can be overridden in your subclass are:

handle_read()#

Called when there is new data to be read from a socket.

handle_write()#

Called when there is an attempt to write data to the object. Often this method will implement the necessary buffering for performance. For example:

def handle_write(self):
    sent = self.send(self.buffer)
    self.buffer = self.buffer[sent:]

handle_expt()#

Called when there is out of band (OOB) data for a socket connection. This will almost never happen, as OOB is tenuously supported and rarely used.

handle_connect()#

Called when the socket actually makes a connection. This might be used to send a “welcome” banner, or something similar.

handle_close()#

Called when the socket is closed.

handle_accept()#

Called on listening sockets when they actually accept a new connection.

readable()#

Each time through the select() loop, the set of sockets is scanned, and this method is called to see if there is any interest in reading. The default method simply returns 1, indicating that by default, all channels will be interested.

writeable()#

Each time through the select() loop, the set of sockets is scanned, and this method is called to see if there is any interest in writing. The default method simply returns 1, indicating that by default, all channels will be interested.

In addition, there are the basic methods needed to construct and manipulate “channels,” which are what we will call the socket connections in this context. Note that most of these are nearly identical to their socket partners.

create_socket(family, type)#

This is identical to the creation of a normal socket, and will use the same options for creation. Refer to the socket documentation for information on creating sockets.

connect(address)#

As with the normal socket object, address is a tuple with the first element the host to connect to, and the second the port.

send(data)#

Send data out the socket.

recv(buffer_size)#

Read at most buffer_size bytes from the socket.

listen()#

Listen for connections made to the socket. The backlog argument specifies the maximum number of queued connections and should be at least 1; the maximum value is system-dependent (usually 5).

bind(address)#

Bind the socket to address. The socket must not already be bound. (The format of address depends on the address family — see above.)

accept()#

Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair (conn, address) where conn is a new socket object usable to send and receive data on the connection, and address is the address bound to the socket on the other end of the connection.

close()#

Close the socket. All future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed). Sockets are automatically closed when they are garbage-collected.

Example basic HTTP client#

As a basic example, below is a very basic HTTP client that uses the dispatcher class to implement its socket handling:

class http_client(asyncore.dispatcher):
    def __init__(self, host,path):
        asyncore.dispatcher.__init__(self)
        self.path = path
        self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
        self.connect( (host, 80) )
        self.buffer = 'GET %s HTTP/1.0\r\b\r\n' % self.path
        
    def handle_connect(self):
        pass
        
    def handle_read(self):
        data = self.recv(8192)
        print data
        
    def writeable(self):
        return (len(self.buffer) > 0)
    
    def handle_write(self):
        sent = self.send(self.buffer)
        self.buffer = self.buffer[sent:]

atexit — Exit handlers#

Register and execute cleanup functions.

New in version 2.0.

The atexit module defines a single function to register cleanup functions. Functions thus registered are automatically executed upon normal interpreter termination.

Note: the functions registered via this module are not called when the program is killed by a signal, when a Python fatal internal error is detected, or when os._exit() is called.

This is an alternate interface to the functionality provided by the sys.exitfunc variable.

Note: This module is unlikely to work correctly when used with other code that sets sys.exitfunc. In particular, other core Python modules are free to use atexit without the programmer’s knowledge. Authors who use sys.exitfunc should convert their code to use atexit instead. The simplest way to convert code that sets sys.exitfunc is to import atexit and register the function that had been bound to sys.exitfunc.

register(func)#

Register func as a function to be executed at termination. Any optional arguments that are to be passed to func must be passed as arguments to register().

At normal program termination (for instance, if sys.exit() is called or the main module’s execution completes), all functions registered are called in last in, first out order. The assumption is that lower level modules will normally be imported before higher level modules and thus must be cleaned up later.

See also:#

— readlineUseful example of atexit to read and write readline history files.

atexit Example#

The following simple example demonstrates how a module can initialize a counter from a file when it is imported and save the counter’s updated value automatically when the program terminates without relying on the application making an explicit call into this module at termination.

try:
    _count = int(open("/tmp/counter").read())
except IOError:
    _count = 0

def incrcounter(n):
    global _count
    _count = _count + n

def savecounter():
    open("/tmp/counter", "w").write("%d" % _count)

import atexit
atexit.register(savecounter)

audioop — Manipulate raw audio data#

Manipulate raw audio data.

The audioop module contains some useful operations on sound fragments. It operates on sound fragments consisting of signed integer samples 8, 16 or 32 bits wide, stored in Python strings. This is the same format as used by the al and sunaudiodev modules. All scalar items are integers, unless specified otherwise.

This module provides support for u-LAW and Intel/DVI ADPCM encodings.

A few of the more complicated operations only take 16-bit samples, otherwise the sample size (in bytes) is always a parameter of the operation.

The module defines the following variables and functions:

exception error#

This exception is raised on all errors, such as unknown number of bytes per sample, etc.

add(fragment1, fragment2, width)#

Return a fragment which is the addition of the two samples passed as parameters. width is the sample width in bytes, either 1, 2 or 4. Both fragments should have the same length.

adpcm2lin(adpcmfragment, width, state)#

Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See the description of lin2adpcm() for details on ADPCM coding. Return a tuple (sample, newstate) where the sample has the width specified in width.

adpcm32lin(adpcmfragment, width, state)#

Decode an alternative 3-bit ADPCM code. See lin2adpcm3() for details.

avg(fragment, width)#

Return the average over all samples in the fragment.

avgpp(fragment, width)#

Return the average peak-peak value over all samples in the fragment. No filtering is done, so the usefulness of this routine is questionable.

bias(fragment, width, bias)#

Return a fragment that is the original fragment with a bias added to each sample.

cross(fragment, width)#

Return the number of zero crossings in the fragment passed as an argument.

findfactor(fragment, reference)#

Return a factor F such that rms(add(fragment, mul(reference, -F))) is minimal, i.e., return the factor with which you should multiply reference to make it match as well as possible to fragment. The fragments should both contain 2-byte samples.

The time taken by this routine is proportional to len(fragment).

findfit(fragment, reference)#

Try to match reference as well as possible to a portion of fragment (which should be the longer fragment). This is (conceptually) done by taking slices out of fragment, using findfactor() to compute the best match, and minimizing the result. The fragments should both contain 2-byte samples. Return a tuple (offset, factor) where offset is the (integer) offset into fragment where the optimal match started and factor is the (floating-point) factor as per findfactor().

findmax(fragment, length)#

Search fragment for a slice of length length samples (not bytes!) with maximum energy, i.e., return i for which rms(fragment[i*2:(i+length)*2]) is maximal. The fragments should both contain 2-byte samples.

The routine takes time proportional to len(fragment).

getsample(fragment, width, index)#

Return the value of sample index from the fragment.

lin2lin(fragment, width, newwidth)#

Convert samples between 1-, 2- and 4-byte formats.

lin2adpcm(fragment, width, state)#

Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an adaptive coding scheme, whereby each 4 bit number is the difference between one sample and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it may well become a standard.

state is a tuple containing the state of the coder. The coder returns a tuple (adpcmfrag, newstate), and the newstate should be passed to the next call of lin2adpcm(). In the initial call, None can be passed as the state. adpcmfrag is the ADPCM coded fragment packed 2 4-bit values per byte.

lin2adpcm3(fragment, width, state)#

This is an alternative ADPCM coder that uses only 3 bits per sample. It is not compatible with the Intel/DVI ADPCM coder and its output is not packed (due to laziness on the side of the author). Its use is discouraged.

lin2ulaw(fragment, width)#

Convert samples in the audio fragment to u-LAW encoding and return this as a Python string. u-LAW is an audio encoding format whereby you get a dynamic range of about 14 bits using only 8 bit samples. It is used by the Sun audio hardware, among others.

minmax(fragment, width)#

Return a tuple consisting of the minimum and maximum values of all samples in the sound fragment.

max(fragment, width)#

Return the maximum of the absolute value of all samples in a fragment.

maxpp(fragment, width)#

Return the maximum peak-peak value in the sound fragment.

mul(fragment, width, factor)#

Return a fragment that has all samples in the original fragment multiplied by the floating-point value factor. Overflow is silently ignored.

ratecv(fragment, width, nchannels, inrate, outrate, state)#

Convert the frame rate of the input fragment.

state is a tuple containing the state of the converter. The converter returns a tuple (newfragment, newstate), and newstate should be passed to the next call of ratecv().

The weightA and weightB arguments are parameters for a simple digital filter and default to 1 and 0 respectively.

reverse(fragment, width)#

Reverse the samples in a fragment and returns the modified fragment.

rms(fragment, width)#

Return the root-mean-square of the fragment, i.e. √(S_i)^2n This is a measure of the power in an audio signal.

tomono(fragment, width, lfactor, rfactor)#

Convert a stereo fragment to a mono fragment. The left channel is multiplied by lfactor and the right channel by rfactor before adding the two channels to give a mono signal.

tostereo(fragment, width, lfactor, rfactor)#

Generate a stereo fragment from a mono fragment. Each pair of samples in the stereo fragment are computed from the mono sample, whereby left channel samples are multiplied by lfactor and right channel samples by rfactor.

ulaw2lin(fragment, width)#

Convert sound fragments in u-LAW encoding to linearly encoded sound fragments. u-LAW encoding always uses 8 bits samples, so width refers only to the sample width of the output fragment here.

Note that operations such as mul() or max() make no distinction between mono and stereo fragments, i.e. all samples are treated equal. If this is a problem the stereo fragment should be split into two mono fragments first and recombined later. Here is an example of how to do that:

def mul_stereo(sample, width, lfactor, rfactor):
    lsample = audioop.tomono(sample, width, 1, 0)
    rsample = audioop.tomono(sample, width, 0, 1)
    lsample = audioop.mul(sample, width, lfactor)
    rsample = audioop.mul(sample, width, rfactor)
    lsample = audioop.tostereo(lsample, width, 1, 0)
    rsample = audioop.tostereo(rsample, width, 0, 1)
    return audioop.add(lsample, rsample, width)

If you use the ADPCM coder to build network packets and you want your protocol to be stateless (i.e. to be able to tolerate packet loss) you should not only transmit the data but also the state. Note that you should send the initial state (the one you passed to lin2adpcm()) along to the decoder, not the final state (as returned by the coder). If you want to use struct.struct() to store the state in binary you can code the first element (the predicted value) in 16 bits and the second (the delta index) in 8.

The ADPCM coders have never been tried against other ADPCM coders, only against themselves. It could well be that I misinterpreted the standards in which case they will not be interoperable with the respective standards.

The find*() routines might look a bit funny at first sight. They are primarily meant to do echo cancellation. A reasonably fast way to do this is to pick the most energetic piece of the output sample, locate that in the input sample and subtract the whole output sample from the input sample:

def echocancel(outputdata, inputdata):
    pos = audioop.findmax(outputdata, 800)    # one tenth second
    out_test = outputdata[pos*2:]
    in_test = inputdata[pos*2:]
    ipos, factor = audioop.findfit(in_test, out_test)
    # Optional (for better cancellation):
    # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], 
    #              out_test)
    prefill = '\0'*(pos+ipos)*2
    postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
    outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
    return audioop.add(inputdata, outputdata, 2)

base64 — Encode and decode MIME base64 data#

Encode and decode files using the MIME base64 data.

This module performs base64 encoding and decoding of arbitrary binary strings into text strings that can be safely emailed or posted. The encoding scheme is defined in RFC 1521 (MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies, section 5.2, “Base64 Content-Transfer-Encoding”) and is used for MIME email and various other Internet-related applications; it is not the same as the output produced by the uuencode program. For example, the string ’www.python.org’ is encoded as the string ’d3d3LnB5dGhvbi5vcmc=n’.

decode(input, output)#

Decode the contents of the input file and write the resulting binary data to the output file. input and output must either be file objects or objects that mimic the file object interface. input will be read until input.read() returns an empty string.

decodestring(s)#

Decode the string s, which must contain one or more lines of base64 encoded data, and return a string containing the resulting binary data.

encode(input, output)#

Encode the contents of the input file and write the resulting base64 encoded data to the output file. input and output must either be file objects or objects that mimic the file object interface. input will be read until input.read() returns an empty string.

encodestring(s)#

Encode the string s, which can contain arbitrary binary data, and return a string containing one or more lines of base64 encoded data.

See also:#

— binasciisupport module containing ASCII-to-binary and binary-to-ASCII conversions Internet RFC 1521, MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies, section 5.2, “Base64 Content-Transfer-Encoding,” provides the definition of the base64 encoding.

BaseHTTPServer — Basic HTTP server.#

Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).

This module defines two classes for implementing HTTP servers (web servers). Usually, this module isn’t used directly, but is used as a basis for building functioning web servers. See the SimpleHTTPServer and CGIHTTPServer modules.

The first class, HTTPServer, is a SocketServer.TCPServer subclass. It creates and listens at the web socket, dispatching the requests to a handler. Code to create and run the server looks like this:

def run(server_class=BaseHTTPServer.HTTPServer,
        handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

class HTTPServer(server_address, RequestHandlerClass)#

This class builds on the TCPServer class by storing the server address as instance variables named server_name and server_port. The server is accessible by the handler, typically through the handler’s server instance variable.

class BaseHTTPRequestHandler(request, client_address, server)#

This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). BaseHTTPRequestHandler provides a number of class and instance variables, and methods for use by subclasses.

The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed from the request. For example, for the request method SPAM, the do_SPAM() method will be called with no arguments. All of the relevant information is stored in instance variables of the handler. Subclasses should not need to override or extend the __init__() method.

BaseHTTPRequestHandler has the following instance variables:

client_address#

Contains a tuple of the form (host, port) referring to the client’s address.

command#

Contains the command (request type). For example, ’GET’.

path#

Contains the request path.

request_version#

Contains the version string from the request. For example, ’HTTP/1.0’.

headers#

Holds an instance of the class specified by the MessageClass class variable. This instance parses and manages the headers in the HTTP request.

rfile#

Contains an input stream, positioned at the start of the optional input data.

wfile#

Contains the output stream for writing a response back to the client. Proper adherence to the HTTP protocol must be used when writing to this stream.

BaseHTTPRequestHandler has the following class variables:

server_version#

Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, ’BaseHTTP/0.2’.

sys_version#

Contains the Python system version, in a form usable by the version_string method and the server_version class variable. For example, ’Python/1.4’.

error_message_format#

Specifies a format string for building an error response to the client. It uses parenthesized, keyed format specifiers, so the format operand must be a dictionary. The code key should be an integer, specifying the numeric HTTP error code value. message should be a string containing a (detailed) error message of what occurred, and explain should be an explanation of the error code number. Default message and explain values can found in the responses class variable.

protocol_version#

This specifies the HTTP protocol version used in responses. Typically, this should not be overridden. Defaults to ’HTTP/1.0’.

MessageClass#

Specifies a rfc822.Message-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to mimetools.Message.

responses#

This variable contains a mapping of error code integers to two-element tuples containing a short and long message. For example, {code: (shortmessage, longmessage)}. The shortmessage is usually used as the message key in an error response, and longmessage as the explain key (see the error_message_format class variable).

A BaseHTTPRequestHandler instance has the following methods:

handle()#

Overrides the superclass’ handle() method to provide the specific handler behavior. This method will parse and dispatch the request to the appropriate do_*() method.

send_error(code)#

Sends and logs a complete error reply to the client. The numeric code specifies the HTTP error code, with message as optional, more specific text. A complete set of headers is sent, followed by text composed using the error_message_format class variable.

send_response(code)#

Sends a response header and logs the accepted request. The HTTP response line is sent, followed by Server and Date headers. The values for these two headers are picked up from the version_string() and date_time_string() methods, respectively.

send_header(keyword, value)#

Writes a specific MIME header to the output stream. keyword should specify the header keyword, with value specifying its value.

end_headers()#

Sends a blank line, indicating the end of the MIME headers in the response.

log_request()#

Logs an accepted (successful) request. code should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the size parameter.

log_error(…)#

Logs an error when a request cannot be fulfilled. By default, it passes the message to log_message(), so it takes the same arguments (format and additional values).

log_message(format, …)#

Logs an arbitrary message to sys.stderr. This is typically overridden to create custom error logging mechanisms. The format argument is a standard printf-style format string, where the additional arguments to log_message() are applied as inputs to the formatting. The client address and current date and time are prefixed to every message logged.

version_string()#

Returns the server software’s version string. This is a combination of the server_version and sys_version class variables.

date_time_string()#

Returns the current date and time, formatted for a message header.

log_data_time_string()#

Returns the current date and time, formatted for logging.

address_string()#

Returns the client address, formatted for logging. A name lookup is performed on the client’s IP address.

See also:#

— CGIHTTPServerExtended request handler that supports CGI scripts.

— SimpleHTTPServerBasic request handler that limits response to files actually under the document root.

Bastion — Restricting access to objects#

Providing restricted access to objects.

According to the dictionary, a bastion is “a fortified area or position”, or “something that is considered a stronghold.” It’s a suitable name for this module, which provides a way to forbid access to certain attributes of an object. It must always be used with the rexec module, in order to allow restricted-mode programs access to certain safe attributes of an object, while denying access to other, unsafe attributes.

Bastion(object)#

Protect the object object, returning a bastion for the object. Any attempt to access one of the object’s attributes will have to be approved by the filter function; if the access is denied an AttributeError exception will be raised.

If present, filter must be a function that accepts a string containing an attribute name, and returns true if access to that attribute will be permitted; if filter returns false, the access is denied. The default filter denies access to any function beginning with an underscore (_). The bastion’s string representation will be <Bastion for name> if a value for name is provided; otherwise, repr(object) will be used.

class, if present, should be a subclass of BastionClass; see the code in bastion.py for the details. Overriding the default BastionClass will rarely be required.

class BastionClass(getfunc, name)#

Class which actually implements bastion objects. This is the default class used by Bastion(). The getfunc parameter is a function which returns the value of an attribute which should be exposed to the restricted execution environment when called with the name of the attribute as the only parameter. name is used to construct the repr() of the BastionClass instance.

binascii — Convert between binary and ASCII#

Tools for converting between binary and various ASCII-encoded binary representations.

The binascii module contains a number of methods to convert between binary and various ASCII-encoded binary representations. Normally, you will not use these functions directly but use wrapper modules like uu or binhex instead, this module solely exists because bit-manipulation of large amounts of data is slow in Python.

The binascii module defines the following functions:

a2b_uu(string)#

Convert a single line of uuencoded data back to binary and return the binary data. Lines normally contain 45 (binary) bytes, except for the last line. Line data may be followed by whitespace.

b2a_uu(data)#

Convert binary data to a line of ASCII characters, the return value is the converted line, including a newline char. The length of data should be at most 45.

a2b_base64(string)#

Convert a block of base64 data back to binary and return the binary data. More than one line may be passed at a time.

b2a_base64(data)#

Convert binary data to a line of ASCII characters in base64 coding. The return value is the converted line, including a newline char. The length of data should be at most 57 to adhere to the base64 standard.

a2b_hqx(string)#

Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression. The string should contain a complete number of binary bytes, or (in case of the last portion of the binhex4 data) have the remaining bits zero.

rledecode_hqx(data)#

Perform RLE-decompression on the data, as per the binhex4 standard. The algorithm uses 0x90 after a byte as a repeat indicator, followed by a count. A count of 0 specifies a byte value of 0x90. The routine returns the decompressed data, unless data input data ends in an orphaned repeat indicator, in which case the Incomplete exception is raised.

rlecode_hqx(data)#

Perform binhex4 style RLE-compression on data and return the result.

b2a_hqx(data)#

Perform hexbin4 binary-to-ASCII translation and return the resulting string. The argument should already be RLE-coded, and have a length divisible by 3 (except possibly the last fragment).

crc_hqx(data, crc)#

Compute the binhex4 crc value of data, starting with an initial crc and returning the result.

crc32(data)#

Compute CRC-32, the 32-bit checksum of data, starting with an initial crc. This is consistent with the ZIP file checksum. Use as follows:

    print binascii.crc32("hello world")
    # Or, in two pieces:
    crc = binascii.crc32("hello")
    crc = binascii.crc32(" world", crc)
    print crc

b2a_hex(data)#

Return the hexadecimal representation of the binary data. Every byte of data is converted into the corresponding 2-digit hex representation. The resulting string is therefore twice as long as the length of data.

a2b_hex(hexstr)#

Return the binary data represented by the hexadecimal string hexstr. This function is the inverse of b2a_hex(). hexstr must contain an even number of hexadecimal digits (which can be upper or lower case), otherwise a TypeError is raised.

exception Error#

Exception raised on errors. These are usually programming errors.

exception Incomplete#

Exception raised on incomplete data. These are usually not programming errors, but may be handled by reading a little more data and trying again.

See also:#

— base64Support for base64 encoding used in MIME email messages.

— binhexSupport for the binhex format used on the Macintosh.

— uuSupport for UU encoding used on Unix.

binhex — Encode and decode binhex4 files#

Encode and decode files in binhex4 format.

This module encodes and decodes files in binhex4 format, a format allowing representation of Macintosh files in ASCII. On the Macintosh, both forks of a file and the finder information are encoded (or decoded), on other platforms only the data fork is handled.

The binhex module defines the following functions:

binhex(input, output)#

Convert a binary file with filename input to binhex file output. The output parameter can either be a filename or a file-like object (any object supporting a write() and close() method).

hexbin(input)#

Decode a binhex file input. input may be a filename or a file-like object supporting read() and close() methods. The resulting file is written to a file named output, unless the argument is omitted in which case the output filename is read from the binhex file.

See also:#

— binasciisupport module containing ASCII-to-binary and binary-to-ASCII conversions

Notes#

There is an alternative, more powerful interface to the coder and decoder, see the source for details.

If you code or decode textfiles on non-Macintosh platforms they will still use the Macintosh newline convention (carriage-return as end of line).

As of this writing, hexbin() appears to not work in all cases.

bisect — Array bisection algorithm#

Array bisection algorithms for binary searching.

This module provides support for maintaining a list in sorted order without having to sort the list after each insertion. For long lists of items with expensive comparison operations, this can be an improvement over the more common approach. The module is called bisect because it uses a basic bisection algorithm to do its work. The source code may be most useful as a working example of the algorithm (i.e., the boundary conditions are already right!).

The following functions are provided:

bisect(list, item)#

Locate the proper insertion point for item in list to maintain sorted order. The parameters lo and hi may be used to specify a subset of the list which should be considered. The return value is suitable for use as the first parameter to list.insert().

insort(list, item)#

Insert item in list in sorted order. This is equivalent to list.insert(bisect.bisect(list, item, lo, hi), item).

Example#

The bisect() function is generally useful for categorizing numeric data. This example uses bisect() to look up a letter grade for an exam total (say) based on a set of ordered numeric breakpoints: 85 and up is an ‘A’, 75..84 is a ‘B’, etc.

>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
>>> from bisect import bisect
>>> def grade(total):
...           return grades[bisect(breakpoints, total)]
...
>>> grade(66)
'C'
>>> map(grade, [33, 99, 77, 44, 12, 88])
['E', 'A', 'B', 'D', 'F', 'A']

__builtin__ — Built-in functions#

The set of built-in functions.

This module provides direct access to all ‘built-in’ identifiers of Python; e.g. __builtin__.open is the full name for the built-in function open(). See section, “Built-in Functions.”

bsddb — Interface to Berkeley DB library#

Interface to Berkeley DB database library

The bsddb module provides an interface to the Berkeley DB library. Users can create hash, btree or record based library files using the appropriate open call. Bsddb objects behave generally like dictionaries. Keys and values must be strings, however, so to use other objects as keys or to store other kinds of objects the user must serialize them somehow, typically using marshal.dumps or pickle.dumps.

There are two incompatible versions of the underlying library. Version 1.85 is widely available, but has some known bugs. Version 2 is not quite as widely used, but does offer some improvements. The bsddb module uses the 1.85 interface. Starting with Python 2.0, the configure script can usually determine the version of the library which is available and build it correctly. If you have difficulty getting configure to do the right thing, run it with the --help option to get information about additional options that can help. On Windows, you will need to define the HAVE_DB_185_H macro if you are building Python from source and using version 2 of the DB library.

The bsddb module defines the following functions that create objects that access the appropriate type of Berkeley DB file. The first two arguments of each function are the same. For ease of portability, only the first two arguments should be used in most instances.

hashopen(filename)#

Open the hash format file named filename. The optional flag identifies the mode used to open the file. It may be r (read only), w (read-write), c (read-write - create if necessary) or n (read-write - truncate to zero length). The other arguments are rarely used and are just passed to the low-level function. Consult the Berkeley DB documentation for their use and interpretation.

btopen(filename)#

Open the btree format file named filename. The optional flag identifies the mode used to open the file. It may be r (read only), w (read-write), c (read-write - create if necessary) or n (read-write - truncate to zero length). The other arguments are rarely used and are just passed to the low-level dbopen function. Consult the Berkeley DB documentation for their use and interpretation.

rnopen(filename)#

Open a DB record format file named filename. The optional flag identifies the mode used to open the file. It may be r (read only), w (read-write), c (read-write - create if necessary) or n (read-write - truncate to zero length). The other arguments are rarely used and are just passed to the low-level dbopen function. Consult the Berkeley DB documentation for their use and interpretation.

See also:#

— dbhashDBM-style interface to the bsddb

Hash, BTree and Record Objects#

Once instantiated, hash, btree and record objects support the following methods:

close()#

Close the underlying file. The object can no longer be accessed. Since there is no open open method for these objects, to open the file again a new bsddb module open function must be called.

keys()#

Return the list of keys contained in the DB file. The order of the list is unspecified and should not be relied on. In particular, the order of the list returned is different for different file formats.

has_key(key)#

Return 1 if the DB file contains the argument as a key.

set_location(key)#

Set the cursor to the item indicated by the key and return it.

first()#

Set the cursor to the first item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases.

next()#

Set the cursor to the next item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases.

previous()#

Set the cursor to the first item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases. This is not supported on hashtable databases (those opened with hashopen()).

last()#

Set the cursor to the last item in the DB file and return it. The order of keys in the file is unspecified. This is not supported on hashtable databases (those opened with hashopen()).

sync()#

Synchronize the database on disk.

Example:

>>> import bsddb
>>> db = bsddb.btopen('/tmp/spam.db', 'c')
>>> for i in range(10): db['%d'%i] = '%d'% (i*i)
... 
>>> db['3']
'9'
>>> db.keys()
['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
>>> db.first()
('0', '0')
>>> db.next()
('1', '1')
>>> db.last()
('9', '81')
>>> db.set_location('2')
('2', '4')
>>> db.previous() 
('1', '1')
>>> db.sync()
0

calendar — General calendar-related functions#

General functions for working with the calendar, including some emulation of the Unix cal program.

This module allows you to output calendars like the Unix cal program, and provides additional useful functions related to the calendar. By default, these calendars have Monday as the first day of the week, and Sunday as the last (the European convention). Use setfirstweekday() to set the first day of the week to Sunday (6) or to any other weekday.

setfirstweekday(weekday)#

Sets the weekday (0 is Monday, 6 is Sunday) to start each week. The values , , , , , , and are provided for convenience. For example, to set the first weekday to Sunday:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

firstweekday()#

Returns the current setting for the weekday to start each week.

isleap(year)#

Returns true if year is a leap year.

leapdays(y1, y2)#

Returns the number of leap years in the range [y1…y2].

weekday(year, month, day)#

Returns the day of the week (0 is Monday) for year (1970–…), month (1–12), day (1–31).

monthrange(year, month)#

Returns weekday of first day of the month and number of days in month, for the specified year and month.

monthcalendar(year, month)#

Returns a matrix representing a month’s calendar. Each row represents a week; days outside of the month a represented by zeros. Each week begins with Monday unless set by setfirstweekday().

prmonth(theyear, themonth)#

Prints a month’s calendar as returned by month().

month(theyear, themonth)#

Returns a month’s calendar in a multi-line string. If w is provided, it specifies the width of the date columns, which are centered. If l is given, it specifies the number of lines that each week will use. Depends on the first weekday as set by setfirstweekday().

prcal(year)#

Prints the calendar for an entire year as returned by calendar().

calendar(year)#

Returns a 3-column calendar for an entire year as a multi-line string. Optional parameters w, l, and c are for date column width, lines per week, and number of spaces between month columns, respectively. Depends on the first weekday as set by setfirstweekday().

timegm(tuple)#

An unrelated but handy function that takes a time tuple such as returned by the gmtime() function in the time module, and returns the corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In fact, time.gmtime() and timegm() are each others’ inverse.

See also:#

— timeLow-level time related functions.

cd — CD-ROM access on SGI systems#

Interface to the CD-ROM on Silicon Graphics systems.

This module provides an interface to the Silicon Graphics CD library. It is available only on Silicon Graphics systems.

The way the library works is as follows. A program opens the CD-ROM device with open() and creates a parser to parse the data from the CD with createparser(). The object returned by open() can be used to read data from the CD, but also to get status information for the CD-ROM device, and to get information about the CD, such as the table of contents. Data from the CD is passed to the parser, which parses the frames, and calls any callback functions that have previously been added.

An audio CD is divided into tracks or programs (the terms are used interchangeably). Tracks can be subdivided into indices. An audio CD contains a table of contents which gives the starts of the tracks on the CD. Index 0 is usually the pause before the start of a track. The start of the track as given by the table of contents is normally the start of index 1.

Positions on a CD can be represented in two ways. Either a frame number or a tuple of three values, minutes, seconds and frames. Most functions use the latter representation. Positions can be both relative to the beginning of the CD, and to the beginning of the track.

Module cd defines the following functions and constants:

createparser()#

Create and return an opaque parser object. The methods of the parser object are described below.

msftoframe(minutes, seconds, frames)#

Converts a (minutes, seconds, frames) triple representing time in absolute time code into the corresponding CD frame number.

open()#

Open the CD-ROM device. The return value is an opaque player object; methods of the player object are described below. The device is the name of the SCSI device file, e.g. ’/dev/scsi/sc0d4l0’, or None. If omitted or None, the hardware inventory is consulted to locate a CD-ROM drive. The mode, if not omited, should be the string ’r’.

The module defines the following variables:

exception error#

Exception raised on various errors.

DATASIZE#

The size of one frame’s worth of audio data. This is the size of the audio data as passed to the callback of type audio.

BLOCKSIZE#

The size of one uninterpreted frame of audio data.

The following variables are states as returned by getstatus():

READY#

The drive is ready for operation loaded with an audio CD.

NODISC#

The drive does not have a CD loaded.

CDROM#

The drive is loaded with a CD-ROM. Subsequent play or read operations will return I/O errors.

ERROR#

An error occurred while trying to read the disc or its table of contents.

PLAYING#

The drive is in CD player mode playing an audio CD through its audio jacks.

PAUSED#

The drive is in CD layer mode with play paused.

STILL#

The equivalent of on older (non 3301) model Toshiba CD-ROM drives. Such drives have never been shipped by SGI.

audio#

Integer constants describing the various types of parser callbacks that can be set by the addcallback() method of CD parser objects (see below).

Player Objects#

Player objects (returned by open()) have the following methods:

allowremoval()#

Unlocks the eject button on the CD-ROM drive permitting the user to eject the caddy if desired.

bestreadsize()#

Returns the best value to use for the num_frames parameter of the readda() method. Best is defined as the value that permits a continuous flow of data from the CD-ROM drive.

close()#

Frees the resources associated with the player object. After calling close(), the methods of the object should no longer be used.

eject()#

Ejects the caddy from the CD-ROM drive.

getstatus()#

Returns information pertaining to the current state of the CD-ROM drive. The returned information is a tuple with the following values: state, track, rtime, atime, ttime, first, last, scsi_audio, cur_block. rtime is the time relative to the start of the current track; atime is the time relative to the beginning of the disc; ttime is the total time on the disc. For more information on the meaning of the values, see the man page . The value of state is one of the following: , , , , , , or .

gettrackinfo(track)#

Returns information about the specified track. The returned information is a tuple consisting of two elements, the start time of the track and the duration of the track.

msftoblock(min, sec, frame)#

Converts a minutes, seconds, frames triple representing a time in absolute time code into the corresponding logical block number for the given CD-ROM drive. You should use msftoframe() rather than msftoblock() for comparing times. The logical block number differs from the frame number by an offset required by certain CD-ROM drives.

play(start, play)#

Starts playback of an audio CD in the CD-ROM drive at the specified track. The audio output appears on the CD-ROM drive’s headphone and audio jacks (if fitted). Play stops at the end of the disc. start is the number of the track at which to start playing the CD; if play is 0, the CD will be set to an initial paused state. The method togglepause() can then be used to commence play.

playabs(minutes, seconds, frames, play)#

Like play(), except that the start is given in minutes, seconds, and frames instead of a track number.

playtrack(start, play)#

Like play(), except that playing stops at the end of the track.

playtrackabs(track, minutes, seconds, frames, play)#

Like play(), except that playing begins at the specified absolute time and ends at the end of the specified track.

preventremoval()#

Locks the eject button on the CD-ROM drive thus preventing the user from arbitrarily ejecting the caddy.

readda(num_frames)#

Reads the specified number of frames from an audio CD mounted in the CD-ROM drive. The return value is a string representing the audio frames. This string can be passed unaltered to the parseframe() method of the parser object.

seek(minutes, seconds, frames)#

Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to an absolute time code location specified in minutes, seconds, and frames. The return value is the logical block number to which the pointer has been set.

seekblock(block)#

Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to the specified logical block number. The return value is the logical block number to which the pointer has been set.

seektrack(track)#

Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to the specified track. The return value is the logical block number to which the pointer has been set.

stop()#

Stops the current playing operation.

togglepause()#

Pauses the CD if it is playing, and makes it play if it is paused.

Parser Objects#

Parser objects (returned by createparser()) have the following methods:

addcallback(type, func, arg)#

Adds a callback for the parser. The parser has callbacks for eight different types of data in the digital audio data stream. Constants for these types are defined at the cd module level (see above). The callback is called as follows: func(arg, type, data), where arg is the user supplied argument, type is the particular type of callback, and data is the data returned for this type of callback. The type of the data depends on the type of callback as follows:

deleteparser()#

Deletes the parser and frees the memory it was using. The object should not be used after this call. This call is done automatically when the last reference to the object is removed.

parseframe(frame)#

Parses one or more frames of digital audio data from a CD such as returned by readda(). It determines which subcodes are present in the data. If these subcodes have changed since the last frame, then parseframe() executes a callback of the appropriate type passing to it the subcode data found in the frame. Unlike the C function, more than one frame of digital audio data can be passed to this method.

removecallback(type)#

Removes the callback for the given type.

resetparser()#

Resets the fields of the parser used for tracking subcodes to an initial state. resetparser() should be called after the disc has been changed.

ConfigParser — Configuration file parser#

Configuration file parser.

This module defines the class ConfigParser.

The ConfigParser class implements a basic configuration file parser language which provides a structure similar to what you would find on Microsoft Windows INI files. You can use this to write Python programs which can be customized by end users easily.

The configuration file consists of sections, lead by a [section] header and followed by name: value entries, with continuations in the style of RFC 822; name=value is also accepted. Note that leading whitespace is removed from values. The optional values can contain format strings which refer to other values in the same section, or values in a special DEFAULT section. Additional defaults can be provided upon initialization and retrieval. Lines beginning with # or ; are ignored and may be used to provide comments.

For example:

foodir: %(dir)s/whatever
dir=frob

would resolve the %(dir)s to the value of dir (frob in this case). All reference expansions are done on demand.

Default values can be specified by passing them into the ConfigParser constructor as a dictionary. Additional defaults may be passed into the get() method which will override all others.

class ConfigParser()#

Return a new instance of the ConfigParser class. When defaults is given, it is initialized into the dictionary of intrinsic defaults. They keys must be strings, and the values must be appropriate for the %()s string interpolation. Note that name is always an intrinsic default; its value is the section name.

exception NoSectionError#

Exception raised when a specified section is not found.

exception DuplicateSectionError#

Exception raised when multiple sections with the same name are found, or if add_section() is called with the name of a section that is already present.

exception NoOptionError#

Exception raised when a specified option is not found in the specified section.

exception InterpolationError#

Exception raised when problems occur performing string interpolation.

exception MissingSectionHeaderError#

Exception raised when attempting to parse a file which has no section headers.

exception ParsingError#

Exception raised when errors occur attempting to parse a file.

See also:#

— shlexSupport for a creating Unix shell-like minilanguages which can be used as an alternate format for application configuration files.

ConfigParser Objects#

ConfigParser instances have the following methods:

defaults()#

Return a dictionary containing the instance-wide defaults.

sections()#

Return a list of the sections available; DEFAULT is not included in the list.

add_section(section)#

Add a section named section to the instance. If a section by the given name already exists, DuplicateSectionError is raised.

has_section(section)#

Indicates whether the named section is present in the configuration. The DEFAULT section is not acknowledged.

options(section)#

Returns a list of options available in the specified section.

has_option(section, option)#

If the given section exists, and contains the given option. return 1; otherwise return 0. (New in 1.6)

read(filenames)#

Read and parse a list of filenames. If filenames is a string or Unicode string, it is treated as a single filename.

readfp(fp)#

Read and parse configuration data from the file or file-like object in fp (only the readline() method is used). If filename is omitted and fp has a name attribute, that is used for filename; the default is <???>.

get(section, option)#

Get an option value for the provided section. All the % interpolations are expanded in the return values, based on the defaults passed into the constructor, as well as the options vars provided, unless the raw argument is true.

getint(section, option)#

A convenience method which coerces the option in the specified section to an integer.

getfloat(section, option)#

A convenience method which coerces the option in the specified section to a floating point number.

getboolean(section, option)#

A convenience method which coerces the option in the specified section to a boolean value. Note that the only accepted values for the option are 0 and 1, any others will raise ValueError.

set(section, option, value)#

If the given section exists, set the given option to the specified value; otherwise raise NoSectionError. (New in 1.6)

write(fileobject)#

Write a representation of the configuration to the specified file object. This representation can be parsed by a future read() call. (New in 1.6)

remove_option(section, option)#

Remove the specified option from the specified section. If the section does not exist, raise NoSectionError. If the option existed to be removed, return 1; otherwise return 0. (New in 1.6)

remove_section(section)#

Remove the specified section from the configuration. If the section in fact existed, return 1. Otherwise return 0.

cgi — Common Gateway Interface support.#

Common Gateway Interface support, used to interpret forms in server-side scripts.

Support module for CGI (Common Gateway Interface) scripts.

This module defines a number of utilities for use by CGI scripts written in Python.

Introduction#

A CGI script is invoked by an HTTP server, usually to process user input submitted through an HTML <FORM> or <ISINDEX> element.

Most often, CGI scripts live in the server’s special cgi-bin directory. The HTTP server places all sorts of information about the request (such as the client’s hostname, the requested URL, the query string, and lots of other goodies) in the script’s shell environment, executes the script, and sends the script’s output back to the client.

The script’s input is connected to the client too, and sometimes the form data is read this way; at other times the form data is passed via the “query string” part of the URL. This module is intended to take care of the different cases and provide a simpler interface to the Python script. It also provides a number of utilities that help in debugging scripts, and the latest addition is support for file uploads from a form (if your browser supports it — Grail 0.3 and Netscape 2.0 do).

The output of a CGI script should consist of two sections, separated by a blank line. The first section contains a number of headers, telling the client what kind of data is following. Python code to generate a minimal header section looks like this:

print "Content-Type: text/html"     # HTML is following
print                               # blank line, end of headers

The second section is usually HTML, which allows the client software to display nicely formatted text with header, in-line images, etc. Here’s Python code that prints a simple piece of HTML:

print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"

Using the cgi module#

Begin by writing import cgi. Do not use from cgi import * — the module defines all sorts of names for its own use or for backward compatibility that you don’t want in your namespace.

It’s best to use the FieldStorage class. The other classes defined in this module are provided mostly for backward compatibility. Instantiate it exactly once, without arguments. This reads the form contents from standard input or the environment (depending on the value of various environment variables set according to the CGI standard). Since it may consume standard input, it should be instantiated only once.

The FieldStorage instance can be indexed like a Python dictionary, and also supports the standard dictionary methods has_key() and keys(). Form fields containing empty strings are ignored and do not appear in the dictionary; to keep such values, provide the optional keep_blank_values argument when creating the FieldStorage instance.

For instance, the following code (which assumes that the Content-Type header and blank line have already been printed) checks that the fields name and addr are both set to a non-empty string:

form = cgi.FieldStorage()
form_ok = 0
if form.has_key("name") and form.has_key("addr"):
    form_ok = 1
if not form_ok:
    print "<H1>Error</H1>"
    print "Please fill in the name and addr fields."
    return
print "<p>name:", form["name"].value
print "<p>addr:", form["addr"].value
...further form processing here...

Here the fields, accessed through form[key], are themselves instances of FieldStorage (or MiniFieldStorage, depending on the form encoding). The value attribute of the instance yields the string value of the field. The getvalue() method returns this string value directly; it also accepts an optional second argument as a default to return if the requested key is not present.

If the submitted form data contains more than one field with the same name, the object retrieved by form[key] is not a FieldStorage or MiniFieldStorage instance but a list of such instances. Similarly, in this situation, form.getvalue(key) would return a list of strings. If you expect this possibility (i.e., when your HTML form contains multiple fields with the same name), use the type() function to determine whether you have a single instance or a list of instances. For example, here’s code that concatenates any number of username fields, separated by commas:

value = form.getvalue("username", "")
if type(value) is type([]):
    # Multiple username fields specified
    usernames = ",".join(value)
else:
    # Single or no username field specified
    usernames = value

If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute:

fileitem = form["userfile"]
if fileitem.file:
    # It's an uploaded file; count lines
    linecount = 0
    while 1:
        line = fileitem.file.readline()
        if not line: break
        linecount = linecount + 1

The file upload draft standard entertains the possibility of uploading multiple files from one field (using a recursive encoding). When this occurs, the item will be a dictionary-like FieldStorage item. This can be determined by testing its type attribute, which should be (or perhaps another MIME type matching ). In this case, it can be iterated over recursively just like the top-level form object.

When a form is submitted in the “old” format (as the query string or as a single data part of type ), the items will actually be instances of the class MiniFieldStorage. In this case, the list, file, and filename attributes are always None.

Old classes#

These classes, present in earlier versions of the cgi module, are still supported for backward compatibility. New applications should use the FieldStorage class.

SvFormContentDict stores single value form content as dictionary; it assumes each field name occurs in the form only once.

FormContentDict stores multiple value form content as a dictionary (the form items are lists of values). Useful if your form contains multiple fields with the same name.

Other classes (FormContent, InterpFormContentDict) are present for backwards compatibility with really old applications only. If you still use these and would be inconvenienced when they disappeared from a next version of this module, drop me a note.

Functions#

These are useful if you want more control, or if you want to employ some of the algorithms implemented in this module in other circumstances.

parse(fp)#

Parse a query in the environment or from a file (default sys.stdin).

parse_qs(qs)#

Parse a query string given as a string argument (data of type ). Data are returned as a dictionary. The dictionary keys are the unique query variable names and the values are lists of values for each name.

The optional argument keep_blank_values is a flag indicating whether blank values in URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that blank values are to be ignored and treated as if they were not included.

The optional argument strict_parsing is a flag indicating what to do with parsing errors. If false (the default), errors are silently ignored. If true, errors raise a ValueError exception.

parse_qsl(qs)#

Parse a query string given as a string argument (data of type ). Data are returned as a list of name, value pairs.

The optional argument keep_blank_values is a flag indicating whether blank values in URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that blank values are to be ignored and treated as if they were not included.

The optional argument strict_parsing is a flag indicating what to do with parsing errors. If false (the default), errors are silently ignored. If true, errors raise a ValueError exception.

parse_multipart(fp, pdict)#

Parse input of type (for file uploads). Arguments are fp for the input file and pdict for a dictionary containing other parameters in the Content-Type header.

Returns a dictionary just like parse_qs() keys are the field names, each value is a list of values for that field. This is easy to use but not much good if you are expecting megabytes to be uploaded — in that case, use the FieldStorage class instead which is much more flexible.

Note that this does not parse nested multipart parts — use FieldStorage for that.

parse_header(string)#

Parse a MIME header (such as Content-Type) into a main value and a dictionary of parameters.

test()#

Robust test CGI script, usable as main program. Writes minimal HTTP headers and formats all information provided to the script in HTML form.

print_environ()#

Format the shell environment in HTML.

print_form(form)#

Format a form in HTML.

print_directory()#

Format the current directory in HTML.

print_environ_usage()#

Print a list of useful (used by CGI) environment variables in HTML.

escape(s)#

Convert the characters &, < and > in string s to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML. If the optional flag quote is true, the double quote character (") is also translated; this helps for inclusion in an HTML attribute value, e.g. in <A HREF="...">.

Caring about security#

There’s one important rule: if you invoke an external program (e.g. via the os.system() or os.popen() functions), make very sure you don’t pass arbitrary strings received from the client to the shell. This is a well-known security hole whereby clever hackers anywhere on the web can exploit a gullible CGI script to invoke arbitrary shell commands. Even parts of the URL or field names cannot be trusted, since the request doesn’t have to come from your form!

To be on the safe side, if you must pass a string gotten from a form to a shell command, you should make sure the string contains only alphanumeric characters, dashes, underscores, and periods.

Installing your CGI script on a Unix system#

Read the documentation for your HTTP server and check with your local system administrator to find the directory where CGI scripts should be installed; usually this is in a directory cgi-bin in the server tree.

Make sure that your script is readable and executable by “others”; the Unix file mode should be 0755 octal (use chmod 0755 filename). Make sure that the first line of the script contains #! starting in column 1 followed by the pathname of the Python interpreter, for instance:

#!/usr/local/bin/python

Make sure the Python interpreter exists and is executable by “others”.

Make sure that any files your script needs to read or write are readable or writable, respectively, by “others” — their mode should be 0644 for readable and 0666 for writable. This is because, for security reasons, the HTTP server executes your script as user “nobody”, without any special privileges. It can only read (write, execute) files that everybody can read (write, execute). The current directory at execution time is also different (it is usually the server’s cgi-bin directory) and the set of environment variables is also different from what you get at login. In particular, don’t count on the shell’s search path for executables () or the Python module search path () to be set to anything interesting.

If you need to load modules from a directory which is not on Python’s default module search path, you can change the path in your script, before importing other modules, e.g.:

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")

(This way, the directory inserted last will be searched first!)

Instructions for non-Unix systems will vary; check your HTTP server’s documentation (it will usually have a section on CGI scripts).

Testing your CGI script#

Unfortunately, a CGI script will generally not run when you try it from the command line, and a script that works perfectly from the command line may fail mysteriously when run from the server. There’s one reason why you should still test your script from the command line: if it contains a syntax error, the Python interpreter won’t execute it at all, and the HTTP server will most likely send a cryptic error to the client.

Assuming your script has no syntax errors, yet it does not work, you have no choice but to read the next section.

Debugging CGI scripts#

First of all, check for trivial installation errors — reading the section above on installing your CGI script carefully can save you a lot of time. If you wonder whether you have understood the installation procedure correctly, try installing a copy of this module file (cgi.py) as a CGI script. When invoked as a script, the file will dump its environment and the contents of the form in HTML form. Give it the right mode etc, and send it a request. If it’s installed in the standard cgi-bin directory, it should be possible to send it a request by entering a URL into your browser of the form:

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

If this gives an error of type 404, the server cannot find the script – perhaps you need to install it in a different directory. If it gives another error (e.g. 500), there’s an installation problem that you should fix before trying to go any further. If you get a nicely formatted listing of the environment and form content (in this example, the fields should be listed as “addr” with value “At Home” and “name” with value “Joe Blow”), the cgi.py script has been installed correctly. If you follow the same procedure for your own script, you should now be able to debug it.

The next step could be to call the cgi module’s test() function from your script: replace its main code with the single statement

cgi.test()

This should produce the same results as those gotten from installing the cgi.py file itself.

When an ordinary Python script raises an unhandled exception (e.g. because of a typo in a module name, a file that can’t be opened, etc.), the Python interpreter prints a nice traceback and exits. While the Python interpreter will still do this when your CGI script raises an exception, most likely the traceback will end up in one of the HTTP server’s log file, or be discarded altogether.

Fortunately, once you have managed to get your script to execute some code, it is easy to catch exceptions and cause a traceback to be printed. The test() function below in this module is an example. Here are the rules:

1. Import the traceback module before entering the … statement

2. Assign sys.stderr to be sys.stdout

3. Make sure you finish printing the headers and the blank line early

4. Wrap all remaining code in a … statement

5. In the except clause, call traceback.print_exc()

For example:

import sys
import traceback
print "Content-Type: text/html"
print
sys.stderr = sys.stdout
try:
    ...your code here...
except:
    print "\n\n<PRE>"
    traceback.print_exc()

Notes: The assignment to sys.stderr is needed because the traceback prints to sys.stderr. The print "nn<PRE>" statement is necessary to disable the word wrapping in HTML.

If you suspect that there may be a problem in importing the traceback module, you can use an even more robust approach (which only uses built-in modules):

import sys
sys.stderr = sys.stdout
print "Content-Type: text/plain"
print
...your code here...

This relies on the Python interpreter to print the traceback. The content type of the output is set to plain text, which disables all HTML processing. If your script works, the raw HTML will be displayed by your client. If it raises an exception, most likely after the first two lines have been printed, a traceback will be displayed. Because no HTML interpretation is going on, the traceback will readable.

Common problems and solutions#

• Most HTTP servers buffer the output from CGI scripts until the script is completed. This means that it is not possible to display a progress report on the client’s display while the script is running.

• Check the installation instructions above.

• Check the HTTP server’s log files. (tail -f logfile in a separate window may be useful!)

• Always check a script for syntax errors first, by doing something like python script.py.

• When using any of the debugging techniques, don’t forget to add import sys to the top of the script.

• When invoking external programs, make sure they can be found. Usually, this means using absolute path names — is usually not set to a very useful value in a CGI script.

• When reading or writing external files, make sure they can be read or written by every user on the system.

• Don’t try to give a CGI script a set-uid mode. This doesn’t work on most systems, and is a security liability as well.

CGIHTTPServer — A Do-Something Request Handler#

This module provides a request handler for HTTP servers which can run CGI scripts.

The CGIHTTPServer module defines a request-handler class, interface compatible with BaseHTTPServer.BaseHTTPRequestHandler and inherits behavior from SimpleHTTPServer.SimpleHTTPRequestHandler but can also run CGI scripts.

Note: This module is Unix dependent since it creates the CGI process using os.fork() and os.exec().

The CGIHTTPServer module defines the following class:

class CGIHTTPRequestHandler(request, client_address, server)#

This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic structure to local directory structure is exactly as in SimpleHTTPServer.SimpleHTTPRequestHandler.

The class will however, run the CGI script, instead of serving it as a file, if it guesses it to be a CGI script. Only directory-based CGI are used — the other common server configuration is to treat special extensions as denoting CGI scripts.

The do_GET() and do_HEAD() functions are modified to run CGI scripts and serve the output, instead of serving files, if the request leads to somewhere below the cgi_directories path.

The CGIHTTPRequestHandler defines the following data member:

cgi_directories#

This defaults to [’/cgi-bin’, ’/htbin’] and describes directories to treat as containing CGI scripts.

The CGIHTTPRequestHandler defines the following methods:

do_POST()#

This method serves the ’POST’ request type, only allowed for CGI scripts. Error 501, “Can only POST to CGI scripts”, is output when trying to POST to a non-CGI url.

Note that CGI scripts will be run with UID of user nobody, for security reasons. Problems with the CGI script will be translated to error 403.

For example usage, see the implementation of the test() function.

See also:#

— BaseHTTPServerBase class implementation for Web server and request handler.

chunk — Read IFF chunked data#

Module to read IFF chunks.

This module provides an interface for reading files that use EA IFF 85 chunks.¹ This format is used in at least the Audio Interchange File Format (AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format is closely related and can also be read using this module.

A chunk has the following structure:

The ID is a 4-byte string which identifies the type of chunk.

The size field (a 32-bit value, encoded using big-endian byte order) gives the size of the chunk data, not including the 8-byte header.

Usually an IFF-type file consists of one or more chunks. The proposed usage of the Chunk class defined here is to instantiate an instance at the start of each chunk and read from the instance until it reaches the end, after which a new instance can be instantiated. At the end of the file, creating a new instance will fail with a EOFError exception.

class Chunk(file)#

Class which represents a chunk. The file argument is expected to be a file-like object. An instance of this class is specifically allowed. The only method that is needed is read(). If the methods seek() and tell() are present and don’t raise an exception, they are also used. If these methods are present and raise an exception, they are expected to not have altered the object. If the optional argument align is true, chunks are assumed to be aligned on 2-byte boundaries. If align is false, no alignment is assumed. The default value is true. If the optional argument bigendian is false, the chunk size is assumed to be in little-endian order. This is needed for WAVE audio files. The default value is true. If the optional argument inclheader is true, the size given in the chunk header includes the size of the header. The default value is false.

A Chunk object supports the following methods:

getname()#

Returns the name (ID) of the chunk. This is the first 4 bytes of the chunk.

getsize()#

Returns the size of the chunk.

close()#

Close and skip to the end of the chunk. This does not close the underlying file.

The remaining methods will raise IOError if called after the close() method has been called.

isatty()#

Returns 0.

seek(pos)#

Set the chunk’s current position. The whence argument is optional and defaults to 0 (absolute file positioning); other values are 1 (seek relative to the current position) and 2 (seek relative to the file’s end). There is no return value. If the underlying file does not allow seek, only forward seeks are allowed.

tell()#

Return the current position into the chunk.

read()#

Read at most size bytes from the chunk (less if the read hits the end of the chunk before obtaining size bytes). If the size argument is negative or omitted, read all data until the end of the chunk. The bytes are returned as a string object. An empty string is returned when the end of the chunk is encountered immediately.

skip()#

Skip to the end of the chunk. All further calls to read() for the chunk will return ’’. If you are not interested in the contents of the chunk, this method should be called so that the file points to the start of the next chunk.

cmath — Mathematical functions for complex numbers#

Mathematical functions for complex numbers.

This module is always available. It provides access to mathematical functions for complex numbers. The functions are:

acos(x)#

Return the arc cosine of x.

acosh(x)#

Return the hyperbolic arc cosine of x.

asin(x)#

Return the arc sine of x.

asinh(x)#

Return the hyperbolic arc sine of x.

atan(x)#

Return the arc tangent of x.

atanh(x)#

Return the hyperbolic arc tangent of x.

cos(x)#

Return the cosine of x.

cosh(x)#

Return the hyperbolic cosine of x.

exp(x)#

Return the exponential value e**x.

log(x)#

Return the natural logarithm of x.

log10(x)#

Return the base-10 logarithm of x.

sin(x)#

Return the sine of x.

sinh(x)#

Return the hyperbolic sine of x.

sqrt(x)#

Return the square root of x.

tan(x)#

Return the tangent of x.

tanh(x)#

Return the hyperbolic tangent of x.

The module also defines two mathematical constants:

pi#

The mathematical constant pi, as a real.

e#

The mathematical constant e, as a real.

Note that the selection of functions is similar, but not identical, to that in module math. The reason for having two modules is that some users aren’t interested in complex numbers, and perhaps don’t even know what they are. They would rather have math.sqrt(-1) raise an exception than return a complex number. Also note that the functions defined in cmath always return a complex number, even if the answer can be expressed as a real number (in which case the complex number has an imaginary part of zero).

cmd — Build line-oriented command interpreters.#

Build line-oriented command interpreters; this is used by module pdb.

The Cmd class provides a simple framework for writing line-oriented command interpreters. These are often useful for test harnesses, administrative tools, and prototypes that will later be wrapped in a more sophisticated interface.

class Cmd()#

A Cmd instance or subclass instance is a line-oriented interpreter framework. There is no good reason to instantiate Cmd itself; rather, it’s useful as a superclass of an interpreter class you define yourself in order to inherit Cmd’s methods and encapsulate action methods.

Cmd Objects#

A Cmd instance has the following methods:

cmdloop()#

Repeatedly issue a prompt, accept input, parse an initial prefix off the received input, and dispatch to action methods, passing them the remainder of the line as argument.

The optional argument is a banner or intro string to be issued before the first prompt (this overrides the intro class member).

If the readline module is loaded, input will automatically inherit bash-like history-list editing (e.g. Ctrl-P scrolls back to the last command, Ctrl-N forward to the next one, Ctrl-F moves the cursor to the right non-destructively, Ctrl-B moves the cursor to the left non-destructively, etc.).

An end-of-file on input is passed back as the string ’EOF’.

An interpreter instance will recognize a command name foo if and only if it has a method do_foo(). As a special case, a line beginning with the character ? is dispatched to the method do_help(). As another special case, a line beginning with the character ! is dispatched to the method do_shell (if such a method is defined).

All subclasses of Cmd inherit a predefined do_help. This method, called with an argument bar, invokes the corresponding method help_bar(). With no argument, do_help() lists all available help topics (that is, all commands with corresponding help_*() methods), and also lists any undocumented commands.

onecmd(str)#

Interpret the argument as though it had been typed in in response to the prompt.

emptyline()#

Method called when an empty line is entered in response to the prompt. If this method is not overridden, it repeats the last nonempty command entered.

default(line)#

Method called on an input line when the command prefix is not recognized. If this method is not overridden, it prints an error message and returns.

precmd()#

Hook method executed just before the input prompt is issued. This method is a stub in Cmd; it exists to be overridden by subclasses.

postcmd()#

Hook method executed just after a command dispatch is finished. This method is a stub in Cmd; it exists to be overridden by subclasses.

preloop()#

Hook method executed once when cmdloop() is called. This method is a stub in Cmd; it exists to be overridden by subclasses.

postloop()#

Hook method executed once when cmdloop() is about to return. This method is a stub in Cmd; it exists to be overridden by subclasses.

Instances of Cmd subclasses have some public instance variables:

prompt#

The prompt issued to solicit input.

identchars#

The string of characters accepted for the command prefix.

lastcmd#

The last nonempty command prefix seen.

intro#

A string to issue as an intro or banner. May be overridden by giving the cmdloop() method an argument.

doc_header#

The header to issue if the help output has a section for documented commands.

misc_header#

The header to issue if the help output has a section for miscellaneous help topics (that is, there are help_*() methods without corresponding do_*() methods).

undoc_header#

The header to issue if the help output has a section for undocumented commands (that is, there are do_*() methods without corresponding help_*() methods).

ruler#

The character used to draw separator lines under the help-message headers. If empty, no ruler line is drawn. It defaults to =.

cmp — File comparisons#

Compare files very efficiently.

Deprecated since version 1.5.3: Use the filecmp module instead.

The cmp module defines a function to compare files, taking all sort of short-cuts to make it a highly efficient operation.

The cmp module defines the following function:

cmp(f1, f2)#

Compare two files given as names. The following tricks are used to optimize the comparisons:

• Files with identical type, size and mtime are assumed equal.

• Files with different type or size are never equal.

• The module only compares files it already compared if their signature (type, size and mtime) changed.

• No external programs are called.

Example:

>>> import cmp
>>> cmp.cmp('libundoc.tex', 'libundoc.tex')
1
>>> cmp.cmp('libundoc.tex', 'lib.tex')
0

cmpcache — Efficient file comparisons#

Compare files very efficiently.

Deprecated since version 1.5.3: Use the filecmp module instead.

The cmpcache module provides an identical interface and similar functionality as the cmp module, but can be a bit more efficient as it uses statcache.stat() instead of os.stat() (see the statcache module for information on the difference).

Note: Using the statcache module to provide stat() information results in trashing the cache invalidation mechanism: results are not as reliable. To ensure “current” results, use cmp.cmp() instead of the version defined in this module, or use statcache.forget() to invalidate the appropriate entries.

code — Interpreter base classes#

Base classes for interactive Python interpreters.

The code module provides facilities to implement read-eval-print loops in Python. Two classes and convenience functions are included which can be used to build applications which provide an interactive interpreter prompt.

class InteractiveInterpreter()#

This class deals with parsing and interpreter state (the user’s namespace); it does not deal with input buffering or prompting or input file naming (the filename is always passed in explicitly). The optional locals argument specifies the dictionary in which code will be executed; it defaults to a newly created dictionary with key ’__name__’ set to ’__console__’ and key ’__doc__’ set to None.

class InteractiveConsole()#

Closely emulate the behavior of the interactive Python interpreter. This class builds on InteractiveInterpreter and adds prompting using the familiar sys.ps1 and sys.ps2, and input buffering.

interact()#

Convenience function to run a read-eval-print loop. This creates a new instance of InteractiveConsole and sets readfunc to be used as the raw_input() method, if provided. If local is provided, it is passed to the InteractiveConsole constructor for use as the default namespace for the interpreter loop. The interact() method of the instance is then run with banner passed as the banner to use, if provided. The console object is discarded after use.

compile_command(source)#

This function is useful for programs that want to emulate Python’s interpreter main loop (a.k.a. the read-eval-print loop). The tricky part is to determine when the user has entered an incomplete command that can be completed by entering more text (as opposed to a complete command or a syntax error). This function almost always makes the same decision as the real interpreter main loop.

source is the source string; filename is the optional filename from which source was read, defaulting to ’<input>’; and symbol is the optional grammar start symbol, which should be either ’single’ (the default) or ’eval’.

Returns a code object (the same as compile(source, filename, symbol)) if the command is complete and valid; None if the command is incomplete; raises SyntaxError if the command is complete and contains a syntax error, or raises OverflowError if the command includes a numeric constant which exceeds the range of the appropriate numeric type.

Interactive Interpreter Objects#

runsource(source)#

Compile and run some source in the interpreter. Arguments are the same as for compile_command(); the default for filename is ’<input>’, and for symbol is ’single’. One several things can happen:

• The input is incorrect; compile_command() raised an exception (SyntaxError or OverflowError). A syntax traceback will be printed by calling the showsyntaxerror() method. runsource() returns 0.

• The input is incomplete, and more input is required; compile_command() returned None. runsource() returns 1.

• The input is complete; compile_command() returned a code object. The code is executed by calling the runcode() (which also handles run-time exceptions, except for SystemExit). runsource() returns 0.

The return value can be used to decide whether to use sys.ps1 or sys.ps2 to prompt the next line.

runcode(code)#

Execute a code object. When an exception occurs, showtraceback() is called to display a traceback. All exceptions are caught except SystemExit, which is allowed to propagate.

A note about KeyboardInterrupt: this exception may occur elsewhere in this code, and may not always be caught. The caller should be prepared to deal with it.

showsyntaxerror()#

Display the syntax error that just occurred. This does not display a stack trace because there isn’t one for syntax errors. If filename is given, it is stuffed into the exception instead of the default filename provided by Python’s parser, because it always uses ’<string>’ when reading from a string. The output is written by the write() method.

showtraceback()#

Display the exception that just occurred. We remove the first stack item because it is within the interpreter object implementation. The output is written by the write() method.

write(data)#

Write a string to the standard error stream (sys.stderr). Derived classes should override this to provide the appropriate output handling as needed.

Interactive Console Objects#

The InteractiveConsole class is a subclass of InteractiveInterpreter, and so offers all the methods of the interpreter objects as well as the following additions.

interact()#

Closely emulate the interactive Python console. The optional banner argument specify the banner to print before the first interaction; by default it prints a banner similar to the one printed by the standard Python interpreter, followed by the class name of the console object in parentheses (so as not to confuse this with the real interpreter – since it’s so close!).

push(line)#

Push a line of source text to the interpreter. The line should not have a trailing newline; it may have internal newlines. The line is appended to a buffer and the interpreter’s runsource() method is called with the concatenated contents of the buffer as source. If this indicates that the command was executed or invalid, the buffer is reset; otherwise, the command is incomplete, and the buffer is left as it was after the line was appended. The return value is 1 if more input is required, 0 if the line was dealt with in some way (this is the same as runsource()).

resetbuffer()#

Remove any unhandled source text from the input buffer.

raw_input()#

Write a prompt and read a line. The returned line does not include the trailing newline. When the user enters the EOF key sequence, EOFError is raised. The base implementation uses the built-in function raw_input(); a subclass may replace this with a different implementation.

codecs — Codec registry and base classes#

Encode and decode data and streams.

This module defines base classes for standard Python codecs (encoders and decoders) and provides access to the internal Python codec registry which manages the codec lookup process.

It defines the following functions:

register(search_function)#

Register a codec search function. Search functions are expected to take one argument, the encoding name in all lower case letters, and return a tuple of functions (encoder, decoder, stream_reader, stream_writer) taking the following arguments:

encoder and decoder: These must be functions or methods which have the same interface as the .encode/.decode methods of Codec instances (see Codec Interface). The functions/methods are expected to work in a stateless mode.

stream_reader and stream_writer: These have to be factory functions providing the following interface:

factory(stream, errors=’strict’)

The factory functions must return objects providing the interfaces defined by the base classes StreamWriter and StreamReader, respectively. Stream codecs can maintain state.

Possible values for errors are ’strict’ (raise an exception in case of an encoding error), ’replace’ (replace malformed data with a suitable replacement marker, such as ?) and ’ignore’ (ignore malformed data and continue without further notice).

In case a search function cannot find a given encoding, it should return None.

lookup(encoding)#

Looks up a codec tuple in the Python codec registry and returns the function tuple as defined above.

Encodings are first looked up in the registry’s cache. If not found, the list of registered search functions is scanned. If no codecs tuple is found, a LookupError is raised. Otherwise, the codecs tuple is stored in the cache and returned to the caller.

To simplify working with encoded files or stream, the module also defines these utility functions:

open(filename, mode)#

Open an encoded file using the given mode and return a wrapped version providing transparent encoding/decoding.

Note: The wrapped version will only accept the object format defined by the codecs, i.e. Unicode objects for most built-in codecs. Output is also codec-dependent and will usually be Unicode as well.

encoding specifies the encoding which is to be used for the the file.

errors may be given to define the error handling. It defaults to ’strict’ which causes a ValueError to be raised in case an encoding error occurs.

buffering has the same meaning as for the built-in open() function. It defaults to line buffered.

EncodedFile(file, input)#

Return a wrapped version of file which provides transparent encoding translation.

Strings written to the wrapped file are interpreted according to the given input encoding and then written to the original file as strings using the output encoding. The intermediate encoding will usually be Unicode but depends on the specified codecs.

If output is not given, it defaults to input.

errors may be given to define the error handling. It defaults to ’strict’, which causes ValueError to be raised in case an encoding error occurs.

…XXX document codec base classes…

The module also provides the following constants which are useful for reading and writing to platform dependent files:

BOM#

These constants define the byte order marks (BOM) used in data streams to indicate the byte order used in the stream or file. is either or depending on the platform’s native byte order, while the others represent big endian (_BE suffix) and little endian (_LE suffix) byte order using 32-bit and 64-bit encodings.

codeop — Compile Python code#

Compile (possibly incomplete) Python code.

The codeop module provides a function to compile Python code with hints on whether it is certainly complete, possibly complete or definitely incomplete. This is used by the code module and should not normally be used directly.

The codeop module defines the following function:

compile_command(source)#

Tries to compile source, which should be a string of Python code and return a code object if source is valid Python code. In that case, the filename attribute of the code object will be filename, which defaults to ’<input>’. Returns None if source is not valid Python code, but is a prefix of valid Python code.

If there is a problem with source, an exception will be raised. SyntaxError is raised if there is invalid Python syntax, and OverflowError if there is an invalid numeric constant.

The symbol argument determines whether source is compiled as a statement (’single’, the default) or as an expression (’eval’). Any other value will cause ValueError to be raised.

Caveat: It is possible (but not likely) that the parser stops parsing with a successful outcome before reaching the end of the source; in this case, trailing symbols may be ignored instead of causing an error. For example, a backslash followed by two newlines may be followed by arbitrary garbage. This will be fixed once the API for the parser is better.

colorsys — Conversions between color systems#

Conversion functions between RGB and other color systems.

The colorsys module defines bidirectional conversions of color values between colors expressed in the RGB (Red Green Blue) color space used in computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness Saturation) and HSV (Hue Saturation Value). Coordinates in all of these color spaces are floating point values. In the YIQ space, the Y coordinate is between 0 and 1, but the I and Q coordinates can be positive or negative. In all other spaces, the coordinates are all between 0 and 1.

More information about color spaces can be found at http://www.inforamp.net/%7epoynton/ColorFAQ.html.

The colorsys module defines the following functions:

rgb_to_yiq(r, g, b)#

Convert the color from RGB coordinates to YIQ coordinates.

yiq_to_rgb(y, i, q)#

Convert the color from YIQ coordinates to RGB coordinates.

rgb_to_hls(r, g, b)#

Convert the color from RGB coordinates to HLS coordinates.

hls_to_rgb(h, l, s)#

Convert the color from HLS coordinates to RGB coordinates.

rgb_to_hsv(r, g, b)#

Convert the color from RGB coordinates to HSV coordinates.

hsv_to_rgb(h, s, v)#

Convert the color from HSV coordinates to RGB coordinates.

Example:

>>> import colorsys
>>> colorsys.rgb_to_hsv(.3, .4, .2)
(0.25, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4)
(0.3, 0.4, 0.2)

commands — Utilities for running commands#

Utility functions for running external commands.

The commands module contains wrapper functions for os.popen() which take a system command as a string and return any output generated by the command and, optionally, the exit status.

The commands module defines the following functions:

getstatusoutput(cmd)#

Execute the string cmd in a shell with os.popen() and return a 2-tuple (status, output). cmd is actually run as { cmd ; } 2>&1, so that the returned output will contain output or error messages. A trailing newline is stripped from the output. The exit status for the command can be interpreted according to the rules for the C function .

getoutput(cmd)#

Like getstatusoutput(), except the exit status is ignored and the return value is a string containing the command’s output.

getstatus(file)#

Return the output of ls -ld file as a string. This function uses the getoutput() function, and properly escapes backslashes and dollar signs in the argument.

Example:

>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'

compileall — Byte-compile Python libraries#

Tools for byte-compiling all Python source files in a directory tree.

This module provides some utility functions to support installing Python libraries. These functions compile Python source files in a directory tree, allowing users without permission to write to the libraries to take advantage of cached byte-code files.

The source file for this module may also be used as a script to compile Python sources in directories named on the command line or in sys.path.

compile_dir(dir)#

Recursively descend the directory tree named by dir, compiling all .py files along the way. The maxlevels parameter is used to limit the depth of the recursion; it defaults to 10. If ddir is given, it is used as the base path from which the filenames used in error messages will be generated. If force is true, modules are re-compiled even if the timestamps are up to date.

compile_path()#

Byte-compile all the .py files found along sys.path. If skip_curdir is true (the default), the current directory is not included in the search. The maxlevels and force parameters default to 0 and are passed to the compile_dir() function.

See also:#

pycompile — py_compileByte-compile a single source file.

Cookie — HTTP state management#

Support for HTTP state management (cookies).

The Cookie module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simplistic string-only cookies, and provides an abstraction for having any serializable data-type as cookie value.

The module formerly strictly applied the parsing rules described in in the RFC 2109 and RFC 2068 specifications. It has since been discovered that MSIE 3.0x doesn’t follow the character rules outlined in those specs. As a result, the parsing rules used are a bit less strict.

exception CookieError#

Exception failing because of RFC 2109 invalidity: incorrect attributes, incorrect Set-Cookie header, etc.

class BaseCookie()#

This class is a dictionary-like object whose keys are strings and whose values are Morsel s. Note that upon setting a key to a value, the value is first converted to a Morsel containing the key and the value.

If input is given, it is passed to the load method.

class SimpleCookie()#

This class derives from BaseCookie and overrides value_decode and value_encode to be the identity and str() respectively.

class SerialCookie()#

This class derives from BaseCookie and overrides value_decode and value_encode to be the pickle.loads() and pickle.dumps.

Do not use this class. Reading pickled values from a cookie is a security hole, as arbitrary client-code can be run on pickle.loads(). It is supported for backwards compatibility.

class SmartCookie()#

This class derives from BaseCookie. It overrides value_decode to be pickle.loads() if it is a valid pickle, and otherwise the value itself. It overrides value_encode to be pickle.dumps() unless it is a string, in which case it returns the value itself.

The same security warning from SerialCookie applies here.

See also:#

Cookie Objects#

value_decode(val)#

Return a decoded value from a string representation. Return value can be any type. This method does nothing in BaseCookie — it exists so it can be overridden.

value_encode(val)#

Return an encoded value. val can be any type, but return value must be a string. This method does nothing in BaseCookie — it exists so it can be overridden

In general, it should be the case that value_encode and value_decode are inverses on the range of value_decode. .

output()#

Return a string representation suitable to be sent as HTTP headers. attrs and header are sent to each Morsel’s output method. sep is used to join the headers together, and is by default a newline.

js_output()#

Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP headers was sent.

The meaning for attrs is the same as in output().

load(rawdata)#

If rawdata is a string, parse it as an HTTP_COOKIE and add the values found there as Morsel s. If it is a dictionary, it is equivalent to:

for k, v in rawdata.items():
    cookie[k] = v

Morsel Objects#

class Morsel()#

Abstract a key/value pair, which has some RFC 2109 attributes.

Morsels are dictionary-like objects, whose set of keys is constant — the valid RFC 2109 attributes, which are

• expires

• path

• comment

• domain

• max-age

• secure

• version

The keys are case-insensitive.

value#

The value of the cookie.

coded_value#

The encoded value of the cookie — this is what should be sent.

key#

The name of the cookie.

set(key, value, coded_value)#

Set the key, value and coded_value members.

isReservedKey(K)#

Whether K is a member of the set of keys of a Morsel.

output()#

Return a string representation of the Morsel, suitable to be sent as an HTTP header. By default, all the attributes are included, unless attrs is given, in which case it should be a list of attributes to use. header is by default "Set-Cookie:".

js_output()#

Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP header was sent.

The meaning for attrs is the same as in output(). .

OutputString()#

Return a string representing the Morsel, without any surrounding HTTP or JavaScript.

The meaning for attrs is the same as in output().

Example#

The following example demonstrates how to open a can of spam using the spam module.

>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C = Cookie.SerialCookie()
>>> C = Cookie.SmartCookie()
>>> C = Cookie.Cookie() # backwards compatible alias for SmartCookie
>>> C = Cookie.SmartCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> C # generate HTTP headers
Set-Cookie: sugar=wafer;
Set-Cookie: fig=newton;
>>> C = Cookie.SmartCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print C.output(header="Cookie:")
Cookie: rocky=road; Path=/cookie;
>>> print C.output(attrs=[], header="Cookie:")
Cookie: rocky=road;
>>> C = Cookie.SmartCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> C
Set-Cookie: vienna=finger;
Set-Cookie: chips=ahoy;
>>> C = Cookie.SmartCookie()
>>> C.load('keebler="E=everybody; L=\"Loves\"; fudge=\012;";')
>>> C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
>>> C = Cookie.SmartCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> C
Set-Cookie: oreo="doublestuff"; Path=/;
>>> C = Cookie.SmartCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = Cookie.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> C
Set-Cookie: number=7;
Set-Cookie: string=seven;
>>> C = Cookie.SerialCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> C
Set-Cookie: number="I7\012.";
Set-Cookie: string="S'seven'\012p1\012.";
>>> C = Cookie.SmartCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> C
Set-Cookie: number="I7\012.";
Set-Cookie: string=seven;

copy — Shallow and deep copy operations#

Shallow and deep copy operations.

This module provides generic (shallow and deep) copying operations.

Interface summary:

import copy

x = copy.copy(y)        # make a shallow copy of y
x = copy.deepcopy(y)    # make a deep copy of y

For module specific errors, copy.error is raised.

The difference between shallow and deep copying is only relevant for compound objects (objects that contain other objects, like lists or class instances):

• A shallow copy constructs a new compound object and then (to the extent possible) inserts references into it to the objects found in the original.

• A deep copy constructs a new compound object and then, recursively, inserts copies into it of the objects found in the original.

Two problems often exist with deep copy operations that don’t exist with shallow copy operations:

• Recursive objects (compound objects that, directly or indirectly, contain a reference to themselves) may cause a recursive loop.

• Because deep copy copies everything it may copy too much, e.g., administrative data structures that should be shared even between copies.

The deepcopy() function avoids these problems by:

• keeping a “memo” dictionary of objects already copied during the current copying pass; and

• letting user-defined classes override the copying operation or the set of components copied.

This version does not copy types like module, class, function, method, stack trace, stack frame, file, socket, window, array, or any similar types.

Classes can use the same interfaces to control copying that they use to control pickling: they can define methods called __getinitargs__(), __getstate__() and __setstate__(). See the description of module pickle for information on these methods. The copy module does not use the copy_reg registration module.

In order for a class to define its own copy implementation, it can define special methods __copy__() and __deepcopy__(). The former is called to implement the shallow copy operation; no additional arguments are passed. The latter is called to implement the deep copy operation; it is passed one argument, the memo dictionary. If the __deepcopy__() implementation needs to make a deep copy of a component, it should call the deepcopy() function with the component as first argument and the memo dictionary as second argument.

See also:#

— pickleDiscussion of the special disciplines used to support object state retrieval and restoration.

copy_reg — Register pickle support functions#

Register pickle support functions.

The copy_reg module provides support for the pickle and cPickle modules. The copy module is likely to use this in the future as well. It provides configuration information about object constructors which are not classes. Such constructors may be factory functions or class instances.

constructor(object)#

Declares object to be a valid constructor.

pickle(type, function)#

Declares that function should be used as a “reduction” function for objects of type or class type. function should return either a string or a tuple. The optional constructor parameter, if provided, is a callable object which can be used to reconstruct the object when called with the tuple of arguments returned by function at pickling time.

crypt — Function to check Unix passwords#

The function used to check Unix passwords.

This module implements an interface to the routine, which is a one-way hash function based upon a modified DES algorithm; see the Unix man page for further details. Possible uses include allowing Python scripts to accept typed passwords from the user, or attempting to crack Unix passwords with a dictionary.

crypt(word, salt)#

word will usually be a user’s password as typed at a prompt or in a graphical interface. salt is usually a random two-character string which will be used to perturb the DES algorithm in one of 4096 ways. The characters in salt must be in the set [./a-zA-Z0-9]. Returns the hashed password as a string, which will be composed of characters from the same alphabet as the salt (the first two characters represent the salt itself).

A simple example illustrating typical use:

import crypt, getpass, pwd

def login():
    username = raw_input('Python login:')
    cryptedpasswd = pwd.getpwnam(username)[1]
    if cryptedpasswd:
        if cryptedpasswd == 'x' or cryptedpasswd == '*': 
            raise "Sorry, currently no support for shadow passwords"
        cleartext = getpass.getpass()
        return crypt.crypt(cleartext, cryptedpasswd[:2]) == cryptedpasswd
    else:
        return 1

Cryptographic Services#

The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the installation. Here’s an overview:

Hardcore cypherpunks will probably find the cryptographic modules written by Andrew Kuchling of further interest; the package adds built-in modules for DES and IDEA encryption, provides a Python module for reading and decrypting PGP files, and then some. These modules are not distributed with Python but available separately. See the URL http://starship.python.net/crew/amk/python/code/crypto.html or send email to amk1@bigfoot.com for more information.

curses — Screen painting and input handling for character-cell terminals#

An interface to the curses library. New in version 1.6.

The curses module provides an interface to the curses library, the de-facto standard for portable advanced terminal handling.

While curses is most widely used in the Unix environment, versions are available for DOS, OS/2, and possibly other systems as well. This extension module is designed to match the API of ncurses, an open-source curses library hosted on Linux and the BSD variants of Unix.

See also:#

— curses.asciiUtilities for working with ASCII characters, regardless of your locale settings. — curses.textpadEditable text widget for curses supporting Emacs-like bindings. — curses.wrapperConvenience function to ensure proper terminal setup and resetting on application entry and exit. Curses Programming with Python

Functions#

The module curses defines the following exception:

exception error#

Exception raised when a curses library function returns an error.

Note: Whenever x or y arguments to a function or a method are optional, they default to the current cursor location. Whenever attr is optional, it defaults to .

The module curses defines the following functions:

baudrate()#

Returns the output speed of the terminal in bits per second. On software terminal emulators it will have a fixed high value. Included for historical reasons; in former times, it was used to write output loops for time delays and occasionally to change interfaces depending on the line speed.

beep()#

Emit a short attention sound.

can_change_color()#

Returns true or false, depending on whether the programmer can change the colors displayed by the terminal.

cbreak()#

Enter cbreak mode. In cbreak mode (sometimes called “rare” mode) normal tty line buffering is turned off and characters are available to be read one by one. However, unlike raw mode, special characters (interrupt, quit, suspend, and flow control) retain their effects on the tty driver and calling program. Calling first raw() then cbreak() leaves the terminal in cbreak mode.

color_content(color_number)#

Returns the intensity of the red, green, and blue (RGB) components in the color color_number, which must be between 0 and COLORS. A 3-tuple is returned, containing the R,G,B values for the given color, which will be between 0 (no component) and 1000 (maximum amount of component).

color_pair(color_number)#

Returns the attribute value for displaying text in the specified color. This attribute value can be combined with , , and the other attributes. pair_number() is the counterpart to this function.

curs_set(visibility)#

Sets the cursor state. visibility can be set to 0, 1, or 2, for invisible, normal, or very visible. If the terminal supports the visibility requested, the previous cursor state is returned; otherwise, an exception is raised. On many terminals, the “visible” mode is an underline cursor and the “very visible” mode is a block cursor.

def_prog_mode()#

Saves the current terminal mode as the “program” mode, the mode when the running program is using curses. (Its counterpart is the “shell” mode, for when the program is not in curses.) Subsequent calls to reset_prog_mode() will restore this mode.

def_shell_mode()#

Saves the current terminal mode as the “shell” mode, the mode when the running program is not using curses. (Its counterpart is the “program” mode, when the program is using curses capabilities.) Subsequent calls to reset_shell_mode() will restore this mode.

delay_output(ms)#

Inserts an ms millisecond pause in output.

doupdate()#

Update the physical screen. The curses library keeps two data structures, one representing the current physical screen contents and a virtual screen representing the desired next state. The doupdate() ground updates the physical screen to match the virtual screen.

The virtual screen may be updated by a noutrefresh() call after write operations such as addstr() have been performed on a window. The normal refresh() call is simply noutrefresh() followed by doupdate(); if you have to update multiple windows, you can speed performance and perhaps reduce screen flicker by issuing noutrefresh() calls on all windows, followed by a single doupdate().

echo()#

Enter echo mode. In echo mode, each character input is echoed to the screen as it is entered.

endwin()#

De-initialize the library, and return terminal to normal status.

erasechar()#

Returns the user’s current erase character. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

filter()#

The filter() routine, if used, must be called before initscr() is called. The effect is that, during those calls, LINES is set to 1; the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. The effect is that the cursor is confined to the current line, and so are screen updates. This may be used for enabling cgaracter-at-a-time line editing without touching the rest of the screen.

flash()#

Flash the screen. That is, change it to reverse-video and then change it back in a short interval. Some people prefer such as ‘visible bell’ to the audible attention signal produced by beep().

flushinp()#

Flush all input buffers. This throws away any typeahead that has been typed by the user and has not yet been processed by the program.

getmouse()#

After getch() returns to signal a mouse event, this method should be call to retrieve the queued mouse event, represented as a 5-tuple (id, x, y, z, bstate). id is an ID value used to distinguish multiple devices, and x, y, z are the event’s coordinates. (z is currently unused.). bstate is an integer value whose bits will be set to indicate the type of event, and will be the bitwise OR of one or more of the following constants, where n is the button number from 1 to 4: , , , , , , , .

getsyx()#

Returns the current coordinates of the virtual screen cursor in y and x. If leaveok is currently true, then -1,-1 is returned.

getwin(file)#

Reads window related data stored in the file by an earlier putwin() call. The routine then creates and initializes a new window using that data, returning the new window object.

has_colors()#

Returns true if the terminal can display colors; otherwise, it returns false.

has_ic()#

Returns true if the terminal has insert- and delete- character capabilities. This function is included for historical reasons only, as all modern software terminal emulators have such capabilities.

has_il()#

Returns true if the terminal has insert- and delete-line capabilities, or can simulate them using scrolling regions. This function is included for historical reasons only, as all modern software terminal emulators have such capabilities.

has_key(ch)#

Takes a key value ch, and returns true if the current terminal type recognizes a key with that value.

halfdelay(tenths)#

Used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after blocking for tenths tenths of seconds, an exception is raised if nothing has been typed. The value of tenths must be a number between 1 and 255. Use nocbreak() to leave half-delay mode.

init_color(color_number, r, g, b)#

Changes the definition of a color, taking the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of color_number must be between 0 and COLORS. Each of r, g, b, must be a value between 0 and 1000. When init_color() is used, all occurrences of that color on the screen immediately change to the new definition. This function is a no-op on most terminals; it is active only if can_change_color() returns 1.

init_pair(pair_number, fg, bg)#

Changes the definition of a color-pair. It takes three arguments: the number of the color-pair to be changed, the foreground color number, and the background color number. The value of pair_number must be between 1 and COLOR_PAIRS-1 (the 0 color pair is wired to white on black and cannot be changed). The value of fg and bg arguments must be between 0 and COLORS. If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition.

initscr()#

Initialize the library. Returns a WindowObject which represents the whole screen.

isendwin()#

Returns true if endwin() has been called (that is, the curses library has been deinitialized).

keyname(k)#

Return the name of the key numbered k. The name of a key generating printable ASCII character is the key’s character. The name of a control-key combination is a two-character string consisting of a caret followed by the corresponding printable ASCII character. The name of an alt-key combination (128-255) is a string consisting of the prefix ‘M-’ followed by the name of the corresponding ASCII character.

killchar()#

Returns the user’s current line kill character. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

longname()#

Returns a string containing the terminfo long name field describing the current terminal. The maximum length of a verbose description is 128 characters. It is defined only after the call to initscr().

meta(yes)#

If yes is 1, allow 8-bit characters to be input. If yes is 0, allow only 7-bit chars.

mouseinterval(interval)#

Sets the maximum time in milliseconds that can elapse between press and release events in order for them to be recognized as a click, and returns the previous interval value. The default value is 200 msec, or one fifth of a second.

mousemask(mousemask)#

Sets the mouse events to be reported, and returns a tuple (availmask, oldmask). availmask indicates which of the specified mouse events can be reported; on complete failure it returns 0. oldmask is the previous value of the given window’s mouse event mask. If this function is never called, no mouse events are ever reported.

newpad(nlines, ncols)#

Creates and returns a pointer to a new pad data structure with the given number of lines and columns. A pad is returned as a window object.

A pad is like a window, except that it is not restricted by the screen size, and is not necessarily associated with a particular part of the screen. Pads can be used when a large window is needed, and only a part of the window will be on the screen at one time. Automatic refreshes of pads (e.g., from scrolling or echoing of input) do not occur. The refresh() and noutrefresh() methods of a pad require 6 arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. The arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p arguments refer to the upper left corner of the the pad region to be displayed and the s arguments define a clipping box on the screen within which the pad region is to be displayed.

newwin( begin_y, begin_x)#

Return a new window, whose left-upper corner is at (begin_y, begin_x), and whose height/width is nlines/ncols.

By default, the window will extend from the specified position to the lower right corner of the screen.

nl()#

Enter newline mode. This mode translates the return key into newline on input, and translates newline into return and line-feed on output. Newline mode is initially on.

nocbreak()#

Leave cbreak mode. Return to normal “cooked” mode with line buffering.

noecho()#

Leave echo mode. Echoing of input characters is turned off,

nonl()#

Leave newline mode. Disable translation of return into newline on input, and disable low-level translation of newline into newline/return on output (but this does not change the behavior of addch(’n’), which always does the equivalent of return and line feed on the virtual screen). With translation off, curses can sometimes speed up vertical motion a little; also, it will be able to detect the return key on input.

noqiflush()#

When the noqiflush routine is used, normal flush of input and output queues associated with the INTR, QUIT and SUSP characters will not be done. You may want to call noqiflush() in a signal handler if you want output to continue as though the interrupt had not occurred, after the handler exits.

noraw()#

Leave raw mode. Return to normal “cooked” mode with line buffering.

pair_content(pair_number)#

Returns a tuple (fg,bg) containing the colors for the requested color pair. The value of pair_number must be between 0 and COLOR_PAIRS-1.

pair_number(attr)#

Returns the number of the color-pair set by the attribute value attr. color_pair() is the counterpart to this function.

putp(string)#

Equivalent to tputs(str, 1, putchar); emits the value of a specified terminfo capability for the current terminal. Note that the output of putp always goes to standard output.

qiflush( )#

If flag is false, the effect is the same as calling noqiflush(). If flag is true, or no argument is provided, the queues will be flushed when these control characters are read.

raw()#

Enter raw mode. In raw mode, normal line buffering and processing of interrupt, quit, suspend, and flow control keys are turned off; characters are presented to curses input functions one by one.

reset_prog_mode()#

Restores the terminal to “program” mode, as previously saved by def_prog_mode().

reset_shell_mode()#

Restores the terminal to “shell” mode, as previously saved by def_shell_mode().

setsyx(y, x)#

Sets the virtual screen cursor to y, x. If y and x are both -1, then leaveok is set.

start_color()#

Must be called if the programmer wants to use colors, and before any other color manipulation routine is called. It is good practice to call this routine right after initscr().

start_color() initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global variables in the curses module, COLORS and COLOR_PAIRS, containing the maximum number of colors and color-pairs the terminal can support. It also restores the colors on the terminal to the values they had when the terminal was just turned on.

termattrs()#

Returns a logical OR of all video attributes supported by the terminal. This information is useful when a curses program needs complete control over the appearance of the screen.

termname()#

Returns the value of the environment variable TERM, truncated to 14 characters.

tigetflag(capname)#

Returns the value of the Boolean capability corresponding to the terminfo capability name capname. The value -1 is returned if capname is not a Boolean capability, or 0 if it is canceled or absent from the terminal description.

tigetnum(capname)#

Returns the value of the numeric capability corresponding to the terminfo capability name capname. The value -2 is returned if capname is not a numeric capability, or -1 if it is canceled or absent from the terminal description.

tigetstr(capname)#

Returns the value of the string capability corresponding to the terminfo capability name capname. None is returned if capname is not a string capability, or is canceled or absent from the terminal description.

typeahead(fd)#

Specifies that the file descriptor fd be used for typeahead checking. If fd is -1, then no typeahead checking is done.

The curses library does “line-breakout optimization” by looking for typeahead periodically while updating the screen. If input is found, and it is coming from a tty, the current update is postponed until refresh or doupdate is called again, allowing faster response to commands typed in advance. This function allows specifying a different file descriptor for typeahead checking.

unctrl(ch)#

Returns a string which is a printable representation of the character ch. Control characters are displayed as a caret followed by the character, for example as ^C. Printing characters are left as they are.

ungetch(ch)#

Push ch so the next getch() will return it. Note: only one ch can be pushed before getch() is called.

ungetmouse(id, x, y, z, bstate)#

Push a event onto the input queue, associating the given state data with it.

use_env(flag)#

If used, this function should be called before initscr or newterm are called. When flag is false, the values of lines and columns specified in the terminfo database will be used, even if environment variables LINES and COLUMNS (used by default) are set, or if curses is running in a window (in which case default behavior would be to use the window size if LINES and COLUMNS are not set).

Window Objects#

Window objects, as returned by initscr() and newwin() above, have the following methods:

addch( ch)#

Note: A character means a C character (i.e., an ASCII code), rather then a Python character (a string of length 1). (This note is true whenever the documentation mentions a character.) The builtin ord() is handy for conveying strings to codes.

Paint character ch at (y, x) with attributes attr, overwriting any character previously painter at that location. By default, the character position and attributes are the current settings for the window object.

addnstr( str, n)#

Paint at most n characters of the string str at (y, x) with attributes attr, overwriting anything previously on the display.

addstr( str)#

Paint the string str at (y, x) with attributes attr, overwriting anything previously on the display.

attroff(attr)#

Remove attribute attr from the “background” set applied to all writes to the current window.

attron(attr)#

Add attribute attr from the “background” set applied to all writes to the current window.

attrset(attr)#

Set the “background” set of attributes to attr. This set is initially 0 (no attributes).

bkgd(ch)#

Sets the background property of the window to the character ch, with attributes attr. The change is then applied to every character position in that window:

• The attribute of every character in the window is changed to the new background attribute.

• Wherever the former background character appears, it is changed to the new background character.

bkgdset(ch)#

Sets the window’s background. A window’s background consists of a character and any combination of attributes. The attribute part of the background is combined (OR’ed) with all non-blank characters that are written into the window. Both the character and attribute parts of the background are combined with the blank characters. The background becomes a property of the character and moves with the character through any scrolling and insert/delete line/character operations.

border()#

Draw a border around the edges of the window. Each parameter specifies the character to use for a specific part of the border; see the table below for more details. The characters must be specified as integers; using one-character strings will cause TypeError to be raised.

Note: A 0 value for any parameter will cause the default character to be used for that parameter. Keyword parameters can not be used. The defaults are listed in this table:

box()#

Similar to border(), but both ls and rs are vertch and both ts and bs are horch. The default corner characters are always used by this function.

clear()#

Like erase(), but also causes the whole window to be repainted upon next call to refresh().

clearok(yes)#

If yes is 1, the next call to refresh() will clear the window completely.

clrtobot()#

Erase from cursor to the end of the window: all lines below the cursor are deleted, and then the equivalent of clrtoeol() is performed.

clrtoeol()#

Erase from cursor to the end of the line.

cursyncup()#

Updates the current cursor position of all the ancestors of the window to reflect the current cursor position of the window.

delch()#

Delete any character at (y, x).

deleteln()#

Delete the line under the cursor. All following lines are moved up by 1 line.

derwin( begin_y, begin_y)#

An abbreviation for “derive window”, derwin() is the same as calling subwin(), except that begin_y and begin_x are relative to the origin of the window, rather than relative to the entire screen. Returns a window object for the derived window.

echochar(ch)#

Add character ch with attribute attr, and immediately call refresh on the window.

enclose(y, x)#

Tests whether the given pair of screen-relative character-cell coordinates are enclosed by the given window, returning true or false. It is useful for determining what subset of the screen windows enclose the location of a mouse event.

erase()#

Clear the window.

getbegyx()#

Return a tuple (y, x) of co-ordinates of upper-left corner.

getch()#

Get a character. Note that the integer returned does not have to be in ASCII range: function keys, keypad keys and so on return numbers higher then 256. In no-delay mode, an exception is raised if there is no input.

getkey()#

Get a character, returning a string instead of an integer, as getch() does. Function keys, keypad keys and so on return a multibyte string containing the key name. In no-delay mode, an exception is raised if there is no input.

getmaxyx()#

Return a tuple (y, x) of the height and width of the window.

getparyx()#

Returns the beginning coordinates of this window relative to its parent window into two integer variables y and x. Returns -1,-1 if this window has no parent.

getstr()#

Read a string from the user, with primitive line editing capacity.

getyx()#

Return a tuple (y, x) of current cursor position relative to the window’s upper-left corner.

hline( ch, n)#

Display a horizontal line starting at (y, x) with length n consisting of the character ch.

idcok(flag)#

If flag is false, curses no longer considers using the hardware insert/delete character feature of the terminal; if flag is true, use of character insertion and deletion is enabled. When curses is first initialized, use of character insert/delete is enabled by default.

idlok(yes)#

If called with yes equal to 1, curses will try and use hardware line editing facilities. Otherwise, line insertion/deletion are disabled.

immedok(flag)#

If flag is true, any change in the window image automatically causes the window to be refreshed; you no longer have to call refresh() yourself. However, it may degrade performance considerably, due to repeated calls to wrefresh. This option is disabled by default.

inch()#

Return the character at the given position in the window. The bottom 8 bits are the character proper, and upper bits are the attributes.

insch( ch)#

Paint character ch at (y, x) with attributes attr, moving the line from position x right by one character.

insdelln(nlines)#

Inserts nlines lines into the specified window above the current line. The nlines bottom lines are lost. For negative nlines, delete nlines lines starting with the one under the cursor, and move the remaining lines up. The bottom nlines lines are cleared. The current cursor position remains the same.

insertln()#

Insert a blank line under the cursor. All following lines are moved down by 1 line.

insnstr( str, n )#

Insert a character string (as many characters as will fit on the line) before the character under the cursor, up to n characters. If n is zero or negative, the entire string is inserted. All characters to the right of the cursor are shifted right, with the the rightmost characters on the line being lost. The cursor position does not change (after moving to y, x, if specified).

insstr( str )#

Insert a character string (as many characters as will fit on the line) before the character under the cursor. All characters to the right of the cursor are shifted right, with the the rightmost characters on the line being lost. The cursor position does not change (after moving to y, x, if specified).

instr( )#

Returns a string of characters, extracted from the window starting at the current cursor position, or at y, x if specified. Attributes are stripped from the characters. If n is specified, instr() returns return a string at most n characters long (exclusive of the trailing NUL).

is_linetouched(line)#

Returns true if the specified line was modified since the last call to refresh(); otherwise returns false. Raises a curses.error exception if line is not valid for the given window.

is_wintouched()#

Returns true if the specified window was modified since the last call to refresh(); otherwise returns false.

keypad(yes)#

If yes is 1, escape sequences generated by some keys (keypad, function keys) will be interpreted by curses. If yes is 0, escape sequences will be left as is in the input stream.

leaveok(yes)#

If yes is 1, cursor is left where it is on update, instead of being at “cursor position.” This reduces cursor movement where possible. If possible the cursor will be made invisible.

If yes is 0, cursor will always be at “cursor position” after an update.

move(new_y, new_x)#

Move cursor to (new_y, new_x).

mvderwin(y, x)#

Moves the window inside its parent window. The screen-relative parameters of the window are not changed. This routine is used to display different parts of the parent window at the same physical position on the screen.

mvwin(new_y, new_x)#

Move the window so its upper-left corner is at (new_y, new_x).

nodelay(yes)#

If yes is 1, getch() will be non-blocking.

notimeout(yes)#

If yes is 1, escape sequences will not be timed out.

If yes is 0, after a few milliseconds, an escape sequence will not be interpreted, and will be left in the input stream as is.

noutrefresh()#

Mark for refresh but wait. This function updates the data structure representing the desired state of the window, but does not force an update of the physical screen.

putwin(file)#

Writes all data associated with the window into the provided file object. This information can be later retrieved using the getwin() function.

redrawln(beg, num)#

Indicates that the num screen lines, starting at line beg, are corrupted and should be completely redrawn on the next refresh() call.

redrawwin()#

Touches the entire window, causing it to be completely redrawn on the next refresh() call.

refresh( )#

Update the display immediately (sync actual screen with previous drawing/deleting methods).

The 6 optional arguments can only be specified when the window is a pad created with newpad(). The additional parameters are needed to indicate what part of the pad and screen are involved. pminrow and pmincol specify the upper left-hand corner of the rectangle to be displayed in the pad. sminrow, smincol, smaxrow, and smaxcol specify the edges of the rectangle to be displayed on the screen. The lower right-hand corner of the rectangle to be displayed in the pad is calculated from the screen coordinates, since the rectangles must be the same size. Both rectangles must be entirely contained within their respective structures. Negative values of pminrow, pmincol, sminrow, or smincol are treated as if they were zero.

scroll()#

Scroll the screen upward by lines lines.

scrollok(flag)#

Controls what happens when the cursor of a window is moved off the edge of the window or scrolling region, either as a result of a newline action on the bottom line, or typing the last character of the last line. If flag is false, the cursor is left on the bottom line. If flag is true, the window is scrolled up one line. Note that in order to get the physical scrolling effect on the terminal, it is also necessary to call idlok().

setscrreg(top, bottom)#

Set the scrolling region from line top to line bottom. All scrolling actions will take place in this region.

standend()#

Turn off the standout attribute. On some terminals this has the side effect of turning off all attributes.

standout()#

Turn on attribute A_STANDOUT.

subpad( begin_y, begin_y)#

Return a sub-window, whose upper-left corner is at (begin_y, begin_x), and whose width/height is ncols/nlines.

subwin( begin_y, begin_y)#

Return a sub-window, whose upper-left corner is at (begin_y, begin_x), and whose width/height is ncols/nlines.

By default, the sub-window will extend from the specified position to the lower right corner of the window.

syncdown()#

Touches each location in the window that has been touched in any of its ancestor windows. This routine is called by refresh(), so it should almost never be necessary to call it manually.

syncok(flag)#

If called with flag set to true, then syncup() is called automatically whenever there is a change in the window.

syncup()#

Touches all locations in ancestors of the window that have been changed in the window.

timeout(delay)#

Sets blocking or non-blocking read behavior for the window. If delay is negative, blocking read is used, which will wait indefinitely for input). If delay is zero, then non-blocking read is used, and -1 will be returned by getch() if no input is waiting. If delay is positive, then getch() will block for delay milliseconds, and return -1 if there is still no input at the end of that time.

touchline(start, count)#

Pretend count lines have been changed, starting with line start.

touchwin()#

Pretend the whole window has been changed, for purposes of drawing optimizations.

untouchwin()#

Marks all lines in the window as unchanged since the last call to refresh().

vline( ch, n)#

Display a vertical line starting at (y, x) with length n consisting of the character ch.

Constants#

The curses module defines the following data members:

version#

A string representing the current version of the module. Also available as .

Several constants are available to specify character cell attributes:

Keys are referred to by integer constants with names starting with KEY_. The exact keycaps available are system dependent.

On VT100s and their software emulations, such as X terminal emulators, there are normally at least four function keys (, , , ) available, and the arrow keys mapped to , , and in the obvious way. If your machine has a PC keybboard, it is safe to expect arrow keys and twelve function keys (older PC keyboards may have only ten function keys); also, the following keypad mappings are standard:

The following table lists characters from the alternate character set. These are inherited from the VT100 terminal, and will generally be available on software emulations such as X terminals. When there is no graphic available, curses falls back on a crude printable ASCII approximation. Note: These are available only after initscr() has been called.

The following table lists the predefined colors:

curses.textpad — Text input widget for curses programs#

Emacs-like input editing in a curses window. New in version 1.6.

The curses.textpad module provides a Textbox class that handles elementary text editing in a curses window, supporting a set of keybindings resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x, FrameMaker, and many other programs). The module also provides a rectangle-drawing function useful for framing text boxes or for other purposes.

The module curses.textpad defines the following function:

rectangle(win, uly, ulx, lry, lrx)#

Draw a rectangle. The first argument must be a window object; the remaining arguments are coordinates relative to that window. The second and third arguments are the y and x coordinates of the upper left hand corner of the rectangle To be drawn; the fourth and fifth arguments are the y and x coordinates of the lower right hand corner. The rectangle will be drawn using VT100/IBM PC forms characters on terminals that make this possible (including xterm and most other software terminal emulators). Otherwise it will be drawn with ASCII dashes, vertical bars, and plus signs.

Textbox objects#

You can instantiate a Textbox object as follows:

class Textbox(win)#

Return a textbox widget object. The win argument should be a curses WindowObject in which the textbox is to be contained. The edit cursor of the textbox is initially located at the upper left hand corner of the containin window, with coordinates (0, 0). The instance’s stripspaces flag is initially on.

Textbox objects have the following methods:

edit()#

This is the entry point you will normally use. It accepts editing keystrokes until one of the termination keystrokes is entered. If validator is supplied, it must be a function. It will be called for each keystroke entered with the keystroke as a parameter; command dispatch is done on the result. This method returns the window contents as a string; whether blanks in the window are included is affected by the stripspaces member.

do_command(ch)#

Process a single command keystroke. Here are the supported special keystrokes:

Move operations do nothing if the cursor is at an edge where the movement is not possible. The following synonyms are supported where possible:

All other keystrokes are treated as a command to insert the given character and move right (with line wrapping).

gather()#

This method returns the window contents as a string; whether blanks in the window are included is affected by the stripspaces member.

stripspaces#

This data member is a flag which controls the interpretation of blanks in the window. When it is on, trailing blanks on each line are ignored; any cursor motion that would land the cursor on a trailing blank goes to the end of that line instead, and trailing blanks are stripped when the window contents is gathered.

curses.wrapper — Terminal handler for curses programs#

Terminal configuration wrapper for curses programs. New in version 1.6.

This module supplies one function, wrapper(), which runs another function which should be the rest of your curses-using application. If the application raises an exception, wrapper() will restore the terminal to a sane state before passing it further up the stack and generating a traceback.

wrapper(func, )#

Wrapper function that initializes curses and calls another function, func, restoring normal keyboard/screen behavior on error. The callable object func is then passed the main window ’stdscr’ as its first argument, followed by any other arguments passed to wrapper().

Before calling the hook function, wrapper() turns on cbreak mode, turns off echo, enables the terminal keypad, and initializes colors if the terminal has color support. On exit (whether normally or by exception) it restores cooked mode, turns on echo, and disables the terminal keypad.

dbhash — DBM-style interface to the BSD database library#

DBM-style interface to the BSD database library.

The dbhash module provides a function to open databases using the BSD db library. This module mirrors the interface of the other Python database modules that provide access to DBM-style databases. The bsddb module is required to use dbhash.

This module provides an exception and a function:

exception error#

Exception raised on database errors other than KeyError. It is a synonym for bsddb.error.

open(path, flag)#

Open a db database and return the database object. The path argument is the name of the database file.

The flag argument can be ’r’ (the default), ’w’, ’c’ (which creates the database if it doesn’t exist), or ’n’ (which always creates a new empty database). For platforms on which the BSD db library supports locking, an l can be appended to indicate that locking should be used.

The optional mode parameter is used to indicate the Unix permission bits that should be set if a new database must be created; this will be masked by the current umask value for the process.

See also:#

— anydbmGeneric interface to dbm-style databases. — bsddbLower-level interface to the BSD db library. — whichdbUtility module used to determine the type of an existing database.

Database Objects#

The database objects returned by open() provide the methods common to all the DBM-style databases. The following methods are available in addition to the standard methods.

first()#

It’s possible to loop over every key in the database using this method and the next() method. The traversal is ordered by the databases internal hash values, and won’t be sorted by the key values. This method returns the starting key.

last()#

Return the last key in a database traversal. This may be used to begin a reverse-order traversal; see previous().

next(key)#

Returns the key that follows key in the traversal. The following code prints every key in the database db, without having to create a list in memory that contains them all:

k = db.first()
while k != None:
    print k
    k = db.next(k)

previous(key)#

Return the key that comes before key in a forward-traversal of the database. In conjunction with last(), this may be used to implement a reverse-order traversal.

sync()#

This method forces any unwritten data to be written to the disk.

dbm — Simple “database” interface#

The standard “database” interface, based on ndbm.

The dbm module provides an interface to the Unix (n) dbm library. Dbm objects behave like mappings (dictionaries), except that keys and values are always strings. Printing a dbm object doesn’t print the keys and values, and the items() and values() methods are not supported.

This module can be used with the “classic” ndbm interface, the BSD DB compatibility interface, or the GNU GDBM compatibility interface. On Unix, the configure script will attempt to locate the appropriate header file to simplify building this module.

The module defines the following:

exception error#

Raised on dbm-specific errors, such as I/O errors. KeyError is raised for general mapping errors like specifying an incorrect key.

library#

Name of the ndbm implementation library used.

open(filename)#

Open a dbm database and return a dbm object. The filename argument is the name of the database file (without the .dir or .pag extensions; note that the BSD DB implementation of the interface will append the extension .db and only create one file).

The optional flag argument must be one of these values:

The optional mode argument is the Unix mode of the file, used only when the database has to be created. It defaults to octal 0666.

See also:#

— anydbmGeneric interface to dbm-style databases. — gdbmSimilar interface to the GNU GDBM library. — whichdbUtility module used to determine the type of an existing database.

dircache — Cached directory listings#

Return directory listing, with cache mechanism.

The dircache module defines a function for reading directory listing using a cache, and cache invalidation using the mtime of the directory. Additionally, it defines a function to annotate directories by appending a slash.

The dircache module defines the following functions:

listdir(path)#

Return a directory listing of path, as gotten from os.listdir(). Note that unless path changes, further call to listdir() will not re-read the directory structure.

Note that the list returned should be regarded as read-only. (Perhaps a future version should change it to return a tuple?)

opendir(path)#

Same as listdir(). Defined for backwards compatibility.

annotate(head, list)#

Assume list is a list of paths relative to head, and append, in place, a / to each path which points to a directory.

>>> import dircache
>>> a=dircache.listdir('/')
>>> a=a[:] # Copy the return value so we can change 'a'
>>> a
['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
>>> dircache.annotate('/', a)
>>> a
['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
linuz']

dis — Disassembler.#

Disassembler.

The dis module supports the analysis of Python byte code by disassembling it. Since there is no Python assembler, this module defines the Python assembly language. The Python byte code which this module takes as an input is defined in the file Include/opcode.h and used by the compiler and the interpreter.

Example: Given the function myfunc:

def myfunc(alist):
    return len(alist)

the following command can be used to get the disassembly of myfunc():

>>> dis.dis(myfunc)
          0 SET_LINENO          1

          3 SET_LINENO          2
          6 LOAD_GLOBAL         0 (len)
          9 LOAD_FAST           0 (alist)
         12 CALL_FUNCTION       1
         15 RETURN_VALUE   
         16 LOAD_CONST          0 (None)
         19 RETURN_VALUE   

The dis module defines the following functions:

dis()#

Disassemble the bytesource object. bytesource can denote either a class, a method, a function, or a code object. For a class, it disassembles all methods. For a single code sequence, it prints one line per byte code instruction. If no object is provided, it disassembles the last traceback.

distb()#

Disassembles the top-of-stack function of a traceback, using the last traceback if none was passed. The instruction causing the exception is indicated.

disassemble(code)#

Disassembles a code object, indicating the last instruction if lasti was provided. The output is divided in the following columns:

1. the current instruction, indicated as -->,

2. a labelled instruction, indicated with >>,

3. the address of the instruction,

4. the operation code name,

5. operation parameters, and

6. interpretation of the parameters in parentheses.

The parameter interpretation recognizes local and global variable names, constant values, branch targets, and compare operators.

disco(code)#

A synonym for disassemble. It is more convenient to type, and kept for compatibility with earlier Python releases.

opname#

Sequence of a operation names, indexable using the byte code.

cmp_op#

Sequence of all compare operation names.

hasconst#

Sequence of byte codes that have a constant parameter.

hasname#

Sequence of byte codes that access a attribute by name.

hasjrel#

Sequence of byte codes that have a relative jump target.

hasjabs#

Sequence of byte codes that have an absolute jump target.

haslocal#

Sequence of byte codes that access a a local variable.

hascompare#

Sequence of byte codes of boolean operations.

Python Byte Code Instructions#

The Python compiler currently generates the following byte code instructions.

STOP_CODE #

Indicates end-of-code to the compiler, not used by the interpreter.

POP_TOP #

Removes the top-of-stack (TOS) item.

ROT_TWO #

Swaps the two top-most stack items.

ROT_THREE #

Lifts second and third stack item one position up, moves top down to position three.

ROT_FOUR #

Lifts second, third and forth stack item one position up, moves top down to position four.

DUP_TOP #

Duplicates the reference on top of the stack.

Unary Operations take the top of the stack, apply the operation, and push the result back on the stack.

UNARY_POSITIVE #

Implements TOS = +TOS.

UNARY_NEGATIVE #

Implements TOS = -TOS.

UNARY_NOT #

Implements TOS = not TOS.

UNARY_CONVERT #

Implements TOS = ‘TOS‘.

UNARY_INVERT #

Implements TOS = ~TOS.

Binary operations remove the top of the stack (TOS) and the second top-most stack item (TOS1) from the stack. They perform the operation, and put the result back on the stack.

BINARY_POWER #

Implements TOS = TOS1 ** TOS.

BINARY_MULTIPLY #

Implements TOS = TOS1 * TOS.

BINARY_DIVIDE #

Implements TOS = TOS1 / TOS.

BINARY_MODULO #

Implements TOS = TOS1 % TOS.

BINARY_ADD #

Implements TOS = TOS1 + TOS.

BINARY_SUBTRACT #

Implements TOS = TOS1 - TOS.

BINARY_SUBSCR #

Implements TOS = TOS1[TOS].

BINARY_LSHIFT #

Implements TOS = TOS1 << TOS.

BINARY_RSHIFT #

Implements TOS = TOS1 >> TOS.

BINARY_AND #

Implements TOS = TOS1 & TOS.

BINARY_XOR #

Implements TOS = TOS1  ̂TOS.

BINARY_OR #

Implements TOS = TOS1 | TOS.

In-place operations are like binary operations, in that they remove TOS and TOS1, and push the result back on the stack, but the operation is done in-place when TOS1 supports it, and the resulting TOS may be (but does not have to be) the original TOS1.

INPLACE_POWER #

Implements in-place TOS = TOS1 ** TOS.

INPLACE_MULTIPLY #

Implements in-place TOS = TOS1 * TOS.

INPLACE_DIVIDE #

Implements in-place TOS = TOS1 / TOS.

INPLACE_MODULO #

Implements in-place TOS = TOS1 % TOS.

INPLACE_ADD #

Implements in-place TOS = TOS1 + TOS.

INPLACE_SUBTRACT #

Implements in-place TOS = TOS1 - TOS.

INPLACE_LSHIFT #

Implements in-place TOS = TOS1 << TOS.

INPLACE_RSHIFT #

Implements in-place TOS = TOS1 >> TOS.

INPLACE_AND #

Implements in-place TOS = TOS1 & TOS.

INPLACE_XOR #

Implements in-place TOS = TOS1  ̂TOS.

INPLACE_OR #

Implements in-place TOS = TOS1 | TOS.

The slice opcodes take up to three parameters.

SLICE+0 #

Implements TOS = TOS[:].

SLICE+1 #

Implements TOS = TOS1[TOS:].

SLICE+2 #

Implements TOS = TOS1[:TOS1].

SLICE+3 #

Implements TOS = TOS2[TOS1:TOS].

Slice assignment needs even an additional parameter. As any statement, they put nothing on the stack.

STORE_SLICE+0 #

Implements TOS[:] = TOS1.

STORE_SLICE+1 #

Implements TOS1[TOS:] = TOS2.

STORE_SLICE+2 #

Implements TOS1[:TOS] = TOS2.

STORE_SLICE+3 #

Implements TOS2[TOS1:TOS] = TOS3.

DELETE_SLICE+0 #

Implements del TOS[:].

DELETE_SLICE+1 #

Implements del TOS1[TOS:].

DELETE_SLICE+2 #

Implements del TOS1[:TOS].

DELETE_SLICE+3 #

Implements del TOS2[TOS1:TOS].

STORE_SUBSCR #

Implements TOS1[TOS] = TOS2.

DELETE_SUBSCR #

Implements del TOS1[TOS].

PRINT_EXPR #

Implements the expression statement for the interactive mode. TOS is removed from the stack and printed. In non-interactive mode, an expression statement is terminated with POP_STACK.

PRINT_ITEM #

Prints TOS to the file-like object bound to sys.stdout. There is one such instruction for each item in the statement.

PRINT_ITEM_TO #

Like PRINT_ITEM, but prints the item second from TOS to the file-like object at TOS. This is used by the extended print statement.

PRINT_NEWLINE #

Prints a new line on sys.stdout. This is generated as the last operation of a statement, unless the statement ends with a comma.

PRINT_NEWLINE_TO #

Like PRINT_NEWLINE, but prints the new line on the file-like object on the TOS. This is used by the extended print statement.

BREAK_LOOP #

Terminates a loop due to a statement.

LOAD_LOCALS #

Pushes a reference to the locals of the current scope on the stack. This is used in the code for a class definition: After the class body is evaluated, the locals are passed to the class definition.

RETURN_VALUE #

Returns with TOS to the caller of the function.

IMPORT_STAR #

Loads all symbols not starting with _ directly from the module TOS to the local namespace. The module is popped after loading all names. This opcode implements from module import *.

EXEC_STMT #

Implements exec TOS2,TOS1,TOS. The compiler fills missing optional parameters with None.

POP_BLOCK #

Removes one block from the block stack. Per frame, there is a stack of blocks, denoting nested loops, try statements, and such.

END_FINALLY #

Terminates a clause. The interpreter recalls whether the exception has to be re-raised, or whether the function returns, and continues with the outer-next block.

BUILD_CLASS #

Creates a new class object. TOS is the methods dictionary, TOS1 the tuple of the names of the base classes, and TOS2 the class name.

All of the following opcodes expect arguments. An argument is two bytes, with the more significant byte last.

STORE_NAME namei#

Implements name = TOS. namei is the index of name in the attribute co_names of the code object. The compiler tries to use STORE_LOCAL or STORE_GLOBAL if possible.

DELETE_NAME namei#

Implements del name, where namei is the index into co_names attribute of the code object.

UNPACK_SEQUENCE count#

Unpacks TOS into count individual values, which are put onto the stack right-to-left.

DUP_TOPX count#

Duplicate count items, keeping them in the same order. Due to implementation limits, count should be between 1 and 5 inclusive.

STORE_ATTR namei#

Implements TOS.name = TOS1, where namei is the index of name in co_names.

DELETE_ATTR namei#

Implements del TOS.name, using namei as index into co_names.

STORE_GLOBAL namei#

Works as STORE_NAME, but stores the name as a global.

DELETE_GLOBAL namei#

Works as DELETE_NAME, but deletes a global name.

LOAD_CONST consti#

Pushes co_consts[consti] onto the stack.

LOAD_NAME namei#

Pushes the value associated with co_names[namei] onto the stack.

BUILD_TUPLE count#

Creates a tuple consuming count items from the stack, and pushes the resulting tuple onto the stack.

BUILD_LIST count#

Works as BUILD_TUPLE, but creates a list.

BUILD_MAP zero#

Pushes a new empty dictionary object onto the stack. The argument is ignored and set to zero by the compiler.

LOAD_ATTR namei#

Replaces TOS with getattr(TOS, co_names[namei].

COMPARE_OP opname#

Performs a boolean operation. The operation name can be found in cmp_op[opname].

IMPORT_NAME namei#

Imports the module co_names[namei]. The module object is pushed onto the stack. The current namespace is not affected: for a proper import statement, a subsequent STORE_FAST instruction modifies the namespace.

IMPORT_FROM namei#

Loads the attribute co_names[namei] from the module found in TOS. The resulting object is pushed onto the stack, to be subsequently stored by a STORE_FAST instruction.

JUMP_FORWARD delta#

Increments byte code counter by delta.

JUMP_IF_TRUE delta#

If TOS is true, increment the byte code counter by delta. TOS is left on the stack.

JUMP_IF_FALSE delta#

If TOS is false, increment the byte code counter by delta. TOS is not changed.

JUMP_ABSOLUTE target#

Set byte code counter to target.

FOR_LOOP delta#

Iterate over a sequence. TOS is the current index, TOS1 the sequence. First, the next element is computed. If the sequence is exhausted, increment byte code counter by delta. Otherwise, push the sequence, the incremented counter, and the current item onto the stack.

LOAD_GLOBAL namei#

Loads the global named co_names[namei] onto the stack.

SETUP_LOOP delta#

Pushes a block for a loop onto the block stack. The block spans from the current instruction with a size of delta bytes.

SETUP_EXCEPT delta#

Pushes a try block from a try-except clause onto the block stack. delta points to the first except block.

SETUP_FINALLY delta#

Pushes a try block from a try-except clause onto the block stack. delta points to the finally block.

LOAD_FAST var_num#

Pushes a reference to the local co_varnames[var_num] onto the stack.

STORE_FAST var_num#

Stores TOS into the local co_varnames[var_num].

DELETE_FAST var_num#

Deletes local co_varnames[var_num].

SET_LINENO lineno#

Sets the current line number to lineno.

RAISE_VARARGS argc#

Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS.

CALL_FUNCTION argc#

Calls a function. The low byte of argc indicates the number of positional parameters, the high byte the number of keyword parameters. On the stack, the opcode finds the keyword parameters first. For each keyword argument, the value is on top of the key. Below the keyword parameters, the positional parameters are on the stack, with the right-most parameter on top. Below the parameters, the function object to call is on the stack.

MAKE_FUNCTION argc#

Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc default parameters, which are found below TOS.

BUILD_SLICE argc#

Pushes a slice object on the stack. argc must be 2 or 3. If it is 2, slice(TOS1, TOS) is pushed; if it is 3, slice(TOS2, TOS1, TOS) is pushed. See the slice() built-in function for more information.

EXTENDED_ARG ext#

Prefixes any opcode which has an argument too big to fit into the default two bytes. ext holds two additional bytes which, taken together with the subsequent opcode’s argument, comprise a four-byte argument, ext being the two most-significant bytes.

CALL_FUNCTION_VAR argc#

Calls a function. argc is interpreted as in CALL_FUNCTION. The top element on the stack contains the variable argument list, followed by keyword and positional arguments.

CALL_FUNCTION_KW argc#

Calls a function. argc is interpreted as in CALL_FUNCTION. The top element on the stack contains the keyword arguments dictionary, followed by explicit keyword and positional arguments.

CALL_FUNCTION_VAR_KW argc#

Calls a function. argc is interpreted as in CALL_FUNCTION. The top element on the stack contains the keyword arguments dictionary, followed by the variable-arguments tuple, followed by explicit keyword and positional arguments.

dl — Call C functions in shared objects#

Call C functions in shared objects.

The dl module defines an interface to the function, which is the most common interface on Unix platforms for handling dynamically linked libraries. It allows the program to call arbitrary functions in such a library.

Note: This module will not work unless

sizeof(int) == sizeof(long) == sizeof(char *)

If this is not the case, SystemError will be raised on import.

The dl module defines the following function:

open(name)#

Open a shared object file, and return a handle. Mode signifies late binding () or immediate binding (). Default is . Note that some systems do not support .

Return value is a .

The dl module defines the following constants:

RTLD_LAZY#

Useful as an argument to open().

RTLD_NOW#

Useful as an argument to open(). Note that on systems which do not support immediate binding, this constant will not appear in the module. For maximum portability, use hasattr() to determine if the system supports immediate binding.

The dl module defines the following exception:

exception error#

Exception raised when an error has occurred inside the dynamic loading and linking routines.

Example:

>>> import dl, time
>>> a=dl.open('/lib/libc.so.6')
>>> a.call('time'), time.time()
(929723914, 929723914.498)

This example was tried on a Debian GNU/Linux system, and is a good example of the fact that using this module is usually a bad alternative.

Dl Objects#

Dl objects, as returned by open() above, have the following methods:

close()#

Free all resources, except the memory.

sym(name)#

Return the pointer for the function named name, as a number, if it exists in the referenced shared object, otherwise None. This is useful in code like:

>>> if a.sym('time'): 
...     a.call('time')
... else: 
...     time.time()

(Note that this function will return a non-zero number, as zero is the NULL pointer)

call(name)#

Call the function named name in the referenced shared object. The arguments must be either Python integers, which will be passed as is, Python strings, to which a pointer will be passed, or None, which will be passed as NULL. Note that strings should only be passed to functions as const char*, as Python will not like its string mutated.

There must be at most 10 arguments, and arguments not given will be treated as None. The function’s return value must be a C long, which is a Python integer.

errno — Standard errno system symbols.#

Standard errno system symbols.

This module makes available standard errno system symbols. The value of each symbol is the corresponding integer value. The names and descriptions are borrowed from linux/include/errno.h, which should be pretty all-inclusive.

errorcode#

Dictionary providing a mapping from the errno value to the string name in the underlying system. For instance, errno.errorcode[errno.EPERM] maps to ’EPERM’.

To translate a numeric error code to an error message, use os.strerror().

Of the following list, symbols that are not used on the current platform are not defined by the module. Symbols available can include:

EPERM#

Operation not permitted

ENOENT#

No such file or directory

ESRCH#

No such process

EINTR#

Interrupted system call

EIO#

I/O error

ENXIO#

No such device or address

E2BIG#

Arg list too long

ENOEXEC#

Exec format error

EBADF#

Bad file number

ECHILD#

No child processes

EAGAIN#

Try again

ENOMEM#

Out of memory

EACCES#

Permission denied

EFAULT#

Bad address

ENOTBLK#

Block device required

EBUSY#

Device or resource busy

EEXIST#

File exists

EXDEV#

Cross-device link

ENODEV#

No such device

ENOTDIR#

Not a directory

EISDIR#

Is a directory

EINVAL#

Invalid argument

ENFILE#

File table overflow

EMFILE#

Too many open files

ENOTTY#

Not a typewriter

ETXTBSY#

Text file busy

EFBIG#

File too large

ENOSPC#

No space left on device

ESPIPE#

Illegal seek

EROFS#

Read-only file system

EMLINK#

Too many links

EPIPE#

Broken pipe

EDOM#

Math argument out of domain of func

ERANGE#

Math result not representable

EDEADLK#

Resource deadlock would occur

ENAMETOOLONG#

File name too long

ENOLCK#

No record locks available

ENOSYS#

Function not implemented

ENOTEMPTY#

Directory not empty

ELOOP#

Too many symbolic links encountered

EWOULDBLOCK#

Operation would block

ENOMSG#

No message of desired type

EIDRM#

Identifier removed

ECHRNG#

Channel number out of range

EL2NSYNC#

Level 2 not synchronized

EL3HLT#

Level 3 halted

EL3RST#

Level 3 reset

ELNRNG#

Link number out of range

EUNATCH#

Protocol driver not attached

ENOCSI#

No CSI structure available

EL2HLT#

Level 2 halted

EBADE#

Invalid exchange

EBADR#

Invalid request descriptor

EXFULL#

Exchange full

ENOANO#

No anode

EBADRQC#

Invalid request code

EBADSLT#

Invalid slot

EDEADLOCK#

File locking deadlock error

EBFONT#

Bad font file format

ENOSTR#

Device not a stream

ENODATA#

No data available

ETIME#

Timer expired

ENOSR#

Out of streams resources

ENONET#

Machine is not on the network

ENOPKG#

Package not installed

EREMOTE#

Object is remote

ENOLINK#

Link has been severed

EADV#

Advertise error

ESRMNT#

Srmount error

ECOMM#

Communication error on send

EPROTO#

Protocol error

EMULTIHOP#

Multihop attempted

EDOTDOT#

RFS specific error

EBADMSG#

Not a data message

EOVERFLOW#

Value too large for defined data type

ENOTUNIQ#

Name not unique on network

EBADFD#

File descriptor in bad state

EREMCHG#

Remote address changed

ELIBACC#

Can not access a needed shared library

ELIBBAD#

Accessing a corrupted shared library

ELIBSCN#

.lib section in a.out corrupted

ELIBMAX#

Attempting to link in too many shared libraries

ELIBEXEC#

Cannot exec a shared library directly

EILSEQ#

Illegal byte sequence

ERESTART#

Interrupted system call should be restarted

ESTRPIPE#

Streams pipe error

EUSERS#

Too many users

ENOTSOCK#

Socket operation on non-socket

EDESTADDRREQ#

Destination address required

EMSGSIZE#

Message too long

EPROTOTYPE#

Protocol wrong type for socket

ENOPROTOOPT#

Protocol not available

EPROTONOSUPPORT#

Protocol not supported

ESOCKTNOSUPPORT#

Socket type not supported

EOPNOTSUPP#

Operation not supported on transport endpoint

EPFNOSUPPORT#

Protocol family not supported

EAFNOSUPPORT#

Address family not supported by protocol

EADDRINUSE#

Address already in use

EADDRNOTAVAIL#

Cannot assign requested address

ENETDOWN#

Network is down

ENETUNREACH#

Network is unreachable

ENETRESET#

Network dropped connection because of reset

ECONNABORTED#

Software caused connection abort

ECONNRESET#

Connection reset by peer

ENOBUFS#

No buffer space available

EISCONN#

Transport endpoint is already connected

ENOTCONN#

Transport endpoint is not connected

ESHUTDOWN#

Cannot send after transport endpoint shutdown

ETOOMANYREFS#

Too many references: cannot splice

ETIMEDOUT#

Connection timed out

ECONNREFUSED#

Connection refused

EHOSTDOWN#

Host is down

EHOSTUNREACH#

No route to host

EALREADY#

Operation already in progress

EINPROGRESS#

Operation now in progress

ESTALE#

Stale NFS file handle

EUCLEAN#

Structure needs cleaning

ENOTNAM#

Not a XENIX named type file

ENAVAIL#

No XENIX semaphores available

EISNAM#

Is a named type file

EREMOTEIO#

Remote I/O error

EDQUOT#

Quota exceeded

Built-in Exceptions#

Standard exceptions classes.

Exceptions can be class objects or string objects. Though most exceptions have been string objects in past versions of Python, in Python 1.5 and newer versions, all standard exceptions have been converted to class objects, and users are encouraged to do the same. The exceptions are defined in the module exceptions. This module never needs to be imported explicitly: the exceptions are provided in the built-in namespace.

Two distinct string objects with the same value are considered different exceptions. This is done to force programmers to use exception names rather than their string value when specifying exception handlers. The string value of all built-in exceptions is their name, but this is not a requirement for user-defined exceptions or exceptions defined by library modules.

For class exceptions, in a statement with an clause that mentions a particular class, that clause also handles any exception classes derived from that class (but not exception classes from which it is derived). Two exception classes that are not related via subclassing are never equivalent, even if they have the same name.

The built-in exceptions listed below can be generated by the interpreter or built-in functions. Except where mentioned, they have an “associated value” indicating the detailed cause of the error. This may be a string or a tuple containing several items of information (e.g., an error code and a string explaining the code). The associated value is the second argument to the statement. For string exceptions, the associated value itself will be stored in the variable named as the second argument of the clause (if any). For class exceptions, that variable receives the exception instance. If the exception class is derived from the standard root class Exception, the associated value is present as the exception instance’s args attribute, and possibly on other attributes as well.

User code can raise built-in exceptions. This can be used to test an exception handler or to report an error condition “just like” the situation in which the interpreter raises the same exception; but beware that there is nothing to prevent user code from raising an inappropriate error.

The following exceptions are only used as base classes for other exceptions.

exception Exception#

The root class for exceptions. All built-in exceptions are derived from this class. All user-defined exceptions should also be derived from this class, but this is not (yet) enforced. The str() function, when applied to an instance of this class (or most derived classes) returns the string value of the argument or arguments, or an empty string if no arguments were given to the constructor. When used as a sequence, this accesses the arguments given to the constructor (handy for backward compatibility with old code). The arguments are also available on the instance’s args attribute, as a tuple.

exception StandardError#

The base class for all built-in exceptions except SystemExit. StandardError itself is derived from the root class Exception.

exception ArithmeticError#

The base class for those built-in exceptions that are raised for various arithmetic errors: OverflowError, ZeroDivisionError, FloatingPointError.

exception LookupError#

The base class for the exceptions that are raised when a key or index used on a mapping or sequence is invalid: IndexError, KeyError.

exception EnvironmentError#

The base class for exceptions that can occur outside the Python system: IOError, OSError. When exceptions of this type are created with a 2-tuple, the first item is available on the instance’s errno attribute (it is assumed to be an error number), and the second item is available on the strerror attribute (it is usually the associated error message). The tuple itself is also available on the args attribute. New in version 1.5.2.

When an EnvironmentError exception is instantiated with a 3-tuple, the first two items are available as above, while the third item is available on the filename attribute. However, for backwards compatibility, the args attribute contains only a 2-tuple of the first two constructor arguments.

The filename attribute is None when this exception is created with other than 3 arguments. The errno and strerror attributes are also None when the instance was created with other than 2 or 3 arguments. In this last case, args contains the verbatim constructor arguments as a tuple.

The following exceptions are the exceptions that are actually raised.

exception AssertionError#

Raised when an statement fails.

exception AttributeError#

Raised when an attribute reference or assignment fails. (When an object does not support attribute references or attribute assignments at all, TypeError is raised.)

exception EOFError#

Raised when one of the built-in functions (input() or raw_input()) hits an end-of-file condition (EOF) without reading any data.

(N.B.: the read() and readline() methods of file objects return an empty string when they hit EOF.)

exception FloatingPointError#

Raised when a floating point operation fails. This exception is always defined, but can only be raised when Python is configured with the --with-fpectl option, or the symbol is defined in the config.h file.

exception IOError#

Raised when an I/O operation (such as a statement, the built-in open() function or a method of a file object) fails for an I/O-related reason, e.g., “file not found” or “disk full”.

This class is derived from EnvironmentError. See the discussion above for more information on exception instance attributes.

exception ImportError#

Raised when an statement fails to find the module definition or when a from … import fails to find a name that is to be imported.

exception IndexError#

Raised when a sequence subscript is out of range. (Slice indices are silently truncated to fall in the allowed range; if an index is not a plain integer, TypeError is raised.)

exception KeyError#

Raised when a mapping (dictionary) key is not found in the set of existing keys.

exception KeyboardInterrupt#

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 input() or raw_input()) is waiting for input also raise this exception.

exception MemoryError#

Raised when an operation runs out of memory but the situation may still be rescued (by deleting some objects). The associated value is a string indicating what kind of (internal) operation ran out of memory. Note that because of the underlying memory management architecture (C’s function), the interpreter may not always be able to completely recover from this situation; it nevertheless raises an exception so that a stack traceback can be printed, in case a run-away program was the cause.

exception NameError#

Raised when a local or global name is not found. This applies only to unqualified names. The associated value is the name that could not be found.

exception NotImplementedError#

This exception is derived from RuntimeError. In user defined base classes, abstract methods should raise this exception when they require derived classes to override the method. New in version 1.5.2.

exception OSError#

This class is derived from EnvironmentError and is used primarily as the os module’s os.error exception. See EnvironmentError above for a description of the possible associated values. New in version 1.5.2.

exception OverflowError#

Raised when the result of an arithmetic operation is too large to be represented. This cannot occur for long integers (which would rather raise MemoryError than give up). Because of the lack of standardization of floating point exception handling in C, most floating point operations also aren’t checked. For plain integers, all operations that can overflow are checked except left shift, where typical applications prefer to drop bits than raise an exception.

exception RuntimeError#

Raised when an error is detected that doesn’t fall in any of the other categories. The associated value is a string indicating what precisely went wrong. (This exception is mostly a relic from a previous version of the interpreter; it is not used very much any more.)

exception SyntaxError#

Raised when the parser encounters a syntax error. This may occur in an statement, in an statement, in a call to the built-in function eval() or input(), or when reading the initial script or standard input (also interactively).

When class exceptions are used, instances of this class have atttributes filename, lineno, offset and text for easier access to the details; for string exceptions, the associated value is usually a tuple of the form (message, (filename, lineno, offset, text)). For class exceptions, str() returns only the message.

exception SystemError#

Raised when the interpreter finds an internal error, but the situation does not look so serious to cause it to abandon all hope. The associated value is a string indicating what went wrong (in low-level terms).

You should report this to the author or maintainer of your Python interpreter. Be sure to report the version string of the Python interpreter (sys.version; it is also printed at the start of an interactive Python session), the exact error message (the exception’s associated value) and if possible the source of the program that triggered the error.

exception SystemExit#

This exception is raised by the sys.exit() function. When it is not handled, the Python interpreter exits; no stack traceback is printed. If the associated value is a plain integer, it specifies the system exit status (passed to C’s function); if it is None, the exit status is zero; if it has another type (such as a string), the object’s value is printed and the exit status is one.

Instances have an attribute code which is set to the proposed exit status or error message (defaulting to None). Also, this exception derives directly from Exception and not StandardError, since it is not technically an error.

A call to sys.exit() is translated into an exception so that clean-up handlers ( clauses of statements) can be executed, and so that a debugger can execute a script without running the risk of losing control. The os._exit() function can be used if it is absolutely positively necessary to exit immediately (e.g., after a fork() in the child process).

exception TypeError#

Raised when a built-in operation or function is applied to an object of inappropriate type. The associated value is a string giving details about the type mismatch.

exception UnboundLocalError#

Raised when a reference is made to a local variable in a function or method, but no value has been bound to that variable. This is a subclass of NameError. New in version 2.0.

exception UnicodeError#

Raised when a Unicode-related encoding or decoding error occurs. It is a subclass of ValueError. New in version 2.0.

exception ValueError#

Raised when a built-in operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as IndexError.

exception WindowsError#

Raised when a Windows-specific error occurs or when the error number does not correspond to an value. The errno and strerror values are created from the return values of the and functions from the Windows Platform API. This is a subclass of OSError. New in version 2.0.

exception ZeroDivisionError#

Raised when the second argument of a division or modulo operation is zero. The associated value is a string indicating the type of the operands and the operation.

fcntl — The fcntl() and ioctl() system calls#

The fcntl() and ioctl() system calls.

This module performs file control and I/O control on file descriptors. It is an interface to the and Unix routines. File descriptors can be obtained with the fileno() method of a file or socket object.

The module defines the following functions:

fcntl(fd, op)#

Perform the requested operation on file descriptor fd. The operation is defined by op and is operating system dependent. Typically these codes can be retrieved from the library module FCNTL. The argument arg is optional, and defaults to the integer value 0. When present, it can either be an integer value, or a string. With the argument missing or an integer value, the return value of this function is the integer return value of the C call. When the argument is a string it represents a binary structure, e.g. created by struct.pack(). The binary data is copied to a buffer whose address is passed to the C call. The return value after a successful call is the contents of the buffer, converted to a string object. The length of the returned string will be the same as the length of the arg argument. This is limited to 1024 bytes. If the information returned in the buffer by the operating system is larger than 1024 bytes, this is most likely to result in a segmentation violation or a more subtle data corruption.

If the fails, an IOError is raised.

ioctl(fd, op, arg)#

This function is identical to the fcntl() function, except that the operations are typically defined in the library module IOCTL.

flock(fd, op)#

Perform the lock operation op on file descriptor fd. See the Unix manual for details. (On some systems, this function is emulated using .)

lockf(fd, code, )#

This is a wrapper around the and fcntl() calls. See the Unix manual for details.

If the library modules FCNTL or IOCTL are missing, you can find the opcodes in the C include files <sys/fcntl.h> and <sys/ioctl.h>. You can create the modules yourself with the h2py script, found in the Tools/scripts/ directory.

Examples (all on a SVR4 compliant system):

import struct, fcntl, FCNTL

file = open(...)
rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)

lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)

Note that in the first example the return value variable rv will hold an integer value; in the second example it will hold a string value. The structure lay-out for the lockdata variable is system dependent — therefore using the flock() call may be better.

filecmp — File and Directory Comparisons#

Compare files efficiently.

The filecmp module defines functions to compare files and directories, with various optional time/correctness trade-offs.

The filecmp module defines the following function:

cmp(f1, f2)#

Compare the files named f1 and f2, returning 1 if they seem equal, 0 otherwise.

Unless shallow is given and is false, files with identical os.stat() signatures are taken to be equal. If use_statcache is given and is true, statcache.stat() will be called rather then os.stat(); the default is to use os.stat().

Files that were compared using this function will not be compared again unless their os.stat() signature changes. Note that using use_statcache true will cause the cache invalidation mechanism to fail — the stale stat value will be used from statcache’s cache.

Note that no external programs are called from this function, giving it portability and efficiency.

cmpfiles(dir1, dir2, common)#

Returns three lists of file names: match, mismatch, errors. match contains the list of files match in both directories, mismatch includes the names of those that don’t, and errros lists the names of files which could not be compared. Files may be listed in errors because the user may lack permission to read them or many other reasons, but always that the comparison could not be done for some reason.

The shallow and use_statcache parameters have the same meanings and default values as for filecmp.cmp().

Example:

>>> import filecmp
>>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
1
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
0

The dircmp class#

class dircmp(a, b)#

Construct a new directory comparison object, to compare the directories a and b. ignore is a list of names to ignore, and defaults to [’RCS’, ’CVS’, ’tags’]. hide is a list of names to hid, and defaults to [os.curdir, os.pardir].

report()#

Print (to sys.stdout) a comparison between a and b.

report_partial_closure()#

Print a comparison between a and b and common immediate subdirctories.

report_full_closure()#

Print a comparison between a and b and common subdirctories (recursively).

left_list#

Files and subdirectories in a, filtered by hide and ignore.

right_list#

Files and subdirectories in b, filtered by hide and ignore.

common#

Files and subdirectories in both a and b.

left_only#

Files and subdirectories only in a.

right_only#

Files and subdirectories only in b.

common_dirs#

Subdirectories in both a and b.

common_files#

Files in both a and b

common_funny#

Names in both a and b, such that the type differs between the directories, or names for which os.stat() reports an error.

same_files#

Files which are identical in both a and b.

diff_files#

Files which are in both a and b, whose contents differ.

funny_files#

Files which are in both a and b, but could not be compared.

subdirs#

A dictionary mapping names in common_dirs to dircmp objects.

Note that via __getattr__() hooks, all attributes are computed lazilly, so there is no speed penalty if only those attributes which are lightweight to compute are used.

fileinput — Iterate over lines from multiple input streams#

Perl-like iteration over lines from multiple input streams, with “save in place” capability.

This module implements a helper class and functions to quickly write a loop over standard input or a list of files.

The typical use is:

import fileinput
for line in fileinput.input():
    process(line)

This iterates over the lines of all files listed in sys.argv[1:], defaulting to sys.stdin if the list is empty. If a filename is ’-’, it is also replaced by sys.stdin. To specify an alternative list of filenames, pass it as the first argument to input(). A single file name is also allowed.

All files are opened in text mode. If an I/O error occurs during opening or reading a file, IOError is raised.

If sys.stdin is used more than once, the second and further use will return no lines, except perhaps for interactive use, or if it has been explicitly reset (e.g. using sys.stdin.seek(0)).

Empty files are opened and immediately closed; the only time their presence in the list of filenames is noticeable at all is when the last file opened is empty.

It is possible that the last line of a file does not end in a newline character; lines are returned including the trailing newline when it is present.

The following function is the primary interface of this module:

input()#

Create an instance of the FileInput class. The instance will be used as global state for the functions of this module, and is also returned to use during iteration.

The following functions use the global state created by input(); if there is no active state, RuntimeError is raised.

filename()#

Return the name of the file currently being read. Before the first line has been read, returns None.

lineno()#

Return the cumulative line number of the line that has just been read. Before the first line has been read, returns 0. After the last line of the last file has been read, returns the line number of that line.

filelineno()#

Return the line number in the current file. Before the first line has been read, returns 0. After the last line of the last file has been read, returns the line number of that line within the file.

isfirstline()#

Returns true the line just read is the first line of its file, otherwise returns false.

isstdin()#

Returns true if the last line was read from sys.stdin, otherwise returns false.

nextfile()#

Close the current file so that the next iteration will read the first line from the next file (if any); lines not read from the file will not count towards the cumulative line count. The filename is not changed until after the first line of the next file has been read. Before the first line has been read, this function has no effect; it cannot be used to skip the first file. After the last line of the last file has been read, this function has no effect.

close()#

Close the sequence.

The class which implements the sequence behavior provided by the module is available for subclassing as well:

class FileInput()#

Class FileInput is the implementation; its methods filename(), lineno(), fileline(), isfirstline(), isstdin(), nextfile() and close() correspond to the functions of the same name in the module. In addition it has a readline() method which returns the next input line, and a __getitem__() method which implements the sequence behavior. The sequence must be accessed in strictly sequential order; random access and readline() cannot be mixed.

Optional in-place filtering: if the keyword argument inplace=1 is passed to input() or to the FileInput constructor, the file is moved to a backup file and standard output is directed to the input file. This makes it possible to write a filter that rewrites its input file in place. If the keyword argument backup=’.<some extension>’ is also given, it specifies the extension for the backup file, and the backup file remains around; by default, the extension is ’.bak’ and it is deleted when the output file is closed. In-place filtering is disabled when standard input is read.

Caveat: The current implementation does not work for MS-DOS 8+3 filesystems.

fl — FORMS library interface for GUI applications#

FORMS library interface for GUI applications.

This module provides an interface to the FORMS Library by Mark Overmars. The source for the library can be retrieved by anonymous ftp from host ftp.cs.ruu.nl, directory SGI/FORMS. It was last tested with version 2.0b.

Most functions are literal translations of their C equivalents, dropping the initial fl_ from their name. Constants used by the library are defined in module FL described below.

The creation of objects is a little different in Python than in C: instead of the ‘current form’ maintained by the library to which new FORMS objects are added, all functions that add a FORMS object to a form are methods of the Python object representing the form. Consequently, there are no Python equivalents for the C functions and , and the equivalent of is called fl.make_form().

Watch out for the somewhat confusing terminology: FORMS uses the word object for the buttons, sliders etc. that you can place in a form. In Python, ‘object’ means any value. The Python interface to FORMS introduces two new Python object types: form objects (representing an entire form) and FORMS objects (representing one button, slider etc.). Hopefully this isn’t too confusing.

There are no ‘free objects’ in the Python interface to FORMS, nor is there an easy way to add object classes written in Python. The FORMS interface to GL event handling is available, though, so you can mix FORMS with pure GL windows.

Please note: importing fl implies a call to the GL function and to the FORMS routine .

Functions Defined in Module fl#

Module fl defines the following functions. For more information about what they do, see the description of the equivalent C function in the FORMS documentation:

make_form(type, width, height)#

Create a form with given type, width and height. This returns a form object, whose methods are described below.

do_forms()#

The standard FORMS main loop. Returns a Python object representing the FORMS object needing interaction, or the special value .

check_forms()#

Check for FORMS events. Returns what do_forms() above returns, or None if there is no event that immediately needs interaction.

set_event_call_back(function)#

Set the event callback function.

set_graphics_mode(rgbmode, doublebuffering)#

Set the graphics modes.

get_rgbmode()#

Return the current rgb mode. This is the value of the C global variable .

show_message(str1, str2, str3)#

Show a dialog box with a three-line message and an OK button.

show_question(str1, str2, str3)#

Show a dialog box with a three-line message and YES and NO buttons. It returns 1 if the user pressed YES, 0 if NO.

show_choice(str1, str2, str3, but1)#

Show a dialog box with a three-line message and up to three buttons. It returns the number of the button clicked by the user (1, 2 or 3).

show_input(prompt, default)#

Show a dialog box with a one-line prompt message and text field in which the user can enter a string. The second argument is the default input string. It returns the string value as edited by the user.

show_file_selector(message, directory, pattern, default)#

Show a dialog box in which the user can select a file. It returns the absolute filename selected by the user, or None if the user presses Cancel.

get_directory()#

These functions return the directory, pattern and filename (the tail part only) selected by the user in the last show_file_selector() call.

qdevice(dev)#

These functions are the FORMS interfaces to the corresponding GL functions. Use these if you want to handle some GL events yourself when using fl.do_events(). When a GL event is detected that FORMS cannot handle, fl.do_forms() returns the special value and you should call fl.qread() to read the event from the queue. Don’t use the equivalent GL functions!

color()#

See the description in the FORMS documentation of , and .

Form Objects#

Form objects (returned by make_form() above) have the following methods. Each method corresponds to a C function whose name is prefixed with fl_; and whose first argument is a form pointer; please refer to the official FORMS documentation for descriptions.

All the add_*() methods return a Python object representing the FORMS object. Methods of FORMS objects are described below. Most kinds of FORMS object also have some methods specific to that kind; these methods are listed here.

show_form(placement, bordertype, name)#

Show the form.

hide_form()#

Hide the form.

redraw_form()#

Redraw the form.

set_form_position(x, y)#

Set the form’s position.

freeze_form()#

Freeze the form.

unfreeze_form()#

Unfreeze the form.

activate_form()#

Activate the form.

deactivate_form()#

Deactivate the form.

bgn_group()#

Begin a new group of objects; return a group object.

end_group()#

End the current group of objects.

find_first()#

Find the first object in the form.

find_last()#

Find the last object in the form.

add_box(type, x, y, w, h, name)#

Add a box object to the form. No extra methods.

add_text(type, x, y, w, h, name)#

Add a text object to the form. No extra methods.

add_clock(type, x, y, w, h, name)#

Add a clock object to the form.
Method: get_clock().

add_button(type, x, y, w, h, name)#

Add a button object to the form.
Methods: get_button(), set_button().

add_lightbutton(type, x, y, w, h, name)#

Add a lightbutton object to the form.
Methods: get_button(), set_button().

add_roundbutton(type, x, y, w, h, name)#

Add a roundbutton object to the form.
Methods: get_button(), set_button().

add_slider(type, x, y, w, h, name)#

Add a slider object to the form.
Methods: set_slider_value(), get_slider_value(), set_slider_bounds(), get_slider_bounds(), set_slider_return(), set_slider_size(), set_slider_precision(), set_slider_step().

add_valslider(type, x, y, w, h, name)#

Add a valslider object to the form.
Methods: set_slider_value(), get_slider_value(), set_slider_bounds(), get_slider_bounds(), set_slider_return(), set_slider_size(), set_slider_precision(), set_slider_step().

add_dial(type, x, y, w, h, name)#

Add a dial object to the form.
Methods: set_dial_value(), get_dial_value(), set_dial_bounds(), get_dial_bounds().

add_positioner(type, x, y, w, h, name)#

Add a positioner object to the form.
Methods: set_positioner_xvalue(), set_positioner_yvalue(), set_positioner_xbounds(), set_positioner_ybounds(), get_positioner_xvalue(), get_positioner_yvalue(), get_positioner_xbounds(), get_positioner_ybounds().

add_counter(type, x, y, w, h, name)#

Add a counter object to the form.
Methods: set_counter_value(), get_counter_value(), set_counter_bounds(), set_counter_step(), set_counter_precision(), set_counter_return().

add_input(type, x, y, w, h, name)#

Add a input object to the form.
Methods: set_input(), get_input(), set_input_color(), set_input_return().

add_menu(type, x, y, w, h, name)#

Add a menu object to the form.
Methods: set_menu(), get_menu(), addto_menu().

add_choice(type, x, y, w, h, name)#

Add a choice object to the form.
Methods: set_choice(), get_choice(), clear_choice(), addto_choice(), replace_choice(), delete_choice(), get_choice_text(), set_choice_fontsize(), set_choice_fontstyle().

add_browser(type, x, y, w, h, name)#

Add a browser object to the form.
Methods: set_browser_topline(), clear_browser(), add_browser_line(), addto_browser(), insert_browser_line(), delete_browser_line(), replace_browser_line(), get_browser_line(), load_browser(), get_browser_maxline(), select_browser_line(), deselect_browser_line(), deselect_browser(), isselected_browser_line(), get_browser(), set_browser_fontsize(), set_browser_fontstyle(), set_browser_specialkey().

add_timer(type, x, y, w, h, name)#

Add a timer object to the form.
Methods: set_timer(), get_timer().

Form objects have the following data attributes; see the FORMS documentation:

FORMS Objects#

Besides methods specific to particular kinds of FORMS objects, all FORMS objects also have the following methods:

set_call_back(function, argument)#

Set the object’s callback function and argument. When the object needs interaction, the callback function will be called with two arguments: the object, and the callback argument. (FORMS objects without a callback function are returned by fl.do_forms() or fl.check_forms() when they need interaction.) Call this method without arguments to remove the callback function.

delete_object()#

Delete the object.

show_object()#

Show the object.

hide_object()#

Hide the object.

redraw_object()#

Redraw the object.

freeze_object()#

Freeze the object.

unfreeze_object()#

Unfreeze the object.

FORMS objects have these data attributes; see the FORMS documentation:

FL — Constants used with the fl module#

Constants used with the fl module.

This module defines symbolic constants needed to use the built-in module fl (see above); they are equivalent to those defined in the C header file <forms.h> except that the name prefix FL_ is omitted. Read the module source for a complete list of the defined names. Suggested use:

import fl
from FL import *

flp — Functions for loading stored FORMS designs#

Functions for loading stored FORMS designs.

This module defines functions that can read form definitions created by the ‘form designer’ (fdesign) program that comes with the FORMS library (see module fl above).

For now, see the file flp.doc in the Python library source directory for a description.

XXX A complete description should be inserted here!

fm — Font Manager interface#

Font Manager interface for SGI workstations.

This module provides access to the IRIS Font Manager library.

It is available only on Silicon Graphics machines. See also: 4Sight User’s Guide, section 1, chapter 5: “Using the IRIS Font Manager.”

This is not yet a full interface to the IRIS Font Manager. Among the unsupported features are: matrix operations; cache operations; character operations (use string operations instead); some details of font info; individual glyph metrics; and printer matching.

It supports the following operations:

init()#

Initialization function. Calls . It is normally not necessary to call this function, since it is called automatically the first time the fm module is imported.

findfont(fontname)#

Return a font handle object. Calls fmfindfont(fontname).

enumerate()#

Returns a list of available font names. This is an interface to .

prstr(string)#

Render a string using the current font (see the setfont() font handle method below). Calls fmprstr(string).

setpath(string)#

Sets the font search path. Calls fmsetpath(string). (XXX Does not work!?!)

fontpath()#

Returns the current font search path.

Font handle objects support the following operations:

scalefont(factor)#

Returns a handle for a scaled version of this font. Calls fmscalefont(fh, factor).

setfont()#

Makes this font the current font. Note: the effect is undone silently when the font handle object is deleted. Calls fmsetfont(fh).

getfontname()#

Returns this font’s name. Calls fmgetfontname(fh).

getcomment()#

Returns the comment string associated with this font. Raises an exception if there is none. Calls fmgetcomment(fh).

getfontinfo()#

Returns a tuple giving some pertinent data about this font. This is an interface to fmgetfontinfo(). The returned tuple contains the following numbers: (printermatched, fixed_width, xorig, yorig, xsize, ysize, height, nglyphs).

getstrwidth(string)#

Returns the width, in pixels, of string when drawn in this font. Calls fmgetstrwidth(fh, string).

fnmatch — Unix filename pattern matching#

Unix shell style filename pattern matching.

This module provides support for Unix shell-style wildcards, which are not the same as regular expressions (which are documented in the re module). The special characters used in shell-style wildcards are:

Note that the filename separator (’/’ on Unix) is not special to this module. See module glob for pathname expansion (glob uses fnmatch() to match pathname segments). Similarly, filenames starting with a period are not special for this module, and are matched by the * and ? patterns.

fnmatch(filename, pattern)#

Test whether the filename string matches the pattern string, returning true or false. If the operating system is case-insensitive, then both parameters will be normalized to all lower- or upper-case before the comparison is performed. If you require a case-sensitive comparison regardless of whether that’s standard for your operating system, use fnmatchcase() instead.

fnmatchcase(filename, pattern)#

Test whether filename matches pattern, returning true or false; the comparison is case-sensitive.

See also:#

— globUnix shell-style path expansion.

formatter — Generic output formatting#

Generic output formatter and device interface.

This module supports two interface definitions, each with multiple implementations. The formatter interface is used by the HTMLParser class of the htmllib module, and the writer interface is required by the formatter interface.

Formatter objects transform an abstract flow of formatting events into specific output events on writer objects. Formatters manage several stack structures to allow various properties of a writer object to be changed and restored; writers need not be able to handle relative changes nor any sort of “change back” operation. Specific writer properties which may be controlled via formatter objects are horizontal alignment, font, and left margin indentations. A mechanism is provided which supports providing arbitrary, non-exclusive style settings to a writer as well. Additional interfaces facilitate formatting events which are not reversible, such as paragraph separation.

Writer objects encapsulate device interfaces. Abstract devices, such as file formats, are supported as well as physical devices. The provided implementations all work with abstract devices. The interface makes available mechanisms for setting the properties which formatter objects manage and inserting data into the output.

The Formatter Interface#

Interfaces to create formatters are dependent on the specific formatter class being instantiated. The interfaces described below are the required interfaces which all formatters must support once initialized.

One data element is defined at the module level:

AS_IS#

Value which can be used in the font specification passed to the push_font() method described below, or as the new value to any other push_property() method. Pushing the AS_IS value allows the corresponding pop_property() method to be called without having to track whether the property was changed.

The following attributes are defined for formatter instance objects:

writer#

The writer instance with which the formatter interacts.

end_paragraph(blanklines)#

Close any open paragraphs and insert at least blanklines before the next paragraph.

add_line_break()#

Add a hard line break if one does not already exist. This does not break the logical paragraph.

add_hor_rule(*args, **kw)#

Insert a horizontal rule in the output. A hard break is inserted if there is data in the current paragraph, but the logical paragraph is not broken. The arguments and keywords are passed on to the writer’s send_line_break() method.

add_flowing_data(data)#

Provide data which should be formatted with collapsed whitespace. Whitespace from preceding and successive calls to add_flowing_data() is considered as well when the whitespace collapse is performed. The data which is passed to this method is expected to be word-wrapped by the output device. Note that any word-wrapping still must be performed by the writer object due to the need to rely on device and font information.

add_literal_data(data)#

Provide data which should be passed to the writer unchanged. Whitespace, including newline and tab characters, are considered legal in the value of data.

add_label_data(format, counter)#

Insert a label which should be placed to the left of the current left margin. This should be used for constructing bulleted or numbered lists. If the format value is a string, it is interpreted as a format specification for counter, which should be an integer. The result of this formatting becomes the value of the label; if format is not a string it is used as the label value directly. The label value is passed as the only argument to the writer’s send_label_data() method. Interpretation of non-string label values is dependent on the associated writer.

Format specifications are strings which, in combination with a counter value, are used to compute label values. Each character in the format string is copied to the label value, with some characters recognized to indicate a transform on the counter value. Specifically, the character 1 represents the counter value formatter as an Arabic number, the characters A and a represent alphabetic representations of the counter value in upper and lower case, respectively, and I and i represent the counter value in Roman numerals, in upper and lower case. Note that the alphabetic and roman transforms require that the counter value be greater than zero.

flush_softspace()#

Send any pending whitespace buffered from a previous call to add_flowing_data() to the associated writer object. This should be called before any direct manipulation of the writer object.

push_alignment(align)#

Push a new alignment setting onto the alignment stack. This may be if no change is desired. If the alignment value is changed from the previous setting, the writer’s new_alignment() method is called with the align value.

pop_alignment()#

Restore the previous alignment.

push_font((size, italic, bold, teletype))#

Change some or all font properties of the writer object. Properties which are not set to are set to the values passed in while others are maintained at their current settings. The writer’s new_font() method is called with the fully resolved font specification.

pop_font()#

Restore the previous font.

push_margin(margin)#

Increase the number of left margin indentations by one, associating the logical tag margin with the new indentation. The initial margin level is 0. Changed values of the logical tag must be true values; false values other than are not sufficient to change the margin.

pop_margin()#

Restore the previous margin.

push_style(*styles)#

Push any number of arbitrary style specifications. All styles are pushed onto the styles stack in order. A tuple representing the entire stack, including values, is passed to the writer’s new_styles() method.

pop_style()#

Pop the last n style specifications passed to push_style(). A tuple representing the revised stack, including values, is passed to the writer’s new_styles() method.

set_spacing(spacing)#

Set the spacing style for the writer.

assert_line_data()#

Inform the formatter that data has been added to the current paragraph out-of-band. This should be used when the writer has been manipulated directly. The optional flag argument can be set to false if the writer manipulations produced a hard line break at the end of the output.

Formatter Implementations#

Two implementations of formatter objects are provided by this module. Most applications may use one of these classes without modification or subclassing.

class NullFormatter()#

A formatter which does nothing. If writer is omitted, a NullWriter instance is created. No methods of the writer are called by NullFormatter instances. Implementations should inherit from this class if implementing a writer interface but don’t need to inherit any implementation.

class AbstractFormatter(writer)#

The standard formatter. This implementation has demonstrated wide applicability to many writers, and may be used directly in most circumstances. It has been used to implement a full-featured world-wide web browser.

The Writer Interface#

Interfaces to create writers are dependent on the specific writer class being instantiated. The interfaces described below are the required interfaces which all writers must support once initialized. Note that while most applications can use the AbstractFormatter class as a formatter, the writer must typically be provided by the application.

flush()#

Flush any buffered output or device control events.

new_alignment(align)#

Set the alignment style. The align value can be any object, but by convention is a string or None, where None indicates that the writer’s “preferred” alignment should be used. Conventional align values are ’left’, ’center’, ’right’, and ’justify’.

new_font(font)#

Set the font style. The value of font will be None, indicating that the device’s default font should be used, or a tuple of the form (size, italic, bold, teletype). Size will be a string indicating the size of font that should be used; specific strings and their interpretation must be defined by the application. The italic, bold, and teletype values are boolean indicators specifying which of those font attributes should be used.

new_margin(margin, level)#

Set the margin level to the integer level and the logical tag to margin. Interpretation of the logical tag is at the writer’s discretion; the only restriction on the value of the logical tag is that it not be a false value for non-zero values of level.

new_spacing(spacing)#

Set the spacing style to spacing.

new_styles(styles)#

Set additional styles. The styles value is a tuple of arbitrary values; the value should be ignored. The styles tuple may be interpreted either as a set or as a stack depending on the requirements of the application and writer implementation.

send_line_break()#

Break the current line.

send_paragraph(blankline)#

Produce a paragraph separation of at least blankline blank lines, or the equivalent. The blankline value will be an integer. Note that the implementation will receive a call to send_line_break() before this call if a line break is needed; this method should not include ending the last line of the paragraph. It is only responsible for vertical spacing between paragraphs.

send_hor_rule(*args, **kw)#

Display a horizontal rule on the output device. The arguments to this method are entirely application- and writer-specific, and should be interpreted with care. The method implementation may assume that a line break has already been issued via send_line_break().

send_flowing_data(data)#

Output character data which may be word-wrapped and re-flowed as needed. Within any sequence of calls to this method, the writer may assume that spans of multiple whitespace characters have been collapsed to single space characters.

send_literal_data(data)#

Output character data which has already been formatted for display. Generally, this should be interpreted to mean that line breaks indicated by newline characters should be preserved and no new line breaks should be introduced. The data may contain embedded newline and tab characters, unlike data provided to the send_formatted_data() interface.

send_label_data(data)#

Set data to the left of the current left margin, if possible. The value of data is not restricted; treatment of non-string values is entirely application- and writer-dependent. This method will only be called at the beginning of a line.

Writer Implementations#

Three implementations of the writer object interface are provided as examples by this module. Most applications will need to derive new writer classes from the NullWriter class.

class NullWriter()#

A writer which only provides the interface definition; no actions are taken on any methods. This should be the base class for all writers which do not need to inherit any implementation methods.

class AbstractWriter()#

A writer which can be used in debugging formatters, but not much else. Each method simply announces itself by printing its name and arguments on standard output.

class DumbWriter()#

Simple writer class which writes output on the file object passed in as file or, if file is omitted, on standard output. The output is simply word-wrapped to the number of columns specified by maxcol. This class is suitable for reflowing a sequence of paragraphs.

fpformat — Floating point conversions#

General floating point formatting functions.

The fpformat module defines functions for dealing with floating point numbers representations in 100% pure Python. Note: This module is unneeded: everything here could be done via the % string interpolation operator.

The fpformat module defines the following functions and an exception:

fix(x, digs)#

Format x as [-]ddd.ddd with digs digits after the point and at least one digit before. If digs <= 0, the decimal point is suppressed.

x can be either a number or a string that looks like one. digs is an integer.

Return value is a string.

sci(x, digs)#

Format x as [-]d.dddE[+-]ddd with digs digits after the point and exactly one digit before. If digs <= 0, one digit is kept and the point is suppressed.

x can be either a real number, or a string that looks like one. digs is an integer.

Return value is a string.

exception NotANumber#

Exception raised when a string passed to fix() or sci() as the x parameter does not look like a number. This is a subclass of ValueError when the standard exceptions are strings. The exception value is the improperly formatted string that caused the exception to be raised.

Example:

>>> import fpformat
>>> fpformat.fix(1.23, 1)
'1.2'

ftplib — FTP protocol client#

FTP protocol client (requires sockets).

This module defines the class FTP and a few related items. The FTP class implements the client side of the FTP protocol. You can use this to write Python programs that perform a variety of automated FTP jobs, such as mirroring other ftp servers. It is also used by the module urllib to handle URLs that use FTP. For more information on FTP (File Transfer Protocol), see Internet RFC 959.

Here’s a sample session using the ftplib module:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
>>> ftp.login()               # user anonymous, passwd user@hostname
>>> ftp.retrlines('LIST')     # list directory contents
total 24418
drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
-rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
 .
 .
 .
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()

The module defines the following items:

class FTP()#

Return a new instance of the FTP class. When host is given, the method call connect(host) is made. When user is given, additionally the method call login(user, passwd, acct) is made (where passwd and acct default to the empty string when not given).

all_errors#

The set of all exceptions (as a tuple) that methods of FTP instances may raise as a result of problems with the FTP connection (as opposed to programming errors made by the caller). This set includes the four exceptions listed below as well as socket.error and IOError.

exception error_reply#

Exception raised when an unexpected reply is received from the server.

exception error_temp#

Exception raised when an error code in the range 400–499 is received.

exception error_perm#

Exception raised when an error code in the range 500–599 is received.

exception error_proto#

Exception raised when a reply is received from the server that does not begin with a digit in the range 1–5.

See also:#

— netrcParser for the .netrc file format. The file .netrc is typically used by FTP clients to load user authentication information before prompting the user. The file Tools/scripts/ftpmirror.py in the Python source distribution is a script that can mirror FTP sites, or portions thereof, using the ftplib module. It can be used as an extended example that applies this module.

FTP Objects#

Several methods are available in two flavors: one for handling text files and another for binary files. These are named for the command which is used followed by lines for the text version or binary for the binary version.

FTP instances have the following methods:

set_debuglevel(level)#

Set the instance’s debugging level. This controls the amount of debugging output printed. The default, 0, produces no debugging output. A value of 1 produces a moderate amount of debugging output, generally a single line per request. A value of 2 or higher produces the maximum amount of debugging output, logging each line sent and received on the control connection.

connect(host)#

Connect to the given host and port. The default port number is 21, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made.

getwelcome()#

Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.)

login()#

Log in as the given user. The passwd and acct parameters are optional and default to the empty string. If no user is specified, it defaults to ’anonymous’. If user is ’anonymous’, the default passwd is realuser@host where realuser is the real user name (glanced from the or environment variable) and host is the hostname as returned by socket.gethostname(). This function should be called only once for each instance, after a connection has been established; it should not be called at all if a host and user were given when the instance was created. Most FTP commands are only allowed after the client has logged in.

abort()#

Abort a file transfer that is in progress. Using this does not always work, but it’s worth a try.

sendcmd(command)#

Send a simple command string to the server and return the response string.

voidcmd(command)#

Send a simple command string to the server and handle the response. Return nothing if a response code in the range 200–299 is received. Raise an exception otherwise.

retrbinary(command, callback)#

Retrieve a file in binary transfer mode. command should be an appropriate RETR command, i.e. ’RETR filename’. The callback function is called for each block of data received, with a single string argument giving the data block. The optional maxblocksize argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to callback). A reasonable default is chosen. rest means the same thing as in the transfercmd() method.

retrlines(command)#

Retrieve a file or directory listing in ASCII transfer mode. command should be an appropriate RETR command (see retrbinary() or a LIST command (usually just the string ’LIST’). The callback function is called for each line, with the trailing CRLF stripped. The default callback prints the line to sys.stdout.

set_pasv(boolean)#

Enable “passive” mode if boolean is true, other disable passive mode.

storbinary(command, file, blocksize)#

Store a file in binary transfer mode. command should be an appropriate STOR command, i.e. "STOR filename". file is an open file object which is read until EOF using its read() method in blocks of size blocksize to provide the data to be stored.