Standard Module aifc#

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.

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  mode)#

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. The mode is either the string ’r’ when the file must be opened for reading, or ’w’ when the file must be opened for writing. 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 aifc.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 aifc.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.

Built-in Module al#

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 al.newconfig(). The return value is an port object; methods of port objects are described below.

newconfig()#

The return value is a new configuration object; methods of 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 ALqueryparams().

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 al.queryparams.

Configuration Objects#

Configuration objects (returned by al.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 (returned by al.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.

Standard Module AL#

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 modelled after the Unix or C interfaces but they are available on most other systems as well. Here’s an overview:

os
— Miscellaneous OS interfaces.

time
— Time access and conversions.

getopt
— Parser for command line options.

tempfile
— Generate temporary file names.

errno
— Standard errno system symbols.

glob
— Unix shell style pathname pattern expansion.

fnmatch
— Unix shell style pathname pattern matching.

locale
— Internationalization services.

Amoeba Specific Services#

Built-in Module amoeba#

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

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.

Standard Modules anydbm and dumbdbm#

anydbm is a generic interface to variants of the DBM database–DBM, GDBM, or dbhash. If none of these modules is installed, the slow-but-simple implementation in module dumbdbm will be used. Both modules provide the same interface:

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

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.

Both modules also export the exception error, which is raised for various problems. The anydbm.error exception is simply a different name for the error exception of the underlying implementation module used.

Built-in Module array#

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 can’t represent the full range of C’s unsigned (long) integers.

See also built-in module struct.

The module defines the following function:

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.

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 ioctl operations. The returned numbers are valid as long as the array exists and no length-changing operations are applied to it.

byteswap(x)#

“Byteswap” all items of the array. This is only supported for integer values. It is useful when reading data from a file written on a machine with a different byte order.

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

insert(i  x)#

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

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

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 (‘‘). Examples:

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

Built-in Module audioop#

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.

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

This routine (which only accepts 2-byte sample fragments)

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 framgent 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 tupl (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. the square root of the quotient of the sum of all squared sample value, divided by the sumber of samples.

√(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 ULAW encoding to linearly encoded sound fragments. ULAW 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 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)

Standard Module base64#

This module perform base-64 encoding and decoding of arbitrary binary strings into text strings that can be safely emailed or posted. The encoding scheme is defined in RFC 1421 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 base-64 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 base-64 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 base-64 encoded data.

Standard Module BaseHTTPServer#

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

The HTTPServer 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.

The module’s second class, BaseHTTPRequestHandler, 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 SPAM, the do_SPAM method will be called with no arguments. All of the relevant information is stored into instance variables of the handler.

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 adherance 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, specifing 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 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.

Standard Module Bastion#

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 class instance 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, would be a subclass of BastionClass; see the code in bastion.py for the details. Overriding the default BastionClass will rarely be required.

Standard Module binhex#

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 empty in which case the output filename is read from the binhex file.

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.

Standard Module uu#

This module encodes and decodes files in uuencode format, allowing arbitrary binary data to be transferred over ascii-only connections. Wherever a file argument is expected, the methods accept a file-like object. For backwards compatibility, a string containing a pathname is also accepted, and the corresponding file will be opened for reading and writing; the pathname ’-’ is understood to mean the standard input or output. However, this interface is deprecated; it’s better for the caller to open the file itself, and be sure that, when required, the mode is ’rb’ or ’wb’ on Windows or DOS.

This code was contributed by Lance Ellinghouse, and modified by Jack Jansen.

The uu module defines the following functions:

encode(in_file  out_file)#

Uuencode file in_file into file out_file. The uuencoded file will have the header specifying name and mode as the defaults for the results of decoding the file. The default defaults are taken from in_file, or ’-’ and 0666 respectively.

decode(in_file)#

This call decodes uuencoded file in_file placing the result on file out_file. If out_file is a pathname the mode is also set. Defaults for out_file and mode are taken from the uuencode header.

Built-in Module binascii#

The binascii module contains a number of methods to convert between binary and various ascii-encoded binary representations. Normally, you will not use these modules directly but use wrapper modules like uu or hexbin in stead, this module solely exists because bit-manipuation 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.

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 handled by reading a little more data and trying again.

Built-in Module __builtin__#

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

Built-in Module cd#

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 cd.open() and creates a parser to parse the data from the CD with cd.createparser(). The object returned by cd.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(min  sec  frame)#

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 omited 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:

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 aoocurred 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 PAUSED 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 (returned by cd.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 manual for CDgetstatus. The value of state is one of the following: cd.ERROR, cd.NODISC, cd.READY, cd.PLAYING, cd.PAUSED, cd.STILL, or cd.CDROM.

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 cd.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(min  sec  frame  play)#

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

playtrack(start  play)#

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

playtrackabs(track  min  sec  frame  play)#

Like play(), except that playing begins at the spcified 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(min  sec  frame)#

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 (returned by cd.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:

cd.audio:
The argument is a string which can be passed unmodified to al.writesamps().

cd.pnum:
The argument is an integer giving the program (track) number.

cd.index:
The argument is an integer giving the index number.

cd.ptime:
The argument is a tuple consisting of the program time in minutes, seconds, and frames.

cd.atime:
The argument is a tuple consisting of the absolute time in minutes, seconds, and frames.

cd.catalog:
The argument is a string of 13 characters, giving the catalog number of the CD.

cd.ident:
The argument is a string of 12 characters, giving the ISRC identification number of the recording. The string consists of two characters country code, three characters owner code, two characters giving the year, and five characters giving a serial number.

cd.control:
The argument is an integer giving the control bits from the CD subcode data.

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.

Standard Module cgi#

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 <ISINPUT> 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 (cgi.py) 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!"

(It may not be fully legal HTML according to the letter of the standard, but any browser will understand it.)

Using the cgi module#

Begin by writing import cgi. Don’t 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 define 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 accessed as if it were a Python dictionary. 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"):
    if form["name"].value != "" and form["addr"].value != "":
        form_ok = 1
if not form_ok:
    print "<H1>Error</H1>"
    print "Please fill in the name and addr fields."
    return
...further form processing here...

Here the fields, accessed through form[key], are themselves instances of FieldStorage (or MiniFieldStorage, depending on the form encoding).

If the submitted form data contains more than one field with the same name, the object retrieved by form[key] is not a (Mini)FieldStorage instance but a list of such instances. If you expect this possibility (i.e., when your HTML form comtains 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:

username = form["username"]
if type(username) is type([]):
    # Multiple username fields specified
    usernames = ""
    for item in username:
        if usernames:
            # Next item -- insert comma
            usernames = usernames + "," + item.value
        else:
            # First item -- don't insert comma
            usernames = item.value
else:
    # Single username field specified
    usernames = username.value

If a field represents an uploaded file, the value attribute 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 leasure 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 multipart/* encoding). When this occurs, the item will be a dictionary-like FieldStorage item. This can be determined by testing its type attribute, which should have the value multipart/form-data (or perhaps another string beginning with multipart/ It 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 application/x-www-form-urlencoded), 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 single value form content as dictionary; assumes each field name occurs in the form only once.

FormContentDict multiple value form content as 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 application/x-www-form-urlencoded).

parse_multipart(fp  pdict)#

parse input of type multipart/form-data (for file uploads). Arguments are fp for the input file and pdict for the dictionary containing other parameters of 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 content-type is the raw, unparsed contents of the content-type header.

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

parse_header(string)#

parse a header like Content-type into a main content-type 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 755 (use chmod 755 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 644 for readable and 666 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 ($PATH) or the Python module search path ($PYTHONPATH) 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 try-except!)

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

3. Assign sys.stderr to sys.stdout

4. Wrap all remaining code in a try-except 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 – $PATH 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.

Built-in Module cmath#

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

Standard Module code#

The code module defines operations pertaining to Python code objects.

The code module defines the following functions:

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.

Arguments: 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".

Return a code object (the same as compile(source, filename, symbol)) if the command is complete and valid; return None if the command is incomplete; raise SyntaxError if the command is a syntax error.

Standard Module 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 is only usable on systems which support popen() (currently Unix).

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

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'

Standard Module copy#

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.

Python’s deepcopy() operation avoids these problems by:

• keeping a table 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, nor stack trace, stack frame, nor file, socket, window, nor array, nor 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.

Built-in Module crypt#

This module implements an interface to the crypt(3) 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. salt is a 2-character string which will be used to select one of 4096 variations of DES. The characters in salt must be either ., /, or an alphanumeric character. Returns the hashed password as a string, which will be composed of characters from the same alphabet as the salt.

The module and documentation were written by Steve Majewski.

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:

md5
— RSA’s MD5 message digest algorithm.

mpz
— Interface to the GNU MP library for arbitrary precision arithmetic.

rotor
— Enigma-like encryption and decryption.

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://www.magnet.com/ãmk/python/pct.html or send email to amk@magnet.com for more information.

Built-in Module ctb#

This module provides a partial interface to the Macintosh Communications Toolbox. Currently, only Connection Manager tools are supported. It may not be available in all Mac Python versions.

error#

The exception raised on errors.

cmData#

Flags for the channel argument of the Read and Write methods.

cmFlagsEOM#

End-of-message flag for Read and Write.

choose*#

Values returned by Choose.

cmStatus*#

Bits in the status as returned by Status.

available()#

Return 1 if the communication toolbox is available, zero otherwise.

CMNew(name  sizes)#

Create a connection object using the connection tool named name. sizes is a 6-tuple given buffer sizes for data in, data out, control in, control out, attention in and attention out. Alternatively, passing None will result in default buffer sizes.

connection object#

For all connection methods that take a timeout argument, a value of -1 is indefinite, meaning that the command runs to completion.

callback#

If this member is set to a value other than None it should point to a function accepting a single argument (the connection object). This will make all connection object methods work asynchronously, with the callback routine being called upon completion.

Note: for reasons beyond my understanding the callback routine is currently never called. You are advised against using asynchronous calls for the time being.

Open(timeout)#

Open an outgoing connection, waiting at most timeout seconds for the connection to be established.

Listen(timeout)#

Wait for an incoming connection. Stop waiting after timeout seconds. This call is only meaningful to some tools.

accept(yesno)#

Accept (when yesno is non-zero) or reject an incoming call after Listen returned.

Close(timeout  now)#

Close a connection. When now is zero, the close is orderly (i.e. outstanding output is flushed, etc.) with a timeout of timeout seconds. When now is non-zero the close is immediate, discarding output.

Read(len  chan  timeout)#

Read len bytes, or until timeout seconds have passed, from the channel chan (which is one of cmData, cmCntl or cmAttn). Return a 2-tuple: the data read and the end-of-message flag.

Write(buf  chan  timeout  eom)#

Write buf to channel chan, aborting after timeout seconds. When eom has the value cmFlagsEOM an end-of-message indicator will be written after the data (if this concept has a meaning for this communication tool). The method returns the number of bytes written.

Status()#

Return connection status as the 2-tuple (sizes, flags). sizes is a 6-tuple giving the actual buffer sizes used (see CMNew), flags is a set of bits describing the state of the connection.

GetConfig()#

Return the configuration string of the communication tool. These configuration strings are tool-dependent, but usually easily parsed and modified.

SetConfig(str)#

Set the configuration string for the tool. The strings are parsed left-to-right, with later values taking precedence. This means individual configuration parameters can be modified by simply appending something like ’baud 4800’ to the end of the string returned by GetConfig and passing that to this method. The method returns the number of characters actually parsed by the tool before it encountered an error (or completed successfully).

Choose()#

Present the user with a dialog to choose a communication tool and configure it. If there is an outstanding connection some choices (like selecting a different tool) may cause the connection to be aborted. The return value (one of the choose* constants) will indicate this.

Idle()#

Give the tool a chance to use the processor. You should call this method regularly.

Abort()#

Abort an outstanding asynchronous Open or Listen.

Reset()#

Reset a connection. Exact meaning depends on the tool.

Break(length)#

Send a break. Whether this means anything, what it means and interpretation of the length parameter depend on the tool in use.

Built-in Module dbm#

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.

See also the gdbm module, which provides a similar interface using the GNU GDBM library.

The module defines the following constant and functions:

exception error#

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

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

The optional flag argument can be ’r’ (to open an existing database for reading only — default), ’w’ (to open an existing database for reading and writing), ’c’ (which creates the database if it doesn’t exist), or ’n’ (which always creates a new empty database).

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.

Standard Module dis#

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:

• the current instruction, indicated as -->,

• a labelled instruction, indicated with >>,

• the address of the instruction,

• the operation code name,

• operation parameters, and

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

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_NEG #

Implements TOS = -TOS.

UNARY_NOT #

Implements TOS = not TOS.

UNARY_CONVERT #

Implements TOS = ‘TOS‘.

UNARY_INVERT #

Implements TOS = T̃OS.

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 and TOS.

BINARY_XOR #

Implements TOS = TOS1  ̂TOS.

BINARY_OR #

Implements TOS = TOS1 or 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. There is one such instruction for each item in the print statement.

PRINT_NEWLINE #

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

BREAK_LOOP #

Terminates a loop due to a break 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.

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 finally-block. 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_TUPLE count#

Unpacks TOS into count individual values, which are put onto the stack right-to-left.

UNPACK_LIST count#

Unpacks TOS into count individual values.

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 an 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 name space is not affect: for a proper import statement, a subsequent STORE_FAST instruction modifies the name space.

IMPORT_FROM namei#

Imports the attribute co_names[namei]. The module to import from is found in TOS and left there.

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_LINE_NO 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 1 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. If argc is three, creates TOS3[TOS2:TOS1:TOS]. Otherwise, expects three arguments.

Standard Module errno#

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. Of the following list, symbols that are not used on the current platform are not defined by the module.

The module also defines the dictionary variable errorcode which maps numeric error codes back to their symbol names, so that e.g. errno.errorcode[errno.EPERM] == ’EPERM’. To translate a numeric error code to an error message, use os.strerror().

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#

Exceptions can be class objects or string objects. While traditionally, most exceptions have been string objects, in Python 1.5, all standard exceptions have been converted to class objects, and users are encouraged to the the same. The source code for those exceptions is present in the standard library module exceptions; this module never needs to be imported explicitly.

For backward compatibility, when Python is invoked with the -X option, the standard exceptions are strings. This may be needed to run some code that breaks because of the different semantics of class based exceptions. The -X option will become obsolete in future Python versions, so the recommended solution is to fix the code.

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 try statement with an except 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 raise statement. For string exceptions, the associated value itself will be stored in the variable named as the second argument of the except clause (if any). For class exceptions derived from the root class Exception, that variable receives the exception instance, and the associated value is present as the exception instance’s args attribute; this is a tuple even if the second argument to raise was not (then it is a singleton tuple).

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. When string-based standard exceptions are used, they are tuples containing the directly derived classes.

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

exception StandardError#

The base class for built-in exceptions. All built-in exceptions are derived from this class, which is itself 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 thise exceptions that are raised when a key or index used on a mapping or sequence is invalid: IndexError, KeyError.

The following exceptions are the exceptions that are actually raised. They are class objects, except when the -X option is used to revert back to string-based standard exceptions.

exception AssertionError#

Raised when an assert 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.) No associated value.

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 WANT_SIGFPE_HANDLER symbol is defined in the config.h file.

exception IOError#

Raised when an I/O operation (such as a print 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”.

When class exceptions are used, and this exception is instantiated as IOError(errno, strerror), the instance has two additional attributes errno and strerror set to the error code and the error message, respectively. These attributes default to None.

exception ImportError#

Raised when an import 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 ). 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. No associated value.

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 malloc() 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 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 import statement, in an exec 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 exit() 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.

When class exceptions are used, the instance has an attribute code which is set to the proposed exit status or error message (defaulting to None).

A call to sys.exit() is translated into an exception so that clean-up handlers (finally clauses of try 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 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 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.

Built-in Module fcntl#

This module performs file control and I/O control on file descriptors. It is an interface to the fcntl() and ioctl() 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 it is 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 real fcntl() 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 real fcntl() call. The return value after a successful call is the contents of the buffer, converted to a string object. In case the fcntl() fails, an IOError will be 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 fcntl.)

lockf(fd  code  )#

This is a wrapper around the F_SETLK and F_SETLKW 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

file = open(...)
rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)

lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
rv = 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 lockadata variable is system dependent – therefore using the flock() call may be better.

Built-in Module fl#

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 fl_addto_form and fl_end_form, and the equivalent of fl_bgn_form 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 foreground() and to the FORMS routine fl_init().

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 FL.EVENT.

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

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 FL.EVENT 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 fl_color, fl_mapcolor and fl_getmcolor.

Form Objects#

Form objects (returned by fl.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_… functions 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:

Standard Module FL#

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 *

Standard Module flp#

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!

Built-in Module fm#

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 fminit(). 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 fmenumerate().

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 the string when drawn in this font. Calls fmgetstrwidth(fh, string).

Standard Module fnmatch#

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:

• matches everything

• matches any single character

• matches any character in seq

• matches any character not in seq

Note that the filename separator (’/’ on Unix) is not special to this module. See module glob for pathname expansion (glob uses fnmatch to match filename segments).

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 comparision is performed. If you require a case-sensitive comparision regardless of whether that’s standard for your operating system, use fnmatchcase() instead.

fnmatchcase()#

Test whether filename matches pattern, returning true or false; the comparision is case-sensitive.

translate(pattern)#

Translate a shell pattern into a corresponding regular expression, returning a string describing the pattern. It does not compile the expression. Version note: in Python 1.4 and earlier, this function translated to regex (Emacs style) regular expressions; in 1.5 and later, it translates to re (Perl style) regular expressions.

Standard Module formatter#

This module supports two interface definitions, each with mulitple 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 whitespaces. Whitespace from preceeding 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 AS_IS 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 AS_IS 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 AS_IS 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 AS_IS 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 AS_IS 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.

NullFormatter()#

A formatter which does nothing. If writer is omitted, a NullWriter instance is created. No methods of the writer are called by NullWriter instances. Implementations should inherit from this class if implementing a writer interface but don’t need to inherit any implementation.

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 AS_IS 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 equivelent. The blankline value will be an integer.

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.

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.

AbstractWriter()#

A writer which can be used in debugging formatters, but not much else. Each method simply accounces itself by printing its name and arguments on standard output.

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.

Standard Module ftplib#

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

The module defines the following items:

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.

FTP Objects#

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 LOGNAME or USER 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.

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.

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.

storlines(command  file)#

Store a file in ASCII transfer mode. command should be an appropriate STOR command (see storbinary()). Lines are read until EOF from the open file object file using its readline() method to privide the data to be stored.

nlst(argument)#

Return a list of files as returned by the NLST command. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the NLST command.

dir(argument)#

Return a directory listing as returned by the LIST command, as a list of lines. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the LIST command. If the last argument is a function, it is used as a callback function as for retrlines().

rename(fromname  toname)#

Rename file fromname on the server to toname.

cwd(pathname)#

Set the current directory on the server.

mkd(pathname)#

Create a new directory on the server.

pwd()#

Return the pathname of the current directory on the server.

quit()#

Send a QUIT command to the server and close the connection. This is the “polite” way to close a connection, but it may raise an exception of the server reponds with an error to the QUIT command.

close()#

Close the connection unilaterally. This should not be applied to an already closed connection (e.g. after a successful call to quit().

Built-in Functions#

The Python interpreter has a number of functions built into it that are always available. They are listed here in alphabetical order.

__import__(name)#

This function is invoked by the import statement. It mainly exists so that you can replace it with another function that has a compatible interface, in order to change the semantics of the import statement. For examples of why and how you would do this, see the standard library modules ni, ihooks and rexec. See also the built-in module imp, which defines some useful operations out of which you can build your own __import__() function.

For example, the statement import spam results in the following call: __import__(’spam’, globals(), locals(), []); the statement from spam.ham import eggs results in __import__(’spam.ham’, globals(), locals(), [’eggs’]). Note that even though locals() and [’eggs’] are passed in as arguments, the __import__() function does not set the local variable named eggs; this is done by subsequent code that is generated for the import statement. (In fact, the standard implementation does not use its locals argument at all, and uses its globals only to determine the package context of the import statement.)

When the name variable is of the form package.module, normally, the top-level package (the name up till the first dot) is returned, not the module named by name. However, when a non-empty fromlist argument is given, the module named by name is returned. This is done for compatibility with the bytecode generated for the different kinds of import statement; when using import spam.ham.eggs, the top-level package spam must be placed in the importing namespace, but when using from spam.ham import eggs, the spam.ham subpackage must be used to find the eggs variable.

abs(x)#

Return the absolute value of a number. The argument may be a plain or long integer or a floating point number. If the argument is a complex number, its magnitude is returned.

apply(function  args)#

The function argument must be a callable object (a user-defined or built-in function or method, or a class object) and the args argument must be a tuple. The function is called with args as argument list; the number of arguments is the the length of the tuple. (This is different from just calling func(args), since in that case there is always exactly one argument.) If the optional keywords argument is present, it must be a dictionary whose keys are strings. It specifies keyword arguments to be added to the end of the the argument list.

callable(object)#

Return true if the object argument appears callable, false if not. If this returns true, it is still possible that a call fails, but if it is false, calling object will never succeed. Note that classes are callable (calling a class returns a new instance); class instances are callable if they have an attribute __call__.

chr(i)#

Return a string of one character whose ASCII code is the integer i, e.g., chr(97) returns the string ’a’. This is the inverse of ord(). The argument must be in the range [0..255], inclusive.

cmp(x  y)#

Compare the two objects x and y and return an integer according to the outcome. The return value is negative if x<y, zero if x==y and strictly positive if x>y.

coerce(x  y)#

Return a tuple consisting of the two numeric arguments converted to a common type, using the same rules as used by arithmetic operations.

compile(string  filename  kind)#

Compile the string into a code object. Code objects can be executed by an exec statement or evaluated by a call to eval(). The filename argument should give the file from which the code was read; pass e.g. ’<string>’ if it wasn’t read from a file. The kind argument specifies what kind of code must be compiled; it can be ’exec’ if string consists of a sequence of statements, ’eval’ if it consists of a single expression, or ’single’ if it consists of a single interactive statement (in the latter case, expression statements that evaluate to something else than None will printed).

complex(real)#

Create a complex number with the value real + *imag**j. Each argument may be any numeric type (including complex). If imag is omitted, it defaults to zero and the function serves as a numeric conversion function like int, long and float.

delattr(object  name)#

This is a relative of setattr. The arguments are an object and a string. The string must be the name of one of the object’s attributes. The function deletes the named attribute, provided the object allows it. For example, delattr(x, ’foobar’) is equivalent to del x.foobar.

dir()#

Without arguments, return the list of names in the current local symbol table. With an argument, attempts to return a list of valid attribute for that object. This information is gleaned from the object’s __dict__, __methods__ and __members__ attributes, if defined. The list is not necessarily complete; e.g., for classes, attributes defined in base classes are not included, and for class instances, methods are not included. The resulting list is sorted alphabetically. For example:

>>> import sys
>>> dir()
['sys']
>>> dir(sys)
['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
>>> 

divmod(a  b)#

Take two numbers as arguments and return a pair of numbers consisting of their quotient and remainder when using long division. With mixed operand types, the rules for binary arithmetic operators apply. For plain and long integers, the result is the same as (a/b, a%b). For floating point numbers the result is the same as (math.floor(a/b), a%b).

eval(expression)#

The arguments are a string and two optional dictionaries. The expression argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the globals and locals dictionaries as global and local name space. If the locals dictionary is omitted it defaults to the globals dictionary. If both dictionaries are omitted, the expression is executed in the environment where eval is called. The return value is the result of the evaluated expression. Syntax errors are reported as exceptions. Example:

>>> x = 1
>>> print eval('x+1')
2
>>> 

This function can also be used to execute arbitrary code objects (e.g. created by compile()). In this case pass a code object instead of a string. The code object must have been compiled passing ’eval’ to the kind argument.

Hints: dynamic execution of statements is supported by the exec statement. Execution of statements from a file is supported by the execfile() function. The globals() and locals() functions returns the current global and local dictionary, respectively, which may be useful to pass around for use by eval() or execfile().

execfile(file)#

This function is similar to the exec statement, but parses a file instead of a string. It is different from the import statement in that it does not use the module administration — it reads the file unconditionally and does not create a new module.¹

The arguments are a file name and two optional dictionaries. The file is parsed and evaluated as a sequence of Python statements (similarly to a module) using the globals and locals dictionaries as global and local name space. If the locals dictionary is omitted it defaults to the globals dictionary. If both dictionaries are omitted, the expression is executed in the environment where execfile() is called. The return value is None.

filter(function  list)#

Construct a list from those elements of list for which function returns true. If list is a string or a tuple, the result also has that type; otherwise it is always a list. If function is None, the identity function is assumed, i.e. all elements of list that are false (zero or empty) are removed.

float(x)#

Convert a string or a number to floating point. If the argument is a string, it must contain a possibly singed decimal or floating point number, possibly embedded in whitespace; this behaves identical to string.atof(x). Otherwise, the argument may be a plain or long integer or a floating point number, and a floating point number with the same value (within Python’s floating point precision) is returned.

getattr(object  name)#

The arguments are an object and a string. The string must be the name of one of the object’s attributes. The result is the value of that attribute. For example, getattr(x, ’foobar’) is equivalent to x.foobar.

globals()#

Return a dictionary representing the current global symbol table. This is always the dictionary of the current module (inside a function or method, this is the module where it is defined, not the module from which it is called).

hasattr(object  name)#

The arguments are an object and a string. The result is 1 if the string is the name of one of the object’s attributes, 0 if not. (This is implemented by calling getattr(object, name) and seeing whether it raises an exception or not.)

hash(object)#

Return the hash value of the object (if it has one). Hash values are integers. They are used to quickly compare dictionary keys during a dictionary lookup. Numeric values that compare equal have the same hash value (even if they are of different types, e.g. 1 and 1.0).

hex(x)#

Convert an integer number (of any size) to a hexadecimal string. The result is a valid Python expression. Note: this always yields an unsigned literal, e.g. on a 32-bit machine, hex(-1) yields ’0xffffffff’. When evaluated on a machine with the same word size, this literal is evaluated as -1; at a different word size, it may turn up as a large positive number or raise an OverflowError exception.

id(object)#

Return the ‘identity’ of an object. This is an integer which is guaranteed to be unique and constant for this object during its lifetime. (Two objects whose lifetimes are disjunct may have the same id() value.) (Implementation note: this is the address of the object.)

input()#

Almost equivalent to eval(raw_input(prompt)). Like raw_input(), the prompt argument is optional, and the readline module is used when loaded. The difference is that a long input expression may be broken over multiple lines using the backslash convention.

intern(string)#

Enter string in the table of “interned” strings and return the interned string – which is string itself or a copy. Interning strings is useful to gain a little performance on dictionary lookup – if the keys in a dictionary are interned, and the lookup key is interned, the key comparisons (after hashing) can be done by a pointer compare instead of a string compare. Normally, the names used in Python programs are automatically interned, and the dictionaries used to hold module, class or instance attributes have interned keys. Interned strings are immortal (i.e. never get garbage collected).

int(x)#

Convert a string or number to a plain integer. If the argument is a string, it must contain a possibly singed decimal number representable as a Python integer, possibly embedded in whitespace; this behaves identical to string.atoi(x). Otherwise, the argument may be a plain or long integer or a floating point number. Conversion of floating point numbers to integers is defined by the C semantics; normally the conversion truncates towards zero.²

isinstance(object, class)#

Return true if the object argument is an instance of the class argument, or of a (direct or indirect) subclass thereof. Also return true if class is a type object and object is an object of that type. If object is not a class instance or a object of the given type, the function always returns false. If class is neither a class object nor a type object, a TypeError exception is raised.

issubclass(class1, class2)#

Return true if class1 is a subclass (direct or indirect) of class2. A class is considered a subclass of itself. If either argument is not a class object, a TypeError exception is raised.

len(s)#

Return the length (the number of items) of an object. The argument may be a sequence (string, tuple or list) or a mapping (dictionary).

list(sequence)#

Return a list whose items are the same and in the same order as sequence’s items. If sequence is already a list, a copy is made and returned, similar to sequence[:]. For instance, list(’abc’) returns returns [’a’, ’b’, ’c’] and list( (1, 2, 3) ) returns [1, 2, 3].

locals()#

Return a dictionary representing the current local symbol table. Inside a function, modifying this dictionary does not always have the desired effect.

long(x)#

Convert a string or number to a long integer. If the argument is a string, it must contain a possibly singed decimal number of arbitrary size, possibly embedded in whitespace; this behaves identical to string.atol(x). Otherwise, the argument may be a plain or long integer or a floating point number, and a long integer with the same value is returned. Conversion of floating point numbers to integers is defined by the C semantics; see the description of int().

map(function  list  …)#

Apply function to every item of list and return a list of the results. If additional list arguments are passed, function must take that many arguments and is applied to the items of all lists in parallel; if a list is shorter than another it is assumed to be extended with None items. If function is None, the identity function is assumed; if there are multiple list arguments, map returns a list consisting of tuples containing the corresponding items from all lists (i.e. a kind of transpose operation). The list arguments may be any kind of sequence; the result is always a list.

max(s)#

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

min(s)#

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

oct(x)#

Convert an integer number (of any size) to an octal string. The result is a valid Python expression. Note: this always yields an unsigned literal, e.g. on a 32-bit machine, oct(-1) yields ’037777777777’. When evaluated on a machine with the same word size, this literal is evaluated as -1; at a different word size, it may turn up as a large positive number or raise an OverflowError exception.

open(filename)#

Return a new file object (described earlier under Built-in Types). The first two arguments are the same as for stdio’s fopen(): filename is the file name to be opened, mode indicates how the file is to be opened: ’r’ for reading, ’w’ for writing (truncating an existing file), and ’a’ opens it for appending (which on some Unix systems means that all writes append to the end of the file, regardless of the current seek position). Modes ’r+’, ’w+’ and ’a+’ open the file for updating, provided the underlying stdio library understands this. On systems that differentiate between binary and text files, ’b’ appended to the mode opens the file in binary mode. If the file cannot be opened, IOError is raised. If mode is omitted, it defaults to ’r’. The optional bufsize argument specifies the file’s desired buffer size: 0 means unbuffered, 1 means line buffered, any other positive value means use a buffer of (approximately) that size. A negative bufsize means to use the system default, which is usually line buffered for for tty devices and fully buffered for other files. ³

ord(c)#

Return the ASCII value of a string of one character. E.g., ord(’a’) returns the integer 97. This is the inverse of chr().

pow(x  y)#

Return x to the power y; if z is present, return x to the power y, modulo z (computed more efficiently than pow(x, y) % z). The arguments must have numeric types. With mixed operand types, the rules for binary arithmetic operators apply. The effective operand type is also the type of the result; if the result is not expressible in this type, the function raises an exception; e.g., pow(2, -1) or pow(2, 35000) is not allowed.

range( stop)#

This is a versatile function to create lists containing arithmetic progressions. It is most often used in for loops. The arguments must be plain integers. If the step argument is omitted, it defaults to 1. If the start argument is omitted, it defaults to 0. The full form returns a list of plain integers [start, start+step, start+ 2 *step, …]. If step is positive, the last element is the largest start+i*step less than stop; if step is negative, the last element is the largest start+i*step greater than stop. step must not be zero (or else an exception is raised). Example:

>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> range(1, 11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> range(0, 30, 5)
[0, 5, 10, 15, 20, 25]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(0, -10, -1)
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> range(0)
[]
>>> range(1, 0)
[]
>>> 

raw_input()#

If the prompt argument is present, it is written to standard output without a trailing newline. The function then reads a line from input, converts it to a string (stripping a trailing newline), and returns that. When EOF is read, EOFError is raised. Example:

>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"
>>> 

If the readline module was loaded, then raw_input() will use it to provide elaborate line editing and history features.

reduce(function  list)#

Apply the binary function to the items of list so as to reduce the list to a single value. E.g., reduce(lambda x, y: x*y, list, 1) returns the product of the elements of list. The optional initializer can be thought of as being prepended to list so as to allow reduction of an empty list. The list arguments may be any kind of sequence.

reload(module)#

Re-parse and re-initialize an already imported module. The argument must be a module object, so it must have been successfully imported before. This is useful if you have edited the module source file using an external editor and want to try out the new version without leaving the Python interpreter. The return value is the module object (i.e. the same as the module argument).

There are a number of caveats:

If a module is syntactically correct but its initialization fails, the first import statement for it does not bind its name locally, but does store a (partially initialized) module object in sys.modules. To reload the module you must first import it again (this will bind the name to the partially initialized module object) before you can reload() it.

When a module is reloaded, its dictionary (containing the module’s global variables) is retained. Redefinitions of names will override the old definitions, so this is generally not a problem. If the new version of a module does not define a name that was defined by the old version, the old definition remains. This feature can be used to the module’s advantage if it maintains a global table or cache of objects — with a try statement it can test for the table’s presence and skip its initialization if desired.

It is legal though generally not very useful to reload built-in or dynamically loaded modules, except for sys, __main__ and __builtin__. In certain cases, however, extension modules are not designed to be initialized more than once, and may fail in arbitrary ways when reloaded.

If a module imports objects from another module using from … import …, calling reload() for the other module does not redefine the objects imported from it — one way around this is to re-execute the from statement, another is to use import and qualified names (module.name) instead.

If a module instantiates instances of a class, reloading the module that defines the class does not affect the method definitions of the instances — they continue to use the old class definition. The same is true for derived classes.

repr(object)#

Return a string containing a printable representation of an object. This is the same value yielded by conversions (reverse quotes). It is sometimes useful to be able to access this operation as an ordinary function. For many types, this function makes an attempt to return a string that would yield an object with the same value when passed to eval().

round(x  n)#

Return the floating point value x rounded to n digits after the decimal point. If n is omitted, it defaults to zero. The result is a floating point number. Values are rounded to the closest multiple of 10 to the power minus n; if two multiples are equally close, rounding is done away from 0 (so e.g. round(0.5) is 1.0 and round(-0.5) is -1.0).

setattr(object  name  value)#

This is the counterpart of getattr. The arguments are an object, a string and an arbitrary value. The string must be the name of one of the object’s attributes. The function assigns the value to the attribute, provided the object allows it. For example, setattr(x, ’foobar’, 123) is equivalent to x.foobar = 123.

slice( stop)#

Return a slice object representing the set of indices specified by range(start, stop, step). The start and step arguments default to None. Slice objects have read-only data attributes start, stop and step which merely return the argument values (or their default). They have no other explicit functionality; however they are used by Numerical Python and other third party extensions. Slice objects are also generated when extended indexing syntax is used, e.g. for a[start:stop:step] or a[start:stop, i].

str(object)#

Return a string containing a nicely printable representation of an object. For strings, this returns the string itself. The difference with repr(object) is that str(object) does not always attempt to return a string that is acceptable to eval(); its goal is to return a printable string.

tuple(sequence)#

Return a tuple whose items are the same and in the same order as sequence’s items. If sequence is already a tuple, it is returned unchanged. For instance, tuple(’abc’) returns returns (’a’, ’b’, ’c’) and tuple([1, 2, 3]) returns (1, 2, 3).

type(object)#

Return the type of an object. The return value is a type object. The standard module types defines names for all built-in types.

For instance:

>>> import types
>>> if type(x) == types.StringType: print "It's a string"

vars()#

Without arguments, return a dictionary corresponding to the current local symbol table. With a module, class or class instance object as argument (or anything else that has a __dict__ attribute), returns a dictionary corresponding to the object’s symbol table. The returned dictionary should not be modified: the effects on the corresponding symbol table are undefined. ⁴

xrange( stop)#

This function is very similar to range(), but returns an “xrange object” instead of a list. This is an opaque sequence type which yields the same values as the corresponding list, without actually storing them all simultaneously. The advantage of xrange() over range() is minimal (since xrange() still has to create the values when asked for them) except when a very large range is used on a memory-starved machine (e.g. MS-DOS) or when all of the range’s elements are never used (e.g. when the loop is usually terminated with break).

Built-in Module gdbm#

This module is quite similar to the dbm module, but uses gdbm instead to provide some additional functionality. Please note that the file formats created by gdbm and dbm are incompatible.

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

The module defines the following constant and functions:

exception error#

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

open(filename  )#

Open a gdbm database and return a gdbm object. The filename argument is the name of the database file.

The optional flag argument can be ’r’ (to open an existing database for reading only — default), ’w’ (to open an existing database for reading and writing), ’c’ (which creates the database if it doesn’t exist), or ’n’ (which always creates a new empty database).

Appending f to the flag opens the database in fast mode; altered data will not automatically be written to the disk after every change. This results in faster writes to the database, but may result in an inconsistent database if the program crashes while the database is still open. Use the sync() method to force any unwritten data to be written to the disk.

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.

In addition to the dictionary-like methods, gdbm objects have the following methods:

firstkey()#

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

nextkey(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.firstkey()
while k!=None:
    print k
    k=db.nextkey(k)

reorganize()#

If you have carried out a lot of deletions and would like to shrink the space used by the gdbm file, this routine will reorganize the database. gdbm will not shorten the length of a database file except by using this reorganization; otherwise, deleted file space will be kept and reused as new (key,value) pairs are added.

sync()#

When the database has been opened in fast mode, this method forces any unwritten data to be written to the disk.

Standard Module getopt#

This module helps scripts to parse the command line arguments in sys.argv. It supports the same conventions as the Unix getopt() function (including the special meanings of arguments of the form ‘-’ and ‘--’).

Long options similar to those supported by GNU software may be used as well via an optional third argument. It defines the function getopt.getopt(args, options [, long_options]) and the exception getopt.error.

The first argument to getopt() is the argument list passed to the script with its first element chopped off (i.e., sys.argv[1:]). The second argument is the string of option letters that the script wants to recognize, with options that require an argument followed by a colon (i.e., the same format that Unix getopt() uses). The third option, if specified, is a list of strings with the names of the long options which should be supported. The leading ’--’ characters should not be included in the option name. Options which require an argument should be followed by an equal sign (’=’). The return value consists of two elements: the first is a list of option-and-value pairs; the second is the list of program arguments left after the option list was stripped (this is a trailing slice of the first argument). Each option-and-value pair returned has the option as its first element, prefixed with a hyphen (e.g., ’-x’), and the option argument as its second element, or an empty string if the option has no argument. The options occur in the list in the same order in which they were found, thus allowing multiple occurrences. Long and short options may be mixed.

An example using only Unix style options:

>>> import getopt, string
>>> args = string.split('-a -b -cfoo -d bar a1 a2')
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
>>> 

Using long option names is equally easy:

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = string.split(s)
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']
>>> 

The exception getopt.error is raised when an unrecognized option is found in the argument list or when an option requiring an argument is given none. The argument to the exception is a string indicating the cause of the error. For long options, an argument given to an option which does not require one will also cause this exception to be raised.

Built-in Module gl#

This module provides access to the Silicon Graphics Graphics Library. It is available only on Silicon Graphics machines.

Warning: Some illegal calls to the GL library cause the Python interpreter to dump core. In particular, the use of most GL calls is unsafe before the first window is opened.

The module is too large to document here in its entirety, but the following should help you to get started. The parameter conventions for the C functions are translated to Python as follows:

• All (short, long, unsigned) int values are represented by Python integers.

• All float and double values are represented by Python floating point numbers. In most cases, Python integers are also allowed.

• All arrays are represented by one-dimensional Python lists. In most cases, tuples are also allowed.

• All string and character arguments are represented by Python strings, for instance, winopen(’Hi There!’) and rotate(900, ’z’).

• All (short, long, unsigned) integer arguments or return values that are only used to specify the length of an array argument are omitted. For example, the C call

  lmdef(deftype, index, np, props)
  

  is translated to Python as

  lmdef(deftype, index, props)
  

• Output arguments are omitted from the argument list; they are transmitted as function return values instead. If more than one value must be returned, the return value is a tuple. If the C function has both a regular return value (that is not omitted because of the previous rule) and an output argument, the return value comes first in the tuple. Examples: the C call

  getmcolor(i, &red, &green, &blue)
  

  is translated to Python as

  red, green, blue = getmcolor(i)
  

The following functions are non-standard or have special argument conventions:

varray(argument)#

Equivalent to but faster than a number of v3d() calls. The argument is a list (or tuple) of points. Each point must be a tuple of coordinates (x, y, z) or (x, y). The points may be 2- or 3-dimensional but must all have the same dimension. Float and int values may be mixed however. The points are always converted to 3D double precision points by assuming z = 0.0 if necessary (as indicated in the man page), and for each point v3d() is called.

nvarray()#

Equivalent to but faster than a number of n3f and v3f calls. The argument is an array (list or tuple) of pairs of normals and points. Each pair is a tuple of a point and a normal for that point. Each point or normal must be a tuple of coordinates (x, y, z). Three coordinates must be given. Float and int values may be mixed. For each pair, n3f() is called for the normal, and then v3f() is called for the point.

vnarray()#

Similar to nvarray() but the pairs have the point first and the normal second.

nurbssurface(s_k  t_k  ctl  s_ord  t_ord  type)#

Defines a nurbs surface. The dimensions of ctl[][] are computed as follows: [len(s_k) - s_ord], [len(t_k) - t_ord].

nurbscurve(knots  ctlpoints  order  type)#

Defines a nurbs curve. The length of ctlpoints is len(knots) - order.

pwlcurve(points  type)#

Defines a piecewise-linear curve. points is a list of points. type must be N_ST.

pick(n)#

The only argument to these functions specifies the desired size of the pick or select buffer.

endpick()#

These functions have no arguments. They return a list of integers representing the used part of the pick/select buffer. No method is provided to detect buffer overrun.

Here is a tiny but complete example GL program in Python:

import gl, GL, time

def main():
    gl.foreground()
    gl.prefposition(500, 900, 500, 900)
    w = gl.winopen('CrissCross')
    gl.ortho2(0.0, 400.0, 0.0, 400.0)
    gl.color(GL.WHITE)
    gl.clear()
    gl.color(GL.RED)
    gl.bgnline()
    gl.v2f(0.0, 0.0)
    gl.v2f(400.0, 400.0)
    gl.endline()
    gl.bgnline()
    gl.v2f(400.0, 0.0)
    gl.v2f(0.0, 400.0)
    gl.endline()
    time.sleep(5)

main()

Standard Modules GL and DEVICE#

These modules define the constants used by the Silicon Graphics Graphics Library that C programmers find in the header files <gl/gl.h> and <gl/device.h>. Read the module source files for details.

Standard Module glob#

The glob module finds all the pathnames matching a specified pattern according to the rules used by the Unix shell. No tilde expansion is done, but *, ?, and character ranges expressed with [] will be correctly matched. This is done by using the os.listdir() and fnmatch.fnmatch() functions in concert, and not by actually invoking a subshell. (For tilde and shell variable expansion, use os.path.expanduser() and os.path.expandvars().)

glob(pathname)#

Returns a possibly-empty list of path names that match pathname, which must be a string containing a path specification. pathname can be either absolute (like /usr/src/Python1.4/Makefile) or relative (like ../../Tools/*.gif), and can contain shell-style wildcards.

For example, consider a directory containing only the following files: 1.gif, 2.txt, and card.gif. glob.glob() will produce the following results. Notice how any leading components of the path are preserved.

>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']

Standard Module gopherlib#

This module provides a minimal implementation of client side of the the Gopher protocol. It is used by the module urllib to handle URLs that use the Gopher protocol.

The module defines the following functions:

send_selector(selector  host)#

Send a selector string to the gopher server at host and port (default 70). Return an open file object from which the returned document can be read.

send_query(selector  query  host)#

Send a selector string and a query string to a gopher server at host and port (default 70). Return an open file object from which the returned document can be read.

Note that the data returned by the Gopher server can be of any type, depending on the first character of the selector string. If the data is text (first character of the selector is 0), lines are terminated by CRLF, and the data is terminated by a line consisting of a single ., and a leading . should be stripped from lines that begin with ... Directory listings (first charactger of the selector is 1) are transferred using the same protocol.

Built-in Module grp#

This module provides access to the Unix group database. It is available on all Unix versions.

Group database entries are reported as 4-tuples containing the following items from the group database (see <grp.h>), in order: gr_name, gr_passwd, gr_gid, gr_mem. The gid is an integer, name and password are strings, and the member list is a list of strings. (Note that most users are not explicitly listed as members of the group they are in according to the password database.) A KeyError exception is raised if the entry asked for cannot be found.

It defines the following items:

getgrgid(gid)#

Return the group database entry for the given numeric group ID.

getgrnam(name)#

Return the group database entry for the given group name.

getgrall()#

Return a list of all available group entries, in arbitrary order.

Built-in Module gzip#

The data compression provided by the zlib module is compatible with that used by the GNU compression program gzip. Accordingly, the gzip module provides the GzipFile class to read and write gzip-format files, automatically compressing or decompressing the data so it looks like an ordinary file object.

GzipFile objects simulate most of the methods of a file object, though it’s not possible to use the seek() and tell() methods to access the file randomly.

open(fileobj)#

Returns a new GzipFile object on top of fileobj, which can be a regular file, a StringIO object, or any object which simulates a file.

The gzip file format includes the original filename of the uncompressed file; when opening a GzipFile object for writing, it can be set by the filename argument. The default value is an empty string.

mode can be either ’r’ or ’w’ depending on whether the file will be read or written. compresslevel is an integer from 1 to 9 controlling the level of compression; 1 is fastest and produces the least compression, and 9 is slowest and produces the most compression. The default value of compresslevel is 9.

Calling a GzipFile object’s close() method does not close fileobj, since you might wish to append more material after the compressed data. This also allows you to pass a StringIO object opened for writing as fileobj, and retrieve the resulting memory buffer using the StringIO object’s getvalue() method.

See also:#

— zlibthe basic data compression module

Standard Module htmllib#

This module defines a class which can serve as a base for parsing text files formatted in the HyperText Mark-up Language (HTML). The class is not directly concerned with I/O — it must be provided with input in string form via a method, and makes calls to methods of a “formatter” object in order to produce output. The HTMLParser class is designed to be used as a base class for other classes in order to add functionality, and allows most of its methods to be extended or overridden. In turn, this class is derived from and extends the SGMLParser class defined in module sgmllib. Two implementations of formatter objects are provided in the formatter module; refer to the documentation for that module for information on the formatter interface.

The following is a summary of the interface defined by sgmllib.SGMLParser:

• The interface to feed data to an instance is through the feed() method, which takes a string argument. This can be called with as little or as much text at a time as desired; p.feed(a); p.feed(b) has the same effect as p.feed(a+b). When the data contains complete HTML tags, these are processed immediately; incomplete elements are saved in a buffer. To force processing of all unprocessed data, call the close() method.

  For example, to parse the entire contents of a file, use:

  parser.feed(open('myfile.html').read())
  parser.close()
  

• The interface to define semantics for HTML tags is very simple: derive a class and define methods called start_tag(), end_tag(), or do_tag(). The parser will call these at appropriate moments: start_tag or do_tag is called when an opening tag of the form <tag ...> is encountered; end_tag is called when a closing tag of the form <tag> is encountered. If an opening tag requires a corresponding closing tag, like <H1> … </H1>, the class should define the start_tag method; if a tag requires no closing tag, like <P>, the class should define the do_tag method.

The module defines a single class:

HTMLParser(formatter)#

This is the basic HTML parser class. It supports all entity names required by the HTML 2.0 specification (RFC 1866). It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.

In addition to tag methods, the HTMLParser class provides some additional methods and instance variables for use within tag methods.

formatter#

This is the formatter instance associated with the parser.

nofill#

Boolean flag which should be true when whitespace should not be collapsed, or false when it should be. In general, this should only be true when character data is to be treated as “preformatted” text, as within a <PRE> element. The default value is false. This affects the operation of handle_data() and save_end().

anchor_bgn(href  name  type)#

This method is called at the start of an anchor region. The arguments correspond to the attributes of the <A> tag with the same names. The default implementation maintains a list of hyperlinks (defined by the href argument) within the document. The list of hyperlinks is available as the data attribute anchorlist.

anchor_end()#

This method is called at the end of an anchor region. The default implementation adds a textual footnote marker using an index into the list of hyperlinks created by anchor_bgn().

handle_image(source  alt)#

This method is called to handle images. The default implementation simply passes the alt value to the handle_data() method.

save_bgn()#

Begins saving character data in a buffer instead of sending it to the formatter object. Retrieve the stored data via save_end() Use of the save_bgn() / save_end() pair may not be nested.

save_end()#

Ends buffering character data and returns all data saved since the preceeding call to save_bgn(). If nofill flag is false, whitespace is collapsed to single spaces. A call to this method without a preceeding call to save_bgn() will raise a TypeError exception.

Standard Module httplib#

This module defines a class which implements the client side of the HTTP protocol. It is normally not used directly — the module urllib uses it to handle URLs that use HTTP.

The module defines one class, HTTP. An HTTP instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form host:port, else the default HTTP port (80) is used. If no host is passed, no connection is made, and the connect method should be used to connect to a server. For example, the following calls all create instances that connect to the server at the same host and port:

>>> h1 = httplib.HTTP('www.cwi.nl')
>>> h2 = httplib.HTTP('www.cwi.nl:80')
>>> h3 = httplib.HTTP('www.cwi.nl', 80)

Once an HTTP instance has been connected to an HTTP server, it should be used as follows:

1. Make exactly one call to the putrequest() method.

2. Make zero or more calls to the putheader() method.

3. Call the endheaders() method (this can be omitted if step 4 makes no calls).

4. Optional calls to the send() method.

5. Call the getreply() method.

6. Call the getfile() method and read the data off the file object that it returns.

HTTP Objects#

HTTP instances have the following methods:

set_debuglevel(level)#

Set the debugging level (the amount of debugging output printed). The default debug level is 0, meaning no debugging output is printed.

connect(host)#

Connect to the server given by host and port. See the intro for the default port. This should be called directly only if the instance was instantiated without passing a host.

send(data)#

Send data to the server. This should be used directly only after the endheaders() method has been called and before getreply() has been called.

putrequest(request  selector)#

This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the request string, the selector string, and the HTTP version (HTTP/1.0).

putheader(header  argument)#

Send an RFC-822 style header to the server. It sends a line to the server consisting of the header, a colon and a space, and the first argument. If more arguments are given, continuation lines are sent, each consisting of a tab and an argument.

endheaders()#

Send a blank line to the server, signalling the end of the headers.

getreply()#

Complete the request by shutting down the sending end of the socket, read the reply from the server, and return a triple (replycode, message, headers). Here replycode is the integer reply code from the request (e.g. 200 if the request was handled properly); message is the message string corresponding to the reply code; and headers is an instance of the class mimetools.Message containing the headers received from the server. See the description of the mimetools module.

getfile()#

Return a file object from which the data returned by the server can be read, using the read(), readline() or readlines() methods.

Example#

Here is an example session:

>>> import httplib
>>> h = httplib.HTTP('www.cwi.nl')
>>> h.putrequest('GET', '/index.html')
>>> h.putheader('Accept', 'text/html')
>>> h.putheader('Accept', 'text/plain')
>>> h.endheaders()
>>> errcode, errmsg, headers = h.getreply()
>>> print errcode # Should be 200
>>> f = h.getfile()
>>> data = f.read() # Get the raw HTML
>>> f.close()
>>> 

Built-in Module imageop#

The imageop module contains some useful operations on images. It operates on images consisting of 8 or 32 bit pixels stored in Python strings. This is the same format as used by gl.lrectwrite and the imgfile module.

The module defines the following variables and functions:

exception error#

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

crop(image  psize  width  height  x0  y0  x1  y1)#

Return the selected part of image, which should by width by height in size and consist of pixels of psize bytes. x0, y0, x1 and y1 are like the lrectread parameters, i.e. the boundary is included in the new image. The new boundaries need not be inside the picture. Pixels that fall outside the old image will have their value set to zero. If x0 is bigger than x1 the new image is mirrored. The same holds for the y coordinates.

scale(image  psize  width  height  newwidth  newheight)#

Return image scaled to size newwidth by newheight. No interpolation is done, scaling is done by simple-minded pixel duplication or removal. Therefore, computer-generated images or dithered images will not look nice after scaling.

tovideo(image  psize  width  height)#

Run a vertical low-pass filter over an image. It does so by computing each destination pixel as the average of two vertically-aligned source pixels. The main use of this routine is to forestall excessive flicker if the image is displayed on a video device that uses interlacing, hence the name.

grey2mono(image  width  height  threshold)#

Convert a 8-bit deep greyscale image to a 1-bit deep image by tresholding all the pixels. The resulting image is tightly packed and is probably only useful as an argument to mono2grey.

dither2mono(image  width  height)#

Convert an 8-bit greyscale image to a 1-bit monochrome image using a (simple-minded) dithering algorithm.

mono2grey(image  width  height  p0  p1)#

Convert a 1-bit monochrome image to an 8 bit greyscale or color image. All pixels that are zero-valued on input get value p0 on output and all one-value input pixels get value p1 on output. To convert a monochrome black-and-white image to greyscale pass the values 0 and 255 respectively.

grey2grey4(image  width  height)#

Convert an 8-bit greyscale image to a 4-bit greyscale image without dithering.

grey2grey2(image  width  height)#

Convert an 8-bit greyscale image to a 2-bit greyscale image without dithering.

dither2grey2(image  width  height)#

Convert an 8-bit greyscale image to a 2-bit greyscale image with dithering. As for dither2mono, the dithering algorithm is currently very simple.

grey42grey(image  width  height)#

Convert a 4-bit greyscale image to an 8-bit greyscale image.

grey22grey(image  width  height)#

Convert a 2-bit greyscale image to an 8-bit greyscale image.

Built-in Module imgfile#

The imgfile module allows python programs to access SGI imglib image files (also known as .rgb files). The module is far from complete, but is provided anyway since the functionality that there is is enough in some cases. Currently, colormap files are not supported.

The module defines the following variables and functions:

exception error#

This exception is raised on all errors, such as unsupported file type, etc.

getsizes(file)#

This function returns a tuple (x, y, z) where x and y are the size of the image in pixels and z is the number of bytes per pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels are currently supported.

read(file)#

This function reads and decodes the image on the specified file, and returns it as a python string. The string has either 1 byte greyscale pixels or 4 byte RGBA pixels. The bottom left pixel is the first in the string. This format is suitable to pass to gl.lrectwrite, for instance.

readscaled(file  x  y  filter)#

This function is identical to read but it returns an image that is scaled to the given x and y sizes. If the filter and blur parameters are omitted scaling is done by simply dropping or duplicating pixels, so the result will be less than perfect, especially for computer-generated images.

Alternatively, you can specify a filter to use to smoothen the image after scaling. The filter forms supported are ’impulse’, ’box’, ’triangle’, ’quadratic’ and ’gaussian’. If a filter is specified blur is an optional parameter specifying the blurriness of the filter. It defaults to 1.0.

readscaled makes no attempt to keep the aspect ratio correct, so that is the users’ responsibility.

ttob(flag)#

This function sets a global flag which defines whether the scan lines of the image are read or written from bottom to top (flag is zero, compatible with SGI GL) or from top to bottom(flag is one, compatible with X). The default is zero.

write(file  data  x  y  z)#

This function writes the RGB or greyscale data in data to image file file. x and y give the size of the image, z is 1 for 1 byte greyscale images or 3 for RGB images (which are stored as 4 byte values of which only the lower three bytes are used). These are the formats returned by gl.lrectread.

Standard Module imghdr#

The imghdr module determines the type of image contained in a file or byte stream.

The imghdr module defines the following function:

what(filename)#

Tests the image data contained in the file named by filename, and returns a string describing the image type. If optional h is provided, the filename is ignored and h is assumed to contain the byte stream to test.

The following image types are recognized, as listed below with the return value from what:

1. SGI ImgLib Files

2. GIF 87a and 89a Files

3. Portable Bitmap Files

4. Portable Graymap Files

5. Portable Pixmap Files

6. TIFF Files

7. Sun Raster Files

8. X Bitmap Files

9. JPEG data in JIFF format

You can extend the list of file types imghdr can recognize by appending to this variable:

tests#

A list of functions performing the individual tests. Each function takes two arguments: the byte-stream and an open file-like object. When what() is called with a byte-stream, the file-like object will be None.

The test function should return a string describing the image type if the test succeeded, or None if it failed.

Example:

>>> import imghdr
>>> imghdr.what('/tmp/bass.gif')
'gif'

Built-in Module imp#

This module provides an interface to the mechanisms used to implement the import statement. It defines the following constants and functions:

get_magic()#

Return the magic string value used to recognize byte-compiled code files (“.pyc files”). (This value may be different for each Python version.)

get_suffixes()#

Return a list of triples, each describing a particular type of module. Each triple has the form (suffix, mode, type), where suffix is a string to be appended to the module name to form the filename to search for, mode is the mode string to pass to the built-in open function to open the file (this can be ’r’ for text files or ’rb’ for binary files), and type is the file type, which has one of the values PY_SOURCE, PY_COMPILED, or C_EXTENSION, defined below.

find_module(name  )#

Try to find the module name on the search path path. If path is a list of directory names, each directory is searched for files with any of the suffixes returned by get_suffixes() above. Invalid names in the list are silently ignored (but all list items must be strings). If path is omitted or None, the list of directory names given by sys.path is searched, but first it searches a few special places: it tries to find a built-in module with the given name (C_BUILTIN), then a frozen module (PY_FROZEN), and on some systems some other places are looked in as well (on the Mac, it looks for a resource (PY_RESOURCE); on Windows, it looks in the registry which may point to a specific file).

If search is successful, the return value is a triple (file, pathname, description) where file is an open file object positioned at the beginning, pathname is the pathname of the file found, and description is a triple as contained in the list returned by get_suffixes describing the kind of module found. If the module does not live in a file, the returned file is None, filename is the empty string, and the description tuple contains empty strings for its suffix and mode; the module type is as indicate in parentheses dabove. If the search is unsuccessful, ImportError is raised. Other exceptions indicate problems with the arguments or environment.

This function does not handle hierarchical module names (names containing dots). In order to find P.M, i.e., submodule M of package P, use find_module() and load_module() to find and load package P, and then use find_module() with the path argument set to P.__path__. When P itself has a dotted name, apply this recipe recursively.

load_module(name, file, filename, description)#

Load a module that was previously found by find_module() (or by an otherwise conducted search yielding compatible results). This function does more than importing the module: if the module was already imported, it is equivalent to a reload()! The name argument indicates the full module name (including the package name, if this is a submodule of a package). The file argument is an open file, and filename is the corresponding file name; these can be None and "", respectively, when the module is not being loaded from a file. The description argument is a tuple as returned by find_module() describing what kind of module must be loaded.

If the load is successful, the return value is the module object; otherwise, an exception (usually ImportError) is raised.

Important: the caller is responsible for closing the file argument, if it was not None, even when an exception is raised. This is best done using a try-finally statement.

new_module(name)#

Return a new empty module object called name. This object is not inserted in sys.modules.

The following constants with integer values, defined in this module, are used to indicate the search result of find_module().

PY_SOURCE#

The module was found as a source file.

PY_COMPILED#

The module was found as a compiled code object file.

C_EXTENSION#

The module was found as dynamically loadable shared library.

PY_RESOURCE#

The module was found as a Macintosh resource. This value can only be returned on a Macintosh.

PKG_DIRECTORY#

The module was found as a package directory.

C_BUILTIN#

The module was found as a built-in module.

PY_FROZEN#

The module was found as a frozen module (see init_frozen).

The following constant and functions are obsolete; their functionality is available through find_module() or load_module(). They are kept around for backward compatibility:

SEARCH_ERROR#

Unused.

init_builtin(name)#

Initialize the built-in module called name and return its module object. If the module was already initialized, it will be initialized again. A few modules cannot be initialized twice — attempting to initialize these again will raise an ImportError exception. If there is no built-in module called name, None is returned.

init_frozen(name)#

Initialize the frozen module called name and return its module object. If the module was already initialized, it will be initialized again. If there is no frozen module called name, None is returned. (Frozen modules are modules written in Python whose compiled byte-code object is incorporated into a custom-built Python interpreter by Python’s freeze utility. See Tools/freeze for now.)

is_builtin(name)#

Return 1 if there is a built-in module called name which can be initialized again. Return -1 if there is a built-in module called name which cannot be initialized again (see init_builtin). Return 0 if there is no built-in module called name.

is_frozen(name)#

Return 1 if there is a frozen module (see init_frozen) called name, 0 if there is no such module.

load_compiled(name  pathname  file)#

Load and initialize a module implemented as a byte-compiled code file and return its module object. If the module was already initialized, it will be initialized again. The name argument is used to create or access a module object. The pathname argument points to the byte-compiled code file. The file argument is the byte-compiled code file, open for reading in binary mode, from the beginning. It must currently be a real file object, not a user-defined class emulating a file.

load_dynamic(name  pathname  )#

Load and initialize a module implemented as a dynamically loadable shared library and return its module object. If the module was already initialized, it will be initialized again. Some modules don’t like that and may raise an exception. The pathname argument must point to the shared library. The name argument is used to construct the name of the initialization function: an external C function called initname() in the shared library is called. The optional file argment is ignored. (Note: using shared libraries is highly system dependent, and not all systems support it.)

load_source(name  pathname  file)#

Load and initialize a module implemented as a Python source file and return its module object. If the module was already initialized, it will be initialized again. The name argument is used to create or access a module object. The pathname argument points to the source file. The file argument is the source file, open for reading as text, from the beginning. It must currently be a real file object, not a user-defined class emulating a file. Note that if a properly matching byte-compiled file (with suffix .pyc) exists, it will be used instead of parsing the given source file.

Examples#

The following function emulates what was the standard import statement up to Python 1.4 (i.e., no hierarchical module names). (This implementation wouldn’t work in that version, since imp.find_module() has been extended and imp.load_module() has been added in 1.4.)

import imp import sys

def __import__(name, globals=None, locals=None, fromlist=None):
    # Fast path: see if the module has already been imported.
    try:
        return sys.modules[name]
    except KeyError:
        pass

    # If any of the following calls raises an exception,
    # there's a problem we can't handle -- let the caller handle it.

    fp, pathname, description = imp.find_module(name)
    
    try:
        return imp.load_module(name, fp, pathname, description)
    finally:
        # Since we may exit via an exception, close fp explicitly.
        if fp:
            fp.close()

A more complete example that implements hierarchical module names and includes a reload() function can be found in the standard module knee (which is intended as an example only – don’t rely on any part of it being a standard interface).

Introduction#

The “Python library” contains several different kinds of components.

It contains data types that would normally be considered part of the “core” of a language, such as numbers and lists. For these types, the Python language core defines the form of literals and places some constraints on their semantics, but does not fully define the semantics. (On the other hand, the language core does define syntactic properties like the spelling and priorities of operators.)

The library also contains built-in functions and exceptions — objects that can be used by all Python code without the need of an import statement. Some of these are defined by the core language, but many are not essential for the core semantics and are only described here.

The bulk of the library, however, consists of a collection of modules. There are many ways to dissect this collection. Some modules are written in C and built in to the Python interpreter; others are written in Python and imported in source form. Some modules provide interfaces that are highly specific to Python, like printing a stack trace; some provide interfaces that are specific to particular operating systems, like socket I/O; others provide interfaces that are specific to a particular application domain, like the World-Wide Web. Some modules are avaiable in all versions and ports of Python; others are only available when the underlying system supports or requires them; yet others are available only when a particular configuration option was chosen at the time when Python was compiled and installed.

This manual is organized “from the inside out”: it first describes the built-in data types, then the built-in functions and exceptions, and finally the modules, grouped in chapters of related modules. The ordering of the chapters as well as the ordering of the modules within each chapter is roughly from most relevant to least important.

This means that if you start reading this manual from the start, and skip to the next chapter when you get bored, you will get a reasonable overview of the available modules and application areas that are supported by the Python library. Of course, you don’t have to read it like a novel — you can also browse the table of contents (in front of the manual), or look for a specific function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module rand) and read a section or two.

Let the show begin!

Built-in Module jpeg#

The module jpeg provides access to the jpeg compressor and decompressor written by the Independent JPEG Group. JPEG is a (draft?) standard for compressing pictures. For details on jpeg or the Independent JPEG Group software refer to the JPEG standard or the documentation provided with the software.

The jpeg module defines these functions:

compress(data  w  h  b)#

Treat data as a pixmap of width w and height h, with b bytes per pixel. The data is in SGI GL order, so the first pixel is in the lower-left corner. This means that lrectread return data can immediately be passed to compress. Currently only 1 byte and 4 byte pixels are allowed, the former being treated as greyscale and the latter as RGB color. Compress returns a string that contains the compressed picture, in JFIF format.

decompress(data)#

Data is a string containing a picture in JFIF format. It returns a tuple (data, width, height, bytesperpixel). Again, the data is suitable to pass to lrectwrite.

setoption(name  value)#

Set various options. Subsequent compress and decompress calls will use these options. The following options are available:

’forcegray’
Force output to be grayscale, even if input is RGB.

’quality’
Set the quality of the compressed image to a value between 0 and 100 (default is 75). Compress only.

’optimize’
Perform Huffman table optimization. Takes longer, but results in smaller compressed image. Compress only.

’smooth’
Perform inter-block smoothing on uncompressed image. Only useful for low-quality images. Decompress only.

Compress and uncompress raise the error jpeg.error in case of errors.

Standard Module keyword#

This module allows a Python program to determine if a string is a keyword. A single function is provided:

iskeyword(s)#

Return true if s is a Python keyword.

Standard Module locale#

The locale module opens access to the POSIX locale database and functionality. The POSIX locale mechanism allows applications to integrate certain cultural aspects into an applications, without requiring the programmer to know all the specifics of each country where the software is executed.

The locale module is implemented on top of the _locale module, which in turn uses an ANSI C locale implementation if available.

The locale module defines the following functions:

setlocale(category)#

If value is specified, modifies the locale setting for the category. The available categories are listed in the data description below. The value is the name of a locale. An empty string specifies the user’s default settings. If the modification of the locale fails, the exception locale.Error is raised. If successful, the new locale setting is returned.

If no value is specified, the current setting for the category is returned.

setlocale() is not thread safe on most systems. Applications typically start with a call of

import locale
locale.setlocale(locale.LC_ALL,"")

This sets the locale for all categories to the user’s default setting (typically specified in the LANG environment variable). If the locale is not changed thereafter, using multithreading should not cause problems.

localeconv()#

Returns the database of of the local conventions as a dictionary. This dictionary has the following strings as keys:

• decimal_point specifies the decimal point used in floating point number representations for the LC_NUMERIC category.

• grouping is a sequence of numbers specifying at which relative positions the thousands_sep is expected. If the sequence is terminated with locale.CHAR_MAX, no further grouping is performed. If the sequence terminates with a 0, the last group size is repeatedly used.

• thousands_sep is the character used between groups.

• int_curr_symbol specifies the international currency symbol from the LC_MONETARY category.

• currency_symbol is the local currency symbol.

• mon_decimal_point is the decimal point used in monetary values.

• mon_thousands_sep is the separator for grouping of monetary values.

• mon_grouping has the same format as the grouping key; it is used for monetary values.

• positive_sign and negative_sign gives the sign used for positive and negative monetary quantities.

• int_frac_digits and frac_digits specify the number of fractional digits used in the international and local formatting of monetary values.

• p_cs_precedes and n_cs_precedes specifies whether the currency symbol precedes the value for positive or negative values.

• p_sep_by_space and n_sep_by_space specifies whether there is a space between the positive or negative value and the currency symbol.

• p_sign_posn and n_sign_posn indicate how the sign should be placed for positive and negative monetary values.

The possible values for p_sign_posn and n_sign_posn are given below.

• 0 - Currency and value are surrounded by parentheses.

• 1 - The sign should precede the value and currency symbol.

• 2 - The sign should follow the value and currency symbol.

• 3 - The sign should immediately precede the value.

• 4 - The sign should immediately follow the value.

• LC_MAX - nothing is specified in this locale.

strcoll(string1,string2)#

Compares two strings according to the current LC_COLLATE setting. As any other compare function, returns a negative, or a positive value, or 0, depending on whether string1 collates before or after string2 or is equal to it.

strxfrm(string)#

Transforms a string to one that can be used for the builtin function cmp(), and still returns locale-aware results. This function can be used when the same string is compared repeatedly, e.g. when collating a sequence of strings.

format(format,val)#

Formats a number val according to the current LC_NUMERIC setting. The format follows the conventions of the % operator. For floating point values, the decimal point is modified if appropriate. If grouping is true, also takes the grouping into account.

str(float)#

Formats a floating point number using the same format as the built-in function str(float), but takes the decimal point into account.

atof(string)#

Converts a string to a floating point number, following the LC_NUMERIC settings.

atoi(string)#

Converts a string to an integer, following the LC_NUMERIC conventions.

LC_CTYPE#

Locale category for the character type functions. Depending on the settings of this category, the functions of module string dealing with case change their behaviour.

LC_COLLATE#

Locale category for sorting strings. The functions strcoll() and strxfrm() of the locale module are affected.

LC_TIME#

Locale category for the formatting of time. The function time.strftime() follows these conventions.

LC_MONETARY#

Locale category for formatting of monetary values. The available options are available from the localeconv() function.

LC_MESSAGES#

Locale category for message display. Python currently does not support application specific locale-aware messages. Messages displayed by the operating system, like those returned by posix.strerror() might be affected by this category.

LC_NUMERIC#

Locale category for formatting numbers. The functions format(), atoi(), atof() and str() of the locale module are affected by that category. All other numeric formatting operations are not affected.

LC_ALL#

Combination of all locale settings. If this flag is used when the locale is changed, setting the locale for all categories is attempted. If that fails for any category, no category is changed at all. When the locale is retrieved using this flag, a string indicating the setting for all categories is returned. This string can be later used to restore the settings.

CHAR_MAX#

This is a symbolic constant used for different values returned by localeconv().

exception Error#

Exception raised when setlocale() fails.

Example:

>>> import locale
>>> locale.open(locale.LC_ALL,"de") #setting locale to German
>>> locale.strcoll("f\344n","foo")  #comparing a string containing an umlaut 
>>> can.close()

Macintosh Specific Services#

The modules in this chapter are available on the Apple Macintosh only.

Aside from the modules described here there are also interfaces to various MacOS toolboxes, which are currently not extensively described. The toolboxes for which modules exist are: AE (Apple Events), Cm (Component Manager), Ctl (Control Manager), Dlg (Dialog Manager), Evt (Event Manager), Fm (Font Manager), List (List Manager), Menu (Moenu Manager), Qd (QuickDraw), Qt (QuickTime), Res (Resource Manager and Handles), Scrap (Scrap Manager), Snd (Sound Manager), TE (TextEdit), Waste (non-Apple TextEdit replacement) and Win (Window Manager).

If applicable the module will define a number of Python objects for the various structures declared by the toolbox, and operations will be implemented as methods of the object. Other operations will be implemented as functions in the module. Not all operations possible in C will also be possible in Python (callbacks are often a problem), and parameters will occasionally be different in Python (input and output buffers, especially). All methods and functions have a __doc__ string describing their arguments and return values, and for additional description you are referred to Inside Mac or similar works.

Built-in Module mac#

This module provides a subset of the operating system dependent functionality provided by the optional built-in module posix. It is best accessed through the more portable standard module os.

The following functions are available in this module: chdir, close, dup, fdopen, getcwd, lseek, listdir, mkdir, open, read, rename, rmdir, stat, sync, unlink, write, as well as the exception error. Note that the times returned by stat() are floating-point values, like all time values in MacPython.

One additional function is available: xstat(). This function returns the same information as stat(), but with three extra values appended: the size of the resource fork of the file and its 4-char creator and type.

Standard Module macpath#

This module provides a subset of the pathname manipulation functions available from the optional standard module posixpath. It is best accessed through the more portable standard module os, as os.path.

The following functions are available in this module: normcase, normpath, isabs, join, split, isdir, isfile, walk, exists. For other functions available in posixpath dummy counterparts are available.

Built-in Module macconsole#

This module is available on the Macintosh, provided Python has been built using the Think C compiler. It provides an interface to the Think console package, with which basic text windows can be created.

options#

An object allowing you to set various options when creating windows, see below.

C_ECHO#

Options for the setmode method. C_ECHO and C_CBREAK enable character echo, the other two disable it, C_ECHO and C_NOECHO enable line-oriented input (erase/kill processing, etc).

copen()#

Open a new console window. Return a console window object.

fopen(fp)#

Return the console window object corresponding with the given file object. fp should be one of sys.stdin, sys.stdout or sys.stderr.

macconsole options object#

These options are examined when a window is created:

top#

The origin of the window.

nrows#

The size of the window.

txFont#

The font, fontsize and fontstyle to be used in the window.

title#

The title of the window.

pause_atexit#

If set non-zero, the window will wait for user action before closing.

console window object#

file#

The file object corresponding to this console window. If the file is buffered, you should call file.flush() between write() and read() calls.

setmode(mode)#

Set the input mode of the console to C_ECHO, etc.

settabs(n)#

Set the tabsize to n spaces.

cleos()#

Clear to end-of-screen.

cleol()#

Clear to end-of-line.

inverse(onoff)#

Enable inverse-video mode: characters with the high bit set are displayed in inverse video (this disables the upper half of a non-ASCII character set).

gotoxy(x  y)#

Set the cursor to position (x, y).

hide()#

Hide the window, remembering the contents.

show()#

Show the window again.

echo2printer()#

Copy everything written to the window to the printer as well.

Built-in Module macdnr#

This module provides an interface to the Macintosh Domain Name Resolver. It is usually used in conjunction with the mactcp module, to map hostnames to IP-addresses. It may not be available in all Mac Python versions.

The macdnr module defines the following functions:

Open()#

Open the domain name resolver extension. If filename is given it should be the pathname of the extension, otherwise a default is used. Normally, this call is not needed since the other calls will open the extension automatically.

Close()#

Close the resolver extension. Again, not needed for normal use.

StrToAddr(hostname)#

Look up the IP address for hostname. This call returns a dnr result object of the “address” variation.

AddrToName(addr)#

Do a reverse lookup on the 32-bit integer IP-address addr. Returns a dnr result object of the “address” variation.

AddrToStr(addr)#

Convert the 32-bit integer IP-address addr to a dotted-decimal string. Returns the string.

HInfo(hostname)#

Query the nameservers for a HInfo record for host hostname. These records contain hardware and software information about the machine in question (if they are available in the first place). Returns a dnr result object of the “hinfo” variety.

MXInfo(domain)#

Query the nameservers for a mail exchanger for domain. This is the hostname of a host willing to accept SMTP mail for the given domain. Returns a dnr result object of the “mx” variety.

dnr result object#

Since the DNR calls all execute asynchronously you do not get the results back immediately. Instead, you get a dnr result object. You can check this object to see whether the query is complete, and access its attributes to obtain the information when it is.

Alternatively, you can also reference the result attributes directly, this will result in an implicit wait for the query to complete.

The rtnCode and cname attributes are always available, the others depend on the type of query (address, hinfo or mx).

wait()#

Wait for the query to complete.

isdone()#

Return 1 if the query is complete.

rtnCode#

The error code returned by the query.

cname#

The canonical name of the host that was queried.

ip0#

At most four integer IP addresses for this host. Unused entries are zero. Valid only for address queries.

cpuType#

Textual strings giving the machine type an OS name. Valid for hinfo queries.

exchange#

The name of a mail-exchanger host. Valid for mx queries.

preference#

The preference of this mx record. Not too useful, since the Macintosh will only return a single mx record. Mx queries only.

The simplest way to use the module to convert names to dotted-decimal strings, without worrying about idle time, etc:

>>> def gethostname(name):
...     import macdnr
...     dnrr = macdnr.StrToAddr(name)
...     return macdnr.AddrToStr(dnrr.ip0)

Built-in Module macfs#

This module provides access to macintosh FSSpec handling, the Alias Manager, finder aliases and the Standard File package.

Whenever a function or method expects a file argument, this argument can be one of three things: (1) a full or partial Macintosh pathname, (2) an FSSpec object or (3) a 3-tuple (wdRefNum, parID, name) as described in Inside Mac VI. A description of aliases and the standard file package can also be found there.

FSSpec(file)#

Create an FSSpec object for the specified file.

RawFSSpec(data)#

Create an FSSpec object given the raw data for the C structure for the FSSpec as a string. This is mainly useful if you have obtained an FSSpec structure over a network.

RawAlias(data)#

Create an Alias object given the raw data for the C structure for the alias as a string. This is mainly useful if you have obtained an FSSpec structure over a network.

FInfo()#

Create a zero-filled FInfo object.

ResolveAliasFile(file)#

Resolve an alias file. Returns a 3-tuple (fsspec, isfolder, aliased) where fsspec is the resulting FSSpec object, isfolder is true if fsspec points to a folder and aliased is true if the file was an alias in the first place (otherwise the FSSpec object for the file itself is returned).

StandardGetFile()#

Present the user with a standard “open input file” dialog. Optionally, you can pass up to four 4-char file types to limit the files the user can choose from. The function returns an FSSpec object and a flag indicating that the user completed the dialog without cancelling.

PromptGetFile(prompt)#

Similar to StandardGetFile but allows you to specify a prompt.

StandardPutFile(prompt  )#

Present the user with a standard “open output file” dialog. prompt is the prompt string, and the optional default argument initializes the output file name. The function returns an FSSpec object and a flag indicating that the user completed the dialog without cancelling.

GetDirectory()#

Present the user with a non-standard “select a directory” dialog. prompt is the prompt string, and the optional. Return an FSSpec object and a success-indicator.

SetFolder()#

Set the folder that is initially presented to the user when one of the file selection dialogs is presented. Fsspec should point to a file in the folder, not the folder itself (the file need not exist, though). If no argument is passed the folder will be set to the current directory, i.e. what os.getcwd() returns.

Note that starting with system 7.5 the user can change Standard File behaviour with the “general controls” controlpanel, thereby making this call inoperative.

FindFolder(where  which  create)#

Locates one of the “special” folders that MacOS knows about, such as the trash or the Preferences folder. Where is the disk to search, which is the 4-char string specifying which folder to locate. Setting create causes the folder to be created if it does not exist. Returns a (vrefnum, dirid) tuple.

NewAliasMinimalFromFullPath(pathname)#

Return a minimal alias record object that points to the given file, which must be specified as a full pathname. This is the only way to create an alias record pointing to a non-existing file.

The constants for where and which can be obtained from the standard module MACFS.

FindApplication(creator)#

Locate the application with 4-char creator code creator. The function returns an FSSpec object pointing to the application.

FSSpec objects#

data#

The raw data from the FSSpec object, suitable for passing to other applications, for instance.

as_pathname()#

Return the full pathname of the file described by the FSSpec object.

as_tuple()#

Return the (wdRefNum, parID, name) tuple of the file described by the FSSpec object.

NewAlias()#

Create an Alias object pointing to the file described by this FSSpec. If the optional file parameter is present the alias will be relative to that file, otherwise it will be absolute.

NewAliasMinimal()#

Create a minimal alias pointing to this file.

GetCreatorType()#

Return the 4-char creator and type of the file.

SetCreatorType(creator  type)#

Set the 4-char creator and type of the file.

GetFInfo()#

Return a FInfo object describing the finder info for the file.

SetFInfo(finfo)#

Set the finder info for the file to the values specified in the finfo object.

GetDates()#

Return a tuple with three floating point values representing the creation date, modification date and backup date of the file.

SetDates(crdate  moddate  backupdate)#

Set the creation, modification and backup date of the file. The values are in the standard floating point format used for times throughout Python.

alias objects#

data#

The raw data for the Alias record, suitable for storing in a resource or transmitting to other programs.

Resolve()#

Resolve the alias. If the alias was created as a relative alias you should pass the file relative to which it is. Return the FSSpec for the file pointed to and a flag indicating whether the alias object itself was modified during the search process. If the file does not exist but the path leading up to it does exist a valid fsspec is returned.

GetInfo(num)#

An interface to the C routine GetAliasInfo().

Update(file  )#

Update the alias to point to the file given. If file2 is present a relative alias will be created.

Note that it is currently not possible to directly manipulate a resource as an alias object. Hence, after calling Update or after Resolve indicates that the alias has changed the Python program is responsible for getting the data from the alias object and modifying the resource.

FInfo objects#

See Inside Mac for a complete description of what the various fields mean.

Creator#

The 4-char creator code of the file.

Type#

The 4-char type code of the file.

Flags#

The finder flags for the file as 16-bit integer. The bit values in Flags are defined in standard module MACFS.

Location#

A Point giving the position of the file’s icon in its folder.

Fldr#

The folder the file is in (as an integer).

Standard Module ic#

This module provides access to macintosh Internet Config package, which stores preferences for Internet programs such as mail address, default homepage, etc. Also, Internet Config contains an elaborate set of mappings from Macintosh creator/type codes to foreign filename extensions plus information on how to transfer files (binary, ascii, etc).

There is a low-level companion module icglue which provides the basic ic access functionality. This low-level module is not documented, but the docstrings of the routines document the parameters and the routine names are the same as for the Pascal or C API to Internet Config, so the standard IC programmers documentation can be used if this module is needed.

The ic module defines the error exception and symbolic names for all error codes IC can produce, see the source for details.

The ic module defines the following functions:

IC()#

Create an internet config object. The signature is a 4-char creator code of the current application (default ’Pyth’) which may influence some of ICs settings. The optional ic argument is a low-level icinstance created beforehand, this may be useful if you want to get preferences from a different config file, etc.

launchurl(url )#

parseurl(data )#

mapfile(file)#

maptypecreator(type, creator )#

settypecreator(file)#

These functions are “shortcuts” to the methods of the same name, described below.

IC objects#

IC objects have a mapping interface, hence to obtain the mail address you simply get ic[’MailAddress’]. Assignment also works, and changes the option in the configuration file.

The module knows about various datatypes, and converts the internal IC representation to a “logical” python datastructure. Running the ic module standalone will run a test program that lists all keys and values in your IC database, this will have to server as documentation.

If the module does not know how to represent the data it returns an instance of the ICOpaqueData type, with the raw data in its data attribute. Objects of this type are also acceptable values for assignment.

Besides the dictionary interface IC objects have the following methods:

launchurl(url )#

Parse the given URL, lauch the correct application and pass it the URL. The optional hint can be a scheme name such as mailto:, in which case incomplete URLs are completed with this scheme (otherwise incomplete URLs are invalid).

parseurl(data )#

Find an URL somewhere in data and return start position, end position and the URL. The optional start and end can be used to limit the search, so for instance if a user clicks in a long textfield you can pass the whole textfield and the click-position in start and this routine will return the whole URL in which the user clicked. Hint is again an optional scheme used to complete incomplete URLs.

mapfile(file)#

Return the mapping entry for the given file, which can be passed as either a filename or an FSSpec object, and which need not exist.

The mapping entry is returned as a tuple (version, type, creator, postcreator, flags, extension, appname, postappname, mimetype, entryname), where version is the entry version number, type is the 4-char filetype, creator is the 4-char creator type, postcreator is the 4-char creator code of an optional application to post-process the file after downloading, flags are various bits specifying whether to transfer in binary or ascii and such, extension is the filename extension for this file type, appname is the printable name of the application to which this file belongs, postappname is the name of the postprocessing application, mimetype is the MIME type of this file and entryname is the name of this entry.

maptypecreator(type, creator )#

Return the mapping entry for files with given 4-char type and creator codes. The optional filename may be specified to further help finding the correct entry (if the creator code is ’????’, for instance).

The mapping entry is returned in the same format as for mapfile.

settypecreator(file)#

Given an existing file, specified either as a filename or as an FSSpec record, set its creator and type correctly based on its extension. The finder is told about the change, so the finder icon will be updated quickly.

Built-in Module MacOS#

This module provides access to MacOS specific functionality in the python interpreter, such as how the interpreter eventloop functions and the like. Use with care.

Note the capitalisation of the module name, this is a historical artefact.

exception Error#

This exception is raised on MacOS generated errors, either from functions in this module or from other mac-specific modules like the toolbox interfaces. The arguments are the integer error code (the OSErr value) and a textual description of the error code. Symbolic names for all known error codes are defined in the standard module macerrors.

SetEventHandler(handler)#

In the inner interpreter loop Python will occasionally check for events, unless disabled with ScheduleParams. With this function you can pass a Python event-handler function that will be called if an event is available. The event is passed as parameter and the function should return non-zero if the event has been fully processed, otherwise event processing continues (by passing the event to the console window package, for instance).

Call SetEventHandler without parameter to clear the event handler. Setting an eventhandler while one is already set is an error.

SchedParams()#

Influence the interpreter inner loop event handling. Interval specifies how often (in seconds, floating point) the interpreter should enter the event processing code. When true, doint causes interrupt (command-dot) checking to be done. Evtmask tells the interpreter to do event processing for events in the mask (redraws, mouseclicks to switch to other applications, etc). The besocial flag gives other processes a chance to run. They are granted minimal runtime when Python is in the foreground and bgyield seconds per interval when Python runs in the background.

All parameters are optional, and default to the current value. The return value of this function is a tuple with the old values of these options. Initial defaults are that all processing is enabled, checking is done every quarter second and the CPU is given up for a quarter second when in the background.

HandleEvent(ev)#

Pass the event record ev back to the python event loop, or possibly to the handler for the sys.stdout window (based on the compiler used to build python). This allows python programs that do their own event handling to still have some command-period and window-switching capability.

If you attempt to call this function from an event handler set through SetEventHandler you will get an exception.

GetErrorString(errno)#

Return the textual description of MacOS error code errno.

splash(resid)#

This function will put a splash window on-screen, with the contents of the DLOG resource specified by resid. Calling with a zero argument will remove the splash screen. This function is useful if you want an applet to post a splash screen early in initialization without first having to load numerous extension modules.

DebugStr(message )#

Drop to the low-level debugger with message message. The optional object argument is not used, but can easily be inspected from the debugger.

Note that you should use this function with extreme care: if no low-level debugger like MacsBug is installed this call will crash your system. It is intended mainly for developers of Python extension modules.

openrf(name )#

Open the resource fork of a file. Arguments are the same as for the builtin function open. The object returned has file-like semantics, but it is not a python file object, so there may be subtle differences.

Standard Module macostools#

This module contains some convenience routines for file-manipulation on the Macintosh.

The macostools module defines the following functions:

copy(src  dst)#

Copy file src to dst. The files can be specified as pathnames or FSSpec objects. If createpath is non-zero dst must be a pathname and the folders leading to the destination are created if necessary. The method copies data and resource fork and some finder information (creator, type, flags) and optionally the creation, modification and backup times (default is to copy them). Custom icons, comments and icon position are not copied.

If the source is an alias the original to which the alias points is copied, not the aliasfile.

copytree(src  dst)#

Recursively copy a file tree from src to dst, creating folders as needed. Src and dst should be specified as pathnames.

mkalias(src  dst)#

Create a finder alias dst pointing to src. Both may be specified as pathnames or FSSpec objects.

touched(dst)#

Tell the finder that some bits of finder-information such as creator or type for file dst has changed. The file can be specified by pathname or fsspec. This call should prod the finder into redrawing the files icon.

BUFSIZ#

The buffer size for copy, default 1 megabyte.

Note that the process of creating finder aliases is not specified in the Apple documentation. Hence, aliases created with mkalias could conceivably have incompatible behaviour in some cases.

Standard Module findertools#

This module contains routines that give Python programs access to some functionality provided by the finder. They are implemented as wrappers around the AppleEvent interface to the finder.

All file and folder parameters can be specified either as full pathnames or as FSSpec objects.

The findertools module defines the following functions:

launch(file)#

Tell the finder to launch file. What launching means depends on the file: applications are started, folders are opened and documents are opened in the correct application.

Print(file)#

Tell the finder to print a file (again specified by full pathname or FSSpec). The behaviour is identical to selecting the file and using the print command in the finder.

copy(file, destdir)#

Tell the finder to copy a file or folder file to folder destdir. The function returns an Alias object pointing to the new file.

move(file, destdir)#

Tell the finder to move a file or folder file to folder destdir. The function returns an Alias object pointing to the new file.

sleep()#

Tell the finder to put the mac to sleep, if your machine supports it.

restart()#

Tell the finder to perform an orderly restart of the machine.

shutdown()#

Tell the finder to perform an orderly shutdown of the machine.

Built-in Module macspeech#

This module provides an interface to the Macintosh Speech Manager, allowing you to let the Macintosh utter phrases. You need a version of the speech manager extension (version 1 and 2 have been tested) in your Extensions folder for this to work. The module does not provide full access to all features of the Speech Manager yet. It may not be available in all Mac Python versions.

Available()#

Test availability of the Speech Manager extension (and, on the PowerPC, the Speech Manager shared library). Return 0 or 1.

Version()#

Return the (integer) version number of the Speech Manager.

SpeakString(str)#

Utter the string str using the default voice, asynchronously. This aborts any speech that may still be active from prior SpeakString invocations.

Busy()#

Return the number of speech channels busy, system-wide.

CountVoices()#

Return the number of different voices available.

GetIndVoice(num)#

Return a voice object for voice number num.

voice objects#

Voice objects contain the description of a voice. It is currently not yet possible to access the parameters of a voice.

GetGender()#

Return the gender of the voice: 0 for male, 1 for female and -1 for neuter.

NewChannel()#

Return a new speech channel object using this voice.

speech channel objects#

A speech channel object allows you to speak strings with slightly more control than SpeakString(), and allows you to use multiple speakers at the same time. Please note that channel pitch and rate are interrelated in some way, so that to make your Macintosh sing you will have to adjust both.

SpeakText(str)#

Start uttering the given string.

Stop()#

Stop babbling.

GetPitch()#

Return the current pitch of the channel, as a floating-point number.

SetPitch(pitch)#

Set the pitch of the channel.

GetRate()#

Get the speech rate (utterances per minute) of the channel as a floating point number.

SetRate(rate)#

Set the speech rate of the channel.

Built-in Module mactcp#

This module provides an interface to the Macintosh TCP/IP driver MacTCP. There is an accompanying module macdnr which provides an interface to the name-server (allowing you to translate hostnames to ip-addresses), a module MACTCPconst which has symbolic names for constants constants used by MacTCP. Since the builtin module socket is also available on the mac it is usually easier to use sockets in stead of the mac-specific MacTCP API.

A complete description of the MacTCP interface can be found in the Apple MacTCP API documentation.

MTU()#

Return the Maximum Transmit Unit (the packet size) of the network interface.

IPAddr()#

Return the 32-bit integer IP address of the network interface.

NetMask()#

Return the 32-bit integer network mask of the interface.

TCPCreate(size)#

Create a TCP Stream object. size is the size of the receive buffer, 4096 is suggested by various sources.

UDPCreate(size, port)#

Create a UDP stream object. size is the size of the receive buffer (and, hence, the size of the biggest datagram you can receive on this port). port is the UDP port number you want to receive datagrams on, a value of zero will make MacTCP select a free port.

TCP Stream Objects#

asr#

When set to a value different than None this should point to a function with two integer parameters: an event code and a detail. This function will be called upon network-generated events such as urgent data arrival. In addition, it is called with eventcode MACTCP.PassiveOpenDone when a PassiveOpen completes. This is a Python addition to the MacTCP semantics. It is safe to do further calls from the asr.

PassiveOpen(port)#

Wait for an incoming connection on TCP port port (zero makes the system pick a free port). The call returns immediately, and you should use wait to wait for completion. You should not issue any method calls other than wait, isdone or GetSockName before the call completes.

wait()#

Wait for PassiveOpen to complete.

isdone()#

Return 1 if a PassiveOpen has completed.

GetSockName()#

Return the TCP address of this side of a connection as a 2-tuple (host, port), both integers.

ActiveOpen(lport  host  rport)#

Open an outgoing connection to TCP address (host, rport). Use local port lport (zero makes the system pick a free port). This call blocks until the connection has been established.

Send(buf  push  urgent)#

Send data buf over the connection. Push and urgent are flags as specified by the TCP standard.

Rcv(timeout)#

Receive data. The call returns when timeout seconds have passed or when (according to the MacTCP documentation) “a reasonable amount of data has been received”. The return value is a 3-tuple (data, urgent, mark). If urgent data is outstanding Rcv will always return that before looking at any normal data. The first call returning urgent data will have the urgent flag set, the last will have the mark flag set.

Close()#

Tell MacTCP that no more data will be transmitted on this connection. The call returns when all data has been acknowledged by the receiving side.

Abort()#

Forcibly close both sides of a connection, ignoring outstanding data.

Status()#

Return a TCP status object for this stream giving the current status (see below).

TCP Status Objects#

This object has no methods, only some members holding information on the connection. A complete description of all fields in this objects can be found in the Apple documentation. The most interesting ones are:

localHost#

The integer IP-addresses and port numbers of both endpoints of the connection.

sendWindow#

The current window size.

amtUnackedData#

The number of bytes sent but not yet acknowledged. sendWindow - amtUnackedData is what you can pass to Send without blocking.

amtUnreadData#

The number of bytes received but not yet read (what you can Recv without blocking).

UDP Stream Objects#

Note that, unlike the name suggests, there is nothing stream-like about UDP.

asr#

The asynchronous service routine to be called on events such as datagram arrival without outstanding Read call. The asr has a single argument, the event code.

port#

A read-only member giving the port number of this UDP stream.

Read(timeout)#

Read a datagram, waiting at most timeout seconds (-1 is infinite). Return the data.

Write(host  port  buf)#

Send buf as a datagram to IP-address host, port port.

Standard Module EasyDialogs#

The EasyDialogs module contains some simple dialogs for the Macintosh, modelled after the stdwin dialogs with similar names. All routines have an optional parameter id with which you can override the DLOG resource used for the dialog, as long as the item numbers correspond. See the source for details.

The EasyDialogs module defines the following functions:

Message(str)#

A modal dialog with the message text str, which should be at most 255 characters long, is displayed. Control is returned when the user clicks “OK”.

AskString(prompt)#

Ask the user to input a string value, in a modal dialog. Prompt is the promt message, the optional default arg is the initial value for the string. All strings can be at most 255 bytes long. AskString returns the string entered or None in case the user cancelled.

AskYesNoCancel(question)#

Present a dialog with text question and three buttons labelled “yes”, “no” and “cancel”. Return 1 for yes, 0 for no and -1 for cancel. The default return value chosen by hitting return is 0. This can be changed with the optional default argument.

ProgressBar()#

Display a modeless progress dialog with a thermometer bar. Label is the textstring displayed (default “Working…”), maxval is the value at which progress is complete (default 100). The returned object has one method, set(value), which sets the value of the progress bar. The bar remains visible until the object returned is discarded.

The progress bar has a “cancel” button, but it is currently non-functional.

Note that EasyDialogs does not currently use the notification manager. This means that displaying dialogs while the program is in the background will lead to unexpected results and possibly crashes. Also, all dialogs are modeless and hence expect to be at the top of the stacking order. This is true when the dialogs are created, but windows that pop-up later (like a console window) may also result in crashes.

Standard Module FrameWork#

The FrameWork module contains classes that together provide a framework for an interactive Macintosh application. The programmer builds an application by creating subclasses that override various methods of the bases classes, thereby implementing the functionality wanted. Overriding functionality can often be done on various different levels, i.e. to handle clicks in a single dialog window in a non-standard way it is not necessary to override the complete event handling.

The FrameWork is still very much work-in-progress, and the documentation describes only the most important functionality, and not in the most logical manner at that. Examine the source or the examples for more details.

The FrameWork module defines the following functions:

Application()#

An object representing the complete application. See below for a description of the methods. The default __init__ routine creates an empty window dictionary and a menu bar with an apple menu.

MenuBar()#

An object representing the menubar. This object is usually not created by the user.

Menu(bar  title)#

An object representing a menu. Upon creation you pass the MenuBar the menu appears in, the title string and a position (1-based) after where the menu should appear (default: at the end).

MenuItem(menu  title)#

Create a menu item object. The arguments are the menu to crate the item it, the item title string and optionally the keyboard shortcut and a callback routine. The callback is called with the arguments menu-id, item number within menu (1-based), current front window and the event record.

In stead of a callable object the callback can also be a string. In this case menu selection causes the lookup of a method in the topmost window and the application. The method name is the callback string with ’domenu_’ prepended.

Calling the MenuBar fixmenudimstate method sets the correct dimming for all menu items based on the current front window.

Separator(menu)#

Add a separator to the end of a menu.

SubMenu(menu  label)#

Create a submenu named label under menu menu. The menu object is returned.

Window(parent)#

Creates a (modeless) window. Parent is the application object to which the window belongs. The window is not displayed until later.

DialogWindow(parent)#

Creates a modeless dialog window.

windowbounds(width  height)#

Return a (left, top, right, bottom) tuple suitable for creation of a window of given width and height. The window will be staggered with respect to previous windows, and an attempt is made to keep the whole window on-screen. The window will however always be exact the size given, so parts may be offscreen.

setwatchcursor()#

Set the mouse cursor to a watch.

setarrowcursor()#

Set the mouse cursor to an arrow.

Application objects#

Application objects have the following methods, among others:

makeusermenus()#

Override this method if you need menus in your application. Append the menus to self.menubar.

getabouttext()#

Override this method to return a text string describing your application. Alternatively, override the do_about method for more elaborate about messages.

mainloop()#

This routine is the main event loop, call it to set your application rolling. Mask is the mask of events you want to handle, wait is the number of ticks you want to leave to other concurrent application (default 0, which is probably not a good idea). While raising self to exit the mainloop is still supported it is not recommended, call self._quit instead.

The event loop is split into many small parts, each of which can be overridden. The default methods take care of dispatching events to windows and dialogs, handling drags and resizes, Apple Events, events for non-FrameWork windows, etc.

In general, all event handlers should return 1 if the event is fully handled and 0 otherwise (because the front window was not a FrameWork window, for instance). This is needed so that update events and such can be passed on to other windows like the Sioux console window. Calling MacOS.HandleEvent is not allowed within our_dispatch or its callees, since this may result in an infinite loop if the code is called through the python inner-loop event handler.

asyncevents(onoff)#

Call this method with a nonzero parameter to enable asynchronous event handling. This will tell the inner interpreter loop to call the application event handler async_dispatch whenever events are available. This will cause FrameWork window updates and the user interface to remain working during long computations, but will slow the interpreter down and may cause surprising results in non-reentrant code (such as FrameWork itself). By default async_dispatch will immedeately call our_dispatch but you may override this to handle only certain events asynchronously. Events you do not handle will be passed to Sioux and such.

The old on/off value is returned.

_quit()#

Terminate the event mainloop at the next convenient moment.

do_char(c  event)#

The user typed character c. The complete details of the event can be found in the event structure. This method can also be provided in a Window object, which overrides the application-wide handler if the window is frontmost.

do_dialogevent(event)#

Called early in the event loop to handle modeless dialog events. The default method simply dispatches the event to the relevant dialog (not through the the DialogWindow object involved). Override if you need special handling of dialog events (keyboard shortcuts, etc).

idle(event)#

Called by the main event loop when no events are available. The null-event is passed (so you can look at mouse position, etc).

Window Objects#

Window objects have the following methods, among others:

open()#

Override this method to open a window. Store the MacOS window-id in self.wid and call self.do_postopen to register the window with the parent application.

close()#

Override this method to do any special processing on window close. Call self.do_postclose to cleanup the parent state.

do_postresize(width  height  macoswindowid)#

Called after the window is resized. Override if more needs to be done than calling InvalRect.

do_contentclick(local  modifiers  event)#

The user clicked in the content part of a window. The arguments are the coordinates (window-relative), the key modifiers and the raw event.

do_update(macoswindowid  event)#

An update event for the window was received. Redraw the window.

do_activate(activate  event)#

The window was activated (activate==1) or deactivated (activate==0). Handle things like focus highlighting, etc.

ControlsWindow Object#

ControlsWindow objects have the following methods besides those of Window objects:

do_controlhit(window  control  pcode  event)#

Part pcode of control control was hit by the user. Tracking and such has already been taken care of.

ScrolledWindow Object#

ScrolledWindow objects are ControlsWindow objects with the following extra methods:

scrollbars()#

Create (or destroy) horizontal and vertical scrollbars. The arguments specify which you want (default: both). The scrollbars always have minimum 0 and maximum 32767.

getscrollbarvalues()#

You must supply this method. It should return a tuple x, y giving the current position of the scrollbars (between 0 and 32767). You can return None for either to indicate the whole document is visible in that direction.

updatescrollbars()#

Call this method when the document has changed. It will call getscrollbarvalues and update the scrollbars.

scrollbar_callback(which  what  value)#

Supplied by you and called after user interaction. Which will be ’x’ or ’y’, what will be ’-’, ’--’, ’set’, ’++’ or ’+’. For ’set’, value will contain the new scrollbar position.

scalebarvalues(absmin  absmax  curmin  curmax)#

Auxiliary method to help you calculate values to return from getscrollbarvalues. You pass document minimum and maximum value and topmost (leftmost) and bottommost (rightmost) visible values and it returns the correct number or None.

do_activate(onoff  event)#

Takes care of dimming/highlighting scrollbars when a window becomes frontmost vv. If you override this method call this one at the end of your method.

do_postresize(width  height  window)#

Moves scrollbars to the correct position. Call this method initially if you override it.

do_controlhit(window  control  pcode  event)#

Handles scrollbar interaction. If you override it call this method first, a nonzero return value indicates the hit was in the scrollbars and has been handled.

DialogWindow Objects#

DialogWindow objects have the following methods besides those of Window objects:

open(resid)#

Create the dialog window, from the DLOG resource with id resid. The dialog object is stored in self.wid.

do_itemhit(item  event)#

Item number item was hit. You are responsible for redrawing toggle buttons, etc.

Standard Module MiniAEFrame#

The module MiniAEFrame provides a framework for an application that can function as an OSA server, i.e. receive and process AppleEvents. It can be used in conjunction with FrameWork or standalone.

This module is temporary, it will eventually be replaced by a module that handles argument names better and possibly automates making your application scriptable.

The MiniAEFrame module defines the following classes:

AEServer()#

A class that handles AppleEvent dispatch. Your application should subclass this class together with either MiniAEFrame.MiniApplication or FrameWork.Application. Your __init__ method should call the __init__ method for both classes.

MiniApplication()#

A class that is more or less compatible with FrameWork.Application but with less functionality. Its eventloop supports the apple menu, command-dot and AppleEvents, other events are passed on to the Python interpreter and/or Sioux. Useful if your application wants to use AEServer but does not provide its own windows, etc.

AEServer Objects#

installaehandler(classe  type  callback)#

Installs an AppleEvent handler. Classe and type are the four-char OSA Class and Type designators, ’****’ wildcards are allowed. When a matching AppleEvent is received the parameters are decoded and your callback is invoked.

callback(_object  **kwargs)#

Your callback is called with the OSA Direct Object as first positional parameter. The other parameters are passed as keyword arguments, with the 4-char designator as name. Three extra keyword parameters are passed: _class and _type are the Class and Type designators and _attributes is a dictionary with the AppleEvent attributes.

The return value of your method is packed with aetools.packevent and sent as reply.

Note that there are some serious problems with the current design. AppleEvents which have non-identifier 4-char designators for arguments are not implementable, and it is not possible to return an error to the originator. This will be addressed in a future release.

Standard Module mailbox#

This module defines a number of classes that allow easy and uniform access to mail messages in a (unix) mailbox.

UnixMailbox(fp)#

Access a classic unix-style mailbox, where all messages are contained in a single file and separated by “From name time” lines. Fp is the file object pointing to the mailbox file.

MmdfMailbox(fp)#

Access an MMDF-style mailbox, where all messages are contained in a single file and separated by lines consisting of 4 control-A characters. Fp is the file object pointing to the mailbox file.

MHMailbox(dirname)#

Access an MH mailbox, a directory with each message in a separate file with a numeric name. Dirname is the name of the mailbox directory.

Mailbox Objects#

All implementations of Mailbox objects have one externally visible method:

next()#

Return the next message in the mailbox, as a rfc822.Message object. Depending on the mailbox implementation the fp attribute of this object may be a true file object or a class instance simulating a file object, taking care of things like message boundaries if multiple mail messages are contained in a single file, etc.

Standard Module mailcap#

Mailcap files are used to configure how MIME-aware applications such as mail readers and Web browsers react to files with different MIME types. (The name “mailcap” is derived from the phrase “mail capability”.) For example, a mailcap file might contain a line like video/mpeg; xmpeg %s. Then, if the user encounters an email message or Web document with the MIME type video/mpeg, %s will be replaced by a filename (usually one belonging to a temporary file) and the xmpeg program can be automatically started to view the file.

The mailcap format is documented in RFC 1524, “A User Agent Configuration Mechanism For Multimedia Mail Format Information”, but is not an Internet standard. However, mailcap files are supported on most Unix systems.

findmatch(caps  MIMEtype  key  filename  plist)#

Return a 2-tuple; the first element is a string containing the command line to be executed (which can be passed to os.system()), and the second element is the mailcap entry for a given MIME type. If no matching MIME type can be found, (None, None) is returned.

key is the name of the field desired, which represents the type of activity to be performed; the default value is ’view’, since in the most common case you simply want to view the body of the MIME-typed data. Other possible values might be ’compose’ and ’edit’, if you wanted to create a new body of the given MIME type or alter the existing body data. See RFC1524 for a complete list of these fields.

filename is the filename to be substituted for %s in the command line; the default value is /dev/null which is almost certainly not what you want, so usually you’ll override it by specifying a filename.

plist can be a list containing named parameters; the default value is simply an empty list. Each entry in the list must be a string containing the parameter name, an equals sign (=), and the parameter’s value. Mailcap entries can contain named parameters like %{foo}, which will be replaced by the value of the parameter named ’foo’. For example, if the command line showpartial %{id} %{number} %{total} was in a mailcap file, and plist was set to [’id=1’, ’number=2’, ’total=3’], the resulting command line would be "showpartial 1 2 3".

In a mailcap file, the “test” field can optionally be specified to test some external condition (e.g., the machine architecture, or the window system in use) to determine whether or not the mailcap line applies. findmatch() will automatically check such conditions and skip the entry if the check fails.

getcaps()#

Returns a dictionary mapping MIME types to a list of mailcap file entries. This dictionary must be passed to the findmatch() function. An entry is stored as a list of dictionaries, but it shouldn’t be necessary to know the details of this representation.

The information is derived from all of the mailcap files found on the system. Settings in the user’s mailcap file $HOME/.mailcap will override settings in the system mailcap files /etc/mailcap, /usr/etc/mailcap, and /usr/local/etc/mailcap.

An example usage:

>>> import mailcap
>>> d=mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})

Built-in Module __main__#

This module represents the (otherwise anonymous) scope in which the interpreter’s main program executes — commands read either from standard input or from a script file.

Built-in Module marshal#

This module contains functions that can read and write Python values in a binary format. The format is specific to Python, but independent of machine architecture issues (e.g., you can write a Python value to a file on a PC, transport the file to a Sun, and read it back there). Details of the format are undocumented on purpose; it may change between Python versions (although it rarely does). ¹

This is not a general “persistency” module. For general persistency and transfer of Python objects through RPC calls, see the modules pickle and shelve. The marshal module exists mainly to support reading and writing the “pseudo-compiled” code for Python modules of .pyc files.

Not all Python object types are supported; in general, only objects whose value is independent from a particular invocation of Python can be written and read by this module. The following types are supported: None, integers, long integers, floating point numbers, strings, tuples, lists, dictionaries, and code objects, where it should be understood that tuples, lists and dictionaries are only supported as long as the values contained therein are themselves supported; and recursive lists and dictionaries should not be written (they will cause infinite loops).

Caveat: On machines where C’s long int type has more than 32 bits (such as the DEC Alpha), it is possible to create plain Python integers that are longer than 32 bits. Since the current marshal module uses 32 bits to transfer plain Python integers, such values are silently truncated. This particularly affects the use of very long integer literals in Python modules — these will be accepted by the parser on such machines, but will be silently be truncated when the module is read from the .pyc instead. ²

There are functions that read/write files as well as functions operating on strings.

The module defines these functions:

dump(value  file)#

Write the value on the open file. The value must be a supported type. The file must be an open file object such as sys.stdout or returned by open() or posix.popen().

If the value has (or contains an object that has) an unsupported type, a ValueError exception is raised – but garbage data will also be written to the file. The object will not be properly read back by load().

load(file)#

Read one value from the open file and return it. If no valid value is read, raise EOFError, ValueError or TypeError. The file must be an open file object.

Warning: If an object containing an unsupported type was marshalled with dump(), load() will substitute None for the unmarshallable type.

dumps(value)#

Return the string that would be written to a file by dump(value, file). The value must be a supported type. Raise a ValueError exception if value has (or contains an object that has) an unsupported type.

loads(string)#

Convert the string to a value. If no valid value is found, raise EOFError, ValueError or TypeError. Extra characters in the string are ignored.

Built-in Module math#

This module is always available. It provides access to the mathematical functions defined by the C standard. They are:

acos(x)#

Return the arc cosine of x.

asin(x)#

Return the arc sine of x.

atan(x)#

Return the arc tangent of x.

atan2(x, y)#

Return atan(x / y).

ceil(x)#

Return the ceiling of x.

cos(x)#

Return the cosine of x.

cosh(x)#

Return the hyperbolic cosine of x.

exp(x)#

Return e**x.

fabs(x)#

Return the absolute value of the real x.

floor(x)#

Return the floor of x.

fmod(x, y)#

Return x % y.

frexp(x)#

Return the matissa and exponent for x. The mantissa is positive.

hypot(x, y)#

Return the Euclidean distance, sqrt(x*x + y*y).

ldexp(x, i)#

Return x * (2**i).

modf(x)#

Return the fractional and integer parts of x. Both results carry the sign of x.

pow(x, y)#

Return x**y.

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.

Note that frexp and modf have a different call/return pattern than their C equivalents: they take a single argument and return a pair of values, rather than returning their second return value through an ‘output parameter’ (there is no such thing in Python).

The module also defines two mathematical constants:

pi#

The mathematical constant pi.

e#

The mathematical constant e.

See also:#

— cmathComplex number versions of many of these functions.

Built-in Module md5#

This module implements the interface to RSA’s MD5 message digest algorithm (see also Internet RFC 1321). Its use is quite straightforward: use the md5.new() to create an md5 object. You can now feed this object with arbitrary strings using the update() method, and at any point you can ask it for the digest (a strong kind of 128-bit checksum, a.k.a. “fingerprint”) of the contatenation of the strings fed to it so far using the digest() method.

For example, to obtain the digest of the string "Nobody inspects the spammish repetition":

>>> import md5
>>> m = md5.new()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'

More condensed:

>>> md5.new("Nobody inspects the spammish repetition").digest()
'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'

new()#

Return a new md5 object. If arg is present, the method call update(arg) is made.

md5()#

For backward compatibility reasons, this is an alternative name for the new() function.

An md5 object has the following methods:

update(arg)#

Update the md5 object with the string arg. Repeated calls are equivalent to a single call with the concatenation of all the arguments, i.e. m.update(a); m.update(b) is equivalent to m.update(a+b).

digest()#

Return the digest of the strings passed to the update() method so far. This is an 16-byte string which may contain non-ASCII characters, including null bytes.

copy()#

Return a copy (“clone”) of the md5 object. This can be used to efficiently compute the digests of strings that share a common initial substring.

Standard Module mimetools#

This module defines a subclass of the class rfc822.Message and a number of utility functions that are useful for the manipulation for MIME style multipart or encoded message.

It defines the following items:

Message(fp)#

Return a new instance of the mimetools.Message class. This is a subclass of the rfc822.Message class, with some additional methods (see below).

choose_boundary()#

Return a unique string that has a high likelihood of being usable as a part boundary. The string has the form "hostipaddr.uid.pid.timestamp.random".

decode(input  output  encoding)#

Read data encoded using the allowed MIME encoding from open file object input and write the decoded data to open file object output. Valid values for encoding include "base64", "quoted-printable" and "uuencode".

encode(input  output  encoding)#

Read data from open file object input and write it encoded using the allowed MIME encoding to open file object output. Valid values for encoding are the same as for decode().

copyliteral(input  output)#

Read lines until EOF from open file input and write them to open file output.

copybinary(input  output)#

Read blocks until EOF from open file input and write them to open file output. The block size is currently fixed at 8192.

Additional Methods of Message objects#

The mimetools.Message class defines the following methods in addition to the rfc822.Message class:

getplist()#

Return the parameter list of the Content-type header. This is a list if strings. For parameters of the form key=value, key is converted to lower case but value is not. For example, if the message contains the header Content-type: text/html; spam=1; Spam=2; Spam then getplist() will return the Python list [’spam=1’, ’spam=2’, ’Spam’].

getparam(name)#

Return the value of the first parameter (as returned by getplist() of the form name=value for the given name. If value is surrounded by quotes of the form <…> or "…", these are removed.

getencoding()#

Return the encoding specified in the Content-transfer-encoding message header. If no such header exists, return "7bit". The encoding is converted to lower case.

gettype()#

Return the message type (of the form type/subtype) as specified in the Content-type header. If no such header exists, return "text/plain". The type is converted to lower case.

getmaintype()#

Return the main type as specified in the Content-type header. If no such header exists, return "text". The main type is converted to lower case.

getsubtype()#

Return the subtype as specified in the Content-type header. If no such header exists, return "plain". The subtype is converted to lower case.

Standard Module mimify#

The mimify module defines two functions to convert mail messages to and from MIME format. The mail message can be either a simple message or a so-called multipart message. Each part is treated separately. Mimifying (a part of) a message entails encoding the message as quoted-printable if it contains any characters that cannot be represented using 7-bit ASCII. Unmimifying (a part of) a message entails undoing the quoted-printable encoding. Mimify and unmimify are especially useful when a message has to be edited before being sent. Typical use would be:

unmimify message
edit message
mimify message
send message

The modules defines the following user-callable functions and user-settable variables:

mimify(infile, outfile)#

Copy the message in infile to outfile, converting parts to quoted-printable and adding MIME mail headers when necessary. infile and outfile can be file objects (actually, any object that has a readline method (for infile) or a write method (for outfile)) or strings naming the files. If infile and outfile are both strings, they may have the same value.

unmimify(infile, outfile, decode_base64 = 0)#

Copy the message in infile to outfile, decoding all quoted-printable parts. infile and outfile can be file objects (actually, any object that has a readline method (for infile) or a write method (for outfile)) or strings naming the files. If infile and outfile are both strings, they may have the same value. If the decode_base64 argument is provided and tests true, any parts that are coded in the base64 encoding are decoded as well.

mime_decode_header(line)#

Return a decoded version of the encoded header line in line.

mime_encode_header(line)#

Return a MIME-encoded version of the header line in line.

MAXLEN#

By default, a part will be encoded as quoted-printable when it contains any non-ASCII characters (i.e., characters with the 8th bit set), or if there are any lines longer than MAXLEN characters (default value 200).

CHARSET#

When not specified in the mail headers, a character set must be filled in. The string used is stored in CHARSET, and the default value is ISO-8859-1 (also known as Latin1 (latin-one)).

This module can also be used from the command line. Usage is as follows:

mimify.py -e [-l length] [infile [outfile]]
mimify.py -d [-b] [infile [outfile]]

to encode (mimify) and decode (unmimify) respectively. infile defaults to standard input, outfile defaults to standard output. The same file can be specified for input and output.