File: bflib_python_2.3.xml

package info (click to toggle)
bluefish 2.2.6-2
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 28,096 kB
ctags: 5,830
sloc: xml: 150,791; ansic: 59,107; sh: 11,453; python: 6,337; makefile: 1,034; sed: 16
file content (36082 lines) | stat: -rw-r--r-- 1,686,250 bytes
parent folder | download | duplicates (9)
<?xml version="1.0" ?>
<ref description="Complete reference for Python 2.3.3" name="Python 2.3.3" version="2">
<group name="Built-in Functions, Types, and Exceptions">
<group name="Built-in Functions">
<description>The Python interpreter has a number of functions built into it that
are always available. They are listed here in alphabetical order.
</description>
<element kind="function" name="__import__">
<description>This function is invoked by the importimport
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
ihooksihooks and
rexecrexec. See also the built-in
module impimp, 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. As a workaround for this
behavior, use getattr() to extract the desired
components. For example, you could define the following helper:
def my_import(name):
mod = __import__(name)
components = name.split('.')
for comp in components[1:]:
mod = getattr(mod, comp)
return mod
</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="globals"/><property kind="parameter" name="locals"/><property kind="parameter" name="fromlist"/></properties></element>

<element kind="function" name="abs">
<description>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.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="basestring">
<description>This abstract type is the superclass for str and unicode.
It cannot be called or instantiated, but it can be used to test whether
an object is an instance of str or unicode.
isinstance(obj, basestring) is equivalent to
isinstance(obj, (str, unicode)).
New in version 2.3</description>

</element>

<element kind="function" name="bool">
<description>Convert a value to a Boolean, using the standard truth testing
procedure. If x is false or omitted, this returns
False; otherwise it returns True.
bool is also a class, which is a subclass of int.
Class bool cannot be subclassed further. Its only instances
are False and True.
New in version 2.2.1
Changed in version 2.3: If no argument is given, this function returns False</description>

<properties><property kind="parameter" name="x" required="1"/></properties></element>

<element kind="function" name="callable">
<description>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 a __call__()
method.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="chr">
<description>Return a string of one character whose ASCII code is the integer
i. For example, chr(97) returns the string 'a'.
This is the inverse of ord(). The argument must be in
the range [0..255], inclusive; ValueError will be raised
if i is outside that range.</description>

<properties><property kind="parameter" name="ii" required="1"/></properties></element>

<element kind="function" name="classmethod">
<description>Return a class method for function.
A class method receives the class as implicit first argument,
just like an instance method receives the instance.
To declare a class method, use this idiom:
class C:
def f(cls, arg1, arg2, ...): ...
f = classmethod(f)
It can be called either on the class (such as C.f()) or on an
instance (such as C().f()). The instance is ignored except for
its class.
If a class method is called for a derived class, the derived class
object is passed as the implied first argument.
Class methods are different than or Java static methods.
If you want those, see staticmethod() in this section.
New in version 2.2</description>

<properties><property kind="parameter" name="functionfunction" required="1"/></properties></element>

<element kind="function" name="cmp">
<description>Compare the two objects x and y and return an integer
according to the outcome. The return value is negative if x
&lt; y, zero if x == y and strictly positive if
x &gt; y.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y y" required="1"/></properties></element>

<element kind="function" name="compile">
<description>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 some recognizable value
if it wasn't read from a file ('&lt;string&gt;' is commonly used).
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).
When compiling multi-line statements, two caveats apply: line
endings must be represented by a single newline character
('\n'), and the input must be terminated by at least one
newline character. If line endings are represented by
'\r\n', use the string replace() method to
change them into '\n'.
The optional arguments flags and dont_inherit
(which are new in Python 2.2) control which future statements (see
236) affect the compilation of string. If neither is
present (or both are zero) the code is compiled with those future
statements that are in effect in the code that is calling compile.
If the flags argument is given and dont_inherit is not
(or is zero) then the future statements specified by the flags
argument are used in addition to those that would be used anyway.
If dont_inherit is a non-zero integer then the flags
argument is it -- the future statements in effect around the call to
compile are ignored.
Future statemants are specified by bits which can be bitwise or-ed
together to specify multiple statements. The bitfield required to
specify a given feature can be found as the compiler_flag
attribute on the _Feature instance in the
__future__ module.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="kind" required="1"/><property kind="parameter" name="flags"/><property kind="parameter" name="dont_inherit"/></properties></element>

<element kind="function" name="complex">
<description>Create a complex number with the value real + imag*j or
convert a string or number to a complex number. If the first
parameter is a string, it will be interpreted as a complex number
and the function must be called without a second parameter. The
second parameter can never be a string.
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(). If both arguments
are omitted, returns 0j.</description>

<properties><property kind="parameter" name="real" required="1"/><property kind="parameter" name="imag"/></properties></element>

<element kind="function" name="delattr">
<description>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.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="dict">
<description>Return a new dictionary initialized from an optional positional
argument or from a set of keyword arguments.
If no arguments are given, return a new empty dictionary.
If the positional argument is a mapping object, return a dictionary
mapping the same keys to the same values as does the mapping object.
Otherwise the positional argument must be a sequence, a container that
supports iteration, or an iterator object. The elements of the argument
must each also be of one of those kinds, and each must in turn contain
exactly two objects. The first is used as a key in the new dictionary,
and the second as the key's value. If a given key is seen more than
once, the last value associated with it is retained in the new
dictionary.
If keyword arguments are given, the keywords themselves with their
associated values are added as items to the dictionary. If a key
is specified both in the positional argument and as a keyword argument,
the value associated with the keyword is retained in the dictionary.
For example, these all return a dictionary equal to
{&quot;one&quot;: 2, &quot;two&quot;: 3}:
dict({'one': 2, 'two': 3})
dict({'one': 2, 'two': 3}.items())
dict({'one': 2, 'two': 3}.iteritems())
dict(zip(('one', 'two'), (2, 3)))
dict([['two', 3], ['one', 2]])
dict(one=2, two=3)
dict([(['one', 'two'][i-2], i) for i in (2, 3)])
New in version 2.2
Changed in version 2.3: Support for building a dictionary from keyword
arguments added</description>

<properties><property kind="parameter" name="mapping-or-sequence" required="1"/></properties></element>

<element kind="function" name="dir">
<description>Without arguments, return the list of names in the current local
symbol table. With an argument, attempts to return a list of valid
attributes for that object. This information is gleaned from the
object's __dict__ attribute, if defined, and from the class
or type object. The list is not necessarily complete.
If the object is a module object, the list contains the names of the
module's attributes.
If the object is a type or class object,
the list contains the names of its attributes,
and recursively of the attributes of its bases.
Otherwise, the list contains the object's attributes' names,
the names of its class's attributes,
and recursively of the attributes of its class's base classes.
The resulting list is sorted alphabetically.
For example:
&gt;&gt;&gt; import struct
&gt;&gt;&gt; dir()
['__builtins__', '__doc__', '__name__', 'struct']
&gt;&gt;&gt; dir(struct)
['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']
Because dir() is supplied primarily as a convenience
for use at an interactive prompt,
it tries to supply an interesting set of names more than it tries to
supply a rigorously or consistently defined set of names,
and its detailed behavior may change across releases.</description>

<properties><property kind="parameter" name="object" required="1"/></properties></element>

<element kind="function" name="divmod">
<description>Take two (non complex) 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 (q, a %
b), where q is usually math.floor(a /
b) but may be 1 less than that. In any case q *
b + a % b is very close to a, if
a % b is non-zero it has the same sign as
b, and 0 &lt;= abs(a % b) &lt; abs(b).
Changed in version 2.3: Using divmod() with complex numbers is
deprecated</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="enumerate">
<description>Return an enumerate object. iterable must be a sequence, an
iterator, or some other object which supports iteration. The
next() method of the iterator returned by
enumerate() returns a tuple containing a count (from
zero) and the corresponding value obtained from iterating over
iterable. enumerate() is useful for obtaining an
indexed series: (0, seq[0]), (1, seq[1]), (2,
seq[2]), ....
New in version 2.3</description>

<properties><property kind="parameter" name="iterableiterable" required="1"/></properties></element>

<element kind="function" name="eval">
<description>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 globals dictionary is present and lacks
'__builtins__', the current globals are copied into globals before
expression is parsed. This means that expression
normally has full access to the standard
__builtin__ module and restricted environments
are propagated. 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:
&gt;&gt;&gt; x = 1
&gt;&gt;&gt; print eval('x+1')
2
This function can also be used to execute arbitrary code objects
(such as those created by compile()). In this case pass
a code object instead of a string. The code object must have been
compiled passing 'eval' as 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().</description>

<properties><property kind="parameter" name="expression" required="1"/><property kind="parameter" name="globals"/><property kind="parameter" name="locals"/></properties></element>

<element kind="function" name="execfile">
<description>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.It is used relatively
rarely so does not warrant being made into a statement.
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 namespace. 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.
The default locals act as described for function
locals() below: modifications to the default locals
dictionary should not be attempted. Pass an explicit locals
dictionary if you need to see effects of the code on locals after
function execfile() returns. execfile() cannot
be used reliably to modify a function's locals.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="globals"/><property kind="parameter" name="locals"/></properties></element>

<element kind="function" name="file">
<description>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 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 (note that 'w+' truncates the file). Append
'b' to the mode to open the file in binary mode, on systems
that differentiate between binary and text files (else it is
ignored). If the file cannot be opened, IOError is
raised.
In addition to the standard fopen() values mode
may be 'U' or 'rU'. If Python is built with universal
newline support (the default) the file is opened as a text file, but
lines may be terminated by any of '\n', the Unix end-of-line
convention,
'\r', the Macintosh convention or '\r\n', the Windows
convention. All of these external representations are seen as
'\n'
by the Python program. If Python is built without universal newline support
mode 'U' is the same as normal text mode. Note that
file objects so opened also have an attribute called
newlines which has a value of None (if no newlines
have yet been seen), '\n', '\r', '\r\n', or a tuple containing all the newline types seen.
If mode is omitted, it defaults to 'r'. When opening a
binary file, you should append 'b' to the mode value
for improved portability. (It's useful even on systems which don't
treat binary and text files differently, where it serves as
documentation.)
</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="filter">
<description>Construct a list from those elements of list for which
function returns true. list may be either a sequence, a
container which supports iteration, or an iterator, 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, that is, all elements of list that are false
(zero or empty) are removed.
Note that filter(function, list) is equivalent to
[item for item in list if function(item)] if function is
not None and [item for item in list if item] if
function is None.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="list list" required="1"/></properties></element>

<element kind="function" name="float">
<description>Convert a string or a number to floating point. If the argument is a
string, it must contain a possibly signed 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. If no argument is given, returns 0.0.
When passing in a string, values for NaN</description>

<properties><property kind="parameter" name="x" required="1"/></properties></element>

<element kind="function" name="frozenset">
<description>Return a frozenset object whose elements are taken from iterable.
Frozensets are sets that have no update methods but can be hashed and
used as members of other sets or as dictionary keys. The elements of
a frozenset must be immutable themselves. To represent sets of sets,
the inner sets should also be frozenset objects. If
iterable is not specified, returns a new empty set,
frozenset([]).
New in version 2.4</description>

<properties><property kind="parameter" name="iterable" required="1"/></properties></element>

<element kind="function" name="getattr">
<description>Return the value of the named attributed of object. name
must be a string. If the string is 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. If the
named attribute does not exist, default is returned if provided,
otherwise AttributeError is raised.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="name" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="globals">
<description>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).</description>

</element>

<element kind="function" name="hasattr">
<description>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.)</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="hash">
<description>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, as is
the case for 1 and 1.0).</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="help">
<description>Invoke the built-in help system. (This function is intended for
interactive use.) If no argument is given, the interactive help
system starts on the interpreter console. If the argument is a
string, then the string is looked up as the name of a module,
function, class, method, keyword, or documentation topic, and a
help page is printed on the console. If the argument is any other
kind of object, a help page on the object is generated.
New in version 2.2</description>

<properties><property kind="parameter" name="object" required="1"/></properties></element>

<element kind="function" name="hex">
<description>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. For example, 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.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="id">
<description>Return the `identity' of an object. This is an integer (or long
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.)</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="input">
<description>Equivalent to eval(raw_input(prompt)).
This function is not safe from user errors! It
expects a valid Python expression as input; if the input is not
syntactically valid, a SyntaxError will be raised.
Other exceptions may be raised if there is an error during
evaluation. (On the other hand, sometimes this is exactly what you
need when writing a quick script for expert use.)
If the readline module was loaded, then
input() will use it to provide elaborate line editing and
history features.
Consider using the raw_input() function for general input
from users.</description>

<properties><property kind="parameter" name="prompt" required="1"/></properties></element>

<element kind="function" name="int">
<description>Convert a string or number to a plain integer. If the argument is a
string, it must contain a possibly signed decimal number
representable as a Python integer, possibly embedded in whitespace.
The radix parameter gives the base for the
conversion and may be any integer in the range [2, 36], or zero. If
radix is zero, the proper radix is guessed based on the
contents of string; the interpretation is the same as for integer
literals. If radix is specified and x is not a string,
TypeError is raised.
Otherwise, the argument may be a plain or
long integer or a floating point number. Conversion of floating
point numbers to integers truncates (towards zero).
If the argument is outside the integer range a long object will
be returned instead. If no arguments are given, returns 0.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="radix"/></properties></element>

<element kind="function" name="isinstance">
<description>Return true if the object argument is an instance of the
classinfo argument, or of a (direct or indirect) subclass
thereof. Also return true if classinfo is a type object and
object is an object of that type. If object is not a
class instance or an object of the given type, the function always
returns false. If classinfo is neither a class object nor a
type object, it may be a tuple of class or type objects, or may
recursively contain other such tuples (other sequence types are not
accepted). If classinfo is not a class, type, or tuple of
classes, types, and such tuples, a TypeError exception
is raised.
Changed in version 2.2: Support for a tuple of type information was added</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="classinfo classinfo" required="1"/></properties></element>

<element kind="function" name="issubclass">
<description>Return true if class is a subclass (direct or indirect) of
classinfo. A class is considered a subclass of itself.
classinfo may be a tuple of class objects, in which case every
entry in classinfo will be checked. In any other case, a
TypeError exception is raised.
Changed in version 2.3: Support for a tuple of type information was added</description>

<properties><property kind="parameter" name="class" required="1"/><property kind="parameter" name="classinfo classinfo" required="1"/></properties></element>

<element kind="function" name="iter">
<description>Return an iterator object. The first argument is interpreted very
differently depending on the presence of the second argument.
Without a second argument, o must be a collection object which
supports the iteration protocol (the __iter__() method), or
it must support the sequence protocol (the __getitem__()
method with integer arguments starting at 0). If it does not
support either of those protocols, TypeError is raised.
If the second argument, sentinel, is given, then o must
be a callable object. The iterator created in this case will call
o with no arguments for each call to its next()
method; if the value returned is equal to sentinel,
StopIteration will be raised, otherwise the value will
be returned.
New in version 2.2</description>

<properties><property kind="parameter" name="o" required="1"/><property kind="parameter" name="sentinel"/></properties></element>

<element kind="function" name="len">
<description>Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary).</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="list">
<description>Return a list whose items are the same and in the same order as
sequence's items. sequence may be either a sequence, a
container that supports iteration, or an iterator object. If
sequence is already a list, a copy is made and returned,
similar to sequence[:]. For instance,
list('abc') returns ['a', 'b', 'c'] and list(
(1, 2, 3) ) returns [1, 2, 3]. If no argument is given,
returns a new empty list, [].</description>

<properties><property kind="parameter" name="sequence" required="1"/></properties></element>

<element kind="function" name="locals">
<description>Update and return a dictionary representing the current local symbol table.
The contents of this dictionary should not be modified;
changes may not affect the values of local variables used by the
interpreter.</description>

</element>

<element kind="function" name="long">
<description>Convert a string or number to a long integer. If the argument is a
string, it must contain a possibly signed number of
arbitrary size, possibly embedded in whitespace;
this behaves identical to string.atol(x). The
radix argument is interpreted in the same way as for
int(), and may only be given when x is a string.
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 truncates (towards zero). If no arguments
are given, returns 0L.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="radix"/></properties></element>

<element kind="function" name="map">
<description>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 (a kind
of transpose operation). The list arguments may be any kind
of sequence; the result is always a list.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="list" required="1"/><property kind="parameter" name="... ..." required="1"/></properties></element>

<element kind="function" name="max">
<description>With a single argument s, return the largest item of a
non-empty sequence (such as a string, tuple or list). With more
than one argument, return the largest of the arguments.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="args..."/></properties></element>

<element kind="function" name="min">
<description>With a single argument s, return the smallest item of a
non-empty sequence (such as a string, tuple or list). With more
than one argument, return the smallest of the arguments.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="args..."/></properties></element>

<element kind="function" name="object">
<description>Return a new featureless object. object() is a base for all new style classes. It has the methods that are common
to all instances of new style classes.
New in version 2.2
Changed in version 2.3: This function does not accept any arguments.
Formerly, it accepted arguments but ignored them</description>

</element>

<element kind="function" name="oct">
<description>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. For example, 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.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="open">
<description>An alias for the file() function above.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="ord">
<description>Return the ASCII value of a string of one character or a Unicode
character. E.g., ord('a') returns the integer 97,
ord(u'\u2020') returns 8224. This is the inverse of
chr() for strings and of unichr() for Unicode
characters.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="pow">
<description>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
coercion rules for binary arithmetic operators apply. For int and
long int operands, the result has the same type as the operands
(after coercion) unless the second argument is negative; in that
case, all arguments are converted to float and a float result is
delivered. For example, 10**2 returns 100, but
10**-2 returns 0.01. (This last feature was added in
Python 2.2. In Python 2.1 and before, if both arguments were of integer
types and the second argument was negative, an exception was raised.)
If the second argument is negative, the third argument must be omitted.
If z is present, x and y must be of integer types,
and y must be non-negative. (This restriction was added in
Python 2.2. In Python 2.1 and before, floating 3-argument pow()
returned platform-dependent results depending on floating-point
rounding accidents.)</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="z"/></properties></element>

<element kind="function" name="property">
<description>Return a property attribute for new-style classes (classes that
derive from object).
fget is a function for getting an attribute value, likewise
fset is a function for setting, and fdel a function
for del'ing, an attribute. Typical use is to define a managed attribute x:
class C(object):
def getx(self): return self.__x
def setx(self, value): self.__x = value
def delx(self): del self.__x
x = property(getx, setx, delx, &quot;I'm the 'x' property.&quot;)
New in version 2.2</description>

<properties><property kind="parameter" name="fget" required="1"/><property kind="parameter" name="fset"/><property kind="parameter" name="fdel"/><property kind="parameter" name="doc"/></properties></element>

<element kind="function" name="range">
<description>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
ValueError is raised). Example:
&gt;&gt;&gt; range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
&gt;&gt;&gt; range(1, 11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
&gt;&gt;&gt; range(0, 30, 5)
[0, 5, 10, 15, 20, 25]
&gt;&gt;&gt; range(0, 10, 3)
[0, 3, 6, 9]
&gt;&gt;&gt; range(0, -10, -1)
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
&gt;&gt;&gt; range(0)
[]
&gt;&gt;&gt; range(1, 0)
[]
</description>

<properties><property kind="parameter" name="start" required="1"/><property kind="parameter" name="stop"/><property kind="parameter" name="step"/></properties></element>

<element kind="function" name="raw_input">
<description>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 is read, EOFError is raised. Example:
&gt;&gt;&gt; s = raw_input('--&gt; ')
--&gt; Monty Python's Flying Circus
&gt;&gt;&gt; s
&quot;Monty Python's Flying Circus&quot;
If the readline module was loaded, then
raw_input() will use it to provide elaborate
line editing and history features.</description>

<properties><property kind="parameter" name="prompt" required="1"/></properties></element>

<element kind="function" name="reduce">
<description>Apply function of two arguments cumulatively to the items of
sequence, from left to right, so as to reduce the sequence to
a single value. For example, reduce(lambda x, y: x+y, [1, 2,
3, 4, 5]) calculates ((((1+2)+3)+4)+5). The left argument,
x, is the accumulated value and the right argument, y,
is the update value from the sequence. If the optional
initializer is present, it is placed before the items of the
sequence in the calculation, and serves as a default when the
sequence is empty. If initializer is not given and
sequence contains only one item, the first item is returned.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="sequence" required="1"/><property kind="parameter" name="initializer"/></properties></element>

<element kind="function" name="reload">
<description>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 (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
many 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.</description>

<properties><property kind="parameter" name="modulemodule" required="1"/></properties></element>

<element kind="function" name="repr">
<description>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().</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="reversed">
<description>Return a reverse iterator. seq must be an object which
supports the sequence protocol (the __len__() method and the
__getitem__() method with integer arguments starting at
0).
New in version 2.4</description>

<properties><property kind="parameter" name="seqseq" required="1"/></properties></element>

<element kind="function" name="round">
<description>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. for example,
round(0.5) is 1.0 and round(-0.5) is -1.0).</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="n"/></properties></element>

<element kind="function" name="set">
<description>Return a set whose elements are taken from iterable. The elements
must be immutable. To represent sets of sets, the inner sets should
be frozenset objects. If iterable is not specified,
returns a new empty set, set([]).
New in version 2.4</description>

<properties><property kind="parameter" name="iterable" required="1"/></properties></element>

<element kind="function" name="setattr">
<description>This is the counterpart of getattr(). The arguments are an
object, a string and an arbitrary value. The string may name an
existing attribute or a new attribute. 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.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="name" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="slice">
<description>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</description>

<properties><property kind="parameter" name="start" required="1"/><property kind="parameter" name="stop"/><property kind="parameter" name="step"/></properties></element>

<element kind="function" name="sorted">
<description>Return a new sorted list from the items in iterable.
The optional arguments cmp, key, and reverse
have the same meaning as those for the list.sort() method.
New in version 2.4</description>

<properties><property kind="parameter" name="iterable" required="1"/><property default="None" kind="parameter" name="cmp"/><property default="None" kind="parameter" name="key"/><property default="False" kind="parameter" name="reverse"/></properties></element>

<element kind="function" name="staticmethod">
<description>Return a static method for function.
A static method does not receive an implicit first argument.
To declare a static method, use this idiom:
class C:
def f(arg1, arg2, ...): ...
f = staticmethod(f)
It can be called either on the class (such as C.f()) or on an
instance (such as C().f()). The instance is ignored except
for its class.
Static methods in Python are similar to those found in Java or Cpp.
For a more advanced concept, see classmethod() in this
section.
New in version 2.2</description>

<properties><property kind="parameter" name="functionfunction" required="1"/></properties></element>

<element kind="function" name="str">
<description>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. If no argument is given, returns the empty
string, ''.</description>

<properties><property kind="parameter" name="object" required="1"/></properties></element>

<element kind="function" name="sum">
<description>Sums start and the items of a sequence, from left to
right, and returns the total. start defaults to 0.
The sequence's items are normally numbers, and are not allowed
to be strings. The fast, correct way to concatenate sequence of
strings is by calling ''.join(sequence).
Note that sum(range(n), m) is equivalent to
reduce(operator.add, range(n), m)
New in version 2.3</description>

<properties><property kind="parameter" name="sequence" required="1"/><property kind="parameter" name="start"/></properties></element>

<element kind="function" name="super">
<description>Return the superclass of type. If the second argument is omitted
the super object returned is unbound. If the second argument is an
object, isinstance(obj, type) must be true. If
the second argument is a type, issubclass(type2,
type) must be true.
super() only works for new-style classes.
A typical use for calling a cooperative superclass method is:
class C(B):
def meth(self, arg):
super(C, self).meth(arg)
New in version 2.2</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="object-or-type"/></properties></element>

<element kind="function" name="tuple">
<description>Return a tuple whose items are the same and in the same order as
sequence's items. sequence may be a sequence, a
container that supports iteration, or an iterator object.
If sequence is already a tuple, it
is returned unchanged. For instance, tuple('abc') returns
('a', 'b', 'c') and tuple([1, 2, 3]) returns
(1, 2, 3). If no argument is given, returns a new empty
tuple, ().</description>

<properties><property kind="parameter" name="sequence" required="1"/></properties></element>

<element kind="function" name="type">
<description>Return the type of an object. The return value is a
typetype object. The standard module
typestypes defines names for all built-in
types that don't already have built-in names.
For instance:
&gt;&gt;&gt; import types
&gt;&gt;&gt; x = 'abc'
&gt;&gt;&gt; if type(x) is str: print &quot;It's a string&quot;
...
It's a string
&gt;&gt;&gt; def f(): pass
...
&gt;&gt;&gt; if type(f) is types.FunctionType: print &quot;It's a function&quot;
...
It's a function
The isinstance() built-in function is recommended for
testing the type of an object.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="unichr">
<description>Return the Unicode string of one character whose Unicode code is the
integer i. For example, unichr(97) returns the string
u'a'. This is the inverse of ord() for Unicode
strings. The argument must be in the range [0..65535], inclusive.
ValueError is raised otherwise.
New in version 2.0</description>

<properties><property kind="parameter" name="ii" required="1"/></properties></element>

<element kind="function" name="unicode">
<description>Return the Unicode string version of object using one of the
following modes:
If encoding and/or errors are given, unicode()
will decode the object which can either be an 8-bit string or a
character buffer using the codec for encoding. The
encoding parameter is a string giving the name of an encoding;
if the encoding is not known, LookupError is raised.
Error handling is done according to errors; this specifies the
treatment of characters which are invalid in the input encoding. If
errors is 'strict' (the default), a
ValueError is raised on errors, while a value of
'ignore' causes errors to be silently ignored, and a value of
'replace' causes the official Unicode replacement character,
U+FFFD, to be used to replace input characters which cannot
be decoded. See also the codecs module.
If no optional parameters are given, unicode() will mimic the
behaviour of str() except that it returns Unicode strings
instead of 8-bit strings. More precisely, if object is a
Unicode string or subclass it will return that Unicode string without
any additional decoding applied.
For objects which provide a __unicode__() method, it will
call this method without arguments to create a Unicode string. For
all other objects, the 8-bit string version or representation is
requested and then converted to a Unicode string using the codec for
the default encoding in 'strict' mode.
New in version 2.0
Changed in version 2.2: Support for __unicode__() added</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="encoding"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="vars">
<description>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.
In the current implementation, local variable bindings cannot
normally be affected this way, but variables retrieved from
other scopes (such as modules) can be. This may change.</description>

<properties><property kind="parameter" name="object" required="1"/></properties></element>

<element kind="function" name="xrange">
<description>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 or when all of the range's elements are never used (such as
when the loop is usually terminated with break).</description>

<properties><property kind="parameter" name="start" required="1"/><property kind="parameter" name="stop"/><property kind="parameter" name="step"/></properties></element>

<element kind="function" name="zip">
<description>This function returns a list of tuples, where the i-th tuple contains
the i-th element from each of the argument sequences.
The returned list is truncated in length to the length of
the shortest argument sequence. When there are multiple argument
sequences which are all of the same length, zip() is
similar to map() with an initial argument of None.
With a single sequence argument, it returns a list of 1-tuples.
With no arguments, it returns an empty list.
New in version 2.0
Changed in version 2.4: Formerly, zip() required at least one argument
and zip() raised a TypeError instead of returning
an empty list.</description>

<properties><property kind="parameter" name="seq1" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="apply">
<description>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 sequence. The function is
called with args as the argument list; the number of arguments
is the length of the tuple.
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 argument list.
Calling apply() is different from just calling
function(args), since in that case there is always
exactly one argument. The use of apply() is equivalent
to function(*args, **keywords).
Use of apply() is not necessary since the ``extended call
syntax,'' as used in the last example, is completely equivalent.
2.3{Use the extended call syntax instead, as described
above.}</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="args" required="1"/><property kind="parameter" name="keywords"/></properties></element>

<element kind="function" name="buffer">
<description>The object argument must be an object that supports the buffer
call interface (such as strings, arrays, and buffers). A new buffer
object will be created which references the object argument.
The buffer object will be a slice from the beginning of object
(or from the specified offset). The slice will extend to the
end of object (or will have a length given by the size
argument).</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="offset"/><property kind="parameter" name="size"/></properties></element>

<element kind="function" name="coerce">
<description>Return a tuple consisting of the two numeric arguments converted to
a common type, using the same rules as used by arithmetic
operations.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y y" required="1"/></properties></element>

<element kind="function" name="intern">
<description>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. Changed in version 2.3: Interned strings are not
immortal (like they used to be in Python 2.2 and before);
you must keep a reference to the return value of intern()
around to benefit from it</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

</group>
<group name="Built-in Types">
<description>The following sections describe the standard types that are built into
the interpreter. Historically, Python's built-in types have differed
from user-defined types because it was not possible to use the built-in
types as the basis for object-oriented inheritance. With the 2.2
release this situation has started to change, although the intended
unification of user-defined and built-in types is as yet far from
complete.
The principal built-in types are numerics, sequences, mappings, files
classes, instances and exceptions.
Some operations are supported by several object types; in particular,
all objects can be compared, tested for truth value, and converted to
a string (with the `...` notation). The latter
conversion is implicitly used when an object is written by the
printprint statement.
(Information on print statement{../ref/print.html}
and other language statements can be found in the
Python Reference Manual and the
Python Tutorial.)
</description>
<group name="Truth Value Testing">
<description>Any object can be tested for truth value, for use in an if or
while condition or as operand of the Boolean operations below.
The following values are considered false:
if
while
</description>
</group>
<group name="Boolean Operations">
<description>These are the Boolean operations, ordered by ascending priority:
{c|l|c}{code}{Operation}{Result}{Notes}
x or y
{if x is false, then y, else x}{(1)}
x and y
{if x is false, then x, else y}{(1)}
not x
{if x is false, then True, else False}{(2)}
and
or
not
Notes:
[(1)]
These only evaluate their second argument if needed for their outcome.
[(2)]
not has a lower priority than non-Boolean operators, so
not a == b is interpreted as not (a ==
b), and a == not b is a syntax error.
</description>
</group>
<group name="Comparisons">
<description>Comparison operations are supported by all objects. They all have the
same priority (which is higher than that of the Boolean operations).
Comparisons can be chained arbitrarily; for example, x &lt;
y &lt;= z is equivalent to x &lt; y and
y &lt;= z, except that y is evaluated only once (but
in both cases z is not evaluated at all when x &lt;
y is found to be false).
This table summarizes the comparison operations:
{c|l|c}{code}{Operation}{Meaning}{Notes}
&lt;{strictly less than}{}
&lt;={less than or equal}{}
&gt;{strictly greater than}{}
&gt;={greater than or equal}{}
=={equal}{}
!={not equal}{(1)}
&lt;&gt;{not equal}{(1)}
is{object identity}{}
is not{negated object identity}{}
== % XXX *All* others have funny characters &lt; ! &gt;
is
is not
Notes:
[(1)]
&lt;&gt; and != are alternate spellings for the same operator.
!= is the preferred spelling; &lt;&gt; is obsolescent.
Objects of different types, except different numeric types and different string types, never
compare equal; such objects are ordered consistently but arbitrarily
(so that sorting a heterogeneous array yields a consistent result).
Furthermore, some types (for example, file objects) support only a
degenerate notion of comparison where any two objects of that type are
unequal. Again, such objects are ordered arbitrarily but
consistently. The &lt;, &lt;=, &gt; and &gt;=
operators will raise a TypeError exception when any operand
is a complex number. Instances of a class normally compare as non-equal unless the class
(instance method){__cmp__()}
defines the __cmp__() method. Refer to the
Python Reference Manual for
information on the use of this method to effect object comparisons.
Implementation note: Objects of different types except
numbers are ordered by their type names; objects of the same types
that don't support proper comparison are ordered by their address.
Two more operations with the same syntactic priority,
inin and not innot in, are supported
only by sequence types (below).
</description>
</group>
<group name="Numeric Types">
<description>There are four distinct numeric types: plain integers,
long integers, floating point numbers, and complex numbers.
In addition, Booleans are a subtype of plain integers.
Plain integers (also just called integers)
are implemented using long in C, which gives them at least 32
bits of precision. Long integers have unlimited precision. Floating
point numbers are implemented using double in C. All bets on
their precision are off unless you happen to know the machine you are
working with.
numeric
Boolean
integer
long integer
floating point
complex number
Complex numbers have a real and imaginary part, which are each
implemented using double in C. To extract these parts from
a complex number z, use z.real and z.imag.
Numbers are created by numeric literals or as the result of built-in
functions and operators. Unadorned integer literals (including hex
and octal numbers) yield plain integers unless the value they denote
is too large to be represented as a plain integer, in which case
they yield a long integer. Integer literals with an
L or l suffix yield long integers
(L is preferred because 1l looks too much like
eleven!). Numeric literals containing a decimal point or an exponent
sign yield floating point numbers. Appending j or
J to a numeric literal yields a complex number with a
zero real part. A complex numeric literal is the sum of a real and
an imaginary part.
long{integer}{literals}
Python fully supports mixed arithmetic: when a binary arithmetic
operator has operands of different numeric types, the operand with the
``narrower'' type is widened to that of the other, where plain
integer is narrower than long integer is narrower than floating point is
narrower than complex.
Comparisons between numbers of mixed type use the same rule.
As a consequence, the list [1, 2] is considered equal
to [1.0, 2.0], and similarly for tuples.
The constructors int(), long(), float(),
and complex() can be used
to produce numbers of a specific type.
</description>
</group>
<group name="Iterator Types">
<description>New in version 2.2
</description>
<element kind="function" name="__iter__">
<description>Return an iterator object. The object is required to support the
iterator protocol described below. If a container supports
different types of iteration, additional methods can be provided to
specifically request iterators for those iteration types. (An
example of an object supporting multiple forms of iteration would be
a tree structure which supports both breadth-first and depth-first
traversal.) This method corresponds to the tp_iter slot of
the type structure for Python objects in the Python/C API.</description>

</element>

<element kind="function" name="__iter__">
<description>Return the iterator object itself. This is required to allow both
containers and iterators to be used with the for and
in statements. This method corresponds to the
tp_iter slot of the type structure for Python objects in
the Python/C API.</description>

</element>

<element kind="function" name="next">
<description>Return the next item from the container. If there are no further
items, raise the StopIteration exception. This method
corresponds to the tp_iternext slot of the type structure
for Python objects in the Python/C API.</description>

</element>

</group>
<group name="Sequence Types">
<description>There are six sequence types: strings, Unicode strings, lists,
tuples, buffers, and xrange objects.
String literals are written in single or double quotes:
'xyzzy', &quot;frobozz&quot;. See chapter 2 of the
Python Reference Manual for more about
string literals. Unicode strings are much like strings, but are
specified in the syntax using a preceeding u character:
u'abc', u&quot;def&quot;. Lists are constructed with square brackets,
separating items with commas: [a, b, c]. Tuples are
constructed by the comma operator (not within square brackets), with
or without enclosing parentheses, but an empty tuple must have the
enclosing parentheses, such as a, b, c or (). A single
item tuple must have a trailing comma, such as (d,).
sequence
string
Unicode
tuple
list
Buffer objects are not directly supported by Python syntax, but can be
created by calling the builtin function
buffer().buffer They don't support
concatenation or repetition.
buffer
Xrange objects are similar to buffers in that there is no specific
syntax to create them, but they are created using the xrange()
function.xrange They don't support slicing,
concatenation or repetition, and using in, not in,
min() or max() on them is inefficient.
xrange
Most sequence types support the following operations. The in and
not in operations have the same priorities as the comparison
operations. The + and * operations have the same
priority as the corresponding numeric operations.They must
have since the parser can't tell the type of the operands.
This table lists the sequence operations sorted in ascending priority
(operations in the same box have the same priority). In the table,
s and t are sequences of the same type; n, i
and j are integers:
{c|l|c}{code}{Operation}{Result}{Notes}
x in s{1 if an item of s is equal to x, else 0}{(1)}
x not in s{0 if an item of s is
equal to x, else 1}{(1)}
s + t{the concatenation of s and t}{}
s * n, n * s{n shallow copies of s concatenated}{(2)}
s[i]{i'th item of s, origin 0}{(3)}
s[i:j]{slice of s from i to j}{(3), (4)}
s[i:j:k]{slice of s from i to j with step k}{(3), (5)}
len(s){length of s}{}
min(s){smallest item of s}{}
max(s){largest item of s}{}
operations on{sequence}{types}
len
min
max
in
not in
Notes:
[(1)] When s is a string or Unicode string object the
in and not in operations act like a substring test. In
Python versions before 2.3, x had to be a string of length 1.
In Python 2.3 and beyond, x may be a string of any length.
[(2)] Values of n less than 0 are treated as
0 (which yields an empty sequence of the same type as
s). Note also that the copies are shallow; nested structures
are not copied. This often haunts new Python programmers; consider:
&gt;&gt;&gt; lists = [[]] * 3
&gt;&gt;&gt; lists
[[], [], []]
&gt;&gt;&gt; lists[0].append(3)
&gt;&gt;&gt; lists
[[3], [3], [3]]
What has happened is that lists is a list containing three
copies of the list [[]] (a one-element list containing an
empty list), but the contained list is shared by each copy. You can
create a list of different lists this way:
&gt;&gt;&gt; lists = [[] for i in range(3)]
&gt;&gt;&gt; lists[0].append(3)
&gt;&gt;&gt; lists[1].append(5)
&gt;&gt;&gt; lists[2].append(7)
&gt;&gt;&gt; lists
[[3], [5], [7]]
[(3)] If i or j is negative, the index is relative to
the end of the string: len(s) + i or
len(s) + j is substituted. But note that -0 is
still 0.
[(4)] The slice of s from i to j is defined as
the sequence of items with index k such that i &lt;=
k &lt; j. If i or j is greater than
len(s), use len(s). If i is omitted,
use 0. If j is omitted, use len(s). If
i is greater than or equal to j, the slice is empty.
[(5)] The slice of s from i to j with step
k is defined as the sequence of items with index x = i + n*k such that 0
&lt;= n &lt; abs(i-j). If i or j
is greater than len(s), use len(s). If
i or j are omitted then they become ``end'' values
(which end depends on the sign of k). Note, k cannot
be zero.
String Methods These are the string methods which both 8-bit strings and Unicode
objects support:
</description>
<element kind="function" name="capitalize">
<description>Return a copy of the string with only its first character capitalized.</description>

</element>

<element kind="function" name="center">
<description>Return centered in a string of length width. Padding is done
using the specified fillchar (default is a space).
Changed in version 2.4: Support for the fillchar argument</description>

<properties><property kind="parameter" name="width" required="1"/><property kind="parameter" name="fillchar"/></properties></element>

<element kind="function" name="count">
<description>Return the number of occurrences of substring sub in string
S[start:end]. Optional arguments start and
end are interpreted as in slice notation.</description>

<properties><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="decode">
<description>Decodes the string using the codec registered for encoding.
encoding defaults to the default string encoding. errors
may be given to set a different error handling scheme. The default is
'strict', meaning that encoding errors raise
ValueError. Other possible values are 'ignore' and
'replace'.
New in version 2.2</description>

<properties><property kind="parameter" name="encoding" required="1"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="encode">
<description>Return an encoded version of the string. Default encoding is the current
default string encoding. errors may be given to set a different
error handling scheme. The default for errors is
'strict', meaning that encoding errors raise a
ValueError. Other possible values are 'ignore' and
'replace'.
New in version 2.0</description>

<properties><property kind="parameter" name="encoding" required="1"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="endswith">
<description>Return True if the string ends with the specified suffix,
otherwise return False. With optional start, test beginning at
that position. With optional end, stop comparing at that position.</description>

<properties><property kind="parameter" name="suffix" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="expandtabs">
<description>Return a copy of the string where all tab characters are expanded
using spaces. If tabsize is not given, a tab size of 8
characters is assumed.</description>

<properties><property kind="parameter" name="tabsize" required="1"/></properties></element>

<element kind="function" name="find">
<description>Return the lowest index in the string where substring sub is
found, such that sub is contained in the range [start,
end). Optional arguments start and end are
interpreted as in slice notation. Return -1 if sub is
not found.</description>

<properties><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="index">
<description>Like find(), but raise ValueError when the
substring is not found.</description>

<properties><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="isalnum">
<description>Return true if all characters in the string are alphanumeric and there
is at least one character, false otherwise.</description>

</element>

<element kind="function" name="isalpha">
<description>Return true if all characters in the string are alphabetic and there
is at least one character, false otherwise.</description>

</element>

<element kind="function" name="isdigit">
<description>Return true if all characters in the string are digits and there
is at least one character, false otherwise.</description>

</element>

<element kind="function" name="islower">
<description>Return true if all cased characters in the string are lowercase and
there is at least one cased character, false otherwise.</description>

</element>

<element kind="function" name="isspace">
<description>Return true if there are only whitespace characters in the string and
there is at least one character, false otherwise.</description>

</element>

<element kind="function" name="istitle">
<description>Return true if the string is a titlecased string and there is at least one
character, for example uppercase characters may only follow uncased
characters and lowercase characters only cased ones. Return false
otherwise.</description>

</element>

<element kind="function" name="isupper">
<description>Return true if all cased characters in the string are uppercase and
there is at least one cased character, false otherwise.</description>

</element>

<element kind="function" name="join">
<description>Return a string which is the concatenation of the strings in the
sequence seq. The separator between elements is the string
providing this method.</description>

<properties><property kind="parameter" name="seqseq" required="1"/></properties></element>

<element kind="function" name="ljust">
<description>Return the string left justified in a string of length width.
Padding is done using the specified fillchar (default is a
space). The original string is returned if
width is less than len(s).
Changed in version 2.4: Support for the fillchar argument</description>

<properties><property kind="parameter" name="width" required="1"/><property kind="parameter" name="fillchar"/></properties></element>

<element kind="function" name="lower">
<description>Return a copy of the string converted to lowercase.</description>

</element>

<element kind="function" name="lstrip">
<description>Return a copy of the string with leading characters removed. If
chars is omitted or None, whitespace characters are
removed. If given and not None, chars must be a string;
the characters in the string will be stripped from the beginning of
the string this method is called on.
Changed in version 2.2.2: Support for the chars argument</description>

<properties><property kind="parameter" name="chars" required="1"/></properties></element>

<element kind="function" name="replace">
<description>Return a copy of the string with all occurrences of substring
old replaced by new. If the optional argument
count is given, only the first count occurrences are
replaced.</description>

<properties><property kind="parameter" name="old" required="1"/><property kind="parameter" name="new" required="1"/><property kind="parameter" name="count"/></properties></element>

<element kind="function" name="rfind">
<description>Return the highest index in the string where substring sub is
found, such that sub is contained within s[start,end]. Optional
arguments start and end are interpreted as in slice
notation. Return -1 on failure.</description>

<properties><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="rindex">
<description>Like rfind() but raises ValueError when the
substring sub is not found.</description>

<properties><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="rjust">
<description>Return the string right justified in a string of length width.
Padding is done using the specified fillchar (default is a space).
The original string is returned if
width is less than len(s).
Changed in version 2.4: Support for the fillchar argument</description>

<properties><property kind="parameter" name="width" required="1"/><property kind="parameter" name="fillchar"/></properties></element>

<element kind="function" name="rsplit">
<description>Return a list of the words in the string, using sep as the
delimiter string. If maxsplit is given, at most maxsplit
splits are done, the rightmost ones. If sep is not specified
or None, any whitespace string is a separator.
New in version 2.4</description>

<properties><property kind="parameter" name="sep" required="1"/><property kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="rstrip">
<description>Return a copy of the string with trailing characters removed. If
chars is omitted or None, whitespace characters are
removed. If given and not None, chars must be a string;
the characters in the string will be stripped from the end of the
string this method is called on.
Changed in version 2.2.2: Support for the chars argument</description>

<properties><property kind="parameter" name="chars" required="1"/></properties></element>

<element kind="function" name="split">
<description>Return a list of the words in the string, using sep as the
delimiter string. If maxsplit is given, at most maxsplit
splits are done. If sep is not specified or None, any
whitespace string is a separator.</description>

<properties><property kind="parameter" name="sep" required="1"/><property kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="splitlines">
<description>Return a list of the lines in the string, breaking at line
boundaries. Line breaks are not included in the resulting list unless
keepends is given and true.</description>

<properties><property kind="parameter" name="keepends" required="1"/></properties></element>

<element kind="function" name="startswith">
<description>Return True if string starts with the prefix, otherwise
return False. With optional start, test string beginning at
that position. With optional end, stop comparing string at that
position.</description>

<properties><property kind="parameter" name="prefix" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="strip">
<description>Return a copy of the string with leading and trailing characters
removed. If chars is omitted or None, whitespace
characters are removed. If given and not None, chars
must be a string; the characters in the string will be stripped from
the both ends of the string this method is called on.
Changed in version 2.2.2: Support for the chars argument</description>

<properties><property kind="parameter" name="chars" required="1"/></properties></element>

<element kind="function" name="swapcase">
<description>Return a copy of the string with uppercase characters converted to
lowercase and vice versa.</description>

</element>

<element kind="function" name="title">
<description>Return a titlecased version of the string: words start with uppercase
characters, all remaining cased characters are lowercase.</description>

</element>

<element kind="function" name="translate">
<description>Return a copy of the string where all characters occurring in the
optional argument deletechars are removed, and the remaining
characters have been mapped through the given translation table, which
must be a string of length 256.
For Unicode objects, the translate() method does not
accept the optional deletechars argument. Instead, it
returns a copy of the s where all characters have been mapped
through the given translation table which must be a mapping of
Unicode ordinals to Unicode ordinals, Unicode strings or None.
Unmapped characters are left untouched. Characters mapped to None
are deleted. Note, a more flexible approach is to create a custom
character mapping codec using the codecs module (see
encodings.cp1251 for an example).</description>

<properties><property kind="parameter" name="table" required="1"/><property kind="parameter" name="deletechars"/></properties></element>

<element kind="function" name="upper">
<description>Return a copy of the string converted to uppercase.</description>

</element>

<element kind="function" name="zfill">
<description>Return the numeric string left filled with zeros in a string
of length width. The original string is returned if
width is less than len(s).
New in version 2.2.2</description>

<properties><property kind="parameter" name="widthwidth" required="1"/></properties></element>

</group>
<group name="Set Types">
<description>set
A set object is an unordered collection of immutable values.
Common uses include membership testing, removing duplicates from a sequence,
and computing mathematical operations such as intersection, union, difference,
and symmetric difference.
New in version 2.4 Like other collections, sets support x in set,
len(set), and for x in set. Being an
unordered collection, sets do not record element position or order of
insertion. Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior. There are currently two builtin set types, set and frozenset.
The set type is mutable --- the contents can be changed using methods
like add() and remove(). Since it is mutable, it has no
hash value and cannot be used as either a dictionary key or as an element of
another set. The frozenset type is immutable and hashable --- its
contents cannot be altered after is created; however, it can be used as
a dictionary key or as an element of another set.
Instances of set and frozenset provide the following operations:
{c|c|l}{code}{Operation}{Equivalent}{Result}
len(s){}{cardinality of set s}
x in s{}
{test x for membership in s}
x not in s{}
{test x for non-membership in s}
s.issubset(t){s &lt;= t}
{test whether every element in s is in t}
s.issuperset(t){s &gt;= t}
{test whether every element in t is in s}
s.union(t){s | t}
{new set with elements from both s and t}
s.intersection(t){s t}
{new set with elements common to s and t}
s.difference(t){s - t}
{new set with elements in s but not in t}
s.symmetric_difference(t){s t}
{new set with elements in either s or t but not both}
s.copy(){}
{new set with a shallow copy of s}
Note, the non-operator versions of union(), intersection(),
difference(), and symmetric_difference(),
issubset(), and issuperset() methods will accept any
iterable as an argument. In contrast, their operator based counterparts
require their arguments to be sets. This precludes error-prone constructions
like set('abc') ' in favor of the more readable
set('abc').intersection('cbs').
Both set and frozenset support set to set comparisons.
Two sets are equal if and only if every element of each set is contained in
the other (each is a subset of the other).
A set is less than another set if and only if the first set is a proper
subset of the second set (is a subset, but is not equal).
A set is greater than another set if and only if the first set is a proper
superset of the second set (is a superset, but is not equal).
The subset and equality comparisons do not generalize to a complete
ordering function. For example, any two disjoint sets are not equal and
are not subsets of each other, so all of the following return
False: a&lt;b, a==b, or
a&gt;b.
Accordingly, sets do not implement the __cmp__ method.
Since sets only define partial ordering (subset relationships), the output
of the list.sort() method is undefined for lists of sets.
For convenience in implementing sets of sets, the __contains__(),
remove(), and discard() methods automatically match
instances of the set class their frozenset counterparts
inside a set. For example, set('abc') in set([frozenset('abc')])
returns True.
The following table lists operations available for set
that do not apply to immutable instances of frozenset:
{c|c|l}{code}{Operation}{Equivalent}{Result}
s.update(t)
{s |= t}
{return set s with elements added from t}
s.intersection_update(t)
{s t}
{return set s keeping only elements also found in t}
s.difference_update(t)
{s -= t}
{return set s after removing elements found in t}
s.symmetric_difference_update(t)
{s = t}
{return set s with elements from s or t
but not both}
s.add(x){}
{add element x to set s}
s.remove(x){}
{remove x from set s; raises KeyError if not present}
s.discard(x){}
{removes x from set s if present}
s.pop(){}
{remove and return an arbitrary element from s; raises
KeyError if empty}
s.clear(){}
{remove all elements from set s}
Note, the non-operator versions of the update(),
intersection_update(), difference_update(), and
symmetric_difference_update() methods will accept any iterable
as an argument.
</description>
</group>
<group name="Mapping Types">
<description>mapping
dictionary
A mapping object maps immutable values to
arbitrary objects. Mappings are mutable objects. There is currently
only one standard mapping type, the dictionary. A dictionary's keys are
almost arbitrary values. Only values containing lists, dictionaries
or other mutable types (that are compared by value rather than by
object identity) may not be used as keys.
Numeric types used for keys obey the normal rules for numeric
comparison: if two numbers compare equal (such as 1 and
1.0) then they can be used interchangeably to index the same
dictionary entry.
Dictionaries are created by placing a comma-separated list of
key: value pairs within braces, for example:
{'jack': 4098, 'sjoerd': 4127} or
{4098: 'jack', 4127: 'sjoerd'}.
The following operations are defined on mappings (where a and
b are mappings, k is a key, and v and x are
arbitrary objects):
operations on{mapping}{types}
operations on{dictionary}{type}
del
len
(dictionary method){
clear()
copy()
has_key()
fromkeys() items()
keys()
update()
values()
get()
setdefault()
pop()
popitem()
iteritems()
iterkeys()
itervalues()}
{c|l|c}{code}{Operation}{Result}{Notes}
len(a){the number of items in a}{}
a[k]{the item of a with key k}{(1)}
a[k] = v
{set a[k] to v}
{}
del a[k]
{remove a[k] from a}
{(1)}
a.clear(){remove all items from a}{}
a.copy(){a (shallow) copy of a}{}
a.has_key(k)
{True if a has a key k, else False}
{}
k in a
{Equivalent to a.has_key(k)}
{(2)}
k not in a
{Equivalent to not a.has_key(k)}
{(2)}
a.items()
{a copy of a's list of (key, value) pairs}
{(3)}
a.keys(){a copy of a's list of keys}{(3)}
a.update(b)
{for k in b.keys(): a[k] = b[k]}
{}
a.fromkeys(seq, value)
{Creates a new dictionary with keys from seq and values set to value}
{(7)}	a.values(){a copy of a's list of values}{(3)}
a.get(k, x)
{a[k] if k in a,
else x}
{(4)}
a.setdefault(k, x)
{a[k] if k in a,
else x (also setting it)}
{(5)}
a.pop(k, x)
{a[k] if k in a,
else x (and remove k)}
{(8)}
a.popitem()
{remove and return an arbitrary (key, value) pair}
{(6)}
a.iteritems()
{return an iterator over (key, value) pairs}
{(2), (3)}
a.iterkeys()
{return an iterator over the mapping's keys}
{(2), (3)}
a.itervalues()
{return an iterator over the mapping's values}
{(2), (3)}
Notes:
[(1)] Raises a KeyError exception if k is not
in the map.
[(2)] New in version 2.2
[(3)] Keys and values are listed in random order. If
items(), keys(), values(),
iteritems(), iterkeys(), and itervalues()
are called with no intervening modifications to the dictionary, the
lists will directly correspond. This allows the creation of
(value, key) pairs using zip():
pairs = zip(a.values(), a.keys()). The same
relationship holds for the iterkeys() and
itervalues() methods: pairs = zip(a.itervalues(),
a.iterkeys()) provides the same value for pairs.
Another way to create the same list is pairs = [(v, k) for (k,
v) in a.iteritems()].
[(4)] Never raises an exception if k is not in the map,
instead it returns x. x is optional; when x is not
provided and k is not in the map, None is returned.
[(5)] setdefault() is like get(), except
that if k is missing, x is both returned and inserted into
the dictionary as the value of k.
[(6)] popitem() is useful to destructively iterate
over a dictionary, as often used in set algorithms.
[(7)] fromkeys() is a class method that returns a
new dictionary. value defaults to None. New in version 2.3
[(8)] pop() raises a KeyError when no default
value is given and the key is not found. New in version 2.3
</description>
</group>
<group name="File Objects">
<description>File objectsfile are implemented using C's stdio
package and can be created with the built-in constructor
file()file described in section
built-in-funcs, ``Built-in Functions.''file()
is new in Python 2.2. The older built-in open() is an
alias for file().
File objects are also returned
by some other built-in functions and methods, such as
os.popen() and os.fdopen() and the
makefile() method of socket objects.
os
socket
When a file operation fails for an I/O-related reason, the exception
IOError is raised. This includes situations where the
operation is not defined for some reason, like seek() on a tty
device or writing a file opened for reading.
Files have the following methods:
</description>
<element kind="function" name="close">
<description>Close the file. A closed file cannot be read or written any more.
Any operation which requires that the file be open will raise a
ValueError after the file has been closed. Calling
close() more than once is allowed.</description>

</element>

<element kind="function" name="flush">
<description>Flush the internal buffer, like stdio's
fflush(). This may be a no-op on some file-like
objects.</description>

</element>

<element kind="function" name="fileno">
<description/>

</element>

<element kind="function" name="isatty">
<description>Return True if the file is connected to a tty(-like) device, else
False. If a file-like object is not associated
with a real file, this method should not be implemented.</description>

</element>

<element kind="function" name="next">
<description>A file object is its own iterator, for example iter(f) returns
f (unless f is closed). When a file is used as an
iterator, typically in a for loop (for example,
for line in f: print line), the next() method is
called repeatedly. This method returns the next input line, or raises
StopIteration when is hit. In order to make a
for loop the most efficient way of looping over the lines of
a file (a very common operation), the next() method uses a
hidden read-ahead buffer. As a consequence of using a read-ahead
buffer, combining next() with other file methods (like
readline()) does not work right. However, using
seek() to reposition the file to an absolute position will
flush the read-ahead buffer.
New in version 2.3</description>

</element>

<element kind="function" name="read">
<description>Read at most size bytes from the file (less if the read hits
before obtaining size bytes). If the size
argument is negative or omitted, read all data until is
reached. The bytes are returned as a string object. An empty
string is returned when is encountered immediately. (For
certain files, like ttys, it makes sense to continue reading after
an is hit.) Note that this method may call the underlying
C function fread() more than once in an effort to
acquire as close to size bytes as possible. Also note that
when in non-blocking mode, less data than what was requested may
be returned, even if no size parameter was given.</description>

<properties><property kind="parameter" name="size" required="1"/></properties></element>

<element kind="function" name="readline">
<description>Read one entire line from the file. A trailing newline character is
kept in the string
The advantage of leaving the newline on is that
returning an empty string is then an unambiguous indication. It is also possible (in cases where it might
matter, for example, if you
want to make an exact copy of a file while scanning its lines)
to tell whether the last line of a file ended in a newline
or not (yes this happens!).
(but may be absent when a file ends with an
incomplete line). If the size argument is present and
non-negative, it is a maximum byte count (including the trailing
newline) and an incomplete line may be returned.
An empty string is returned only when is encountered
immediately. Unlike stdio's fgets(), the
returned string contains null characters ('\0') if they
occurred in the input.</description>

<properties><property kind="parameter" name="size" required="1"/></properties></element>

<element kind="function" name="readlines">
<description>Read until using readline() and return a list containing
the lines thus read. If the optional sizehint argument is
present, instead of reading up to , whole lines totalling
approximately sizehint bytes (possibly after rounding up to an
internal buffer size) are read. Objects implementing a file-like
interface may choose to ignore sizehint if it cannot be
implemented, or cannot be implemented efficiently.</description>

<properties><property kind="parameter" name="sizehint" required="1"/></properties></element>

<element kind="function" name="xreadlines">
<description>This method returns the same thing as iter(f).
New in version 2.1
2.3{Use for line in file instead.}</description>

</element>

<element kind="function" name="seek">
<description>Set the file's current position, like stdio's fseek().
The whence argument is optional and defaults to 0
(absolute file positioning); other values are 1 (seek
relative to the current position) and 2 (seek relative to the
file's end). There is no return value. Note that if the file is
opened for appending (mode 'a' or 'a+'), any
seek() operations will be undone at the next write. If the
file is only opened for writing in append mode (mode 'a'),
this method is essentially a no-op, but it remains useful for files
opened in append mode with reading enabled (mode 'a+'). If the
file is opened in text mode (mode 't'), only offsets returned
by tell() are legal. Use of other offsets causes undefined
behavior.
Note that not all file objects are seekable.</description>

<properties><property kind="parameter" name="offset" required="1"/><property kind="parameter" name="whence"/></properties></element>

<element kind="function" name="tell">
<description>Return the file's current position, like stdio's
ftell().</description>

</element>

<element kind="function" name="truncate">
<description>Truncate the file's size. If the optional size argument is
present, the file is truncated to (at most) that size. The size
defaults to the current position. The current file position is
not changed. Note that if a specified size exceeds the file's
current size, the result is platform-dependent: possibilities
include that file may remain unchanged, increase to the specified
size as if zero-filled, or increase to the specified size with
undefined new content.
Availability: Windows, many variants.</description>

<properties><property kind="parameter" name="size" required="1"/></properties></element>

<element kind="function" name="write">
<description>Write a string to the file. There is no return value. Due to
buffering, the string may not actually show up in the file until
the flush() or close() method is called.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="writelines">
<description>Write a sequence of strings to the file. The sequence can be any
iterable object producing strings, typically a list of strings.
There is no return value.
(The name is intended to match readlines();
writelines() does not add line separators.)</description>

<properties><property kind="parameter" name="sequencesequence" required="1"/></properties></element>

</group>
<group name="Other Built-in Types">
<description>The interpreter supports several other kinds of objects.
Most of these support only one or two operations.
Modules The only special operation on a module is attribute access:
m.name, where m is a module and name
accesses a name defined in m's symbol table. Module attributes
can be assigned to. (Note that the import statement is not,
strictly speaking, an operation on a module object; import
foo does not require a module object named foo to exist,
rather it requires an (external) definition for a module named
foo somewhere.)
A special member of every module is __dict__.
This is the dictionary containing the module's symbol table.
Modifying this dictionary will actually change the module's symbol
table, but direct assignment to the __dict__ attribute is not
possible (you can write m.__dict__['a'] = 1, which
defines m.a to be 1, but you can't write
m.__dict__ = {}).
Modules built into the interpreter are written like this:
&lt;module 'sys' (built-in)&gt;. If loaded from a file, they are
written as &lt;module 'os' from
'/usr/local/lib/python/os.pyc'&gt;.
Classes and Class Instances Classes and Instances
See chapters 3 and 7 of the Python
Reference Manual for these.
Functions Function objects are created by function definitions. The only
operation on a function object is to call it:
func(argument-list).
There are really two flavors of function objects: built-in functions
and user-defined functions. Both support the same operation (to call
the function), but the implementation is different, hence the
different object types.
The implementation adds two special read-only attributes:
f.func_code is a function's code
objectcode (see below) and f.func_globals is
the dictionary used as the function's global namespace (this is the
same as m.__dict__ where m is the module in which
the function f was defined).
Function objects also support getting and setting arbitrary
attributes, which can be used, for example, to attach metadata to
functions. Regular attribute dot-notation is used to get and set such
attributes. Note that the current implementation only supports
function attributes on user-defined functions. Function attributes on
built-in functions may be supported in the future.
Functions have another special attribute f.__dict__
(a.k.a. f.func_dict) which contains the namespace used to
support function attributes. __dict__ and func_dict can
be accessed directly or set to a dictionary object. A function's
dictionary cannot be deleted.
Methods method
Methods are functions that are called using the attribute notation.
There are two flavors: built-in methods (such as append() on
lists) and class instance methods. Built-in methods are described
with the types that support them.
The implementation adds two special read-only attributes to class
instance methods: m.im_self is the object on which the
method operates, and m.im_func is the function
implementing the method. Calling m(arg-1,
arg-2, ..., arg-n) is completely equivalent to
calling m.im_func(m.im_self, arg-1,
arg-2, ..., arg-n).
Class instance methods are either bound or unbound,
referring to whether the method was accessed through an instance or a
class, respectively. When a method is unbound, its im_self
attribute will be None and if called, an explicit self
object must be passed as the first argument. In this case,
self must be an instance of the unbound method's class (or a
subclass of that class), otherwise a TypeError is raised.
Like function objects, methods objects support getting
arbitrary attributes. However, since method attributes are actually
stored on the underlying function object (meth.im_func),
setting method attributes on either bound or unbound methods is
disallowed. Attempting to set a method attribute results in a
TypeError being raised. In order to set a method attribute,
you need to explicitly set it on the underlying function object:
class C:
def method(self):
pass
c = C()
c.method.im_func.whoami = 'my name is c'
See the Python Reference Manual for more
information.
Code Objects code
Code objects are used by the implementation to represent
``pseudo-compiled'' executable Python code such as a function body.
They differ from function objects because they don't contain a
reference to their global execution environment. Code objects are
returned by the built-in compile() function and can be
extracted from function objects through their func_code
attribute.
compile
(function object attribute){func_code}
A code object can be executed or evaluated by passing it (instead of a
source string) to the exec statement or the built-in
eval() function.
exec
eval
See the Python Reference Manual for more
information.
Type Objects Type objects represent the various object types. An object's type is
accessed by the built-in function type(). There are no special
operations on types. The standard module types defines names
for all standard built-in types.
type
types
Types are written like this: &lt;type 'int'&gt;.
The Null Object This object is returned by functions that don't explicitly return a
value. It supports no special operations. There is exactly one null
object, named None (a built-in name).
It is written as None.
The Ellipsis Object This object is used by extended slice notation (see the
Python Reference Manual). It supports no
special operations. There is exactly one ellipsis object, named
Ellipsis (a built-in name).
It is written as Ellipsis.
Boolean Values
Boolean values are the two constant objects False and
True. They are used to represent truth values (although other
values can also be considered false or true). In numeric contexts
(for example when used as the argument to an arithmetic operator),
they behave like the integers 0 and 1, respectively. The built-in
function bool() can be used to cast any value to a Boolean,
if the value can be interpreted as a truth value (see section Truth
Value Testing above).
They are written as False and True, respectively.
</description>
</group>
<group name="Special Attributes">
</group>
</group>
<group name="Built-in Exceptions">
</group>
</group>
<group name="Python Runtime Services">
<group name="sys --- System-specific parameters and functions">
<description>Access system-specific parameters and functions.
This module provides access to some variables used or maintained by the
interpreter and to functions that interact strongly with the interpreter.
It is always available.
{argv}
The list of command line arguments passed to a Python script.
argv[0] is the script name (it is operating system dependent
whether this is a full pathname or not). If the command was
executed using the -c command line option to the
interpreter, argv[0] is set to the string '-c'. If no
script name was passed to the Python interpreter, argv has
zero length.
{byteorder}
An indicator of the native byte order. This will have the value
'big' on big-endian (most-signigicant byte first) platforms,
and 'little' on little-endian (least-significant byte first)
platforms.
New in version 2.0
{builtin_module_names}
A tuple of strings giving the names of all modules that are compiled
into this Python interpreter. (This information is not available in
any other way --- modules.keys() only lists the imported
modules.)
{copyright}
A string containing the copyright pertaining to the Python
interpreter.
{dllhandle}
Integer specifying the handle of the Python DLL.
Availability: Windows.
</description>
<element kind="function" name="displayhook">
<description>If value is not None, this function prints it to
sys.stdout, and saves it in __builtin__._.
sys.displayhook is called on the result of evaluating an
expression entered in an interactive Python session. The display of
these values can be customized by assigning another one-argument
function to sys.displayhook.</description>

<properties><property kind="parameter" name="value" required="1"/></properties></element>

<element kind="function" name="excepthook">
<description>This function prints out a given traceback and exception to
sys.stderr.
When an exception is raised and uncaught, the interpreter calls
sys.excepthook with three arguments, the exception class,
exception instance, and a traceback object. In an interactive
session this happens just before control is returned to the prompt;
in a Python program this happens just before the program exits. The
handling of such top-level exceptions can be customized by assigning
another three-argument function to sys.excepthook.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="value" required="1"/><property kind="parameter" name="traceback" required="1"/></properties></element>

<element kind="function" name="exc_info">
<description>This function returns a tuple of three values that give information
about the exception that is currently being handled. The
information returned is specific both to the current thread and to
the current stack frame. If the current stack frame is not handling
an exception, the information is taken from the calling stack frame,
or its caller, and so on until a stack frame is found that is
handling an exception. Here, ``handling an exception'' is defined
as ``executing or having executed an except clause.'' For any stack
frame, only information about the most recently handled exception is
accessible.
If no exception is being handled anywhere on the stack, a tuple
containing three None values is returned. Otherwise, the
values returned are (type, value,
traceback). Their meaning is: type gets the exception
type of the exception being handled (a class object);
value gets the exception parameter (its associated value
or the second argument to raise, which is always a class
instance if the exception type is a class object); traceback
gets a traceback object (see the Reference Manual) which
encapsulates the call stack at the point where the exception
originally occurred. traceback
If exc_clear() is called, this function will return three
None values until either another exception is raised in the
current thread or the execution stack returns to a frame where
another exception is being handled.
Assigning the traceback return value to a
local variable in a function that is handling an exception will
cause a circular reference. This will prevent anything referenced
by a local variable in the same function or by the traceback from
being garbage collected. Since most functions don't need access to
the traceback, the best solution is to use something like
exctype, value = sys.exc_info()[:2] to extract only the
exception type and value. If you do need the traceback, make sure
to delete it after use (best done with a try
... finally statement) or to call exc_info() in
a function that does not itself handle an exception. Beginning
with Python 2.2, such cycles are automatically reclaimed when garbage
collection is enabled and they become unreachable, but it remains more
efficient to avoid creating cycles.</description>

</element>

<element kind="function" name="exc_clear">
<description>This function clears all information relating to the current or last
exception that occured in the current thread. After calling this
function, exc_info() will return three None values until
another exception is raised in the current thread or the execution stack
returns to a frame where another exception is being handled.
This function is only needed in only a few obscure situations. These
include logging and error handling systems that report information on the
last or current exception. This function can also be used to try to free
resources and trigger object finalization, though no guarantee is made as
to what objects will be freed, if any.
New in version 2.3</description>

</element>

<element kind="function" name="exit">
<description>Exit from Python. This is implemented by raising the
SystemExit exception, so cleanup actions specified by
finally clauses of try statements are honored, and it is
possible to intercept the exit attempt at an outer level. The
optional argument arg can be an integer giving the exit status
(defaulting to zero), or another type of object. If it is an
integer, zero is considered ``successful termination'' and any
nonzero value is considered ``abnormal termination'' by shells and
the like. Most systems require it to be in the range 0-127, and
produce undefined results otherwise. Some systems have a convention
for assigning specific meanings to specific exit codes, but these
are generally underdeveloped; programs generally use 2 for
command line syntax errors and 1 for all other kind of errors. If
another type of object is passed, None is equivalent to
passing zero, and any other object is printed to sys.stderr
and results in an exit code of 1. In particular,
sys.exit(&quot;some error message&quot;) is a quick way to exit a
program when an error occurs.</description>

<properties><property kind="parameter" name="arg" required="1"/></properties></element>

<element kind="function" name="getcheckinterval">
<description>Return the interpreter's ``check interval'';
see setcheckinterval().
New in version 2.3</description>

</element>

<element kind="function" name="getdefaultencoding">
<description>Return the name of the current default string encoding used by the
Unicode implementation.
New in version 2.0</description>

</element>

<element kind="function" name="getdlopenflags">
<description>Return the current value of the flags that are used for
dlopen() calls. The flag constants are defined in the
dl and DLFCN modules.
Availability: .
New in version 2.2</description>

</element>

<element kind="function" name="getfilesystemencoding">
<description>Return the name of the encoding used to convert Unicode filenames
into system file names, or None if the system default encoding
is used. The result value depends on the operating system:
On Windows 9x, the encoding is ``mbcs''.
On Mac OS X, the encoding is ``utf-8''.
On Unix, the encoding is the user's preference according to the result of nl_langinfo(CODESET), or None if
the nl_langinfo(CODESET) failed.
On Windows NT+, file names are Unicode natively, so no conversion
is performed.
New in version 2.3</description>

</element>

<element kind="function" name="getrefcount">
<description>Return the reference count of the object. The count returned
is generally one higher than you might expect, because it includes
the (temporary) reference as an argument to
getrefcount().</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getrecursionlimit">
<description>Return the current value of the recursion limit, the maximum depth
of the Python interpreter stack. This limit prevents infinite
recursion from causing an overflow of the C stack and crashing
Python. It can be set by setrecursionlimit().</description>

</element>

<element kind="function" name="_getframe">
<description>Return a frame object from the call stack. If optional integer
depth is given, return the frame object that many calls below
the top of the stack. If that is deeper than the call stack,
ValueError is raised. The default for depth is
zero, returning the frame at the top of the call stack.
This function should be used for internal and specialized purposes
only.</description>

<properties><property kind="parameter" name="depth" required="1"/></properties></element>

<element kind="function" name="getwindowsversion">
<description>Return a tuple containing five components, describing the Windows version currently running. The elements are major, minor, build, platform, and text. text contains
a string while all other values are integers.
platform may be one of the following values:
{}{ 0.7in 0.65in}
[0 (VER_PLATFORM_WIN32s)]
Win32s on Windows 3.1.
[1 (VER_PLATFORM_WIN32_WINDOWS)] Windows 95/98/ME
[2 (VER_PLATFORM_WIN32_NT)] Windows NT/2000/XP
[3 (VER_PLATFORM_WIN32_CE)] Windows CE.
This function wraps the Win32 GetVersionEx() function;
see the Microsoft Documentation for more information about these
fields.
Availability: Windows.
New in version 2.3</description>

</element>

<element kind="function" name="setcheckinterval">
<description>Set the interpreter's ``check interval''. This integer value
determines how often the interpreter checks for periodic things such
as thread switches and signal handlers. The default is 100,
meaning the check is performed every 100 Python virtual instructions.
Setting it to a larger value may increase performance for programs
using threads. Setting it to a value &lt;= 0 checks every
virtual instruction, maximizing responsiveness as well as overhead.</description>

<properties><property kind="parameter" name="intervalinterval" required="1"/></properties></element>

<element kind="function" name="setdefaultencoding">
<description>Set the current default string encoding used by the Unicode
implementation. If name does not match any available
encoding, LookupError is raised. This function is only
intended to be used by the site module implementation
and, where needed, by sitecustomize. Once used by the
site module, it is removed from the sys
module's namespace.
% Note that site is not imported if
% the -S option is passed to the interpreter, in which
% case this function will remain available.
New in version 2.0</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="setdlopenflags">
<description>Set the flags used by the interpreter for dlopen()
calls, such as when the interpreter loads extension modules. Among
other things, this will enable a lazy resolving of symbols when
importing a module, if called as sys.setdlopenflags(0). To
share symbols across extension modules, call as
sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL). Symbolic
names for the flag modules can be either found in the dl
module, or in the DLFCN module. If DLFCN is not
available, it can be generated from /usr/include/dlfcn.h
using the h2py script.
Availability: .
New in version 2.2</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="setprofile">
<description>Set the system's profile function,</description>

<properties><property kind="parameter" name="profilefuncprofilefunc" required="1"/></properties></element>

<element kind="function" name="setrecursionlimit">
<description>Set the maximum depth of the Python interpreter stack to
limit. This limit prevents infinite recursion from causing an
overflow of the C stack and crashing Python.
The highest possible limit is platform-dependent. A user may need
to set the limit higher when she has a program that requires deep
recursion and a platform that supports a higher limit. This should
be done with care, because a too-high limit can lead to a crash.</description>

<properties><property kind="parameter" name="limitlimit" required="1"/></properties></element>

<element kind="function" name="settrace">
<description>Set the system's trace function,</description>

<properties><property kind="parameter" name="tracefunctracefunc" required="1"/></properties></element>

</group>
<group name="gc --- Garbage Collector interface">
<description>Interface to the cycle-detecting garbage collector.
The gc module is only available if the interpreter was built
with the optional cyclic garbage detector (enabled by default). If
this was not enabled, an ImportError is raised by attempts
to import this module.
This module provides an interface to the optional garbage collector. It
provides the ability to disable the collector, tune the collection
frequency, and set debugging options. It also provides access to
unreachable objects that the collector found but cannot free. Since the
collector supplements the reference counting already used in Python, you
can disable the collector if you are sure your program does not create
reference cycles. Automatic collection can be disabled by calling
gc.disable(). To debug a leaking program call
gc.set_debug(gc.DEBUG_LEAK).
The gc module provides the following functions:
</description>
<element kind="function" name="enable">
<description>Enable automatic garbage collection.</description>

</element>

<element kind="function" name="disable">
<description>Disable automatic garbage collection.</description>

</element>

<element kind="function" name="isenabled">
<description>Returns true if automatic collection is enabled.</description>

</element>

<element kind="function" name="collect">
<description>Run a full collection. All generations are examined and the
number of unreachable objects found is returned.</description>

</element>

<element kind="function" name="set_debug">
<description>Set the garbage collection debugging flags.
Debugging information will be written to sys.stderr. See below
for a list of debugging flags which can be combined using bit
operations to control debugging.</description>

<properties><property kind="parameter" name="flagsflags" required="1"/></properties></element>

<element kind="function" name="get_debug">
<description>Return the debugging flags currently set.</description>

</element>

<element kind="function" name="get_objects">
<description>Returns a list of all objects tracked by the collector, excluding the
list returned.
New in version 2.2</description>

</element>

<element kind="function" name="set_threshold">
<description>Set the garbage collection thresholds (the collection frequency).
Setting threshold0 to zero disables collection.
The GC classifies objects into three generations depending on how many
collection sweeps they have survived. New objects are placed in the
youngest generation (generation 0). If an object survives a
collection it is moved into the next older generation. Since
generation 2 is the oldest generation, objects in that
generation remain there after a collection. In order to decide when
to run, the collector keeps track of the number object allocations and
deallocations since the last collection. When the number of
allocations minus the number of deallocations exceeds
threshold0, collection starts. Initially only generation
0 is examined. If generation 0 has been examined more
than threshold1 times since generation 1 has been
examined, then generation 1 is examined as well. Similarly,
threshold2 controls the number of collections of generation
1 before collecting generation 2.</description>

<properties><property kind="parameter" name="threshold0" required="1"/><property kind="parameter" name="threshold1"/><property kind="parameter" name="threshold2"/></properties></element>

<element kind="function" name="get_threshold">
<description>Return the current collection thresholds as a tuple of
(threshold0, threshold1, threshold2).</description>

</element>

<element kind="function" name="get_referrers">
<description>Return the list of objects that directly refer to any of objs. This
function will only locate those containers which support garbage
collection; extension types which do refer to other objects but do not
support garbage collection will not be found.
Note that objects which have already been dereferenced, but which live
in cycles and have not yet been collected by the garbage collector can
be listed among the resulting referrers. To get only currently live
objects, call collect() before calling
get_referrers().
Care must be taken when using objects returned by
get_referrers() because some of them could still be under
construction and hence in a temporarily invalid state. Avoid using
get_referrers() for any purpose other than debugging.
New in version 2.2</description>

<properties><property kind="parameter" name="*objs*objs" required="1"/></properties></element>

<element kind="function" name="get_referents">
<description>Return a list of objects directly referred to by any of the arguments.
The referents returned are those objects visited by the arguments'
C-level tp_traverse methods (if any), and may not be all
objects actually directly reachable. tp_traverse methods
are supported only by objects that support garbage collection, and are
only required to visit objects that may be involved in a cycle. So,
for example, if an integer is directly reachable from an argument, that
integer object may or may not appear in the result list.
New in version 2.3</description>

<properties><property kind="parameter" name="*objs*objs" required="1"/></properties></element>

</group>
<group name="weakref --- Weak references">
<description>Support for weak references and weak dictionaries.
New in version 2.1
The weakref module allows the Python programmer to create
weak references to objects.
In the following, the term referent means the
object which is referred to by a weak reference.
A weak reference to an object is not enough to keep the object alive:
when the only remaining references to a referent are weak references,
garbage collection is free to destroy the referent and reuse its memory
for something else. A primary use for weak references is to implement
caches or mappings holding large objects, where it's desired that a
large object not be kept alive solely because it appears in a cache or
mapping. For example, if you have a number of large binary image objects,
you may wish to associate a name with each. If you used a Python
dictionary to map names to images, or images to names, the image objects
would remain alive just because they appeared as values or keys in the
dictionaries. The WeakKeyDictionary and
WeakValueDictionary classes supplied by the weakref
module are an alternative, using weak references to construct mappings
that don't keep objects alive solely because they appear in the mapping
objects. If, for example, an image object is a value in a
WeakValueDictionary, then when the last remaining
references to that image object are the weak references held by weak
mappings, garbage collection can reclaim the object, and its corresponding
entries in weak mappings are simply deleted.
WeakKeyDictionary and WeakValueDictionary use weak
references in their implementation, setting up callback functions on
the weak references that notify the weak dictionaries when a key or value
has been reclaimed by garbage collection. Most programs should find that
using one of these weak dictionary types is all they need -- it's
not usually necessary to create your own weak references directly. The
low-level machinery used by the weak dictionary implementations is exposed
by the weakref module for the benefit of advanced uses.
Not all objects can be weakly referenced; those objects which can
include class instances, functions written in Python (but not in C),
and methods (both bound and unbound). Extension types can easily
be made to support weak references; see section weakref-extension,
``Weak References in Extension Types,'' for more information.
</description>
<element kind="function" name="ref">
<description>Return a weak reference to object. The original object can be
retrieved by calling the reference object if the referent is still
alive; if the referent is no longer alive, calling the reference
object will cause None to be returned. If callback is
provided, it will be called when the object is about to be
finalized; the weak reference object will be passed as the only
parameter to the callback; the referent will no longer be available.
It is allowable for many weak references to be constructed for the
same object. Callbacks registered for each weak reference will be
called from the most recently registered callback to the oldest
registered callback.
Exceptions raised by the callback will be noted on the standard
error output, but cannot be propagated; they are handled in exactly
the same way as exceptions raised from an object's
__del__() method.
Weak references are hashable if the object is hashable. They
will maintain their hash value even after the object was
deleted. If hash() is called the first time only after
the object was deleted, the call will raise
TypeError.
Weak references support tests for equality, but not ordering. If
the referents are still alive, two references have the same
equality relationship as their referents (regardless of the
callback). If either referent has been deleted, the
references are equal only if the reference objects are the same
object.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="callback"/></properties></element>

<element kind="function" name="proxy">
<description>Return a proxy to object which uses a weak reference. This
supports use of the proxy in most contexts instead of requiring the
explicit dereferencing used with weak reference objects. The
returned object will have a type of either ProxyType or
CallableProxyType, depending on whether object is
callable. Proxy objects are not hashable regardless of the
referent; this avoids a number of problems related to their
fundamentally mutable nature, and prevent their use as dictionary
keys. callback is the same as the parameter of the same name
to the ref() function.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="callback"/></properties></element>

<element kind="function" name="getweakrefcount">
<description>Return the number of weak references and proxies which refer to
object.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getweakrefs">
<description>Return a list of all weak reference and proxy objects which refer to
object.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="WeakKeyDictionary">
<description>Mapping class that references keys weakly. Entries in the
dictionary will be discarded when there is no longer a strong
reference to the key. This can be used to associate additional data
with an object owned by other parts of an application without adding
attributes to those objects. This can be especially useful with
objects that override attribute accesses.
Caution: Because a WeakKeyDictionary is built on top
of a Python dictionary, it must not change size when iterating
over it. This can be difficult to ensure for a
WeakKeyDictionary because actions performed by the
program during iteration may cause items in the dictionary
to vanish &quot;by magic&quot; (as a side effect of garbage collection).</description>

<properties><property kind="parameter" name="dict" required="1"/></properties></element>

<element kind="function" name="WeakValueDictionary">
<description>Mapping class that references values weakly. Entries in the
dictionary will be discarded when no strong reference to the value
exists any more.
Caution: Because a WeakValueDictionary is built on top
of a Python dictionary, it must not change size when iterating
over it. This can be difficult to ensure for a
WeakValueDictionary because actions performed by the
program during iteration may cause items in the dictionary
to vanish &quot;by magic&quot; (as a side effect of garbage collection).</description>

<properties><property kind="parameter" name="dict" required="1"/></properties></element>

<group name="Weak Reference Objects">
<description>Weak reference objects have no attributes or methods, but do allow the
referent to be obtained, if it still exists, by calling it:
&gt;&gt;&gt; import weakref
&gt;&gt;&gt; class Object:
... pass
...
&gt;&gt;&gt; o = Object()
&gt;&gt;&gt; r = weakref.ref(o)
&gt;&gt;&gt; o2 = r()
&gt;&gt;&gt; o is o2
True
If the referent no longer exists, calling the reference object returns
None:
&gt;&gt;&gt; del o, o2
&gt;&gt;&gt; print r()
None
Testing that a weak reference object is still live should be done
using the expression ref() is not None. Normally,
application code that needs to use a reference object should follow
this pattern:
# r is a weak reference object
o = r()
if o is None:
# referent has been garbage collected
print &quot;Object has been allocated; can't frobnicate.&quot;
else:
print &quot;Object is still live!&quot;
o.do_something_useful()
Using a separate test for ``liveness'' creates race conditions in
threaded applications; another thread can cause a weak reference to
become invalidated before the weak reference is called; the
idiom shown above is safe in threaded applications as well as
single-threaded applications.
</description>
</group>
<group name="Example">
<description>This simple example shows how an application can use objects IDs to
retrieve objects that it has seen before. The IDs of the objects can
then be used in other data structures without forcing the objects to
remain alive, but the objects can still be retrieved by ID if they
do.
% Example contributed by Tim Peters &lt;tim_one@msn.com&gt;.
import weakref
_id2obj_dict = weakref.WeakValueDictionary()
def remember(obj):
oid = id(obj)
_id2obj_dict[oid] = obj
return oid
def id2obj(oid):
return _id2obj_dict[oid]
</description>
</group>
<group name="Weak References in Extension Types">
</group>
</group>
<group name="fpectl --- Floating point exception control">
<description>Unix
Provide control for floating point exception handling.
Most computers carry out floating point operations</description>
<element kind="function" name="turnon_sigfpe">
<description>Turn on the generation of SIGFPE,
and set up an appropriate signal handler.</description>

</element>

<element kind="function" name="turnoff_sigfpe">
<description>Reset default handling of floating point exceptions.</description>

</element>

<group name="Example">
<description>The following example demonstrates how to start up and test operation of
the fpectl module.
&gt;&gt;&gt; import fpectl
&gt;&gt;&gt; import fpetest
&gt;&gt;&gt; fpectl.turnon_sigfpe()
&gt;&gt;&gt; fpetest.test()
overflow PASS
FloatingPointError: Overflow
div by 0 PASS
FloatingPointError: Division by zero
[ more output from test elided ]
&gt;&gt;&gt; import math
&gt;&gt;&gt; math.exp(1000)
Traceback (most recent call last):
File &quot;&lt;stdin&gt;&quot;, line 1, in ?
FloatingPointError: in math_1
</description>
</group>
<group name="Limitations and other considerations">
</group>
</group>
<group name="atexit --- Exit handlers">
<description>Register and execute cleanup functions.
New in version 2.0
The atexit module defines a single function to register
cleanup functions. Functions thus registered are automatically
executed upon normal interpreter termination.
Note: the functions registered via this module are not called when the program is killed by a
signal, when a Python fatal internal error is detected, or when
os._exit() is called.
This is an alternate interface to the functionality provided by the
sys.exitfunc variable.
(in sys){exitfunc}
Note: This module is unlikely to work correctly when used with other code
that sets sys.exitfunc. In particular, other core Python modules are
free to use atexit without the programmer's knowledge. Authors who
use sys.exitfunc should convert their code to use
atexit instead. The simplest way to convert code that sets
sys.exitfunc is to import atexit and register the function
that had been bound to sys.exitfunc.
</description>
<element kind="function" name="register">
<description>Register func as a function to be executed at termination. Any
optional arguments that are to be passed to func must be passed
as arguments to register().
At normal program termination (for instance, if
sys.exit() is called or the main module's execution
completes), all functions registered are called in last in, first out
order. The assumption is that lower level modules will normally be
imported before higher level modules and thus must be cleaned up
later.</description>

<properties><property kind="parameter" name="func" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kargs"/></properties></element>

<group name="atexit Example">
</group>
</group>
<group name="types --- Names for built-in types">
</group>
<group name="UserDict --- Class wrapper for dictionary objects">
<description>Class wrapper for dictionary objects.
This module is available for backward compatibility only. If
you are writing code that does not need to work with versions of
Python earlier than Python 2.2, please consider subclassing directly
from the built-in dict type.
This module defines a class that acts as a wrapper around
dictionary objects. It is a useful base class for
your own dictionary-like classes, which can inherit from
them and override existing methods or add new ones. In this way one
can add new behaviors to dictionaries.
The module also defines a mixin defining all dictionary methods for
classes that already have a minimum mapping interface. This greatly
simplifies writing classes that need to be substitutable for
dictionaries (such as the shelve module).
The UserDict module defines the UserDict class
and DictMixin:
</description>
<element kind="function" name="UserDict">
<description>Class that simulates a dictionary. The instance's
contents are kept in a regular dictionary, which is accessible via the
data attribute of UserDict instances. If
initialdata is provided, data is initialized with its
contents; note that a reference to initialdata will not be kept, allowing it be used for other purposes.</description>

<properties><property kind="parameter" name="initialdata" required="1"/></properties></element>

<element kind="function" name="DictMixin">
<description>Mixin defining all dictionary methods for classes that already have
a minimum dictionary interface including __getitem__(),
__setitem__(), __delitem__(), and keys().
This mixin should be used as a superclass. Adding each of the
above methods adds progressively more functionality. For instance,
defining all but __delitem__ will preclude only pop
and popitem from the full interface.
In addition to the four base methods, progessively more efficiency
comes with defining __contains__(), __iter__(), and
iteritems().
Since the mixin has no knowledge of the subclass constructor, it
does not define __init__() or copy().</description>

</element>

<element kind="function" name="UserList">
<description>Class that simulates a list. The instance's
contents are kept in a regular list, which is accessible via the
data attribute of UserList instances. The instance's
contents are initially set to a copy of list, defaulting to the
empty list []. list can be either a regular Python list,
or an instance of UserList (or a subclass).</description>

<properties><property kind="parameter" name="list" required="1"/></properties></element>

<element kind="function" name="UserString">
<description>Class that simulates a string or a Unicode string
object. The instance's content is kept in a regular string or Unicode
string object, which is accessible via the data attribute of
UserString instances. The instance's contents are initially
set to a copy of sequence. sequence can be either a
regular Python string or Unicode string, an instance of
UserString (or a subclass) or an arbitrary sequence which can
be converted into a string using the built-in str() function.</description>

<properties><property kind="parameter" name="sequence" required="1"/></properties></element>

<element kind="function" name="MutableString">
<description>This class is derived from the UserString above and redefines
strings to be mutable. Mutable strings can't be used as
dictionary keys, because dictionaries require immutable objects as
keys. The main intention of this class is to serve as an educational
example for inheritance and necessity to remove (override) the
__hash__() method in order to trap attempts to use a
mutable object as dictionary key, which would be otherwise very
error prone and hard to track down.</description>

<properties><property kind="parameter" name="sequence" required="1"/></properties></element>

</group>
<group name="operator --- Standard operators as functions.">
<description>All Python's standard operators as built-in functions.
The operator module exports a set of functions implemented in C
corresponding to the intrinsic operators of Python. For example,
operator.add(x, y) is equivalent to the expression x+y. The
function names are those used for special class methods; variants without
leading and trailing __ are also provided for convenience.
The functions fall into categories that perform object comparisons,
logical operations, mathematical operations, sequence operations, and
abstract type tests.
The object comparison functions are useful for all objects, and are
named after the rich comparison operators they support:
</description>
<element kind="function" name="lt">
<description>le{a, b}
eq{a, b}
ne{a, b}
ge{a, b}
gt{a, b}
__lt__{a, b}
__le__{a, b}
__eq__{a, b}
__ne__{a, b}
__ge__{a, b}
__gt__{a, b}
Perform ``rich comparisons'' between a and b. Specifically,
lt(a, b) is equivalent to a &lt; b,
le(a, b) is equivalent to a &lt;= b,
eq(a, b) is equivalent to a == b,
ne(a, b) is equivalent to a != b,
gt(a, b) is equivalent to a &gt; b
and
ge(a, b) is equivalent to a &gt;= b.
Note that unlike the built-in cmp(), these functions can
return any value, which may or may not be interpretable as a Boolean
value. See the Python Reference Manual
for more informations about rich comparisons.
New in version 2.2</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="not_">
<description>__not__{o}
Return the outcome of not o. (Note that there is no
__not__() method for object instances; only the interpreter
core defines this operation. The result is affected by the
__nonzero__() and __len__() methods.)</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="truth">
<description>Return True if o is true, and False
otherwise. This is equivalent to using the bool
constructor.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="is_">
<description>Return a is b. Tests object identity.
New in version 2.3</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="is_not">
<description>Return a is not b. Tests object identity.
New in version 2.3</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="abs">
<description>__abs__{o}
Return the absolute value of o.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="add">
<description>__add__{a, b}
Return a + b, for a and b numbers.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="and_">
<description>__and__{a, b}
Return the bitwise and of a and b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="div">
<description>__div__{a, b}
Return a / b when __future__.division is not
in effect. This is also known as ``classic'' division.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="floordiv">
<description>__floordiv__{a, b}
Return a // b.
New in version 2.2</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="inv">
<description>invert{o}
__inv__{o}
__invert__{o}
Return the bitwise inverse of the number o. This is equivalent
to o. The names invert() and
__invert__() were added in Python 2.0.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="lshift">
<description>__lshift__{a, b}
Return a shifted left by b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="mod">
<description>__mod__{a, b}
Return a % b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="mul">
<description>__mul__{a, b}
Return a * b, for a and b numbers.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="neg">
<description>__neg__{o}
Return o negated.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="or_">
<description>__or__{a, b}
Return the bitwise or of a and b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="pos">
<description>__pos__{o}
Return o positive.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="pow">
<description>__pow__{a, b}
Return a ** b, for a and b numbers.
New in version 2.3</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="rshift">
<description>__rshift__{a, b}
Return a shifted right by b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="sub">
<description>__sub__{a, b}
Return a - b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="truediv">
<description>__truediv__{a, b}
Return a / b when __future__.division is in
effect. This is also known as division.
New in version 2.2</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="xor">
<description>__xor__{a, b}
Return the bitwise exclusive or of a and b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="concat">
<description>__concat__{a, b}
Return a + b for a and b sequences.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="contains">
<description>__contains__{a, b}
Return the outcome of the test b in a.
Note the reversed operands. The name __contains__() was
added in Python 2.0.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="countOf">
<description>Return the number of occurrences of b in a.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="delitem">
<description>__delitem__{a, b}
Remove the value of a at index b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="delslice">
<description>__delslice__{a, b, c}
Delete the slice of a from index b to index c-1.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="c c" required="1"/></properties></element>

<element kind="function" name="getitem">
<description>__getitem__{a, b}
Return the value of a at index b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="getslice">
<description>__getslice__{a, b, c}
Return the slice of a from index b to index c-1.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="c c" required="1"/></properties></element>

<element kind="function" name="indexOf">
<description>Return the index of the first of occurrence of b in a.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="repeat">
<description>__repeat__{a, b}
Return a * b where a is a sequence and
b is an integer.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="sequenceIncludes">
<description>2.0{Use contains() instead.}
Alias for contains().</description>

<properties><property kind="parameter" name="unspecifiedunspecified" required="1"/></properties></element>

<element kind="function" name="setitem">
<description>__setitem__{a, b, c}
Set the value of a at index b to c.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="c c" required="1"/></properties></element>

<element kind="function" name="setslice">
<description>__setslice__{a, b, c, v}
Set the slice of a from index b to index c-1 to the
sequence v.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="c" required="1"/><property kind="parameter" name="v v" required="1"/></properties></element>

<element kind="function" name="isCallable">
<description>2.0{Use the callable() built-in function instead.}
Returns true if the object o can be called like a function,
otherwise it returns false. True is returned for functions, bound and
unbound methods, class objects, and instance objects which support the
__call__() method.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="isMappingType">
<description>Returns true if the object o supports the mapping interface.
This is true for dictionaries and all instance objects.
There is no reliable way to test if an instance
supports the complete mapping protocol since the interface itself is
ill-defined. This makes this test less useful than it otherwise might
be.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="isNumberType">
<description>Returns true if the object o represents a number. This is true
for all numeric types implemented in C, and for all instance objects.
There is no reliable way to test if an instance
supports the complete numeric interface since the interface itself is
ill-defined. This makes this test less useful than it otherwise might
be.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="isSequenceType">
<description>Returns true if the object o supports the sequence protocol.
This returns true for all objects which define sequence methods in C,
and for all instance objects. There is no reliable
way to test if an instance supports the complete sequence interface
since the interface itself is ill-defined. This makes this test less
useful than it otherwise might be.</description>

<properties><property kind="parameter" name="oo" required="1"/></properties></element>

<element kind="function" name="attrgetter">
<description>Return a callable object that fetches attr from its operand.
After, f=attrgetter('name'), the call f(b) returns
b.name.
New in version 2.4</description>

<properties><property kind="parameter" name="attrattr" required="1"/></properties></element>

<element kind="function" name="itemgetter">
<description>Return a callable object that fetches item from its operand.
After, f=itemgetter(2), the call f(b) returns
b[2].
New in version 2.4</description>

<properties><property kind="parameter" name="itemitem" required="1"/></properties></element>

<group name="Mapping Operators to Functions">
</group>
</group>
<group name="inspect --- Inspect live objects">
<description>Extract information and source code from live objects.
New in version 2.1
The inspect module provides several useful functions
to help get information about live objects such as modules,
classes, methods, functions, tracebacks, frame objects, and
code objects. For example, it can help you examine the
contents of a class, retrieve the source code of a method,
extract and format the argument list for a function, or
get all the information you need to display a detailed traceback.
There are four main kinds of services provided by this module:
type checking, getting source code, inspecting classes
and functions, and examining the interpreter stack.
</description>
<group name="Types and members">
<description>The getmembers() function retrieves the members
of an object such as a class or module.
The eleven functions whose names begin with ``is'' are mainly
provided as convenient choices for the second argument to
getmembers(). They also help you determine when
you can expect to find the following special attributes:
{c|l|l|c}{}{Type}{Attribute}{Description}{Notes}
module{__doc__}{documentation string}{}
{__file__}{filename (missing for built-in modules)}{}
class{__doc__}{documentation string}{}
{__module__}{name of module in which this class was defined}{}
method{__doc__}{documentation string}{}
{__name__}{name with which this method was defined}{}
{im_class}{class object that asked for this method}{(1)}
{im_func}{function object containing implementation of method}{}
{im_self}{instance to which this method is bound, or None}{}
function{__doc__}{documentation string}{}
{__name__}{name with which this function was defined}{}
{func_code}{code object containing compiled function bytecode}{}
{func_defaults}{tuple of any default values for arguments}{}
{func_doc}{(same as __doc__)}{}
{func_globals}{global namespace in which this function was defined}{}
{func_name}{(same as __name__)}{}
traceback{tb_frame}{frame object at this level}{}
{tb_lasti}{index of last attempted instruction in bytecode}{}
{tb_lineno}{current line number in Python source code}{}
{tb_next}{next inner traceback object (called by this level)}{}
frame{f_back}{next outer frame object (this frame's caller)}{}
{f_builtins}{built-in namespace seen by this frame}{}
{f_code}{code object being executed in this frame}{}
{f_exc_traceback}{traceback if raised in this frame, or None}{}
{f_exc_type}{exception type if raised in this frame, or None}{}
{f_exc_value}{exception value if raised in this frame, or None}{}
{f_globals}{global namespace seen by this frame}{}
{f_lasti}{index of last attempted instruction in bytecode}{}
{f_lineno}{current line number in Python source code}{}
{f_locals}{local namespace seen by this frame}{}
{f_restricted}{0 or 1 if frame is in restricted execution mode}{}
{f_trace}{tracing function for this frame, or None}{}
code{co_argcount}{number of arguments (not including * or ** args)}{}
{co_code}{string of raw compiled bytecode}{}
{co_consts}{tuple of constants used in the bytecode}{}
{co_filename}{name of file in which this code object was created}{}
{co_firstlineno}{number of first line in Python source code}{}
{co_flags}{bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg}{}
{co_lnotab}{encoded mapping of line numbers to bytecode indices}{}
{co_name}{name with which this code object was defined}{}
{co_names}{tuple of names of local variables}{}
{co_nlocals}{number of local variables}{}
{co_stacksize}{virtual machine stack space required}{}
{co_varnames}{tuple of names of arguments and local variables}{}
builtin{__doc__}{documentation string}{}
{__name__}{original name of this function or method}{}
{__self__}{instance to which a method is bound, or None}{}
Note:
[(1)]
Changed in version 2.2: im_class used to refer to the class that
defined the method
</description>
<element kind="function" name="getmembers">
<description>Return all the members of an object in a list of (name, value) pairs
sorted by name. If the optional predicate argument is supplied,
only members for which the predicate returns a true value are included.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="predicate"/></properties></element>

<element kind="function" name="getmoduleinfo">
<description>Return a tuple of values that describe how Python will interpret the
file identified by path if it is a module, or None if
it would not be identified as a module. The return tuple is
(name, suffix, mode, mtype), where
name is the name of the module without the name of any
enclosing package, suffix is the trailing part of the file
name (which may not be a dot-delimited extension), mode is the
open() mode that would be used ('r' or
'rb'), and mtype is an integer giving the type of the
module. mtype will have a value which can be compared to the
constants defined in the imp module; see the
documentation for that module for more information on module types.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="getmodulename">
<description>Return the name of the module named by the file path, without
including the names of enclosing packages. This uses the same
algortihm as the interpreter uses when searching for modules. If
the name cannot be matched according to the interpreter's rules,
None is returned.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="ismodule">
<description>Return true if the object is a module.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isclass">
<description>Return true if the object is a class.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="ismethod">
<description>Return true if the object is a method.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isfunction">
<description>Return true if the object is a Python function or unnamed (lambda) function.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="istraceback">
<description>Return true if the object is a traceback.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isframe">
<description>Return true if the object is a frame.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="iscode">
<description>Return true if the object is a code.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isbuiltin">
<description>Return true if the object is a built-in function.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isroutine">
<description>Return true if the object is a user-defined or built-in function or method.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="ismethoddescriptor">
<description>Return true if the object is a method descriptor, but not if ismethod() or isclass() or isfunction() are true.
This is new as of Python 2.2, and, for example, is true of int.__add__.
An object passing this test has a __get__ attribute but not a __set__
attribute, but beyond that the set of attributes varies. __name__ is
usually sensible, and __doc__ often is.
Methods implemented via descriptors that also pass one of the other
tests return false from the ismethoddescriptor() test, simply because
the other tests promise more -- you can, e.g., count on having the
im_func attribute (etc) when an object passes ismethod().</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isdatadescriptor">
<description>Return true if the object is a data descriptor.
Data descriptors have both a __get__ and a __set__ attribute. Examples are
properties (defined in Python) and getsets and members (defined in C).
Typically, data descriptors will also have __name__ and __doc__ attributes (properties, getsets, and members have both of these attributes), but this is not guaranteed.
New in version 2.3</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

</group>
<group name="Retrieving source code">
<element kind="function" name="getdoc">
<description>Get the documentation string for an object.
All tabs are expanded to spaces. To clean up docstrings that are
indented to line up with blocks of code, any whitespace than can be
uniformly removed from the second line onwards is removed.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getcomments">
<description>Return in a single string any lines of comments immediately preceding
the object's source code (for a class, function, or method), or at the
top of the Python source file (if the object is a module).</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getfile">
<description>Return the name of the (text or binary) file in which an object was
defined. This will fail with a TypeError if the object
is a built-in module, class, or function.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getmodule">
<description>Try to guess which module an object was defined in.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getsourcefile">
<description>Return the name of the Python source file in which an object was
defined. This will fail with a TypeError if the object
is a built-in module, class, or function.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getsourcelines">
<description>Return a list of source lines and starting line number for an object.
The argument may be a module, class, method, function, traceback, frame,
or code object. The source code is returned as a list of the lines
corresponding to the object and the line number indicates where in the
original source file the first line of code was found. An
IOError is raised if the source code cannot be retrieved.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="getsource">
<description>Return the text of the source code for an object.
The argument may be a module, class, method, function, traceback, frame,
or code object. The source code is returned as a single string. An
IOError is raised if the source code cannot be retrieved.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

</group>
<group name="Classes and functions">
<element kind="function" name="getclasstree">
<description>Arrange the given list of classes into a hierarchy of nested lists.
Where a nested list appears, it contains classes derived from the class
whose entry immediately precedes the list. Each entry is a 2-tuple
containing a class and a tuple of its base classes. If the unique
argument is true, exactly one entry appears in the returned structure
for each class in the given list. Otherwise, classes using multiple
inheritance and their descendants will appear multiple times.</description>

<properties><property kind="parameter" name="classes" required="1"/><property kind="parameter" name="unique"/></properties></element>

<element kind="function" name="getargspec">
<description>Get the names and default values of a function's arguments.
A tuple of four things is returned: (args,
varargs, varkw, defaults).
args is a list of the argument names (it may contain nested lists).
varargs and varkw are the names of the * and
** arguments or None.
defaults is a tuple of default argument values; if this tuple
has n elements, they correspond to the last n elements
listed in args.</description>

<properties><property kind="parameter" name="funcfunc" required="1"/></properties></element>

<element kind="function" name="getargvalues">
<description>Get information about arguments passed into a particular frame.
A tuple of four things is returned: (args,
varargs, varkw, locals).
args is a list of the argument names (it may contain nested
lists).
varargs and varkw are the names of the * and
** arguments or None.
locals is the locals dictionary of the given frame.</description>

<properties><property kind="parameter" name="frameframe" required="1"/></properties></element>

<element kind="function" name="formatargspec">
<description>Format a pretty argument spec from the four values returned by
getargspec(). The other four arguments are the
corresponding optional formatting functions that are called to turn
names and values into strings.</description>

<properties><property kind="parameter" name="args" required="1"/><property kind="parameter" name="varargs"/><property kind="parameter" name="varkw"/><property kind="parameter" name="defaults"/><property kind="parameter" name="argformat"/><property kind="parameter" name="varargsformat"/><property kind="parameter" name="varkwformat"/><property kind="parameter" name="defaultformat"/></properties></element>

<element kind="function" name="formatargvalues">
<description>Format a pretty argument spec from the four values returned by
getargvalues(). The other four arguments are the
corresponding optional formatting functions that are called to turn
names and values into strings.</description>

<properties><property kind="parameter" name="args" required="1"/><property kind="parameter" name="varargs"/><property kind="parameter" name="varkw"/><property kind="parameter" name="locals"/><property kind="parameter" name="argformat"/><property kind="parameter" name="varargsformat"/><property kind="parameter" name="varkwformat"/><property kind="parameter" name="valueformat"/></properties></element>

<element kind="function" name="getmro">
<description>Return a tuple of class cls's base classes, including cls, in
method resolution order. No class appears more than once in this tuple.
Note that the method resolution order depends on cls's type. Unless a
very peculiar user-defined metatype is in use, cls will be the first
element of the tuple.</description>

<properties><property kind="parameter" name="clscls" required="1"/></properties></element>

</group>
<group name="The interpreter stack">
<description>When the following functions return ``frame records,'' each record
is a tuple of six items: the frame object, the filename,
the line number of the current line, the function name, a list of
lines of context from the source code, and the index of the current
line within that list.
The optional context argument specifies the number of lines of
context to return, which are centered around the current line.
Keeping references to frame objects, as found in
the first element of the frame records these functions return, can
cause your program to create reference cycles. Once a reference cycle
has been created, the lifespan of all objects which can be accessed
from the objects which form the cycle can become much longer even if
Python's optional cycle detector is enabled. If such cycles must be
created, it is important to ensure they are explicitly broken to avoid
the delayed destruction of objects and increased memory consumption
which occurs.
</description>
<element kind="function" name="getframeinfo">
<description>Get information about a frame or traceback object. A 5-tuple
is returned, the last five elements of the frame's frame record.
The optional second argument specifies the number of lines of context
to return, which are centered around the current line.</description>

<properties><property kind="parameter" name="frame" required="1"/><property kind="parameter" name="context"/></properties></element>

<element kind="function" name="getouterframes">
<description>Get a list of frame records for a frame and all higher (calling)
frames.</description>

<properties><property kind="parameter" name="frame" required="1"/><property kind="parameter" name="context"/></properties></element>

<element kind="function" name="getinnerframes">
<description>Get a list of frame records for a traceback's frame and all lower
frames.</description>

<properties><property kind="parameter" name="traceback" required="1"/><property kind="parameter" name="context"/></properties></element>

<element kind="function" name="currentframe">
<description>Return the frame object for the caller's stack frame.</description>

</element>

<element kind="function" name="stack">
<description>Return a list of frame records for the stack above the caller's
frame.</description>

<properties><property kind="parameter" name="context" required="1"/></properties></element>

<element kind="function" name="trace">
<description>Return a list of frame records for the stack below the current
exception.</description>

<properties><property kind="parameter" name="context" required="1"/></properties></element>

</group>
</group>
<group name="traceback --- Print or retrieve a stack traceback">
<description>Print or retrieve a stack traceback.
This module provides a standard interface to extract, format and print
stack traces of Python programs. It exactly mimics the behavior of
the Python interpreter when it prints a stack trace. This is useful
when you want to print stack traces under program control, such as in a
``wrapper'' around the interpreter.
The module uses traceback objects --- this is the object type that is
stored in the variables sys.exc_traceback (deprecated) and
sys.last_traceback and returned as the third item from
sys.exc_info().
traceback
The module defines the following functions:
</description>
<element kind="function" name="print_tb">
<description>Print up to limit stack trace entries from traceback. If
limit is omitted or None, all entries are printed.
If file is omitted or None, the output goes to
sys.stderr; otherwise it should be an open file or file-like
object to receive the output.</description>

<properties><property kind="parameter" name="traceback" required="1"/><property kind="parameter" name="limit"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="print_exception">
<description>Print exception information and up to limit stack trace entries
from traceback to file.
This differs from print_tb() in the
following ways: (1) if traceback is not None, it prints a
header Traceback (most recent call last):; (2) it prints the
exception type and value after the stack trace; (3) if
type is SyntaxError and value has the
appropriate format, it prints the line where the syntax error occurred
with a caret indicating the approximate position of the error.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="value" required="1"/><property kind="parameter" name="traceback" required="1"/><property kind="parameter" name="limit"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="print_exc">
<description>This is a shorthand for print_exception(sys.exc_type,
sys.exc_value, sys.exc_traceback, limit, file). (In
fact, it uses sys.exc_info() to retrieve the same
information in a thread-safe way instead of using the deprecated
variables.)</description>

<properties><property kind="parameter" name="limit" required="1"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="format_exc">
<description>This is like print_exc(limit) but returns a string
instead of printing to a file.
New in version 2.4</description>

<properties><property kind="parameter" name="limit" required="1"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="print_last">
<description>This is a shorthand for print_exception(sys.last_type,
sys.last_value, sys.last_traceback, limit, file).</description>

<properties><property kind="parameter" name="limit" required="1"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="print_stack">
<description>This function prints a stack trace from its invocation point. The
optional f argument can be used to specify an alternate stack
frame to start. The optional limit and file arguments have the
same meaning as for print_exception().</description>

<properties><property kind="parameter" name="f" required="1"/><property kind="parameter" name="limit"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="extract_tb">
<description>Return a list of up to limit ``pre-processed'' stack trace
entries extracted from the traceback object traceback. It is
useful for alternate formatting of stack traces. If limit is
omitted or None, all entries are extracted. A
``pre-processed'' stack trace entry is a quadruple (filename,
line number, function name, text) representing
the information that is usually printed for a stack trace. The
text is a string with leading and trailing whitespace
stripped; if the source is not available it is None.</description>

<properties><property kind="parameter" name="traceback" required="1"/><property kind="parameter" name="limit"/></properties></element>

<element kind="function" name="extract_stack">
<description>Extract the raw traceback from the current stack frame. The return
value has the same format as for extract_tb(). The
optional f and limit arguments have the same meaning as
for print_stack().</description>

<properties><property kind="parameter" name="f" required="1"/><property kind="parameter" name="limit"/></properties></element>

<element kind="function" name="format_list">
<description>Given a list of tuples as returned by extract_tb() or
extract_stack(), return a list of strings ready for
printing. Each string in the resulting list corresponds to the item
with the same index in the argument list. Each string ends in a
newline; the strings may contain internal newlines as well, for those
items whose source text line is not None.</description>

<properties><property kind="parameter" name="listlist" required="1"/></properties></element>

<element kind="function" name="format_exception_only">
<description>Format the exception part of a traceback. The arguments are the
exception type and value such as given by sys.last_type and
sys.last_value. The return value is a list of strings, each
ending in a newline. Normally, the list contains a single string;
however, for SyntaxError exceptions, it contains several
lines that (when printed) display detailed information about where the
syntax error occurred. The message indicating which exception
occurred is the always last string in the list.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="format_exception">
<description>Format a stack trace and the exception information. The arguments have the same meaning as the corresponding arguments to
print_exception(). The return value is a list of strings,
each ending in a newline and some containing internal newlines. When
these lines are concatenated and printed, exactly the same text is
printed as does print_exception().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="value" required="1"/><property kind="parameter" name="tb" required="1"/><property kind="parameter" name="limit"/></properties></element>

<element kind="function" name="format_tb">
<description>A shorthand for format_list(extract_tb(tb, limit)).</description>

<properties><property kind="parameter" name="tb" required="1"/><property kind="parameter" name="limit"/></properties></element>

<element kind="function" name="format_stack">
<description>A shorthand for format_list(extract_stack(f, limit)).</description>

<properties><property kind="parameter" name="f" required="1"/><property kind="parameter" name="limit"/></properties></element>

<element kind="function" name="tb_lineno">
<description>This function returns the current line number set in the traceback
object. This function was necessary because in versions of Python
prior to 2.3 when the -O flag was passed to Python the
tb.tb_lineno was not updated correctly. This function
has no use in versions past 2.3.</description>

<properties><property kind="parameter" name="tbtb" required="1"/></properties></element>

<group name="Traceback Example">
</group>
</group>
<group name="linecache --- Random access to text lines">
<description>This module provides random access to individual lines
from text files.
The linecache module allows one to get any line from any file,
while attempting to optimize internally, using a cache, the common case
where many lines are read from a single file. This is used by the
traceback module to retrieve source lines for inclusion in the formatted traceback.
The linecache module defines the following functions:
</description>
<element kind="function" name="getline">
<description>Get line lineno from file named filename. This function
will never throw an exception --- it will return '' on errors
(the terminating newline character will be included for lines that are
found).
If a file named filename is not found, the function will look
for it in the modulemodule{search}{path} search path,
sys.path.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="lineno lineno" required="1"/></properties></element>

<element kind="function" name="clearcache">
<description>Clear the cache. Use this function if you no longer need lines from
files previously read using getline().</description>

</element>

<element kind="function" name="checkcache">
<description>Check the cache for validity. Use this function if files in the cache may have changed on disk, and you require the updated version.</description>

</element>

</group>
<group name="pickle --- Python object serialization">
<description>Convert Python objects to streams of bytes and back.
% Substantial improvements by Jim Kerr &lt;jbkerr@sr.hp.com&gt;.
% Rewritten by Barry Warsaw &lt;barry@zope.com&gt;
</description>
<group name="Relationship to other Python modules">
<description>The pickle module has an optimized cousin called the
cPickle module. As its name implies, cPickle is
written in C, so it can be up to 1000 times faster than
pickle. However it does not support subclassing of the
Pickler() and Unpickler() classes, because in
cPickle these are functions, not classes. Most applications
have no need for this functionality, and can benefit from the improved
performance of cPickle. Other than that, the interfaces of
the two modules are nearly identical; the common interface is
described in this manual and differences are pointed out where
necessary. In the following discussions, we use the term ``pickle''
to collectively describe the pickle and
cPickle modules.
The data streams the two modules produce are guaranteed to be
interchangeable.
Python has a more primitive serialization module called
marshal, but in general
pickle should always be the preferred way to serialize Python
objects. marshal exists primarily to support Python's
.pyc files.
The pickle module differs from marshal several
significant ways:
The pickle module keeps track of the objects it has
already serialized, so that later references to the same object
won't be serialized again. marshal doesn't do this.
This has implications both for recursive objects and object
sharing. Recursive objects are objects that contain references
to themselves. These are not handled by marshal, and in fact,
attempting to marshal recursive objects will crash your Python
interpreter. Object sharing happens when there are multiple
references to the same object in different places in the object
hierarchy being serialized. pickle stores such objects
only once, and ensures that all other references point to the
master copy. Shared objects remain shared, which can be very
important for mutable objects.
marshal cannot be used to serialize user-defined
classes and their instances. pickle can save and
restore class instances transparently, however the class
definition must be importable and live in the same module as
when the object was stored.
The marshal serialization format is not guaranteed to
be portable across Python versions. Because its primary job in
life is to support .pyc files, the Python implementers
reserve the right to change the serialization format in
non-backwards compatible ways should the need arise. The
pickle serialization format is guaranteed to be
backwards compatible across Python releases.
[warning]
The pickle module is not intended to be secure against
erroneous or maliciously constructed data. Never unpickle data
received from an untrusted or unauthenticated source.
Note that serialization is a more primitive notion than persistence;
although
pickle reads and writes file objects, it does not handle the
issue of naming persistent objects, nor the (even more complicated)
issue of concurrent access to persistent objects. The pickle
module can transform a complex object into a byte stream and it can
transform the byte stream into an object with the same internal
structure. Perhaps the most obvious thing to do with these byte
streams is to write them onto a file, but it is also conceivable to
send them across a network or store them in a database. The module
shelve provides a simple interface
to pickle and unpickle objects on DBM-style database files.
</description>
</group>
<group name="Data stream format">
<description>The data format used by pickle is Python-specific. This has
the advantage that there are no restrictions imposed by external
standards such as XDR</description>
</group>
<group name="Usage">
<description>To serialize an object hierarchy, you first create a pickler, then you
call the pickler's dump() method. To de-serialize a data
stream, you first create an unpickler, then you call the unpickler's
load() method. The pickle module provides the
following constant:
{HIGHEST_PROTOCOL}
The highest protocol version available. This value can be passed
as a protocol value.
New in version 2.3
The pickle module provides the
following functions to make this process more convenient:
</description>
<element kind="function" name="dump">
<description>Write a pickled representation of object to the open file object
file. This is equivalent to
Pickler(file, protocol, bin).dump(object).
If the protocol parameter is ommitted, protocol 0 is used.
If protocol is specified as a negative value
or HIGHEST_PROTOCOL,
the highest protocol version will be used.
Changed in version 2.3: The protocol parameter was added.
The bin parameter is deprecated and only provided
for backwards compatibility. You should use the protocol
parameter instead
If the optional bin argument is true, the binary pickle format
is used; otherwise the (less efficient) text pickle format is used
(for backwards compatibility, this is the default).
file must have a write() method that accepts a single
string argument. It can thus be a file object opened for writing, a
StringIO object, or any other custom
object that meets this interface.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="file" required="1"/><property kind="parameter" name="protocol"/><property kind="parameter" name="bin"/></properties></element>

<element kind="function" name="load">
<description>Read a string from the open file object file and interpret it as
a pickle data stream, reconstructing and returning the original object
hierarchy. This is equivalent to Unpickler(file).load().
file must have two methods, a read() method that takes
an integer argument, and a readline() method that requires no
arguments. Both methods should return a string. Thus file can
be a file object opened for reading, a
StringIO object, or any other custom
object that meets this interface.
This function automatically determines whether the data stream was
written in binary mode or not.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="dumps">
<description>Return the pickled representation of the object as a string, instead
of writing it to a file.
If the protocol parameter is ommitted, protocol 0 is used.
If protocol is specified as a negative value
or HIGHEST_PROTOCOL,
the highest protocol version will be used.
Changed in version 2.3: The protocol parameter was added.
The bin parameter is deprecated and only provided
for backwards compatibility. You should use the protocol
parameter instead
If the optional bin argument is
true, the binary pickle format is used; otherwise the (less efficient)
text pickle format is used (this is the default).</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="protocol"/><property kind="parameter" name="bin"/></properties></element>

<element kind="function" name="loads">
<description>Read a pickled object hierarchy from a string. Characters in the
string past the pickled object's representation are ignored.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="Pickler">
<description>This takes a file-like object to which it will write a pickle data
stream. If the protocol parameter is ommitted, protocol 0 is used.
If protocol is specified as a negative value,
the highest protocol version will be used.
Changed in version 2.3: The bin parameter is deprecated and only provided
for backwards compatibility. You should use the protocol
parameter instead
Optional bin if true, tells the pickler to use the more
efficient binary pickle format, otherwise the ASCII format is used
(this is the default).
file must have a write() method that accepts a single
string argument. It can thus be an open file object, a
StringIO object, or any other custom
object that meets this interface.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="protocol"/><property kind="parameter" name="bin"/></properties></element>

<element kind="function" name="dump">
<description>Write a pickled representation of object to the open file object
given in the constructor. Either the binary or ASCII format will
be used, depending on the value of the bin flag passed to the
constructor.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="clear_memo">
<description>Clears the pickler's ``memo''. The memo is the data structure that
remembers which objects the pickler has already seen, so that shared
or recursive objects pickled by reference and not by value. This
method is useful when re-using picklers.
Prior to Python 2.3, clear_memo() was only available on the
picklers created by cPickle. In the pickle module,
picklers have an instance variable called memo which is a
Python dictionary. So to clear the memo for a pickle module
pickler, you could do the following:
mypickler.memo.clear()
Code that does not need to support older versions of Python should
simply use clear_memo().
</description>

</element>

<element kind="function" name="Unpickler">
<description>This takes a file-like object from which it will read a pickle data
stream. This class automatically determines whether the data stream
was written in binary mode or not, so it does not need a flag as in
the Pickler factory.
file must have two methods, a read() method that takes
an integer argument, and a readline() method that requires no
arguments. Both methods should return a string. Thus file can
be a file object opened for reading, a
StringIO object, or any other custom
object that meets this interface.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="load">
<description>Read a pickled object representation from the open file object given
in the constructor, and return the reconstituted object hierarchy
specified therein.</description>

</element>

<element kind="function" name="noload">
<description>This is just like load() except that it doesn't actually
create any objects. This is useful primarily for finding what's
called ``persistent ids'' that may be referenced in a pickle data
stream. See section~pickle-protocol below for more details.
Note: the noload() method is currently only
available on Unpickler objects created with the
cPickle module. pickle module Unpicklers do
not have the noload() method.</description>

</element>

</group>
<group name="What can be pickled and unpickled?">
<description>The following types can be pickled:
None, True, and False
integers, long integers, floating point numbers, complex numbers
normal and Unicode strings
tuples, lists, and dictionaries containing only picklable objects
functions defined at the top level of a module
built-in functions defined at the top level of a module
classes that are defined at the top level of a module
instances of such classes whose __dict__ or
__setstate__() is picklable (see
section~pickle-protocol for details)
Attempts to pickle unpicklable objects will raise the
PicklingError exception; when this happens, an unspecified
number of bytes may have already been written to the underlying file.
Note that functions (built-in and user-defined) are pickled by ``fully
qualified'' name reference, not by value. This means that only the
function name is pickled, along with the name of module the function
is defined in. Neither the function's code, nor any of its function
attributes are pickled. Thus the defining module must be importable
in the unpickling environment, and the module must contain the named
object, otherwise an exception will be raised.The exception
raised will likely be an ImportError or an
AttributeError but it could be something else.
Similarly, classes are pickled by named reference, so the same
restrictions in the unpickling environment apply. Note that none of
the class's code or data is pickled, so in the following example the
class attribute attr is not restored in the unpickling
environment:
class Foo:
attr = 'a class attr'
picklestring = pickle.dumps(Foo)
These restrictions are why picklable functions and classes must be
defined in the top level of a module.
Similarly, when class instances are pickled, their class's code and
data are not pickled along with them. Only the instance data are
pickled. This is done on purpose, so you can fix bugs in a class or
add methods to the class and still load objects that were created with
an earlier version of the class. If you plan to have long-lived
objects that will see many versions of a class, it may be worthwhile
to put a version number in the objects so that suitable conversions
can be made by the class's __setstate__() method.
</description>
</group>
<group name="The pickle protocol">
</group>
<group name="Subclassing Unpicklers">
<description>By default, unpickling will import any class that it finds in the
pickle data. You can control exactly what gets unpickled and what
gets called by customizing your unpickler. Unfortunately, exactly how
you do this is different depending on whether you're using
pickle or cPickle.A word of caution: the
mechanisms described here use internal attributes and methods, which
are subject to change in future versions of Python. We intend to
someday provide a common interface for controlling this behavior,
which will work in either pickle or cPickle.
In the pickle module, you need to derive a subclass from
Unpickler, overriding the load_global()
method. load_global() should read two lines from the pickle
data stream where the first line will the name of the module
containing the class and the second line will be the name of the
instance's class. It then looks up the class, possibly importing the
module and digging out the attribute, then it appends what it finds to
the unpickler's stack. Later on, this class will be assigned to the
__class__ attribute of an empty class, as a way of magically
creating an instance without calling its class's __init__().
Your job (should you choose to accept it), would be to have
load_global() push onto the unpickler's stack, a known safe
version of any class you deem safe to unpickle. It is up to you to
produce such a class. Or you could raise an error if you want to
disallow all unpickling of instances. If this sounds like a hack,
you're right. Refer to the source code to make this work.
Things are a little cleaner with cPickle, but not by much.
To control what gets unpickled, you can set the unpickler's
find_global attribute to a function or None. If it is
None then any attempts to unpickle instances will raise an
UnpicklingError. If it is a function,
then it should accept a module name and a class name, and return the
corresponding class object. It is responsible for looking up the
class and performing any necessary imports, and it may raise an
error to prevent instances of the class from being unpickled.
The moral of the story is that you should be really careful about the
source of the strings your application unpickles.
</description>
</group>
<group name="Example">
</group>
</group>
<group name="shelve --- Python object persistence">
<description>Python object persistence.
A ``shelf'' is a persistent, dictionary-like object. The difference
with ``dbm'' databases is that the values (not the keys!) in a shelf
can be essentially arbitrary Python objects --- anything that the
pickle module can handle. This includes most class
instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.
pickle
</description>
<element kind="function" name="open">
<description>Open a persistent dictionary. The filename specified is the base filename
for the underlying database. As a side-effect, an extension may be added to
the filename and more than one file may be created. By default, the
underlying database file is opened for reading and writing. The optional
{}flag pararameter has the same interpretation as the flag
parameter of anydbm.open. By default, version 0 pickles are used to serialize values. The version of the pickle protocol can be specified with the
protocol parameter. Changed in version 2.3: The protocol
parameter was added. The binary parameter is deprecated
and provided for backwards compatibility only
By default, mutations to persistent-dictionary mutable entries are not
automatically written back. If the optional writeback parameter
is set to {}True, all entries accessed are cached in memory, and
written back at close time; this can make it handier to mutate mutable
entries in the persistent dictionary, but, if many entries are
accessed, it can consume vast amounts of memory for the cache, and it
can make the close operation very slow since all accessed entries are
written back (there is no way to determine which accessed entries are
mutable, nor which ones were actually mutated).</description>

<properties><property kind="parameter" name="filename" required="1"/><property default="'c'" kind="parameter" name="flag"/><property default="None" kind="parameter" name="protocol"/><property default="False" kind="parameter" name="writeback"/><property default="None" kind="parameter" name="binary"/></properties></element>

<group name="Restrictions">
<description>The choice of which database package will be used
(such as dbm, gdbm or bsddb) depends on
which interface is available. Therefore it is not safe to open the database
directly using dbm. The database is also (unfortunately) subject
to the limitations of dbm, if it is used --- this means
that (the pickled representation of) the objects stored in the
database should be fairly small, and in rare cases key collisions may
cause the database to refuse updates.
dbm
gdbm
bsddb
Depending on the implementation, closing a persistent dictionary may
or may not be necessary to flush changes to disk. The __del__
method of the Shelf class calls the close method, so the
programmer generally need not do this explicitly.
The shelve module does not support concurrent read/write
access to shelved objects. (Multiple simultaneous read accesses are
safe.) When a program has a shelf open for writing, no other program
should have it open for reading or writing. file locking can
be used to solve this, but this differs across versions and
requires knowledge about the database implementation used.
</description>
<element kind="function" name="Shelf">
<description>A subclass of UserDict.DictMixin which stores pickled values in the
dict object. By default, version 0 pickles are used to serialize values. The
version of the pickle protocol can be specified with the
protocol parameter. See the pickle documentation for a
discussion of the pickle protocols. Changed in version 2.3: The protocol
parameter was added. The binary parameter is deprecated and
provided for backwards compatibility only
If the writeback parameter is True, the object will hold a
cache of all entries accessed and write them back to the dict at
sync and close times. This allows natural operations on mutable entries,
but can consume much more memory and make sync and close take a long time.</description>

<properties><property kind="parameter" name="dict" required="1"/><property default="None" kind="parameter" name="protocol"/><property default="False" kind="parameter" name="writeback"/><property default="None" kind="parameter" name="binary"/></properties></element>

<element kind="function" name="BsdDbShelf">
<description>A subclass of Shelf which exposes first,
next, previous, last and
set_location which are available in the bsddb module
but not in other database modules. The dict object passed to
the constructor must support those methods. This is generally
accomplished by calling one of bsddb.hashopen,
bsddb.btopen or bsddb.rnopen. The optional
protocol, writeback, and binary parameters have the
same interpretation as for the Shelf class.</description>

<properties><property kind="parameter" name="dict" required="1"/><property default="None" kind="parameter" name="protocol"/><property default="False" kind="parameter" name="writeback"/><property default="None" kind="parameter" name="binary"/></properties></element>

<element kind="function" name="DbfilenameShelf">
<description>A subclass of Shelf which accepts a filename instead of
a dict-like object. The underlying file will be opened using
{}anydbm.open. By default, the file will be created and
opened for both read and write. The optional flag parameter has
the same interpretation as for the open function. The
optional protocol, writeback, and binary parameters
have the same interpretation as for the Shelf class.</description>

<properties><property kind="parameter" name="filename" required="1"/><property default="'c'" kind="parameter" name="flag"/><property default="None" kind="parameter" name="protocol"/><property default="False" kind="parameter" name="writeback"/><property default="None" kind="parameter" name="binary"/></properties></element>

</group>
<group name="Example">
</group>
</group>
<group name="copy --- Shallow and deep copy operations">
</group>
<group name="marshal --- Internal Python object serialization">
<description>Convert Python objects to streams of bytes and back
(with different constraints).
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).The name of this module stems from a bit of
terminology used by the designers of Modula-3 (amongst others), who
use the term ``marshalling'' for shipping of data around in a
self-contained form. Strictly speaking, ``to marshal'' means to
convert some data from internal to external form (in an RPC buffer for
instance) and ``unmarshalling'' for the reverse process.
This is not a general ``persistence'' module. For general persistence
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. Therefore, the Python
maintainers reserve the right to modify the marshal format in backward
incompatible ways should the need arise. If you're serializing and
de-serializing Python objects, use the pickle module instead. pickle
shelve
code
[warning]
The marshal module is not intended to be secure against
erroneous or maliciously constructed data. Never unmarshal data
received from an untrusted or unauthenticated source.
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, Unicode objects, 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.
If such an integer is marshaled and read back in on a machine where
C's long int type has only 32 bits, a Python long integer object
is returned instead. While of a different type, the numeric value is
the same. (This behavior is new in Python 2.2. In earlier versions,
all but the least-significant 32 bits of the value were lost, and a
warning message was printed.)
There are functions that read/write files as well as functions
operating on strings.
The module defines these functions:
</description>
<element kind="function" name="dump">
<description>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(). It must be opened in binary mode
('wb' or 'w+b').
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().</description>

<properties><property kind="parameter" name="value" required="1"/><property kind="parameter" name="file file" required="1"/></properties></element>

<element kind="function" name="load">
<description>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 opened
in binary mode ('rb' or 'r+b').
If an object containing an unsupported type was
marshalled with dump(), load() will substitute
None for the unmarshallable type.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="dumps">
<description>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.</description>

<properties><property kind="parameter" name="valuevalue" required="1"/></properties></element>

<element kind="function" name="loads">
<description>Convert the string to a value. If no valid value is found, raise
EOFError, ValueError or
TypeError. Extra characters in the string are ignored.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

</group>
<group name="warnings --- Warning control">
<description>Issue warning messages and control their disposition.
</description>
<group name="Warning Categories">
<description>There are a number of built-in exceptions that represent warning
categories. This categorization is useful to be able to filter out
groups of warnings. The following warnings category classes are
currently defined:
{l|l}{exception}{Class}{Description}
Warning{This is the base class of all warning category
classes. It is a subclass of Exception.}
UserWarning{The default category for warn().}
DeprecationWarning{Base category for warnings about
deprecated features.}
SyntaxWarning{Base category for warnings about dubious
syntactic features.}
RuntimeWarning{Base category for warnings about dubious
runtime features.}
FutureWarning{Base category for warnings about constructs
that will change semantically in the future.}
While these are technically built-in exceptions, they are documented
here, because conceptually they belong to the warnings mechanism.
User code can define additional warning categories by subclassing one
of the standard warning categories. A warning category must always be
a subclass of the Warning class.
</description>
</group>
<group name="The Warnings Filter">
<description>The warnings filter controls whether warnings are ignored, displayed,
or turned into errors (raising an exception).
Conceptually, the warnings filter maintains an ordered list of filter
specifications; any specific warning is matched against each filter
specification in the list in turn until a match is found; the match
determines the disposition of the match. Each entry is a tuple of the
form (action, message, category, module,
lineno), where:
action is one of the following strings:
{l|l}{code}{Value}{Disposition}
&quot;error&quot;{turn matching warnings into exceptions}
&quot;ignore&quot;{never print matching warnings}
&quot;always&quot;{always print matching warnings}
&quot;default&quot;{print the first occurrence of matching
warnings for each location where the warning is issued}
&quot;module&quot;{print the first occurrence of matching
warnings for each module where the warning is issued}
&quot;once&quot;{print only the first occurrence of matching
warnings, regardless of location}
message is a string containing a regular expression that
the warning message must match (the match is compiled to always be case-insensitive) category is a class (a subclass of Warning) of
which the warning category must be a subclass in order to match
module is a string containing a regular expression that the module
name must match (the match is compiled to be case-sensitive)
lineno is an integer that the line number where the
warning occurred must match, or 0 to match all line
numbers
Since the Warning class is derived from the built-in
Exception class, to turn a warning into an error we simply
raise category(message).
The warnings filter is initialized by -W options passed
to the Python interpreter command line. The interpreter saves the
arguments for all -W options without interpretation in
sys.warnoptions; the warnings module parses these when
it is first imported (invalid options are ignored, after printing a
message to sys.stderr).
</description>
</group>
<group name="Available Functions">
<element kind="function" name="warn">
<description>Issue a warning, or maybe ignore it or raise an exception. The
category argument, if given, must be a warning category class
(see above); it defaults to UserWarning. Alternatively
message can be a Warning instance, in which case
category will be ignored and message.__class__ will be used.
In this case the message text will be str(message). This function
raises an exception if the particular warning issued is changed
into an error by the warnings filter see above. The stacklevel
argument can be used by wrapper functions written in Python, like
this:
def deprecation(message):
warnings.warn(message, DeprecationWarning, stacklevel=2)
This makes the warning refer to deprecation()'s caller,
rather than to the source of deprecation() itself (since
the latter would defeat the purpose of the warning message).</description>

<properties><property kind="parameter" name="message" required="1"/><property kind="parameter" name="category"/><property kind="parameter" name="stacklevel"/></properties></element>

<element kind="function" name="warn_explicit">
<description>This is a low-level interface to the functionality of
warn(), passing in explicitly the message, category,
filename and line number, and optionally the module name and the
registry (which should be the __warningregistry__ dictionary of
the module). The module name defaults to the filename with .py
stripped; if no registry is passed, the warning is never suppressed.
message must be a string and category a subclass of
Warning or message may be a Warning instance,
in which case category will be ignored.</description>

<properties><property kind="parameter" name="message" required="1"/><property kind="parameter" name="category" required="1"/><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="lineno" required="1"/><property kind="parameter" name="module"/><property kind="parameter" name="registry"/></properties></element>

<element kind="function" name="showwarning">
<description>Write a warning to a file. The default implementation calls
formatwarning(message, category, filename,
lineno) and writes the resulting string to file, which
defaults to sys.stderr. You may replace this function with an
alternative implementation by assigning to
warnings.showwarning.</description>

<properties><property kind="parameter" name="message" required="1"/><property kind="parameter" name="category" required="1"/><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="lineno" required="1"/><property kind="parameter" name="file"/></properties></element>

<element kind="function" name="formatwarning">
<description>Format a warning the standard way. This returns a string which may
contain embedded newlines and ends in a newline.</description>

<properties><property kind="parameter" name="message" required="1"/><property kind="parameter" name="category" required="1"/><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="lineno lineno" required="1"/></properties></element>

<element kind="function" name="filterwarnings">
<description>Insert an entry into the list of warnings filters. The entry is
inserted at the front by default; if append is true, it is
inserted at the end.
This checks the types of the arguments, compiles the message and
module regular expressions, and inserts them as a tuple in front
of the warnings filter. Entries inserted later override entries
inserted earlier, if both match a particular warning. Omitted
arguments default to a value that matches everything.</description>

<properties><property kind="parameter" name="action" required="1"/><property kind="parameter" name="message"/><property kind="parameter" name="category"/><property kind="parameter" name="module"/><property kind="parameter" name="lineno"/><property kind="parameter" name="append"/></properties></element>

<element kind="function" name="resetwarnings">
<description>Reset the warnings filter. This discards the effect of all previous
calls to filterwarnings(), including that of the
-W command line options.</description>

</element>

</group>
</group>
<group name="code --- Interpreter base classes">
<description>Base classes for interactive Python interpreters.
The code module provides facilities to implement
read-eval-print loops in Python. Two classes and convenience
functions are included which can be used to build applications which
provide an interactive interpreter prompt.
</description>
<element kind="function" name="InteractiveInterpreter">
<description>This class deals with parsing and interpreter state (the user's
namespace); it does not deal with input buffering or prompting or
input file naming (the filename is always passed in explicitly).
The optional locals argument specifies the dictionary in
which code will be executed; it defaults to a newly created
dictionary with key '__name__' set to '__console__'
and key '__doc__' set to None.</description>

<properties><property kind="parameter" name="locals" required="1"/></properties></element>

<element kind="function" name="InteractiveConsole">
<description>Closely emulate the behavior of the interactive Python interpreter.
This class builds on InteractiveInterpreter and adds
prompting using the familiar sys.ps1 and sys.ps2, and
input buffering.</description>

<properties><property kind="parameter" name="locals" required="1"/><property kind="parameter" name="filename"/></properties></element>

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

<properties><property kind="parameter" name="banner" required="1"/><property kind="parameter" name="readfunc"/><property kind="parameter" name="local"/></properties></element>

<element kind="function" name="compile_command">
<description>This function is useful for programs that want to emulate Python's
interpreter main loop (a.k.a. the read-eval-print loop). The tricky
part is to determine when the user has entered an incomplete command
that can be completed by entering more text (as opposed to a
complete command or a syntax error). This function
almost always makes the same decision as the real interpreter
main loop.
source is the source string; filename is the optional
filename from which source was read, defaulting to '&lt;input&gt;';
and symbol is the optional grammar start symbol, which should
be either 'single' (the default) or 'eval'.
Returns a code object (the same as compile(source,
filename, symbol)) if the command is complete and
valid; None if the command is incomplete; raises
SyntaxError if the command is complete and contains a
syntax error, or raises OverflowError or
ValueError if the command cotains an invalid literal.</description>

<properties><property kind="parameter" name="source" required="1"/><property kind="parameter" name="filename"/><property kind="parameter" name="symbol"/></properties></element>

<group name="Interactive Interpreter Objects">
<element kind="function" name="runsource">
<description>Compile and run some source in the interpreter.
Arguments are the same as for compile_command(); the
default for filename is '&lt;input&gt;', and for
symbol is 'single'. One several things can happen:
The input is incorrect; compile_command() raised an
exception (SyntaxError or OverflowError). A
syntax traceback will be printed by calling the
showsyntaxerror() method. runsource() returns
False.
The input is incomplete, and more input is required;
compile_command() returned None.
runsource() returns True.
The input is complete; compile_command() returned a code
object. The code is executed by calling the runcode() (which
also handles run-time exceptions, except for SystemExit).
runsource() returns False.
The return value can be used to decide whether to use
sys.ps1 or sys.ps2 to prompt the next line.</description>

<properties><property kind="parameter" name="source" required="1"/><property kind="parameter" name="filename"/><property kind="parameter" name="symbol"/></properties></element>

<element kind="function" name="runcode">
<description>Execute a code object.
When an exception occurs, showtraceback() is called to
display a traceback. All exceptions are caught except
SystemExit, which is allowed to propagate.
A note about KeyboardInterrupt: this exception may occur
elsewhere in this code, and may not always be caught. The caller
should be prepared to deal with it.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="showsyntaxerror">
<description>Display the syntax error that just occurred. This does not display
a stack trace because there isn't one for syntax errors.
If filename is given, it is stuffed into the exception instead
of the default filename provided by Python's parser, because it
always uses '&lt;string&gt;' when reading from a string.
The output is written by the write() method.</description>

<properties><property kind="parameter" name="filename" required="1"/></properties></element>

<element kind="function" name="showtraceback">
<description>Display the exception that just occurred. We remove the first stack
item because it is within the interpreter object implementation.
The output is written by the write() method.</description>

</element>

<element kind="function" name="write">
<description>Write a string to the standard error stream (sys.stderr).
Derived classes should override this to provide the appropriate output
handling as needed.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

</group>
<group name="Interactive Console Objects">
<description>The InteractiveConsole class is a subclass of
InteractiveInterpreter, and so offers all the methods of the
interpreter objects as well as the following additions.
</description>
<element kind="function" name="interact">
<description>Closely emulate the interactive Python console.
The optional banner argument specify the banner to print before the
first interaction; by default it prints a banner similar to the one
printed by the standard Python interpreter, followed by the class
name of the console object in parentheses (so as not to confuse this
with the real interpreter -- since it's so close!).</description>

<properties><property kind="parameter" name="banner" required="1"/></properties></element>

<element kind="function" name="push">
<description>Push a line of source text to the interpreter.
The line should not have a trailing newline; it may have internal
newlines. The line is appended to a buffer and the interpreter's
runsource() method is called with the concatenated contents
of the buffer as source. If this indicates that the command was
executed or invalid, the buffer is reset; otherwise, the command is
incomplete, and the buffer is left as it was after the line was
appended. The return value is True if more input is required,
False if the line was dealt with in some way (this is the same as
runsource()).</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="resetbuffer">
<description>Remove any unhandled source text from the input buffer.</description>

</element>

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

<properties><property kind="parameter" name="prompt" required="1"/></properties></element>

</group>
</group>
<group name="codeop --- Compile Python code">
<description>% LaTeXed from excellent doc-string.
Compile (possibly incomplete) Python code.
The codeop module provides utilities upon which the Python
read-eval-print loop can be emulated, as is done in the
code module. As a result, you probably don't want to use
the module directly; if you want to include such a loop in your
program you probably want to use the code module instead.
There are two parts to this job: Being able to tell if a line of input completes a Python statement: in short, telling whether to print
`&gt;&gt;&gt;~ or `...~' next.
Remembering which future statements the user has entered, so subsequent input can be compiled with these in effect.
The codeop module provides a way of doing each of these
things, and a way of doing them both.
To do just the former:
</description>
<element kind="function" name="compile_command">
<description>Tries to compile source, which should be a string of Python
code and return a code object if source is valid
Python code. In that case, the filename attribute of the code object
will be filename, which defaults to '&lt;input&gt;'.
Returns None if source is not valid Python
code, but is a prefix of valid Python code.
If there is a problem with source, an exception will be raised.
SyntaxError is raised if there is invalid Python syntax,
and OverflowError or ValueError if there is an
invalid literal.
The symbol argument determines whether source is compiled
as a statement ('single', the default) or as an expression
('eval'). Any other value will cause ValueError to be raised.
Caveat:
It is possible (but not likely) that the parser stops parsing
with a successful outcome before reaching the end of the source;
in this case, trailing symbols may be ignored instead of causing an
error. For example, a backslash followed by two newlines may be
followed by arbitrary garbage. This will be fixed once the API
for the parser is better.</description>

<properties><property kind="parameter" name="source" required="1"/><property kind="parameter" name="filename"/><property kind="parameter" name="symbol"/></properties></element>

<element kind="function" name="Compile">
<description>Instances of this class have __call__() methods indentical in
signature to the built-in function compile(), but with the
difference that if the instance compiles program text containing a
__future__ statement, the instance 'remembers' and compiles
all subsequent program texts with the statement in force.</description>

</element>

<element kind="function" name="CommandCompiler">
<description>Instances of this class have __call__() methods identical in
signature to compile_command(); the difference is that if
the instance compiles program text containing a __future__
statement, the instance 'remembers' and compiles all subsequent
program texts with the statement in force.</description>

</element>

</group>
<group name="pprint --- Data pretty printer">
<description>Data pretty printer.
The pprint module provides a capability to ``pretty-print''
arbitrary Python data structures in a form which can be used as input
to the interpreter. If the formatted structures include objects which
are not fundamental Python types, the representation may not be
loadable. This may be the case if objects such as files, sockets,
classes, or instances are included, as well as many other builtin
objects which are not representable as Python constants.
The formatted representation keeps objects on a single line if it can,
and breaks them onto multiple lines if they don't fit within the
allowed width. Construct PrettyPrinter objects explicitly if
you need to adjust the width constraint.
The pprint module defines one class:
% First the implementation class:
</description>
<element kind="function" name="PrettyPrinter">
<description>Construct a PrettyPrinter instance. This constructor
understands several keyword parameters. An output stream may be set
using the stream keyword; the only method used on the stream
object is the file protocol's write() method. If not
specified, the PrettyPrinter adopts sys.stdout. Three
additional parameters may be used to control the formatted
representation. The keywords are indent, depth, and
width. The amount of indentation added for each recursive level
is specified by indent; the default is one. Other values can
cause output to look a little odd, but can make nesting easier to
spot. The number of levels which may be printed is controlled by
depth; if the data structure being printed is too deep, the next
contained level is replaced by .... By default, there is no
constraint on the depth of the objects being formatted. The desired
output width is constrained using the width parameter; the
default is eighty characters. If a structure cannot be formatted
within the constrained width, a best effort will be made.
&gt;&gt;&gt; import pprint, sys
&gt;&gt;&gt; stuff = sys.path[:]
&gt;&gt;&gt; stuff.insert(0, stuff[:])
&gt;&gt;&gt; pp = pprint.PrettyPrinter(indent=4)
&gt;&gt;&gt; pp.pprint(stuff)
[ [ '',
'/usr/local/lib/python1.5',
'/usr/local/lib/python1.5/test',
'/usr/local/lib/python1.5/sunos5',
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter'],
'',
'/usr/local/lib/python1.5',
'/usr/local/lib/python1.5/test',
'/usr/local/lib/python1.5/sunos5',
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter']
&gt;&gt;&gt;
&gt;&gt;&gt; import parser
&gt;&gt;&gt; tup = parser.ast2tuple(
... parser.suite(open('pprint.py').read()))[1][1][1]
&gt;&gt;&gt; pp = pprint.PrettyPrinter(depth=6)
&gt;&gt;&gt; pp.pprint(tup)
(266, (267, (307, (287, (288, (...))))))
</description>

<properties><property kind="parameter" name="......" required="1"/></properties></element>

<element kind="function" name="pformat">
<description>Return the formatted representation of object as a string. indent,
width and depth will be passed to the PrettyPrinter
constructor as formatting parameters.
Changed in version 2.4: The parameters indent, width and depth
were added</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="indent"/><property kind="parameter" name="width"/><property kind="parameter" name="depth"/></properties></element>

<element kind="function" name="pprint">
<description>Prints the formatted representation of object on stream,
followed by a newline. If stream is omitted, sys.stdout
is used. This may be used in the interactive interpreter instead of a
print statement for inspecting values. indent,
width and depth will be passed to the PrettyPrinter
constructor as formatting parameters.
&gt;&gt;&gt; stuff = sys.path[:]
&gt;&gt;&gt; stuff.insert(0, stuff)
&gt;&gt;&gt; pprint.pprint(stuff)
[&lt;Recursion on list with id=869440&gt;,
'',
'/usr/local/lib/python1.5',
'/usr/local/lib/python1.5/test',
'/usr/local/lib/python1.5/sunos5',
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter']
Changed in version 2.4: The parameters indent, width and depth
were added</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="stream"/><property kind="parameter" name="indent"/><property kind="parameter" name="width"/><property kind="parameter" name="depth"/></properties></element>

<element kind="function" name="isreadable">
<description>Determine if the formatted representation of object is
``readable,'' or can be used to reconstruct the value using
eval()eval. This always returns false for
recursive objects.
&gt;&gt;&gt; pprint.isreadable(stuff)
False
</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isrecursive">
<description>Determine if object requires a recursive representation.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="saferepr">
<description>Return a string representation of object, protected against
recursive data structures. If the representation of object
exposes a recursive entry, the recursive reference will be represented
as &lt;Recursion on typename with id=number&gt;. The
representation is not otherwise formatted.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<group name="PrettyPrinter Objects">
<element kind="function" name="pformat">
<description>Return the formatted representation of object. This takes into
Account the options passed to the PrettyPrinter constructor.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="pprint">
<description>Print the formatted representation of object on the configured
stream, followed by a newline.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isreadable">
<description>Determine if the formatted representation of the object is
``readable,'' or can be used to reconstruct the value using
eval()eval. Note that this returns false for
recursive objects. If the depth parameter of the
PrettyPrinter is set and the object is deeper than allowed,
this returns false.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="isrecursive">
<description>Determine if the object requires a recursive representation.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="format">
<description>Returns three values: the formatted version of object as a
string, a flag indicating whether the result is readable, and a flag
indicating whether recursion was detected. The first argument is the
object to be presented. The second is a dictionary which contains the
id() of objects that are part of the current presentation
context (direct and indirect containers for object that are
affecting the presentation) as the keys; if an object needs to be
presented which is already represented in context, the third
return value should be true. Recursive calls to the format()
method should add additionaly entries for containers to this
dictionary. The fourth argument, maxlevels, gives the requested
limit to recursion; this will be 0 if there is no requested
limit. This argument should be passed unmodified to recursive calls.
The fourth argument, level gives the current level; recursive
calls should be passed a value less than that of the current call.
New in version 2.3</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="context" required="1"/><property kind="parameter" name="maxlevels" required="1"/><property kind="parameter" name="level level" required="1"/></properties></element>

</group>
</group>
<group name="repr --- Alternate repr() implementation">
<description>Alternate repr() implementation with size limits.
The repr module provides a means for producing object
representations with limits on the size of the resulting strings.
This is used in the Python debugger and may be useful in other
contexts as well.
This module provides a class, an instance, and a function:
</description>
<element kind="function" name="Repr">
<description>Class which provides formatting services useful in implementing
functions similar to the built-in repr(); size limits for different object types are added to avoid the generation of
representations which are excessively long.</description>

</element>

<element kind="function" name="repr">
<description>This is the repr() method of aRepr. It returns a
string similar to that returned by the built-in function of the same name, but with limits on most sizes.</description>

<properties><property kind="parameter" name="objobj" required="1"/></properties></element>

<group name="Repr Objects">
<description>Repr instances provide several members which can be used to
provide size limits for the representations of different object types, and methods which format specific object types.
{maxlevel}
Depth limit on the creation of recursive representations. The
default is 6.
{maxdict}
maxlist
maxtuple
Limits on the number of entries represented for the named object
type. The default for maxdict is 4, for the others, 6.
{maxlong}
Maximum number of characters in the representation for a long
integer. Digits are dropped from the middle. The default is
40.
{maxstring}
Limit on the number of characters in the representation of the
string. Note that the ``normal'' representation of the string is
used as the character source: if escape sequences are needed in the
representation, these may be mangled when the representation is
shortened. The default is 30.
{maxother}
This limit is used to control the size of object types for which no
specific formatting method is available on the Repr object.
It is applied in a similar manner as maxstring. The
default is 20.
</description>
<element kind="function" name="repr">
<description>The equivalent to the built-in repr() that uses the
formatting imposed by the instance.</description>

<properties><property kind="parameter" name="objobj" required="1"/></properties></element>

<element kind="function" name="repr1">
<description>Recursive implementation used by repr(). This uses the
type of obj to determine which formatting method to call,
passing it obj and level. The type-specific methods
should call repr1() to perform recursive formatting, with
level - 1 for the value of level in the recursive call.</description>

<properties><property kind="parameter" name="obj" required="1"/><property kind="parameter" name="level level" required="1"/></properties></element>

</group>
<group name="Subclassing Repr Objects">
</group>
</group>
<group name="new --- Creation of runtime internal objects">
<description>Interface to the creation of runtime implementation objects.
The new module allows an interface to the interpreter object
creation functions. This is for use primarily in marshal-type functions,
when a new object needs to be created ``magically'' and not by using the
regular creation functions. This module provides a low-level interface
to the interpreter, so care must be exercised when using this module.
The new module defines the following functions:
</description>
<element kind="function" name="instance">
<description>This function creates an instance of class with dictionary
dict without calling the __init__() constructor. If
dict is omitted or None, a new, empty dictionary is
created for the new instance. Note that there are no guarantees that
the object will be in a consistent state.</description>

<properties><property kind="parameter" name="class" required="1"/><property kind="parameter" name="dict"/></properties></element>

<element kind="function" name="instancemethod">
<description>This function will return a method object, bound to instance, or
unbound if instance is None. function must be
callable.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="instance" required="1"/><property kind="parameter" name="class class" required="1"/></properties></element>

<element kind="function" name="function">
<description>Returns a (Python) function with the given code and globals. If
name is given, it must be a string or None. If it is a
string, the function will have the given name, otherwise the function
name will be taken from code.co_name. If
argdefs is given, it must be a tuple and will be used to
determine the default values of parameters.</description>

<properties><property kind="parameter" name="code" required="1"/><property kind="parameter" name="globals" required="1"/><property kind="parameter" name="name"/><property kind="parameter" name="argdefs"/></properties></element>

<element kind="function" name="code">
<description>This function is an interface to the PyCode_New() C
function.
%XXX This is still undocumented!!!!!!!!!!!</description>

<properties><property kind="parameter" name="argcount" required="1"/><property kind="parameter" name="nlocals" required="1"/><property kind="parameter" name="stacksize" required="1"/><property kind="parameter" name="flags" required="1"/><property kind="parameter" name="codestring" required="1"/><property kind="parameter" name="constants" required="1"/><property kind="parameter" name="names" required="1"/><property kind="parameter" name="varnames" required="1"/><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="name" required="1"/><property kind="parameter" name="firstlineno" required="1"/><property kind="parameter" name="lnotab                        lnotab" required="1"/></properties></element>

<element kind="function" name="module">
<description>This function returns a new module object with name name.
name must be a string.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="classobj">
<description>This function returns a new class object, with name name, derived
from baseclasses (which should be a tuple of classes) and with
namespace dict.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="baseclasses" required="1"/><property kind="parameter" name="dict dict" required="1"/></properties></element>

</group>
<group name="site --- Site-specific configuration hook">
</group>
<group name="user --- User-specific configuration hook">
</group>
<group name="__builtin__ --- Built-in functions">
</group>
<group name="__main__ --- Top-level script environment">
</group>
<group name="__future__ --- Future statement definitions">
</group>
</group>
<group name="String Services">
<group name="string --- Common string operations">
<description>Common string operations.
This module defines some constants useful for checking character
classes and some useful string functions. See the module
rere for string functions based on regular
expressions.
The constants defined in this module are:
{ascii_letters}
The concatenation of the ascii_lowercase and
ascii_uppercase constants described below. This value is
not locale-dependent.
{ascii_lowercase}
The lowercase letters 'abcdefghijklmnopqrstuvwxyz'. This
value is not locale-dependent and will not change.
{ascii_uppercase}
The uppercase letters 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. This
value is not locale-dependent and will not change.
{digits}
The string '0123456789'.
{hexdigits}
The string '0123456789abcdefABCDEF'.
{letters}
The concatenation of the strings lowercase and
uppercase described below. The specific value is
locale-dependent, and will be updated when
locale.setlocale() is called.
{lowercase}
A string containing all the characters that are considered lowercase
letters. On most systems this is the string
'abcdefghijklmnopqrstuvwxyz'. Do not change its definition ---
the effect on the routines upper() and
swapcase() is undefined. The specific value is
locale-dependent, and will be updated when
locale.setlocale() is called.
{octdigits}
The string '01234567'.
{punctuation}
String of ASCII characters which are considered punctuation
characters in the C locale.
{printable}
String of characters which are considered printable. This is a
combination of digits, letters,
punctuation, and whitespace.
{uppercase}
A string containing all the characters that are considered uppercase
letters. On most systems this is the string
'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Do not change its definition ---
the effect on the routines lower() and
swapcase() is undefined. The specific value is
locale-dependent, and will be updated when
locale.setlocale() is called.
{whitespace}
A string containing all characters that are considered whitespace.
On most systems this includes the characters space, tab, linefeed,
return, formfeed, and vertical tab. Do not change its definition ---
the effect on the routines strip() and split()
is undefined.
Many of the functions provided by this module are also defined as
methods of string and Unicode objects; see ``String Methods'' (section
string-methods) for more information on those.
The functions defined in this module are:
</description>
<element kind="function" name="atof">
<description>2.0{Use the float() built-in function.}
Convert a string to a floating point number. The string must have
the standard syntax for a floating point literal in Python,
optionally preceded by a sign (+ or -). Note that
this behaves identical to the built-in function
float()float when passed a string.
When passing in a string, values for NaN</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="atoi">
<description>2.0{Use the int() built-in function.}
Convert string s to an integer in the given base. The
string must consist of one or more digits, optionally preceded by a
sign (+ or -). The base defaults to 10. If it
is 0, a default base is chosen depending on the leading characters
of the string (after stripping the sign): 0x or 0X
means 16, 0 means 8, anything else means 10. If base
is 16, a leading 0x or 0X is always accepted, though
not required. This behaves identically to the built-in function
int() when passed a string. (Also note: for a more
flexible interpretation of numeric literals, use the built-in
function eval()eval.)</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="base"/></properties></element>

<element kind="function" name="atol">
<description>2.0{Use the long() built-in function.}
Convert string s to a long integer in the given base.
The string must consist of one or more digits, optionally preceded
by a sign (+ or -). The base argument has the
same meaning as for atoi(). A trailing l or
L is not allowed, except if the base is 0. Note that when
invoked without base or with base set to 10, this
behaves identical to the built-in function
long()long when passed a string.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="base"/></properties></element>

<element kind="function" name="capitalize">
<description>Return a copy of word with only its first character capitalized.</description>

<properties><property kind="parameter" name="wordword" required="1"/></properties></element>

<element kind="function" name="capwords">
<description>Split the argument into words using split(), capitalize
each word using capitalize(), and join the capitalized
words using join(). Note that this replaces runs of
whitespace characters by a single space, and removes leading and
trailing whitespace.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="expandtabs">
<description>Expand tabs in a string, i.e. them by one or more spaces,
depending on the current column and the given tab size. The column
number is reset to zero after each newline occurring in the string.
This doesn't understand other non-printing characters or escape
sequences. The tab size defaults to 8.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="tabsize"/></properties></element>

<element kind="function" name="find">
<description>Return the lowest index in s where the substring sub is
found such that sub is wholly contained in
s[start:end]. Return -1 on failure.
Defaults for start and end and interpretation of
negative values is the same as for slices.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="rfind">
<description>Like find() but find the highest index.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="index">
<description>Like find() but raise ValueError when the
substring is not found.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="rindex">
<description>Like rfind() but raise ValueError when the
substring is not found.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="count">
<description>Return the number of (non-overlapping) occurrences of substring
sub in string s[start:end].
Defaults for start and end and interpretation of
negative values are the same as for slices.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sub" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="end"/></properties></element>

<element kind="function" name="lower">
<description>Return a copy of s, but with upper case letters converted to
lower case.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="maketrans">
<description>Return a translation table suitable for passing to
translate() or regex.compile(), that will map
each character in from into the character at the same position
in to; from and to must have the same length.
Don't use strings derived from lowercase
and uppercase as arguments; in some locales, these don't have
the same length. For case conversions, always use
lower() and upper().</description>

<properties><property kind="parameter" name="from" required="1"/><property kind="parameter" name="to to" required="1"/></properties></element>

<element kind="function" name="split">
<description>Return a list of the words of the string s. If the optional
second argument sep is absent or None, the words are
separated by arbitrary strings of whitespace characters (space, tab, newline, return, formfeed). If the second argument sep is
present and not None, it specifies a string to be used as the word separator. The returned list will then have one more item
than the number of non-overlapping occurrences of the separator in
the string. The optional third argument maxsplit defaults to
0. If it is nonzero, at most maxsplit number of splits occur,
and the remainder of the string is returned as the final element of
the list (thus, the list will have at most maxsplit+1
elements).</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sep"/><property kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="rsplit">
<description>Return a list of the words of the string s, scanning s
from the end. To all intents and purposes, the resulting list of
words is the same as returned by split(), except when the
optional third argument maxsplit is explicitly specified and
nonzero. When maxsplit is nonzero, at most maxsplit
number of splits -- the rightmost ones -- occur, and the remainder
of the string is returned as the first element of the list (thus, the
list will have at most maxsplit+1 elements).
New in version 2.4</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sep"/><property kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="splitfields">
<description>This function behaves identically to split(). (In the
past, split() was only used with one argument, while
splitfields() was only used with two arguments.)</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="sep"/><property kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="join">
<description>Concatenate a list or tuple of words with intervening occurrences of sep. The default value for sep is a single space
character. It is always true that
string.join(string.split(s, sep), sep)
equals s.</description>

<properties><property kind="parameter" name="words" required="1"/><property kind="parameter" name="sep"/></properties></element>

<element kind="function" name="joinfields">
<description>This function behaves identically to join(). (In the past, join() was only used with one argument, while
joinfields() was only used with two arguments.)
Note that there is no joinfields() method on string
objects; use the join() method instead.</description>

<properties><property kind="parameter" name="words" required="1"/><property kind="parameter" name="sep"/></properties></element>

<element kind="function" name="lstrip">
<description>Return a copy of the string with leading characters removed. If
chars is omitted or None, whitespace characters are
removed. If given and not None, chars must be a string;
the characters in the string will be stripped from the beginning of
the string this method is called on.
Changed in version 2.2.3: The chars parameter was added. The chars
parameter cannot be passed in earlier 2.2 versions</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="chars"/></properties></element>

<element kind="function" name="rstrip">
<description>Return a copy of the string with trailing characters removed. If
chars is omitted or None, whitespace characters are
removed. If given and not None, chars must be a string;
the characters in the string will be stripped from the end of the
string this method is called on.
Changed in version 2.2.3: The chars parameter was added. The chars
parameter cannot be passed in 2.2 versions</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="chars"/></properties></element>

<element kind="function" name="strip">
<description>Return a copy of the string with leading and trailing characters
removed. If chars is omitted or None, whitespace
characters are removed. If given and not None, chars
must be a string; the characters in the string will be stripped from
the both ends of the string this method is called on.
Changed in version 2.2.3: The chars parameter was added. The chars
parameter cannot be passed in earlier 2.2 versions</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="chars"/></properties></element>

<element kind="function" name="swapcase">
<description>Return a copy of s, but with lower case letters
converted to upper case and vice versa.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="translate">
<description>Delete all characters from s that are in deletechars (if present), and then translate the characters using table, which must be a 256-character string giving the translation for each
character value, indexed by its ordinal.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="table" required="1"/><property kind="parameter" name="deletechars"/></properties></element>

<element kind="function" name="upper">
<description>Return a copy of s, but with lower case letters converted to
upper case.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="ljust">
<description>rjust{s, width}
center{s, width}
These functions respectively left-justify, right-justify and center
a string in a field of given width. They return a string that is at
least width characters wide, created by padding the string
s with spaces until the given width on the right, left or both
sides. The string is never truncated.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="zfill">
<description>Pad a numeric string on the left with zero digits until the given
width is reached. Strings starting with a sign are handled
correctly.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="replace">
<description>Return a copy of string str with all occurrences of substring
old replaced by new. If the optional argument
maxreplace is given, the first maxreplace occurrences are
replaced.</description>

<properties><property kind="parameter" name="str" required="1"/><property kind="parameter" name="old" required="1"/><property kind="parameter" name="new" required="1"/><property kind="parameter" name="maxreplace"/></properties></element>

</group>
<group name="re --- Regular expression operations">
<description>Regular expression search and match operations with a
Perl-style expression syntax.
This module provides regular expression matching operations similar to
those found in Perl. Regular expression pattern strings may not
contain null bytes, but can specify the null byte using the
\number notation. Both patterns and strings to be
searched can be Unicode strings as well as 8-bit strings. The
re module is always available.
Regular expressions use the backslash character (\) to
indicate special forms or to allow special characters to be used
without invoking their special meaning. This collides with Python's
usage of the same character for the same purpose in string literals;
for example, to match a literal backslash, one might have to write
'\e\e' as the pattern string, because the regular expression
must be \e, and each backslash must be expressed as
\e inside a regular Python string literal.
The solution is to use Python's raw string notation for regular
expression patterns; backslashes are not handled in any special way in
a string literal prefixed with r. So r&quot;\n&quot; is a
two-character string containing \ and n,
while &quot;\n&quot; is a one-character string containing a newline.
Usually patterns will be expressed in Python code using this raw
string notation.
See also Mastering Regular Expressions - Book on regular expressions
by Jeffrey Friedl, published by O'Reilly. The second edition of the book no longer covers Python at all, but the first edition covered writing good regular expression
patterns in great detail.
</description>
<group name="Regular Expression Syntax">
<description>A regular expression (or RE) specifies a set of strings that matches
it; the functions in this module let you check if a particular string
matches a given regular expression (or if a given regular expression
matches a particular string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular
expressions; if A and B are both regular expressions,
then AB is also a regular expression. In general, if a string
p matches A and another string q matches B,
the string pq will match AB. This holds unless A or
B contain low precedence operations; boundary conditions between
A and B; or have numbered group references. Thus, complex
expressions can easily be constructed from simpler primitive
expressions like the ones described here. For details of the theory
and implementation of regular expressions, consult the Friedl book
referenced above, or almost any textbook about compiler construction.
A brief explanation of the format of regular expressions follows. For
further information and a gentler presentation, consult the Regular
Expression HOWTO, accessible from http://www.python.org/doc/howto/.
Regular expressions can contain both special and ordinary characters.
Most ordinary characters, like A, a, or
0, are the simplest regular expressions; they simply match
themselves. You can concatenate ordinary characters, so last
matches the string 'last'. (In the rest of this section, we'll
write RE's in this special style, usually without quotes, and
strings to be matched 'in single quotes'.)
Some characters, like | or (, are special.
Special characters either stand for classes of ordinary characters, or
affect how the regular expressions around them are interpreted.
The special characters are:
{}{ 0.7in 0.65in}
[.] (Dot.) In the default mode, this matches any
character except a newline. If the DOTALL flag has been
specified, this matches any character including a newline.
[] (Caret.) Matches the start of the
string, and in MULTILINE mode also matches immediately
after each newline.
[$] Matches the end of the string or just before the
newline at the end of the string, and in MULTILINE mode
also matches before a newline. foo matches both 'foo' and
'foobar', while the regular expression foo$ matches only
'foo'. More interestingly, searching for foo.$ in
'foo1 nfoo2 n' matches 'foo2' normally,
but 'foo1' in MULTILINE mode.
[*] Causes the resulting RE to
match 0 or more repetitions of the preceding RE, as many repetitions
as are possible. ab* will
match 'a', 'ab', or 'a' followed by any number of 'b's.
[+] Causes the
resulting RE to match 1 or more repetitions of the preceding RE.
ab+ will match 'a' followed by any non-zero number of 'b's; it
will not match just 'a'.
[?] Causes the resulting RE to
match 0 or 1 repetitions of the preceding RE. ab? will
match either 'a' or 'ab'.
[*?, +?, ??] The *,
+, and ? qualifiers are all greedy; they
match as much text as possible. Sometimes this behaviour isn't
desired; if the RE &lt;.*&gt; is matched against
'&lt;H1&gt;title&lt;/H1&gt;', it will match the entire string, and not just
'&lt;H1&gt;'. Adding ? after the qualifier makes it
perform the match in non-greedy or minimal fashion; as
few characters as possible will be matched. Using .*?
in the previous expression will match only '&lt;H1&gt;'.
[{m}]
Specifies that exactly m copies of the previous RE should be
matched; fewer matches cause the entire RE not to match. For example,
a{6} will match exactly six a characters, but
not five.
[{m,n}] Causes the resulting RE to match from
m to n repetitions of the preceding RE, attempting to
match as many repetitions as possible. For example, a{3,5}
will match from 3 to 5 a characters. Omitting m
specifies a lower bound of zero, and omitting n specifies an infinite upper bound. As an
example, a{4,}b will match aaaab or a thousand
a characters followed by a b, but not aaab.
The comma may not be omitted or the modifier would be confused with
the previously described form.
[{m,n}?] Causes the resulting RE to
match from m to n repetitions of the preceding RE,
attempting to match as few repetitions as possible. This is
the non-greedy version of the previous qualifier. For example, on the
6-character string 'aaaaaa', a{3,5} will match 5
a characters, while a{3,5}? will only match 3
characters.
[\] Either escapes special characters (permitting
you to match characters like *, ?, and so
forth), or signals a special sequence; special sequences are discussed
below.
If you're not using a raw string to
express the pattern, remember that Python also uses the
backslash as an escape sequence in string literals; if the escape
sequence isn't recognized by Python's parser, the backslash and
subsequent character are included in the resulting string. However,
if Python would recognize the resulting sequence, the backslash should
be repeated twice. This is complicated and hard to understand, so
it's highly recommended that you use raw strings for all but the
simplest expressions.
[[]] Used to indicate a set of characters. Characters can
be listed individually, or a range of characters can be indicated by
giving two characters and separating them by a -. Special
characters are not active inside sets. For example, [akm]
will match any of the characters a, k,
m, or $; [a-z]
will match any lowercase letter, and [a-zA-Z0-9] matches any
letter or digit. Character classes such as \w or \S
(defined below) are also acceptable inside a range. If you want to
include a ] or a - inside a set, precede it with a
backslash, or place it as the first character. The
pattern []] will match ']', for example.
You can match the characters not within a range by complementing
the set. This is indicated by including a
as the first character of the set;
elsewhere will simply match the
character. For example,
[{}5] will match
any character except 5, and
[] will match any character
except .
[|]A|B, where A and B can be arbitrary REs,
creates a regular expression that will match either A or B. An
arbitrary number of REs can be separated by the | in this
way. This can be used inside groups (see below) as well. As the target
string is scanned, REs separated by | are tried from left to
right. When one pattern completely matches, that branch is accepted.
This means that once A matches, B will not be tested further,
even if it would produce a longer overall match. In other words, the
| operator is never greedy. To match a literal |,
use \, or enclose it inside a character class, as in [|].
[(...)] Matches whatever regular expression is inside the
parentheses, and indicates the start and end of a group; the contents
of a group can be retrieved after a match has been performed, and can
be matched later in the string with the \number special
sequence, described below. To match the literals ( or
), use \ or \, or enclose them
inside a character class: [(] [)].
[(?...)] This is an extension notation (a ?
following a ( is not meaningful otherwise). The first
character after the ?
determines what the meaning and further syntax of the construct is.
Extensions usually do not create a new group;
(?P&lt;name&gt;...) is the only exception to this rule.
Following are the currently supported extensions.
[(?iLmsux)] (One or more letters from the set i,
L, m, s, u,
x.) The group matches the empty string; the letters set
the corresponding flags (re.I, re.L,
re.M, re.S, re.U, re.X)
for the entire regular expression. This is useful if you wish to
include the flags as part of the regular expression, instead of
passing a flag argument to the compile() function.
Note that the (?x) flag changes how the expression is parsed.
It should be used first in the expression string, or after one or more
whitespace characters. If there are non-whitespace characters before
the flag, the results are undefined.
[(?:...)] A non-grouping version of regular parentheses.
Matches whatever regular expression is inside the parentheses, but the
substring matched by the
group cannot be retrieved after performing a match or
referenced later in the pattern.
[(?P&lt;name&gt;...)] Similar to regular parentheses, but
the substring matched by the group is accessible via the symbolic group
name name. Group names must be valid Python identifiers, and
each group name must be defined only once within a regular expression. A
symbolic group is also a numbered group, just as if the group were not
named. So the group named 'id' in the example above can also be
referenced as the numbered group 1.
For example, if the pattern is
(?P&lt;id&gt;[a-zA-Z_]\w*), the group can be referenced by its
name in arguments to methods of match objects, such as
m.group('id') or m.end('id'), and also by name in
pattern text (for example, (?P=id)) and replacement text
(such as \g&lt;id&gt;).
[(?P=name)] Matches whatever text was matched by the
earlier group named name.
[(?)] A comment; the contents of the parentheses are
simply ignored.
[(?=...)] Matches if ... matches next, but doesn't
consume any of the string. This is called a lookahead assertion. For
example, Isaac (?=Asimov) will match 'Isaac~' only if it's
followed by 'Asimov'.
[(?!...)] Matches if ... doesn't match next. This
is a negative lookahead assertion. For example,
Isaac (?!Asimov) will match 'Isaac~' only if it's not
followed by 'Asimov'.
[(?&lt;=...)] Matches if the current position in the string
is preceded by a match for ... that ends at the current
position. This is called a positive lookbehind assertion.
(?&lt;=abc)def will find a match in abcdef, since the
lookbehind will back up 3 characters and check if the contained
pattern matches. The contained pattern must only match strings of
some fixed length, meaning that abc or a|b are
allowed, but a* and a{3,4} are not. Note that
patterns which start with positive lookbehind assertions will never
match at the beginning of the string being searched; you will most
likely want to use the search() function rather than the
match() function:
&gt;&gt;&gt; import re
&gt;&gt;&gt; m = re.search('(?&lt;=abc)def', 'abcdef')
&gt;&gt;&gt; m.group(0)
'def'
This example looks for a word following a hyphen:
&gt;&gt;&gt; m = re.search('(?&lt;=-)+', 'spam-egg')
&gt;&gt;&gt; m.group(0)
'egg'
[(?&lt;!...)] Matches if the current position in the string
is not preceded by a match for .... This is called a
negative lookbehind assertion. Similar to positive lookbehind
assertions, the contained pattern must only match strings of some
fixed length. Patterns which start with negative lookbehind
assertions may match at the beginning of the string being searched.
[(?(id/name)yes-pattern|no-pattern)] Will try to match
with yes-pattern if the group with given id or name
exists, and with no-pattern if it doesn't. |no-pattern
is optional and can be omitted. For example, (&lt;)?(\w+@\w+(?:\.\w+)+)(?(1)&gt;) is a poor email matching
pattern, which will match with '&lt;user@host.com&gt;' as well as
'user@host.com', but not with '&lt;user@host.com'.
New in version 2.4
The special sequences consist of \ and a character from the
list below. If the ordinary character is not on the list, then the
resulting RE will match the second character. For example,
\$ matches the character $.
{}{ 0.7in 0.65in}
[\number] Matches the contents of the group of the
same number. Groups are numbered starting from 1. For example,
(.+) \1 matches 'the the' or '55 55', but not
'the end' (note
the space after the group). This special sequence can only be used to
match one of the first 99 groups. If the first digit of number
is 0, or number is 3 octal digits long, it will not be interpreted
as a group match, but as the character with octal value number.
Inside the [ and ] of a character class, all numeric
escapes are treated as characters.
[\A] Matches only at the start of the string.
[\b] Matches the empty string, but only at the
beginning or end of a word. A word is defined as a sequence of
alphanumeric or underscore characters, so the end of a word is indicated by
whitespace or a non-alphanumeric, non-underscore character. Note that {}\b is defined as the boundary between \w and \W, so the precise set of characters deemed to be alphanumeric depends on the
values of the UNICODE and LOCALE flags. Inside a character
range, \b represents the backspace character, for compatibility
with Python's string literals.
[\B] Matches the empty string, but only when it is not
at the beginning or end of a word. This is just the opposite of {}\b, so is also subject to the settings of LOCALE and UNICODE.
[\d]Matches any decimal digit; this is
equivalent to the set [0-9].
[\D]Matches any non-digit character; this is
equivalent to the set [{}0-9].
[\s]Matches any whitespace character; this is
equivalent to the set [ \t\n\r\f\v].
[\S]Matches any non-whitespace character; this is
equivalent to the set [ t\n\r\f\v].
[\w]When the LOCALE and UNICODE
flags are not specified, matches any alphanumeric character and the
underscore; this is equivalent to the set
[a-zA-Z0-9_]. With LOCALE, it will match the set
[0-9_] plus whatever characters are defined as alphanumeric for
the current locale. If UNICODE is set, this will match the
characters [0-9_] plus whatever is classified as alphanumeric
in the Unicode character properties database.
[\W]When the LOCALE and UNICODE
flags are not specified, matches any non-alphanumeric character; this
is equivalent to the set [{}a-zA-Z0-9_]. With
LOCALE, it will match any character not in the set
[0-9_], and not defined as alphanumeric for the current locale.
If UNICODE is set, this will match anything other than
[0-9_] and characters marked as alphanumeric in the Unicode
character properties database.
[\Z]Matches only at the end of the string.
Most of the standard escapes supported by Python string literals are
also accepted by the regular expression parser:
Octal escapes are included in a limited form: If the first digit is a
0, or if there are three octal digits, it is considered an octal
escape. Otherwise, it is a group reference.
% Note the lack of a period in the section title; it causes problems
% with readers of the GNU info version. See http://www.python.org/sf/581414.
</description>
</group>
<group name="Matching vs Searching">
<description>Python offers two different primitive operations based on regular
expressions: match and search. If you are accustomed to Perl's
semantics, the search operation is what you're looking for. See the
search() function and corresponding method of compiled
regular expression objects.
Note that match may differ from search using a regular expression
beginning with :
matches only at the
start of the string, or in MULTILINE mode also immediately
following a newline. The ``match'' operation succeeds only if the
pattern matches at the start of the string regardless of mode, or at
the starting position given by the optional pos argument
regardless of whether a newline precedes it.
% Examples from Tim Peters:
re.compile(&quot;a&quot;).match(&quot;ba&quot;, 1) # succeeds
re.compile(&quot;^a&quot;).search(&quot;ba&quot;, 1) # fails; 'a' not at start
re.compile(&quot;^a&quot;).search(&quot;&quot;, 1) # fails; 'a' not at start
re.compile(&quot;^a&quot;, re.M).search(&quot;&quot;, 1) # succeeds
re.compile(&quot;^a&quot;, re.M).search(&quot;ba&quot;, 1) # fails; no preceding </description>
</group>
<group name="Module Contents">
<description>Contents of Module re
The module defines the following functions and constants, and an exception:
</description>
<element kind="function" name="compile">
<description>Compile a regular expression pattern into a regular expression
object, which can be used for matching using its match() and
search() methods, described below.
The expression's behaviour can be modified by specifying a
flags value. Values can be any of the following variables,
combined using bitwise OR (the | operator).
The sequence
prog = re.compile(pat)
result = prog.match(str)
is equivalent to
result = re.match(pat, str)
but the version using compile() is more efficient when the
expression will be used several times in a single program.
%(The compiled version of the last pattern passed to
%re.match() or re.search() is cached, so
%programs that use only a single regular expression at a time needn't
%worry about compiling regular expressions.)</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="search">
<description>Scan through string looking for a location where the regular
expression pattern produces a match, and return a
corresponding MatchObject instance.
Return None if no
position in the string matches the pattern; note that this is
different from finding a zero-length match at some point in the string.</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="string" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="match">
<description>If zero or more characters at the beginning of string match
the regular expression pattern, return a corresponding
MatchObject instance. Return None if the string does not
match the pattern; note that this is different from a zero-length
match.
If you want to locate a match anywhere in
string, use search() instead.</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="string" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="split">
<description>Split string by the occurrences of pattern. If
capturing parentheses are used in pattern, then the text of all
groups in the pattern are also returned as part of the resulting list.
If maxsplit is nonzero, at most maxsplit splits
occur, and the remainder of the string is returned as the final
element of the list. (Incompatibility note: in the original Python
1.5 release, maxsplit was ignored. This has been fixed in
later releases.)
&gt;&gt;&gt; re.split('+', 'Words, words, words.')
['Words', 'words', 'words', '']
&gt;&gt;&gt; re.split('(+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
&gt;&gt;&gt; re.split('+', 'Words, words, words.', 1)
['Words', 'words, words.']
This function combines and extends the functionality of
the old regsub.split() and regsub.splitx().</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="string" required="1"/><property default=" 0" kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="findall">
<description>Return a list of all non-overlapping matches of pattern in
string. If one or more groups are present in the pattern,
return a list of groups; this will be a list of tuples if the
pattern has more than one group. Empty matches are included in the
result unless they touch the beginning of another match.
New in version 1.5.2</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="string string" required="1"/></properties></element>

<element kind="function" name="finditer">
<description>Return an iterator over all non-overlapping matches for the RE
pattern in string. For each match, the iterator returns
a match object. Empty matches are included in the result unless they
touch the beginning of another match.
New in version 2.2</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="string string" required="1"/></properties></element>

<element kind="function" name="sub">
<description>Return the string obtained by replacing the leftmost non-overlapping
occurrences of pattern in string by the replacement
repl. If the pattern isn't found, string is returned
unchanged. repl can be a string or a function; if it is a
string, any backslash escapes in it are processed. That is,
\n is converted to a single newline character, \r
is converted to a linefeed, and so forth. Unknown escapes such as
\j are left alone. Backreferences, such as \, are
replaced with the substring matched by group 6 in the pattern. For
example:
&gt;&gt;&gt; re.sub(r'def+([a-zA-Z_][a-zA-Z_0-9]*)**'static PyObject*_)',
... 'def myfunc():')
'static PyObject*_myfunc(void)'
If repl is a function, it is called for every non-overlapping
occurrence of pattern. The function takes a single match
object argument, and returns the replacement string. For example:
&gt;&gt;&gt; def dashrepl(matchobj):
.... if matchobj.group(0) == '-': return ' '
.... else: return '-'
&gt;&gt;&gt; re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
The pattern may be a string or an RE object; if you need to specify
regular expression flags, you must use a RE object, or use embedded
modifiers in a pattern; for example, sub(&quot;(?i)b+&quot;, &quot;x&quot;, &quot;bbbb
BBBB&quot;) returns 'x x'.
The optional argument count is the maximum number of pattern
occurrences to be replaced; count must be a non-negative
integer. If omitted or zero, all occurrences will be replaced.
Empty matches for the pattern are replaced only when not adjacent to
a previous match, so sub('x*', '-', 'abc') returns
'-a-b-c-'.
In addition to character escapes and backreferences as described
above, \g&lt;name&gt; will use the substring matched by the group
named name, as defined by the (?P&lt;name&gt;...) syntax.
\g&lt;number&gt; uses the corresponding group number;
\g&lt;2&gt; is therefore equivalent to \2, but isn't
ambiguous in a replacement such as \g&lt;2&gt;0. \20
would be interpreted as a reference to group 20, not a reference to
group 2 followed by the literal character 0. The
backreference \g&lt;0&gt; substitutes in the entire substring
matched by the R</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="repl" required="1"/><property kind="parameter" name="string" required="1"/><property kind="parameter" name="count"/></properties></element>

<element kind="function" name="subn">
<description>Perform the same operation as sub(), but return a tuple
(new_string, number_of_subs_made).</description>

<properties><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="repl" required="1"/><property kind="parameter" name="string" required="1"/><property kind="parameter" name="count"/></properties></element>

<element kind="function" name="escape">
<description>Return string with all non-alphanumerics backslashed; this is
useful if you want to match an arbitrary literal string that may have
regular expression metacharacters in it.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

</group>
<group name="Regular Expression Objects">
<description>Compiled regular expression objects support the following methods and
attributes:
</description>
<element kind="function" name="match">
<description>If zero or more characters at the beginning of string match
this regular expression, return a corresponding
MatchObject instance. Return None if the string does not
match the pattern; note that this is different from a zero-length
match.
If you want to locate a match anywhere in
string, use search() instead.
The optional second parameter pos gives an index in the string
where the search is to start; it defaults to 0. This is not
completely equivalent to slicing the string; the
'' pattern
character matches at the real beginning of the string and at positions
just after a newline, but not necessarily at the index where the search
is to start.
The optional parameter endpos limits how far the string will
be searched; it will be as if the string is endpos characters
long, so only the characters from pos to endpos -
1 will be searched for a match. If endpos is less than
pos, no match will be found, otherwise, if rx is a
compiled regular expression object,
rx.match(string, 0, 50) is equivalent to
rx.match(string[:50], 0).</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="pos"/><property kind="parameter" name="endpos"/></properties></element>

<element kind="function" name="search">
<description>Scan through string looking for a location where this regular
expression produces a match, and return a
corresponding MatchObject instance. Return None if no
position in the string matches the pattern; note that this is
different from finding a zero-length match at some point in the string.
The optional pos and endpos parameters have the same
meaning as for the match() method.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="pos"/><property kind="parameter" name="endpos"/></properties></element>

<element kind="function" name="split">
<description>Identical to the split() function, using the compiled pattern.</description>

<properties><property kind="parameter" name="string" required="1"/><property default=" 0" kind="parameter" name="maxsplit"/></properties></element>

<element kind="function" name="findall">
<description>Identical to the findall() function, using the compiled pattern.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="finditer">
<description>Identical to the finditer() function, using the compiled pattern.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="sub">
<description>Identical to the sub() function, using the compiled pattern.</description>

<properties><property kind="parameter" name="repl" required="1"/><property kind="parameter" name="string" required="1"/><property default=" 0" kind="parameter" name="count"/></properties></element>

<element kind="function" name="subn">
<description>Identical to the subn() function, using the compiled pattern.</description>

<properties><property kind="parameter" name="repl" required="1"/><property kind="parameter" name="string" required="1"/><property default=" 0" kind="parameter" name="count"/></properties></element>

</group>
<group name="Match Objects">
<description>MatchObject instances support the following methods and
attributes:
</description>
<element kind="function" name="expand">
<description>Return the string obtained by doing backslash substitution on the
template string template, as done by the sub() method.
Escapes such as \n are converted to the appropriate
characters, and numeric backreferences (\1, \2) and
named backreferences (\g&lt;1&gt;, \g&lt;name&gt;) are replaced
by the contents of the corresponding group.</description>

<properties><property kind="parameter" name="templatetemplate" required="1"/></properties></element>

<element kind="function" name="group">
<description>Returns one or more subgroups of the match. If there is a single
argument, the result is a single string; if there are
multiple arguments, the result is a tuple with one item per argument.
Without arguments, group1 defaults to zero (the whole match
is returned).
If a groupN argument is zero, the corresponding return value is the
entire matching string; if it is in the inclusive range [1..99], it is
the string matching the corresponding parenthesized group. If a
group number is negative or larger than the number of groups defined
in the pattern, an IndexError exception is raised.
If a group is contained in a part of the pattern that did not match,
the corresponding result is None. If a group is contained in a
part of the pattern that matched multiple times, the last match is
returned.
If the regular expression uses the (?P&lt;name&gt;...) syntax,
the groupN arguments may also be strings identifying groups by
their group name. If a string argument is not used as a group name in
the pattern, an IndexError exception is raised.
A moderately complicated example:
m = re.match(r&quot;(?P&lt;int&gt;+)*)&quot;, '3.14')
After performing this match, m.group(1) is '3', as is
m.group('int'), and m.group(2) is '14'.</description>

<properties><property kind="parameter" name="group1" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="groups">
<description>Return a tuple containing all the subgroups of the match, from 1 up to
however many groups are in the pattern. The default argument is
used for groups that did not participate in the match; it defaults to
None. (Incompatibility note: in the original Python 1.5
release, if the tuple was one element long, a string would be returned
instead. In later versions (from 1.5.1 on), a singleton tuple is
returned in such cases.)</description>

<properties><property kind="parameter" name="default" required="1"/></properties></element>

<element kind="function" name="groupdict">
<description>Return a dictionary containing all the named subgroups of the
match, keyed by the subgroup name. The default argument is
used for groups that did not participate in the match; it defaults to
None.</description>

<properties><property kind="parameter" name="default" required="1"/></properties></element>

<element kind="function" name="start">
<description>end{group}
Return the indices of the start and end of the substring
matched by group; group defaults to zero (meaning the whole
matched substring).
Return -1 if group exists but
did not contribute to the match. For a match object
m, and a group g that did contribute to the match, the
substring matched by group g (equivalent to
m.group(g)) is
m.string[m.start(g):m.end(g)]
Note that
m.start(group) will equal m.end(group) if
group matched a null string. For example, after m =
re.search('b(c?)', 'cba'), m.start(0) is 1,
m.end(0) is 2, m.start(1) and
m.end(1) are both 2, and m.start(2) raises
an IndexError exception.</description>

<properties><property kind="parameter" name="group" required="1"/></properties></element>

<element kind="function" name="span">
<description>For MatchObject m, return the 2-tuple
(m.start(group), m.end(group)).
Note that if group did not contribute to the match, this is
(-1, -1). Again, group defaults to zero.</description>

<properties><property kind="parameter" name="group" required="1"/></properties></element>

</group>
<group name="Examples">
</group>
</group>
<group name="struct --- Interpret strings as packed binary data">
<description>Interpret strings as packed binary data.
packing{binary}{data}
This module performs conversions between Python values and C
structs represented as Python strings. It uses format strings
(explained below) as compact descriptions of the lay-out of the C
structs and the intended conversion to/from Python values. This can
be used in handling binary data stored in files or from network
connections, among other sources.
The module defines the following exception and functions:
{error}
Exception raised on various occasions; argument is a string
describing what is wrong.
</description>
<element kind="function" name="pack">
<description>Return a string containing the values
v1, v2, ... packed according to the given
format. The arguments must match the values required by the format
exactly.</description>

<properties><property kind="parameter" name="fmt" required="1"/><property kind="parameter" name="v1" required="1"/><property kind="parameter" name="v2" required="1"/><property kind="parameter" name="ldots" required="1"/></properties></element>

<element kind="function" name="unpack">
<description>Unpack the string (presumably packed by pack(fmt,
...)) according to the given format. The result is a
tuple even if it contains exactly one item. The string must contain
exactly the amount of data required by the format
(len(string) must equal calcsize(fmt)).</description>

<properties><property kind="parameter" name="fmt" required="1"/><property kind="parameter" name="string string" required="1"/></properties></element>

<element kind="function" name="calcsize">
<description>Return the size of the struct (and hence of the string)
corresponding to the given format.</description>

<properties><property kind="parameter" name="fmtfmt" required="1"/></properties></element>

</group>
<group name="difflib --- Helpers for computing deltas">
<description>Helpers for computing differences between objects.
% LaTeXification by Fred L. Drake, Jr. &lt;fdrake@acm.org&gt;.
New in version 2.1
{SequenceMatcher}
This is a flexible class for comparing pairs of sequences of any
type, so long as the sequence elements are hashable. The basic
algorithm predates, and is a little fancier than, an algorithm
published in the late 1980's by Ratcliff and Obershelp under the
hyperbolic name ``gestalt pattern matching.'' The idea is to find
the longest contiguous matching subsequence that contains no
``junk'' elements (the Ratcliff and Obershelp algorithm doesn't
address junk). The same idea is then applied recursively to the
pieces of the sequences to the left and to the right of the matching
subsequence. This does not yield minimal edit sequences, but does
tend to yield matches that ``look right'' to people.
Timing: The basic Ratcliff-Obershelp algorithm is cubic
time in the worst case and quadratic time in the expected case.
SequenceMatcher is quadratic time for the worst case and has
expected-case behavior dependent in a complicated way on how many
elements the sequences have in common; best case time is linear.
{Differ}
This is a class for comparing sequences of lines of text, and
producing human-readable differences or deltas. Differ uses
SequenceMatcher both to compare sequences of lines, and to
compare sequences of characters within similar (near-matching)
lines.
Each line of a Differ delta begins with a two-letter code:
{l|l}{code}{Code}{Meaning}
'- '{line unique to sequence 1}
'+ '{line unique to sequence 2}
' '{line common to both sequences}
'? '{line not present in either input sequence}
Lines beginning with `?~' attempt to guide the eye to
intraline differences, and were not present in either input
sequence. These lines can be confusing if the sequences contain tab
characters.
</description>
<element kind="function" name="context_diff">
<description>Compare a and b (lists of strings); return a
delta (a generator generating the delta lines) in context diff
format.
Context diffs are a compact way of showing just the lines that have
changed plus a few lines of context. The changes are shown in a
before/after style. The number of context lines is set by n
which defaults to three.
By default, the diff control lines (those with *** or ---)
are created with a trailing newline. This is helpful so that inputs created
from file.readlines() result in diffs that are suitable for use
with file.writelines() since both the inputs and outputs have
trailing newlines.
For inputs that do not have trailing newlines, set the lineterm
argument to &quot;&quot; so that the output will be uniformly newline free.
The context diff format normally has a header for filenames and
modification times. Any or all of these may be specified using strings for
fromfile, tofile, fromfiledate, and tofiledate.
The modification times are normally expressed in the format returned by
time.ctime(). If not specified, the strings default to blanks.
Tools/scripts/diff.py is a command-line front-end for this
function.
New in version 2.3</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="fromfile"/><property kind="parameter" name="tofile"/><property kind="parameter" name="fromfiledate"/><property kind="parameter" name="tofiledate"/><property kind="parameter" name="n"/><property kind="parameter" name="lineterm"/></properties></element>

<element kind="function" name="get_close_matches">
<description>Return a list of the best ``good enough'' matches. word is a
sequence for which close matches are desired (typically a string),
and possibilities is a list of sequences against which to
match word (typically a list of strings).
Optional argument n (default 3) is the maximum number
of close matches to return; n must be greater than 0.
Optional argument cutoff (default 0.6) is a float in
the range [0, 1]. Possibilities that don't score at least that
similar to word are ignored.
The best (no more than n) matches among the possibilities are
returned in a list, sorted by similarity score, most similar first.
&gt;&gt;&gt; get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
&gt;&gt;&gt; import keyword
&gt;&gt;&gt; get_close_matches('wheel', keyword.kwlist)
['while']
&gt;&gt;&gt; get_close_matches('apple', keyword.kwlist)
[]
&gt;&gt;&gt; get_close_matches('accept', keyword.kwlist)
['except']
</description>

<properties><property kind="parameter" name="word" required="1"/><property kind="parameter" name="possibilities" required="1"/><property kind="parameter" name="n"/><property kind="parameter" name="cutoff"/></properties></element>

<element kind="function" name="ndiff">
<description>Compare a and b (lists of strings); return a
Differ-style delta (a generator generating the delta lines).
Optional keyword parameters linejunk and charjunk are
for filter functions (or None):
linejunk: A function that accepts a single string
argument, and returns true if the string is junk, or false if not.
The default is (None), starting with Python 2.3. Before then,
the default was the module-level function
IS_LINE_JUNK(), which filters out lines without visible
characters, except for at most one pound character (#).
As of Python 2.3, the underlying SequenceMatcher class
does a dynamic analysis of which lines are so frequent as to
constitute noise, and this usually works better than the pre-2.3
default.
charjunk: A function that accepts a character (a string of
length 1), and returns if the character is junk, or false if not.
The default is module-level function IS_CHARACTER_JUNK(),
which filters out whitespace characters (a blank or tab; note: bad
idea to include newline in this!).
Tools/scripts/ndiff.py is a command-line front-end to this
function.
&gt;&gt;&gt; diff = ndiff('one'.splitlines(1),
... 'ore'.splitlines(1))
&gt;&gt;&gt; print ''.join(diff),
- one
? ^
+ ore
? ^
- two
- three
? -
+ tree
+ emu
</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="linejunk"/><property kind="parameter" name="charjunk"/></properties></element>

<element kind="function" name="restore">
<description>Return one of the two sequences that generated a delta.
Given a sequence produced by Differ.compare() or
ndiff(), extract lines originating from file 1 or 2
(parameter which), stripping off line prefixes.
Example:
&gt;&gt;&gt; diff = ndiff('one'.splitlines(1),
... 'ore'.splitlines(1))
&gt;&gt;&gt; diff = list(diff) # materialize the generated delta into a list
&gt;&gt;&gt; print ''.join(restore(diff, 1)),
one
two
three
&gt;&gt;&gt; print ''.join(restore(diff, 2)),
ore
tree
emu
</description>

<properties><property kind="parameter" name="sequence" required="1"/><property kind="parameter" name="which which" required="1"/></properties></element>

<element kind="function" name="unified_diff">
<description>Compare a and b (lists of strings); return a
delta (a generator generating the delta lines) in unified diff
format.
Unified diffs are a compact way of showing just the lines that have
changed plus a few lines of context. The changes are shown in a
inline style (instead of separate before/after blocks). The number
of context lines is set by n which defaults to three.
By default, the diff control lines (those with ---, +++,
or @@) are created with a trailing newline. This is helpful so
that inputs created from file.readlines() result in diffs
that are suitable for use with file.writelines() since both
the inputs and outputs have trailing newlines.
For inputs that do not have trailing newlines, set the lineterm
argument to &quot;&quot; so that the output will be uniformly newline free.
The context diff format normally has a header for filenames and
modification times. Any or all of these may be specified using strings for
fromfile, tofile, fromfiledate, and tofiledate.
The modification times are normally expressed in the format returned by
time.ctime(). If not specified, the strings default to blanks.
Tools/scripts/diff.py is a command-line front-end for this
function.
New in version 2.3</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="fromfile"/><property kind="parameter" name="tofile"/><property kind="parameter" name="fromfiledate"/><property kind="parameter" name="tofiledate"/><property kind="parameter" name="n"/><property kind="parameter" name="lineterm"/></properties></element>

<element kind="function" name="IS_LINE_JUNK">
<description>Return true for ignorable lines. The line line is ignorable
if line is blank or contains a single #,
otherwise it is not ignorable. Used as a default for parameter
linejunk in ndiff() before Python 2.3.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="IS_CHARACTER_JUNK">
<description>Return true for ignorable characters. The character ch is
ignorable if ch is a space or tab, otherwise it is not
ignorable. Used as a default for parameter charjunk in
ndiff().</description>

<properties><property kind="parameter" name="chch" required="1"/></properties></element>

<group name="SequenceMatcher Objects">
<description>The SequenceMatcher class has this constructor:
</description>
<element kind="function" name="SequenceMatcher">
<description>Optional argument isjunk must be None (the default) or
a one-argument function that takes a sequence element and returns
true if and only if the element is ``junk'' and should be ignored.
Passing None for b is equivalent to passing
lambda x: 0; in other words, no elements are ignored. For
example, pass:
lambda x: x in &quot; &quot;
if you're comparing lines as sequences of characters, and don't want
to synch up on blanks or hard tabs.
The optional arguments a and b are sequences to be
compared; both default to empty strings. The elements of both
sequences must be hashable.</description>

<properties><property kind="parameter" name="isjunk" required="1"/><property kind="parameter" name="a"/><property kind="parameter" name="b"/></properties></element>

<element kind="function" name="set_seqs">
<description>Set the two sequences to be compared.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="set_seq1">
<description>Set the first sequence to be compared. The second sequence to be
compared is not changed.</description>

<properties><property kind="parameter" name="aa" required="1"/></properties></element>

<element kind="function" name="set_seq2">
<description>Set the second sequence to be compared. The first sequence to be
compared is not changed.</description>

<properties><property kind="parameter" name="bb" required="1"/></properties></element>

<element kind="function" name="find_longest_match">
<description>Find longest matching block in a[alo:ahi]
and b[blo:bhi].
If isjunk was omitted or None,
get_longest_match() returns (i, j,
k) such that a[i:i+k] is equal
to b[j:j+k], where
alo &lt;= i &lt;= i+k &lt;= ahi and
blo &lt;= j &lt;= j+k &lt;= bhi.
For all (i', j', k') meeting those
conditions, the additional conditions
k &gt;= k',
i &lt;= i',
and if i == i', j &lt;= j'
are also met.
In other words, of all maximal matching blocks, return one that
starts earliest in a, and of all those maximal matching blocks
that start earliest in a, return the one that starts earliest
in b.
&gt;&gt;&gt; s = SequenceMatcher(None, &quot; abcd&quot;, &quot;abcd abcd&quot;)
&gt;&gt;&gt; s.find_longest_match(0, 5, 0, 9)
(0, 4, 5)
If isjunk was provided, first the longest matching block is
determined as above, but with the additional restriction that no
junk element appears in the block. Then that block is extended as
far as possible by matching (only) junk elements on both sides.
So the resulting block never matches on junk except as identical
junk happens to be adjacent to an interesting match.
Here's the same example as before, but considering blanks to be junk.
That prevents ' abcd' from matching the ' abcd' at the
tail end of the second sequence directly. Instead only the
'abcd' can match, and matches the leftmost 'abcd' in
the second sequence:
&gt;&gt;&gt; s = SequenceMatcher(lambda x: x==&quot; &quot;, &quot; abcd&quot;, &quot;abcd abcd&quot;)
&gt;&gt;&gt; s.find_longest_match(0, 5, 0, 9)
(1, 0, 4)
If no blocks match, this returns (alo, blo, 0).</description>

<properties><property kind="parameter" name="alo" required="1"/><property kind="parameter" name="ahi" required="1"/><property kind="parameter" name="blo" required="1"/><property kind="parameter" name="bhi bhi" required="1"/></properties></element>

<element kind="function" name="get_matching_blocks">
<description>Return list of triples describing matching subsequences.
Each triple is of the form (i, j, n), and
means that a[i:i+n] ==
b[j:j+n]. The triples are monotonically
increasing in i and j.
The last triple is a dummy, and has the value (len(a),
len(b), 0). It is the only triple with n == 0.
% Explain why a dummy is used!
&gt;&gt;&gt; s = SequenceMatcher(None, &quot;abxcd&quot;, &quot;abcd&quot;)
&gt;&gt;&gt; s.get_matching_blocks()
[(0, 0, 2), (3, 2, 2), (5, 4, 0)]
</description>

</element>

<element kind="function" name="get_opcodes">
<description>Return list of 5-tuples describing how to turn a into b.
Each tuple is of the form (tag, i1, i2,
j1, j2). The first tuple has i1 ==
j1 == 0, and remaining tuples have i1 equal to the
i2 from the preceeding tuple, and, likewise, j1 equal to
the previous j2.
The tag values are strings, with these meanings:
{l|l}{code}{Value}{Meaning}
'replace'{a[i1:i2] should be
replaced by b[j1:j2].}
'delete'{a[i1:i2] should be
deleted. Note that j1 == j2 in
this case.}
'insert'{b[j1:j2] should be
inserted at a[i1:i1].
Note that i1 == i2 in this
case.}
'equal'{a[i1:i2] ==
b[j1:j2] (the sub-sequences are
equal).}
For example:
&gt;&gt;&gt; a = &quot;qabxcd&quot;
&gt;&gt;&gt; b = &quot;abycdf&quot;
&gt;&gt;&gt; s = SequenceMatcher(None, a, b)
&gt;&gt;&gt; for tag, i1, i2, j1, j2 in s.get_opcodes():
... print (&quot;%7s a[%d:%d] (%s) b[%d:%d] (%s)&quot; %
... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
delete a[0:1] (q) b[0:0] ()
equal a[1:3] (ab) b[0:2] (ab)
replace a[3:4] (x) b[2:3] (y)
equal a[4:6] (cd) b[3:5] (cd)
insert a[6:6] () b[5:6] (f)
</description>

</element>

<element kind="function" name="get_grouped_opcodes">
<description>Return a generator of groups with up to n lines of context.
Starting with the groups returned by get_opcodes(),
this method splits out smaller change clusters and eliminates
intervening ranges which have no changes.
The groups are returned in the same format as get_opcodes().
New in version 2.3</description>

<properties><property kind="parameter" name="n" required="1"/></properties></element>

<element kind="function" name="ratio">
<description>Return a measure of the sequences' similarity as a float in the
range [0, 1].
Where T is the total number of elements in both sequences, and M is
the number of matches, this is 2.0*M / T. Note that this is
1.0 if the sequences are identical, and 0.0 if they
have nothing in common.
This is expensive to compute if get_matching_blocks() or
get_opcodes() hasn't already been called, in which case you
may want to try quick_ratio() or
real_quick_ratio() first to get an upper bound.</description>

</element>

<element kind="function" name="quick_ratio">
<description>Return an upper bound on ratio() relatively quickly.
This isn't defined beyond that it is an upper bound on
ratio(), and is faster to compute.</description>

</element>

<element kind="function" name="real_quick_ratio">
<description>Return an upper bound on ratio() very quickly.
This isn't defined beyond that it is an upper bound on
ratio(), and is faster to compute than either
ratio() or quick_ratio().</description>

</element>

</group>
<group name="SequenceMatcher Examples">
<description>This example compares two strings, considering blanks to be ``junk:''
&gt;&gt;&gt; s = SequenceMatcher(lambda x: x == &quot; &quot;,
... &quot;private Thread currentThread;&quot;,
... &quot;private volatile Thread currentThread;&quot;)
ratio() returns a float in [0, 1], measuring the similarity
of the sequences. As a rule of thumb, a ratio() value over
0.6 means the sequences are close matches:
&gt;&gt;&gt; print round(s.ratio(), 3)
0.866
If you're only interested in where the sequences match,
get_matching_blocks() is handy:
&gt;&gt;&gt; for block in s.get_matching_blocks():
... print &quot;a[%d] and b[%d] match for %d elements&quot; % block
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 6 elements
a[14] and b[23] match for 15 elements
a[29] and b[38] match for 0 elements
Note that the last tuple returned by get_matching_blocks() is
always a dummy, (len(a), len(b), 0), and this is
the only case in which the last tuple element (number of elements
matched) is 0.
If you want to know how to change the first sequence into the second,
use get_opcodes():
&gt;&gt;&gt; for opcode in s.get_opcodes():
... print &quot;%6s a[%d:%d] b[%d:%d]&quot; % opcode
equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
equal a[8:14] b[17:23]
equal a[14:29] b[23:38]
See also the function get_close_matches() in this module,
which shows how simple code building on SequenceMatcher can be
used to do useful work.
</description>
</group>
<group name="Differ Objects">
<description>Note that Differ-generated deltas make no claim to be
minimal diffs. To the contrary, minimal diffs are often
counter-intuitive, because they synch up anywhere possible, sometimes
accidental matches 100 pages apart. Restricting synch points to
contiguous matches preserves some notion of locality, at the
occasional cost of producing a longer diff.
The Differ class has this constructor:
</description>
<element kind="function" name="Differ">
<description>Optional keyword parameters linejunk and charjunk are
for filter functions (or None):
linejunk: A function that accepts a single string
argument, and returns true if the string is junk. The default is
None, meaning that no line is considered junk.
charjunk: A function that accepts a single character argument
(a string of length 1), and returns true if the character is junk.
The default is None, meaning that no character is
considered junk.</description>

<properties><property kind="parameter" name="linejunk" required="1"/><property kind="parameter" name="charjunk"/></properties></element>

<element kind="function" name="compare">
<description>Compare two sequences of lines, and generate the delta (a sequence
of lines).
Each sequence must contain individual single-line strings ending
with newlines. Such sequences can be obtained from the
readlines() method of file-like objects. The delta generated
also consists of newline-terminated strings, ready to be printed as-is
via the writelines() method of a file-like object.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

</group>
<group name="Differ Example">
</group>
</group>
<group name="fpformat --- Floating point conversions">
<description>General floating point formatting functions.
The fpformat module defines functions for dealing with
floating point numbers representations in 100% pure
Python. This module is unneeded: everything here could
be done via the % string interpolation operator.
The fpformat module defines the following functions and an
exception:
</description>
<element kind="function" name="fix">
<description>Format x as [-]ddd.ddd with digs digits after the
point and at least one digit before.
If digs &lt;= 0, the decimal point is suppressed.
x can be either a number or a string that looks like
one. digs is an integer.
Return value is a string.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="digs digs" required="1"/></properties></element>

<element kind="function" name="sci">
<description>Format x as [-]d.dddE[+-]ddd with digs digits after the point and exactly one digit before.
If digs &lt;= 0, one digit is kept and the point is suppressed.
x can be either a real number, or a string that looks like
one. digs is an integer.
Return value is a string.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="digs digs" required="1"/></properties></element>

</group>
<group name="StringIO --- Read and write strings as files">
<description>Read and write strings as if they were files.
This module implements a file-like class, StringIO,
that reads and writes a string buffer (also known as memory
files). See the description of file objects for operations (section
bltin-file-objects).
</description>
<element kind="function" name="StringIO">
<description>When a StringIO object is created, it can be initialized
to an existing string by passing the string to the constructor.
If no string is given, the StringIO will start empty.
The StringIO object can accept either Unicode or 8-bit
strings, but mixing the two may take some care. If both are used,
8-bit strings that cannot be interpreted as 7-bit ASCII (that
use the 8th bit) will cause a UnicodeError to be raised
when getvalue() is called.</description>

<properties><property kind="parameter" name="buffer" required="1"/></properties></element>

<element kind="function" name="getvalue">
<description>Retrieve the entire contents of the ``file'' at any time before the
StringIO object's close() method is called. See the
note above for information about mixing Unicode and 8-bit strings;
such mixing can cause this method to raise UnicodeError.</description>

</element>

<element kind="function" name="close">
<description>Free the memory buffer.</description>

</element>

</group>
<group name="textwrap --- Text wrapping and filling">
<description>Text wrapping and filling
New in version 2.3
The textwrap module provides two convenience functions,
wrap() and fill(), as well as
TextWrapper, the class that does all the work, and a utility function dedent(). If you're just wrapping or filling one or two text strings, the convenience functions should be good enough; otherwise, you should use an instance of TextWrapper for efficiency.
</description>
<element kind="function" name="wrap">
<description>Wraps the single paragraph in text (a string) so every line is at
most width characters long. Returns a list of output lines,
without final newlines.
Optional keyword arguments correspond to the instance attributes of
TextWrapper, documented below. width defaults to
70.</description>

<properties><property kind="parameter" name="text" required="1"/><property kind="parameter" name="width"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="fill">
<description>Wraps the single paragraph in text, and returns a single string
containing the wrapped paragraph. fill() is shorthand for
&quot;&quot;.join(wrap(text, ...))
In particular, fill() accepts exactly the same keyword
arguments as wrap().</description>

<properties><property kind="parameter" name="text" required="1"/><property kind="parameter" name="width"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="dedent">
<description>Remove any whitespace than can be uniformly removed from the left
of every line in text.
This is typically used to make triple-quoted strings line up with
the left edge of screen/whatever, while still presenting it in the
source code in indented form. For example:
def test():
# end first line with avoid the empty line!
s = '''
world
'''
print repr(s) # prints ' hello world '
print repr(dedent(s)) # prints 'hello world'
</description>

<properties><property kind="parameter" name="texttext" required="1"/></properties></element>

<element kind="function" name="TextWrapper">
<description>The TextWrapper constructor accepts a number of optional
keyword arguments. Each argument corresponds to one instance attribute,
so for example
wrapper = TextWrapper(initial_indent=&quot;* &quot;)
is the same as
wrapper = TextWrapper()
wrapper.initial_indent = &quot;* &quot;
You can re-use the same TextWrapper object many times, and you
can change any of its options through direct assignment to instance
attributes between uses.</description>

<properties><property kind="parameter" name="......" required="1"/></properties></element>

<element kind="function" name="wrap">
<description>Wraps the single paragraph in text (a string) so every line is
at most width characters long. All wrapping options are
taken from instance attributes of the TextWrapper instance.
Returns a list of output lines, without final newlines.</description>

<properties><property kind="parameter" name="texttext" required="1"/></properties></element>

<element kind="function" name="fill">
<description>Wraps the single paragraph in text, and returns a single string
containing the wrapped paragraph.</description>

<properties><property kind="parameter" name="texttext" required="1"/></properties></element>

</group>
<group name="codecs --- Codec registry and base classes">
<description>Encode and decode data and streams.
</description>
<element kind="function" name="register">
<description>Register a codec search function. Search functions are expected to
take one argument, the encoding name in all lower case letters, and
return a tuple of functions (encoder, decoder, stream_reader,
stream_writer) taking the following arguments:
encoder and decoder: These must be functions or methods
which have the same interface as the
encode()/decode() methods of Codec instances (see
Codec Interface). The functions/methods are expected to work in a
stateless mode.
stream_reader and stream_writer: These have to be
factory functions providing the following interface:
factory(stream, errors='strict')
The factory functions must return objects providing the interfaces
defined by the base classes StreamWriter and
StreamReader, respectively. Stream codecs can maintain
state.
Possible values for errors are 'strict' (raise an exception
in case of an encoding error), 'replace' (replace malformed
data with a suitable replacement marker, such as ?),
'ignore' (ignore malformed data and continue without further
notice), 'xmlcharrefreplace' (replace with the appropriate XML
character reference (for encoding only)) and 'backslashreplace'
(replace with backslashed escape sequences (for encoding only)) as
well as any other error handling name defined via
register_error().
In case a search function cannot find a given encoding, it should
return None.</description>

<properties><property kind="parameter" name="search_functionsearch_function" required="1"/></properties></element>

<element kind="function" name="lookup">
<description>Looks up a codec tuple in the Python codec registry and returns the
function tuple as defined above.
Encodings are first looked up in the registry's cache. If not found,
the list of registered search functions is scanned. If no codecs tuple
is found, a LookupError is raised. Otherwise, the codecs
tuple is stored in the cache and returned to the caller.</description>

<properties><property kind="parameter" name="encodingencoding" required="1"/></properties></element>

<element kind="function" name="getencoder">
<description>Lookup up the codec for the given encoding and return its encoder
function.
Raises a LookupError in case the encoding cannot be found.</description>

<properties><property kind="parameter" name="encodingencoding" required="1"/></properties></element>

<element kind="function" name="getdecoder">
<description>Lookup up the codec for the given encoding and return its decoder
function.
Raises a LookupError in case the encoding cannot be found.</description>

<properties><property kind="parameter" name="encodingencoding" required="1"/></properties></element>

<element kind="function" name="getreader">
<description>Lookup up the codec for the given encoding and return its StreamReader
class or factory function.
Raises a LookupError in case the encoding cannot be found.</description>

<properties><property kind="parameter" name="encodingencoding" required="1"/></properties></element>

<element kind="function" name="getwriter">
<description>Lookup up the codec for the given encoding and return its StreamWriter
class or factory function.
Raises a LookupError in case the encoding cannot be found.</description>

<properties><property kind="parameter" name="encodingencoding" required="1"/></properties></element>

<element kind="function" name="register_error">
<description>Register the error handling function error_handler under the
name name. error_handler will be called during encoding
and decoding in case of an error, when name is specified as the
errors parameter.
For encoding error_handler will be called with a
UnicodeEncodeError instance, which contains information about
the location of the error. The error handler must either raise this or
a different exception or return a tuple with a replacement for the
unencodable part of the input and a position where encoding should
continue. The encoder will encode the replacement and continue encoding
the original input at the specified position. Negative position values
will be treated as being relative to the end of the input string. If the
resulting position is out of bound an IndexError will be raised.
Decoding and translating works similar, except UnicodeDecodeError
or UnicodeTranslateError will be passed to the handler and
that the replacement from the error handler will be put into the output
directly.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="error_handler error_handler" required="1"/></properties></element>

<element kind="function" name="lookup_error">
<description>Return the error handler previously register under the name name.
Raises a LookupError in case the handler cannot be found.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="strict_errors">
<description>Implements the strict error handling.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="replace_errors">
<description>Implements the replace error handling.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="ignore_errors">
<description>Implements the ignore error handling.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="xmlcharrefreplace_errors_errors">
<description>Implements the xmlcharrefreplace error handling.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="backslashreplace_errors_errors">
<description>Implements the backslashreplace error handling.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="open">
<description>Open an encoded file using the given mode and return
a wrapped version providing transparent encoding/decoding.
The wrapped version will only accept the object format
defined by the codecs, i.e. objects for most built-in
codecs. Output is also codec-dependent and will usually be Unicode as
well.
encoding specifies the encoding which is to be used for the
file.
errors may be given to define the error handling. It defaults
to 'strict' which causes a ValueError to be raised
in case an encoding error occurs.
buffering has the same meaning as for the built-in
open() function. It defaults to line buffered.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode" required="1"/><property kind="parameter" name="encoding"/><property kind="parameter" name="errors"/><property kind="parameter" name="buffering"/></properties></element>

<element kind="function" name="EncodedFile">
<description>Return a wrapped version of file which provides transparent
encoding translation.
Strings written to the wrapped file are interpreted according to the
given input encoding and then written to the original file as
strings using the output encoding. The intermediate encoding will
usually be Unicode but depends on the specified codecs.
If output is not given, it defaults to input.
errors may be given to define the error handling. It defaults to
'strict', which causes ValueError to be raised in case
an encoding error occurs.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output"/><property kind="parameter" name="errors"/></properties></element>

<group name="Codec Base Classes">
<description>The codecs defines a set of base classes which define the
interface and can also be used to easily write you own codecs for use
in Python.
Each codec has to define four interfaces to make it usable as codec in
Python: stateless encoder, stateless decoder, stream reader and stream
writer. The stream reader and writers typically reuse the stateless
encoder/decoder to implement the file protocols.
The Codec class defines the interface for stateless
encoders/decoders.
To simplify and standardize error handling, the encode() and
decode() methods may implement different error handling
schemes by providing the errors string argument. The following
string values are defined and implemented by all standard Python
codecs:
{l|l}{code}{Value}{Meaning}
'strict'{Raise UnicodeError (or a subclass);
this is the default.}
'ignore'{Ignore the character and continue with the next.}
'replace'{Replace with a suitable replacement character;
Python will use the official U+FFFD REPLACEMENT
CHARACTER for the built-in Unicode codecs on
decoding and '?' on encoding.}
'xmlcharrefreplace'{Replace with the appropriate XML
character reference (only for encoding).}
'backslashreplace'{Replace with backslashed escape sequences
(only for encoding).}
The set of allowed values can be extended via register_error.
Codec Objects The Codec class defines these methods which also define the
function interfaces of the stateless encoder and decoder:
</description>
<element kind="function" name="encode">
<description>Encodes the object input and returns a tuple (output object,
length consumed). While codecs are not restricted to use with Unicode, in
a Unicode context, encoding converts a Unicode object to a plain string
using a particular character set encoding (e.g., cp1252 or
iso-8859-1).
errors defines the error handling to apply. It defaults to
'strict' handling.
The method may not store state in the Codec instance. Use
StreamCodec for codecs which have to keep state in order to
make encoding/decoding efficient.
The encoder must be able to handle zero length input and return an
empty object of the output object type in this situation.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="decode">
<description>Decodes the object input and returns a tuple (output object,
length consumed). In a Unicode context, decoding converts a plain string
encoded using a particular character set encoding to a Unicode object.
input must be an object which provides the bf_getreadbuf
buffer slot. Python strings, buffer objects and memory mapped files
are examples of objects providing this slot.
errors defines the error handling to apply. It defaults to
'strict' handling.
The method may not store state in the Codec instance. Use
StreamCodec for codecs which have to keep state in order to
make encoding/decoding efficient.
The decoder must be able to handle zero length input and return an
empty object of the output object type in this situation.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="StreamWriter">
<description>Constructor for a StreamWriter instance. All stream writers must provide this constructor interface. They are
free to add additional keyword arguments, but only the ones defined
here are used by the Python codec registry.
stream must be a file-like object open for writing (binary)
data.
The StreamWriter may implement different error handling
schemes by providing the errors keyword argument. These
parameters are predefined:
'strict' Raise ValueError (or a subclass);
this is the default.
'ignore' Ignore the character and continue with the next.
'replace' Replace with a suitable replacement character
'xmlcharrefreplace' Replace with the appropriate XML
character reference
'backslashreplace' Replace with backslashed escape sequences.
The errors argument will be assigned to an attribute of the
same name. Assigning to this attribute makes it possible to switch
between different error handling strategies during the lifetime
of the StreamWriter object.
The set of allowed values for the errors argument can
be extended with register_error().</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="write">
<description>Writes the object's contents encoded to the stream.</description>

<properties><property kind="parameter" name="objectobject" required="1"/></properties></element>

<element kind="function" name="writelines">
<description>Writes the concatenated list of strings to the stream (possibly by
reusing the write() method).</description>

<properties><property kind="parameter" name="listlist" required="1"/></properties></element>

<element kind="function" name="reset">
<description>Flushes and resets the codec buffers used for keeping state.
Calling this method should ensure that the data on the output is put
into a clean state, that allows appending of new fresh data without
having to rescan the whole stream to recover state.</description>

</element>

<element kind="function" name="StreamReader">
<description>Constructor for a StreamReader instance. All stream readers must provide this constructor interface. They are
free to add additional keyword arguments, but only the ones defined
here are used by the Python codec registry.
stream must be a file-like object open for reading (binary)
data.
The StreamReader may implement different error handling
schemes by providing the errors keyword argument. These
parameters are defined:
'strict' Raise ValueError (or a subclass);
this is the default.
'ignore' Ignore the character and continue with the next.
'replace' Replace with a suitable replacement character.
The errors argument will be assigned to an attribute of the
same name. Assigning to this attribute makes it possible to switch
between different error handling strategies during the lifetime
of the StreamReader object.
The set of allowed values for the errors argument can
be extended with register_error().</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="errors"/></properties></element>

<element kind="function" name="read">
<description>Decodes data from the stream and returns the resulting object.
size indicates the approximate maximum number of bytes to read
from the stream for decoding purposes. The decoder can modify this
setting as appropriate. The default value -1 indicates to read and
decode as much as possible. size is intended to prevent having
to decode huge files in one step.
The method should use a greedy read strategy meaning that it should
read as much data as is allowed within the definition of the encoding
and the given size, e.g. if optional encoding endings or state
markers are available on the stream, these should be read too.</description>

<properties><property kind="parameter" name="size" required="1"/></properties></element>

<element kind="function" name="readline">
<description>Read one line from the input stream and return the
decoded data.
Unlike the readlines() method, this method inherits
the line breaking knowledge from the underlying stream's
readline() method -- there is currently no support for line
breaking using the codec decoder due to lack of line buffering.
Sublcasses should however, if possible, try to implement this method
using their own knowledge of line breaking.
size, if given, is passed as size argument to the stream's
readline() method.</description>

<properties><property kind="parameter" name="[size][size]" required="1"/></properties></element>

<element kind="function" name="readlines">
<description>Read all lines available on the input stream and return them as list
of lines.
Line breaks are implemented using the codec's decoder method and are
included in the list entries.
sizehint, if given, is passed as size argument to the
stream's read() method.</description>

<properties><property kind="parameter" name="[sizehint][sizehint]" required="1"/></properties></element>

<element kind="function" name="reset">
<description>Resets the codec buffers used for keeping state.
Note that no stream repositioning should take place. This method is
primarily intended to be able to recover from decoding errors.</description>

</element>

<element kind="function" name="StreamReaderWriter">
<description>Creates a StreamReaderWriter instance.
stream must be a file-like object.
Reader and Writer must be factory functions or classes
providing the StreamReader and StreamWriter interface
resp.
Error handling is done in the same way as defined for the
stream readers and writers.</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="Reader" required="1"/><property kind="parameter" name="Writer" required="1"/><property kind="parameter" name="errors errors" required="1"/></properties></element>

<element kind="function" name="StreamRecoder">
<description>Creates a StreamRecoder instance which implements a two-way
conversion: encode and decode work on the frontend (the
input to read() and output of write()) while
Reader and Writer work on the backend (reading and
writing to the stream).
You can use these objects to do transparent direct recodings from
e.g.-1 to UTF-8 and back.
stream must be a file-like object.
encode, decode must adhere to the Codec
interface, Reader, Writer must be factory functions or
classes providing objects of the StreamReader and
StreamWriter interface respectively.
encode and decode are needed for the frontend
translation, Reader and Writer for the backend
translation. The intermediate format used is determined by the two
sets of codecs, e.g. the Unicode codecs will use Unicode as
intermediate encoding.
Error handling is done in the same way as defined for the
stream readers and writers.</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="encode" required="1"/><property kind="parameter" name="decode" required="1"/><property kind="parameter" name="Reader" required="1"/><property kind="parameter" name="Writer" required="1"/><property kind="parameter" name="errors errors" required="1"/></properties></element>

</group>
<group name="Standard Encodings">
<description>Python comes with a number of codecs builtin, either implemented as C
functions, or with dictionaries as mapping tables. The following table
lists the codecs by name, together with a few common aliases, and the
languages for which the encoding is likely used. Neither the list of
aliases nor the list of languages is meant to be exhaustive. Notice
that spelling alternatives that only differ in case or use a hyphen
instead of an underscore are also valid aliases.
Many of the character sets support the same languages. They vary in
individual characters (e.g. whether the EURO SIGN is supported or
not), and in the assignment of characters to code positions. For the
European languages in particular, the following variants typically
exist:
an ISO 8859 codeset
a Microsoft Windows code page, which is typically derived from
a 8859 codeset, but replaces control characters with additional
graphic characters
an IBM EBCDIC code page
an IBM PC code page, which is ASCII compatible
{l|l|l}{textrm}{Codec}{Aliases}{Languages}
ascii
{646, us-ascii}
{English}
cp037
{IBM037, IBM039}
{English}
cp424
{EBCDIC-CP-HE, IBM424}
{Hebrew}
cp437
{437, IBM437}
{English}
cp500
{EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500}
{Western Europe}
cp737
{}
{Greek}
cp775
{IBM775}
{Baltic languages}
cp850
{850, IBM850}
{Western Europe}
cp852
{852, IBM852}
{Central and Eastern Europe}
cp855
{855, IBM855}
{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
cp856
{}
{Hebrew}
cp857
{857, IBM857}
{Turkish}
cp860
{860, IBM860}
{Portuguese}
cp861
{861, CP-IS, IBM861}
{Icelandic}
cp862
{862, IBM862}
{Hebrew}
cp863
{863, IBM863}
{Canadian}
cp864
{IBM864}
{Arabic}
cp865
{865, IBM865}
{Danish, Norwegian}
cp869
{869, CP-GR, IBM869}
{Greek}
cp874
{}
{Thai}
cp875
{}
{Greek}
cp1006
{}
{Urdu}
cp1026
{ibm1026}
{Turkish}
cp1140
{ibm1140}
{Western Europe}
cp1250
{windows-1250}
{Central and Eastern Europe}
cp1251
{windows-1251}
{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
cp1252
{windows-1252}
{Western Europe}
cp1253
{windows-1253}
{Greek}
cp1254
{windows-1254}
{Turkish}
cp1255
{windows-1255}
{Hebrew}
cp1256
{windows1256}
{Arabic}
cp1257
{windows-1257}
{Baltic languages}
cp1258
{windows-1258}
{Vietnamese}
latin_1
{iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1}
{West Europe}
iso8859_2
{iso-8859-2, latin2, L2}
{Central and Eastern Europe}
iso8859_3
{iso-8859-3, latin3, L3}
{Esperanto, Maltese}
iso8859_4
{iso-8859-4, latin4, L4}
{Baltic languagues}
iso8859_5
{iso-8859-5, cyrillic}
{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
iso8859_6
{iso-8859-6, arabic}
{Arabic}
iso8859_7
{iso-8859-7, greek, greek8}
{Greek}
iso8859_8
{iso-8859-8, hebrew}
{Hebrew}
iso8859_9
{iso-8859-9, latin5, L5}
{Turkish}
iso8859_10
{iso-8859-10, latin6, L6}
{Nordic languages}
iso8859_13
{iso-8859-13}
{Baltic languages}
iso8859_14
{iso-8859-14, latin8, L8}
{Celtic languages}
iso8859_15
{iso-8859-15}
{Western Europe}
koi8_r
{}
{Russian}
koi8_u
{}
{Ukrainian}
mac_cyrillic
{maccyrillic}
{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
mac_greek
{macgreek}
{Greek}
mac_iceland
{maciceland}
{Icelandic}
mac_latin2
{maclatin2, maccentraleurope}
{Central and Eastern Europe}
mac_roman
{macroman}
{Western Europe}
mac_turkish
{macturkish}
{Turkish}
utf_16
{U16, utf16}
{all languages}
utf_16_be
{UTF-16BE}
{all languages (BMP only)}
utf_16_le
{UTF-16LE}
{all languages (BMP only)}
utf_7
{U7}
{all languages}
utf_8
{U8, UTF, utf8}
{all languages}
A number of codecs are specific to Python, so their codec names have
no meaning outside Python. Some of them don't convert from Unicode
strings to byte strings, but instead use the property of the Python
codecs machinery that any bijective function with one argument can be
considered as an encoding.
For the codecs listed below, the result in the ``encoding'' direction
is always a byte string. The result of the ``decoding'' direction is
listed as operand type in the table.
{l|l|l|l}{textrm}{Codec}{Aliases}{Operand type}{Purpose}
base64_codec
{base64, base-64}
{byte string}
{Convert operand to MIME base64}
bz2_codec
{bz2}
{byte string}
{Compress the operand using bz2}
hex_codec
{hex}
{byte string}
{Convert operand to hexadecimal representation, with two
digits per byte}
idna
{}
{Unicode string}
{Implements 3490.
New in version 2.3
See also encodings.idna}
mbcs
{dbcs}
{Unicode string}
{Windows only: Encode operand according to the ANSI codepage (CP_ACP)}
palmos
{}
{Unicode string}
{Encoding of PalmOS 3.5}
punycode
{}
{Unicode string}
{Implements 3492.
New in version 2.3}
quopri_codec
{quopri, quoted-printable, quotedprintable}
{byte string}
{Convert operand to MIME quoted printable}
raw_unicode_escape
{}
{Unicode string}
{Produce a string that is suitable as raw Unicode literal in
Python source code}
rot_13
{rot13}
{byte string}
{Returns the Caesar-cypher encryption of the operand}
string_escape
{}
{byte string}
{Produce a string that is suitable as string literal in
Python source code}
undefined
{}
{any}
{Raise an exception for all conversion. Can be used as the
system encoding if no automatic coercion between byte and
Unicode strings is desired.} unicode_escape
{}
{Unicode string}
{Produce a string that is suitable as Unicode literal in
Python source code}
unicode_internal
{}
{Unicode string}
{Return the internal represenation of the operand}
uu_codec
{uu}
{byte string}
{Convert the operand using uuencode}
zlib_codec
{zip, zlib}
{byte string}
{Compress the operand using gzip}
</description>
</group>
<group name="encodings.idna --- Internationalized Domain Names in Applications">
<description>Internationalized Domain Names implementation
% XXX The next line triggers a formatting bug, so it's commented out
% until that can be fixed.
%</description>
<element kind="function" name="nameprep">
<description>Return the nameprepped version of label. The implementation
currently assumes query strings, so AllowUnassigned is
true.</description>

<properties><property kind="parameter" name="labellabel" required="1"/></properties></element>

<element kind="function" name="ToASCII">
<description>Convert a label to , as specified in 3490.
UseSTD3ASCIIRules is assumed to be false.</description>

<properties><property kind="parameter" name="labellabel" required="1"/></properties></element>

<element kind="function" name="ToUnicode">
<description>Convert a label to Unicode, as specified in 3490.</description>

<properties><property kind="parameter" name="labellabel" required="1"/></properties></element>

</group>
</group>
<group name="unicodedata --- Unicode Database">
<description>Access the Unicode Database.
</description>
<element kind="function" name="lookup">
<description>Look up character by name. If a character with the
given name is found, return the corresponding Unicode
character. If not found, KeyError is raised.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="name">
<description>Returns the name assigned to the Unicode character
unichr as a string. If no name is defined,
default is returned, or, if not given,
ValueError is raised.</description>

<properties><property kind="parameter" name="unichr" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="decimal">
<description>Returns the decimal value assigned to the Unicode character
unichr as integer. If no such value is defined,
default is returned, or, if not given,
ValueError is raised.</description>

<properties><property kind="parameter" name="unichr" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="digit">
<description>Returns the digit value assigned to the Unicode character
unichr as integer. If no such value is defined,
default is returned, or, if not given,
ValueError is raised.</description>

<properties><property kind="parameter" name="unichr" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="numeric">
<description>Returns the numeric value assigned to the Unicode character
unichr as float. If no such value is defined, default is
returned, or, if not given, ValueError is raised.</description>

<properties><property kind="parameter" name="unichr" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="category">
<description>Returns the general category assigned to the Unicode character
unichr as string.</description>

<properties><property kind="parameter" name="unichrunichr" required="1"/></properties></element>

<element kind="function" name="bidirectional">
<description>Returns the bidirectional category assigned to the Unicode character
unichr as string. If no such value is defined, an empty string
is returned.</description>

<properties><property kind="parameter" name="unichrunichr" required="1"/></properties></element>

<element kind="function" name="combining">
<description>Returns the canonical combining class assigned to the Unicode
character unichr as integer. Returns 0 if no combining
class is defined.</description>

<properties><property kind="parameter" name="unichrunichr" required="1"/></properties></element>

<element kind="function" name="mirrored">
<description>Returns the mirrored property of assigned to the Unicode character
unichr as integer. Returns 1 if the character has been
identified as a ``mirrored'' character in bidirectional text,
0 otherwise.</description>

<properties><property kind="parameter" name="unichrunichr" required="1"/></properties></element>

<element kind="function" name="decomposition">
<description>Returns the character decomposition mapping assigned to the Unicode
character unichr as string. An empty string is returned in case
no such mapping is defined.</description>

<properties><property kind="parameter" name="unichrunichr" required="1"/></properties></element>

<element kind="function" name="normalize">
<description>Return the normal form form for the Unicode string unistr.
Valid values for form are 'NFC', 'NFKC', 'NFD', and 'NFKD'.
The Unicode standard defines various normalization forms of a Unicode
string, based on the definition of canonical equivalence and
compatibility equivalence. In Unicode, several characters can be
expressed in various way. For example, the character U+00C7 (LATIN
CAPITAL LETTER C WITH CEDILLA) can also be expressed as the sequence
U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
For each character, there are two normal forms: normal form C and
normal form D. Normal form D (NFD) is also known as canonical
decomposition, and translates each character into its decomposed form.
Normal form C (NFC) first applies a canonical decomposition, then
composes pre-combined characters again.
In addition to these two forms, there two additional normal forms
based on compatibility equivalence. In Unicode, certain characters are
supported which normally would be unified with other characters. For
example, U+2160 (ROMAN NUMERAL ONE) is really the same thing as U+0049
(LATIN CAPITAL LETTER I). However, it is supported in Unicode for
compatibility with existing character sets (e.g. gb2312).
The normal form KD (NFKD) will apply the compatibility decomposition,
i.e. replace all compatibility characters with their equivalents. The
normal form KC (NFKC) first applies the compatibility decomposition,
followed by the canonical composition.
New in version 2.3</description>

<properties><property kind="parameter" name="form" required="1"/><property kind="parameter" name="unistr unistr" required="1"/></properties></element>

</group>
<group name="stringprep --- Internet String Preparation">
<description>String preparation, as per RFC 3453
When identifying things (such as host names) in the internet, it is
often necessary to compare such identifications for
``equality''. Exactly how this comparison is executed may depend on
the application domain, e.g. whether it should be case-insensitive or
not. It may be also necessary to restrict the possible
identifications, to allow only identifications consisting of
``printable'' characters.
3454 defines a procedure for ``preparing'' Unicode strings in
internet protocols. Before passing strings onto the wire, they are
processed with the preparation procedure, after which they have a
certain normalized form. The RFC defines a set of tables, which can be
combined into profiles. Each profile must define which tables it uses,
and what other optional parts of the stringprep procedure are
part of the profile. One example of a stringprep profile is
nameprep, which is used for internationalized domain names.
The module stringprep only exposes the tables from RFC
3454. As these tables would be very large to represent them as
dictionaries or lists, the module uses the Unicode character database
internally. The module source code itself was generated using the
mkstringprep.py utility.
As a result, these tables are exposed as functions, not as data
structures. There are two kinds of tables in the RFC: sets and
mappings. For a set, stringprep provides the ``characteristic
function'', i.e. a function that returns true if the parameter is part
of the set. For mappings, it provides the mapping function: given the
key, it returns the associated value. Below is a list of all functions
available in the module.
</description>
<element kind="function" name="in_table_a1">
<description>Determine whether code is in table{A.1} (Unassigned code points
in Unicode 3.2).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_b1">
<description>Determine whether code is in table{B.1} (Commonly mapped to
nothing).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="map_table_b2">
<description>Return the mapped value for code according to table{B.2} (Mapping for case-folding used with NFKC).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="map_table_b3">
<description>Return the mapped value for code according to table{B.3} (Mapping for case-folding used with no normalization).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c11">
<description>Determine whether code is in table{C.1.1} (ASCII space characters).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c12">
<description>Determine whether code is in table{C.1.2} (Non-ASCII space characters).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c11_c12">
<description>Determine whether code is in table{C.1} (Space characters, union of C.1.1 and C.1.2).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c21">
<description>Determine whether code is in table{C.2.1} (ASCII control characters).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c22">
<description>Determine whether code is in table{C.2.2} (Non-ASCII control characters).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c21_c22">
<description>Determine whether code is in table{C.2} (Control characters, union of C.2.1 and C.2.2).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c3">
<description>Determine whether code is in table{C.3} (Private use).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c4">
<description>Determine whether code is in table{C.4} (Non-character code points).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c5">
<description>Determine whether code is in table{C.5} (Surrogate codes).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c6">
<description>Determine whether code is in table{C.6} (Inappropriate for plain text).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c7">
<description>Determine whether code is in table{C.7} (Inappropriate for canonical representation).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c8">
<description>Determine whether code is in table{C.8} (Change display properties or are deprecated).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_c9">
<description>Determine whether code is in table{C.9} (Tagging characters).</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_d1">
<description>Determine whether code is in table{D.1} (Characters with bidirectional property ``R'' or ``AL'').</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="in_table_d2">
<description>Determine whether code is in table{D.2} (Characters with bidirectional property ``L'').</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

</group>
</group>
<group name="Miscellaneous Services">
<group name="pydoc --- Documentation generator and online help system">
</group>
<group name="doctest --- Test docstrings represent reality">
<description>A framework for verifying examples in docstrings.
The doctest module searches a module's docstrings for text that looks
like an interactive Python session, then executes all such sessions to verify
they still work exactly as shown. Here's a complete but small example:
&quot;&quot;&quot;
This is module example.
Example supplies one function, factorial. For example,
&gt;&gt;&gt; factorial(5)
120
&quot;&quot;&quot;
def factorial(n):
&quot;&quot;&quot;Return the factorial of n, an exact integer &gt;= 0.
If the result is small enough to fit in an int, return an int.
Else return a long.
&gt;&gt;&gt; [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
&gt;&gt;&gt; [factorial(long(n)) for n in range(6)]
[1, 1, 2, 6, 24, 120]
&gt;&gt;&gt; factorial(30)
265252859812191058636308480000000L
&gt;&gt;&gt; factorial(30L)
265252859812191058636308480000000L
&gt;&gt;&gt; factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be &gt;= 0
Factorials of floats are OK, but the float must be an exact integer:
&gt;&gt;&gt; factorial(30.1)
Traceback (most recent call last):
...
ValueError: n must be exact integer
&gt;&gt;&gt; factorial(30.0)
265252859812191058636308480000000L
It must also not be ridiculously large:
&gt;&gt;&gt; factorial(1e100)
Traceback (most recent call last):
...
OverflowError: n too large
&quot;&quot;&quot;
% allow LaTeX to break here.
import math
if not n &gt;= 0:
raise ValueError(&quot;n must be &gt;= 0&quot;)
if math.floor(n) != n:
raise ValueError(&quot;n must be exact integer&quot;)
if n+1 == n: # catch a value like 1e300
raise OverflowError(&quot;n too large&quot;)
result = 1
factor = 2
while factor &lt;= n:
try:
result *= factor
except OverflowError:
result *= long(factor)
factor += 1
return result
def _test():
import doctest, example
return doctest.testmod(example)
if __name__ == &quot;__main__&quot;:
_test()
If you run example.py directly from the command line,
doctest works its magic:
$ python example.py
$
There's no output! That's normal, and it means all the examples
worked. Pass -v to the script, and doctest
prints a detailed log of what it's trying, and prints a summary at the
end:
$ python example.py -v
Running example.__doc__
Trying: factorial(5)
Expecting: 120
ok
0 of 1 examples failed in example.__doc__
Running example.factorial.__doc__
Trying: [factorial(n) for n in range(6)]
Expecting: [1, 1, 2, 6, 24, 120]
ok
Trying: [factorial(long(n)) for n in range(6)]
Expecting: [1, 1, 2, 6, 24, 120]
ok
Trying: factorial(30)
Expecting: 265252859812191058636308480000000L
ok
And so on, eventually ending with:
Trying: factorial(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
0 of 8 examples failed in example.factorial.__doc__
2 items passed all tests:
1 tests in example
8 tests in example.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$
That's all you need to know to start making productive use of
doctest! Jump in. The docstrings in doctest.py contain
detailed information about all aspects of doctest, and we'll
just cover the more important points here.
</description>
<group name="Normal Usage">
<description>In normal use, end each module M with:
def _test():
import doctest, M # replace M with your module's name
return doctest.testmod(M) # ditto
if __name__ == &quot;__main__&quot;:
_test()
If you want to test the module as the main module, you don't need to
pass M to testmod(); in this case, it will test the current
module.
Then running the module as a script causes the examples in the docstrings
to get executed and verified:
python M.py
This won't display anything unless an example fails, in which case the
failing example(s) and the cause(s) of the failure(s) are printed to stdout,
and the final line of output is 'Test failed.'.
Run it with the -v switch instead:
python M.py -v
and a detailed report of all examples tried is printed to standard
output, along with assorted summaries at the end.
You can force verbose mode by passing verbose=1 to
testmod(), or
prohibit it by passing verbose=0. In either of those cases,
sys.argv is not examined by testmod().
In any case, testmod() returns a 2-tuple of ints (f,
t), where f is the number of docstring examples that
failed and t is the total number of docstring examples
attempted.
</description>
</group>
<group name="Which Docstrings Are Examined?">
<description>See the docstrings in doctest.py for all the details. They're
unsurprising: the module docstring, and all function, class and method
docstrings are searched. Optionally, the tester can be directed to
exclude docstrings attached to objects with private names. Objects
imported into the module are not searched.
In addition, if M.__test__ exists and &quot;is true&quot;, it must be a
dict, and each entry maps a (string) name to a function object, class
object, or string. Function and class object docstrings found from
M.__test__ are searched even if the tester has been
directed to skip over private names in the rest of the module.
In output, a key K in M.__test__ appears with name
&lt;name of M&gt;.__test__.K
Any classes found are recursively searched similarly, to test docstrings in
their contained methods and nested classes. While private names reached
from M's globals can be optionally skipped, all names reached from
M.__test__ are searched.
</description>
</group>
<group name="What's the Execution Context?">
<description>By default, each time testmod() finds a docstring to test, it uses
a copy of M's globals, so that running tests on a module
doesn't change the module's real globals, and so that one test in
M can't leave behind crumbs that accidentally allow another test
to work. This means examples can freely use any names defined at top-level
in M, and names defined earlier in the docstring being run.
You can force use of your own dict as the execution context by passing
globs=your_dict to testmod() instead. Presumably this
would be a copy of M.__dict__ merged with the globals from other
imported modules.
</description>
</group>
<group name="What About Exceptions?">
<description>No problem, as long as the only output generated by the example is the
traceback itself. For example:
&gt;&gt;&gt; [1, 2, 3].remove(42)
Traceback (most recent call last):
File &quot;&lt;stdin&gt;&quot;, line 1, in ?
ValueError: list.remove(x): x not in list
&gt;&gt;&gt;
Note that only the exception type and value are compared (specifically,
only the last line in the traceback). The various ``File'' lines in
between can be left out (unless they add significantly to the documentation
value of the example).
</description>
</group>
<group name="Advanced Usage">
<description>Several module level functions are available for controlling how doctests
are run.
</description>
<element kind="function" name="debug">
<description>Debug a single docstring containing doctests.
Provide the module (or dotted name of the module) containing the
docstring to be debugged and the name (within the module) of the
object with the docstring to be debugged.
The doctest examples are extracted (see function testsource()),
and written to a temporary file. The Python debugger, pdb,
is then invoked on that file.
New in version 2.3</description>

<properties><property kind="parameter" name="module" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="testmod">
<description>This function provides the most basic interface to the doctests.
It creates a local instance of class Tester, runs appropriate
methods of that class, and merges the results into the global Tester
instance, master.
To get finer control than testmod() offers, create an instance
of Tester with custom policies, or run methods of master
directly. See Tester.__doc__ for details.</description>

</element>

<element kind="function" name="testsource">
<description>Extract the doctest examples from a docstring.
Provide the module (or dotted name of the module) containing the
tests to be extracted and the name (within the module) of the object
with the docstring containing the tests to be extracted.
The doctest examples are returned as a string containing Python
code. The expected output blocks in the examples are converted
to Python comments.
New in version 2.3</description>

<properties><property kind="parameter" name="module" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="DocTestSuite">
<description>Convert doctest tests for a module to a
unittest.TestSuite.
The returned TestSuite is to be run by the unittest framework
and runs each doctest in the module. If any of the doctests fail,
then the synthesized unit test fails, and a DocTestTestFailure
exception is raised showing the name of the file containing the test and a
(sometimes approximate) line number.
The optional module argument provides the module to be tested. It
can be a module object or a (possibly dotted) module name. If not
specified, the module calling this function is used.
Example using one of the many ways that the unittest module
can use a TestSuite:
import unittest
import doctest
import my_module_with_doctests
suite = doctest.DocTestSuite(my_module_with_doctests)
runner = unittest.TextTestRunner()
runner.run(suite)
New in version 2.3
This function does not currently search M.__test__
and its search technique does not exactly match testmod() in
every detail. Future versions will bring the two into convergence.</description>

<properties><property kind="parameter" name="module" required="1"/></properties></element>

</group>
<group name="How are Docstring Examples Recognized?">
<description>In most cases a copy-and-paste of an interactive console session works
fine---just make sure the leading whitespace is rigidly consistent
(you can mix tabs and spaces if you're too lazy to do it right, but
doctest is not in the business of guessing what you think a tab
means).
&gt;&gt;&gt; # comments are ignored
&gt;&gt;&gt; x = 12
&gt;&gt;&gt; x
12
&gt;&gt;&gt; if x == 13:
... print &quot;yes&quot;
... else:
... print &quot;no&quot;
... print &quot;NO&quot;
... print &quot;NO!!!&quot;
...
no
NO
NO!!!
&gt;&gt;&gt;
Any expected output must immediately follow the final
'&gt;&gt;&gt;~' or '...~' line containing the code, and
the expected output (if any) extends to the next '&gt;&gt;&gt;~'
or all-whitespace line.
The fine print:
Expected output cannot contain an all-whitespace line, since such a
line is taken to signal the end of expected output.
Output to stdout is captured, but not output to stderr (exception
tracebacks are captured via a different means).
If you continue a line via backslashing in an interactive session, or
for any other reason use a backslash, you need to double the backslash in
the docstring version. This is simply because you're in a string, and so
the backslash must be escaped for it to survive intact. Like:
&gt;&gt;&gt; if &quot;yes&quot; == &quot; + &quot;:
... print 'yes'
yes
The starting column doesn't matter:
&gt;&gt;&gt; assert &quot;Easy!&quot;
&gt;&gt;&gt; import math
&gt;&gt;&gt; math.floor(1.9)
1.0
and as many leading whitespace characters are stripped from the
expected output as appeared in the initial '&gt;&gt;&gt;~' line
that triggered it.
</description>
</group>
<group name="Warnings">
<description>doctest is serious about requiring exact matches in expected
output. If even a single character doesn't match, the test fails. This
will probably surprise you a few times, as you learn exactly what Python
does and doesn't guarantee about output. For example, when printing a
dict, Python doesn't guarantee that the key-value pairs will be printed
in any particular order, so a test like
% Hey! What happened to Monty Python examples?
% Tim: ask Guido -- it's his example!
&gt;&gt;&gt; foo()
{&quot;Hermione&quot;: &quot;hippogryph&quot;, &quot;Harry&quot;: &quot;broomstick&quot;}
&gt;&gt;&gt;
is vulnerable! One workaround is to do
&gt;&gt;&gt; foo() == {&quot;Hermione&quot;: &quot;hippogryph&quot;, &quot;Harry&quot;: &quot;broomstick&quot;}
True
&gt;&gt;&gt;
instead. Another is to do
&gt;&gt;&gt; d = foo().items()
&gt;&gt;&gt; d.sort()
&gt;&gt;&gt; d
[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
There are others, but you get the idea.
Another bad idea is to print things that embed an object address, like
&gt;&gt;&gt; id(1.0) # certain to fail some of the time
7948648
&gt;&gt;&gt;
Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for float
formatting, and C libraries vary widely in quality here.
&gt;&gt;&gt; 1./7 # risky
0.14285714285714285
&gt;&gt;&gt; print 1./7 # safer
0.142857142857
&gt;&gt;&gt; print round(1./7, 6) # much safer
0.142857
Numbers of the form I/2.**J are safe across all platforms, and I
often contrive doctest examples to produce numbers of that form:
&gt;&gt;&gt; 3./4 # utterly safe
0.75
Simple fractions are also easier for people to understand, and that makes
for better documentation.
Be careful if you have code that must only execute once.
If you have module-level code that must only execute once, a more foolproof
definition of _test() is
def _test():
import doctest, sys
doctest.testmod()
WYSIWYG isn't always the case, starting in Python 2.3. The
string form of boolean results changed from '0' and
'1' to 'False' and 'True' in Python 2.3.
This makes it clumsy to write a doctest showing boolean results that
passes under multiple versions of Python. In Python 2.3, by default,
and as a special case, if an expected output block consists solely
of '0' and the actual output block consists solely of
'False', that's accepted as an exact match, and similarly for
'1' versus 'True'. This behavior can be turned off by
passing the new (in 2.3) module constant
DONT_ACCEPT_TRUE_FOR_1 as the value of testmod()'s
new (in 2.3) optional optionflags argument. Some years after
the integer spellings of booleans are history, this hack will
probably be removed again.
</description>
</group>
<group name="Soapbox">
</group>
</group>
<group name="unittest --- Unit testing framework">
<description>Unit testing framework for Python.
New in version 2.1
The Python unit testing framework, often referred to as ``PyUnit,'' is
a Python language version of JUnit, by Kent Beck and Erich Gamma.
JUnit is, in turn, a Java version of Kent's Smalltalk testing
framework. Each is the de facto standard unit testing framework for
its respective language.
PyUnit supports test automation, sharing of setup and shutdown code
for tests, aggregation of tests into collections, and independence of
the tests from the reporting framework. The unittest module
provides classes that make it easy to support these qualities for a
set of tests.
To achieve this, PyUnit supports some important concepts:
test fixture
A test fixture represents the preparation needed to perform one
or more tests, and any associate cleanup actions. This may involve,
for example, creating temporary or proxy databases, directories, or
starting a server process.
test case
A test case is the smallest unit of testing. It checks for a
specific response to a particular set of inputs. PyUnit provides a
base class, TestCase, which may be used to create new test
cases.
test suite
A test suite is a collection of test cases, test suites, or
both. It is used to aggregate tests that should be executed
together.
test runner
A test runner is a component which orchestrates the execution of
tests and provides the outcome to the user. The runner may use a
graphical interface, a textual interface, or return a special value to
indicate the results of executing the tests.
The test case and test fixture concepts are supported through the
TestCase and FunctionTestCase classes; the former
should be used when creating new tests, and the latter can be used when
integrating existing test code with a PyUnit-driven framework. When
building test fixtures using TestCase, the setUp()
and tearDown() methods can be overridden to provide
initialization and cleanup for the fixture. With
FunctionTestCase, existing functions can be passed to the
constructor for these purposes. When the test is run, the
fixture initialization is run first; if it succeeds, the cleanup
method is run after the test has been executed, regardless of the
outcome of the test. Each instance of the TestCase will only
be used to run a single test method, so a new fixture is created for
each test.
Test suites are implemented by the TestSuite class. This
class allows individual tests and test suites to be aggregated; when
the suite is executed, all tests added directly to the suite and in
``child'' test suites are run.
A test runner is an object that provides a single method,
run(), which accepts a TestCase or TestSuite
object as a parameter, and returns a result object. The class
TestResult is provided for use as the result object. PyUnit
provide the TextTestRunner as an example test runner which
reports test results on the standard error stream by default.
Alternate runners can be implemented for other environments (such as
graphical environments) without any need to derive from a specific
class.
See also PyUnit Web Site - The
source for further information on PyUnit.
See also Simple Smalltalk
Testing: With Patterns - Kent Beck's original paper on
testing frameworks using the pattern shared by
\module{unittest}.
</description>
<group name="Basic example">
<description>The unittest module provides a rich set of tools for
constructing and running tests. This section demonstrates that a
small subset of the tools suffice to meet the needs of most users.
Here is a short script to test three functions from the
random module:
import random
import unittest
class TestSequenceFunctions(unittest.TestCase):
def setUp(self):
self.seq = range(10)
def testshuffle(self):
# make sure the shuffled sequence does not lose any elements
random.shuffle(self.seq)
self.seq.sort()
self.assertEqual(self.seq, range(10))
def testchoice(self):
element = random.choice(self.seq)
self.assert_(element in self.seq)
def testsample(self):
self.assertRaises(ValueError, random.sample, self.seq, 20)
for element in random.sample(self.seq, 5):
self.assert_(element in self.seq)
if __name__ == '__main__':
unittest.main()
A testcase is created by subclassing unittest.TestCase.
The three individual tests are defined with methods whose names start with
the letters test. This naming convention informs the test runner
about which methods represent tests.
The crux of each test is a call to assertEqual() to
check for an expected result; assert_() to verify a condition;
or assertRaises() to verify that an expected exception gets
raised. These methods are used instead of the assert statement
so the test runner can accumulate all test results and produce a report.
When a setUp() method is defined, the test runner will run that
method prior to each test. Likewise, if a tearDown() method is
defined, the test runner will invoke that method after each test. In the
example, setUp() was used to create a fresh sequence for each test.
The final block shows a simple way to run the tests. unittest.main()
provides a command line interface to the test script. When run from the
command line, the above script produces an output that looks like this:
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OK
Instead of unittest.main(), there are other ways to run the tests
with a finer level of control, less terse output, and no requirement to be
run from the command line. For example, the last two lines may be replaced
with:
suite = unittest.TestSuite()
suite.addTest(unittest.makeSuite(TestSequenceFunctions))
unittest.TextTestRunner(verbosity=2).run(suite)
Running the revised script from the interpreter or another script
produces the following output:
testchoice (__main__.TestSequenceFunctions) ... ok
testsample (__main__.TestSequenceFunctions) ... ok
testshuffle (__main__.TestSequenceFunctions) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.110s
OK
The above examples show the most commonly used unittest features
which are sufficient to meet many everyday testing needs. The remainder
of the documentation explores the full feature set from first principles.
</description>
</group>
<group name="Organizing test code">
<description>The basic building blocks of unit testing are test cases ---
single scenarios that must be set up and checked for correctness. In
PyUnit, test cases are represented by instances of the
TestCase class in the unittest module. To make
your own test cases you must write subclasses of TestCase, or
use FunctionTestCase.
An instance of a TestCase-derived class is an object that can
completely run a single test method, together with optional set-up
and tidy-up code.
The testing code of a TestCase instance should be entirely
self contained, such that it can be run either in isolation or in
arbitrary combination with any number of other test cases.
The simplest test case subclass will simply override the
runTest() method in order to perform specific testing code:
import unittest
class DefaultWidgetSizeTestCase(unittest.TestCase):
def runTest(self):
widget = Widget(&quot;The widget&quot;)
self.failUnless(widget.size() == (50,50), 'incorrect default size')
Note that in order to test something, we use the one of the
assert*() or fail*() methods provided by the
TestCase base class. If the test fails when the test case
runs, an exception will be raised, and the testing framework will
identify the test case as a failure. Other exceptions that do
not arise from checks made through the assert*() and
fail*() methods are identified by the testing framework as
dfn{errors}.
The way to run a test case will be described later. For now, note
that to construct an instance of such a test case, we call its
constructor without arguments:
testCase = DefaultWidgetSizeTestCase()
Now, such test cases can be numerous, and their set-up can be
repetitive. In the above case, constructing a ``Widget'' in each of
100 Widget test case subclasses would mean unsightly duplication.
Luckily, we can factor out such set-up code by implementing a method
called setUp(), which the testing framework will
automatically call for us when we run the test:
import unittest
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget(&quot;The widget&quot;)
class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.failUnless(self.widget.size() == (50,50),
'incorrect default size')
class WidgetResizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.widget.resize(100,150)
self.failUnless(self.widget.size() == (100,150),
'wrong size after resize')
If the setUp() method raises an exception while the test is
running, the framework will consider the test to have suffered an
error, and the runTest() method will not be executed.
Similarly, we can provide a tearDown() method that tidies up
after the runTest() method has been run:
import unittest
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget(&quot;The widget&quot;)
def tearDown(self):
self.widget.dispose()
self.widget = None
If setUp() succeeded, the tearDown() method will be
run regardless of whether or not runTest() succeeded.
Such a working environment for the testing code is called a
fixture.
Often, many small test cases will use the same fixture. In this case,
we would end up subclassing SimpleWidgetTestCase into many
small one-method classes such as
DefaultWidgetSizeTestCase. This is time-consuming and
discouraging, so in the same vein as JUnit, PyUnit provides a simpler
mechanism:
import unittest
class WidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget(&quot;The widget&quot;)
def tearDown(self):
self.widget.dispose()
self.widget = None
def testDefaultSize(self):
self.failUnless(self.widget.size() == (50,50),
'incorrect default size')
def testResize(self):
self.widget.resize(100,150)
self.failUnless(self.widget.size() == (100,150),
'wrong size after resize')
Here we have not provided a runTest() method, but have
instead provided two different test methods. Class instances will now
each run one of the test*() methods, with self.widget
created and destroyed separately for each instance. When creating an
instance we must specify the test method it is to run. We do this by
passing the method name in the constructor:
defaultSizeTestCase = WidgetTestCase(&quot;testDefaultSize&quot;)
resizeTestCase = WidgetTestCase(&quot;testResize&quot;)
Test case instances are grouped together according to the features
they test. PyUnit provides a mechanism for this: the test
suite, represented by the class TestSuite in the
unittest module:
widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase(&quot;testDefaultSize&quot;))
widgetTestSuite.addTest(WidgetTestCase(&quot;testResize&quot;))
For the ease of running tests, as we will see later, it is a good
idea to provide in each test module a callable object that returns a
pre-built test suite:
def suite():
suite = unittest.TestSuite()
suite.addTest(WidgetTestCase(&quot;testDefaultSize&quot;))
suite.addTest(WidgetTestCase(&quot;testResize&quot;))
return suite
or even:
class WidgetTestSuite(unittest.TestSuite):
def __init__(self):
unittest.TestSuite.__init__(self,map(WidgetTestCase,
(&quot;testDefaultSize&quot;,
&quot;testResize&quot;)))
(The latter is admittedly not for the faint-hearted!)
Since it is a common pattern to create a TestCase subclass
with many similarly named test functions, there is a convenience
function called makeSuite() provided in the
unittest module that constructs a test suite that
comprises all of the test cases in a test case class:
suite = unittest.makeSuite(WidgetTestCase,'test')
Note that when using the makeSuite() function, the order in
which the various test cases will be run by the test suite is the
order determined by sorting the test function names using the
cmp() built-in function.
Often it is desirable to group suites of test cases together, so as to
run tests for the whole system at once. This is easy, since
TestSuite instances can be added to a TestSuite just
as TestCase instances can be added to a TestSuite:
suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite((suite1, suite2))
You can place the definitions of test cases and test suites in the
same modules as the code they are to test (such as widget.py),
but there are several advantages to placing the test code in a
separate module, such as widgettests.py:
The test module can be run standalone from the command line.
The test code can more easily be separated from shipped code.
There is less temptation to change test code to fit the code
it tests without a good reason.
Test code should be modified much less frequently than the
code it tests.
Tested code can be refactored more easily.
Tests for modules written in C must be in separate modules
anyway, so why not be consistent?
If the testing strategy changes, there is no need to change
the source code.
</description>
</group>
<group name="Re-using old test code">
<description>Some users will find that they have existing test code that they would
like to run from PyUnit, without converting every old test function to
a TestCase subclass.
For this reason, PyUnit provides a FunctionTestCase class.
This subclass of TestCase can be used to wrap an existing test
function. Set-up and tear-down functions can also optionally be
wrapped.
Given the following test function:
def testSomething():
something = makeSomething()
assert something.name is not None
# ...
one can create an equivalent test case instance as follows:
testcase = unittest.FunctionTestCase(testSomething)
If there are additional set-up and tear-down methods that should be
called as part of the test case's operation, they can also be provided:
testcase = unittest.FunctionTestCase(testSomething,
setUp=makeSomethingDB,
tearDown=deleteSomethingDB)
PyUnit supports the use of AssertionError
as an indicator of test failure, but does not recommend it. Future
versions may treat AssertionError differently.
</description>
</group>
<group name="Classes and functions">
<element kind="function" name="TestCase">
<description>Instances of the TestCase class represent the smallest
testable units in a set of tests. This class is intended to be used
as a base class, with specific tests being implemented by concrete
subclasses. This class implements the interface needed by the test
runner to allow it to drive the test, and methods that the test code
can use to check for and report various kinds of failures.</description>

</element>

<element kind="function" name="FunctionTestCase">
<description>This class implements the portion of the TestCase interface
which allows the test runner to drive the test, but does not provide
the methods which test code can use to check and report errors.
This is used to create test cases using legacy test code, allowing
it to be integrated into a unittest-based test
framework.</description>

<properties><property kind="parameter" name="testFunc" required="1"/><property kind="parameter" name="setUp"/><property kind="parameter" name="tearDown"/><property kind="parameter" name="description"/></properties></element>

<element kind="function" name="TestSuite">
<description>This class represents an aggregation of individual tests cases and
test suites. The class presents the interface needed by the test
runner to allow it to be run as any other test case, but all the
contained tests and test suites are executed. Additional methods
are provided to add test cases and suites to the aggregation. If
tests is given, it must be a sequence of individual tests that
will be added to the suite.</description>

<properties><property kind="parameter" name="tests" required="1"/></properties></element>

<element kind="function" name="TestLoader">
<description>This class is responsible for loading tests according to various
criteria and returning them wrapped in a TestSuite.
It can load all tests within a given module or TestCase
class. When loading from a module, it considers all
TestCase-derived classes. For each such class, it creates
an instance for each method with a name beginning with the string
test.</description>

</element>

<element kind="function" name="TextTestRunner">
<description>A basic test runner implementation which prints results on standard
output. It has a few configurable parameters, but is essentially
very simple. Graphical applications which run test suites should
provide alternate implementations.</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="descriptions"/><property kind="parameter" name="verbosity"/></properties></element>

<element kind="function" name="main">
<description>A command-line program that runs a set of tests; this is primarily
for making test modules conveniently executable. The simplest use
for this function is:
if __name__ == '__main__':
unittest.main()
</description>

<properties><property kind="parameter" name="module" required="1"/><property kind="parameter" name="defaultTest"/><property kind="parameter" name="argv"/><property kind="parameter" name="testRunner"/><property kind="parameter" name="testRunner"/></properties></element>

</group>
<group name="TestCase Objects">
<description>Each TestCase instance represents a single test, but each
concrete subclass may be used to define multiple tests --- the
concrete class represents a single test fixture. The fixture is
created and cleaned up for each test case.
TestCase instances provide three groups of methods: one group
used to run the test, another used by the test implementation to
check conditions and report failures, and some inquiry methods
allowing information about the test itself to be gathered.
Methods in the first group are:
</description>
<element kind="function" name="setUp">
<description>Method called to prepare the test fixture. This is called
immediately before calling the test method; any exception raised by
this method will be considered an error rather than a test failure.
The default implementation does nothing.</description>

</element>

<element kind="function" name="tearDown">
<description>Method called immediately after the test method has been called and
the result recorded. This is called even if the test method raised
an exception, so the implementation in subclasses may need to be
particularly careful about checking internal state. Any exception
raised by this method will be considered an error rather than a test
failure. This method will only be called if the setUp()
succeeds, regardless of the outcome of the test method.
The default implementation does nothing.</description>

</element>

<element kind="function" name="run">
<description>Run the test, collecting the result into the test result object
passed as result. If result is omitted or None,
a temporary result object is created and used, but is not made
available to the caller. This is equivalent to simply calling the
TestCase instance.</description>

<properties><property kind="parameter" name="result" required="1"/></properties></element>

<element kind="function" name="debug">
<description>Run the test without collecting the result. This allows exceptions
raised by the test to be propogated to the caller, and can be used
to support running tests under a debugger.</description>

</element>

<element kind="function" name="assert_">
<description>failUnless{expr, msg}
Signal a test failure if expr is false; the explanation for
the error will be msg if given, otherwise it will be
None.</description>

<properties><property kind="parameter" name="expr" required="1"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="assertEqual">
<description>failUnlessEqual{first, second, msg}
Test that first and second are equal. If the values do
not compare equal, the test will fail with the explanation given by
msg, or None. Note that using failUnlessEqual()
improves upon doing the comparison as the first parameter to
failUnless(): the default value for msg can be
computed to include representations of both first and
second.</description>

<properties><property kind="parameter" name="first" required="1"/><property kind="parameter" name="second" required="1"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="assertNotEqual">
<description>failIfEqual{first, second, msg}
Test that first and second are not equal. If the values
do compare equal, the test will fail with the explanation given by
msg, or None. Note that using failIfEqual()
improves upon doing the comparison as the first parameter to
failUnless() is that the default value for msg can be
computed to include representations of both first and
second.</description>

<properties><property kind="parameter" name="first" required="1"/><property kind="parameter" name="second" required="1"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="assertAlmostEqual">
<description>failUnlessAlmostEqual{first, second,
places, msg}
Test that first and second are approximately equal
by computing the difference, rounding to the given number of places,
and comparing to zero. Note that comparing a given number of decimal places
is not the same as comparing a given number of significant digits.
If the values do not compare equal, the test will fail with the explanation
given by msg, or None.</description>

<properties><property kind="parameter" name="first" required="1"/><property kind="parameter" name="second" required="1"/><property kind="parameter" name="places"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="assertNotAlmostEqual">
<description>failIfAlmostEqual{first, second,
places, msg}
Test that first and second are not approximately equal
by computing the difference, rounding to the given number of places,
and comparing to zero. Note that comparing a given number of decimal places
is not the same as comparing a given number of significant digits.
If the values do not compare equal, the test will fail with the explanation
given by msg, or None.</description>

<properties><property kind="parameter" name="first" required="1"/><property kind="parameter" name="second" required="1"/><property kind="parameter" name="places"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="assertRaises">
<description>failUnlessRaises{exception, callable, }
Test that an exception is raised when callable is called with
any positional or keyword arguments that are also passed to
assertRaises(). The test passes if exception is
raised, is an error if another exception is raised, or fails if no
exception is raised. To catch any of a group of exceptions, a tuple
containing the exception classes may be passed as exception.</description>

<properties><property kind="parameter" name="exception" required="1"/><property kind="parameter" name="callable" required="1"/><property kind="parameter" name="moreargsmoreargs" required="1"/></properties></element>

<element kind="function" name="failIf">
<description>The inverse of the failUnless() method is the
failIf() method. This signals a test failure if expr
is true, with msg or None for the error message.</description>

<properties><property kind="parameter" name="expr" required="1"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="fail">
<description>Signals a test failure unconditionally, with msg or
None for the error message.</description>

<properties><property kind="parameter" name="msg" required="1"/></properties></element>

<element kind="function" name="countTestCases">
<description>Return the number of tests represented by the this test object. For
TestCase instances, this will always be 1, but this
method is also implemented by the TestSuite class, which can
return larger values.</description>

</element>

<element kind="function" name="defaultTestResult">
<description>Return the default type of test result object to be used to run this
test.</description>

</element>

<element kind="function" name="id">
<description>Return a string identifying the specific test case. This is usually
the full name of the test method, including the module and class
names.</description>

</element>

<element kind="function" name="shortDescription">
<description>Returns a one-line description of the test, or None if no
description has been provided. The default implementation of this
method returns the first line of the test method's docstring, if
available, or None.</description>

</element>

</group>
<group name="TestSuite Objects">
<description>TestSuite objects behave much like TestCase objects,
except they do not actually implement a test. Instead, they are used
to aggregate tests into groups that should be run together. Some
additional methods are available to add tests to TestSuite
instances:
</description>
<element kind="function" name="addTest">
<description>Add a TestCase or TestSuite to the set of tests that
make up the suite.</description>

<properties><property kind="parameter" name="testtest" required="1"/></properties></element>

<element kind="function" name="addTests">
<description>Add all the tests from a sequence of TestCase and
TestSuite instances to this test suite.</description>

<properties><property kind="parameter" name="teststests" required="1"/></properties></element>

<element kind="function" name="run">
<description>Run the tests associated with this suite, collecting the result into
the test result object passed as result. Note that unlike
TestCase.run(), TestSuite.run() requires the
result object to be passed in.</description>

<properties><property kind="parameter" name="resultresult" required="1"/></properties></element>

</group>
<group name="TestResult Objects">
<description>A TestResult object stores the results of a set of tests. The
TestCase and TestSuite classes ensure that results are
properly stored; test authors do not need to worry about recording the
outcome of tests.
Testing frameworks built on top of unittest may want
access to the TestResult object generated by running a set of
tests for reporting purposes; a TestResult instance is
returned by the TestRunner.run() method for this purpose.
Each instance holds the total number of tests run, and collections of
failures and errors that occurred among those test runs. The
collections contain tuples of (testcase,
traceback), where traceback is a string containing a
formatted version of the traceback for the exception.
TestResult instances have the following attributes that will
be of interest when inspecting the results of running a set of tests:
[TestResult]{errors}
A list containing pairs of TestCase instances and the
formatted tracebacks for tests which raised an exception but did not
signal a test failure.
Changed in version 2.2: Contains formatted tracebacks instead of
sys.exc_info() results
[TestResult]{failures}
A list containing pairs of TestCase instances and the
formatted tracebacks for tests which signalled a failure in the code
under test.
Changed in version 2.2: Contains formatted tracebacks instead of
sys.exc_info() results
[TestResult]{testsRun}
The number of tests which have been started.
</description>
<element kind="function" name="wasSuccessful">
<description>Returns true if all tests run so far have passed, otherwise returns
false.</description>

</element>

<element kind="function" name="startTest">
<description>Called when the test case test is about to be run.</description>

<properties><property kind="parameter" name="testtest" required="1"/></properties></element>

<element kind="function" name="stopTest">
<description>Called when the test case test has been executed, regardless
of the outcome.</description>

<properties><property kind="parameter" name="testtest" required="1"/></properties></element>

<element kind="function" name="addError">
<description>Called when the test case test raises an exception without
signalling a test failure. err is a tuple of the form
returned by sys.exc_info(): (type,
value, traceback).</description>

<properties><property kind="parameter" name="test" required="1"/><property kind="parameter" name="err err" required="1"/></properties></element>

<element kind="function" name="addFailure">
<description>Called when the test case test signals a failure.
err is a tuple of the form returned by
sys.exc_info(): (type, value,
traceback).</description>

<properties><property kind="parameter" name="test" required="1"/><property kind="parameter" name="err err" required="1"/></properties></element>

<element kind="function" name="addSuccess">
<description>This method is called for a test that does not fail; test is
the test case object.</description>

<properties><property kind="parameter" name="testtest" required="1"/></properties></element>

<element kind="function" name="stop">
<description>This method can be called to signal that the set of tests being run
should be aborted. Once this has been called, the
TestRunner object return to its caller without running any
additional tests. This is used by the TextTestRunner class
to stop the test framework when the user signals an interrupt from
the keyboard. Interactive tools which provide runners can use this
in a similar manner.</description>

</element>

</group>
<group name="TestLoader Objects">
<description>The TestLoader class is used to create test suites from
classes and modules. Normally, there is no need to create an instance
of this class; the unittest module provides an instance
that can be shared as the defaultTestLoader module attribute.
Using a subclass or instance would allow customization of some
configurable properties.
TestLoader objects have the following methods:
</description>
<element kind="function" name="loadTestsFromTestCase">
<description>Return a suite of all tests cases contained in the
TestCase-derived class testCaseClass.</description>

<properties><property kind="parameter" name="testCaseClasstestCaseClass" required="1"/></properties></element>

<element kind="function" name="loadTestsFromModule">
<description>Return a suite of all tests cases contained in the given module.
This method searches module for classes derived from
TestCase and creates an instance of the class for each test
method defined for the class.
While using a hierarchy of
Testcase-derived classes can be convenient in sharing
fixtures and helper functions, defining test methods on base classes
that are not intended to be instantiated directly does not play well
with this method. Doing so, however, can be useful when the
fixtures are different and defined in subclasses.</description>

<properties><property kind="parameter" name="modulemodule" required="1"/></properties></element>

<element kind="function" name="loadTestsFromName">
<description>Return a suite of all tests cases given a string specifier.
The specifier name is a ``dotted name'' that may resolve
either to a module, a test case class, a test method within a test
case class, or a callable object which returns a TestCase or
TestSuite instance. For example, if you have a module
SampleTests containing a TestCase-derived class
SampleTestCase with three test methods (test_one(),
test_two(), and test_three()), the specifier
'SampleTests.SampleTestCase' would cause this method to
return a suite which will run all three test methods. Using the
specifier 'SampleTests.SampleTestCase.test_two' would cause
it to return a test suite which will run only the
test_two() test method. The specifier can refer to modules
and packages which have not been imported; they will be imported as
a side-effect.
The method optionally resolves name relative to a given module.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="module"/></properties></element>

<element kind="function" name="loadTestsFromNames">
<description>Similar to loadTestsFromName(), but takes a sequence of
names rather than a single name. The return value is a test suite
which supports all the tests defined for each name.</description>

<properties><property kind="parameter" name="names" required="1"/><property kind="parameter" name="module"/></properties></element>

<element kind="function" name="getTestCaseNames">
<description>Return a sorted sequence of method names found within
testCaseClass.</description>

<properties><property kind="parameter" name="testCaseClasstestCaseClass" required="1"/></properties></element>

</group>
</group>
<group name="test --- Regression tests package for Python">
<description>Regression tests package containing the testing suite
for Python.
The test package contains all regression tests for Python as
well as the modules test.test_support and
test.regrtest. test.test_support is used to enhance
your tests while test.regrtest drives the testing suite.
Each module in the test package whose name starts with
test_ is a testing suite for a specific module or feature.
All new tests should be written using the unittest module;
using unittest is not required but makes the tests more
flexible and maintenance of the tests easier. Some older tests are
written to use doctest and a ``traditional'' testing
style; these styles of tests will not be covered.
unittest{Writing PyUnit regression tests.}
doctest{Tests embedded in documentation strings.}
</description>
<group name="Writing Unit Tests for the test package%">
<description>It is preferred that tests for the test package use the
unittest module and follow a few guidelines.
One is to have the name of all the test methods start with test_ as
well as the module's name.
This is needed so that the methods are recognized by the test driver as
test methods.
Also, no documentation string for the method should be included.
A comment (such as
function returns only True or False) should be used to provide
documentation for test methods.
This is done because documentation strings get printed out if they exist and
thus what test is being run is not stated.
A basic boilerplate is often used:
import unittest
from test import test_support
class MyTestCase1(unittest.TestCase):
# Only use setUp() and tearDown() if necessary
def setUp(self):
... code to execute in preparation for tests ...
def tearDown(self):
... code to execute to clean up after tests ...
def test_feature_one(self):
# Test feature one.
... testing code ...
def test_feature_two(self):
# Test feature two.
... testing code ...
... more test methods ...
class MyTestCase2(unittest.TestCase):
... same structure as MyTestCase1 ...
... more test classes ...
def test_main():
test_support.run_unittest(MyTestCase1,
MyTestCase2,
... list other tests ...
)
if __name__ == '__main__':
test_main()
This boilerplate code allows the testing suite to be run by
test.regrtest as well as on its own as a script.
The goal for regression testing is to try to break code.
This leads to a few guidelines to be followed:
The testing suite should exercise all classes, functions, and
constants.
This includes not just the external API that is to be presented to the
outside world but also &quot;private&quot; code.
Whitebox testing (examining the code being tested when the tests are
being written) is preferred.
Blackbox testing (testing only the published user interface) is not
complete enough to make sure all boundary and edge cases are tested.
Make sure all possible values are tested including invalid ones.
This makes sure that not only all valid values are acceptable but also
that improper values are handled correctly.
Exhaust as many code paths as possible.
Test where branching occurs and thus tailor input to make sure as many
different paths through the code are taken.
Add an explicit test for any bugs discovered for the tested code.
This will make sure that the error does not crop up again if the code is
changed in the future.
Make sure to clean up after your tests (such as close and remove all
temporary files).
Import as few modules as possible and do it as soon as possible.
This minimizes external dependencies of tests and also minimizes possible
anomalous behavior from side-effects of importing a module.
Try to maximize code reuse.
On occasion, tests will vary by something as small as what type
of input is used.
Minimize code duplication by subclassing a basic test class with a class
that specifies the input:
class TestFuncAcceptsSequences(unittest.TestCase):
func = mySuperWhammyFunction
def test_func(self):
self.func(self.arg)
class AcceptLists(TestFuncAcceptsSequences):
arg = [1,2,3]
class AcceptStrings(TestFuncAcceptsSequences):
arg = 'abc'
class AcceptTuples(TestFuncAcceptsSequences):
arg = (1,2,3)
See also Test Driven Development - {A book by Kent Beck on writing tests before code.}
\end{seealso}
</description>
</group>
<group name="Running tests Using test.regrtest">
<description>test.regrtest can be used as a script to drive Python's
regression test suite.
Running the script by itself automatically starts running all
regression tests in the test package.
It does this by finding all modules in the package whose name starts with
test_, importing them, and executing the function
test_main() if present.
The names of tests to execute may also be passed to the script.
Specifying a single regression test (python regrtest.py
test_spam.py) will minimize output and only print whether
the test passed or failed and thus minimize output.
Running test.regrtest directly allows what resources are
available for tests to use to be set.
You do this by using the -u command-line option.
Run python regrtest.py -uall to turn on all
resources; specifying all as an option for
-u enables all possible resources.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
all.
The command python regrtest.py
-uall,-audio,-largefile will run test.regrtest
with all resources except the audio and
largefile resources.
For a list of all resources and more command-line options, run
python regrtest.py -h.
Some other ways to execute the regression tests depend on what platform the
tests are being executed on.
On , you can run make test at the
top-level directory where Python was built.
On Windows, executing rt.bat from your PCBuild
directory will run all regression tests.
test.test_support ---
Utility functions for tests
Support for Python regression tests.
The test.test_support module provides support for Python's
regression tests.
This module defines the following exceptions:
{TestFailed}
Exception to be raised when a test fails.
{TestSkipped}
Subclass of TestFailed.
Raised when a test is skipped.
This occurs when a needed resource (such as a network connection) is not
available at the time of testing.
{ResourceDenied}
Subclass of TestSkipped.
Raised when a resource (such as a network connection) is not available.
Raised by the requires() function.
The test.test_support module defines the following constants:
{verbose}
True when verbose output is enabled.
Should be checked when more detailed information is desired about a running
test.
verbose is set by test.regrtest.
{have_unicode}
True when Unicode support is available.
{is_jython}
True if the running interpreter is Jython.
{TESTFN}
Set to the path that a temporary file may be created at.
Any temporary that is created should be closed and unlinked (removed).
The test.test_support module defines the following functions:
</description>
<element kind="function" name="forget">
<description>Removes the module named module_name from sys.modules and deletes
any byte-compiled files of the module.</description>

<properties><property kind="parameter" name="module_namemodule_name" required="1"/></properties></element>

<element kind="function" name="is_resource_enabled">
<description>Returns True if resource is enabled and available.
The list of available resources is only set when test.regrtest
is executing the tests.</description>

<properties><property kind="parameter" name="resourceresource" required="1"/></properties></element>

<element kind="function" name="requires">
<description>Raises ResourceDenied if resource is not available.
msg is the argument to ResourceDenied if it is raised.
Always returns true if called by a function whose __name__ is
'__main__'.
Used when tests are executed by test.regrtest.</description>

<properties><property kind="parameter" name="resource" required="1"/><property kind="parameter" name="msg"/></properties></element>

<element kind="function" name="findfile">
<description>Return the path to the file named filename.
If no match is found filename is returned.
This does not equal a failure since it could be the path to the file.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="run_unittest">
<description>Execute unittest.TestCase subclasses passed to the function.
The function scans the classes for methods starting with the prefix
test_ and executes the tests individually.
This is the preferred way to execute tests.</description>

<properties><property kind="parameter" name="*classes*classes" required="1"/></properties></element>

<element kind="function" name="run_suite">
<description>Execute the unittest.TestSuite instance suite.
The optional argument testclass accepts one of the test classes in the
suite so as to print out more detailed information on where the testing suite
originated from.</description>

<properties><property kind="parameter" name="suite" required="1"/><property kind="parameter" name="testclass"/></properties></element>

</group>
</group>
<group name="math --- Mathematical functions">
<description>Mathematical functions (sin() etc.).
This module is always available. It provides access to the
mathematical functions defined by the C standard.
These functions cannot be used with complex numbers; use the functions
of the same name from the cmath module if you require
support for complex numbers. The distinction between functions which
support complex numbers and those which don't is made since most users
do not want to learn quite as much mathematics as required to
understand complex numbers. Receiving an exception instead of a
complex result allows earlier detection of the unexpected complex
number used as a parameter, so that the programmer can determine how
and why it was generated in the first place.
The following functions are provided by this module. Except
when explicitly noted otherwise, all return values are floats:
</description>
<element kind="function" name="acos">
<description>Return the arc cosine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="asin">
<description>Return the arc sine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="atan">
<description>Return the arc tangent of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="atan2">
<description>Return atan(y / x).</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x x" required="1"/></properties></element>

<element kind="function" name="ceil">
<description>Return the ceiling of x as a float.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="cos">
<description>Return the cosine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="cosh">
<description>Return the hyperbolic cosine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="degrees">
<description>Converts angle x from radians to degrees.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="exp">
<description>Return e**x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="fabs">
<description>Return the absolute value of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="floor">
<description>Return the floor of x as a float.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="fmod">
<description>Return fmod(x, y), as defined by the platform C library.
Note that the Python expression x % y may not return
the same result.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y y" required="1"/></properties></element>

<element kind="function" name="frexp">
<description>% Blessed by Tim.
Return the mantissa and exponent of x as the pair
(m, e). m is a float and e is an
integer such that x == m * 2**e.
If x is zero, returns (0.0, 0), otherwise
0.5 &lt;= abs(m) &lt; 1.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="hypot">
<description>Return the Euclidean distance, sqrt(x*x + y*y).</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y y" required="1"/></properties></element>

<element kind="function" name="ldexp">
<description>Return x * (2**i).</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="i i" required="1"/></properties></element>

<element kind="function" name="log">
<description>Returns the logarithm of x to the given base.
If the base is not specified, returns the natural logarithm of x.
Changed in version 2.3: base argument added</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="base"/></properties></element>

<element kind="function" name="log10">
<description>Return the base-10 logarithm of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="modf">
<description>Return the fractional and integer parts of x. Both results
carry the sign of x. The integer part is returned as a float.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="pow">
<description>Return x**y.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y y" required="1"/></properties></element>

<element kind="function" name="radians">
<description>Converts angle x from degrees to radians.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="sin">
<description>Return the sine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="sinh">
<description>Return the hyperbolic sine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="sqrt">
<description>Return the square root of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="tan">
<description>Return the tangent of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="tanh">
<description>Return the hyperbolic tangent of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

</group>
<group name="cmath --- Mathematical functions for complex numbers">
<description>Mathematical functions for complex numbers.
This module is always available. It provides access to mathematical
functions for complex numbers. The functions are:
</description>
<element kind="function" name="acos">
<description>Return the arc cosine of x.
There are two branch cuts:
One extends right from 1 along the real axis to , continuous
from below.
The other extends left from -1 along the real axis to -,
continuous from above.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="acosh">
<description>Return the hyperbolic arc cosine of x.
There is one branch cut, extending left from 1 along the real axis
to -, continuous from above.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="asin">
<description>Return the arc sine of x.
This has the same branch cuts as acos().</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="asinh">
<description>Return the hyperbolic arc sine of x.
There are two branch cuts, extending left from 1j to
-j, both continuous from above.
These branch cuts should be considered a bug to be corrected in a
future release.
The correct branch cuts should extend along the imaginary axis,
one from 1j up to j and continuous from the
right, and one from -1j down to -j and
continuous from the left.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="atan">
<description>Return the arc tangent of x.
There are two branch cuts:
One extends from 1j along the imaginary axis to
j, continuous from the left.
The other extends from -1j along the imaginary axis to
-j, continuous from the left.
(This should probably be changed so the upper cut becomes continuous
from the other side.)</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="atanh">
<description>Return the hyperbolic arc tangent of x.
There are two branch cuts:
One extends from 1 along the real axis to , continuous
from above.
The other extends from -1 along the real axis to -,
continuous from above.
(This should probably be changed so the right cut becomes continuous from
the other side.)</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="cos">
<description>Return the cosine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="cosh">
<description>Return the hyperbolic cosine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="exp">
<description>Return the exponential value e**x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="log">
<description>Return the natural logarithm of x.
There is one branch cut, from 0 along the negative real axis to
-, continuous from above.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="log10">
<description>Return the base-10 logarithm of x.
This has the same branch cut as log().</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="sin">
<description>Return the sine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="sinh">
<description>Return the hyperbolic sine of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="sqrt">
<description>Return the square root of x.
This has the same branch cut as log().</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="tan">
<description>Return the tangent of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="tanh">
<description>Return the hyperbolic tangent of x.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

</group>
<group name="random --- Generate pseudo-random numbers">
<description>Generate pseudo-random numbers with various common
distributions.
This module implements pseudo-random number generators for various
distributions.
For integers, uniform selection from a range.
For sequences, uniform selection of a random element, a function to
generate a random permutation of a list in-place, and a function for
random sampling without replacement.
On the real line, there are functions to compute uniform, normal (Gaussian),
lognormal, negative exponential, gamma, and beta distributions.
For generating distributions of angles, the von Mises distribution
is available.
Almost all module functions depend on the basic function
random(), which generates a random float uniformly in
the semi-open range [0.0, 1.0). Python uses the Mersenne Twister as
the core generator. It produces 53-bit precision floats and has a
period of 2**19937-1. The underlying implementation in C is both fast and threadsafe. The Mersenne Twister is one of the most
extensively tested random number generators in existence. However, being
completely deterministic, it is not suitable for all purposes, and is
completely unsuitable for cryptographic purposes.
The functions supplied by this module are actually bound methods of a
hidden instance of the random.Random class. You can
instantiate your own instances of Random to get generators
that don't share state. This is especially useful for multi-threaded
programs, creating a different instance of Random for each
thread, and using the jumpahead() method to ensure that the
generated sequences seen by each thread don't overlap.
Class Random can also be subclassed if you want to use a
different basic generator of your own devising: in that case, override
the random(), seed(), getstate(),
setstate() and jumpahead() methods.
Optionally, a new generator can supply a getrandombits()
method --- this allows randrange() to produce selections
over an arbitrarily large range.
New in version 2.4
As an example of subclassing, the random module provides
the WichmannHill class which implements an alternative generator
in pure Python. The class provides a backward compatible way to
reproduce results from earlier versions of Python which used the
Wichmann-Hill algorithm as the core generator.
Changed in version 2.3: Substituted MersenneTwister for Wichmann-Hill
Bookkeeping functions:
</description>
<element kind="function" name="seed">
<description>Initialize the basic random number generator.
Optional argument x can be any hashable object.
If x is omitted or None, current system time is used;
current system time is also used to initialize the generator when the
module is first imported.
If x is not None or an int or long,
hash(x) is used instead.
If x is an int or long, x is used directly.</description>

<properties><property kind="parameter" name="x" required="1"/></properties></element>

<element kind="function" name="getstate">
<description>Return an object capturing the current internal state of the
generator. This object can be passed to setstate() to
restore the state.
New in version 2.1</description>

</element>

<element kind="function" name="setstate">
<description>state should have been obtained from a previous call to
getstate(), and setstate() restores the
internal state of the generator to what it was at the time
setstate() was called.
New in version 2.1</description>

<properties><property kind="parameter" name="statestate" required="1"/></properties></element>

<element kind="function" name="jumpahead">
<description>Change the internal state to one different from and likely far away from
the current state. n is a non-negative integer which is used to
scramble the current state vector. This is most useful in multi-threaded
programs, in conjuction with multiple instances of the Random
class: setstate() or seed() can be used to force all
instances into the same internal state, and then jumpahead()
can be used to force the instances' states far apart.
New in version 2.1
Changed in version 2.3: Instead of jumping to a specific state, n steps
ahead, jumpahead(n) jumps to another state likely to be
separated by many steps.</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="getrandbits">
<description>Returns a python long int with k random bits.
This method is supplied with the MersenneTwister generator and some
other generators may also provide it as an optional part of the API.
When available, getrandbits() enables randrange()
to handle arbitrarily large ranges.
New in version 2.4</description>

<properties><property kind="parameter" name="kk" required="1"/></properties></element>

<element kind="function" name="randrange">
<description>Return a randomly selected element from range(start,
stop, step). This is equivalent to
choice(range(start, stop, step)),
but doesn't actually build a range object.
New in version 1.5.2</description>

<properties><property kind="parameter" name="start" required="1"/><property kind="parameter" name="stop"/><property kind="parameter" name="step"/></properties></element>

<element kind="function" name="randint">
<description>Return a random integer N such that
a &lt;= N &lt;= b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="choice">
<description>Return a random element from the non-empty sequence seq.</description>

<properties><property kind="parameter" name="seqseq" required="1"/></properties></element>

<element kind="function" name="shuffle">
<description>Shuffle the sequence x in place.
The optional argument random is a 0-argument function
returning a random float in [0.0, 1.0); by default, this is the
function random().
Note that for even rather small len(x), the total
number of permutations of x is larger than the period of most
random number generators; this implies that most permutations of a
long sequence can never be generated.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="random"/></properties></element>

<element kind="function" name="sample">
<description>Return a k length list of unique elements chosen from the
population sequence. Used for random sampling without replacement.
New in version 2.3
Returns a new list containing elements from the population while
leaving the original population unchanged. The resulting list is
in selection order so that all sub-slices will also be valid random
samples. This allows raffle winners (the sample) to be partitioned
into grand prize and second place winners (the subslices).
Members of the population need not be hashable or unique. If the
population contains repeats, then each occurrence is a possible
selection in the sample.
To choose a sample from a range of integers, use xrange
as an argument. This is especially fast and space efficient for
sampling from a large population: sample(xrange(10000000), 60).</description>

<properties><property kind="parameter" name="population" required="1"/><property kind="parameter" name="k k" required="1"/></properties></element>

<element kind="function" name="random">
<description>Return the next random floating point number in the range [0.0, 1.0).</description>

</element>

<element kind="function" name="uniform">
<description>Return a random real number N such that
a &lt;= N &lt; b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="betavariate">
<description>Beta distribution. Conditions on the parameters are
alpha &gt; -1 and beta &gt; -1.
Returned values range between 0 and 1.</description>

<properties><property kind="parameter" name="alpha" required="1"/><property kind="parameter" name="beta beta" required="1"/></properties></element>

<element kind="function" name="expovariate">
<description>Exponential distribution. lambd is 1.0 divided by the desired
mean. (The parameter would be called ``lambda'', but that is a
reserved word in Python.) Returned values range from 0 to
positive infinity.</description>

<properties><property kind="parameter" name="lambdlambd" required="1"/></properties></element>

<element kind="function" name="gammavariate">
<description>Gamma distribution. (Not the gamma function!) Conditions on
the parameters are alpha &gt; 0 and beta &gt; 0.</description>

<properties><property kind="parameter" name="alpha" required="1"/><property kind="parameter" name="beta beta" required="1"/></properties></element>

<element kind="function" name="gauss">
<description>Gaussian distribution. mu is the mean, and sigma is the
standard deviation. This is slightly faster than the
normalvariate() function defined below.</description>

<properties><property kind="parameter" name="mu" required="1"/><property kind="parameter" name="sigma sigma" required="1"/></properties></element>

<element kind="function" name="lognormvariate">
<description>Log normal distribution. If you take the natural logarithm of this
distribution, you'll get a normal distribution with mean mu
and standard deviation sigma. mu can have any value,
and sigma must be greater than zero.</description>

<properties><property kind="parameter" name="mu" required="1"/><property kind="parameter" name="sigma sigma" required="1"/></properties></element>

<element kind="function" name="normalvariate">
<description>Normal distribution. mu is the mean, and sigma is the
standard deviation.</description>

<properties><property kind="parameter" name="mu" required="1"/><property kind="parameter" name="sigma sigma" required="1"/></properties></element>

<element kind="function" name="vonmisesvariate">
<description>mu is the mean angle, expressed in radians between 0 and
2*pi, and kappa is the concentration parameter, which
must be greater than or equal to zero. If kappa is equal to
zero, this distribution reduces to a uniform random angle over the
range 0 to 2*pi.</description>

<properties><property kind="parameter" name="mu" required="1"/><property kind="parameter" name="kappa kappa" required="1"/></properties></element>

<element kind="function" name="paretovariate">
<description>Pareto distribution. alpha is the shape parameter.</description>

<properties><property kind="parameter" name="alphaalpha" required="1"/></properties></element>

<element kind="function" name="weibullvariate">
<description>Weibull distribution. alpha is the scale parameter and
beta is the shape parameter.</description>

<properties><property kind="parameter" name="alpha" required="1"/><property kind="parameter" name="beta beta" required="1"/></properties></element>

<element kind="function" name="WichmannHill">
<description>Class that implements the Wichmann-Hill algorithm as the core generator.
Has all of the same methods as Random plus the whseed
method described below. Because this class is implemented in pure
Python, it is not threadsafe and may require locks between calls. The
period of the generator is 6,953,607,871,644 which is small enough to
require care that two independent random sequences do not overlap.</description>

<properties><property kind="parameter" name="seed" required="1"/></properties></element>

<element kind="function" name="whseed">
<description>This is obsolete, supplied for bit-level compatibility with versions
of Python prior to 2.1.
See seed for details. whseed does not guarantee
that distinct integer arguments yield distinct internal states, and can
yield no more than about 2**24 distinct internal states in all.</description>

<properties><property kind="parameter" name="x" required="1"/></properties></element>

</group>
<group name="whrandom --- Pseudo-random number generator">
<description>Floating point pseudo-random number generator.
2.1{Use random instead.}
This module was an implementation detail of the
random module in releases of Python prior to 2.1. It is
no longer used. Please do not use this module directly; use
random instead.
This module implements a Wichmann-Hill pseudo-random number generator
class that is also named whrandom. Instances of the
whrandom class conform to the Random Number Generator
interface described in section rng-objects. They also offer the following method, specific to the Wichmann-Hill algorithm:
</description>
<element kind="function" name="seed">
<description>Initializes the random number generator from the integers x,
y and z. When the module is first imported, the random
number is initialized using values derived from the current time.
If x, y, and z are either omitted or 0, the seed will be computed from the current system time. If one or two
of the parameters are 0, but not all three, the zero values
are replaced by ones. This causes some apparently different seeds
to be equal, with the corresponding result on the pseudo-random
series produced by the generator.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y"/><property kind="parameter" name="z"/></properties></element>

<element kind="function" name="choice">
<description>Chooses a random element from the non-empty sequence seq and returns it.</description>

<properties><property kind="parameter" name="seqseq" required="1"/></properties></element>

<element kind="function" name="randint">
<description>Returns a random integer N such that a&lt;=N&lt;=b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="random">
<description>Returns the next random floating point number in the range [0.0 ... 1.0).</description>

</element>

<element kind="function" name="seed">
<description>Initializes the random number generator from the integers x,
y and z. When the module is first imported, the random
number is initialized using values derived from the current time.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="z z" required="1"/></properties></element>

<element kind="function" name="uniform">
<description>Returns a random real number N such that a&lt;=N&lt;b.</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

</group>
<group name="bisect --- Array bisection algorithm">
<description>Array bisection algorithms for binary searching.
% LaTeX produced by Fred L. Drake, Jr. &lt;fdrake@acm.org&gt;, with an
% example based on the PyModules FAQ entry by Aaron Watters
% &lt;arw@pythonpros.com&gt;.
This module provides support for maintaining a list in sorted order
without having to sort the list after each insertion. For long lists
of items with expensive comparison operations, this can be an
improvement over the more common approach. The module is called
bisect because it uses a basic bisection algorithm to do its
work. The source code may be most useful as a working example of the
algorithm (the boundary conditions are already right!).
The following functions are provided:
</description>
<element kind="function" name="bisect_left">
<description>Locate the proper insertion point for item in list to
maintain sorted order. The parameters lo and hi may be
used to specify a subset of the list which should be considered; by
default the entire list is used. If item is already present
in list, the insertion point will be before (to the left of)
any existing entries. The return value is suitable for use as the
first parameter to list.insert(). This assumes that
list is already sorted.
New in version 2.1</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="item" required="1"/><property kind="parameter" name="lo"/><property kind="parameter" name="hi"/></properties></element>

<element kind="function" name="bisect_right">
<description>Similar to bisect_left(), but returns an insertion point
which comes after (to the right of) any existing entries of
item in list.
New in version 2.1</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="item" required="1"/><property kind="parameter" name="lo"/><property kind="parameter" name="hi"/></properties></element>

<element kind="function" name="bisect">
<description>Alias for bisect_right().</description>

<properties><property kind="parameter" name="unspecifiedunspecified" required="1"/></properties></element>

<element kind="function" name="insort_left">
<description>Insert item in list in sorted order. This is equivalent
to list.insert(bisect.bisect_left(list, item,
lo, hi), item). This assumes that list is
already sorted.
New in version 2.1</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="item" required="1"/><property kind="parameter" name="lo"/><property kind="parameter" name="hi"/></properties></element>

<element kind="function" name="insort_right">
<description>Similar to insort_left(), but inserting item in
list after any existing entries of item.
New in version 2.1</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="item" required="1"/><property kind="parameter" name="lo"/><property kind="parameter" name="hi"/></properties></element>

<element kind="function" name="insort">
<description>Alias for insort_right().</description>

<properties><property kind="parameter" name="unspecifiedunspecified" required="1"/></properties></element>

<group name="Examples">
</group>
</group>
<group name="heapq --- Heap queue algorithm">
<description>Heap queue algorithm (a.k.a. priority queue).
% Theoretical explanation:
New in version 2.3
This module provides an implementation of the heap queue algorithm,
also known as the priority queue algorithm.
Heaps are arrays for which
heap[k] &lt;= heap[2*k+1] and
heap[k] &lt;= heap[2*k+2]
for all k, counting elements from zero. For the sake of
comparison, non-existing elements are considered to be infinite. The
interesting property of a heap is that heap[0] is always
its smallest element.
The API below differs from textbook heap algorithms in two aspects:
(a) We use zero-based indexing. This makes the relationship between the
index for a node and the indexes for its children slightly less
obvious, but is more suitable since Python uses zero-based indexing.
(b) Our pop method returns the smallest item, not the largest (called a
&quot;min heap&quot; in textbooks; a &quot;max heap&quot; is more common in texts because
of its suitability for in-place sorting).
These two make it possible to view the heap as a regular Python list
without surprises: heap[0] is the smallest item, and
heap.sort() maintains the heap invariant!
To create a heap, use a list initialized to [], or you can
transform a populated list into a heap via function heapify().
The following functions are provided:
</description>
<element kind="function" name="heappush">
<description>Push the value item onto the heap, maintaining the
heap invariant.</description>

<properties><property kind="parameter" name="heap" required="1"/><property kind="parameter" name="item item" required="1"/></properties></element>

<element kind="function" name="heappop">
<description>Pop and return the smallest item from the heap, maintaining the
heap invariant. If the heap is empty, IndexError is raised.</description>

<properties><property kind="parameter" name="heapheap" required="1"/></properties></element>

<element kind="function" name="heapify">
<description>Transform list x into a heap, in-place, in linear time.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="heapreplace">
<description>Pop and return the smallest item from the heap, and also push
the new item. The heap size doesn't change.
If the heap is empty, IndexError is raised.
This is more efficient than heappop() followed
by heappush(), and can be more appropriate when using
a fixed-size heap. Note that the value returned may be larger
than item! That constrains reasonable uses of this routine.</description>

<properties><property kind="parameter" name="heap" required="1"/><property kind="parameter" name="item item" required="1"/></properties></element>

<group name="Theory">
</group>
</group>
<group name="array --- Efficient arrays of numeric values">
<description>Efficient arrays of uniformly typed numeric values.
This module defines an object type which can efficiently represent
an array of basic values: characters, integers, floating point
numbers. Arrays</description>
<element kind="function" name="array">
<description>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(), fromstring(), or
fromunicode() method (see below) to add initial items to
the array.</description>

<properties><property kind="parameter" name="typecode" required="1"/><property kind="parameter" name="initializer"/></properties></element>

<element kind="function" name="append">
<description>Append a new item with value x to the end of the array.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="buffer_info">
<description>Return a tuple (address, length) giving the current
memory address and the length in elements of the buffer used to hold
array's contents. The size of the memory buffer in bytes can be
computed as array.buffer_info()[1] *
array.itemsize. 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.
When using array objects from code written in C or
(the only way to effectively make use of this information), it
makes more sense to use the buffer interface supported by array
objects. This method is maintained for backward compatibility and
should be avoided in new code. The buffer interface is documented in
the Python/C API Reference Manual.</description>

</element>

<element kind="function" name="byteswap">
<description>``Byteswap'' all items of the array. This is only supported for
values which are 1, 2, 4, or 8 bytes in size; for other types of
values, RuntimeError is raised. It is useful when reading
data from a file written on a machine with a different byte order.</description>

</element>

<element kind="function" name="count">
<description>Return the number of occurences of x in the array.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="extend">
<description>Append array items from a to the end of the array. The two
arrays must have exactly the same type code; if not,
TypeError will be raised.</description>

<properties><property kind="parameter" name="aa" required="1"/></properties></element>

<element kind="function" name="fromfile">
<description>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.</description>

<properties><property kind="parameter" name="f" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="fromlist">
<description>Append items from the list. This is equivalent to
for x in list:.append(x)
except that if there is a type error, the array is unchanged.</description>

<properties><property kind="parameter" name="listlist" required="1"/></properties></element>

<element kind="function" name="fromstring">
<description>Appends items from the string, interpreting the string as an
array of machine values (as if it had been read from a
file using the fromfile() method).</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="fromunicode">
<description>Extends this array with data from the given unicode string.
The array must be a type 'u' array; otherwise a ValueError
is raised. Use array.fromstring(ustr.decode(enc)) to
append Unicode data to an array of some other type.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="index">
<description>Return the smallest i such that i is the index of
the first occurence of x in the array.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="insert">
<description>Insert a new item with value x in the array before position
i. Negative values are treated as being relative to the end
of the array.</description>

<properties><property kind="parameter" name="i" required="1"/><property kind="parameter" name="x x" required="1"/></properties></element>

<element kind="function" name="pop">
<description>Removes the item with the index i from the array and returns
it. The optional argument defaults to -1, so that by default
the last item is removed and returned.</description>

<properties><property kind="parameter" name="i" required="1"/></properties></element>

<element kind="function" name="read">
<description>{1.5.1}
{Use the fromfile() method.}
Read n items (as machine values) from the file object f
and append them to the end of the array. If less than n items
are available, EOFError is raised, but the items that were
available are still inserted into the array. f must be a real
built-in file object; something else with a read() method won't
do.</description>

<properties><property kind="parameter" name="f" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="remove">
<description>Remove the first occurence of x from the array.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="reverse">
<description>Reverse the order of the items in the array.</description>

</element>

<element kind="function" name="tofile">
<description>Write all items (as machine values) to the file object f.</description>

<properties><property kind="parameter" name="ff" required="1"/></properties></element>

<element kind="function" name="tolist">
<description>Convert the array to an ordinary list with the same items.</description>

</element>

<element kind="function" name="tostring">
<description>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.)</description>

</element>

<element kind="function" name="tounicode">
<description>Convert the array to a unicode string. The array must be
a type 'u' array; otherwise a ValueError is raised. Use
array.tostring().decode(enc) to obtain a unicode string
from an array of some other type.</description>

</element>

<element kind="function" name="write">
<description>{1.5.1}
{Use the tofile() method.}
Write all items (as machine values) to the file object f.</description>

<properties><property kind="parameter" name="ff" required="1"/></properties></element>

</group>
<group name="sets --- Unordered collections of unique elements">
<description>Implementation of sets of unique elements.
New in version 2.3
The sets module provides classes for constructing and manipulating
unordered collections of unique elements. Common uses include membership
testing, removing duplicates from a sequence, and computing standard math
operations on sets such as intersection, union, difference, and symmetric
difference.
Like other collections, sets support x in set,
len(set), and for x in set. Being an
unordered collection, sets do not record element position or order of
insertion. Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior.
Most set applications use the Set class which provides every set
method except for __hash__(). For advanced applications requiring
a hash method, the ImmutableSet class adds a __hash__()
method but omits methods which alter the contents of the set. Both
Set and ImmutableSet derive from BaseSet, an
abstract class useful for determining whether something is a set:
isinstance(obj, BaseSet).
The set classes are implemented using dictionaries. As a result, sets
cannot contain mutable elements such as lists or dictionaries.
However, they can contain immutable collections such as tuples or
instances of ImmutableSet. For convenience in implementing
sets of sets, inner sets are automatically converted to immutable
form, for example, Set([Set(['dog'])]) is transformed to
Set([ImmutableSet(['dog'])]).
</description>
<element kind="function" name="Set">
<description>Constructs a new empty Set object. If the optional iterable
parameter is supplied, updates the set with elements obtained from iteration.
All of the elements in iterable should be immutable or be transformable
to an immutable using the protocol described in
section~immutable-transforms.</description>

<properties><property kind="parameter" name="iterable" required="1"/></properties></element>

<element kind="function" name="ImmutableSet">
<description>Constructs a new empty ImmutableSet object. If the optional
iterable parameter is supplied, updates the set with elements obtained
from iteration. All of the elements in iterable should be immutable or
be transformable to an immutable using the protocol described in
section~immutable-transforms.
Because ImmutableSet objects provide a __hash__() method,
they can be used as set elements or as dictionary keys. ImmutableSet
objects do not have methods for adding or removing elements, so all of the
elements must be known when the constructor is called.</description>

<properties><property kind="parameter" name="iterable" required="1"/></properties></element>

<group name="Set Objects">
<description>Instances of Set and ImmutableSet both provide
the following operations:
{c|c|l}{code}{Operation}{Equivalent}{Result}
len(s){}{cardinality of set s}
x in s{}
{test x for membership in s}
x not in s{}
{test x for non-membership in s}
s.issubset(t){s &lt;= t}
{test whether every element in s is in t}
s.issuperset(t){s &gt;= t}
{test whether every element in t is in s}
s.union(t){s | t}
{new set with elements from both s and t}
s.intersection(t){s t}
{new set with elements common to s and t}
s.difference(t){s - t}
{new set with elements in s but not in t}
s.symmetric_difference(t){s t}
{new set with elements in either s or t but not both}
s.copy(){}
{new set with a shallow copy of s}
Note, the non-operator versions of union(),
intersection(), difference(), and
symmetric_difference() will accept any iterable as an argument.
In contrast, their operator based counterparts require their arguments to
be sets. This precludes error-prone constructions like
Set('abc') ' in favor of the more readable
Set('abc').intersection('cbs').
Changed in version 2.3.1: Formerly all arguments were required to be sets
In addition, both Set and ImmutableSet
support set to set comparisons. Two sets are equal if and only if
every element of each set is contained in the other (each is a subset
of the other).
A set is less than another set if and only if the first set is a proper
subset of the second set (is a subset, but is not equal).
A set is greater than another set if and only if the first set is a proper
superset of the second set (is a superset, but is not equal).
The subset and equality comparisons do not generalize to a complete
ordering function. For example, any two disjoint sets are not equal and
are not subsets of each other, so all of the following return
False: a&lt;b, a==b, or
a&gt;b.
Accordingly, sets do not implement the __cmp__ method.
Since sets only define partial ordering (subset relationships), the output
of the list.sort() method is undefined for lists of sets.
The following table lists operations available in ImmutableSet
but not found in Set:
{c|l}{code}{Operation}{Result}
hash(s){returns a hash value for s}
The following table lists operations available in Set
but not found in ImmutableSet:
{c|c|l}{code}{Operation}{Equivalent}{Result}
s.union_update(t)
{s |= t}
{return set s with elements added from t}
s.intersection_update(t)
{s t}
{return set s keeping only elements also found in t}
s.difference_update(t)
{s -= t}
{return set s after removing elements found in t}
s.symmetric_difference_update(t)
{s = t}
{return set s with elements from s or t
but not both}
s.add(x){}
{add element x to set s}
s.remove(x){}
{remove x from set s; raises KeyError if not present}
s.discard(x){}
{removes x from set s if present}
s.pop(){}
{remove and return an arbitrary element from s; raises
KeyError if empty}
s.clear(){}
{remove all elements from set s}
Note, the non-operator versions of union_update(),
intersection_update(), difference_update(), and
symmetric_difference_update() will accept any iterable as
an argument.
Changed in version 2.3.1: Formerly all arguments were required to be sets
</description>
</group>
<group name="Example">
<description>&gt;&gt;&gt; from sets import Set
&gt;&gt;&gt; engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
&gt;&gt;&gt; programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
&gt;&gt;&gt; managers = Set(['Jane', 'Jack', 'Susan', 'Zack'])
&gt;&gt;&gt; employees = engineers | programmers | managers # union
&gt;&gt;&gt; engineering_management = engineers &amp; managers # intersection
&gt;&gt;&gt; fulltime_management = managers - engineers - programmers # difference
&gt;&gt;&gt; engineers.add('Marvin') # add element
&gt;&gt;&gt; print engineers
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
&gt;&gt;&gt; employees.issuperset(engineers) # superset test
False
&gt;&gt;&gt; employees.union_update(engineers) # update from another set
&gt;&gt;&gt; employees.issuperset(engineers)
True
&gt;&gt;&gt; for group in [engineers, programmers, managers, employees]:
... group.discard('Susan') # unconditionally remove element
... print group
...
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
Set(['Janice', 'Jack', 'Sam'])
Set(['Jane', 'Zack', 'Jack'])
Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack'])
</description>
</group>
<group name="Protocol for automatic conversion to immutable">
</group>
</group>
<group name="itertools --- Functions creating iterators for efficient looping">
<description>Functions creating iterators for efficient looping.
New in version 2.3
This module implements a number of iterator building blocks inspired
by constructs from the Haskell and SML programming languages. Each
has been recast in a form suitable for Python.
The module standardizes a core set of fast, memory efficient tools
that are useful by themselves or in combination. Standardization helps
avoid the readability and reliability problems which arise when many
different individuals create their own slightly varying implementations,
each with their own quirks and naming conventions.
The tools are designed to combine readily with one another. This makes
it easy to construct more specialized tools succinctly and efficiently
in pure Python.
For instance, SML provides a tabulation tool: tabulate(f)
which produces a sequence f(0), f(1), .... This toolbox
provides imap() and count() which can be combined
to form imap(f, count()) and produce an equivalent result.
Likewise, the functional tools are designed to work well with the
high-speed functions provided by the operator module.
The module author welcomes suggestions for other basic building blocks
to be added to future versions of the module.
Whether cast in pure python form or C code, tools that use iterators
are more memory efficient (and faster) than their list based counterparts.
Adopting the principles of just-in-time manufacturing, they create
data when and where needed instead of consuming memory with the
computer equivalent of ``inventory''.
The performance advantage of iterators becomes more acute as the number
of elements increases -- at some point, lists grow large enough to
severely impact memory cache performance and start running slowly.
The Standard ML Basis Library,
[http://www.standardml.org/Basis/]
{The Standard ML Basis Library}.
Haskell, A Purely Functional Language,
[http://www.haskell.org/definition/]
{Definition of Haskell and the Standard Libraries}.
</description>
<group name="Itertool functions">
<description>The following module functions all construct and return iterators.
Some provide streams of infinite length, so they should only be accessed
by functions or loops that truncate the stream.
</description>
<element kind="function" name="chain">
<description>Make an iterator that returns elements from the first iterable until
it is exhausted, then proceeds to the next iterable, until all of the
iterables are exhausted. Used for treating consecutive sequences as
a single sequence. Equivalent to:
def chain(*iterables):
for it in iterables:
for element in it:
yield element
</description>

<properties><property kind="parameter" name="*iterables*iterables" required="1"/></properties></element>

<element kind="function" name="count">
<description>Make an iterator that returns consecutive integers starting with n.
If not specified n defaults to zero. Does not currently support python long integers. Often used as an
argument to imap() to generate consecutive data points.
Also, used with izip() to add sequence numbers. Equivalent to:
def count(n=0):
while True:
yield n
n += 1
Note, count() does not check for overflow and will return
negative numbers after exceeding sys.maxint. This behavior
may change in the future.</description>

<properties><property kind="parameter" name="n" required="1"/></properties></element>

<element kind="function" name="cycle">
<description>Make an iterator returning elements from the iterable and saving a
copy of each. When the iterable is exhausted, return elements from
the saved copy. Repeats indefinitely. Equivalent to:
def cycle(iterable):
saved = []
for element in iterable:
yield element
saved.append(element)
while saved:
for element in saved:
yield element
Note, this member of the toolkit may require significant
auxiliary storage (depending on the length of the iterable).</description>

<properties><property kind="parameter" name="iterableiterable" required="1"/></properties></element>

<element kind="function" name="dropwhile">
<description>Make an iterator that drops elements from the iterable as long as
the predicate is true; afterwards, returns every element. Note,
the iterator does not produce any output until the predicate
is true, so it may have a lengthy start-up time. Equivalent to:
def dropwhile(predicate, iterable):
iterable = iter(iterable)
for x in iterable:
if not predicate(x):
yield x
break
for x in iterable:
yield x
</description>

<properties><property kind="parameter" name="predicate" required="1"/><property kind="parameter" name="iterable iterable" required="1"/></properties></element>

<element kind="function" name="groupby">
<description>Make an iterator that returns consecutive keys and groups from the
iterable. key is a function computing a key value for each
element. If not specified or is None, key defaults to an
identity function and returns the element unchanged. Generally, the
iterable needs to already be sorted on the same key function.
The returned group is itself an iterator that shares the underlying
iterable with groupby(). Because the source is shared, when
the groupby object is advanced, the previous group is no
longer visible. So, if that data is needed later, it should be stored
as a list:
groups = []
uniquekeys = []
for k, g in groupby(data, keyfunc):
groups.append(list(g)) # Store group iterator as a list
uniquekeys.append(k)
groupby() is equivalent to:
class groupby(object):
def __init__(self, iterable, key=None):
if key is None:
key = lambda x: x
self.keyfunc = key
self.it = iter(iterable)
self.tgtkey = self.currkey = self.currvalue = xrange(0)
def __iter__(self):
return self
def next(self):
while self.currkey == self.tgtkey:
self.currvalue = self.it.next() # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
self.tgtkey = self.currkey
return (self.currkey, self._grouper(self.tgtkey))
def _grouper(self, tgtkey):
while self.currkey == tgtkey:
yield self.currvalue
self.currvalue = self.it.next() # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
New in version 2.4</description>

<properties><property kind="parameter" name="iterable" required="1"/><property kind="parameter" name="key"/></properties></element>

<element kind="function" name="ifilter">
<description>Make an iterator that filters elements from iterable returning only
those for which the predicate is True.
If predicate is None, return the items that are true.
Equivalent to:
def ifilter(predicate, iterable):
if predicate is None:
predicate = bool
for x in iterable:
if predicate(x):
yield x
</description>

<properties><property kind="parameter" name="predicate" required="1"/><property kind="parameter" name="iterable iterable" required="1"/></properties></element>

<element kind="function" name="ifilterfalse">
<description>Make an iterator that filters elements from iterable returning only
those for which the predicate is False.
If predicate is None, return the items that are false.
Equivalent to:
def ifilterfalse(predicate, iterable):
if predicate is None:
predicate = bool
for x in iterable:
if not predicate(x):
yield x
</description>

<properties><property kind="parameter" name="predicate" required="1"/><property kind="parameter" name="iterable iterable" required="1"/></properties></element>

<element kind="function" name="imap">
<description>Make an iterator that computes the function using arguments from
each of the iterables. If function is set to None, then
imap() returns the arguments as a tuple. Like
map() but stops when the shortest iterable is exhausted
instead of filling in None for shorter iterables. The reason
for the difference is that infinite iterator arguments are typically
an error for map() (because the output is fully evaluated)
but represent a common and useful way of supplying arguments to
imap().
Equivalent to:
def imap(function, *iterables):
iterables = map(iter, iterables)
while True:
args = [i.next() for i in iterables]
if function is None:
yield tuple(args)
else:
yield function(*args)
</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="*iterables *iterables" required="1"/></properties></element>

<element kind="function" name="islice">
<description>Make an iterator that returns selected elements from the iterable.
If start is non-zero, then elements from the iterable are skipped
until start is reached. Afterward, elements are returned consecutively
unless step is set higher than one which results in items being
skipped. If stop is None, then iteration continues until
the iterator is exhausted, if at all; otherwise, it stops at the specified
position. Unlike regular slicing,
islice() does not support negative values for start,
stop, or step. Can be used to extract related fields
from data where the internal structure has been flattened (for
example, a multi-line report may list a name field on every
third line). Equivalent to:
def islice(iterable, *args):
s = slice(*args)
next, stop, step = s.start or 0, s.stop, s.step or 1
for cnt, element in enumerate(iterable):
if cnt &lt; next:
continue
if stop is not None and cnt &gt;= stop:
break
yield element
next += step </description>

<properties><property kind="parameter" name="iterable" required="1"/><property kind="parameter" name="start" required="1"/><property kind="parameter" name="stop"/><property kind="parameter" name="step"/></properties></element>

<element kind="function" name="izip">
<description>Make an iterator that aggregates elements from each of the iterables.
Like zip() except that it returns an iterator instead of
a list. Used for lock-step iteration over several iterables at a
time. Equivalent to:
def izip(*iterables):
iterables = map(iter, iterables)
while iterables:
result = [i.next() for i in iterables]
yield tuple(result)
Changed in version 2.4: When no iterables are specified, returns a zero length
iterator instead of raising a TypeError exception</description>

<properties><property kind="parameter" name="*iterables*iterables" required="1"/></properties></element>

<element kind="function" name="repeat">
<description>Make an iterator that returns object over and over again.
Runs indefinitely unless the times argument is specified.
Used as argument to imap() for invariant parameters
to the called function. Also used with izip() to create
an invariant part of a tuple record. Equivalent to:
def repeat(object, times=None):
if times is None:
while True:
yield object
else:
for i in xrange(times):
yield object
</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="times"/></properties></element>

<element kind="function" name="starmap">
<description>Make an iterator that computes the function using arguments tuples
obtained from the iterable. Used instead of imap() when
argument parameters are already grouped in tuples from a single iterable
(the data has been ``pre-zipped''). The difference between
imap() and starmap() parallels the distinction
between function(a,b) and function(*c).
Equivalent to:
def starmap(function, iterable):
iterable = iter(iterable)
while True:
yield function(*iterable.next())
</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="iterable iterable" required="1"/></properties></element>

<element kind="function" name="takewhile">
<description>Make an iterator that returns elements from the iterable as long as
the predicate is true. Equivalent to:
def takewhile(predicate, iterable):
for x in iterable:
if predicate(x):
yield x
else:
break
</description>

<properties><property kind="parameter" name="predicate" required="1"/><property kind="parameter" name="iterable iterable" required="1"/></properties></element>

<element kind="function" name="tee">
<description>Return n independent iterators from a single iterable.
The case where n is two is equivalent to:
def tee(iterable):
def gen(next, data={}, cnt=[0]):
for i in count():
if i == cnt[0]:
item = data[i] = next()
cnt[0] += 1
else:
item = data.pop(i)
yield item
it = iter(iterable)
return (gen(it.next), gen(it.next))
Note, once tee() has made a split, the original iterable
should not be used anywhere else; otherwise, the iterable could get
advanced without the tee objects being informed.
Note, this member of the toolkit may require significant auxiliary
storage (depending on how much temporary data needs to be stored).
In general, if one iterator is going to use most or all of the data before
the other iterator, it is faster to use list() instead of
tee().
New in version 2.4</description>

<properties><property kind="parameter" name="iterable" required="1"/><property default="2" kind="parameter" name="n"/></properties></element>

</group>
<group name="Examples">
</group>
</group>
<group name="ConfigParser --- Configuration file parser">
<description>Configuration file parser.
This module defines the class ConfigParser.
</description>
<element kind="function" name="RawConfigParser">
<description>The basic configuration object. When defaults is given, it is
initialized into the dictionary of intrinsic defaults. This class
does not support the magical interpolation behavior.
New in version 2.3</description>

<properties><property kind="parameter" name="defaults" required="1"/></properties></element>

<element kind="function" name="ConfigParser">
<description>Derived class of RawConfigParser that implements the magical
interpolation feature and adds optional arguments to the get()
and items() methods. The values in defaults must be
appropriate for the %()s string interpolation. Note that
__name__ is an intrinsic default; its value is the section name,
and will override any value provided in defaults.</description>

<properties><property kind="parameter" name="defaults" required="1"/></properties></element>

<element kind="function" name="SafeConfigParser">
<description>Derived class of ConfigParser that implements a more-sane
variant of the magical interpolation feature. This implementation is
more predictable as well.
% XXX Need to explain what's safer/more predictable about it.
New applications should prefer this version if they don't need to be
compatible with older versions of Python.
New in version 2.3</description>

<properties><property kind="parameter" name="defaults" required="1"/></properties></element>

<group name="RawConfigParser Objects">
<description>RawConfigParser instances have the following methods:
</description>
<element kind="function" name="defaults">
<description>Return a dictionary containing the instance-wide defaults.</description>

</element>

<element kind="function" name="sections">
<description>Return a list of the sections available; DEFAULT is not
included in the list.</description>

</element>

<element kind="function" name="add_section">
<description>Add a section named section to the instance. If a section by
the given name already exists, DuplicateSectionError is
raised.</description>

<properties><property kind="parameter" name="sectionsection" required="1"/></properties></element>

<element kind="function" name="has_section">
<description>Indicates whether the named section is present in the
configuration. The DEFAULT section is not acknowledged.</description>

<properties><property kind="parameter" name="sectionsection" required="1"/></properties></element>

<element kind="function" name="options">
<description>Returns a list of options available in the specified section.</description>

<properties><property kind="parameter" name="sectionsection" required="1"/></properties></element>

<element kind="function" name="has_option">
<description>If the given section exists, and contains the given option. return 1;
otherwise return 0.
New in version 1.6</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option option" required="1"/></properties></element>

<element kind="function" name="read">
<description>Read and parse a list of filenames. If filenames is a string or
Unicode string, it is treated as a single filename.
If a file named in filenames cannot be opened, that file will be
ignored. This is designed so that you can specify a list of potential
configuration file locations (for example, the current directory, the
user's home directory, and some system-wide directory), and all
existing configuration files in the list will be read. If none of the
named files exist, the ConfigParser instance will contain an
empty dataset. An application which requires initial values to be
loaded from a file should load the required file or files using
readfp() before calling read() for any optional
files:
import ConfigParser, os
config = ConfigParser.ConfigParser()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
</description>

<properties><property kind="parameter" name="filenamesfilenames" required="1"/></properties></element>

<element kind="function" name="readfp">
<description>Read and parse configuration data from the file or file-like object in
fp (only the readline() method is used). If
filename is omitted and fp has a name attribute,
that is used for filename; the default is &lt;???&gt;.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="filename"/></properties></element>

<element kind="function" name="get">
<description>Get an option value for the named section.</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option option" required="1"/></properties></element>

<element kind="function" name="getint">
<description>A convenience method which coerces the option in the specified
section to an integer.</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option option" required="1"/></properties></element>

<element kind="function" name="getfloat">
<description>A convenience method which coerces the option in the specified
section to a floating point number.</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option option" required="1"/></properties></element>

<element kind="function" name="getboolean">
<description>A convenience method which coerces the option in the specified
section to a Boolean value. Note that the accepted values
for the option are &quot;1&quot;, &quot;yes&quot;, &quot;true&quot;, and &quot;on&quot;,
which cause this method to return True, and &quot;0&quot;, &quot;no&quot;,
&quot;false&quot;, and &quot;off&quot;, which cause it to return False. These
string values are checked in a case-insensitive manner. Any other value will
cause it to raise ValueError.</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option option" required="1"/></properties></element>

<element kind="function" name="items">
<description>Return a list of (name, value) pairs for each
option in the given section.</description>

<properties><property kind="parameter" name="sectionsection" required="1"/></properties></element>

<element kind="function" name="set">
<description>If the given section exists, set the given option to the specified value;
otherwise raise NoSectionError.
New in version 1.6</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="write">
<description>Write a representation of the configuration to the specified file
object. This representation can be parsed by a future read()
call.
New in version 1.6</description>

<properties><property kind="parameter" name="fileobjectfileobject" required="1"/></properties></element>

<element kind="function" name="remove_option">
<description>Remove the specified option from the specified section.
If the section does not exist, raise NoSectionError. If the option existed to be removed, return 1; otherwise return 0.
New in version 1.6</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option option" required="1"/></properties></element>

<element kind="function" name="remove_section">
<description>Remove the specified section from the configuration.
If the section in fact existed, return True.
Otherwise return False.</description>

<properties><property kind="parameter" name="sectionsection" required="1"/></properties></element>

<element kind="function" name="optionxform">
<description>Transforms the option name option as found in an input file or
as passed in by client code to the form that should be used in the
internal structures. The default implementation returns a lower-case
version of option; subclasses may override this or client code
can set an attribute of this name on instances to affect this
behavior. Setting this to str(), for example, would make
option names case sensitive.</description>

<properties><property kind="parameter" name="optionoption" required="1"/></properties></element>

</group>
<group name="ConfigParser Objects">
<description>The ConfigParser class extends some methods of the
RawConfigParser interface, adding some optional arguments.
</description>
<element kind="function" name="get">
<description>Get an option value for the named section. All the
% interpolations are expanded in the return values, based
on the defaults passed into the constructor, as well as the options
vars provided, unless the raw argument is true.</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="option" required="1"/><property kind="parameter" name="raw"/><property kind="parameter" name="vars"/></properties></element>

<element kind="function" name="items">
<description>Return a list of (name, value) pairs for each
option in the given section. Optional arguments have the
same meaning as for the get() method.
New in version 2.3</description>

<properties><property kind="parameter" name="section" required="1"/><property kind="parameter" name="raw"/><property kind="parameter" name="vars"/></properties></element>

</group>
</group>
<group name="fileinput --- Iterate over lines from multiple input streams">
<description>Perl-like iteration over lines from multiple input
streams, with ``save in place'' capability.
This module implements a helper class and functions to quickly write a
loop over standard input or a list of files.
The typical use is:
import fileinput
for line in fileinput.input():
process(line)
This iterates over the lines of all files listed in
sys.argv[1:], defaulting to sys.stdin if the list is
empty. If a filename is '-', it is also replaced by
sys.stdin. To specify an alternative list of filenames, pass
it as the first argument to input(). A single file name is
also allowed.
All files are opened in text mode. If an I/O error occurs during
opening or reading a file, IOError is raised.
If sys.stdin is used more than once, the second and further use
will return no lines, except perhaps for interactive use, or if it has
been explicitly reset (e.g. using sys.stdin.seek(0)).
Empty files are opened and immediately closed; the only time their
presence in the list of filenames is noticeable at all is when the
last file opened is empty.
It is possible that the last line of a file does not end in a newline
character; lines are returned including the trailing newline when it
is present.
The following function is the primary interface of this module:
</description>
<element kind="function" name="input">
<description>Create an instance of the FileInput class. The instance
will be used as global state for the functions of this module, and
is also returned to use during iteration. The parameters to this
function will be passed along to the constructor of the
FileInput class.</description>

<properties><property kind="parameter" name="files" required="1"/><property kind="parameter" name="inplace"/><property kind="parameter" name="backup"/></properties></element>

<element kind="function" name="filename">
<description>Return the name of the file currently being read. Before the first
line has been read, returns None.</description>

</element>

<element kind="function" name="lineno">
<description>Return the cumulative line number of the line that has just been
read. Before the first line has been read, returns 0. After
the last line of the last file has been read, returns the line
number of that line.</description>

</element>

<element kind="function" name="filelineno">
<description>Return the line number in the current file. Before the first line
has been read, returns 0. After the last line of the last
file has been read, returns the line number of that line within the
file.</description>

</element>

<element kind="function" name="isfirstline">
<description>Returns true if the line just read is the first line of its file,
otherwise returns false.</description>

</element>

<element kind="function" name="isstdin">
<description>Returns true if the last line was read from sys.stdin,
otherwise returns false.</description>

</element>

<element kind="function" name="nextfile">
<description>Close the current file so that the next iteration will read the
first line from the next file (if any); lines not read from the file
will not count towards the cumulative line count. The filename is
not changed until after the first line of the next file has been
read. Before the first line has been read, this function has no
effect; it cannot be used to skip the first file. After the last
line of the last file has been read, this function has no effect.</description>

</element>

<element kind="function" name="close">
<description>Close the sequence.</description>

</element>

<element kind="function" name="FileInput">
<description>Class FileInput is the implementation; its methods
filename(), lineno(), fileline(),
isfirstline(), isstdin(), nextfile() and
close() correspond to the functions of the same name in the
module. In addition it has a readline() method which
returns the next input line, and a __getitem__() method
which implements the sequence behavior. The sequence must be
accessed in strictly sequential order; random access and
readline() cannot be mixed.</description>

<properties><property kind="parameter" name="files" required="1"/><property kind="parameter" name="inplace"/><property kind="parameter" name="backup"/></properties></element>

</group>
<group name="xreadlines --- Efficient iteration over a file">
<description>Efficient iteration over the lines of a file.
New in version 2.1
2.3{Use for line in file instead.}
This module defines a new object type which can efficiently iterate
over the lines of a file. An xreadlines object is a sequence type
which implements simple in-order indexing beginning at 0, as
required by for statement or the
filter() function.
Thus, the code
import xreadlines, sys
for line in xreadlines.xreadlines(sys.stdin):
pass
has approximately the same speed and memory consumption as
while 1:
lines = sys.stdin.readlines(8*1024)
if not lines: break
for line in lines:
pass
except the clarity of the for statement is retained in the
former case.
</description>
<element kind="function" name="xreadlines">
<description>Return a new xreadlines object which will iterate over the contents
of fileobj. fileobj must have a readlines()
method that supports the sizehint parameter. Because
the readlines() method buffers data, this effectively
ignores the effects of setting the file object as unbuffered.</description>

<properties><property kind="parameter" name="fileobjfileobj" required="1"/></properties></element>

</group>
<group name="calendar --- General calendar-related functions">
<description>Functions for working with calendars,
including some emulation of the cal
program.
This module allows you to output calendars like the cal program, and provides additional useful functions
related to the calendar. By default, these calendars have Monday as
the first day of the week, and Sunday as the last (the European
convention). Use setfirstweekday() to set the first day of the
week to Sunday (6) or to any other weekday. Parameters that specify
dates are given as integers.
Most of these functions rely on the datetime module which
uses an idealized calendar, the current Gregorian calendar indefinitely
extended in both directions. This matches the definition of the
&quot;proleptic Gregorian&quot; calendar in Dershowitz and Reingold's book
&quot;Calendrical Calculations&quot;, where it's the base calendar for all
computations.
</description>
<element kind="function" name="setfirstweekday">
<description>Sets the weekday (0 is Monday, 6 is Sunday) to start
each week. The values MONDAY, TUESDAY,
WEDNESDAY, THURSDAY, FRIDAY,
SATURDAY, and SUNDAY are provided for
convenience. For example, to set the first weekday to Sunday:
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
New in version 2.0</description>

<properties><property kind="parameter" name="weekdayweekday" required="1"/></properties></element>

<element kind="function" name="firstweekday">
<description>Returns the current setting for the weekday to start each week.
New in version 2.0</description>

</element>

<element kind="function" name="isleap">
<description>Returns 1 if year is a leap year, otherwise 0.</description>

<properties><property kind="parameter" name="yearyear" required="1"/></properties></element>

<element kind="function" name="leapdays">
<description>Returns the number of leap years in the range
[y1...y2), where y1 and y2 are years.
Changed in version 2.0: This function didn't work for ranges spanning a century change in Python 1.5.2</description>

<properties><property kind="parameter" name="y1" required="1"/><property kind="parameter" name="y2 y2" required="1"/></properties></element>

<element kind="function" name="weekday">
<description>Returns the day of the week (0 is Monday) for year
(1970--...), month (1--12), day
(1--31).</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month" required="1"/><property kind="parameter" name="day day" required="1"/></properties></element>

<element kind="function" name="monthrange">
<description>Returns weekday of first day of the month and number of days in month, for the specified year and month.</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month month" required="1"/></properties></element>

<element kind="function" name="monthcalendar">
<description>Returns a matrix representing a month's calendar. Each row represents
a week; days outside of the month a represented by zeros.
Each week begins with Monday unless set by setfirstweekday().</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month month" required="1"/></properties></element>

<element kind="function" name="prmonth">
<description>Prints a month's calendar as returned by month().</description>

<properties><property kind="parameter" name="theyear" required="1"/><property kind="parameter" name="themonth" required="1"/><property kind="parameter" name="w"/><property kind="parameter" name="l"/></properties></element>

<element kind="function" name="month">
<description>Returns a month's calendar in a multi-line string. If w is
provided, it specifies the width of the date columns, which are
centered. If l is given, it specifies the number of lines that
each week will use. Depends on the first weekday as set by
setfirstweekday().
New in version 2.0</description>

<properties><property kind="parameter" name="theyear" required="1"/><property kind="parameter" name="themonth" required="1"/><property kind="parameter" name="w"/><property kind="parameter" name="l"/></properties></element>

<element kind="function" name="prcal">
<description>Prints the calendar for an entire year as returned by calendar().</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="w"/><property kind="parameter" name="lc"/></properties></element>

<element kind="function" name="calendar">
<description>Returns a 3-column calendar for an entire year as a multi-line string.
Optional parameters w, l, and c are for date column
width, lines per week, and number of spaces between month columns,
respectively. Depends on the first weekday as set by
setfirstweekday(). The earliest year for which a calendar can
be generated is platform-dependent.
New in version 2.0</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="w"/><property kind="parameter" name="lc"/></properties></element>

<element kind="function" name="timegm">
<description>An unrelated but handy function that takes a time tuple such as
returned by the gmtime() function in the time
module, and returns the corresponding timestamp value, assuming
an epoch of 1970, and the POSIX encoding. In fact,
time.gmtime() and timegm() are each others' inverse.
New in version 2.0</description>

<properties><property kind="parameter" name="tupletuple" required="1"/></properties></element>

</group>
<group name="cmd --- Support for line-oriented command interpreters">
<description>Build line-oriented command interpreters.
The Cmd class provides a simple framework for writing
line-oriented command interpreters. These are often useful for
test harnesses, administrative tools, and prototypes that will
later be wrapped in a more sophisticated interface.
</description>
<element kind="function" name="Cmd">
<description>A Cmd instance or subclass instance is a line-oriented
interpreter framework. There is no good reason to instantiate
Cmd itself; rather, it's useful as a superclass of an
interpreter class you define yourself in order to inherit
Cmd's methods and encapsulate action methods.
The optional argument completekey is the readline name
of a completion key; it defaults to Tab. If completekey is
not None and readline is available, command completion
is done automatically.
The optional arguments stdin and stdout specify the input and output file objects that the Cmd instance or subclass instance will use for input and output. If not specified, they
will default to sys.stdin and sys.stdout.
Changed in version 2.3: The stdin and stdout parameters were added.</description>

<properties><property kind="parameter" name="completekey" required="1"/><property kind="parameter" name="stdin"/><property kind="parameter" name="stdout"/></properties></element>

<group name="Cmd Objects">
<element kind="function" name="cmdloop">
<description>Repeatedly issue a prompt, accept input, parse an initial prefix off
the received input, and dispatch to action methods, passing them the
remainder of the line as argument.
The optional argument is a banner or intro string to be issued before the
first prompt (this overrides the intro class member).
If the readline module is loaded, input will automatically
inherit bash-like history-list editing (e.g. Control-P
scrolls back to the last command, Control-N forward to the next
one, Control-F moves the cursor to the right non-destructively,
Control-B moves the cursor to the left non-destructively, etc.).
An end-of-file on input is passed back as the string 'EOF'.
An interpreter instance will recognize a command name foo if
and only if it has a method do_foo(). As a special case,
a line beginning with the character ? is dispatched to
the method do_help(). As another special case, a line
beginning with the character ! is dispatched to the
method do_shell() (if such a method is defined).
If completion is enabled, completing commands will be done
automatically, and completing of commands args is done by calling
complete_foo() with arguments text, line,
begidx, and endidx. text is the string prefix we
are attempting to match: all returned matches must begin with it.
line is the current input line with leading whitespace removed,
begidx and endidx are the beginning and ending indexes
of the prefix text, which could be used to provide different
completion depending upon which position the argument is in.
All subclasses of Cmd inherit a predefined do_help().
This method, called with an argument 'bar', invokes the
corresponding method help_bar(). With no argument,
do_help() lists all available help topics (that is, all
commands with corresponding help_*() methods), and also lists
any undocumented commands.</description>

<properties><property kind="parameter" name="intro" required="1"/></properties></element>

<element kind="function" name="onecmd">
<description>Interpret the argument as though it had been typed in response to the
prompt. This may be overridden, but should not normally need to be;
see the precmd() and postcmd() methods for useful
execution hooks. The return value is a flag indicating whether
interpretation of commands by the interpreter should stop.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="emptyline">
<description>Method called when an empty line is entered in response to the prompt.
If this method is not overridden, it repeats the last nonempty command
entered.</description>

</element>

<element kind="function" name="default">
<description>Method called on an input line when the command prefix is not
recognized. If this method is not overridden, it prints an
error message and returns.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="completedefault">
<description>Method called to complete an input line when no command-specific
complete_*() method is available. By default, it returns an
empty list.</description>

<properties><property kind="parameter" name="text" required="1"/><property kind="parameter" name="line" required="1"/><property kind="parameter" name="begidx" required="1"/><property kind="parameter" name="endidx endidx" required="1"/></properties></element>

<element kind="function" name="precmd">
<description>Hook method executed just before the command line line is
interpreted, but after the input prompt is generated and issued. This
method is a stub in Cmd; it exists to be overridden by
subclasses. The return value is used as the command which will be
executed by the onecmd() method; the precmd()
implementation may re-write the command or simply return line
unchanged.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="postcmd">
<description>Hook method executed just after a command dispatch is finished. This
method is a stub in Cmd; it exists to be overridden by
subclasses. line is the command line which was executed, and
stop is a flag which indicates whether execution will be
terminated after the call to postcmd(); this will be the
return value of the onecmd() method. The return value of
this method will be used as the new value for the internal flag which
corresponds to stop; returning false will cause interpretation
to continue.</description>

<properties><property kind="parameter" name="stop" required="1"/><property kind="parameter" name="line line" required="1"/></properties></element>

<element kind="function" name="preloop">
<description>Hook method executed once when cmdloop() is called. This
method is a stub in Cmd; it exists to be overridden by
subclasses.</description>

</element>

<element kind="function" name="postloop">
<description>Hook method executed once when cmdloop() is about to return.
This method is a stub in Cmd; it exists to be overridden by
subclasses.</description>

</element>

</group>
</group>
<group name="shlex --- Simple lexical analysis">
<description>Simple lexical analysis for -like languages.
New in version 1.5.2
The shlex class makes it easy to write lexical analyzers for
simple syntaxes resembling that of the shell. This will often
be useful for writing minilanguages, (e.g. in run control files for
Python applications) or for parsing quoted strings.
ConfigParser{Parser for configuration files similar to the
Windows .ini files.}
</description>
<group name="Module Contents">
<description>The shlex module defines the following functions:
</description>
<element kind="function" name="split">
<description>Split the string s using shell-like syntax. If comments is
False, the parsing of comments in the given string will be
disabled (setting the commenters member of the shlex
instance to the empty string). This function operates in mode.
New in version 2.3</description>

<properties><property kind="parameter" name="s" required="1"/><property default="False" kind="parameter" name="comments"/></properties></element>

<element kind="function" name="shlex">
<description>A shlex instance or subclass instance is a lexical analyzer
object. The initialization argument, if present, specifies where to
read characters from. It must be a file-/stream-like object with
read() and readline() methods, or a string (strings
are accepted since Python 2.3). If no argument is given, input will be
taken from sys.stdin. The second optional argument is a filename
string, which sets the initial value of the infile member. If
the instream argument is omitted or equal to sys.stdin,
this second argument defaults to ``stdin''. The posix argument
was introduced in Python 2.3, and defines the operational mode. When
posix is not true (default), the shlex instance will
operate in compatibility mode. When operating in mode,
shlex will try to be as close as possible to the shell
parsing rules. See~shlex-objects.</description>

<properties><property default="sys.stdin" kind="parameter" name="instream" required="1"/><property default="None" kind="parameter" name="infile"/><property default="False" kind="parameter" name="posix"/></properties></element>

</group>
<group name="shlex Objects">
<description>A shlex instance has the following methods:
</description>
<element kind="function" name="get_token">
<description>Return a token. If tokens have been stacked using
push_token(), pop a token off the stack. Otherwise, read one
from the input stream. If reading encounters an immediate
end-of-file, self.eof is returned (the empty string ('')
in non- mode, and None in mode).</description>

</element>

<element kind="function" name="push_token">
<description>Push the argument onto the token stack.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="read_token">
<description>Read a raw token. Ignore the pushback stack, and do not interpret source
requests. (This is not ordinarily a useful entry point, and is
documented here only for the sake of completeness.)</description>

</element>

<element kind="function" name="sourcehook">
<description>When shlex detects a source request (see
source below) this method is given the following token as
argument, and expected to return a tuple consisting of a filename and
an open file-like object.
Normally, this method first strips any quotes off the argument. If
the result is an absolute pathname, or there was no previous source
request in effect, or the previous source was a stream
(e.g. sys.stdin), the result is left alone. Otherwise, if the
result is a relative pathname, the directory part of the name of the
file immediately before it on the source inclusion stack is prepended
(this behavior is like the way the C preprocessor handles
&quot;file.h&quot;).
The result of the manipulations is treated as a filename, and returned
as the first component of the tuple, with
open() called on it to yield the second component. (Note:
this is the reverse of the order of arguments in instance initialization!)
This hook is exposed so that you can use it to implement directory
search paths, addition of file extensions, and other namespace hacks.
There is no corresponding `close' hook, but a shlex instance will call
the close() method of the sourced input stream when it
returns .
For more explicit control of source stacking, use the
push_source() and pop_source() methods.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="push_source">
<description>Push an input source stream onto the input stack. If the filename
argument is specified it will later be available for use in error
messages. This is the same method used internally by the
sourcehook method.
New in version 2.1</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="filename"/></properties></element>

<element kind="function" name="pop_source">
<description>Pop the last-pushed input source from the input stack.
This is the same method used internally when the lexer reaches
on a stacked input stream.
New in version 2.1</description>

</element>

<element kind="function" name="error_leader">
<description>This method generates an error message leader in the format of a
C compiler error label; the format is '&quot;&quot;, line : ',
where the is replaced with the name of the current source
file and the with the current input line number (the
optional arguments can be used to override these).
This convenience is provided to encourage shlex users to
generate error messages in the standard, parseable format understood
by Emacs and other tools.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="line"/></properties></element>

</group>
<group name="Parsing Rules">
</group>
</group>
</group>
<group name="Generic Operating System Services">
<group name="os --- Miscellaneous operating system interfaces">
<description>Miscellaneous operating system interfaces.
This module provides a more portable way of using operating system
dependent functionality than importing a operating system dependent
built-in module like posix or nt.
This module searches for an operating system dependent built-in module like
mac or posix and exports the same functions and data
as found there. The design of all Python's built-in operating system dependent
modules is such that as long as the same functionality is available,
it uses the same interface; for example, the function
os.stat(path) returns stat information about path in
the same format (which happens to have originated with the
interface).
Extensions peculiar to a particular operating system are also
available through the os module, but using them is of course a
threat to portability!
Note that after the first time os is imported, there is
no performance penalty in using functions from os
instead of directly from the operating system dependent built-in module,
so there should be no reason not to use os!
% Frank Stajano &lt;fstajano@uk.research.att.com&gt; complained that it
% wasn't clear that the entries described in the subsections were all
% available at the module level (most uses of subsections are
% different); I think this is only a problem for the HTML version,
% where the relationship may not be as clear.
%
The os module contains many functions and data values.
The items below and in the following sub-sections are all available
directly from the os module.
{error}
This exception is raised when a function returns a system-related
error (not for illegal argument types or other incidental errors).
This is also known as the built-in exception OSError. The
accompanying value is a pair containing the numeric error code from
errno and the corresponding string, as would be printed by the
C function perror(). See the module
errnoerrno, which contains names for the
error codes defined by the underlying operating system.
When exceptions are classes, this exception carries two attributes,
errno and strerror. The first holds the value of
the C errno variable, and the latter holds the corresponding
error message from strerror(). For exceptions that
involve a file system path (such as chdir() or
unlink()), the exception instance will contain a third
attribute, filename, which is the file name passed to the
function.
{name}
The name of the operating system dependent module imported. The
following names have currently been registered: 'posix',
'nt', 'mac', 'os2', 'ce',
'java', 'riscos'.
{path}
The corresponding operating system dependent standard module for pathname
operations, such as posixpath or macpath. Thus,
given the proper imports, os.path.split(file) is
equivalent to but more portable than
posixpath.split(file). Note that this is also an
importable module: it may be imported directly as
os.path.
</description>
<group name="Process Parameters">
<description>These functions and data items provide information and operate on the
current process and user.
{environ}
A mapping object representing the string environment. For example,
environ['HOME'] is the pathname of your home directory (on some
platforms), and is equivalent to getenv(&quot;HOME&quot;) in C.
If the platform supports the putenv() function, this
mapping may be used to modify the environment as well as query the
environment. putenv() will be called automatically when
the mapping is modified. On some platforms, including
FreeBSD and Mac OS X, setting environ may cause memory leaks.
Refer to the system documentation for putenv.
If putenv() is not provided, this mapping may be passed to
the appropriate process-creation functions to cause child processes to
use a modified environment.
{chdir}{path}
fchdir{fd}
getcwd{}
These functions are described in ``Files and Directories'' (section
os-file-dir).
</description>
<element kind="function" name="ctermid">
<description>Return the filename corresponding to the controlling terminal of the
process.
Availability: .</description>

</element>

<element kind="function" name="getegid">
<description>Return the effective group id of the current process. This
corresponds to the `set id' bit on the file being executed in the
current process.
Availability: .</description>

</element>

<element kind="function" name="geteuid">
<description/>

</element>

<element kind="function" name="getgid">
<description/>

</element>

<element kind="function" name="getgroups">
<description>Return list of supplemental group ids associated with the current
process.
Availability: .</description>

</element>

<element kind="function" name="getlogin">
<description>Return the name of the user logged in on the controlling terminal of
the process. For most purposes, it is more useful to use the
environment variable LOGNAME to find out who the user is,
or pwd.getpwuid(os.getuid())[0] to get the login name
of the currently effective user ID.
Availability: .</description>

</element>

<element kind="function" name="getpgid">
<description>Return the process group id of the process with process id pid.
If pid is 0, the process group id of the current process is
returned. Availability: .
New in version 2.3</description>

<properties><property kind="parameter" name="pidpid" required="1"/></properties></element>

<element kind="function" name="getpgrp">
<description/>

</element>

<element kind="function" name="getpid">
<description/>

</element>

<element kind="function" name="getppid">
<description/>

</element>

<element kind="function" name="getuid">
<description/>

</element>

<element kind="function" name="getenv">
<description>Return the value of the environment variable varname if it
exists, or value if it doesn't. value defaults to
None.
Availability: most flavors of , Windows.</description>

<properties><property kind="parameter" name="varname" required="1"/><property kind="parameter" name="value"/></properties></element>

<element kind="function" name="putenv">
<description/>

<properties><property kind="parameter" name="varname" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="setegid">
<description>Set the current process's effective group id.
Availability: .</description>

<properties><property kind="parameter" name="egidegid" required="1"/></properties></element>

<element kind="function" name="seteuid">
<description>Set the current process's effective user id.
Availability: .</description>

<properties><property kind="parameter" name="euideuid" required="1"/></properties></element>

<element kind="function" name="setgid">
<description>Set the current process' group id.
Availability: .</description>

<properties><property kind="parameter" name="gidgid" required="1"/></properties></element>

<element kind="function" name="setgroups">
<description>Set the list of supplemental group ids associated with the current
process to groups. groups must be a sequence, and each
element must be an integer identifying a group. This operation is
typical available only to the superuser.
Availability: .
New in version 2.2</description>

<properties><property kind="parameter" name="groupsgroups" required="1"/></properties></element>

<element kind="function" name="setpgrp">
<description>Calls the system call setpgrp() or setpgrp(0,
0) depending on which version is implemented (if any). See the
manual for the semantics.
Availability: .</description>

</element>

<element kind="function" name="setpgid">
<description>Calls the system call
setpgid() to set the process group id of the process with
id pid to the process group with id pgrp. See the manual for the semantics.
Availability: .</description>

<properties><property kind="parameter" name="pid" required="1"/><property kind="parameter" name="pgrp pgrp" required="1"/></properties></element>

<element kind="function" name="setreuid">
<description>Set the current process's real and effective user ids.
Availability: .</description>

<properties><property kind="parameter" name="ruid" required="1"/><property kind="parameter" name="euid euid" required="1"/></properties></element>

<element kind="function" name="setregid">
<description>Set the current process's real and effective group ids.
Availability: .</description>

<properties><property kind="parameter" name="rgid" required="1"/><property kind="parameter" name="egid egid" required="1"/></properties></element>

<element kind="function" name="getsid">
<description>Calls the system call getsid(). See the manual
for the semantics.
Availability: . New in version 2.4</description>

<properties><property kind="parameter" name="pidpid" required="1"/></properties></element>

<element kind="function" name="setsid">
<description>Calls the system call setsid(). See the manual
for the semantics.
Availability: .</description>

</element>

<element kind="function" name="setuid">
<description/>

<properties><property kind="parameter" name="uiduid" required="1"/></properties></element>

<element kind="function" name="strerror">
<description>Return the error message corresponding to the error code in
code.
Availability: , Windows.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="umask">
<description>Set the current numeric umask and returns the previous umask.
Availability: , Windows.</description>

<properties><property kind="parameter" name="maskmask" required="1"/></properties></element>

<element kind="function" name="uname">
<description>Return a 5-tuple containing information identifying the current
operating system. The tuple contains 5 strings:
(sysname, nodename, release, version,
machine). Some systems truncate the nodename to 8
characters or to the leading component; a better way to get the
hostname is socket.gethostname()
(in module socket){gethostname()}
or even
(in module socket){gethostbyaddr()}
socket.gethostbyaddr(socket.gethostname()).
Availability: recent flavors of .</description>

</element>

</group>
<group name="File Object Creation">
<description>These functions create new file objects.
</description>
<element kind="function" name="fdopen">
<description>Return an open file object connected to the file descriptor fd.
</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="popen">
<description>Open a pipe to or from command. The return value is an open
file object connected to the pipe, which can be read or written
depending on whether mode is 'r' (default) or 'w'.
The bufsize argument has the same meaning as the corresponding
argument to the built-in open() function. The exit status of
the command (encoded in the format specified for wait()) is
available as the return value of the close() method of the file
object, except that when the exit status is zero (termination without
errors), None is returned.
Availability: , Windows.
Changed in version 2.0: This function worked unreliably under Windows in
earlier versions of Python. This was due to the use of the
_popen() function from the libraries provided with
Windows. Newer versions of Python do not use the broken
implementation from the Windows libraries</description>

<properties><property kind="parameter" name="command" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="tmpfile">
<description>Return a new file object opened in update mode (w+b). The file
has no directory entries associated with it and will be automatically
deleted once there are no file descriptors for the file.
Availability: , Windows.</description>

</element>

<element kind="function" name="popen2">
<description>Executes cmd as a sub-process. Returns the file objects
(child_stdin, child_stdout).
Availability: , Windows.
New in version 2.0</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="popen3">
<description>Executes cmd as a sub-process. Returns the file objects
(child_stdin, child_stdout, child_stderr).
Availability: , Windows.
New in version 2.0</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="popen4">
<description>Executes cmd as a sub-process. Returns the file objects
(child_stdin, child_stdout_and_stderr).
Availability: , Windows.
New in version 2.0</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

</group>
<group name="File Descriptor Operations">
<description>These functions operate on I/O streams referred to
using file descriptors.
</description>
<element kind="function" name="close">
<description>Close file descriptor fd.
Availability: Macintosh, , Windows.
Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by open() or
pipe(). To close a ``file object'' returned by the
built-in function open() or by popen() or
fdopen(), use its close() method.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="dup">
<description>Return a duplicate of file descriptor fd.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="dup2">
<description>Duplicate file descriptor fd to fd2, closing the latter
first if necessary.
Availability: , Windows.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="fd2 fd2" required="1"/></properties></element>

<element kind="function" name="fdatasync">
<description>Force write of file with filedescriptor fd to disk.
Does not force update of metadata.
Availability: .</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="fpathconf">
<description>Return system configuration information relevant to an open file.
name specifies the configuration value to retrieve; it may be a
string which is the name of a defined system value; these names are
specified in a number of standards (.1, 95, 98, and
others). Some platforms define additional names as well. The names
known to the host operating system are given in the
pathconf_names dictionary. For configuration variables not
included in that mapping, passing an integer for name is also
accepted.
Availability: .
If name is a string and is not known, ValueError is
raised. If a specific value for name is not supported by the
host system, even if it is included in pathconf_names, an
OSError is raised with errno.EINVAL for the
error number.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="fstat">
<description>Return status for file descriptor fd, like stat().
Availability: , Windows.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="fstatvfs">
<description>Return information about the filesystem containing the file associated
with file descriptor fd, like statvfs().
Availability: .</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="fsync">
<description>Force write of file with filedescriptor fd to disk. On ,
this calls the native fsync() function; on Windows, the
MS _commit() function.
If you're starting with a Python file object f, first do
f.flush(), and then do os.fsync(f.fileno()),
to ensure that all internal buffers associated with f are written
to disk.
Availability: , and Windows starting in 2.2.3.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="ftruncate">
<description>Truncate the file corresponding to file descriptor fd,
so that it is at most length bytes in size.
Availability: .</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="length length" required="1"/></properties></element>

<element kind="function" name="isatty">
<description>Return True if the file descriptor fd is open and
connected to a tty(-like) device, else False.
Availability: .</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="lseek">
<description>Set the current position of file descriptor fd to position
pos, modified by how: 0 to set the position
relative to the beginning of the file; 1 to set it relative to
the current position; 2 to set it relative to the end of the
file.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="pos" required="1"/><property kind="parameter" name="how how" required="1"/></properties></element>

<element kind="function" name="open">
<description>Open the file file and set various flags according to
flags and possibly its mode according to mode.
The default mode is 0777 (octal), and the current umask
value is first masked out. Return the file descriptor for the newly
opened file.
Availability: Macintosh, , Windows.
For a description of the flag and mode values, see the C run-time
documentation; flag constants (like O_RDONLY and
O_WRONLY) are defined in this module too (see below).
Note: this function is intended for low-level I/O. For normal usage,
use the built-in function open(), which returns a ``file
object'' with read() and write() methods (and many
more).</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="flags" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="openpty">
<description>Open a new pseudo-terminal pair. Return a pair of file descriptors
(master, slave) for the pty and the tty,
respectively. For a (slightly) more portable approach, use the
ptypty module.
Availability: Some flavors of .</description>

</element>

<element kind="function" name="pipe">
<description>Create a pipe. Return a pair of file descriptors (r,
w) usable for reading and writing, respectively.
Availability: , Windows.</description>

</element>

<element kind="function" name="read">
<description>Read at most n bytes from file descriptor fd.
Return a string containing the bytes read. If the end of the file
referred to by fd has been reached, an empty string is
returned.
Availability: Macintosh, , Windows.
Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by open() or
pipe(). To read a ``file object'' returned by the
built-in function open() or by popen() or
fdopen(), or sys.stdin, use its
read() or readline() methods.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="tcgetpgrp">
<description>Return the process group associated with the terminal given by
fd (an open file descriptor as returned by open()).
Availability: .</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="tcsetpgrp">
<description>Set the process group associated with the terminal given by
fd (an open file descriptor as returned by open())
to pg.
Availability: .</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="pg pg" required="1"/></properties></element>

<element kind="function" name="ttyname">
<description>Return a string which specifies the terminal device associated with
file-descriptor fd. If fd is not associated with a terminal
device, an exception is raised.
Availability: .</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="write">
<description>Write the string str to file descriptor fd.
Return the number of bytes actually written.
Availability: Macintosh, , Windows.
Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by open() or
pipe(). To write a ``file object'' returned by the
built-in function open() or by popen() or
fdopen(), or sys.stdout or sys.stderr, use
its write() method.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="str str" required="1"/></properties></element>

</group>
<group name="Files and Directories">
<element kind="function" name="access">
<description>Use the real uid/gid to test for access to path. Note that most
operations will use the effective uid/gid, therefore this routine can
be used in a suid/sgid environment to test if the invoking user has the
specified access to path. mode should be F_OK
to test the existence of path, or it can be the inclusive OR of
one or more of R_OK, W_OK, and X_OK to
test permissions. Return 1 if access is allowed, 0 if not.
See the man page access{2} for more information.
Availability: , Windows.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="mode mode" required="1"/></properties></element>

<element kind="function" name="chdir">
<description/>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="fchdir">
<description>Change the current working directory to the directory represented by
the file descriptor fd. The descriptor must refer to an opened
directory, not an open file.
Availability: .
New in version 2.3</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="getcwd">
<description>Return a string representing the current working directory.
Availability: Macintosh, , Windows.</description>

</element>

<element kind="function" name="getcwdu">
<description>Return a Unicode object representing the current working directory.
Availability: , Windows.
New in version 2.3</description>

</element>

<element kind="function" name="chroot">
<description>Change the root directory of the current process to path.
Availability: .
New in version 2.2</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="chmod">
<description>Change the mode of path to the numeric mode.
mode may take one of the following values
(as defined in the stat module):
S_ISUID
S_ISGID
S_ENFMT
S_ISVTX
S_IREAD
S_IWRITE
S_IEXEC
S_IRWXU
S_IRUSR
S_IWUSR
S_IXUSR
S_IRWXG
S_IRGRP
S_IWGRP
S_IXGRP
S_IRWXO
S_IROTH
S_IWOTH
S_IXOTH
Availability: , Windows.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="mode mode" required="1"/></properties></element>

<element kind="function" name="chown">
<description>Change the owner and group id of path to the numeric uid
and gid.
Availability: .</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="uid" required="1"/><property kind="parameter" name="gid gid" required="1"/></properties></element>

<element kind="function" name="lchown">
<description>Change the owner and group id of path to the numeric uid
and gid. This function will not follow symbolic links.
Availability: .
New in version 2.3</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="uid" required="1"/><property kind="parameter" name="gid gid" required="1"/></properties></element>

<element kind="function" name="link">
<description>Create a hard link pointing to src named dst.
Availability: .</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="listdir">
<description>Return a list containing the names of the entries in the directory.
The list is in arbitrary order. It does not include the special
entries '.' and '..' even if they are present in the
directory.
Availability: Macintosh, , Windows.
Changed in version 2.3: On Windows NT/2k/XP and Unix, if path is a Unicode
object, the result will be a list of Unicode objects.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="lstat">
<description>Like stat(), but do not follow symbolic links.
Availability: .</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="mkfifo">
<description>Create a FIFO (a named pipe) named path with numeric mode
mode. The default mode is 0666 (octal). The current
umask value is first masked out from the mode.
Availability: .
FIFOs are pipes that can be accessed like regular files. FIFOs exist
until they are deleted (for example with os.unlink()).
Generally, FIFOs are used as rendezvous between ``client'' and
``server'' type processes: the server opens the FIFO for reading, and
the client opens it for writing. Note that mkfifo()
doesn't open the FIFO --- it just creates the rendezvous point.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="mknod">
<description>Create a filesystem node (file, device special file or named pipe)
named filename. mode specifies both the permissions to use and
the type of node to be created, being combined (bitwise OR) with one
of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are
available in stat). For S_IFCHR and S_IFBLK, device
defines the newly created device special file (probably using
os.makedev()), otherwise it is ignored.
New in version 2.3</description>

<properties><property kind="parameter" name="path" required="1"/><property default="0600" kind="parameter" name="mode"/><property kind="parameter" name="device"/></properties></element>

<element kind="function" name="major">
<description>Extracts a device major number from a raw device number.
New in version 2.3</description>

<properties><property kind="parameter" name="devicedevice" required="1"/></properties></element>

<element kind="function" name="minor">
<description>Extracts a device minor number from a raw device number.
New in version 2.3</description>

<properties><property kind="parameter" name="devicedevice" required="1"/></properties></element>

<element kind="function" name="makedev">
<description>Composes a raw device number from the major and minor device numbers.
New in version 2.3</description>

<properties><property kind="parameter" name="major" required="1"/><property kind="parameter" name="minor minor" required="1"/></properties></element>

<element kind="function" name="mkdir">
<description>Create a directory named path with numeric mode mode.
The default mode is 0777 (octal). On some systems,
mode is ignored. Where it is used, the current umask value is
first masked out.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="makedirs">
<description>Recursive directory creation function.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="pathconf">
<description>Return system configuration information relevant to a named file.
name specifies the configuration value to retrieve; it may be a
string which is the name of a defined system value; these names are
specified in a number of standards (.1, 95, 98, and
others). Some platforms define additional names as well. The names
known to the host operating system are given in the
pathconf_names dictionary. For configuration variables not
included in that mapping, passing an integer for name is also
accepted.
Availability: .
If name is a string and is not known, ValueError is
raised. If a specific value for name is not supported by the
host system, even if it is included in pathconf_names, an
OSError is raised with errno.EINVAL for the
error number.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="readlink">
<description>Return a string representing the path to which the symbolic link
points. The result may be either an absolute or relative pathname; if
it is relative, it may be converted to an absolute pathname using
os.path.join(os.path.dirname(path), result).
Availability: .</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="remove">
<description>Remove the file path. If path is a directory,
OSError is raised; see rmdir() below to remove
a directory. This is identical to the unlink() function
documented below. On Windows, attempting to remove a file that is in
use causes an exception to be raised; on , the directory entry is
removed but the storage allocated to the file is not made available
until the original file is no longer in use.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="removedirs">
<description/>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="rename">
<description>Rename the file or directory src to dst. If dst is
a directory, OSError will be raised. On , if
dst exists and is a file, it will be removed silently if the
user has permission. The operation may fail on some flavors
if src and dst are on different filesystems. If
successful, the renaming will be an atomic operation (this is a
requirement). On Windows, if dst already exists,
OSError will be raised even if it is a file; there may be
no way to implement an atomic rename when dst names an existing
file.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="renames">
<description>Recursive directory or file renaming function.
Works like rename(), except creation of any intermediate
directories needed to make the new pathname good is attempted first.
After the rename, directories corresponding to rightmost path segments
of the old name will be pruned away using removedirs().
Note: this function can fail with the new directory structure made if
you lack permissions needed to remove the leaf directory or file.
New in version 1.5.2</description>

<properties><property kind="parameter" name="old" required="1"/><property kind="parameter" name="new new" required="1"/></properties></element>

<element kind="function" name="rmdir">
<description>Remove the directory path.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="stat">
<description>Perform a stat() system call on the given path. The
return value is an object whose attributes correspond to the members of
the stat structure, namely:
st_mode (protection bits),
st_ino (inode number),
st_dev (device),
st_nlink (number of hard links),
st_uid (user ID of owner),
st_gid (group ID of owner),
st_size (size of file, in bytes),
st_atime (time of most recent access),
st_mtime (time of most recent content modification),
st_ctime
(time of most recent content modification or metadata change).
[If stat_float_times returns true, the time
values are floats, measuring seconds. Fractions of a second may be
reported if the system supports that. On Mac OS, the times are always
floats. See stat_float_times for further discussion. ]{2.3}
On some Unix systems (such as Linux), the following attributes may
also be available:
st_blocks (number of blocks allocated for file),
st_blksize (filesystem blocksize),
st_rdev (type of device if an inode device).
On Mac OS systems, the following attributes may also be available:
st_rsize,
st_creator,
st_type.
On RISCOS systems, the following attributes are also available:
st_ftype (file type),
st_attrs (attributes),
st_obtype (object type).
For backward compatibility, the return value of stat() is
also accessible as a tuple of at least 10 integers giving the most
important (and portable) members of the stat structure, in the
order
st_mode,
st_ino,
st_dev,
st_nlink,
st_uid,
st_gid,
st_size,
st_atime,
st_mtime,
st_ctime.
More items may be added at the end by some implementations.
The standard module statstat defines
functions and constants that are useful for extracting information
from a stat structure.
(On Windows, some items are filled with dummy values.)
Availability: Macintosh, , Windows.
[Added access to values as attributes of the returned object]{2.2}</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="stat_float_times">
<description>Determine whether stat_result represents time stamps as float
objects. If newval is True, future calls to stat() return floats, if
it is False, future calls return ints. If newval is omitted, return
the current setting.
For compatibility with older Python versions, accessing
stat_result as a tuple always returns integers. For
compatibility with Python 2.2, accessing the time stamps by field name
also returns integers. Applications that want to determine the
fractions of a second in a time stamp can use this function to have
time stamps represented as floats. Whether they will actually observe
non-zero fractions depends on the system.
Future Python releases will change the default of this setting;
applications that cannot deal with floating point time stamps can then
use this function to turn the feature off.
It is recommended that this setting is only changed at program startup
time in the __main__ module; libraries should never change this
setting. If an application uses a library that works incorrectly if
floating point time stamps are processed, this application should turn
the feature off until the library has been corrected.</description>

<properties><property kind="parameter" name="newvalue" required="1"/></properties></element>

<element kind="function" name="statvfs">
<description>Perform a statvfs() system call on the given path. The
return value is an object whose attributes describe the filesystem on
the given path, and correspond to the members of the
statvfs structure, namely:
f_frsize,
f_blocks,
f_bfree,
f_bavail,
f_files,
f_ffree,
f_favail,
f_flag,
f_namemax.
Availability: .
For backward compatibility, the return value is also accessible as a
tuple whose values correspond to the attributes, in the order given above.
The standard module statvfsstatvfs
defines constants that are useful for extracting information
from a statvfs structure when accessing it as a sequence; this
remains useful when writing code that needs to work with versions of
Python that don't support accessing the fields as attributes.
[Added access to values as attributes of the returned object]{2.2}</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="symlink">
<description>Create a symbolic link pointing to src named dst.
Availability: .</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="tempnam">
<description>Return a unique path name that is reasonable for creating a temporary
file. This will be an absolute path that names a potential directory
entry in the directory dir or a common location for temporary
files if dir is omitted or None. If given and not
None, prefix is used to provide a short prefix to the
filename. Applications are responsible for properly creating and
managing files created using paths returned by tempnam();
no automatic cleanup is provided.
On , the environment variable TMPDIR overrides
dir, while on Windows the TMP is used. The specific
behavior of this function depends on the C library implementation;
some aspects are underspecified in system documentation.
Use of tempnam() is vulnerable to symlink attacks;
consider using tmpfile() instead.
Availability: , Windows.</description>

<properties><property kind="parameter" name="dir" required="1"/><property kind="parameter" name="prefix"/></properties></element>

<element kind="function" name="tmpnam">
<description>Return a unique path name that is reasonable for creating a temporary
file. This will be an absolute path that names a potential directory
entry in a common location for temporary files. Applications are
responsible for properly creating and managing files created using
paths returned by tmpnam(); no automatic cleanup is
provided.
Use of tmpnam() is vulnerable to symlink attacks;
consider using tmpfile() instead.
Availability: , Windows. This function probably shouldn't be used
on Windows, though: Microsoft's implementation of tmpnam()
always creates a name in the root directory of the current drive, and
that's generally a poor location for a temp file (depending on
privileges, you may not even be able to open a file using this name).</description>

</element>

<element kind="function" name="unlink">
<description>Remove the file path. This is the same function as
remove(); the unlink() name is its traditional
name.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="utime">
<description>Set the access and modified times of the file specified by path.
If times is None, then the file's access and modified
times are set to the current time. Otherwise, times must be a
2-tuple of numbers, of the form (atime, mtime)
which is used to set the access and modified times, respectively.
Changed in version 2.0: Added support for None for times
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="times times" required="1"/></properties></element>

<element kind="function" name="walk">
<description/>

<properties><property kind="parameter" name="top" required="1"/><property default="True" kind="parameter" name="topdown"/><property default="None" kind="parameter" name="onerror"/></properties></element>

</group>
<group name="Process Management">
<description>These functions may be used to create and manage processes.
The various exec*() functions take a list of arguments for
the new program loaded into the process. In each case, the first of
these arguments is passed to the new program as its own name rather
than as an argument a user may have typed on a command line. For the
C programmer, this is the argv[0] passed to a program's
main(). For example, os.execv('/bin/echo', ['foo',
'bar']) will only print bar on standard output; foo
will seem to be ignored.
</description>
<element kind="function" name="abort">
<description>Generate a SIGABRT signal to the current process. On
, the default behavior is to produce a core dump; on Windows, the
process immediately returns an exit code of 3. Be aware that
programs which use signal.signal() to register a handler
for SIGABRT will behave differently.
Availability: , Windows.</description>

</element>

<element kind="function" name="execl">
<description>execle{path, arg0, arg1, , env}
execlp{file, arg0, arg1, }
execlpe{file, arg0, arg1, , env}
execv{path, args}
execve{path, args, env}
execvp{file, args}
execvpe{file, args, env}
These functions all execute a new program, replacing the current
process; they do not return. On , the new executable is loaded
into the current process, and will have the same process ID as the
caller. Errors will be reported as OSError exceptions.
The l and v variants of the
exec*() functions differ in how command-line arguments are
passed. The l variants are perhaps the easiest to work
with if the number of parameters is fixed when the code is written;
the individual parameters simply become additional parameters to the
execl*() functions. The v variants are good
when the number of parameters is variable, with the arguments being
passed in a list or tuple as the args parameter. In either
case, the arguments to the child process must start with the name of
the command being run.
The variants which include a p near the end
(execlp(), execlpe(), execvp(),
and execvpe()) will use the PATH environment
variable to locate the program file. When the environment is
being replaced (using one of the exec*e() variants,
discussed in the next paragraph), the
new environment is used as the source of the PATH variable.
The other variants, execl(), execle(),
execv(), and execve(), will not use the
PATH variable to locate the executable; path must
contain an appropriate absolute or relative path.
For execle(), execlpe(), execve(),
and execvpe() (note that these all end in e),
the env parameter must be a mapping which is used to define the
environment variables for the new process; the execl(),
execlp(), execv(), and execvp()
all cause the new process to inherit the environment of the current
process.
Availability: , Windows.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="arg0" required="1"/><property kind="parameter" name="arg1" required="1"/><property kind="parameter" name="moreargsmoreargs" required="1"/></properties></element>

<element kind="function" name="_exit">
<description>Exit to the system with status n, without calling cleanup
handlers, flushing stdio buffers, etc.
Availability: , Windows.
Note: the standard way to exit is sys.exit(n).
_exit() should normally only be used in the child process
after a fork().</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="fork">
<description>Fork a child process. Return 0 in the child, the child's
process id in the parent.
Availability: .</description>

</element>

<element kind="function" name="forkpty">
<description>Fork a child process, using a new pseudo-terminal as the child's
controlling terminal. Return a pair of (pid, fd),
where pid is 0 in the child, the new child's process id
in the parent, and fd is the file descriptor of the master end
of the pseudo-terminal. For a more portable approach, use the
pty module.
Availability: Some flavors of .</description>

</element>

<element kind="function" name="kill">
<description/>

<properties><property kind="parameter" name="pid" required="1"/><property kind="parameter" name="sig sig" required="1"/></properties></element>

<element kind="function" name="killpg">
<description/>

<properties><property kind="parameter" name="pgid" required="1"/><property kind="parameter" name="sig sig" required="1"/></properties></element>

<element kind="function" name="nice">
<description>Add increment to the process's ``niceness''. Return the new
niceness.
Availability: .</description>

<properties><property kind="parameter" name="incrementincrement" required="1"/></properties></element>

<element kind="function" name="plock">
<description>Lock program segments into memory. The value of op
(defined in &lt;sys/lock.h&gt;) determines which segments are locked.
Availability: .</description>

<properties><property kind="parameter" name="opop" required="1"/></properties></element>

<element kind="function" name="spawnl">
<description>spawnle{mode, path, , env}
spawnlp{mode, file, }
spawnlpe{mode, file, , env}
spawnv{mode, path, args}
spawnve{mode, path, args, env}
spawnvp{mode, file, args}
spawnvpe{mode, file, args, env}
Execute the program path in a new process. If mode is
P_NOWAIT, this function returns the process ID of the new
process; if mode is P_WAIT, returns the process's
exit code if it exits normally, or -signal, where
signal is the signal that killed the process. On Windows, the
process ID will actually be the process handle, so can be used with
the waitpid() function.
The l and v variants of the
spawn*() functions differ in how command-line arguments are
passed. The l variants are perhaps the easiest to work
with if the number of parameters is fixed when the code is written;
the individual parameters simply become additional parameters to the
spawnl*() functions. The v variants are good
when the number of parameters is variable, with the arguments being
passed in a list or tuple as the args parameter. In either
case, the arguments to the child process must start with the name of
the command being run.
The variants which include a second p near the end
(spawnlp(), spawnlpe(), spawnvp(),
and spawnvpe()) will use the PATH environment
variable to locate the program file. When the environment is
being replaced (using one of the spawn*e() variants,
discussed in the next paragraph), the new environment is used as the
source of the PATH variable. The other variants,
spawnl(), spawnle(), spawnv(), and
spawnve(), will not use the PATH variable to
locate the executable; path must contain an appropriate absolute
or relative path.
For spawnle(), spawnlpe(), spawnve(),
and spawnvpe() (note that these all end in e),
the env parameter must be a mapping which is used to define the
environment variables for the new process; the spawnl(),
spawnlp(), spawnv(), and spawnvp()
all cause the new process to inherit the environment of the current
process.
As an example, the following calls to spawnlp() and
spawnvpe() are equivalent:
import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
Availability: , Windows. spawnlp(),
spawnlpe(), spawnvp() and spawnvpe()
are not available on Windows.
New in version 1.6</description>

<properties><property kind="parameter" name="mode" required="1"/><property kind="parameter" name="path" required="1"/><property kind="parameter" name="moreargsmoreargs" required="1"/></properties></element>

<element kind="function" name="startfile">
<description>Start a file with its associated application. This acts like
double-clicking the file in Windows Explorer, or giving the file name
as an argument to the start command from the interactive
command shell: the file is opened with whatever application (if any)
its extension is associated.
startfile() returns as soon as the associated application
is launched. There is no option to wait for the application to close,
and no way to retrieve the application's exit status. The path
parameter is relative to the current directory. If you want to use an
absolute path, make sure the first character is not a slash
(/); the underlying Win32 ShellExecute()
function doesn't work if it is. Use the os.path.normpath()
function to ensure that the path is properly encoded for Win32.
Availability: Windows.
New in version 2.0</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="system">
<description>Execute the command (a string) in a subshell. This is implemented by
calling the Standard C function system(), and has the
same limitations. Changes to posix.environ, sys.stdin,
etc. not reflected in the environment of the executed command.
On , the return value is the exit status of the process encoded in the
format specified for wait(). Note that does not
specify the meaning of the return value of the C system()
function, so the return value of the Python function is system-dependent.
On Windows, the return value is that returned by the system shell after
running command, given by the Windows environment variable
COMSPEC: on command.com systems (Windows 95, 98 and ME)
this is always 0; on cmd.exe systems (Windows NT, 2000
and XP) this is the exit status of the command run; on systems using
a non-native shell, consult your shell documentation.
Availability: , Windows.</description>

<properties><property kind="parameter" name="commandcommand" required="1"/></properties></element>

<element kind="function" name="times">
<description>Return a 5-tuple of floating point numbers indicating accumulated
(processor or other)
times, in seconds. The items are: user time, system time, children's
user time, children's system time, and elapsed real time since a fixed
point in the past, in that order. See the manual page
times{2} or the corresponding Windows Platform API
documentation.
Availability: , Windows.</description>

</element>

<element kind="function" name="wait">
<description>Wait for completion of a child process, and return a tuple containing
its pid and exit status indication: a 16-bit number, whose low byte is
the signal number that killed the process, and whose high byte is the
exit status (if the signal number is zero); the high bit of the low
byte is set if a core file was produced.
Availability: .</description>

</element>

<element kind="function" name="waitpid">
<description>The details of this function differ on and Windows.
On :
Wait for completion of a child process given by process id pid,
and return a tuple containing its process id and exit status
indication (encoded as for wait()). The semantics of the
call are affected by the value of the integer options, which
should be 0 for normal operation.
If pid is greater than 0, waitpid() requests
status information for that specific process. If pid is
0, the request is for the status of any child in the process
group of the current process. If pid is -1, the request
pertains to any child of the current process. If pid is less
than -1, status is requested for any process in the process
group -pid (the absolute value of pid).
On Windows:
Wait for completion of a process given by process handle pid,
and return a tuple containing pid,
and its exit status shifted left by 8 bits (shifting makes cross-platform
use of the function easier).
A pid less than or equal to 0 has no special meaning on
Windows, and raises an exception.
The value of integer options has no effect.
pid can refer to any process whose id is known, not necessarily a
child process.
The spawn() functions called with P_NOWAIT
return suitable process handles.</description>

<properties><property kind="parameter" name="pid" required="1"/><property kind="parameter" name="options options" required="1"/></properties></element>

<element kind="function" name="WCOREDUMP">
<description>Returns True if a core dump was generated for the process,
otherwise it returns False.
Availability: .
New in version 2.3</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WIFCONTINUED">
<description>Returns True if the process has been continued from a job
control stop, otherwise it returns False.
Availability: .
New in version 2.3</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WIFSTOPPED">
<description>Returns True if the process has been stopped, otherwise it
returns False.
Availability: .</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WIFSIGNALED">
<description>Returns True if the process exited due to a signal, otherwise
it returns False.
Availability: .</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WIFEXITED">
<description>Returns True if the process exited using the exit{2}
system call, otherwise it returns False.
Availability: .</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WEXITSTATUS">
<description>If WIFEXITED(status) is true, return the integer
parameter to the exit{2} system call. Otherwise, the return
value is meaningless.
Availability: .</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WSTOPSIG">
<description>Return the signal which caused the process to stop.
Availability: .</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="WTERMSIG">
<description>Return the signal which caused the process to exit.
Availability: .</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

</group>
<group name="Miscellaneous System Information">
<element kind="function" name="confstr">
<description>Return string-valued system configuration values.
name specifies the configuration value to retrieve; it may be a
string which is the name of a defined system value; these names are
specified in a number of standards (, 95, 98, and
others). Some platforms define additional names as well. The names
known to the host operating system are given in the
confstr_names dictionary. For configuration variables not
included in that mapping, passing an integer for name is also
accepted.
Availability: .
If the configuration value specified by name isn't defined, the
empty string is returned.
If name is a string and is not known, ValueError is
raised. If a specific value for name is not supported by the
host system, even if it is included in confstr_names, an
OSError is raised with errno.EINVAL for the
error number.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getloadavg">
<description>Return the number of processes in the system run queue averaged over
the last 1, 5, and 15 minutes or raises OSError if the load average
was unobtainable.
New in version 2.3</description>

</element>

<element kind="function" name="sysconf">
<description>Return integer-valued system configuration values.
If the configuration value specified by name isn't defined,
-1 is returned. The comments regarding the name
parameter for confstr() apply here as well; the dictionary
that provides information on the known names is given by
sysconf_names.
Availability: .</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
</group>
<group name="os.path --- Common pathname manipulations">
<description>Common pathname manipulations.
This module implements some useful functions on pathnames.
</description>
<element kind="function" name="abspath">
<description>Return a normalized absolutized version of the pathname path.
On most platforms, this is equivalent to
normpath(join(os.getcwd(), path)).
New in version 1.5.2</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="basename">
<description>Return the base name of pathname path. This is the second half
of the pair returned by split(path). Note that the
result of this function is different from the
basename program; where basename for
'/foo/bar/' returns 'bar', the basename()
function returns an empty string ('').</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="commonprefix">
<description>Return the longest path prefix (taken character-by-character) that is a
prefix of all paths in list. If list is empty, return the empty string
(''). Note that this may return invalid paths because it works a
character at a time.</description>

<properties><property kind="parameter" name="listlist" required="1"/></properties></element>

<element kind="function" name="dirname">
<description>Return the directory name of pathname path. This is the first
half of the pair returned by split(path).</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="exists">
<description>Return True if path refers to an existing path.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="expanduser">
<description>Return the argument with an initial component of ~ or
~user replaced by that user's home directory. An
initial } is replaced by the environment variable
HOME; an initial ~user is looked up in the
password directory through the built-in module
pwdpwd. If the expansion fails, or if the
path does not begin with a tilde, the path is returned unchanged. On
the Macintosh, this always returns path unchanged.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="expandvars">
<description>Return the argument with environment variables expanded. Substrings
of the form $name or {name} are
replaced by the value of environment variable name. Malformed
variable names and references to non-existing variables are left
unchanged. On the Macintosh, this always returns path
unchanged.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="getatime">
<description>Return the time of last access of path. The return
value is a number giving the number of seconds since the epoch (see the time module). Raise os.error if the file does
not exist or is inaccessible.
New in version 1.5.2
Changed in version 2.3: If os.stat_float_times() returns True, the result is a floating point number</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="getmtime">
<description>Return the time of last modification of path. The return
value is a number giving the number of seconds since the epoch (see the time module). Raise os.error if the file does
not exist or is inaccessible.
New in version 1.5.2
Changed in version 2.3: If os.stat_float_times() returns True, the result is a floating point number</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="getctime">
<description>Return the system's ctime which, on some systems (like ) is the
time of the last change, and, on others (like Windows), is the
creation time for path. The return
value is a number giving the number of seconds since the epoch (see the time module). Raise os.error if the file does
not exist or is inaccessible.
New in version 2.3</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="getsize">
<description>Return the size, in bytes, of path. Raise
os.error if the file does not exist or is inaccessible.
New in version 1.5.2</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="isabs">
<description>Return True if path is an absolute pathname (begins with a
slash).</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="isfile">
<description>Return True if path is an existing regular file. This follows
symbolic links, so both islink() and isfile()
can be true for the same path.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="isdir">
<description>Return True if path is an existing directory. This follows
symbolic links, so both islink() and isdir() can
be true for the same path.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="islink">
<description>Return True if path refers to a directory entry that is a
symbolic link. Always False if symbolic links are not supported.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="ismount">
<description>Return True if pathname path is a mount point: a point in
a file system where a different file system has been mounted. The
function checks whether path's parent, path/.., is
on a different device than path, or whether path/..
and path point to the same i-node on the same device --- this
should detect mount points for all and variants.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="join">
<description>Joins one or more path components intelligently. If any component is
an absolute path, all previous components are thrown away, and joining
continues. The return value is the concatenation of path1, and
optionally path2, etc., with exactly one directory separator
(os.sep) inserted between components, unless path2 is
empty. Note that on Windows, since there is a current directory for
each drive, os.path.join(&quot;c:&quot;, &quot;foo&quot;) represents a path
relative to the current directory on drive C: (c:foo), not
c: foo.</description>

<properties><property kind="parameter" name="path1" required="1"/><property kind="parameter" name="path2"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="normcase">
<description>Normalize the case of a pathname. On , this returns the path
unchanged; on case-insensitive filesystems, it converts the path to
lowercase. On Windows, it also converts forward slashes to backward
slashes.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="normpath">
<description>Normalize a pathname. This collapses redundant separators and
up-level references, e.g. A//B, A/./B and
A/foo/../B all become A/B. It does not normalize the
case (use normcase() for that). On Windows, it converts
forward slashes to backward slashes.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="realpath">
<description>Return the canonical path of the specified filename, eliminating any
symbolic links encountered in the path.
Availability: .
New in version 2.2</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="samefile">
<description>Return True if both pathname arguments refer to the same file or
directory (as indicated by device number and i-node number).
Raise an exception if a os.stat() call on either pathname
fails.
Availability: Macintosh, .</description>

<properties><property kind="parameter" name="path1" required="1"/><property kind="parameter" name="path2 path2" required="1"/></properties></element>

<element kind="function" name="sameopenfile">
<description>Return True if the file objects fp1 and fp2 refer to the
same file. The two file objects may represent different file
descriptors.
Availability: Macintosh, .</description>

<properties><property kind="parameter" name="fp1" required="1"/><property kind="parameter" name="fp2 fp2" required="1"/></properties></element>

<element kind="function" name="samestat">
<description>Return True if the stat tuples stat1 and stat2 refer to
the same file. These structures may have been returned by
fstat(), lstat(), or stat(). This
function implements the underlying comparison used by
samefile() and sameopenfile().
Availability: Macintosh, .</description>

<properties><property kind="parameter" name="stat1" required="1"/><property kind="parameter" name="stat2 stat2" required="1"/></properties></element>

<element kind="function" name="split">
<description>Split the pathname path into a pair, (head,
tail) where tail is the last pathname component and
head is everything leading up to that. The tail part will
never contain a slash; if path ends in a slash, tail will
be empty. If there is no slash in path, head will be
empty. If path is empty, both head and tail are
empty. Trailing slashes are stripped from head unless it is the
root (one or more slashes only). In nearly all cases,
join(head, tail) equals path (the only
exception being when there were multiple slashes separating head
from tail).</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="splitdrive">
<description>Split the pathname path into a pair (drive,
tail) where drive is either a drive specification or the
empty string. On systems which do not use drive specifications,
drive will always be the empty string. In all cases,
drive + tail will be the same as path.
New in version 1.3</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="splitext">
<description>Split the pathname path into a pair (root, ext) such that root + ext == path,
and ext is empty or begins with a period and contains
at most one period.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="walk">
<description>Calls the function visit with arguments
(arg, dirname, names) for each directory in the
directory tree rooted at path (including path itself, if it
is a directory). The argument dirname specifies the visited
directory, the argument names lists the files in the directory
(gotten from os.listdir(dirname)).
The visit function may modify names to
influence the set of directories visited below dirname, e.g., to
avoid visiting certain parts of the tree. (The object referred to by
names must be modified in place, using del or slice
assignment.)
Symbolic links to directories are not treated as subdirectories, and
that walk() therefore will not visit them. To visit linked
directories you must identify them with
os.path.islink(file) and
os.path.isdir(file), and invoke walk() as
necessary.
The newer os.walk() generator supplies
similar functionality and can be easier to use.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="visit" required="1"/><property kind="parameter" name="arg arg" required="1"/></properties></element>

</group>
<group name="dircache --- Cached directory listings">
<description>Return directory listing, with cache mechanism.
The dircache module defines a function for reading directory listing
using a cache, and cache invalidation using the mtime of the directory.
Additionally, it defines a function to annotate directories by appending
a slash.
The dircache module defines the following functions:
</description>
<element kind="function" name="listdir">
<description>Return a directory listing of path, as gotten from
os.listdir(). Note that unless path changes, further call
to listdir() will not re-read the directory structure.
Note that the list returned should be regarded as read-only. (Perhaps
a future version should change it to return a tuple?)</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="opendir">
<description>Same as listdir(). Defined for backwards compatibility.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="annotate">
<description>Assume list is a list of paths relative to head, and append,
in place, a / to each path which points to a directory.</description>

<properties><property kind="parameter" name="head" required="1"/><property kind="parameter" name="list list" required="1"/></properties></element>

</group>
<group name="stat --- Interpreting stat() results">
<description>Utilities for interpreting the results of
os.stat(), os.lstat() and os.fstat().
The stat module defines constants and functions for
interpreting the results of os.stat(),
os.fstat() and os.lstat() (if they exist). For
complete details about the stat(), fstat() and
lstat() calls, consult the documentation for your system.
The stat module defines the following functions to test for
specific file types:
</description>
<element kind="function" name="S_ISDIR">
<description>Return non-zero if the mode is from a directory.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_ISCHR">
<description>Return non-zero if the mode is from a character special device file.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_ISBLK">
<description>Return non-zero if the mode is from a block special device file.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_ISREG">
<description>Return non-zero if the mode is from a regular file.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_ISFIFO">
<description>Return non-zero if the mode is from a FIFO (named pipe).</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_ISLNK">
<description>Return non-zero if the mode is from a symbolic link.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_ISSOCK">
<description>Return non-zero if the mode is from a socket.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_IMODE">
<description>Return the portion of the file's mode that can be set by
os.chmod()---that is, the file's permission bits, plus the
sticky bit, set-group-id, and set-user-id bits (on systems that support
them).</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<element kind="function" name="S_IFMT">
<description>Return the portion of the file's mode that describes the file type (used
by the S_IS*() functions above).</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

</group>
<group name="statcache --- An optimization of os.stat()">
<description>Stat files, and remember results.
2.2{Use os.stat() directly instead
of using the cache; the cache introduces a very high level of
fragility in applications using it and complicates application code
with the addition of cache management support.}
The statcache module provides a simple optimization to
os.stat(): remembering the values of previous invocations.
The statcache module defines the following functions:
</description>
<element kind="function" name="stat">
<description>This is the main module entry-point.
Identical for os.stat(), except for remembering the result
for future invocations of the function.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="reset">
<description>Clear the cache: forget all results of previous stat()
calls.</description>

</element>

<element kind="function" name="forget">
<description>Forget the result of stat(path), if any.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="forget_prefix">
<description>Forget all results of stat(path) for path starting
with prefix.</description>

<properties><property kind="parameter" name="prefixprefix" required="1"/></properties></element>

<element kind="function" name="forget_dir">
<description>Forget all results of stat(path) for path a file in the directory prefix, including stat(prefix).</description>

<properties><property kind="parameter" name="prefixprefix" required="1"/></properties></element>

<element kind="function" name="forget_except_prefix">
<description>Similar to forget_prefix(), but for all path values
not starting with prefix.</description>

<properties><property kind="parameter" name="prefixprefix" required="1"/></properties></element>

</group>
<group name="statvfs --- Constants used with os.statvfs()">
</group>
<group name="filecmp --- File and Directory Comparisons">
<description>Compare files efficiently.
The filecmp module defines functions to compare files and
directories, with various optional time/correctness trade-offs.
The filecmp module defines the following functions:
</description>
<element kind="function" name="cmp">
<description>Compare the files named f1 and f2, returning True if
they seem equal, False otherwise.
Unless shallow is given and is false, files with identical
os.stat() signatures are taken to be equal.
Changed in version 2.3: use_statcache is obsolete and ignored.
Files that were compared using this function will not be compared again
unless their os.stat() signature changes.
Note that no external programs are called from this function, giving it
portability and efficiency.</description>

<properties><property kind="parameter" name="f1" required="1"/><property kind="parameter" name="f2" required="1"/><property kind="parameter" name="shallow"/><property kind="parameter" name="use_statcache"/></properties></element>

<element kind="function" name="cmpfiles">
<description>Returns three lists of file names: match, mismatch,
errors. match contains the list of files match in both
directories, mismatch includes the names of those that don't,
and errros lists the names of files which could not be
compared. Files may be listed in errors because the user may
lack permission to read them or many other reasons, but always that
the comparison could not be done for some reason.
The common parameter is a list of file names found in both directories.
The shallow and use_statcache parameters have the same
meanings and default values as for filecmp.cmp().</description>

<properties><property kind="parameter" name="dir1" required="1"/><property kind="parameter" name="dir2" required="1"/><property kind="parameter" name="common" required="1"/><property kind="parameter" name="shallow"/><property kind="parameter" name="use_statcache"/></properties></element>

<group name="The dircmp class">
<description>dircmp instances are built using this constructor:
</description>
<element kind="function" name="dircmp">
<description>Construct a new directory comparison object, to compare the
directories a and b. ignore is a list of names to
ignore, and defaults to ['RCS', 'CVS', 'tags']. hide is a
list of names to hide, and defaults to [os.curdir, os.pardir].</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b" required="1"/><property kind="parameter" name="ignore"/><property kind="parameter" name="hide"/></properties></element>

<element kind="function" name="report">
<description>Print (to sys.stdout) a comparison between a and b.</description>

</element>

<element kind="function" name="report_partial_closure">
<description>Print a comparison between a and b and common immediate
subdirctories.</description>

</element>

<element kind="function" name="report_full_closure">
<description>Print a comparison between a and b and common subdirctories (recursively).</description>

</element>

</group>
</group>
<group name="popen2 --- Subprocesses with accessible I/O streams">
<description>Unix, Windows
Subprocesses with accessible standard I/O streams.
This module allows you to spawn processes and connect to their
input/output/error pipes and obtain their return codes under
and Windows.
Note that starting with Python 2.0, this functionality is available
using functions from the os module which have the same
names as the factory functions here, but the order of the return
values is more intuitive in the os module variants.
The primary interface offered by this module is a trio of factory
functions. For each of these, if bufsize is specified, it specifies the buffer size for the I/O pipes. mode, if
provided, should be the string 'b' or 't'; on Windows
this is needed to determine whether the file objects should be opened
in binary or text mode. The default value for mode is
't'.
The only way to retrieve the return codes for the child processes is
by using the poll() or wait() methods on the
Popen3 and Popen4 classes; these are only available on
. This information is not available when using the
popen2(), popen3(), and popen4()
functions, or the equivalent functions in the os module.
</description>
<element kind="function" name="popen2">
<description>Executes cmd as a sub-process. Returns the file objects
(child_stdout, child_stdin).</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="bufsize"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="popen3">
<description>Executes cmd as a sub-process. Returns the file objects
(child_stdout, child_stdin, child_stderr).</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="bufsize"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="popen4">
<description>Executes cmd as a sub-process. Returns the file objects
(child_stdout_and_stderr, child_stdin).
New in version 2.0</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="bufsize"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="Popen3">
<description>This class represents a child process. Normally, Popen3
instances are created using the popen2() and
popen3() factory functions described above.
If not using one of the helper functions to create Popen3
objects, the parameter cmd is the shell command to execute in a
sub-process. The capturestderr flag, if true, specifies that
the object should capture standard error output of the child process.
The default is false. If the bufsize parameter is specified, it
specifies the size of the I/O buffers to/from the child process.</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="capturestderr"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="Popen4">
<description>Similar to Popen3, but always captures standard error into the
same file object as standard output. These are typically created
using popen4().
New in version 2.0</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="bufsize"/></properties></element>

<group name="Popen3 and Popen4 Objects">
<description>Instances of the Popen3 and Popen4 classes have the
following methods:
</description>
<element kind="function" name="poll">
<description>Returns -1 if child process hasn't completed yet, or its return code otherwise.</description>

</element>

<element kind="function" name="wait">
<description>Waits for and returns the status code of the child process. The
status code encodes both the return code of the process and
information about whether it exited using the exit()
system call or died due to a signal. Functions to help interpret the
status code are defined in the os module; see section
os-process for the W*() family of functions.</description>

</element>

</group>
<group name="Flow Control Issues">
</group>
</group>
<group name="datetime --- Basic date and time types">
<description>Basic date and time types.
New in version 2.3
The datetime module supplies classes for manipulating dates
and times in both simple and complex ways. While date and time
arithmetic is supported, the focus of the implementation is on
efficient member extraction for output formatting and manipulation.
There are two kinds of date and time objects: ``naive'' and ``aware''.
This distinction refers to whether the object has any notion of time
zone, daylight saving time, or other kind of algorithmic or political
time adjustment. Whether a naive datetime object represents
Coordinated Universal Time (UTC), local time, or time in some other
timezone is purely up to the program, just like it's up to the program
whether a particular number represents meters, miles, or mass. Naive
datetime objects are easy to understand and to work with, at
the cost of ignoring some aspects of reality.
For applications requiring more, datetime and time
objects have an optional time zone information member,
tzinfo, that can contain an instance of a subclass of
the abstract tzinfo class. These tzinfo objects
capture information about the offset from UTC time, the time zone
name, and whether Daylight Saving Time is in effect. Note that no
concrete tzinfo classes are supplied by the datetime
module. Supporting timezones at whatever level of detail is required
is up to the application. The rules for time adjustment across the
world are more political than rational, and there is no standard
suitable for every application.
The datetime module exports the following constants:
{MINYEAR}
The smallest year number allowed in a date or
datetime object. MINYEAR
is 1.
{MAXYEAR}
The largest year number allowed in a date or datetime
object. MAXYEAR is 9999.
calendar{General calendar related functions.}
time{Time access and conversions.}
</description>
<group name="Available Types">
<description>{date}
An idealized naive date, assuming the current Gregorian calendar
always was, and always will be, in effect.
Attributes: year, month, and day.
{time}
An idealized time, independent of any particular day, assuming
that every day has exactly 24*60*60 seconds (there is no notion
of &quot;leap seconds&quot; here).
Attributes: hour, minute, second,
microsecond, and tzinfo.
{datetime}
A combination of a date and a time.
Attributes: year, month, day,
hour, minute, second,
microsecond, and tzinfo.
{timedelta}
A duration expressing the difference between two date,
time, or datetime instances to microsecond
resolution.
{tzinfo}
An abstract base class for time zone information objects. These
are used by the datetime and time classes to
provide a customizable notion of time adjustment (for example, to
account for time zone and/or daylight saving time).
Objects of these types are immutable.
Objects of the date type are always naive.
An object d of type time or datetime may be
naive or aware. d is aware if d.tzinfo is not
None and d.tzinfo.utcoffset(d) does not return
None. If d.tzinfo is None, or if
d.tzinfo is not None but
d.tzinfo.utcoffset(d) returns None, d
is naive.
The distinction between naive and aware doesn't apply to
timedelta objects.
Subclass relationships:
object
timedelta
tzinfo
time
date
datetime
</description>
</group>
<group name="timedelta Objects">
<description>A timedelta object represents a duration, the difference
between two dates or times.
</description>
<element kind="function" name="timedelta">
<description>All arguments are optional. Arguments may be ints, longs, or floats,
and may be positive or negative.
Only days, seconds and microseconds are stored
internally. Arguments are converted to those units:
A millisecond is converted to 1000 microseconds.
A minute is converted to 60 seconds.
An hour is converted to 3600 seconds.
A week is converted to 7 days.
and days, seconds and microseconds are then normalized so that the
representation is unique, with
0 &lt;= microseconds &lt; 1000000
0 &lt;= seconds &lt; 3600*24 (the number of seconds in one day)
-999999999 &lt;= days &lt;= 999999999
If any argument is a float and there are fractional microseconds,
the fractional microseconds left over from all arguments are combined
and their sum is rounded to the nearest microsecond. If no
argument is a float, the conversion and normalization processes
are exact (no information is lost).
If the normalized value of days lies outside the indicated range,
OverflowError is raised.
Note that normalization of negative values may be surprising at first.
For example,
&gt;&gt;&gt; d = timedelta(microseconds=-1)
&gt;&gt;&gt; (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
</description>

<properties><property default="0" kind="parameter" name="days" required="1"/><property default="0" kind="parameter" name="seconds" required="1"/><property default="0" kind="parameter" name="microseconds" required="1"/><property default="0" kind="parameter" name="milliseconds" required="1"/><property default="0" kind="parameter" name="minutes" required="1"/><property default="0" kind="parameter" name="hours" required="1"/><property default="0 weeks=0" kind="parameter" name="weeks" required="1"/></properties></element>

</group>
<group name="date Objects">
<description>A date object represents a date (year, month and day) in an idealized
calendar, the current Gregorian calendar indefinitely extended in both
directions. January 1 of year 1 is called day number 1, January 2 of year
1 is called day number 2, and so on. This matches the definition of the
&quot;proleptic Gregorian&quot; calendar in Dershowitz and Reingold's book
Calendrical Calculations, where it's the base calendar for all
computations. See the book for algorithms for converting between
proleptic Gregorian ordinals and many other calendar systems.
</description>
<element kind="function" name="date">
<description>All arguments are required. Arguments may be ints or longs, in the
following ranges:
MINYEAR &lt;= year &lt;= MAXYEAR
1 &lt;= month &lt;= 12
1 &lt;= day &lt;= number of days in the given month and year
If an argument outside those ranges is given, ValueError
is raised.</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month" required="1"/><property kind="parameter" name="day day" required="1"/></properties></element>

<element kind="function" name="today">
<description>Return the current local date. This is equivalent to
date.fromtimestamp(time.time()).</description>

</element>

<element kind="function" name="fromtimestamp">
<description>Return the local date corresponding to the POSIX timestamp, such
as is returned by time.time(). This may raise
ValueError, if the timestamp is out of the range of
values supported by the platform C localtime()
function. It's common for this to be restricted to years from 1970
through 2038. Note that on non-POSIX systems that include leap
seconds in their notion of a timestamp, leap seconds are ignored by
fromtimestamp().</description>

<properties><property kind="parameter" name="timestamptimestamp" required="1"/></properties></element>

<element kind="function" name="fromordinal">
<description>Return the date corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. ValueError is
raised unless 1 &lt;= ordinal &lt;= date.max.toordinal().
For any date d, date.fromordinal(d.toordinal()) ==
d.</description>

<properties><property kind="parameter" name="ordinalordinal" required="1"/></properties></element>

<element kind="function" name="replace">
<description>Return a date with the same value, except for those members given
new values by whichever keyword arguments are specified. For
example, if d == date(2002, 12, 31), then
d.replace(day=26) == date(2000, 12, 26).</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month" required="1"/><property kind="parameter" name="day day" required="1"/></properties></element>

<element kind="function" name="timetuple">
<description>Return a time.struct_time such as returned by
time.localtime(). The hours, minutes and seconds are
0, and the DST flag is -1.
d.timetuple() is equivalent to
time.struct_time((d.year, d.month, d.day,
0, 0, 0, d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1,
-1))</description>

</element>

<element kind="function" name="toordinal">
<description>Return the proleptic Gregorian ordinal of the date, where January 1
of year 1 has ordinal 1. For any date object d,
date.fromordinal(d.toordinal()) == d.</description>

</element>

<element kind="function" name="weekday">
<description>Return the day of the week as an integer, where Monday is 0 and
Sunday is 6. For example, date(2002, 12, 4).weekday() == 2, a
Wednesday.
See also isoweekday().</description>

</element>

<element kind="function" name="isoweekday">
<description>Return the day of the week as an integer, where Monday is 1 and
Sunday is 7. For example, date(2002, 12, 4).isoweekday() == 3, a
Wednesday.
See also weekday(), isocalendar().</description>

</element>

<element kind="function" name="isocalendar">
<description>Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
The ISO calendar is a widely used variant of the Gregorian calendar.
See http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm
for a good explanation.
The ISO year consists of 52 or 53 full weeks, and where a week starts
on a Monday and ends on a Sunday. The first week of an ISO year is
the first (Gregorian) calendar week of a year containing a Thursday.
This is called week number 1, and the ISO year of that Thursday is
the same as its Gregorian year.
For example, 2004 begins on a Thursday, so the first week of ISO
year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
2004, so that
date(2003, 12, 29).isocalendar() == (2004, 1, 1)
and date(2004, 1, 4).isocalendar() == (2004, 1, 7).</description>

</element>

<element kind="function" name="isoformat">
<description>Return a string representing the date in ISO 8601 format,
'YYYY-MM-DD'. For example,
date(2002, 12, 4).isoformat() == '2002-12-04'.</description>

</element>

<element kind="function" name="__str__">
<description>For a date d, str(d) is equivalent to
d.isoformat().</description>

</element>

<element kind="function" name="ctime">
<description>Return a string representing the date, for example
date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'.
d.ctime() is equivalent to
time.ctime(time.mktime(d.timetuple()))
on platforms where the native C ctime() function
(which time.ctime() invokes, but which
date.ctime() does not invoke) conforms to the C standard.</description>

</element>

<element kind="function" name="strftime">
<description>Return a string representing the date, controlled by an explicit
format string. Format codes referring to hours, minutes or seconds
will see 0 values.
See the section on strftime() behavior.</description>

<properties><property kind="parameter" name="formatformat" required="1"/></properties></element>

</group>
<group name="datetime Objects">
<description>A datetime object is a single object containing all the
information from a date object and a time object. Like a
date object, datetime assumes the current Gregorian
calendar extended in both directions; like a time object,
datetime assumes there are exactly 3600*24 seconds in every
day.
Constructor:
</description>
<element kind="function" name="datetime">
<description>The year, month and day arguments are required. tzinfo may
be None, or an instance of a tzinfo subclass. The
remaining arguments may be ints or longs, in the following ranges:
MINYEAR &lt;= year &lt;= MAXYEAR
1 &lt;= month &lt;= 12
1 &lt;= day &lt;= number of days in the given month and year
0 &lt;= hour &lt; 24
0 &lt;= minute &lt; 60
0 &lt;= second &lt; 60
0 &lt;= microsecond &lt; 1000000
If an argument outside those ranges is given,
ValueError is raised.</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month" required="1"/><property kind="parameter" name="day" required="1"/><property default="0" kind="parameter" name="hour" required="1"/><property default="0" kind="parameter" name="minute" required="1"/><property default="0" kind="parameter" name="second" required="1"/><property default="0" kind="parameter" name="microsecond" required="1"/><property default="None                             tzinfo=None" kind="parameter" name="tzinfo" required="1"/></properties></element>

<element kind="function" name="today">
<description>Return the current local datetime, with tzinfo None.
This is equivalent to
datetime.fromtimestamp(time.time()).
See also now(), fromtimestamp().</description>

</element>

<element kind="function" name="now(tz=None)">
<description>Return the current local date and time. If optional argument
tz is None or not specified, this is like
today(), but, if possible, supplies more precision than can
be gotten from going through a time.time() timestamp (for
example, this may be possible on platforms supplying the C
gettimeofday() function).
Else tz must be an instance of a class tzinfo subclass,
and the current date and time are converted to tz's time
zone. In this case the result is equivalent to
tz.fromutc(datetime.utcnow().replace(tzinfo=tz)).
See also today(), utcnow().</description>

</element>

<element kind="function" name="utcnow">
<description>Return the current UTC date and time, with tzinfo None.
This is like now(), but returns the current UTC date and time,
as a naive datetime object.
See also now().</description>

</element>

<element kind="function" name="fromtimestamp">
<description>Return the local date and time corresponding to the timestamp, such as is returned by time.time().
If optional argument tz is None or not specified, the
timestamp is converted to the platform's local date and time, and
the returned datetime object is naive.
Else tz must be an instance of a class tzinfo subclass,
and the timestamp is converted to tz's time zone. In this case
the result is equivalent to
tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz)).
fromtimestamp() may raise ValueError, if the
timestamp is out of the range of values supported by the platform C
localtime() or gmtime() functions. It's common
for this to be restricted to years in 1970 through 2038.
Note that on non-POSIX systems that include leap seconds in their
notion of a timestamp, leap seconds are ignored by
fromtimestamp(), and then it's possible to have two timestamps
differing by a second that yield identical datetime objects.
See also utcfromtimestamp().</description>

<properties><property kind="parameter" name="timestamp" required="1"/><property default="None tz=None" kind="parameter" name="tz" required="1"/></properties></element>

<element kind="function" name="utcfromtimestamp">
<description>Return the UTC datetime corresponding to the timestamp, with tzinfo None.
This may raise ValueError, if the
timestamp is out of the range of values supported by the platform
C gmtime() function. It's common for this to be
restricted to years in 1970 through 2038.
See also fromtimestamp().</description>

<properties><property kind="parameter" name="timestamptimestamp" required="1"/></properties></element>

<element kind="function" name="fromordinal">
<description>Return the datetime corresponding to the proleptic
Gregorian ordinal, where January 1 of year 1 has ordinal 1.
ValueError is raised unless 1 &lt;= ordinal &lt;=
datetime.max.toordinal(). The hour, minute, second and
microsecond of the result are all 0,
and tzinfo is None.</description>

<properties><property kind="parameter" name="ordinalordinal" required="1"/></properties></element>

<element kind="function" name="combine">
<description>Return a new datetime object whose date members are
equal to the given date object's, and whose time
and tzinfo members are equal to the given time object's.
For any datetime object d, d ==
datetime.combine(d.date(), d.timetz()). If date is a
datetime object, its time and tzinfo members are
ignored.</description>

<properties><property kind="parameter" name="date" required="1"/><property kind="parameter" name="time time" required="1"/></properties></element>

<element kind="function" name="date">
<description>Return date object with same year, month and day.</description>

</element>

<element kind="function" name="time">
<description>Return time object with same hour, minute, second and microsecond.
tzinfo is None. See also method timetz().</description>

</element>

<element kind="function" name="timetz">
<description>Return time object with same hour, minute, second, microsecond,
and tzinfo members. See also method time().</description>

</element>

<element kind="function" name="replace">
<description>Return a datetime with the same members, except for those members given
new values by whichever keyword arguments are specified. Note that
tzinfo=None can be specified to create a naive datetime from
an aware datetime with no conversion of date and time members.</description>

<properties><property kind="parameter" name="year" required="1"/><property kind="parameter" name="month" required="1"/><property kind="parameter" name="day" required="1"/><property kind="parameter" name="hour" required="1"/><property kind="parameter" name="minute" required="1"/><property kind="parameter" name="second" required="1"/><property kind="parameter" name="microsecond" required="1"/><property default=" tzinfo=" kind="parameter" name="tzinfo" required="1"/></properties></element>

<element kind="function" name="astimezone">
<description>Return a datetime object with new tzinfo member
tz, adjusting the date and time members so the result is the
same UTC time as self, but in tz's local time.
tz must be an instance of a tzinfo subclass, and its
utcoffset() and dst() methods must not return
None. self must be aware (self.tzinfo must
not be None, and self.utcoffset() must not return
None).
If self.tzinfo is tz,
self.astimezone(tz) is equal to self: no
adjustment of date or time members is performed.
Else the result is local time in time zone tz, representing the
same UTC time as self: after astz =
dt.astimezone(tz),
astz - astz.utcoffset() will usually have the same
date and time members as dt - dt.utcoffset().
The discussion of class tzinfo explains the cases at Daylight
Saving Time transition boundaries where this cannot be achieved (an issue
only if tz models both standard and daylight time).
If you merely want to attach a time zone object tz to a
datetime dt without adjustment of date and time members,
use dt.replace(tzinfo=tz). If
you merely want to remove the time zone object from an aware datetime
dt without conversion of date and time members, use
dt.replace(tzinfo=None).
Note that the default tzinfo.fromutc() method can be overridden
in a tzinfo subclass to affect the result returned by
astimezone(). Ignoring error cases, astimezone()
acts like:
def astimezone(self, tz):
if self.tzinfo is tz:
return self
# Convert self to UTC, and attach the new time zone object.
utc = (self - self.utcoffset()).replace(tzinfo=tz)
# Convert from UTC to tz's local time.
return tz.fromutc(utc)
</description>

<properties><property kind="parameter" name="tztz" required="1"/></properties></element>

<element kind="function" name="utcoffset">
<description>If tzinfo is None, returns None, else
returns self.tzinfo.utcoffset(self), and
raises an exception if the latter doesn't return None, or
a timedelta object representing a whole number of minutes
with magnitude less than one day.</description>

</element>

<element kind="function" name="dst">
<description>If tzinfo is None, returns None, else
returns self.tzinfo.dst(self), and
raises an exception if the latter doesn't return None, or
a timedelta object representing a whole number of minutes
with magnitude less than one day.</description>

</element>

<element kind="function" name="tzname">
<description>If tzinfo is None, returns None, else
returns self.tzinfo.tzname(self),
raises an exception if the latter doesn't return None or
a string object,</description>

</element>

<element kind="function" name="timetuple">
<description>Return a time.struct_time such as returned by
time.localtime().
d.timetuple() is equivalent to
time.struct_time((d.year, d.month, d.day,
d.hour, d.minute, d.second,
d.weekday(),
d.toordinal() - date(d.year, 1, 1).toordinal() + 1,
dst))
The tm_isdst flag of the result is set according to
the dst() method: tzinfo is None or
dst() returns None,
tm_isdst is set to -1; else if dst() returns
a non-zero value, tm_isdst is set to 1;
else tm_isdst is set to 0.</description>

</element>

<element kind="function" name="utctimetuple">
<description>If datetime instance d is naive, this is the same as
d.timetuple() except that tm_isdst is forced to 0
regardless of what d.dst() returns. DST is never in effect
for a UTC time.
If d is aware, d is normalized to UTC time, by subtracting
d.utcoffset(), and a time.struct_time for the
normalized time is returned. tm_isdst is forced to 0.
Note that the result's tm_year member may be
MINYEAR-1 or MAXYEAR+1, if d.year was
MINYEAR or MAXYEAR and UTC adjustment spills over a
year boundary.</description>

</element>

<element kind="function" name="toordinal">
<description>Return the proleptic Gregorian ordinal of the date. The same as
self.date().toordinal().</description>

</element>

<element kind="function" name="weekday">
<description>Return the day of the week as an integer, where Monday is 0 and
Sunday is 6. The same as self.date().weekday().
See also isoweekday().</description>

</element>

<element kind="function" name="isoweekday">
<description>Return the day of the week as an integer, where Monday is 1 and
Sunday is 7. The same as self.date().isoweekday().
See also weekday(), isocalendar().</description>

</element>

<element kind="function" name="isocalendar">
<description>Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
same as self.date().isocalendar().</description>

</element>

<element kind="function" name="isoformat">
<description>Return a string representing the date and time in ISO 8601 format,
YYYY-MM-DDTHH:MM:SS.mmmmmm
or, if microsecond is 0,
YYYY-MM-DDTHH:MM:SS
If utcoffset() does not return None, a 6-character
string is appended, giving the UTC offset in (signed) hours and
minutes:
YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
or, if microsecond is 0
YYYY-MM-DDTHH:MM:SS+HH:MM
The optional argument sep (default 'T') is a
one-character separator, placed between the date and time portions
of the result. For example,
&gt;&gt;&gt; from datetime import tzinfo, timedelta, datetime
&gt;&gt;&gt; class TZ(tzinfo):
... def utcoffset(self, dt): return timedelta(minutes=-399)
...
&gt;&gt;&gt; datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
</description>

<properties><property default="'T'sep='T'" kind="parameter" name="sep" required="1"/></properties></element>

<element kind="function" name="__str__">
<description>For a datetime instance d, str(d) is
equivalent to d.isoformat(' ').</description>

</element>

<element kind="function" name="ctime">
<description>Return a string representing the date and time, for example
datetime(2002, 12, 4, 20, 30, 40).ctime() ==
'Wed Dec 4 20:30:40 2002'.
d.ctime() is equivalent to
time.ctime(time.mktime(d.timetuple())) on platforms where
the native C ctime() function (which
time.ctime() invokes, but which
datetime.ctime() does not invoke) conforms to the C
standard.</description>

</element>

<element kind="function" name="strftime">
<description>Return a string representing the date and time, controlled by an
explicit format string. See the section on strftime()
behavior.</description>

<properties><property kind="parameter" name="formatformat" required="1"/></properties></element>

</group>
<group name="time Objects">
<description>A time object represents a (local) time of day, independent of any
particular day, and subject to adjustment via a tzinfo object.
</description>
<element kind="function" name="time">
<description>All arguments are optional. tzinfo may be None, or
an instance of a tzinfo subclass. The remaining arguments
may be ints or longs, in the following ranges:
0 &lt;= hour &lt; 24
0 &lt;= minute &lt; 60
0 &lt;= second &lt; 60
0 &lt;= microsecond &lt; 1000000.
If an argument outside those ranges is given,
ValueError is raised.</description>

<properties><property default="0" kind="parameter" name="hour" required="1"/><property default="0" kind="parameter" name="minute" required="1"/><property default="0" kind="parameter" name="second" required="1"/><property default="0" kind="parameter" name="microsecond" required="1"/><property default="None                         tzinfo=None" kind="parameter" name="tzinfo" required="1"/></properties></element>

<element kind="function" name="replace">
<description>Return a time with the same value, except for those members given
new values by whichever keyword arguments are specified. Note that
tzinfo=None can be specified to create a naive time from
an aware time, without conversion of the time members.</description>

<properties><property kind="parameter" name="hour" required="1"/><property kind="parameter" name="minute" required="1"/><property kind="parameter" name="second" required="1"/><property kind="parameter" name="microsecond" required="1"/><property default=" tzinfo=" kind="parameter" name="tzinfo" required="1"/></properties></element>

<element kind="function" name="isoformat">
<description>Return a string representing the time in ISO 8601 format,
HH:MM:SS.mmmmmm
or, if self.microsecond is 0,
HH:MM:SS
If utcoffset() does not return None, a 6-character
string is appended, giving the UTC offset in (signed) hours and
minutes:
HH:MM:SS.mmmmmm+HH:MM
or, if self.microsecond is 0,
HH:MM:SS+HH:MM</description>

</element>

<element kind="function" name="__str__">
<description>For a time t, str(t) is equivalent to
t.isoformat().</description>

</element>

<element kind="function" name="strftime">
<description>Return a string representing the time, controlled by an explicit
format string. See the section on strftime() behavior.</description>

<properties><property kind="parameter" name="formatformat" required="1"/></properties></element>

<element kind="function" name="utcoffset">
<description>If tzinfo is None, returns None, else
returns self.tzinfo.utcoffset(None), and
raises an exception if the latter doesn't return None or
a timedelta object representing a whole number of minutes
with magnitude less than one day.</description>

</element>

<element kind="function" name="dst">
<description>If tzinfo is None, returns None, else
returns self.tzinfo.dst(None), and
raises an exception if the latter doesn't return None, or
a timedelta object representing a whole number of minutes
with magnitude less than one day.</description>

</element>

<element kind="function" name="tzname">
<description>If tzinfo is None, returns None, else
returns self.tzinfo.tzname(None), or
raises an exception if the latter doesn't return None or
a string object.</description>

</element>

</group>
<group name="tzinfo Objects">
<description>tzinfo is an abstract base clase, meaning that this class
should not be instantiated directly. You need to derive a concrete
subclass, and (at least) supply implementations of the standard
tzinfo methods needed by the datetime methods you
use. The datetime module does not supply any concrete
subclasses of tzinfo.
An instance of (a concrete subclass of) tzinfo can be passed
to the constructors for datetime and time objects.
The latter objects view their members as being in local time, and the
tzinfo object supports methods revealing offset of local time
from UTC, the name of the time zone, and DST offset, all relative to a
date or time object passed to them.
Special requirement for pickling: A tzinfo subclass must have an
__init__ method that can be called with no arguments, else it
can be pickled but possibly not unpickled again. This is a technical
requirement that may be relaxed in the future.
A concrete subclass of tzinfo may need to implement the
following methods. Exactly which methods are needed depends on the
uses made of aware datetime objects. If in doubt, simply
implement all of them.
</description>
<element kind="function" name="utcoffset">
<description>Return offset of local time from UTC, in minutes east of UTC. If
local time is west of UTC, this should be negative. Note that this
is intended to be the total offset from UTC; for example, if a
tzinfo object represents both time zone and DST adjustments,
utcoffset() should return their sum. If the UTC offset
isn't known, return None. Else the value returned must be
a timedelta object specifying a whole number of minutes in the
range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset
must be less than one day). Most implementations of
utcoffset() will probably look like one of these two:
return CONSTANT # fixed-offset class
return CONSTANT + self.dst(dt) # daylight-aware class
If utcoffset() does not return None,
dst() should not return None either.
The default implementation of utcoffset() raises
NotImplementedError.</description>

<properties><property kind="parameter" name="self" required="1"/><property kind="parameter" name="dt dt" required="1"/></properties></element>

<element kind="function" name="dst">
<description>Return the daylight saving time (DST) adjustment, in minutes east of
UTC, or None if DST information isn't known. Return
timedelta(0) if DST is not in effect.
If DST is in effect, return the offset as a
timedelta object (see utcoffset() for details).
Note that DST offset, if applicable, has
already been added to the UTC offset returned by
utcoffset(), so there's no need to consult dst()
unless you're interested in obtaining DST info separately. For
example, datetime.timetuple() calls its tzinfo
member's dst() method to determine how the
tm_isdst flag should be set, and
tzinfo.fromutc() calls dst() to account for
DST changes when crossing time zones.
An instance tz of a tzinfo subclass that models both
standard and daylight times must be consistent in this sense:
tz.utcoffset(dt) - tz.dst(dt)
must return the same result for every datetime dt
with dt.tzinfo==tz For sane tzinfo
subclasses, this expression yields the time zone's &quot;standard offset&quot;,
which should not depend on the date or the time, but only on geographic
location. The implementation of datetime.astimezone() relies
on this, but cannot detect violations; it's the programmer's
responsibility to ensure it. If a tzinfo subclass cannot
guarantee this, it may be able to override the default implementation
of tzinfo.fromutc() to work correctly with astimezone()
regardless.
Most implementations of dst() will probably look like one
of these two:
return timedelta(0) # a fixed-offset class: doesn't account for DST
or
# Code to set dston and dstoff to the time zone's DST transition
# times based on the input dt.year, and expressed in standard local
# time. Then
if dston &lt;= dt.replace(tzinfo=None) &lt; dstoff:
return timedelta(hours=1)
else:
return timedelta(0)
The default implementation of dst() raises
NotImplementedError.</description>

<properties><property kind="parameter" name="self" required="1"/><property kind="parameter" name="dt dt" required="1"/></properties></element>

<element kind="function" name="tzname">
<description>Return the time zone name corresponding to the datetime
object dt, as a string.
Nothing about string names is defined by the
datetime module, and there's no requirement that it mean
anything in particular. For example, &quot;GMT&quot;, &quot;UTC&quot;, &quot;-500&quot;, &quot;-5:00&quot;,
&quot;EDT&quot;, &quot;US/Eastern&quot;, &quot;America/New York&quot; are all valid replies. Return
None if a string name isn't known. Note that this is a method
rather than a fixed string primarily because some tzinfo
subclasses will wish to return different names depending on the specific
value of dt passed, especially if the tzinfo class is
accounting for daylight time.
The default implementation of tzname() raises
NotImplementedError.</description>

<properties><property kind="parameter" name="self" required="1"/><property kind="parameter" name="dt dt" required="1"/></properties></element>

<element kind="function" name="fromutc">
<description>This is called from the default datetime.astimezone()
implementation. When called from that, dt.tzinfo is
self, and dt's date and time members are to be viewed as
expressing a UTC time. The purpose of fromutc() is to
adjust the date and time members, returning an equivalent datetime in
self's local time.
Most tzinfo subclasses should be able to inherit the default
fromutc() implementation without problems. It's strong enough
to handle fixed-offset time zones, and time zones accounting for both
standard and daylight time, and the latter even if the DST transition
times differ in different years. An example of a time zone the default
fromutc() implementation may not handle correctly in all cases
is one where the standard offset (from UTC) depends on the specific date
and time passed, which can happen for political reasons.
The default implementations of astimezone() and
fromutc() may not produce the result you want if the result is
one of the hours straddling the moment the standard offset changes.
Skipping code for error cases, the default fromutc()
implementation acts like:
def fromutc(self, dt):
# raise ValueError error if dt.tzinfo is not self
dtoff = dt.utcoffset()
dtdst = dt.dst()
# raise ValueError if dtoff is None or dtdst is None
delta = dtoff - dtdst # this is self's standard offset
if delta:
dt += delta # convert to standard local time
dtdst = dt.dst()
# raise ValueError if dtdst is None
if dtdst:
return dt + dtdst
else:
return dt
</description>

<properties><property kind="parameter" name="self" required="1"/><property kind="parameter" name="dt dt" required="1"/></properties></element>

</group>
<group name="strftime() Behavior">
</group>
</group>
<group name="time --- Time access and conversions">
<description>Time access and conversions.
This module provides various time-related functions. It is always
available, but not all functions are available on all platforms. Most
of the functions defined in this module call platform C library
functions with the same name. It may sometimes be helpful to consult
the platform documentation, because the semantics of these functions
varies among platforms.
An explanation of some terminology and conventions is in order.
The epoch</description>
<element kind="function" name="asctime">
<description>Convert a tuple or struct_time representing a time as returned
by gmtime()
or localtime() to a 24-character string of the following form:
'Sun Jun 20 23:21:05 1993'. If t is not provided, the
current time as returned by localtime() is used.
Locale information is not used by asctime().
Unlike the C function of the same name, there is no trailing
newline.
Changed in version 2.1: Allowed t to be omitted</description>

<properties><property kind="parameter" name="t" required="1"/></properties></element>

<element kind="function" name="clock">
<description>On , return
the current processor time as a floating point number expressed in
seconds. The precision, and in fact the very definition of the meaning
of ``processor time''</description>

</element>

<element kind="function" name="ctime">
<description>Convert a time expressed in seconds since the epoch to a string
representing local time. If secs is not provided, the current time
as returned by time() is used. ctime(secs)
is equivalent to asctime(localtime(secs)).
Locale information is not used by ctime().
Changed in version 2.1: Allowed secs to be omitted</description>

<properties><property kind="parameter" name="secs" required="1"/></properties></element>

<element kind="function" name="gmtime">
<description>Convert a time expressed in seconds since the epoch to a struct_time
in UTC in which the dst flag is always zero. If secs is not
provided, the current time as returned by time() is used.
Fractions of a second are ignored. See above for a description of the
struct_time object.
Changed in version 2.1: Allowed secs to be omitted</description>

<properties><property kind="parameter" name="secs" required="1"/></properties></element>

<element kind="function" name="localtime">
<description>Like gmtime() but converts to local time. The dst flag is
set to 1 when DST applies to the given time.
Changed in version 2.1: Allowed secs to be omitted</description>

<properties><property kind="parameter" name="secs" required="1"/></properties></element>

<element kind="function" name="mktime">
<description>This is the inverse function of localtime(). Its argument
is the struct_time or full 9-tuple (since the dst flag is
needed; use -1 as the dst flag if it is unknown) which
expresses the time in
local time, not UTC. It returns a floating point number, for
compatibility with time(). If the input value cannot be
represented as a valid time, either OverflowError or
ValueError will be raised (which depends on whether the
invalid value is caught by Python or the underlying C libraries). The
earliest date for which it can generate a time is platform-dependent.</description>

<properties><property kind="parameter" name="tt" required="1"/></properties></element>

<element kind="function" name="sleep">
<description>Suspend execution for the given number of seconds. The argument may
be a floating point number to indicate a more precise sleep time.
The actual suspension time may be less than that requested because any
caught signal will terminate the sleep() following
execution of that signal's catching routine. Also, the suspension
time may be longer than requested by an arbitrary amount because of
the scheduling of other activity in the system.</description>

<properties><property kind="parameter" name="secssecs" required="1"/></properties></element>

<element kind="function" name="strftime">
<description>Convert a tuple or struct_time representing a time as returned
by gmtime() or localtime() to a string as
specified by the format argument. If t is not
provided, the current time as returned by localtime() is
used. format must be a string.
Changed in version 2.1: Allowed t to be omitted
The following directives can be embedded in the format string.
They are shown without the optional field width and precision
specification, and are replaced by the indicated characters in the
strftime() result:
{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
{Locale's abbreviated weekday name.}{}
{Locale's full weekday name.}{}
{Locale's abbreviated month name.}{}
{Locale's full month name.}{}
{Locale's appropriate date and time representation.}{}
{Day of the month as a decimal number [01,31].}{}
{Hour (24-hour clock) as a decimal number [00,23].}{}
{Hour (12-hour clock) as a decimal number [01,12].}{}
{Day of the year as a decimal number [001,366].}{}
{Month as a decimal number [01,12].}{}
{Minute as a decimal number [00,59].}{}
{Locale's equivalent of either AM or PM.}{}
{Second as a decimal number [00,61].}{(1)}
{Week number of the year (Sunday as the first day of the
week) as a decimal number [00,53]. All days in a new year
preceding the first Sunday are considered to be in week 0.}{}
{Weekday as a decimal number [0(Sunday),6].}{}
{Week number of the year (Monday as the first day of the
week) as a decimal number [00,53]. All days in a new year
preceding the first Monday are considered to be in week 0.}{}
{Locale's appropriate date representation.}{}
{Locale's appropriate time representation.}{}
{Year without century as a decimal number [00,99].}{}
{Year with century as a decimal number.}{}
{Time zone name (no characters if no time zone exists).}{}
%%{A literal % character.}{}
Notes:
[(1)]
The range really is 0 to 61; this accounts for leap
seconds and the (very rare) double leap seconds.
Here is an example, a format for dates compatible with that specified in the 2822 Internet email standard.
The use of is now
deprecated, but the escape that expands to the preferred hour/minute offset is not supported by all ANSI C libraries. Also,
a strict reading of the original 1982 822 standard calls for
a two-digit year ( rather than ), but practice moved to
4-digit years long before the year 2000. The 4-digit year has
been mandated by 2822, which obsoletes 822.
&gt;&gt;&gt; from time import gmtime, strftime
&gt;&gt;&gt; strftime(&quot;%a, %d %b %Y %H:%M:%S +0000&quot;, gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'
Additional directives may be supported on certain platforms, but
only the ones listed here have a meaning standardized by ANSI C.
On some platforms, an optional field width and precision
specification can immediately follow the initial % of a
directive in the following order; this is also not portable.
The field width is normally 2 except for where it is 3.</description>

<properties><property kind="parameter" name="format" required="1"/><property kind="parameter" name="t"/></properties></element>

<element kind="function" name="strptime">
<description>Parse a string representing a time according to a format. The return value is a struct_time as returned by gmtime() or
localtime(). The format parameter uses the same
directives as those used by strftime(); it defaults to
&quot; :: &quot; which matches the formatting
returned by ctime(). If string cannot be parsed
according to format, ValueError is raised. If the
string to be parsed has excess data after parsing,
ValueError is raised. The default values used to fill in
any missing data is (1900, 1, 1, 0, 0, 0, 0, 1, -1) .
Support for the directive is based on the values contained in
tzname and whether daylight is true. Because of this,
it is platform-specific except for recognizing UTC and GMT which are
always known (and are considered to be non-daylight savings
timezones).</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="format"/></properties></element>

<element kind="function" name="time">
<description>Return the time as a floating point number expressed in seconds since
the epoch, in UTC. Note that even though the time is always returned
as a floating point number, not all systems provide time with a better
precision than 1 second. While this function normally returns
non-decreasing values, it can return a lower value than a previous
call if the system clock has been set back between the two calls.</description>

</element>

<element kind="function" name="tzset">
<description>Resets the time conversion rules used by the library routines.
The environment variable TZ specifies how this is done.
New in version 2.3
Availability: .
Although in many cases, changing the TZ environment variable
may affect the output of functions like localtime without calling tzset, this behavior should not be relied on.
The TZ environment variable should contain no whitespace.
The standard format of the TZ environment variable is:
(whitespace added for clarity)
[std offset [dst [offset] [,start[/time], end[/time]]]]
Where:
[std and dst]
Three or more alphanumerics giving the timezone abbreviations.
These will be propogated into time.tzname
[offset]
The offset has the form: hh[:mm[:ss]].
This indicates the value added the local time to arrive at UTC. If preceded by a '-', the timezone is east of the Prime Meridian; otherwise, it is west. If no offset follows
dst, summmer time is assumed to be one hour ahead of standard time.
[start[/time],end[/time]]
Indicates when to change to and back from DST. The format of the
start and end dates are one of the following:
[Jn]
The Julian day n (1 &lt;= n &lt;= 365). Leap days are not counted, so in all years February 28 is day 59 and
March 1 is day 60.
[n]
The zero-based Julian day (0 &lt;= n &lt;= 365). Leap days are
counted, and it is possible to refer to February 29.
[Mm.n.d]
The d'th day (0 &lt;= d &lt;= 6) or week n of month m of the year (1 &lt;= n &lt;= 5, 1 &lt;= m &lt;= 12, where week 5 means &quot;the last d day
in month m&quot; which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d'th day occurs. Day zero is Sunday.
time has the same format as offset except that no leading sign ('-' or
'+') is allowed. The default, if time is not given, is 02:00:00.
&gt;&gt;&gt; os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
&gt;&gt;&gt; time.tzset()
&gt;&gt;&gt; time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
&gt;&gt;&gt; os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
&gt;&gt;&gt; time.tzset()
&gt;&gt;&gt; time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'
On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
is more convenient to use the system's zoneinfo (tzfile{5}) database to specify the timezone rules. To do this, set the TZ environment variable to the path of the required timezone datafile, relative to the root of the systems 'zoneinfo' timezone database,
usually located at /usr/share/zoneinfo. For example, 'US/Eastern', 'Australia/Melbourne', 'Egypt' or 'Europe/Amsterdam'.
&gt;&gt;&gt; os.environ['TZ'] = 'US/Eastern'
&gt;&gt;&gt; time.tzset()
&gt;&gt;&gt; time.tzname
('EST', 'EDT')
&gt;&gt;&gt; os.environ['TZ'] = 'Egypt'
&gt;&gt;&gt; time.tzset()
&gt;&gt;&gt; time.tzname
('EET', 'EEST')
</description>

</element>

</group>
<group name="sched --- Event scheduler">
<description>% LaTeXed and enhanced from comments in file
General purpose event scheduler.
The sched module defines a class which implements a general
purpose event scheduler:</description>
<element kind="function" name="scheduler">
<description>The scheduler class defines a generic interface to scheduling
events. It needs two functions to actually deal with the ``outside world''
--- timefunc should be callable without arguments, and return a number (the ``time'', in any units whatsoever). The delayfunc
function should be callable with one argument, compatible with the output
of timefunc, and should delay that many time units.
delayfunc will also be called with the argument 0 after
each event is run to allow other threads an opportunity to run in
multi-threaded applications.</description>

<properties><property kind="parameter" name="timefunc" required="1"/><property kind="parameter" name="delayfunc delayfunc" required="1"/></properties></element>

<group name="Scheduler Objects">
<description>scheduler instances have the following methods:
</description>
<element kind="function" name="enterabs">
<description>Schedule a new event. The time argument should be a numeric type
compatible with the return value of the timefunc function passed to the constructor. Events scheduled for
the same time will be executed in the order of their
priority.
Executing the event means executing
action(*argument). argument must be a
sequence holding the parameters for action.
Return value is an event which may be used for later cancellation of
the event (see cancel()).</description>

<properties><property kind="parameter" name="time" required="1"/><property kind="parameter" name="priority" required="1"/><property kind="parameter" name="action" required="1"/><property kind="parameter" name="argument argument" required="1"/></properties></element>

<element kind="function" name="enter">
<description>Schedule an event for delay more time units. Other then the
relative time, the other arguments, the effect and the return value
are the same as those for enterabs().</description>

<properties><property kind="parameter" name="delay" required="1"/><property kind="parameter" name="priority" required="1"/><property kind="parameter" name="action" required="1"/><property kind="parameter" name="argument argument" required="1"/></properties></element>

<element kind="function" name="cancel">
<description>Remove the event from the queue. If event is not an event
currently in the queue, this method will raise a
RuntimeError.</description>

<properties><property kind="parameter" name="eventevent" required="1"/></properties></element>

<element kind="function" name="empty">
<description>Return true if the event queue is empty.</description>

</element>

<element kind="function" name="run">
<description>Run all scheduled events. This function will wait (using the delayfunc function passed to the constructor)
for the next event, then execute it and so on until there are no more
scheduled events.
Either action or delayfunc can raise an exception. In
either case, the scheduler will maintain a consistent state and
propagate the exception. If an exception is raised by action,
the event will not be attempted in future calls to run().
If a sequence of events takes longer to run than the time available
before the next event, the scheduler will simply fall behind. No
events will be dropped; the calling code is responsible for canceling events which are no longer pertinent.</description>

</element>

</group>
</group>
<group name="mutex --- Mutual exclusion support">
<description>Lock and queue for mutual exclusion.
The mutex module defines a class that allows mutual-exclusion
via acquiring and releasing locks. It does not require (or imply)
threading or multi-tasking, though it could be useful for
those purposes.
The mutex module defines the following class:
</description>
<element kind="function" name="mutex">
<description>Create a new (unlocked) mutex.
A mutex has two pieces of state --- a ``locked'' bit and a queue.
When the mutex is not locked, the queue is empty.
Otherwise, the queue contains zero or more (function, argument) pairs
representing functions (or methods) waiting to acquire the lock.
When the mutex is unlocked while the queue is not empty,
the first queue entry is removed and its function(argument) pair called,
implying it now has the lock.
Of course, no multi-threading is implied -- hence the funny interface
for lock(), where a function is called once the lock is
acquired.</description>

</element>

<group name="Mutex Objects">
<description>mutex objects have following methods:
</description>
<element kind="function" name="test">
<description>Check whether the mutex is locked.</description>

</element>

<element kind="function" name="testandset">
<description>``Atomic'' test-and-set, grab the lock if it is not set,
and return True, otherwise, return False.</description>

</element>

<element kind="function" name="lock">
<description>Execute function(argument), unless the mutex is locked.
In the case it is locked, place the function and argument on the queue.
See unlock for explanation of when
function(argument) is executed in that case.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="argument argument" required="1"/></properties></element>

<element kind="function" name="unlock">
<description>Unlock the mutex if queue is empty, otherwise execute the first element
in the queue.</description>

</element>

</group>
</group>
<group name="getpass --- Portable password input">
<description>Portable reading of passwords and retrieval of the userid.
% Windows (&amp; Mac?) support by Guido van Rossum.
The getpass module provides two functions:
</description>
<element kind="function" name="getpass">
<description>Prompt the user for a password without echoing. The user is
prompted using the string prompt, which defaults to
'Password: '.
Availability: Macintosh, , Windows.</description>

<properties><property kind="parameter" name="prompt" required="1"/></properties></element>

<element kind="function" name="getuser">
<description>Return the ``login name'' of the user.
Availability: , Windows.
This function checks the environment variables LOGNAME,
USER, LNAME and USERNAME, in order, and
returns the value of the first one which is set to a non-empty
string. If none are set, the login name from the password database
is returned on systems which support the pwd module,
otherwise, an exception is raised.</description>

</element>

</group>
<group name="curses --- Terminal handling for character-cell displays">
<description>An interface to the curses library, providing portable
terminal handling.
Changed in version 1.6: Added support for the ncurses library and
converted to a package
The curses module provides an interface to the curses
library, the de-facto standard for portable advanced terminal
handling.
While curses is most widely used in the environment, versions
are available for DOS, OS/2, and possibly other systems as well. This
extension module is designed to match the API of ncurses, an
open-source curses library hosted on Linux and the BSD variants of
.
curses.ascii{Utilities for working with ASCII
characters, regardless of your locale
settings.}
curses.panel{A panel stack extension that adds depth to curses windows.}
curses.textpad{Editable text widget for curses supporting Emacs-like bindings.}
curses.wrapper{Convenience function to ensure proper
terminal setup and resetting on
application entry and exit.}
See also Curses
Programming with Python - Tutorial material on using curses
with Python, by Andrew Kuchling and Eric Raymond, is
available on the Python Web site.
The Demo/curses/ directory in the Python source
distribution contains some example programs using the
curses bindings provided by this module.
</description>
<group name="Functions">
<description>The module curses defines the following exception:
{error}
Exception raised when a curses library function returns an error.
Whenever x or y arguments to a function
or a method are optional, they default to the current cursor location.
Whenever attr is optional, it defaults to A_NORMAL.
The module curses defines the following functions:
</description>
<element kind="function" name="baudrate">
<description>Returns the output speed of the terminal in bits per second. On
software terminal emulators it will have a fixed high value.
Included for historical reasons; in former times, it was used to write output loops for time delays and occasionally to change
interfaces depending on the line speed.</description>

</element>

<element kind="function" name="beep">
<description>Emit a short attention sound.</description>

</element>

<element kind="function" name="can_change_color">
<description>Returns true or false, depending on whether the programmer can change
the colors displayed by the terminal.</description>

</element>

<element kind="function" name="cbreak">
<description>Enter cbreak mode. In cbreak mode (sometimes called ``rare'' mode)
normal tty line buffering is turned off and characters are available
to be read one by one. However, unlike raw mode, special characters
(interrupt, quit, suspend, and flow control) retain their effects on
the tty driver and calling program. Calling first raw()
then cbreak() leaves the terminal in cbreak mode.</description>

</element>

<element kind="function" name="color_content">
<description>Returns the intensity of the red, green, and blue (RGB) components in
the color color_number, which must be between 0 and
COLORS. A 3-tuple is returned, containing the R,G,B values
for the given color, which will be between 0 (no component) and
1000 (maximum amount of component).</description>

<properties><property kind="parameter" name="color_numbercolor_number" required="1"/></properties></element>

<element kind="function" name="color_pair">
<description>Returns the attribute value for displaying text in the specified
color. This attribute value can be combined with
A_STANDOUT, A_REVERSE, and the other
A_* attributes. pair_number() is the
counterpart to this function.</description>

<properties><property kind="parameter" name="color_numbercolor_number" required="1"/></properties></element>

<element kind="function" name="curs_set">
<description>Sets the cursor state. visibility can be set to 0, 1, or 2, for
invisible, normal, or very visible. If the terminal supports the
visibility requested, the previous cursor state is returned;
otherwise, an exception is raised. On many terminals, the ``visible''
mode is an underline cursor and the ``very visible'' mode is a block cursor.</description>

<properties><property kind="parameter" name="visibilityvisibility" required="1"/></properties></element>

<element kind="function" name="def_prog_mode">
<description>Saves the current terminal mode as the ``program'' mode, the mode when
the running program is using curses. (Its counterpart is the
``shell'' mode, for when the program is not in curses.) Subsequent calls
to reset_prog_mode() will restore this mode.</description>

</element>

<element kind="function" name="def_shell_mode">
<description>Saves the current terminal mode as the ``shell'' mode, the mode when
the running program is not using curses. (Its counterpart is the
``program'' mode, when the program is using curses capabilities.)
Subsequent calls
to reset_shell_mode() will restore this mode.</description>

</element>

<element kind="function" name="delay_output">
<description>Inserts an ms millisecond pause in output.</description>

<properties><property kind="parameter" name="msms" required="1"/></properties></element>

<element kind="function" name="doupdate">
<description>Update the physical screen. The curses library keeps two data
structures, one representing the current physical screen contents
and a virtual screen representing the desired next state. The
doupdate() ground updates the physical screen to match the
virtual screen.
The virtual screen may be updated by a noutrefresh() call
after write operations such as addstr() have been performed
on a window. The normal refresh() call is simply
noutrefresh() followed by doupdate(); if you have
to update multiple windows, you can speed performance and perhaps
reduce screen flicker by issuing noutrefresh() calls on
all windows, followed by a single doupdate().</description>

</element>

<element kind="function" name="echo">
<description>Enter echo mode. In echo mode, each character input is echoed to the
screen as it is entered.</description>

</element>

<element kind="function" name="endwin">
<description>De-initialize the library, and return terminal to normal status.</description>

</element>

<element kind="function" name="erasechar">
<description>Returns the user's current erase character. Under operating
systems this is a property of the controlling tty of the curses
program, and is not set by the curses library itself.</description>

</element>

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

</element>

<element kind="function" name="flash">
<description>Flash the screen. That is, change it to reverse-video and then change
it back in a short interval. Some people prefer such as `visible bell'
to the audible attention signal produced by beep().</description>

</element>

<element kind="function" name="flushinp">
<description>Flush all input buffers. This throws away any typeahead that has
been typed by the user and has not yet been processed by the program.</description>

</element>

<element kind="function" name="getmouse">
<description>After getch() returns KEY_MOUSE to signal a mouse
event, this method should be call to retrieve the queued mouse event,
represented as a 5-tuple
(id, x, y, z, bstate).
id is an ID value used to distinguish multiple devices,
and x, y, z are the event's coordinates. (z
is currently unused.). bstate is an integer value whose bits
will be set to indicate the type of event, and will be the bitwise OR
of one or more of the following constants, where n is the button
number from 1 to 4:
BUTTONn_PRESSED,
BUTTONn_RELEASED,
BUTTONn_CLICKED,
BUTTONn_DOUBLE_CLICKED,
BUTTONn_TRIPLE_CLICKED,
BUTTON_SHIFT,
BUTTON_CTRL,
BUTTON_ALT.</description>

</element>

<element kind="function" name="getsyx">
<description>Returns the current coordinates of the virtual screen cursor in y and
x. If leaveok is currently true, then -1,-1 is returned.</description>

</element>

<element kind="function" name="getwin">
<description>Reads window related data stored in the file by an earlier
putwin() call. The routine then creates and initializes a
new window using that data, returning the new window object.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="has_colors">
<description>Returns true if the terminal can display colors; otherwise, it
returns false.</description>

</element>

<element kind="function" name="has_ic">
<description>Returns true if the terminal has insert- and delete- character
capabilities. This function is included for historical reasons only,
as all modern software terminal emulators have such capabilities.</description>

</element>

<element kind="function" name="has_il">
<description>Returns true if the terminal has insert- and
delete-line capabilities, or can simulate them using
scrolling regions. This function is included for historical reasons only,
as all modern software terminal emulators have such capabilities.</description>

</element>

<element kind="function" name="has_key">
<description>Takes a key value ch, and returns true if the current terminal
type recognizes a key with that value.</description>

<properties><property kind="parameter" name="chch" required="1"/></properties></element>

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

<properties><property kind="parameter" name="tenthstenths" required="1"/></properties></element>

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

<properties><property kind="parameter" name="color_number" required="1"/><property kind="parameter" name="r" required="1"/><property kind="parameter" name="g" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

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

<properties><property kind="parameter" name="pair_number" required="1"/><property kind="parameter" name="fg" required="1"/><property kind="parameter" name="bg bg" required="1"/></properties></element>

<element kind="function" name="initscr">
<description>Initialize the library. Returns a WindowObject which represents
the whole screen. If there is an error opening the terminal,
the underlying curses library may cause the interpreter to exit.</description>

</element>

<element kind="function" name="isendwin">
<description>Returns true if endwin() has been called (that is, the curses library has been deinitialized).</description>

</element>

<element kind="function" name="keyname">
<description>Return the name of the key numbered k. The name of a key
generating printable ASCII character is the key's character. The name
of a control-key combination is a two-character string consisting of a
caret followed by the corresponding printable ASCII character. The
name of an alt-key combination (128-255) is a string consisting of the
prefix `M-' followed by the name of the corresponding ASCII character.</description>

<properties><property kind="parameter" name="kk" required="1"/></properties></element>

<element kind="function" name="killchar">
<description>Returns the user's current line kill character. Under operating
systems this is a property of the controlling tty of the curses
program, and is not set by the curses library itself.</description>

</element>

<element kind="function" name="longname">
<description>Returns a string containing the terminfo long name field describing the current
terminal. The maximum length of a verbose description is 128
characters. It is defined only after the call to
initscr().</description>

</element>

<element kind="function" name="meta">
<description>If yes is 1, allow 8-bit characters to be input. If yes is 0, allow only 7-bit chars.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="mouseinterval">
<description>Sets the maximum time in milliseconds that can elapse between press and
release events in order for them to be recognized as a click, and
returns the previous interval value. The default value is 200 msec,
or one fifth of a second.</description>

<properties><property kind="parameter" name="intervalinterval" required="1"/></properties></element>

<element kind="function" name="mousemask">
<description>Sets the mouse events to be reported, and returns a tuple
(availmask, oldmask). availmask indicates which of the
specified mouse events can be reported; on complete failure it returns
0. oldmask is the previous value of the given window's mouse
event mask. If this function is never called, no mouse events are
ever reported.</description>

<properties><property kind="parameter" name="mousemaskmousemask" required="1"/></properties></element>

<element kind="function" name="napms">
<description>Sleep for ms milliseconds.</description>

<properties><property kind="parameter" name="msms" required="1"/></properties></element>

<element kind="function" name="newpad">
<description>Creates and returns a pointer to a new pad data structure with the
given number of lines and columns. A pad is returned as a
window object.
A pad is like a window, except that it is not restricted by the screen
size, and is not necessarily associated with a particular part of the
screen. Pads can be used when a large window is needed, and only a
part of the window will be on the screen at one time. Automatic
refreshes of pads (such as from scrolling or echoing of input) do not
occur. The refresh() and noutrefresh() methods of a
pad require 6 arguments to specify the part of the pad to be
displayed and the location on the screen to be used for the display.
The arguments are pminrow, pmincol, sminrow, smincol, smaxrow,
smaxcol; the p arguments refer to the upper left corner of the pad
region to be displayed and the s arguments define a clipping box on
the screen within which the pad region is to be displayed.</description>

<properties><property kind="parameter" name="nlines" required="1"/><property kind="parameter" name="ncols ncols" required="1"/></properties></element>

<element kind="function" name="newwin">
<description>Return a new window, whose left-upper corner is at (begin_y, begin_x), and whose height/width is nlines/ncols. By default, the window will extend from the specified position to the lower right corner of the screen.</description>

<properties><property kind="parameter" name="nlines" required="1"/><property kind="parameter" name="ncols"/><property kind="parameter" name="begin_y"/><property kind="parameter" name="begin_x begin_x"/></properties></element>

<element kind="function" name="nl">
<description>Enter newline mode. This mode translates the return key into newline
on input, and translates newline into return and line-feed on output.
Newline mode is initially on.</description>

</element>

<element kind="function" name="nocbreak">
<description>Leave cbreak mode. Return to normal ``cooked'' mode with line buffering.</description>

</element>

<element kind="function" name="noecho">
<description>Leave echo mode. Echoing of input characters is turned off.</description>

</element>

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

</element>

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

</element>

<element kind="function" name="noraw">
<description>Leave raw mode. Return to normal ``cooked'' mode with line buffering.</description>

</element>

<element kind="function" name="pair_content">
<description>Returns a tuple (fg, bg) containing the colors for
the requested color pair. The value of pair_number must be
between 0 and COLOR_PAIRS - 1.</description>

<properties><property kind="parameter" name="pair_numberpair_number" required="1"/></properties></element>

<element kind="function" name="pair_number">
<description>Returns the number of the color-pair set by the attribute value
attr. color_pair() is the counterpart to this
function.</description>

<properties><property kind="parameter" name="attrattr" required="1"/></properties></element>

<element kind="function" name="putp">
<description>Equivalent to tputs(str, 1, putchar); emits the value of a
specified terminfo capability for the current terminal. Note that the
output of putp always goes to standard output.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="qiflush">
<description>If flag is false, the effect is the same as calling
noqiflush(). If flag is true, or no argument is
provided, the queues will be flushed when these control characters are
read.</description>

<properties><property kind="parameter" name="flag" required="1"/></properties></element>

<element kind="function" name="raw">
<description>Enter raw mode. In raw mode, normal line buffering and processing of interrupt, quit, suspend, and flow control keys are
turned off; characters are presented to curses input functions one
by one.</description>

</element>

<element kind="function" name="reset_prog_mode">
<description>Restores the terminal to ``program'' mode, as previously saved by def_prog_mode().</description>

</element>

<element kind="function" name="reset_shell_mode">
<description>Restores the terminal to ``shell'' mode, as previously saved by def_shell_mode().</description>

</element>

<element kind="function" name="setsyx">
<description>Sets the virtual screen cursor to y, x.
If y and x are both -1, then leaveok is set.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x x" required="1"/></properties></element>

<element kind="function" name="setupterm">
<description>Initializes the terminal. termstr is a string giving the
terminal name; if omitted, the value of the TERM environment variable
will be used. fd is the file descriptor to which any
initialization sequences will be sent; if not supplied, the file
descriptor for sys.stdout will be used.</description>

<properties><property kind="parameter" name="termstr" required="1"/><property kind="parameter" name="fd"/></properties></element>

<element kind="function" name="start_color">
<description>Must be called if the programmer wants to use colors, and before any
other color manipulation routine is called. It is good
practice to call this routine right after initscr().
start_color() initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global
variables in the curses module, COLORS and
COLOR_PAIRS, containing the maximum number of colors and
color-pairs the terminal can support. It also restores the colors on
the terminal to the values they had when the terminal was just turned
on.</description>

</element>

<element kind="function" name="termattrs">
<description>Returns a logical OR of all video attributes supported by the
terminal. This information is useful when a curses program needs
complete control over the appearance of the screen.</description>

</element>

<element kind="function" name="termname">
<description>Returns the value of the environment variable TERM, truncated to 14
characters.</description>

</element>

<element kind="function" name="tigetflag">
<description>Returns the value of the Boolean capability corresponding to the
terminfo capability name capname. The value -1 is
returned if capname is not a Boolean capability, or 0 if
it is canceled or absent from the terminal description.</description>

<properties><property kind="parameter" name="capnamecapname" required="1"/></properties></element>

<element kind="function" name="tigetnum">
<description>Returns the value of the numeric capability corresponding to the
terminfo capability name capname. The value -2 is
returned if capname is not a numeric capability, or -1 if
it is canceled or absent from the terminal description.</description>

<properties><property kind="parameter" name="capnamecapname" required="1"/></properties></element>

<element kind="function" name="tigetstr">
<description>Returns the value of the string capability corresponding to the
terminfo capability name capname. None is returned if
capname is not a string capability, or is canceled or absent
from the terminal description.</description>

<properties><property kind="parameter" name="capnamecapname" required="1"/></properties></element>

<element kind="function" name="tparm">
<description>Instantiates the string str with the supplied parameters, where str should be a parameterized string obtained from the terminfo database. E.g. tparm(tigetstr(&quot;cup&quot;), 5, 3) could result in '033[6;4H', the exact result depending on terminal type.</description>

<properties><property kind="parameter" name="str" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="typeahead">
<description>Specifies that the file descriptor fd be used for typeahead
checking. If fd is -1, then no typeahead checking is
done.
The curses library does ``line-breakout optimization'' by looking for
typeahead periodically while updating the screen. If input is found,
and it is coming from a tty, the current update is postponed until
refresh or doupdate is called again, allowing faster response to
commands typed in advance. This function allows specifying a different
file descriptor for typeahead checking.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="unctrl">
<description>Returns a string which is a printable representation of the character
ch. Control characters are displayed as a caret followed by the
character, for example as C. Printing
characters are left as they are.</description>

<properties><property kind="parameter" name="chch" required="1"/></properties></element>

<element kind="function" name="ungetch">
<description>Push ch so the next getch() will return it.
Only one ch can be pushed before getch()
is called.</description>

<properties><property kind="parameter" name="chch" required="1"/></properties></element>

<element kind="function" name="ungetmouse">
<description>Push a KEY_MOUSE event onto the input queue, associating
the given state data with it.</description>

<properties><property kind="parameter" name="id" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="z" required="1"/><property kind="parameter" name="bstate bstate" required="1"/></properties></element>

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

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="use_default_colors">
<description>Allow use of default values for colors on terminals supporting this
feature. Use this to support transparency in your
application. The default color is assigned to the color number -1.
After calling this function, init_pair(x, curses.COLOR_RED, -1) initializes, for instance,
color pair x to a red foreground color on the default background.</description>

</element>

</group>
<group name="Window Objects">
<description>Window objects, as returned by initscr() and
newwin() above, have the
following methods:
</description>
<element kind="function" name="addch">
<description>A character means a C character (an
ASCII code), rather then a Python character (a string of length 1).
(This note is true whenever the documentation mentions a character.)
The builtin ord() is handy for conveying strings to codes.
Paint character ch at (y, x) with attributes
attr, overwriting any character previously painter at that
location. By default, the character position and attributes are the
current settings for the window object.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="ch"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="addnstr">
<description>Paint at most n characters of the string str at (y, x) with attributes
attr, overwriting anything previously on the display.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="str"/><property kind="parameter" name="n"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="addstr">
<description>Paint the string str at (y, x) with attributes
attr, overwriting anything previously on the display.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="str"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="attroff">
<description>Remove attribute attr from the ``background'' set applied to all
writes to the current window.</description>

<properties><property kind="parameter" name="attrattr" required="1"/></properties></element>

<element kind="function" name="attron">
<description>Add attribute attr from the ``background'' set applied to all
writes to the current window.</description>

<properties><property kind="parameter" name="attrattr" required="1"/></properties></element>

<element kind="function" name="attrset">
<description>Set the ``background'' set of attributes to attr. This set is
initially 0 (no attributes).</description>

<properties><property kind="parameter" name="attrattr" required="1"/></properties></element>

<element kind="function" name="bkgd">
<description>Sets the background property of the window to the character ch,
with attributes attr. The change is then applied to every
character position in that window:
The attribute of every character in the window is
changed to the new background attribute.
Wherever the former background character appears,
it is changed to the new background character.
</description>

<properties><property kind="parameter" name="ch" required="1"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="bkgdset">
<description>Sets the window's background. A window's background consists of a
character and any combination of attributes. The attribute part of
the background is combined (OR'ed) with all non-blank characters that
are written into the window. Both the character and attribute parts
of the background are combined with the blank characters. The
background becomes a property of the character and moves with the
character through any scrolling and insert/delete line/character
operations.</description>

<properties><property kind="parameter" name="ch" required="1"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="border">
<description>Draw a border around the edges of the window. Each parameter specifies the character to use for a specific part of the border; see the table
below for more details. The characters can be specified as integers
or as one-character strings.
A 0 value for any parameter will cause the
default character to be used for that parameter. Keyword parameters
can not be used. The defaults are listed in this table:
{l|l|l}{var}{Parameter}{Description}{Default value}
ls{Left side}{ACS_VLINE}
rs{Right side}{ACS_VLINE}
ts{Top}{ACS_HLINE}
bs{Bottom}{ACS_HLINE}
tl{Upper-left corner}{ACS_ULCORNER}
tr{Upper-right corner}{ACS_URCORNER}
bl{Bottom-left corner}{ACS_BLCORNER}
br{Bottom-right corner}{ACS_BRCORNER}
</description>

<properties><property kind="parameter" name="ls" required="1"/><property kind="parameter" name="rs"/><property kind="parameter" name="ts"/><property kind="parameter" name="bs"/><property kind="parameter" name="tl"/><property kind="parameter" name="tr"/><property kind="parameter" name="bl"/><property kind="parameter" name="br"/></properties></element>

<element kind="function" name="box">
<description>Similar to border(), but both ls and rs are
vertch and both ts and {bs} are horch. The default
corner characters are always used by this function.</description>

<properties><property kind="parameter" name="vertch" required="1"/><property kind="parameter" name="horch"/></properties></element>

<element kind="function" name="clear">
<description>Like erase(), but also causes the whole window to be repainted
upon next call to refresh().</description>

</element>

<element kind="function" name="clearok">
<description>If yes is 1, the next call to refresh()
will clear the window completely.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="clrtobot">
<description>Erase from cursor to the end of the window: all lines below the cursor
are deleted, and then the equivalent of clrtoeol() is performed.</description>

</element>

<element kind="function" name="clrtoeol">
<description>Erase from cursor to the end of the line.</description>

</element>

<element kind="function" name="cursyncup">
<description>Updates the current cursor position of all the ancestors of the window
to reflect the current cursor position of the window.</description>

</element>

<element kind="function" name="delch">
<description>Delete any character at (y, x).</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y"/></properties></element>

<element kind="function" name="deleteln">
<description>Delete the line under the cursor. All following lines are moved up
by 1 line.</description>

</element>

<element kind="function" name="derwin">
<description>An abbreviation for ``derive window'', derwin() is the same
as calling subwin(), except that begin_y and
begin_x are relative to the origin of the window, rather than
relative to the entire screen. Returns a window object for the
derived window.</description>

<properties><property kind="parameter" name="nlines" required="1"/><property kind="parameter" name="ncols"/><property kind="parameter" name="begin_y"/><property kind="parameter" name="begin_x begin_x"/></properties></element>

<element kind="function" name="echochar">
<description>Add character ch with attribute attr, and immediately call refresh() on the window.</description>

<properties><property kind="parameter" name="ch" required="1"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="enclose">
<description>Tests whether the given pair of screen-relative character-cell
coordinates are enclosed by the given window, returning true or
false. It is useful for determining what subset of the screen
windows enclose the location of a mouse event.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x x" required="1"/></properties></element>

<element kind="function" name="erase">
<description>Clear the window.</description>

</element>

<element kind="function" name="getbegyx">
<description>Return a tuple (y, x) of co-ordinates of upper-left
corner.</description>

</element>

<element kind="function" name="getch">
<description>Get a character. Note that the integer returned does not have to
be in ASCII range: function keys, keypad keys and so on return numbers
higher than 256. In no-delay mode, -1 is returned if there is no input.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y"/></properties></element>

<element kind="function" name="getkey">
<description>Get a character, returning a string instead of an integer, as
getch() does. Function keys, keypad keys and so on return a
multibyte string containing the key name. In no-delay mode, an
exception is raised if there is no input.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y"/></properties></element>

<element kind="function" name="getmaxyx">
<description>Return a tuple (y, x) of the height and width of
the window.</description>

</element>

<element kind="function" name="getparyx">
<description>Returns the beginning coordinates of this window relative to its
parent window into two integer variables y and x. Returns
-1,-1 if this window has no parent.</description>

</element>

<element kind="function" name="getstr">
<description>Read a string from the user, with primitive line editing capacity.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y"/></properties></element>

<element kind="function" name="getyx">
<description>Return a tuple (y, x) of current cursor position relative to the window's upper-left corner.</description>

</element>

<element kind="function" name="hline">
<description>Display a horizontal line starting at (y, x) with
length n consisting of the character ch.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="ch"/><property kind="parameter" name="n n"/></properties></element>

<element kind="function" name="idcok">
<description>If flag is false, curses no longer considers using the hardware
insert/delete character feature of the terminal; if flag is
true, use of character insertion and deletion is enabled. When curses
is first initialized, use of character insert/delete is enabled by
default.</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="idlok">
<description>If called with yes equal to 1, curses will try and use
hardware line editing facilities. Otherwise, line insertion/deletion
are disabled.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="immedok">
<description>If flag is true, any change in the window image
automatically causes the window to be refreshed; you no longer
have to call refresh() yourself. However, it may
degrade performance considerably, due to repeated calls to
wrefresh. This option is disabled by default.</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="inch">
<description>Return the character at the given position in the window. The bottom
8 bits are the character proper, and upper bits are the attributes.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y"/></properties></element>

<element kind="function" name="insch">
<description>Paint character ch at (y, x) with attributes
attr, moving the line from position x right by one
character.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="ch"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="insdelln">
<description>Inserts nlines lines into the specified window above the current
line. The nlines bottom lines are lost. For negative
nlines, delete nlines lines starting with the one under
the cursor, and move the remaining lines up. The bottom nlines
lines are cleared. The current cursor position remains the same.</description>

<properties><property kind="parameter" name="nlinesnlines" required="1"/></properties></element>

<element kind="function" name="insertln">
<description>Insert a blank line under the cursor. All following lines are moved
down by 1 line.</description>

</element>

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

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="str"/><property kind="parameter" name="n"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="insstr">
<description>Insert a character string (as many characters as will fit on the line)
before the character under the cursor. All characters to the right of
the cursor are shifted right, with the rightmost characters on the
line being lost. The cursor position does not change (after moving to
y, x, if specified).</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="str"/><property kind="parameter" name="attr"/></properties></element>

<element kind="function" name="instr">
<description>Returns a string of characters, extracted from the window starting at
the current cursor position, or at y, x if specified.
Attributes are stripped from the characters. If n is specified,
instr() returns return a string at most n characters
long (exclusive of the trailing NUL).</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="n"/></properties></element>

<element kind="function" name="is_linetouched">
<description>Returns true if the specified line was modified since the last call to
refresh(); otherwise returns false. Raises a
curses.error exception if line is not valid
for the given window.</description>

<properties><property kind="parameter" name="line" required="1"/></properties></element>

<element kind="function" name="is_wintouched">
<description>Returns true if the specified window was modified since the last call to
refresh(); otherwise returns false.</description>

</element>

<element kind="function" name="keypad">
<description>If yes is 1, escape sequences generated by some keys (keypad, function keys) will be interpreted by curses.
If yes is 0, escape sequences will be left as is in the input
stream.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="leaveok">
<description>If yes is 1, cursor is left where it is on update, instead of
being at ``cursor position.'' This reduces cursor movement where
possible. If possible the cursor will be made invisible.
If yes is 0, cursor will always be at ``cursor position'' after
an update.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="move">
<description>Move cursor to (new_y, new_x).</description>

<properties><property kind="parameter" name="new_y" required="1"/><property kind="parameter" name="new_x new_x" required="1"/></properties></element>

<element kind="function" name="mvderwin">
<description>Moves the window inside its parent window. The screen-relative
parameters of the window are not changed. This routine is used to
display different parts of the parent window at the same physical
position on the screen.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x x" required="1"/></properties></element>

<element kind="function" name="mvwin">
<description>Move the window so its upper-left corner is at
(new_y, new_x).</description>

<properties><property kind="parameter" name="new_y" required="1"/><property kind="parameter" name="new_x new_x" required="1"/></properties></element>

<element kind="function" name="nodelay">
<description>If yes is 1, getch() will be non-blocking.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="notimeout">
<description>If yes is 1, escape sequences will not be timed out.
If yes is 0, after a few milliseconds, an escape sequence
will not be interpreted, and will be left in the input stream as is.</description>

<properties><property kind="parameter" name="yesyes" required="1"/></properties></element>

<element kind="function" name="noutrefresh">
<description>Mark for refresh but wait. This function updates the data structure
representing the desired state of the window, but does not force
an update of the physical screen. To accomplish that, call doupdate().</description>

</element>

<element kind="function" name="overlay">
<description>Overlay the window on top of destwin. The windows need not be
the same size, only the overlapping region is copied. This copy is
non-destructive, which means that the current background character
does not overwrite the old contents of destwin.
To get fine-grained control over the copied region, the second form
of overlay() can be used. sminrow and smincol are
the upper-left coordinates of the source window, and the other variables
mark a rectangle in the destination window.</description>

<properties><property kind="parameter" name="destwin" required="1"/><property kind="parameter" name="sminrow"/><property kind="parameter" name="smincol"/><property kind="parameter" name="dminrow"/><property kind="parameter" name="dmincol"/><property kind="parameter" name="dmaxrow"/><property kind="parameter" name="dmaxcol"/></properties></element>

<element kind="function" name="overwrite">
<description>Overwrite the window on top of destwin. The windows need not be
the same size, in which case only the overlapping region is
copied. This copy is destructive, which means that the current
background character overwrites the old contents of destwin.
To get fine-grained control over the copied region, the second form
of overwrite() can be used. sminrow and smincol are
the upper-left coordinates of the source window, the other variables
mark a rectangle in the destination window.</description>

<properties><property kind="parameter" name="destwin" required="1"/><property kind="parameter" name="sminrow"/><property kind="parameter" name="smincol"/><property kind="parameter" name="dminrow"/><property kind="parameter" name="dmincol"/><property kind="parameter" name="dmaxrow"/><property kind="parameter" name="dmaxcol"/></properties></element>

<element kind="function" name="putwin">
<description>Writes all data associated with the window into the provided file
object. This information can be later retrieved using the
getwin() function.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="redrawln">
<description>Indicates that the num screen lines, starting at line beg,
are corrupted and should be completely redrawn on the next
refresh() call.</description>

<properties><property kind="parameter" name="beg" required="1"/><property kind="parameter" name="num num" required="1"/></properties></element>

<element kind="function" name="redrawwin">
<description>Touches the entire window, causing it to be completely redrawn on the
next refresh() call.</description>

</element>

<element kind="function" name="refresh">
<description>Update the display immediately (sync actual screen with previous
drawing/deleting methods).
The 6 optional arguments can only be specified when the window is a
pad created with newpad(). The additional parameters are
needed to indicate what part of the pad and screen are involved.
pminrow and pmincol specify the upper left-hand corner of the
rectangle to be displayed in the pad. sminrow, smincol,
smaxrow, and smaxcol specify the edges of the rectangle to
be displayed on the screen. The lower right-hand corner of the
rectangle to be displayed in the pad is calculated from the screen
coordinates, since the rectangles must be the same size. Both
rectangles must be entirely contained within their respective
structures. Negative values of pminrow, pmincol,
sminrow, or smincol are treated as if they were zero.</description>

<properties><property kind="parameter" name="pminrow" required="1"/><property kind="parameter" name="pmincol"/><property kind="parameter" name="sminrow"/><property kind="parameter" name="smincol"/><property kind="parameter" name="smaxrow"/><property kind="parameter" name="smaxcol"/></properties></element>

<element kind="function" name="scroll">
<description>Scroll the screen or scrolling region upward by lines lines.</description>

<properties><property default=" 1" kind="parameter" name="lines" required="1"/></properties></element>

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

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="setscrreg">
<description>Set the scrolling region from line top to line bottom. All
scrolling actions will take place in this region.</description>

<properties><property kind="parameter" name="top" required="1"/><property kind="parameter" name="bottom bottom" required="1"/></properties></element>

<element kind="function" name="standend">
<description>Turn off the standout attribute. On some terminals this has the
side effect of turning off all attributes.</description>

</element>

<element kind="function" name="standout">
<description>Turn on attribute A_STANDOUT.</description>

</element>

<element kind="function" name="subpad">
<description>Return a sub-window, whose upper-left corner is at
(begin_y, begin_x), and whose width/height is
ncols/nlines.</description>

<properties><property kind="parameter" name="nlines" required="1"/><property kind="parameter" name="ncols"/><property kind="parameter" name="begin_y"/><property kind="parameter" name="begin_x begin_x"/></properties></element>

<element kind="function" name="subwin">
<description>Return a sub-window, whose upper-left corner is at
(begin_y, begin_x), and whose width/height is
ncols/nlines.
By default, the sub-window will extend from the
specified position to the lower right corner of the window.</description>

<properties><property kind="parameter" name="nlines" required="1"/><property kind="parameter" name="ncols"/><property kind="parameter" name="begin_y"/><property kind="parameter" name="begin_x begin_x"/></properties></element>

<element kind="function" name="syncdown">
<description>Touches each location in the window that has been touched in any of
its ancestor windows. This routine is called by refresh(),
so it should almost never be necessary to call it manually.</description>

</element>

<element kind="function" name="syncok">
<description>If called with flag set to true, then syncup() is
called automatically whenever there is a change in the window.</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="syncup">
<description>Touches all locations in ancestors of the window that have been changed in the window.</description>

</element>

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

<properties><property kind="parameter" name="delaydelay" required="1"/></properties></element>

<element kind="function" name="touchline">
<description>Pretend count lines have been changed, starting with line
start.</description>

<properties><property kind="parameter" name="start" required="1"/><property kind="parameter" name="count count" required="1"/></properties></element>

<element kind="function" name="touchwin">
<description>Pretend the whole window has been changed, for purposes of drawing
optimizations.</description>

</element>

<element kind="function" name="untouchwin">
<description>Marks all lines in the window as unchanged since the last call to
refresh().</description>

</element>

<element kind="function" name="vline">
<description>Display a vertical line starting at (y, x) with
length n consisting of the character ch.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x"/><property kind="parameter" name="ch"/><property kind="parameter" name="n n"/></properties></element>

</group>
<group name="Constants">
<description>The curses module defines the following data members:
{ERR}
Some curses routines that return an integer, such as getch(), return ERR upon failure. {OK}
Some curses routines that return an integer, such as napms(), return OK upon success. {version}
A string representing the current version of the module. Also available as __version__.
Several constants are available to specify character cell attributes:
{l|l}{code}{Attribute}{Meaning}
A_ALTCHARSET{Alternate character set mode.}
A_BLINK{Blink mode.}
A_BOLD{Bold mode.}
A_DIM{Dim mode.}
A_NORMAL{Normal attribute.}
A_STANDOUT{Standout mode.}
A_UNDERLINE{Underline mode.}
Keys are referred to by integer constants with names starting with KEY_. The exact keycaps available are system dependent.
% XXX this table is far too large!
% XXX should this table be alphabetized?
{l|l}{code}{Key constant}{Key}
KEY_MIN{Minimum key value}
KEY_BREAK{ Break key (unreliable) }
KEY_DOWN{ Down-arrow }
KEY_UP{ Up-arrow }
KEY_LEFT{ Left-arrow }
KEY_RIGHT{ Right-arrow }
KEY_HOME{ Home key (upward+left arrow) }
KEY_BACKSPACE{ Backspace (unreliable) }
KEY_F0{ Function keys. Up to 64 function keys are supported. }
KEY_Fn{ Value of function key n }
KEY_DL{ Delete line }
KEY_IL{ Insert line }
KEY_DC{ Delete character }
KEY_IC{ Insert char or enter insert mode }
KEY_EIC{ Exit insert char mode }
KEY_CLEAR{ Clear screen }
KEY_EOS{ Clear to end of screen }
KEY_EOL{ Clear to end of line }
KEY_SF{ Scroll 1 line forward }
KEY_SR{ Scroll 1 line backward (reverse) }
KEY_NPAGE{ Next page }
KEY_PPAGE{ Previous page }
KEY_STAB{ Set tab }
KEY_CTAB{ Clear tab }
KEY_CATAB{ Clear all tabs }
KEY_ENTER{ Enter or send (unreliable) }
KEY_SRESET{ Soft (partial) reset (unreliable) }
KEY_RESET{ Reset or hard reset (unreliable) }
KEY_PRINT{ Print }
KEY_LL{ Home down or bottom (lower left) }
KEY_A1{ Upper left of keypad }
KEY_A3{ Upper right of keypad }
KEY_B2{ Center of keypad }
KEY_C1{ Lower left of keypad }
KEY_C3{ Lower right of keypad }
KEY_BTAB{ Back tab }
KEY_BEG{ Beg (beginning) }
KEY_CANCEL{ Cancel }
KEY_CLOSE{ Close }
KEY_COMMAND{ Cmd (command) }
KEY_COPY{ Copy }
KEY_CREATE{ Create }
KEY_END{ End }
KEY_EXIT{ Exit }
KEY_FIND{ Find }
KEY_HELP{ Help }
KEY_MARK{ Mark }
KEY_MESSAGE{ Message }
KEY_MOVE{ Move }
KEY_NEXT{ Next }
KEY_OPEN{ Open }
KEY_OPTIONS{ Options }
KEY_PREVIOUS{ Prev (previous) }
KEY_REDO{ Redo }
KEY_REFERENCE{ Ref (reference) }
KEY_REFRESH{ Refresh }
KEY_REPLACE{ Replace }
KEY_RESTART{ Restart }
KEY_RESUME{ Resume }
KEY_SAVE{ Save }
KEY_SBEG{ Shifted Beg (beginning) }
KEY_SCANCEL{ Shifted Cancel }
KEY_SCOMMAND{ Shifted Command }
KEY_SCOPY{ Shifted Copy }
KEY_SCREATE{ Shifted Create }
KEY_SDC{ Shifted Delete char }
KEY_SDL{ Shifted Delete line }
KEY_SELECT{ Select }
KEY_SEND{ Shifted End }
KEY_SEOL{ Shifted Clear line }
KEY_SEXIT{ Shifted Dxit }
KEY_SFIND{ Shifted Find }
KEY_SHELP{ Shifted Help }
KEY_SHOME{ Shifted Home }
KEY_SIC{ Shifted Input }
KEY_SLEFT{ Shifted Left arrow }
KEY_SMESSAGE{ Shifted Message }
KEY_SMOVE{ Shifted Move }
KEY_SNEXT{ Shifted Next }
KEY_SOPTIONS{ Shifted Options }
KEY_SPREVIOUS{ Shifted Prev }
KEY_SPRINT{ Shifted Print }
KEY_SREDO{ Shifted Redo }
KEY_SREPLACE{ Shifted Replace }
KEY_SRIGHT{ Shifted Right arrow }
KEY_SRSUME{ Shifted Resume }
KEY_SSAVE{ Shifted Save }
KEY_SSUSPEND{ Shifted Suspend }
KEY_SUNDO{ Shifted Undo }
KEY_SUSPEND{ Suspend }
KEY_UNDO{ Undo }
KEY_MOUSE{ Mouse event has occurred }
KEY_RESIZE{ Terminal resize event }
KEY_MAX{Maximum key value}
On VT100s and their software emulations, such as X terminal emulators,
there are normally at least four function keys (KEY_F1,
KEY_F2, KEY_F3, KEY_F4) available,
and the arrow keys mapped to KEY_UP, KEY_DOWN,
KEY_LEFT and KEY_RIGHT in the obvious way. If
your machine has a PC keybboard, it is safe to expect arrow keys and
twelve function keys (older PC keyboards may have only ten function
keys); also, the following keypad mappings are standard:
{l|l}{kbd}{Keycap}{Constant}
Insert{KEY_IC}
Delete{KEY_DC}
Home{KEY_HOME}
End{KEY_END}
Page Up{KEY_NPAGE}
Page Down{KEY_PPAGE}
The following table lists characters from the alternate character set.
These are inherited from the VT100 terminal, and will generally be available on software emulations such as X terminals. When there
is no graphic available, curses falls back on a crude printable ASCII
approximation.
These are available only after initscr() has been called.
{l|l}{code}{ACS code}{Meaning}
ACS_BBSS{alternate name for upper right corner}
ACS_BLOCK{solid square block}
ACS_BOARD{board of squares}
ACS_BSBS{alternate name for horizontal line}
ACS_BSSB{alternate name for upper left corner}
ACS_BSSS{alternate name for top tee}
ACS_BTEE{bottom tee}
ACS_BULLET{bullet}
ACS_CKBOARD{checker board (stipple)}
ACS_DARROW{arrow pointing down}
ACS_DEGREE{degree symbol}
ACS_DIAMOND{diamond}
ACS_GEQUAL{greater-than-or-equal-to}
ACS_HLINE{horizontal line}
ACS_LANTERN{lantern symbol}
ACS_LARROW{left arrow}
ACS_LEQUAL{less-than-or-equal-to}
ACS_LLCORNER{lower left-hand corner}
ACS_LRCORNER{lower right-hand corner}
ACS_LTEE{left tee}
ACS_NEQUAL{not-equal sign}
ACS_PI{letter pi}
ACS_PLMINUS{plus-or-minus sign}
ACS_PLUS{big plus sign}
ACS_RARROW{right arrow}
ACS_RTEE{right tee}
ACS_S1{scan line 1}
ACS_S3{scan line 3}
ACS_S7{scan line 7}
ACS_S9{scan line 9}
ACS_SBBS{alternate name for lower right corner}
ACS_SBSB{alternate name for vertical line}
ACS_SBSS{alternate name for right tee}
ACS_SSBB{alternate name for lower left corner}
ACS_SSBS{alternate name for bottom tee}
ACS_SSSB{alternate name for left tee}
ACS_SSSS{alternate name for crossover or big plus}
ACS_STERLING{pound sterling}
ACS_TTEE{top tee}
ACS_UARROW{up arrow}
ACS_ULCORNER{upper left corner}
ACS_URCORNER{upper right corner}
ACS_VLINE{vertical line}
The following table lists the predefined colors:
{l|l}{code}{Constant}{Color}
COLOR_BLACK{Black}
COLOR_BLUE{Blue}
COLOR_CYAN{Cyan (light greenish blue)}
COLOR_GREEN{Green}
COLOR_MAGENTA{Magenta (purplish red)}
COLOR_RED{Red}
COLOR_WHITE{White}
COLOR_YELLOW{Yellow}
curses.textpad ---
Text input widget for curses programs
Emacs-like input editing in a curses window.
New in version 1.6
The curses.textpad module provides a Textbox class
that handles elementary text editing in a curses window, supporting a
set of keybindings resembling those of Emacs (thus, also of Netscape
Navigator, BBedit 6.x, FrameMaker, and many other programs). The
module also provides a rectangle-drawing function useful for framing
text boxes or for other purposes.
The module curses.textpad defines the following function:
</description>
<element kind="function" name="rectangle">
<description>Draw a rectangle. The first argument must be a window object; the
remaining arguments are coordinates relative to that window. The
second and third arguments are the y and x coordinates of the upper
left hand corner of the rectangle To be drawn; the fourth and fifth
arguments are the y and x coordinates of the lower right hand corner.
The rectangle will be drawn using VT100/IBM PC forms characters on
terminals that make this possible (including xterm and most other
software terminal emulators). Otherwise it will be drawn with ASCII dashes, vertical bars, and plus signs.</description>

<properties><property kind="parameter" name="win" required="1"/><property kind="parameter" name="uly" required="1"/><property kind="parameter" name="ulx" required="1"/><property kind="parameter" name="lry" required="1"/><property kind="parameter" name="lrx lrx" required="1"/></properties></element>

</group>
<group name="Textbox objects">
<description>You can instantiate a Textbox object as follows:
</description>
<element kind="function" name="Textbox">
<description>Return a textbox widget object. The win argument should be a
curses WindowObject in which the textbox is to be contained.
The edit cursor of the textbox is initially located at the upper left
hand corner of the containin window, with coordinates (0, 0).
The instance's stripspaces flag is initially on.</description>

<properties><property kind="parameter" name="winwin" required="1"/></properties></element>

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

<properties><property kind="parameter" name="validator" required="1"/></properties></element>

<element kind="function" name="do_command">
<description>Process a single command keystroke. Here are the supported special
keystrokes: {l|l}{kbd}{Keystroke}{Action}
Control-A{Go to left edge of window.}
Control-B{Cursor left, wrapping to previous line if appropriate.}
Control-D{Delete character under cursor.}
Control-E{Go to right edge (stripspaces off) or end of line
(stripspaces on).}
Control-F{Cursor right, wrapping to next line when appropriate.}
Control-G{Terminate, returning the window contents.}
Control-H{Delete character backward.}
Control-J{Terminate if the window is 1 line, otherwise
insert newline.}
Control-K{If line is blank, delete it, otherwise clear to
end of line.}
Control-L{Refresh screen.}
Control-N{Cursor down; move down one line.}
Control-O{Insert a blank line at cursor location.}
Control-P{Cursor up; move up one line.}
Move operations do nothing if the cursor is at an edge where the
movement is not possible. The following synonyms are supported where
possible:
{l|l}{constant}{Constant}{Keystroke}
KEY_LEFT{Control-B}
KEY_RIGHT{Control-F}
KEY_UP{Control-P}
KEY_DOWN{Control-N}
KEY_BACKSPACE{Control-h}
All other keystrokes are treated as a command to insert the given
character and move right (with line wrapping).</description>

<properties><property kind="parameter" name="chch" required="1"/></properties></element>

<element kind="function" name="gather">
<description>This method returns the window contents as a string; whether blanks in
the window are included is affected by the stripspaces
member.</description>

</element>

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

<properties><property kind="parameter" name="func" required="1"/><property kind="parameter" name="moreargsmoreargs" required="1"/></properties></element>

</group>
</group>
<group name="curses.ascii --- Utilities for ASCII characters">
<description>Constants and set-membership functions for
.
New in version 1.6
The curses.ascii module supplies name constants for
ASCII characters and functions to test membership in various
ASCII character classes. The constants supplied are names for
control characters as follows:
{l|l}{constant}{Name}{Meaning}
NUL{}
SOH{Start of heading, console interrupt}
STX{Start of text}
ETX{End of text}
EOT{End of transmission}
ENQ{Enquiry, goes with ACK flow control}
ACK{Acknowledgement}
BEL{Bell}
BS{Backspace}
TAB{Tab}
HT{Alias for TAB: ``Horizontal tab''}
LF{Line feed}
NL{Alias for LF: ``New line''}
VT{Vertical tab}
FF{Form feed}
CR{Carriage return}
SO{Shift-out, begin alternate character set}
SI{Shift-in, resume default character set}
DLE{Data-link escape}
DC1{XON, for flow control}
DC2{Device control 2, block-mode flow control}
DC3{XOFF, for flow control}
DC4{Device control 4}
NAK{Negative acknowledgement}
SYN{Synchronous idle}
ETB{End transmission block}
CAN{Cancel}
EM{End of medium}
SUB{Substitute}
ESC{Escape}
FS{File separator}
GS{Group separator}
RS{Record separator, block-mode terminator}
US{Unit separator}
SP{Space}
DEL{Delete}
Note that many of these have little practical significance in modern
usage. The mnemonics derive from teleprinter conventions that predate
digital computers.
The module supplies the following functions, patterned on those in the
standard C library:
</description>
<element kind="function" name="isalnum">
<description>Checks for an ASCII alphanumeric character; it is equivalent to
isalpha(c) or isdigit(c).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isalpha">
<description>Checks for an ASCII alphabetic character; it is equivalent to
isupper(c) or islower(c).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isascii">
<description>Checks for a character value that fits in the 7-bit ASCII set.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isblank">
<description>Checks for an ASCII whitespace character.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="iscntrl">
<description>Checks for an ASCII control character (in the range 0x00 to 0x1f).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isdigit">
<description>Checks for an ASCII decimal digit, 0 through
9. This is equivalent to c in string.digits.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isgraph">
<description>Checks for ASCII any printable character except space.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="islower">
<description>Checks for an ASCII lower-case character.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isprint">
<description>Checks for any ASCII printable character including space.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="ispunct">
<description>Checks for any printable ASCII character which is not a space or an
alphanumeric character.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isspace">
<description>Checks for ASCII white-space characters; space, line feed,
carriage return, form feed, horizontal tab, vertical tab.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isupper">
<description>Checks for an ASCII uppercase letter.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isxdigit">
<description>Checks for an ASCII hexadecimal digit. This is equivalent to
c in string.hexdigits.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="isctrl">
<description>Checks for an ASCII control character (ordinal values 0 to 31).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="ismeta">
<description>Checks for a non-ASCII character (ordinal values 0x80 and above).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="ascii">
<description>Return the ASCII value corresponding to the low 7 bits of c.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="ctrl">
<description>Return the control character corresponding to the given character
(the character bit value is bitwise-anded with 0x1f).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="alt">
<description>Return the 8-bit character corresponding to the given ASCII character
(the character bit value is bitwise-ored with 0x80).</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

<element kind="function" name="unctrl">
<description>Return a string representation of the ASCII character c. If
c is printable, this string is the character itself. If the
character is a control character (0x00-0x1f) the string consists of a
caret (^) followed by the corresponding uppercase letter.
If the character is an ASCII delete (0x7f) the string is
''. If the character has its meta bit (0x80) set, the meta
bit is stripped, the preceding rules applied, and
! prepended to the result.</description>

<properties><property kind="parameter" name="cc" required="1"/></properties></element>

</group>
<group name="curses.panel --- A panel stack extension for curses.">
<description>A panel stack extension that adds depth to curses windows.
Panels are windows with the added feature of depth, so they can be
stacked on top of each other, and only the visible portions of
each window will be displayed. Panels can be added, moved up
or down in the stack, and removed. </description>
<group name="Functions">
<description>The module curses.panel defines the following functions:
</description>
<element kind="function" name="bottom_panel">
<description>Returns the bottom panel in the panel stack.</description>

</element>

<element kind="function" name="new_panel">
<description>Returns a panel object, associating it with the given window win.</description>

<properties><property kind="parameter" name="winwin" required="1"/></properties></element>

<element kind="function" name="top_panel">
<description>Returns the top panel in the panel stack.</description>

</element>

<element kind="function" name="update_panels">
<description>Updates the virtual screen after changes in the panel stack. This does
not call curses.doupdate(), so you'll have to do this yourself.</description>

</element>

</group>
<group name="Panel Objects">
<description>Panel objects, as returned by new_panel() above, are windows
with a stacking order. There's always a window associated with a
panel which determines the content, while the panel methods are
responsible for the window's depth in the panel stack.
Panel objects have the following methods:
</description>
<element kind="function" name="above">
<description>Returns the panel above the current panel.</description>

</element>

<element kind="function" name="below">
<description>Returns the panel below the current panel.</description>

</element>

<element kind="function" name="bottom">
<description>Push the panel to the bottom of the stack.</description>

</element>

<element kind="function" name="hidden">
<description>Returns true if the panel is hidden (not visible), false otherwise.</description>

</element>

<element kind="function" name="hide">
<description>Hide the panel. This does not delete the object, it just makes the
window on screen invisible.</description>

</element>

<element kind="function" name="move">
<description>Move the panel to the screen coordinates (y, x).</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="x x" required="1"/></properties></element>

<element kind="function" name="replace">
<description>Change the window associated with the panel to the window win.</description>

<properties><property kind="parameter" name="winwin" required="1"/></properties></element>

<element kind="function" name="set_userptr">
<description>Set the panel's user pointer to obj. This is used to associate an
arbitrary piece of data with the panel, and can be any Python object.</description>

<properties><property kind="parameter" name="objobj" required="1"/></properties></element>

<element kind="function" name="show">
<description>Display the panel (which might have been hidden).</description>

</element>

<element kind="function" name="top">
<description>Push panel to the top of the stack.</description>

</element>

<element kind="function" name="userptr">
<description>Returns the user pointer for the panel. This might be any Python object.</description>

</element>

<element kind="function" name="window">
<description>Returns the window object associated with the panel.</description>

</element>

</group>
</group>
<group name="getopt --- Parser for command line options">
<description>Portable parser for command line options; support both
short and long option names.
This module helps scripts to parse the command line arguments in
sys.argv.
It supports the same conventions as the getopt()
function (including the special meanings of arguments of the form
`-' and `--').
% That's to fool latex2html into leaving the two hyphens alone!
Long options similar to those supported by
GNU software may be used as well via an optional third argument.
This module provides a single function and an exception:
</description>
<element kind="function" name="getopt">
<description>Parses command line options and parameter list. args is the
argument list to be parsed, without the leading reference to the
running program. Typically, this means sys.argv[1:].
options 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 getopt() uses).
Unlike GNU getopt(), after a non-option
argument, all further arguments are considered also non-options.
This is similar to the way non-GNU systems work.
long_options, if specified, must be 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. Long options which require an argument should be followed by an
equal sign (=). To accept only long options,
options should be an empty string. Long options on the command
line can be recognized so long as they provide a prefix of the option
name that matches exactly one of the accepted options. For example,
it long_options is ['foo', 'frob'], the option
fo will match as foo, but
f will not match uniquely, so GetoptError
will be raised.
The return value consists of two elements: the first is a list of
(option, value) pairs; the second is the list of
program arguments left after the option list was stripped (this is a
trailing slice of args). Each option-and-value pair returned
has the option as its first element, prefixed with a hyphen for short
options (e.g., '-x') or two hyphens for long options (e.g.,
'--long-option'), 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.</description>

<properties><property kind="parameter" name="args" required="1"/><property kind="parameter" name="options" required="1"/><property kind="parameter" name="long_options"/></properties></element>

<element kind="function" name="gnu_getopt">
<description>This function works like getopt(), except that GNU style
scanning mode is used by default. This means that option and
non-option arguments may be intermixed. The getopt()
function stops processing options as soon as a non-option argument is
encountered.
If the first character of the option string is `+', or if the
environment variable POSIXLY_CORRECT is set, then option processing
stops as soon as a non-option argument is encountered.</description>

<properties><property kind="parameter" name="args" required="1"/><property kind="parameter" name="options" required="1"/><property kind="parameter" name="long_options"/></properties></element>

</group>
<group name="optparse --- Powerful parser for command line options.">
<description>Powerful, flexible, extensible, easy-to-use command-line
parsing library.
New in version 2.3
The optparse module is a powerful, flexible, extensible,
easy-to-use command-line parsing library for Python. Using
optparse, you can add intelligent, sophisticated handling of
command-line options to your scripts with very little overhead.
Here's an example of using optparse to add some command-line
options to a simple script:
from optparse import OptionParser
parser = OptionParser()
parser.add_option(&quot;-f&quot;, &quot;--file&quot;, dest=&quot;filename&quot;,
help=&quot;write report to FILE&quot;, metavar=&quot;FILE&quot;)
parser.add_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_false&quot;, dest=&quot;verbose&quot;, default=True,
help=&quot;don't print status messages to stdout&quot;)
(options, args) = parser.parse_args()
With these few lines of code, users of your script can now do the
``usual thing'' on the command-line:
$ &lt;yourscript&gt; -f outfile --quiet
$ &lt;yourscript&gt; -qfoutfile
$ &lt;yourscript&gt; --file=outfile -q
$ &lt;yourscript&gt; --quiet --file outfile
(All of these result in options.filename == &quot;outfile&quot; and
options.verbose == False, just as you might expect.)
Even niftier, users can run one of
$ &lt;yourscript&gt; -h
$ &lt;yourscript&gt; --help
and optparse will print out a brief summary of your script's
options:
usage: &lt;yourscript&gt; [options]
options:
-h, --help show this help message and exit
-fFILE, --file=FILE write report to FILE
-q, --quiet don't print status messages to stdout
That's just a taste of the flexibility optparse gives you in
parsing your command-line.
</description>
<group name="Philosophy">
<description>The purpose of optparse is to make it very easy to provide the
most standard, obvious, straightforward, and user-friendly user
interface for command-line programs. The optparse
philosophy is heavily influenced by the and GNU toolkits, and
this section is meant to explain that philosophy.
Terminology
First, we need to establish some terminology.
argument
a chunk of text that a user enters on the command-line, and that the
shell passes to execl() or execv(). In
Python, arguments are elements of
sys.argv[1:]. (sys.argv[0] is the name of the program
being executed; in the context of parsing arguments, it's not very
important.) shells also use the term ``word''.
It is occasionally desirable to use an argument list other than
sys.argv[1:], so you should read ``argument'' as ``an element of
sys.argv[1:], or of some other list provided as a substitute for
sys.argv[1:]''.
option
an argument used to supply extra information to guide or customize
the execution of a program. There are many different syntaxes for
options; the traditional syntax is - followed by a
single letter, e.g. -x or -F. Also,
traditional syntax allows multiple options to be merged into a
single argument, e.g. -x -F is equivalent to
-xF. The GNU project introduced followed by a series of hyphen-separated words,
e.g. file or dry-run. These are
the only two option syntaxes provided by optparse.
Some other option syntaxes that the world has seen include:
a hyphen followed by a few letters, e.g. -pf (this is
not the same as multiple options merged into a single
argument.)
a hyphen followed by a whole word, e.g. -file (this is
technically equivalent to the previous syntax, but they aren't
usually seen in the same program.)
a plus sign followed by a single letter, or a few letters,
or a word, e.g. +f, +rgb.
a slash followed by a letter, or a few letters, or a word, e.g.
/f, /file.
optparse does not support these option syntaxes, and it never
will. (If you really want to use one of those option syntaxes, you'll
have to subclass OptionParser and override all the difficult
bits. But please don't! optparse does things the traditional
/GNU way deliberately; the first three are non-standard anywhere,
and the last one makes sense only if you're exclusively targeting
MS-DOS/Windows and/or VMS.)
option argument
an argument that follows an option, is closely associated with that
option, and is consumed from the argument list when the option is.
Often, option arguments may also be included in the same argument as
the option, e.g. :
[&quot;-f&quot;, &quot;foo&quot;]
may be equivalent to:
[&quot;-ffoo&quot;]
(optparse supports this syntax.)
Some options never take an argument. Some options always take an
argument. Lots of people want an ``optional option arguments'' feature,
meaning that some options will take an argument if they see it, and
won't if they don't. This is somewhat controversial, because it makes
parsing ambiguous: if -a and -b are both
options, and -a takes an optional argument, how do we
interpret -ab? optparse does not support optional
option arguments.
positional argument
something leftover in the argument list after options have been
parsed, i.e., after options and their arguments have been parsed and
removed from the argument list.
required option
an option that must be supplied on the command-line. The phrase
``required option'' is an oxymoron; the presence of ``required options''
in a program is usually a sign of careless user interface design.
optparse doesn't prevent you from implementing required
options, but doesn't give you much help with it either. See ``Extending
Examples'' (section~optparse-extending-examples) for two ways to
implement required options with optparse.
For example, consider this hypothetical command-line:
prog -v --report /tmp/report.txt foo bar
-v and report are both options. Assuming
the report option takes one argument,
/tmp/report.txt is an option argument. foo and bar
are positional arguments.
What are options for?
Options are used to provide extra information to tune or customize the
execution of a program. In case it wasn't clear, options should be
optional. A program should be able to run just fine with no
options whatsoever. (Pick a random program from the or GNU
toolsets. Can it run without any options at all and still make sense?
The only exceptions I can think of are find, tar,
and dd---all of which are mutant oddballs that have been
rightly criticized for their non-standard syntax and confusing
interfaces.)
Lots of people want their programs to have ``required options''.
Think about it. If it's required, then it's not optional! If
there is a piece of information that your program absolutely requires
in order to run successfully, that's what positional arguments are
for. (However, if you insist on adding ``required options'' to your
programs, look in ``Extending Examples''
(section~optparse-extending-examples) for two ways of
implementing them with optparse.)
Consider the humble cp utility, for copying files. It
doesn't make much sense to try to copy files without supplying a
destination and at least one source. Hence, cp fails if you
run it with no arguments. However, it has a flexible, useful syntax
that does not rely on options at all:
$ cp SOURCE DEST
$ cp SOURCE ... DEST-DIR
You can get pretty far with just that. Most cp
implementations provide a bunch of options to tweak exactly how the
files are copied: you can preserve mode and modification time, avoid
following symlinks, ask before clobbering existing files, etc. But
none of this distracts from the core mission of cp, which is
to copy one file to another, or N files to another directory.
What are positional arguments for? In case it wasn't clear from the above example: positional arguments
are for those pieces of information that your program absolutely,
positively requires to run.
A good user interface should have as few absolute requirements as
possible. If your program requires 17 distinct pieces of information in
order to run successfully, it doesn't much matter how you get that
information from the user---most people will give up and walk away
before they successfully run the program. This applies whether the user
interface is a command-line, a configuration file, a GUI, or whatever:
if you make that many demands on your users, most of them will just give
up.
In short, try to minimize the amount of information that users are
absolutely required to supply---use sensible defaults whenever
possible. Of course, you also want to make your programs reasonably
flexible. That's what options are for. Again, it doesn't matter if
they are entries in a config file, checkboxes in the ``Preferences''
dialog of a GUI, or command-line options---the more options you
implement, the more flexible your program is, and the more complicated
its implementation becomes. It's quite easy to overwhelm users (and
yourself!) with too much flexibility, so be careful there.
</description>
</group>
<group name="Basic Usage">
<description>While optparse is quite flexible and powerful, you don't have
to jump through hoops or read reams of documentation to get it working
in basic cases. This document aims to demonstrate some simple usage
patterns that will get you started using optparse in your
scripts.
To parse a command line with optparse, you must create an
OptionParser instance and populate it. Obviously, you'll have
to import the OptionParser classes in any script that uses
optparse:
from optparse import OptionParser
Early on in the main program, create a parser:
parser = OptionParser()
Then you can start populating the parser with options. Each option is
really a set of synonymous option strings; most commonly, you'll have
one short option string and one long option string ---
e.g. -f and file:
parser.add_option(&quot;-f&quot;, &quot;--file&quot;, ...)
The interesting stuff, of course, is what comes after the option
strings. For now, we'll only cover four of the things you can put
there: action, type, dest (destination), and
help.
The store action%
The action tells optparse what to do when it sees one of the
option strings for this option on the command-line. For example, the
action store means: take the next argument (or the remainder of
the current argument), ensure that it is of the correct type, and
store it to your chosen destination.
For example, let's fill in the ``...'' of that last option:
parser.add_option(&quot;-f&quot;, &quot;--file&quot;,
action=&quot;store&quot;, type=&quot;string&quot;, dest=&quot;filename&quot;)
Now let's make up a fake command-line and ask optparse to
parse it:
args = [&quot;-f&quot;, &quot;foo.txt&quot;]
(options, args) = parser.parse_args(args)
(Note that if you don't pass an argument list to
parse_args(), it automatically uses sys.argv[1:].)
When optparse sees the -f, it consumes the next
argument---foo.txt---and stores it in the filename
attribute of a special object. That object is the first return value
from parse_args(), so:
print options.filename
will print foo.txt.
Other option types supported by optparse are int and
float. Here's an option that expects an integer argument:
parser.add_option(&quot;-n&quot;, type=&quot;int&quot;, dest=&quot;num&quot;)
This example doesn't provide a long option, which is perfectly
acceptable. It also doesn't specify the action---it defaults to
``store''.
Let's parse another fake command-line. This time, we'll jam the option
argument right up against the option, since -n42 (one
argument) is equivalent to -n 42 (two arguments).
(options, args) = parser.parse_args([&quot;-n42&quot;])
print options.num
This prints 42.
Trying out the ``float'' type is left as an exercise for the reader.
If you don't specify a type, optparse assumes ``string''.
Combined with the fact that the default action is ``store'', that
means our first example can be a lot shorter:
parser.add_option(&quot;-f&quot;, &quot;--file&quot;, dest=&quot;filename&quot;)
If you don't supply a destination, optparse figures out a
sensible default from the option strings: if the first long option
string is foo-bar, then the default destination is
foo_bar. If there are no long option strings,
optparse looks at the first short option: the default
destination for -f is f.
Adding types is fairly easy; please refer to
section~optparse-adding-types, ``Adding new types.''
Other store_* actions%
Flag options---set a variable to true or false when a particular
option is seen---are quite common. optparse supports them
with two separate actions, ``store_true'' and ``store_false''. For
example, you might have a verbose flag that is turned on with
-v and off with -q:
parser.add_option(&quot;-v&quot;, action=&quot;store_true&quot;, dest=&quot;verbose&quot;)
parser.add_option(&quot;-q&quot;, action=&quot;store_false&quot;, dest=&quot;verbose&quot;)
Here we have two different options with the same destination, which is
perfectly OK. (It just means you have to be a bit careful when setting
default values---see below.)
When optparse sees -v on the command line, it sets
options.verbose to True; when it sees -q, it
sets options.verbose to False.
Setting default values
All of the above examples involve setting some variable (the
``destination'') when certain command-line options are seen. What
happens if those options are never seen? Since we didn't supply any
defaults, they are all set to None. Sometimes, this is just fine (which
is why it's the default), but sometimes, you want more control. To
address that need, optparse lets you supply a default value for
each destination, which is assigned before the command-line is parsed.
First, consider the verbose/quiet example. If we want
optparse to set verbose to True unless
-q is seen, then we can do this:
parser.add_option(&quot;-v&quot;, action=&quot;store_true&quot;, dest=&quot;verbose&quot;, default=True)
parser.add_option(&quot;-q&quot;, action=&quot;store_false&quot;, dest=&quot;verbose&quot;)
Oddly enough, this is exactly equivalent:
parser.add_option(&quot;-v&quot;, action=&quot;store_true&quot;, dest=&quot;verbose&quot;)
parser.add_option(&quot;-q&quot;, action=&quot;store_false&quot;, dest=&quot;verbose&quot;, default=True)
Those are equivalent because you're supplying a default value for the
option's destination, and these two options happen to have the same
destination (the verbose variable).
Consider this:
parser.add_option(&quot;-v&quot;, action=&quot;store_true&quot;, dest=&quot;verbose&quot;, default=False)
parser.add_option(&quot;-q&quot;, action=&quot;store_false&quot;, dest=&quot;verbose&quot;, default=True)
Again, the default value for verbose will be True: the last
default value supplied for any particular destination is the one that
counts.
Generating help
The last feature that you will use in every script is
optparse's ability to generate help messages. All you have
to do is supply a help argument when you add an option. Let's
create a new parser and populate it with user-friendly (documented)
options:
usage = &quot;usage: %prog [options] arg1 arg2&quot;
parser = OptionParser(usage=usage)
parser.add_option(&quot;-v&quot;, &quot;--verbose&quot;,
action=&quot;store_true&quot;, dest=&quot;verbose&quot;, default=True,
help=&quot;make lots of noise [default]&quot;)
parser.add_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_false&quot;, dest=&quot;verbose&quot;, help=&quot;be vewwy quiet (I'm hunting wabbits)&quot;)
parser.add_option(&quot;-f&quot;, &quot;--file&quot;, dest=&quot;filename&quot;,
metavar=&quot;FILE&quot;, help=&quot;write output to FILE&quot;),
parser.add_option(&quot;-m&quot;, &quot;--mode&quot;,
default=&quot;intermediate&quot;,
help=&quot;interaction mode: one of 'novice', &quot;
&quot;'intermediate' [default], 'expert'&quot;)
If optparse encounters either -h or
help on the command-line, or if you just call
parser.print_help(), it prints the following to stdout:
usage: &lt;yourscript&gt; [options] arg1 arg2
options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-fFILE, --file=FILE write output to FILE
-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
[default], 'expert'
There's a lot going on here to help optparse generate the
best possible help message:
the script defines its own usage message:
usage = &quot;usage: %prog [options] arg1 arg2&quot;
optparse expands in the usage string to the name of the
current script, i.e. os.path.basename(sys.argv[0]). The
expanded string is then printed before the detailed option help.
If you don't supply a usage string, optparse uses a bland but
sensible default: &quot;usage: [options]&quot;, which is fine if your
script doesn't take any positional arguments.
every option defines a help string, and doesn't worry about line-wrapping---optparse takes care of wrapping lines and making the help output look good.
options that take a value indicate this fact in their
automatically-generated help message, e.g. for the ``mode'' option:
-mMODE, --mode=MODE
Here, ``MODE'' is called the meta-variable: it stands for the argument
that the user is expected to supply to
-m/mode. By default, optparse
converts the destination variable name to uppercase and uses that for
the meta-variable. Sometimes, that's not what you want---for
example, the filename option explicitly sets
metavar=&quot;FILE&quot;, resulting in this automatically-generated
option description:
-fFILE, --file=FILE
This is important for more than just saving space, though: the
manually written help text uses the meta-variable ``FILE'', to clue
the user in that there's a connection between the formal syntax
``-fFILE'' and the informal semantic description ``write output to
FILE''. This is a simple but effective way to make your help text a
lot clearer and more useful for end users.
When dealing with many options, it is convenient to group these
options for better help output. An OptionParser can contain
several option groups, each of which can contain several options.
Continuing with the parser defined above, adding an
OptionGroup to a parser is easy:
group = OptionGroup(parser, &quot;Dangerous Options&quot;,
&quot;Caution: use these options at your own risk. &quot;
&quot;It is believed that some of them bite.&quot;)
group.add_option(&quot;-g&quot;, action=&quot;store_true&quot;, help=&quot;Group option.&quot;)
parser.add_option_group(group)
This would result in the following help output:
usage: [options] arg1 arg2
options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-fFILE, --file=FILE write output to FILE
-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
[default], 'expert'
Dangerous Options:
Caution: use of these options is at your own risk. It is believed that
some of them bite.
-g Group option.
Print a version number
Similar to the brief usage string, optparse can also print a
version string for your program. You have to supply the string, as
the version argument to OptionParser:
parser = OptionParser(usage=&quot;%prog [-f] [-q]&quot;, version=&quot;%prog 1.0&quot;)
version can contain anything you like; is expanded
in version just as with usage. When you supply it,
optparse automatically adds a version option
to your parser. If it encounters this option on the command line, it
expands your version string (by replacing ), prints
it to stdout, and exits.
For example, if your script is called /usr/bin/foo, a user might do:
$ /usr/bin/foo --version
foo 1.0
% $ (avoid confusing emacs)
Error-handling
The one thing you need to know for basic usage is how
optparse behaves when it encounters an error on the
command-line---e.g. -n 4x where -n is an
integer-valued option. In this case, optparse prints your
usage message to stderr, followed by a useful and human-readable error
message. Then it terminates (calls sys.exit()) with a
non-zero exit status.
If you don't like this, subclass OptionParser and override the
error() method. See section~optparse-extending,
``Extending optparse.''
Putting it all together
Here's what optparse-based scripts typically look like:
from optparse import OptionParser
[...]
def main():
usage = &quot;usage: [-f] [-v] [-q] firstarg secondarg&quot;
parser = OptionParser(usage)
parser.add_option(&quot;-f&quot;, &quot;--file&quot;, type=&quot;string&quot;, dest=&quot;filename&quot;,
help=&quot;read data from FILENAME&quot;)
parser.add_option(&quot;-v&quot;, &quot;--verbose&quot;,
action=&quot;store_true&quot;, dest=&quot;verbose&quot;)
parser.add_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_false&quot;, dest=&quot;verbose&quot;)
(options, args) = parser.parse_args()
if len(args) != 1:
parser.error(&quot;incorrect number of arguments&quot;)
if options.verbose:
print &quot;reading ...&quot; % options.filename
[... go to work ...]
if __name__ == &quot;__main__&quot;:
main()
</description>
</group>
<group name="Advanced Usage">
<description>Creating and populating the
parser
There are several ways to populate the parser with options. One way
is to pass a list of Options to the OptionParser
constructor:
from optparse import OptionParser, make_option
[...]
parser = OptionParser(option_list=[
make_option(&quot;-f&quot;, &quot;--filename&quot;,
action=&quot;store&quot;, type=&quot;string&quot;, dest=&quot;filename&quot;),
make_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_false&quot;, dest=&quot;verbose&quot;)])
(make_option() is a factory function for generating
Option objects.)
For long option lists, it may be more convenient/readable to create the
list separately:
option_list = [make_option(&quot;-f&quot;, &quot;--filename&quot;,
action=&quot;store&quot;, type=&quot;string&quot;, dest=&quot;filename&quot;),
[... more options ...]
make_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_false&quot;, dest=&quot;verbose&quot;)]
parser = OptionParser(option_list=option_list)
Or, you can use the add_option() method of
OptionParser to add options one-at-a-time:
parser = OptionParser()
parser.add_option(&quot;-f&quot;, &quot;--filename&quot;,
action=&quot;store&quot;, type=&quot;string&quot;, dest=&quot;filename&quot;)
parser.add_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_false&quot;, dest=&quot;verbose&quot;)
This method makes it easier to track down exceptions raised by the
Option constructor, which are common because of the complicated
interdependencies among the various keyword arguments. (If you get it
wrong, optparse raises OptionError.)
add_option() can be called in one of two ways:
pass it an Option instance (as returned by make_option())
pass it any combination of positional and keyword arguments that
are acceptable to make_option() (i.e., to the Option
constructor), and it will create the Option instance for you
(shown above).
Defining options
Each Option instance represents a set of synonymous
command-line options, i.e. options that have the same meaning and
effect, but different spellings. You can specify any number of short
or long option strings, but you must specify at least one option
string.
To define an option with only a short option string:
make_option(&quot;-f&quot;, ...)
And to define an option with only a long option string:
make_option(&quot;--foo&quot;, ...)
The ``...'' represents a set of keyword arguments that define attributes
of the Option object. The rules governing which keyword args
you must supply for a given Option are fairly complicated, but
you always have to supply some. If you get it wrong,
optparse raises an OptionError exception explaining
your mistake.
The most important attribute of an option is its action, i.e. what to do
when we encounter this option on the command-line. The possible actions
are:
{l|l}{code}{Action}{Meaning}
store{store this option's argument (default)}
store_const{store a constant value}
store_true{store a true value}
store_false{store a false value}
append{append this option's argument to a list}
count{increment a counter by one}
callback{call a specified function}
help{print a usage message including all options and the
documentation for them} (If you don't supply an action, the default is ``store''. For this
action, you may also supply type and dest keywords; see
below.)
As you can see, most actions involve storing or updating a value
somewhere. optparse always creates a particular object (an
instance of the Values class) specifically for this
purpose. Option arguments (and various other values) are stored as
attributes of this object, according to the dest (destination)
argument to make_option()/add_option().
For example, when you call:
parser.parse_args()
one of the first things optparse does is create a
values object:
values = Values()
If one of the options in this parser is defined with:
make_option(&quot;-f&quot;, &quot;--file&quot;, action=&quot;store&quot;, type=&quot;string&quot;, dest=&quot;filename&quot;)
and the command-line being parsed includes any of the following:
-ffoo
-f foo
--file=foo
--file foo
then optparse, on seeing the -f or
file option, will do the equivalent of this:
values.filename = &quot;foo&quot;
Clearly, the type and dest arguments are almost
as important as action. action is the only attribute that
is meaningful for all options, though, so it is the most
important.
Option actions
The various option actions all have slightly different requirements
and effects. Except for the ``help'' action, you must supply at least
one other keyword argument when creating the Option; the exact
requirements for each action are listed here.
store [relevant: type, dest, nargs, choices]
The option must be followed by an argument, which is converted to a
value according to type and stored in dest. If
nargs &gt; 1, multiple arguments will be consumed from the command
line; all will be converted according to type and stored to
dest as a tuple. See section~optparse-option-types,
``Option types,'' below.
If choices (a sequence of strings) is supplied, the type
defaults to ``choice''.
If type is not supplied, it defaults to ``string''.
If dest is not supplied, optparse derives a
destination from the first long option strings (e.g.,
foo-bar becomes foo_bar). If there are no long
option strings, optparse derives a destination from the first
short option string (e.g., -f becomes f).
Example:
make_option(&quot;-f&quot;)
make_option(&quot;-p&quot;, type=&quot;float&quot;, nargs=3, dest=&quot;point&quot;)
Given the following command line:
-f foo.txt -p 1 -3.5 4 -fbar.txt
optparse will set:
values.f = &quot;bar.txt&quot;
values.point = (1.0, -3.5, 4.0)
(Actually, values.f will be set twice, but only the second
time is visible in the end.)
store_const [required: const, dest]
The const value supplied to the Option constructor is
stored in dest.
Example:
make_option(&quot;-q&quot;, &quot;--quiet&quot;,
action=&quot;store_const&quot;, const=0, dest=&quot;verbose&quot;),
make_option(&quot;-v&quot;, &quot;--verbose&quot;,
action=&quot;store_const&quot;, const=1, dest=&quot;verbose&quot;),
make_option(&quot;--noisy&quot;,
action=&quot;store_const&quot;, const=2, dest=&quot;verbose&quot;),
If noisy is seen, optparse will set:
values.verbose = 2
store_true [required: dest]
A special case of ``store_const'' that stores True to dest.
store_false [required: dest]
Like ``store_true'', but stores False
Example:
make_option(None, &quot;--clobber&quot;, action=&quot;store_true&quot;, dest=&quot;clobber&quot;)
make_option(None, &quot;--no-clobber&quot;, action=&quot;store_false&quot;, dest=&quot;clobber&quot;)
append [relevant: type, dest, nargs, choices]
The option must be followed by an argument, which is appended to the
list in dest. If no default value for dest is supplied
(i.e. the default is None), an empty list is automatically created when
optparse first encounters this option on the command-line.
If nargs &gt; 1, multiple arguments are consumed, and a tuple of
length nargs is appended to dest.
The defaults for type and dest are the same as for the
``store'' action.
Example:
make_option(&quot;-t&quot;, &quot;--tracks&quot;, action=&quot;append&quot;, type=&quot;int&quot;)
If -t3 is seen on the command-line, optparse does the equivalent of:
values.tracks = []
values.tracks.append(int(&quot;3&quot;))
If, a little later on, tracks=4 is seen, it does:
values.tracks.append(int(&quot;4&quot;))
See ``Error handling'' (section~optparse-error-handling) for
information on how optparse deals with something like
tracks=x.
count [required: dest]
Increment the integer stored at dest. dest is set to zero
before being incremented the first time (unless you supply a default
value).
Example:
make_option(&quot;-v&quot;, action=&quot;count&quot;, dest=&quot;verbosity&quot;)
The first time -v is seen on the command line,
optparse does the equivalent of:
values.verbosity = 0
values.verbosity += 1
Every subsequent occurrence of -v results in:
values.verbosity += 1
callback [required: callback;
relevant: type, nargs, callback_args,
callback_kwargs]
Call the function specified by callback. The signature of
this function should be:
func(option : Option,
opt : string,
value : any,
parser : OptionParser,
*args, **kwargs)
Callback options are covered in detail in
section~optparse-callback-options, ``Callback Options.''
help [required: none]
Prints a complete help message for all the options in the current
option parser. The help message is constructed from the usage
string passed to OptionParser's constructor and the help
string passed to every option.
If no help string is supplied for an option, it will still be
listed in the help message. To omit an option entirely, use the
special value optparse.SUPPRESS_HELP.
Example:
from optparse import Option, OptionParser, SUPPRESS_HELP
usage = &quot;usage: %prog [options]&quot;
parser = OptionParser(usage, option_list=[
make_option(&quot;-h&quot;, &quot;--help&quot;, action=&quot;help&quot;),
make_option(&quot;-v&quot;, action=&quot;store_true&quot;, dest=&quot;verbose&quot;,
help=&quot;Be moderately verbose&quot;)
make_option(&quot;--file&quot;, dest=&quot;filename&quot;,
help=&quot;Input file to read data from&quot;),
make_option(&quot;--secret&quot;, help=SUPPRESS_HELP)
])
If optparse sees either -h or
help on the command line, it will print something
like the following help message to stdout:
usage: &lt;yourscript&gt; [options]
options:
-h, --help Show this help message and exit
-v Be moderately verbose
--file=FILENAME Input file to read data from
After printing the help message, optparse terminates your process
with sys.exit(0).
version [required: none]
Prints the version number supplied to the OptionParser to
stdout and exits. The version number is actually formatted and
printed by the print_version() method of
OptionParser. Generally only relevant if the version
argument is supplied to the OptionParser constructor.
Option types
optparse supports six option types out of the box: string,
int, long, choice, float and complex.
(Of these, string, int, float, and choice are the most commonly used
---long and complex are there mainly for completeness.) It's easy to
add new option types by subclassing the Option class; see
section~optparse-extending, ``Extending optparse.''
Arguments to string options are not checked or converted in any way:
the text on the command line is stored in the destination (or passed
to the callback) as-is.
Integer arguments are passed to int() to convert them to
Python integers. If int() fails, so will
optparse, although with a more useful error message.
Internally, optparse raises OptionValueError in
optparse.check_builtin(); at a higher level (in
OptionParser), optparse catches this exception and
terminates your program with a useful error message.
Likewise, float arguments are passed to float() for
conversion, long arguments to long(), and complex arguments
to complex(). Apart from that, they are handled
identically to integer arguments.
Choice options are a subtype of string options. A master list or
tuple of choices (strings) must be passed to the option constructor
(make_option() or OptionParser.add_option()) as
the choices keyword argument. Choice option arguments are
compared against this master list in
optparse.check_choice(), and OptionValueError
is raised if an unknown string is given.
Querying and manipulating your option parser
Sometimes, it's useful to poke around your option parser and see what's
there. OptionParser provides a couple of methods to help you out:
</description>
<element kind="function" name="has_option">
<description>Given an option string such as -q or
verbose, returns true if the OptionParser
has an option with that option string.</description>

<properties><property kind="parameter" name="opt_stropt_str" required="1"/></properties></element>

<element kind="function" name="get_option">
<description>Returns the Option instance that implements the option
string you supplied, or None if no options implement it.</description>

<properties><property kind="parameter" name="opt_stropt_str" required="1"/></properties></element>

<element kind="function" name="remove_option">
<description>If the OptionParser has an option corresponding to
opt_str, that option is removed. If that option provided
any other option strings, all of those option strings become
invalid.
If opt_str does not occur in any option belonging to this
OptionParser, raises ValueError.</description>

<properties><property kind="parameter" name="opt_stropt_str" required="1"/></properties></element>

</group>
<group name="Callback Options">
<description>If optparse's built-in actions and types just don't fit the
bill for you, but it's not worth extending optparse to define
your own actions or types, you'll probably need to define a callback
option. Defining callback options is quite easy; the tricky part is
writing a good callback (the function that is called when
optparse encounters the option on the command line).
Defining a callback option
As always, you can define a callback option either by directly
instantiating the Option class, or by using the
add_option() method of your OptionParser object. The
only option attribute you must specify is callback, the function
to call:
parser.add_option(&quot;-c&quot;, callback=my_callback)
Note that you supply a function object here---so you must have
already defined a function my_callback() when you define
the callback option. In this simple case, optparse knows
nothing about the arguments the -c option expects to
take. Usually, this means that the option doesn't take any arguments
-- the mere presence of -c on the command-line is all it
needs to know. In some circumstances, though, you might want your
callback to consume an arbitrary number of command-line arguments.
This is where writing callbacks gets tricky; it's covered later in
this document.
There are several other option attributes that you can supply when you
define an option attribute:
type
has its usual meaning: as with the ``store'' or ``append'' actions, it
instructs optparse to consume one argument that must be
convertible to type. Rather than storing the value(s) anywhere,
though, optparse converts it to type and passes it to
your callback function.
nargs
also has its usual meaning: if it is supplied and nargs &gt; 1,
optparse will consume nargs arguments, each of which
must be convertible to type. It then passes a tuple of
converted values to your callback.
callback_args
a tuple of extra positional arguments to pass to the callback.
callback_kwargs
a dictionary of extra keyword arguments to pass to the callback.
How callbacks are called
All callbacks are called as follows:
func(option, opt, value, parser, *args, **kwargs)
where
option
is the Option instance that's calling the callback.
opt
is the option string seen on the command-line that's triggering the
callback. (If an abbreviated long option was used, opt will be
the full, canonical option string---for example, if the user puts
foo on the command-line as an abbreviation for
foobar, then opt will be
foobar.)
value
is the argument to this option seen on the command-line.
optparse will only expect an argument if type is
set; the type of value will be the type implied by the
option's type (see~optparse-option-types, ``Option types''). If
type for this option is None (no argument expected), then
value will be None. If nargs &gt; 1, value will
be a tuple of values of the appropriate type.
parser
is the OptionParser instance driving the whole thing, mainly
useful because you can access some other interesting data through it,
as instance attributes:
parser.rargs
the current remaining argument list, i.e. with opt (and
value, if any) removed, and only the arguments following
them still there. Feel free to modify parser.rargs,
e.g. by consuming more arguments.
parser.largs
the current set of leftover arguments, i.e. arguments that have been
processed but have not been consumed as options (or arguments to
options). Feel free to modify parser.largs e.g. by adding
more arguments to it.
parser.values
the object where option values are by default stored. This is useful
because it lets callbacks use the same mechanism as the rest of
optparse for storing option values; you don't need to mess
around with globals or closures. You can also access the value(s) of
any options already encountered on the command-line.
args
is a tuple of arbitrary positional arguments supplied via the
callback_args option attribute.
kwargs
is a dictionary of arbitrary keyword arguments supplied via
callback_kwargs.
Since args and kwargs are optional (they are only passed
if you supply callback_args and/or callback_kwargs when
you define your callback option), the minimal callback function is:
def my_callback (option, opt, value, parser):
pass
Error handling
The callback function should raise OptionValueError if
there are any problems with the option or its
argument(s). optparse catches this and terminates the
program, printing the error message you supply to stderr. Your
message should be clear, concise, accurate, and mention the option at
fault. Otherwise, the user will have a hard time figuring out what he
did wrong.
Examples
Here's an example of a callback option that takes no arguments, and
simply records that the option was seen:
def record_foo_seen (option, opt, value, parser):
parser.saw_foo = 1
parser.add_option(&quot;--foo&quot;, action=&quot;callback&quot;, callback=record_foo_seen)
Of course, you could do that with the ``store_true'' action. Here's a
slightly more interesting example: record the fact that
-a is seen, but blow up if it comes after -b
in the command-line.
def check_order (option, opt, value, parser):
if parser.values.b:
raise OptionValueError(&quot;can't use -a after -b&quot;)
parser.values.a = 1
...
parser.add_option(&quot;-a&quot;, action=&quot;callback&quot;, callback=check_order)
parser.add_option(&quot;-b&quot;, action=&quot;store_true&quot;, dest=&quot;b&quot;)
If you want to reuse this callback for several similar options (set a
flag, but blow up if -b has already been seen), it needs
a bit of work: the error message and the flag that it sets must be
generalized.
def check_order (option, opt, value, parser):
if parser.values.b:
raise OptionValueError(&quot;can't use %s after -b&quot; % opt)
setattr(parser.values, option.dest, 1)
...
parser.add_option(&quot;-a&quot;, action=&quot;callback&quot;, callback=check_order, dest='a')
parser.add_option(&quot;-b&quot;, action=&quot;store_true&quot;, dest=&quot;b&quot;)
parser.add_option(&quot;-c&quot;, action=&quot;callback&quot;, callback=check_order, dest='c')
Of course, you could put any condition in there---you're not limited
to checking the values of already-defined options. For example, if
you have options that should not be called when the moon is full, all
you have to do is this:
def check_moon (option, opt, value, parser):
if is_full_moon():
raise OptionValueError(&quot;%s option invalid when moon full&quot; % opt)
setattr(parser.values, option.dest, 1)
...
parser.add_option(&quot;--foo&quot;,
action=&quot;callback&quot;, callback=check_moon, dest=&quot;foo&quot;)
(The definition of is_full_moon() is left as an exercise for the
reader.)
Fixed arguments
Things get slightly more interesting when you define callback options
that take a fixed number of arguments. Specifying that a callback
option takes arguments is similar to defining a ``store'' or
``append'' option: if you define type, then the option takes one
argument that must be convertible to that type; if you further define
nargs, then the option takes that many arguments.
Here's an example that just emulates the standard ``store'' action:
def store_value (option, opt, value, parser):
setattr(parser.values, option.dest, value)
...
parser.add_option(&quot;--foo&quot;,
action=&quot;callback&quot;, callback=store_value,
type=&quot;int&quot;, nargs=3, dest=&quot;foo&quot;)
Note that optparse takes care of consuming 3 arguments and
converting them to integers for you; all you have to do is store them.
(Or whatever: obviously you don't need a callback for this example.
Use your imagination!)
Variable arguments
Things get hairy when you want an option to take a variable number of
arguments. For this case, you have to write a callback;
optparse doesn't provide any built-in capabilities for it.
You have to deal with the full-blown syntax for conventional command-line parsing. (Previously, optparse took care of
this for you, but I got it wrong. It was fixed at the cost of making
this kind of callback more complex.) In particular, callbacks have to
worry about bare and - arguments; the
convention is:
bare , if not the argument to some option,
causes command-line processing to halt and the itself is lost.
bare - similarly causes command-line processing to
halt, but the - itself is kept.
either or - can be option
arguments.
If you want an option that takes a variable number of arguments, there
are several subtle, tricky issues to worry about. The exact
implementation you choose will be based on which trade-offs you're
willing to make for your application (which is why optparse
doesn't support this sort of thing directly).
Nevertheless, here's a stab at a callback for an option with variable
arguments:
def varargs (option, opt, value, parser):
assert value is None
done = 0
value = []
rargs = parser.rargs
while rargs:
arg = rargs[0]
# Stop if we hit an arg like &quot;--foo&quot;, &quot;-a&quot;, &quot;-fx&quot;, &quot;--file=f&quot;,
# etc. Note that this also stops on &quot;-3&quot; or &quot;-3.0&quot;, so if
# your option takes numeric values, you will need to handle
# this.
if ((arg[:2] == &quot;--&quot; and len(arg) &gt; 2) or
(arg[:1] == &quot;-&quot; and len(arg) &gt; 1 and arg[1] != &quot;-&quot;)):
break
else:
value.append(arg)
del rargs[0]
setattr(parser.values, option.dest, value)
...
parser.add_option(&quot;-c&quot;, &quot;--callback&quot;,
action=&quot;callback&quot;, callback=varargs)
The main weakness with this particular implementation is that negative
numbers in the arguments following -c will be interpreted
as further options, rather than as arguments to -c.
Fixing this is left as an exercise for the reader.
</description>
</group>
<group name="Extending optparse">
</group>
</group>
<group name="tempfile --- Generate temporary files and directories">
<description>Generate temporary files and directories.
This module generates temporary files and directories. It works on
all supported platforms.
In version 2.3 of Python, this module was overhauled for enhanced
security. It now provides three new functions,
NamedTemporaryFile(), mkstemp(), and
mkdtemp(), which should eliminate all remaining need to use
the insecure mktemp() function. Temporary file names created
by this module no longer contain the process ID; instead a string of
six random characters is used.
Also, all the user-callable functions now take additional arguments
which allow direct control over the location and name of temporary
files. It is no longer necessary to use the global tempdir and
template variables. To maintain backward compatibility, the
argument order is somewhat odd; it is recommended to use keyword
arguments for clarity.
The module defines the following user-callable functions:
</description>
<element kind="function" name="TemporaryFile">
<description>Return a file (or file-like) object that can be used as a temporary
storage area. The file is created using mkstemp. It will
be destroyed as soon as it is closed (including an implicit close when
the object is garbage collected). Under , the directory entry
for the file is removed immediately after the file is created. Other
platforms do not support this; your code should not rely on a
temporary file created using this function having or not having a
visible name in the file system.
The mode parameter defaults to 'w+b' so that the file
created can be read and written without being closed. Binary mode is
used so that it behaves consistently on all platforms without regard
for the data that is stored. bufsize defaults to -1,
meaning that the operating system default is used.
The dir, prefix and suffix parameters are passed to
mkstemp().</description>

<properties><property default="'w+b'" kind="parameter" name="mode" required="1"/><property default="-1" kind="parameter" name="bufsize"/><property kind="parameter" name="suffix"/><property kind="parameter" name="prefix"/><property kind="parameter" name="dir"/></properties></element>

<element kind="function" name="NamedTemporaryFile">
<description>This function operates exactly as TemporaryFile() does,
except that the file is guaranteed to have a visible name in the file
system (on , the directory entry is not unlinked). That name can
be retrieved from the name member of the file object. Whether
the name can be used to open the file a second time, while the
named temporary file is still open, varies across platforms (it can
be so used on ; it cannot on Windows NT or later).
New in version 2.3</description>

<properties><property default="'w+b'" kind="parameter" name="mode" required="1"/><property default="-1" kind="parameter" name="bufsize"/><property kind="parameter" name="suffix"/><property kind="parameter" name="prefix"/><property kind="parameter" name="dir"/></properties></element>

<element kind="function" name="mkstemp">
<description>Creates a temporary file in the most secure manner possible. There
are no race conditions in the file's creation, assuming that the
platform properly implements the O_EXCL flag for
os.open(). The file is readable and writable only by the
creating user ID. If the platform uses permission bits to indicate
whether a file is executable, the file is executable by no one. The
file descriptor is not inherited by child processes.
Unlike TemporaryFile(), the user of mkstemp() is
responsible for deleting the temporary file when done with it.
If suffix is specified, the file name will end with that suffix,
otherwise there will be no suffix. mkstemp() does not put a
dot between the file name and the suffix; if you need one, put it at
the beginning of suffix.
If prefix is specified, the file name will begin with that
prefix; otherwise, a default prefix is used.
If dir is specified, the file will be created in that directory;
otherwise, a default directory is used.
If text is specified, it indicates whether to open the file in
binary mode (the default) or text mode. On some platforms, this makes
no difference.
mkstemp() returns a tuple containing an OS-level handle to
an open file (as would be returned by os.open()) and the
absolute pathname of that file, in that order.
New in version 2.3</description>

<properties><property kind="parameter" name="suffix" required="1"/><property kind="parameter" name="prefix"/><property kind="parameter" name="dir"/><property kind="parameter" name="text"/></properties></element>

<element kind="function" name="mkdtemp">
<description>Creates a temporary directory in the most secure manner possible.
There are no race conditions in the directory's creation. The
directory is readable, writable, and searchable only by the
creating user ID.
The user of mkdtemp() is responsible for deleting the
temporary directory and its contents when done with it.
The prefix, suffix, and dir arguments are the same
as for mkstemp().
mkdtemp() returns the absolute pathname of the new directory.
New in version 2.3</description>

<properties><property kind="parameter" name="suffix" required="1"/><property kind="parameter" name="prefix"/><property kind="parameter" name="dir"/></properties></element>

<element kind="function" name="mktemp">
<description>2.3{Use mkstemp() instead.}
Return an absolute pathname of a file that did not exist at the time
the call is made. The prefix, suffix, and dir
arguments are the same as for mkstemp().
Use of this function may introduce a security hole in your
program. By the time you get around to doing anything with the file
name it returns, someone else may have beaten you to the punch.</description>

<properties><property kind="parameter" name="suffix" required="1"/><property kind="parameter" name="prefix"/><property kind="parameter" name="dir"/></properties></element>

<element kind="function" name="gettempdir">
<description>Return the directory currently selected to create temporary files in.
If tempdir is not None, this simply returns its contents;
otherwise, the search described above is performed, and the result
returned.</description>

</element>

<element kind="function" name="gettempprefix">
<description>Return the filename prefix used to create temporary files. This does
not contain the directory component. Using this function is preferred
over reading the template variable directly.
New in version 1.5.2</description>

</element>

</group>
<group name="errno --- Standard errno system symbols">
</group>
<group name="glob --- style pathname pattern expansion">
<description>style pathname pattern expansion.
The glob module finds all the pathnames matching a specified
pattern according to the rules used by the 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().)
</description>
<element kind="function" name="glob">
<description>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/Python-1.5/Makefile) or relative (like
../../Tools/*/*.gif), and can contain shell-style wildcards.</description>

<properties><property kind="parameter" name="pathnamepathname" required="1"/></properties></element>

</group>
<group name="fnmatch --- filename pattern matching">
<description>style filename pattern matching.
</description>
<element kind="function" name="fnmatch">
<description>Test whether the filename string matches the pattern
string, returning true or false. If the operating system is
case-insensitive, then both parameters will be normalized to all
lower- or upper-case before the comparison is performed. If you
require a case-sensitive comparison regardless of whether that's
standard for your operating system, use fnmatchcase()
instead.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="pattern pattern" required="1"/></properties></element>

<element kind="function" name="fnmatchcase">
<description>Test whether filename matches pattern, returning true or
false; the comparison is case-sensitive.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="pattern pattern" required="1"/></properties></element>

<element kind="function" name="filter">
<description>Return the subset of the list of names that match pattern.
It is the same as [n for n in names if fnmatch(n, pattern)], but
implemented more efficiently.
New in version 2.2</description>

<properties><property kind="parameter" name="names" required="1"/><property kind="parameter" name="pattern pattern" required="1"/></properties></element>

</group>
<group name="shutil --- High-level file operations">
<description>High-level file operations, including copying.
% partly based on the docstrings
The shutil module offers a number of high-level operations on
files and collections of files. In particular, functions are provided which support file copying and removal.
</description>
<element kind="function" name="copyfile">
<description>Copy the contents of the file named src to a file named
dst. If dst exists, it will be replaced, otherwise it
will be created. Special files such as character or block devices
and pipes cannot not be copied with this function. src and
dst are path names given as strings.</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="copyfileobj">
<description>Copy the contents of the file-like object fsrc to the
file-like object fdst. The integer length, if given,
is the buffer size. In particular, a negative length value
means to copy the data without looping over the source data in
chunks; by default the data is read in chunks to avoid uncontrolled
memory consumption.</description>

<properties><property kind="parameter" name="fsrc" required="1"/><property kind="parameter" name="fdst" required="1"/><property kind="parameter" name="length"/></properties></element>

<element kind="function" name="copymode">
<description>Copy the permission bits from src to dst. The file
contents, owner, and group are unaffected. src and dst
are path names given as strings.</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="copystat">
<description>Copy the permission bits, last access time, and last modification
time from src to dst. The file contents, owner, and
group are unaffected. src and dst are path names given
as strings.</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="copy">
<description>Copy the file src to the file or directory dst. If
dst is a directory, a file with the same basename as src is created (or overwritten) in the directory specified. Permission
bits are copied. src and dst are path names given as
strings.</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="copy2">
<description>Similar to copy(), but last access time and last
modification time are copied as well. This is similar to the
command cp -p.</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<element kind="function" name="copytree">
<description>Recursively copy an entire directory tree rooted at src. The
destination directory, named by dst, must not already exist;
it will be created. Individual files are copied using
copy2(). If symlinks is true, symbolic links in
the source tree are represented as symbolic links in the new tree;
if false or omitted, the contents of the linked files are copied to
the new tree. If exception(s) occur, an Error is raised
with a list of reasons.
The source code for this should be considered an example rather than a tool.
Changed in version 2.3: Error is raised if any exceptions occur during copying,
rather than printing a message</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst" required="1"/><property kind="parameter" name="symlinks"/></properties></element>

<element kind="function" name="rmtree">
<description>Delete an entire directory tree.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="ignore_errors"/><property kind="parameter" name="onerror"/></properties></element>

<element kind="function" name="move">
<description>Recursively move a file or directory to another location.
If the destination is on our current filesystem, then simply use
rename. Otherwise, copy src to the dst and then remove src.
New in version 2.3</description>

<properties><property kind="parameter" name="src" required="1"/><property kind="parameter" name="dst dst" required="1"/></properties></element>

<group name="Example">
</group>
</group>
<group name="locale --- Internationalization services">
<description>Internationalization services.
The locale module opens access to the locale
database and functionality. The locale mechanism allows
programmers to deal with certain cultural issues in an application,
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_locale module, which in turn uses an
ANSI C locale implementation if available.
The locale module defines the following exception and
functions:
{Error}
Exception raised when setlocale() fails.
</description>
<element kind="function" name="setlocale">
<description>If locale is specified, it may be a string, a tuple of the
form (language code, encoding), or None.
If it is a tuple, it is converted to a string using the locale
aliasing engine. If locale is given and not None,
setlocale() 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 Error is raised. If
successful, the new locale setting is returned.
If locale is omitted or None, the current setting for
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.
Changed in version 2.0: Added support for tuple values of the locale
parameter</description>

<properties><property kind="parameter" name="category" required="1"/><property kind="parameter" name="locale"/></properties></element>

<element kind="function" name="localeconv">
<description>Returns the database of the local conventions as a dictionary.
This dictionary has the following strings as keys:
{l|l|p{3in}}{constant}{Key}{Category}{Meaning}
LC_NUMERIC{'decimal_point'}
{Decimal point character.}
{'grouping'}
{Sequence of numbers specifying which relative positions
the 'thousands_sep' is expected. If the sequence is
terminated with CHAR_MAX, no further grouping
is performed. If the sequence terminates with a 0, the last group size is repeatedly used.}
{'thousands_sep'}
{Character used between groups.}
LC_MONETARY{'int_curr_symbol'}
{International currency symbol.}
{'currency_symbol'}
{Local currency symbol.}
{'mon_decimal_point'}
{Decimal point used for monetary values.}
{'mon_thousands_sep'}
{Group separator used for monetary values.}
{'mon_grouping'}
{Equivalent to 'grouping', used for monetary
values.}
{'positive_sign'}
{Symbol used to annotate a positive monetary value.}
{'negative_sign'}
{Symbol used to annotate a nnegative monetary value.}
{'frac_digits'}
{Number of fractional digits used in local formatting
of monetary values.}
{'int_frac_digits'}
{Number of fractional digits used in international
formatting of monetary values.}
The possible values for 'p_sign_posn' and
'n_sign_posn' are given below.
{c|l}{code}{Value}{Explanation}
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.}
</description>

</element>

<element kind="function" name="nl_langinfo">
<description>Return some locale-specific information as a string. This function is
not available on all systems, and the set of possible options might
also vary across platforms. The possible argument values are numbers,
for which symbolic constants are available in the locale module.</description>

<properties><property kind="parameter" name="optionoption" required="1"/></properties></element>

<element kind="function" name="getdefaultlocale">
<description>Tries to determine the default locale settings and returns
them as a tuple of the form (language code,
encoding).
According to , a program which has not called
setlocale(LC_ALL, '') runs using the portable 'C'
locale. Calling setlocale(LC_ALL, '') lets it use the
default locale as defined by the LANG variable. Since we
do not want to interfere with the current locale setting we thus
emulate the behavior in the way described above.
To maintain compatibility with other platforms, not only the
LANG variable is tested, but a list of variables given as
envvars parameter. The first found to be defined will be
used. envvars defaults to the search path used in GNU gettext;
it must always contain the variable name LANG. The GNU
gettext search path contains 'LANGUAGE', 'LC_ALL',
'LC_CTYPE', and 'LANG', in that order.
Except for the code 'C', the language code corresponds to
1766. language code and encoding may be
None if their values cannot be determined.
New in version 2.0</description>

<properties><property kind="parameter" name="envvars" required="1"/></properties></element>

<element kind="function" name="getlocale">
<description>Returns the current setting for the given locale category as
sequence containing language code, encoding.
category may be one of the LC_* values except
LC_ALL. It defaults to LC_CTYPE.
Except for the code 'C', the language code corresponds to
1766. language code and encoding may be
None if their values cannot be determined.
New in version 2.0</description>

<properties><property kind="parameter" name="category" required="1"/></properties></element>

<element kind="function" name="getpreferredencoding">
<description>Return the encoding used for text data, according to user
preferences. User preferences are expressed differently on
different systems, and might not be available programmatically on
some systems, so this function only returns a guess.
On some systems, it is necessary to invoke setlocale
to obtain the user preferences, so this function is not thread-safe.
If invoking setlocale is not necessary or desired, do_setlocale
should be set to False.
New in version 2.3</description>

<properties><property kind="parameter" name="do_setlocale" required="1"/></properties></element>

<element kind="function" name="normalize">
<description>Returns a normalized locale code for the given locale name. The
returned locale code is formatted for use with
setlocale(). If normalization fails, the original name
is returned unchanged.
If the given encoding is not known, the function defaults to
the default encoding for the locale code just like
setlocale().
New in version 2.0</description>

<properties><property kind="parameter" name="localenamelocalename" required="1"/></properties></element>

<element kind="function" name="resetlocale">
<description>Sets the locale for category to the default setting.
The default setting is determined by calling
getdefaultlocale(). category defaults to
LC_ALL.
New in version 2.0</description>

<properties><property kind="parameter" name="category" required="1"/></properties></element>

<element kind="function" name="strcoll">
<description>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.</description>

<properties><property kind="parameter" name="string1" required="1"/><property kind="parameter" name="string2 string2" required="1"/></properties></element>

<element kind="function" name="strxfrm">
<description>Transforms a string to one that can be used for the built-in
function cmp()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.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="format">
<description>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.</description>

<properties><property kind="parameter" name="format" required="1"/><property kind="parameter" name="val" required="1"/><property kind="parameter" name="grouping"/></properties></element>

<element kind="function" name="str">
<description>Formats a floating point number using the same format as the
built-in function str(float), but takes the decimal
point into account.</description>

<properties><property kind="parameter" name="floatfloat" required="1"/></properties></element>

<element kind="function" name="atof">
<description>Converts a string to a floating point number, following the
LC_NUMERIC settings.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="atoi">
<description>Converts a string to an integer, following the
LC_NUMERIC conventions.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<group name="Background, details, hints, tips and caveats">
<description>The C standard defines the locale as a program-wide property that may
be relatively expensive to change. On top of that, some
implementation are broken in such a way that frequent locale changes
may cause core dumps. This makes the locale somewhat painful to use
correctly.
Initially, when a program is started, the locale is the C locale, no
matter what the user's preferred locale is. The program must
explicitly say that it wants the user's preferred locale settings by
calling setlocale(LC_ALL, '').
It is generally a bad idea to call setlocale() in some library
routine, since as a side effect it affects the entire program. Saving
and restoring it is almost as bad: it is expensive and affects other
threads that happen to run before the settings have been restored.
If, when coding a module for general use, you need a locale
independent version of an operation that is affected by the locale
(such as string.lower(), or certain formats used with
time.strftime()), you will have to find a way to do it
without using the standard library routine. Even better is convincing
yourself that using locale settings is okay. Only as a last resort
should you document that your module is not compatible with
non-C locale settings.
The case conversion functions in the
stringstring module are affected by the
locale settings. When a call to the setlocale() function
changes the LC_CTYPE settings, the variables
string.lowercase, string.uppercase and
string.letters are recalculated. Note that this code that uses
these variable through `from ... import ...',
e.g. from string import letters, is not affected by subsequent
setlocale() calls.
The only way to perform numeric operations according to the locale
is to use the special functions defined by this module:
atof(), atoi(), format(),
str().
</description>
</group>
<group name="For extension writers and programs that embed Python">
<description>Extension modules should never call setlocale(), except to
find out what the current locale is. But since the return value can
only be used portably to restore it, that is not very useful (except
perhaps to find out whether or not the locale is C).
When Python is embedded in an application, if the application sets the
locale to something specific before initializing Python, that is
generally okay, and Python will use whatever locale is set,
except that the LC_NUMERIC locale should always be
C.
The setlocale() function in the locale module
gives the Python programmer the impression that you can manipulate the
LC_NUMERIC locale setting, but this not the case at the C
level: C code will always find that the LC_NUMERIC locale
setting is C. This is because too much would break when the
decimal point character is set to something else than a period
(e.g. the Python parser would break). Caveat: threads that run
without holding Python's global interpreter lock may occasionally find
that the numeric locale setting differs; this is because the only
portable way to implement this feature is to set the numeric locale
settings to what the user requests, extract the relevant
characteristics, and then restore the C numeric locale.
When Python code uses the locale module to change the locale,
this also affects the embedding application. If the embedding
application doesn't want this to happen, it should remove the
_locale extension module (which does all the work) from the
table of built-in modules in the config.c file, and make sure
that the _locale module is not accessible as a shared library.
</description>
</group>
<group name="Access to message catalogs">
</group>
</group>
<group name="gettext --- Multilingual internationalization services">
<description>Multilingual internationalization services.
The gettext module provides internationalization (I18N) and
localization (L10N) services for your Python modules and applications.
It supports both the GNU gettext message catalog API and a
higher level, class-based API that may be more appropriate for Python
files. The interface described below allows you to write your
module and application messages in one natural language, and provide a
catalog of translated messages for running under different natural
languages.
Some hints on localizing your Python modules and applications are also
given.
</description>
<group name="GNU gettext API">
<description>The gettext module defines the following API, which is very
similar to the GNU gettext API. If you use this API you
will affect the translation of your entire application globally. Often
this is what you want if your application is monolingual, with the choice
of language dependent on the locale of your user. If you are
localizing a Python module, or if your application needs to switch
languages on the fly, you probably want to use the class-based API
instead.
</description>
<element kind="function" name="bindtextdomain">
<description>Bind the domain to the locale directory
localedir. More concretely, gettext will look for
binary .mo files for the given domain using the path (on ):
localedir/language/LC_MESSAGES/domain.mo,
where languages is searched for in the environment variables
LANGUAGE, LC_ALL, LC_MESSAGES, and
LANG respectively.
If localedir is omitted or None, then the current binding
for domain is returned.
The default locale directory is system dependent; for example,
on RedHat Linux it is /usr/share/locale, but on Solaris
it is /usr/lib/locale. The gettext module
does not try to support these system dependent defaults;
instead its default is sys.prefix/share/locale.
For this reason, it is always best to call
bindtextdomain() with an explicit absolute path at
the start of your application.</description>

<properties><property kind="parameter" name="domain" required="1"/><property kind="parameter" name="localedir"/></properties></element>

<element kind="function" name="textdomain">
<description>Change or query the current global domain. If domain is
None, then the current global domain is returned, otherwise the
global domain is set to domain, which is returned.</description>

<properties><property kind="parameter" name="domain" required="1"/></properties></element>

<element kind="function" name="gettext">
<description>Return the localized translation of message, based on the
current global domain, language, and locale directory. This function
is usually aliased as _ in the local namespace (see
examples below).</description>

<properties><property kind="parameter" name="messagemessage" required="1"/></properties></element>

<element kind="function" name="dgettext">
<description>Like gettext(), but look the message up in the specified
domain.</description>

<properties><property kind="parameter" name="domain" required="1"/><property kind="parameter" name="message message" required="1"/></properties></element>

<element kind="function" name="ngettext">
<description>Like gettext(), but consider plural forms. If a translation
is found, apply the plural formula to n, and return the
resulting message (some languages have more than two plural forms).
If no translation is found, return singular if n is 1;
return plural otherwise.
The Plural formula is taken from the catalog header. It is a C or
Python expression that has a free variable n; the expression evaluates
to the index of the plural in the catalog. See the GNU gettext
documentation for the precise syntax to be used in .po files, and the
formulas for a variety of languages.
New in version 2.3</description>

<properties><property kind="parameter" name="singular" required="1"/><property kind="parameter" name="plural" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="dngettext">
<description>Like ngettext(), but look the message up in the specified
domain.
New in version 2.3</description>

<properties><property kind="parameter" name="domain" required="1"/><property kind="parameter" name="singular" required="1"/><property kind="parameter" name="plural" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

</group>
<group name="Class-based API">
<description>The class-based API of the gettext module gives you more
flexibility and greater convenience than the GNU gettext
API. It is the recommended way of localizing your Python applications and
modules. gettext defines a ``translations'' class which
implements the parsing of GNU .mo format files, and has methods
for returning either standard 8-bit strings or Unicode strings.
Translations instances can also install themselves in the built-in
namespace as the function _().
</description>
<element kind="function" name="find">
<description>This function implements the standard .mo file search
algorithm. It takes a domain, identical to what
textdomain() takes. Optional localedir is as in
bindtextdomain() Optional languages is a list of
strings, where each string is a language code.
If localedir is not given, then the default system locale
directory is used.See the footnote for
bindtextdomain() above. If languages is not given,
then the following environment variables are searched: LANGUAGE,
LC_ALL, LC_MESSAGES, and LANG. The first one
returning a non-empty value is used for the languages variable.
The environment variables should contain a colon separated list of
languages, which will be split on the colon to produce the expected
list of language code strings.
find() then expands and normalizes the languages, and then
iterates through them, searching for an existing file built of these
components:
localedir/language/LC_MESSAGES/domain.mo
The first such file name that exists is returned by find().
If no such file is found, then None is returned. If all
is given, it returns a list of all file names, in the order in which
they appear in the languages list or the environment variables.</description>

<properties><property kind="parameter" name="domain" required="1"/><property kind="parameter" name="localedir"/><property kind="parameter" name="languages"/><property kind="parameter" name="all"/></properties></element>

<element kind="function" name="translation">
<description>Return a Translations instance based on the domain,
localedir, and languages, which are first passed to
find() to get a list of the
associated .mo file paths. Instances with
identical .mo file names are cached. The actual class instantiated
is either class_ if provided, otherwise
GNUTranslations. The class's constructor must take a single
file object argument. If multiple files are found, later files are used as fallbacks for
earlier ones. To allow setting the fallback, copy.copy
is used to clone each translation object from the cache; the actual
instance data is still shared with the cache.
If no .mo file is found, this function raises
IOError if fallback is false (which is the default),
and returns a NullTranslations instance if fallback is
true.</description>

<properties><property kind="parameter" name="domain" required="1"/><property kind="parameter" name="localedir"/><property kind="parameter" name="languages"/><property kind="parameter" name="class_"/><property kind="parameter" name="fallback"/></properties></element>

<element kind="function" name="install">
<description>This installs the function _ in Python's builtin namespace,
based on domain, and localedir which are passed to the
function translation(). The unicode flag is passed to
the resulting translation object's install method.
As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the
_() function, like this:
print _('This string will be translated.')
For convenience, you want the _() function to be installed in
Python's builtin namespace, so it is easily accessible in all modules
of your application.</description>

<properties><property kind="parameter" name="domain" required="1"/><property kind="parameter" name="localedir"/><property kind="parameter" name="unicode"/></properties></element>

<element kind="function" name="__init__">
<description>Takes an optional file object fp, which is ignored by the base
class. Initializes ``protected'' instance variables _info and
_charset which are set by derived classes, as well as _fallback,
which is set through add_fallback. It then calls
self._parse(fp) if fp is not None.</description>

<properties><property kind="parameter" name="fp" required="1"/></properties></element>

<element kind="function" name="_parse">
<description>No-op'd in the base class, this method takes file object fp, and
reads the data from the file, initializing its message catalog. If
you have an unsupported message catalog file format, you should
override this method to parse your format.</description>

<properties><property kind="parameter" name="fpfp" required="1"/></properties></element>

<element kind="function" name="add_fallback">
<description>Add fallback as the fallback object for the current translation
object. A translation object should consult the fallback if it cannot
provide a translation for a given message.</description>

<properties><property kind="parameter" name="fallbackfallback" required="1"/></properties></element>

<element kind="function" name="gettext">
<description>If a fallback has been set, forward gettext to the fallback.
Otherwise, return the translated message. Overridden in derived classes.</description>

<properties><property kind="parameter" name="messagemessage" required="1"/></properties></element>

<element kind="function" name="ugettext">
<description>If a fallback has been set, forward ugettext to the fallback.
Otherwise, return the translated message as a Unicode string.
Overridden in derived classes.</description>

<properties><property kind="parameter" name="messagemessage" required="1"/></properties></element>

<element kind="function" name="ngettext">
<description>If a fallback has been set, forward ngettext to the fallback.
Otherwise, return the translated message. Overridden in derived classes.
New in version 2.3</description>

<properties><property kind="parameter" name="singular" required="1"/><property kind="parameter" name="plural" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="ungettext">
<description>If a fallback has been set, forward ungettext to the fallback.
Otherwise, return the translated message as a Unicode string.
Overridden in derived classes.
New in version 2.3</description>

<properties><property kind="parameter" name="singular" required="1"/><property kind="parameter" name="plural" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="info">
<description>Return the ``protected'' _info variable.</description>

</element>

<element kind="function" name="charset">
<description>Return the ``protected'' _charset variable.</description>

</element>

<element kind="function" name="install">
<description>If the unicode flag is false, this method installs
self.gettext() into the built-in namespace, binding it to
_. If unicode is true, it binds self.ugettext()
instead. By default, unicode is false.
Note that this is only one way, albeit the most convenient way, to
make the _ function available to your application. Because it
affects the entire application globally, and specifically the built-in
namespace, localized modules should never install _.
Instead, they should use this code to make _ available to
their module:
import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext
This puts _ only in the module's global namespace and so
only affects calls within this module.</description>

<properties><property kind="parameter" name="unicode" required="1"/></properties></element>

<element kind="function" name="gettext">
<description>Look up the message id in the catalog and return the
corresponding message string, as an 8-bit string encoded with the
catalog's charset encoding, if known. If there is no entry in the
catalog for the message id, and a fallback has been set, the
look up is forwarded to the fallback's gettext() method.
Otherwise, the message id is returned.</description>

<properties><property kind="parameter" name="messagemessage" required="1"/></properties></element>

<element kind="function" name="ugettext">
<description>Look up the message id in the catalog and return the
corresponding message string, as a Unicode string. If there is no
entry in the catalog for the message id, and a fallback has been
set, the look up is forwarded to the fallback's ugettext()
method. Otherwise, the message id is returned.</description>

<properties><property kind="parameter" name="messagemessage" required="1"/></properties></element>

<element kind="function" name="ngettext">
<description>Do a plural-forms lookup of a message id. singular is used as
the message id for purposes of lookup in the catalog, while n is
used to determine which plural form to use. The returned message
string is an 8-bit string encoded with the catalog's charset encoding,
if known.
If the message id is not found in the catalog, and a fallback is
specified, the request is forwarded to the fallback's
ngettext() method. Otherwise, when n is 1 singular is
returned, and plural is returned in all other cases.
New in version 2.3</description>

<properties><property kind="parameter" name="singular" required="1"/><property kind="parameter" name="plural" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

<element kind="function" name="ungettext">
<description>Do a plural-forms lookup of a message id. singular is used as
the message id for purposes of lookup in the catalog, while n is
used to determine which plural form to use. The returned message
string is a Unicode string.
If the message id is not found in the catalog, and a fallback is
specified, the request is forwarded to the fallback's
ungettext() method. Otherwise, when n is 1 singular is
returned, and plural is returned in all other cases.
Here is an example:
n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ungettext(
'There is %(num)d file in this directory',
'There are %(num)d files in this directory',
n) % {'n': n}
New in version 2.3</description>

<properties><property kind="parameter" name="singular" required="1"/><property kind="parameter" name="plural" required="1"/><property kind="parameter" name="n n" required="1"/></properties></element>

</group>
<group name="Internationalizing your programs and modules">
<description>Internationalization (I18N) refers to the operation by which a program
is made aware of multiple languages. Localization (L10N) refers to
the adaptation of your program, once internationalized, to the local
language and cultural habits. In order to provide multilingual
messages for your Python programs, you need to take the following
steps:
prepare your program or module by specially marking
translatable strings
run a suite of tools over your marked files to generate raw
messages catalogs
create language specific translations of the message catalogs
use the gettext module so that message strings are
properly translated
In order to prepare your code for I18N, you need to look at all the
strings in your files. Any string that needs to be translated
should be marked by wrapping it in _('...') --- that is, a call
to the function _(). For example:
filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()
In this example, the string 'writing a log message' is marked as
a candidate for translation, while the strings 'mylog.txt' and
'w' are not.
The Python distribution comes with two tools which help you generate
the message catalogs once you've prepared your source code. These may
or may not be available from a binary distribution, but they can be
found in a source distribution, in the Tools/i18n directory.
The pygettextFran cois Pinard has
written a program called
xpot which does a similar job. It is available as part of
his po-utils package at
http://www.iro.umontreal.ca/contrib/po-utils/HTML/. program
scans all your Python source code looking for the strings you
previously marked as translatable. It is similar to the GNU
gettext program except that it understands all the
intricacies of Python source code, but knows nothing about C or Cpp
source code. You don't need GNU gettext unless you're also
going to be translating C code (such as C extension modules).
pygettext generates textual Uniforum-style human readable
message catalog .pot files, essentially structured human
readable files which contain every marked string in the source code,
along with a placeholder for the translation strings.
pygettext is a command line script that supports a similar
command line interface as xgettext; for details on its use,
run:
pygettext.py --help
Copies of these .pot files are then handed over to the
individual human translators who write language-specific versions for
every supported natural language. They send you back the filled in
language-specific versions as a .po file. Using the
msgfmt.pymsgfmt.py is binary
compatible with GNU msgfmt except that it provides a
simpler, all-Python implementation. With this and
pygettext.py, you generally won't need to install the GNU
gettext package to internationalize your Python
applications. program (in the Tools/i18n directory), you take the
.po files from your translators and generate the
machine-readable .mo binary catalog files. The .mo
files are what the gettext module uses for the actual
translation processing during run-time.
How you use the gettext module in your code depends on
whether you are internationalizing your entire application or a single
module.
Localizing your module
If you are localizing your module, you must take care not to make
global changes, e.g. to the built-in namespace. You should not use
the GNU gettext API but instead the class-based API. Let's say your module is called ``spam'' and the module's various
natural language translation .mo files reside in
/usr/share/locale in GNU gettext format. Here's what
you would put at the top of your module:
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext
If your translators were providing you with Unicode strings in their
.po files, you'd instead do:
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.ugettext
Localizing your application
If you are localizing your application, you can install the _()
function globally into the built-in namespace, usually in the main driver file
of your application. This will let all your application-specific
files just use _('...') without having to explicitly install it in
each file.
In the simple case then, you need only add the following bit of code
to the main driver file of your application:
import gettext
gettext.install('myapplication')
If you need to set the locale directory or the unicode flag,
you can pass these into the install() function:
import gettext
gettext.install('myapplication', '/usr/share/locale', unicode=1)
Changing languages on the fly
If your program needs to support many languages at the same time, you
may want to create multiple translation instances and then switch
between them explicitly, like so:
import gettext
lang1 = gettext.translation(languages=['en'])
lang2 = gettext.translation(languages=['fr'])
lang3 = gettext.translation(languages=['de'])
# start by using language1
lang1.install()
# ... time goes by, user selects language 2
lang2.install()
# ... more time goes by, user selects language 3
lang3.install()
Deferred translations
In most coding situations, strings are translated where they are coded.
Occasionally however, you need to mark strings for translation, but
defer actual translation until later. A classic example is:
animals = ['mollusk',
'albatross',
'rat',
'penguin',
'python',
]
# ...
for a in animals:
print a
Here, you want to mark the strings in the animals list as being
translatable, but you don't actually want to translate them until they
are printed.
Here is one way you can handle this situation:
def _(message): return message
animals = [_('mollusk'),
_('albatross'),
_('rat'),
_('penguin'),
_('python'),
]
del _
# ...
for a in animals:
print _(a)
This works because the dummy definition of _() simply returns
the string unchanged. And this dummy definition will temporarily
override any definition of _() in the built-in namespace
(until the del command).
Take care, though if you have a previous definition of _ in
the local namespace.
Note that the second use of _() will not identify ``a'' as
being translatable to the pygettext program, since it is not
a string.
Another way to handle this is with the following example:
def N_(message): return message
animals = [N_('mollusk'),
N_('albatross'),
N_('rat'),
N_('penguin'),
N_('python'),
]
# ...
for a in animals:
print _(a)
In this case, you are marking translatable strings with the function
N_(),The choice of N_() here is totally
arbitrary; it could have just as easily been
MarkThisStringForTranslation().
which won't conflict with any definition of
_(). However, you will need to teach your message extraction
program to look for translatable strings marked with N_().
pygettext and xpot both support this through the
use of command line switches.
</description>
</group>
<group name="Acknowledgements">
</group>
</group>
<group name="logging --- Logging facility for Python">
<description>% These apply to all modules, and may be given more than once:
Logging module for Python based on 282.
New in version 2.3
This module defines functions and classes which implement a flexible
error logging system for applications.
Logging is performed by calling methods on instances of the
Logger class (hereafter called loggers). Each instance has a
name, and they are conceptually arranged in a name space hierarchy
using dots (periods) as separators. For example, a logger named
&quot;scan&quot; is the parent of loggers &quot;scan.text&quot;, &quot;scan.html&quot; and &quot;scan.pdf&quot;.
Logger names can be anything you want, and indicate the area of an
application in which a logged message originates.
Logged messages also have levels of importance associated with them.
The default levels provided are DEBUG, INFO,
WARNING, ERROR and CRITICAL. As a
convenience, you indicate the importance of a logged message by calling
an appropriate method of Logger. The methods are
debug(), info(), warning(), error() and
critical(), which mirror the default levels. You are not
constrained to use these levels: you can specify your own and use a
more general Logger method, log(), which takes an
explicit level argument.
Levels can also be associated with loggers, being set either by the
developer or through loading a saved logging configuration. When a
logging method is called on a logger, the logger compares its own
level with the level associated with the method call. If the logger's
level is higher than the method call's, no logging message is actually
generated. This is the basic mechanism controlling the verbosity of
logging output.
Logging messages are encoded as instances of the LogRecord class.
When a logger decides to actually log an event, an LogRecord
instance is created from the logging message.
Logging messages are subjected to a dispatch mechanism through the
use of handlers, which are instances of subclasses of the
Handler class. Handlers are responsible for ensuring that a logged
message (in the form of a LogRecord) ends up in a particular
location (or set of locations) which is useful for the target audience for
that message (such as end users, support desk staff, system administrators,
developers). Handlers are passed LogRecord instances intended for
particular destinations. Each logger can have zero, one or more handlers
associated with it (via the addHandler method of Logger).
In addition to any handlers directly associated with a logger,
all handlers associated with all ancestors of the logger are
called to dispatch the message.
Just as for loggers, handlers can have levels associated with them.
A handler's level acts as a filter in the same way as a logger's level does.
If a handler decides to actually dispatch an event, the emit() method
is used to send the message to its destination. Most user-defined subclasses
of Handler will need to override this emit().
In addition to the base Handler class, many useful subclasses
are provided:
StreamHandler instances send error messages to
streams (file-like objects).
FileHandler instances send error messages to disk
files.
RotatingFileHandler instances send error messages to disk
files, with support for maximum log file sizes and log file rotation.
SocketHandler instances send error messages to
TCP/IP sockets.
DatagramHandler instances send error messages to UDP
sockets.
SMTPHandler instances send error messages to a
designated email address.
SysLogHandler instances send error messages to a
syslog daemon, possibly on a remote machine.
NTEventLogHandler instances send error messages to a
Windows NT/2000/XP event log.
MemoryHandler instances send error messages to a
buffer in memory, which is flushed whenever specific criteria are
met.
HTTPHandler instances send error messages to an
HTTP server using either GET or POST semantics.
The StreamHandler and FileHandler classes are defined
in the core logging package. The other handlers are defined in a sub-
module, logging.handlers. (There is also another sub-module,
logging.config, for configuration functionality.)
Logged messages are formatted for presentation through instances of the
Formatter class. They are initialized with a format string
suitable for use with the % operator and a dictionary.
For formatting multiple messages in a batch, instances of
BufferingFormatter can be used. In addition to the format string
(which is applied to each message in the batch), there is provision for
header and trailer format strings.
When filtering based on logger level and/or handler level is not enough,
instances of Filter can be added to both Logger and
Handler instances (through their addFilter() method).
Before deciding to process a message further, both loggers and handlers
consult all their filters for permission. If any filter returns a false
value, the message is not processed further.
The basic Filter functionality allows filtering by specific logger
name. If this feature is used, messages sent to the named logger and its
children are allowed through the filter, and all others dropped.
In addition to the classes described above, there are a number of module-
level functions.
</description>
<element kind="function" name="getLogger">
<description>Return a logger with the specified name or, if no name is specified, return
a logger which is the root logger of the hierarchy.
All calls to this function with a given name return the same logger instance.
This means that logger instances never need to be passed between different
parts of an application.</description>

<properties><property kind="parameter" name="name" required="1"/></properties></element>

<element kind="function" name="debug">
<description>Logs a message with level DEBUG on the root logger.
The msg is the message format string, and the args are the
arguments which are merged into msg. The only keyword argument in
kwargs which is inspected is exc_info which, if it does not
evaluate as false, causes exception information (via a call to
sys.exc_info()) to be added to the logging message.</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="info">
<description>Logs a message with level INFO on the root logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="warning">
<description>Logs a message with level WARNING on the root logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="error">
<description>Logs a message with level ERROR on the root logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="critical">
<description>Logs a message with level CRITICAL on the root logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="exception">
<description>Logs a message with level ERROR on the root logger.
The arguments are interpreted as for debug(). Exception info
is added to the logging message. This function should only be called
from an exception handler.</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/></properties></element>

<element kind="function" name="disable">
<description>Provides an overriding level lvl for all loggers which takes
precedence over the logger's own level. When the need arises to
temporarily throttle logging output down across the whole application,
this function can be useful.</description>

<properties><property kind="parameter" name="lvllvl" required="1"/></properties></element>

<element kind="function" name="addLevelName">
<description>Associates level lvl with text levelName in an internal
dictionary, which is used to map numeric levels to a textual
representation, for example when a Formatter formats a message.
This function can also be used to define your own levels. The only
constraints are that all levels used must be registered using this
function, levels should be positive integers and they should increase
in increasing order of severity.</description>

<properties><property kind="parameter" name="lvl" required="1"/><property kind="parameter" name="levelName levelName" required="1"/></properties></element>

<element kind="function" name="getLevelName">
<description>Returns the textual representation of logging level lvl. If the
level is one of the predefined levels CRITICAL,
ERROR, WARNING, INFO or DEBUG
then you get the corresponding string. If you have associated levels
with names using addLevelName() then the name you have associated
with lvl is returned. Otherwise, the string &quot;Level &quot; % lvl is
returned.</description>

<properties><property kind="parameter" name="lvllvl" required="1"/></properties></element>

<element kind="function" name="makeLogRecord">
<description>Creates and returns a new LogRecord instance whose attributes are
defined by attrdict. This function is useful for taking a pickled
LogRecord attribute dictionary, sent over a socket, and reconstituting
it as a LogRecord instance at the receiving end.</description>

<properties><property kind="parameter" name="attrdictattrdict" required="1"/></properties></element>

<element kind="function" name="basicConfig">
<description>Does basic configuration for the logging system by creating a
StreamHandler with a default Formatter and adding it to
the root logger. The functions debug(), info(),
warning(), error() and critical() will call
basicConfig() automatically if no handlers are defined for the
root logger.</description>

</element>

<element kind="function" name="shutdown">
<description>Informs the logging system to perform an orderly shutdown by flushing and
closing all handlers.</description>

</element>

<element kind="function" name="setLoggerClass">
<description>Tells the logging system to use the class klass when instantiating a
logger. The class should define __init__() such that only a name
argument is required, and the __init__() should call
Logger.__init__(). This function is typically called before any
loggers are instantiated by applications which need to use custom logger
behavior.</description>

<properties><property kind="parameter" name="klassklass" required="1"/></properties></element>

<group name="Logger Objects">
<description>Loggers have the following attributes and methods. Note that Loggers are
never instantiated directly, but always through the module-level function
logging.getLogger(name).
{propagate}
If this evaluates to false, logging messages are not passed by this
logger or by child loggers to higher level (ancestor) loggers. The
constructor sets this attribute to 1.
</description>
<element kind="function" name="setLevel">
<description>Sets the threshold for this logger to lvl. Logging messages
which are less severe than lvl will be ignored. When a logger is
created, the level is set to NOTSET (which causes all messages
to be processed in the root logger, or delegation to the parent in non-root
loggers).</description>

<properties><property kind="parameter" name="lvllvl" required="1"/></properties></element>

<element kind="function" name="isEnabledFor">
<description>Indicates if a message of severity lvl would be processed by
this logger. This method checks first the module-level level set by
logging.disable(lvl) and then the logger's effective level as
determined by getEffectiveLevel().</description>

<properties><property kind="parameter" name="lvllvl" required="1"/></properties></element>

<element kind="function" name="getEffectiveLevel">
<description>Indicates the effective level for this logger. If a value other than
NOTSET has been set using setLevel(), it is returned.
Otherwise, the hierarchy is traversed towards the root until a value
other than NOTSET is found, and that value is returned.</description>

</element>

<element kind="function" name="debug">
<description>Logs a message with level DEBUG on this logger.
The msg is the message format string, and the args are the
arguments which are merged into msg. The only keyword argument in
kwargs which is inspected is exc_info which, if it does not
evaluate as false, causes exception information (via a call to
sys.exc_info()) to be added to the logging message.</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="info">
<description>Logs a message with level INFO on this logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="warning">
<description>Logs a message with level WARNING on this logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="error">
<description>Logs a message with level ERROR on this logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="critical">
<description>Logs a message with level CRITICAL on this logger.
The arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="log">
<description>Logs a message with level lvl on this logger.
The other arguments are interpreted as for debug().</description>

<properties><property kind="parameter" name="lvl" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/><property kind="parameter" name="**kwargs"/></properties></element>

<element kind="function" name="exception">
<description>Logs a message with level ERROR on this logger.
The arguments are interpreted as for debug(). Exception info
is added to the logging message. This method should only be called
from an exception handler.</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/></properties></element>

<element kind="function" name="addFilter">
<description>Adds the specified filter filt to this logger.</description>

<properties><property kind="parameter" name="filtfilt" required="1"/></properties></element>

<element kind="function" name="removeFilter">
<description>Removes the specified filter filt from this logger.</description>

<properties><property kind="parameter" name="filtfilt" required="1"/></properties></element>

<element kind="function" name="filter">
<description>Applies this logger's filters to the record and returns a true value if
the record is to be processed.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="addHandler">
<description>Adds the specified handler hdlr to this logger.</description>

<properties><property kind="parameter" name="hdlrhdlr" required="1"/></properties></element>

<element kind="function" name="removeHandler">
<description>Removes the specified handler hdlr from this logger.</description>

<properties><property kind="parameter" name="hdlrhdlr" required="1"/></properties></element>

<element kind="function" name="findCaller">
<description>Finds the caller's source filename and line number. Returns the filename
and line number as a 2-element tuple.</description>

</element>

<element kind="function" name="handle">
<description>Handles a record by passing it to all handlers associated with this logger
and its ancestors (until a false value of propagate is found).
This method is used for unpickled records received from a socket, as well
as those created locally. Logger-level filtering is applied using
filter().</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="makeRecord">
<description>This is a factory method which can be overridden in subclasses to create
specialized LogRecord instances.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="lvl" required="1"/><property kind="parameter" name="fn" required="1"/><property kind="parameter" name="lno" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="args" required="1"/><property kind="parameter" name="exc_info exc_info" required="1"/></properties></element>

</group>
<group name="Handler Objects">
<description>Handlers have the following attributes and methods. Note that
Handler is never instantiated directly; this class acts as a
base for more useful subclasses. However, the __init__()
method in subclasses needs to call Handler.__init__().
</description>
<element kind="function" name="__init__">
<description>Initializes the Handler instance by setting its level, setting
the list of filters to the empty list and creating a lock (using
createLock()) for serializing access to an I/O mechanism.</description>

<properties><property default="NOTSET" kind="parameter" name="level" required="1"/></properties></element>

<element kind="function" name="createLock">
<description>Initializes a thread lock which can be used to serialize access to
underlying I/O functionality which may not be threadsafe.</description>

</element>

<element kind="function" name="acquire">
<description>Acquires the thread lock created with createLock().</description>

</element>

<element kind="function" name="release">
<description>Releases the thread lock acquired with acquire().</description>

</element>

<element kind="function" name="setLevel">
<description>Sets the threshold for this handler to lvl. Logging messages which are
less severe than lvl will be ignored. When a handler is created, the
level is set to NOTSET (which causes all messages to be processed).</description>

<properties><property kind="parameter" name="lvllvl" required="1"/></properties></element>

<element kind="function" name="setFormatter">
<description>Sets the Formatter for this handler to form.</description>

<properties><property kind="parameter" name="formform" required="1"/></properties></element>

<element kind="function" name="addFilter">
<description>Adds the specified filter filt to this handler.</description>

<properties><property kind="parameter" name="filtfilt" required="1"/></properties></element>

<element kind="function" name="removeFilter">
<description>Removes the specified filter filt from this handler.</description>

<properties><property kind="parameter" name="filtfilt" required="1"/></properties></element>

<element kind="function" name="filter">
<description>Applies this handler's filters to the record and returns a true value if
the record is to be processed.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="flush">
<description>Ensure all logging output has been flushed. This version does
nothing and is intended to be implemented by subclasses.</description>

</element>

<element kind="function" name="close">
<description>Tidy up any resources used by the handler. This version does
nothing and is intended to be implemented by subclasses.</description>

</element>

<element kind="function" name="handle">
<description>Conditionally emits the specified logging record, depending on
filters which may have been added to the handler. Wraps the actual
emission of the record with acquisition/release of the I/O thread
lock.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="handleError">
<description>This method should be called from handlers when an exception is
encountered during an emit() call. By default it does nothing,
which means that exceptions get silently ignored. This is what is
mostly wanted for a logging system - most users will not care
about errors in the logging system, they are more interested in
application errors. You could, however, replace this with a custom
handler if you wish.</description>

</element>

<element kind="function" name="format">
<description>Do formatting for a record - if a formatter is set, use it.
Otherwise, use the default formatter for the module.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="emit">
<description>Do whatever it takes to actually log the specified logging record.
This version is intended to be implemented by subclasses and so
raises a NotImplementedError.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="StreamHandler">
<description>Returns a new instance of the StreamHandler class. If strm is
specified, the instance will use it for logging output; otherwise,
sys.stderr will be used.</description>

<properties><property kind="parameter" name="strm" required="1"/></properties></element>

<element kind="function" name="emit">
<description>If a formatter is specified, it is used to format the record.
The record is then written to the stream with a trailing newline.
If exception information is present, it is formatted using
traceback.print_exception() and appended to the stream.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="flush">
<description>Flushes the stream by calling its flush() method. Note that
the close() method is inherited from Handler and
so does nothing, so an explicit flush() call may be needed
at times.</description>

</element>

<element kind="function" name="FileHandler">
<description>Returns a new instance of the FileHandler class. The specified
file is opened and used as the stream for logging. If mode is
not specified, 'a' is used. By default, the file grows
indefinitely.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="close">
<description>Closes the file.</description>

</element>

<element kind="function" name="emit">
<description>Outputs the record to the file.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="RotatingFileHandler">
<description>Returns a new instance of the RotatingFileHandler class. The
specified file is opened and used as the stream for logging. If
mode is not specified, 'a' is used. By default, the
file grows indefinitely. You can use the maxBytes and
backupCount values to allow the file to rollover at a
predetermined size. When the size is about to be exceeded, the file is
closed and a new file is silently opened for output. Rollover occurs
whenever the current log file is nearly maxBytes in length; if
maxBytes is zero, rollover never occurs. If backupCount
is non-zero, the system will save old log files by appending the
extensions &quot;.1&quot;, &quot;.2&quot; etc., to the filename. For example, with
a backupCount of 5 and a base file name of
app.log, you would get app.log,
app.log.1, app.log.2, up to app.log.5. The file being
written to is always app.log. When this file is filled, it is
closed and renamed to app.log.1, and if files app.log.1,
app.log.2, etc. exist, then they are renamed to app.log.2,
app.log.3 etc. respectively.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="maxBytes"/><property kind="parameter" name="backupCount"/></properties></element>

<element kind="function" name="doRollover">
<description>Does a rollover, as described above.</description>

</element>

<element kind="function" name="emit">
<description>Outputs the record to the file, catering for rollover as described
in setRollover().</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="SocketHandler">
<description>Returns a new instance of the SocketHandler class intended to
communicate with a remote machine whose address is given by host
and port.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port port" required="1"/></properties></element>

<element kind="function" name="close">
<description>Closes the socket.</description>

</element>

<element kind="function" name="handleError">
<description/>

</element>

<element kind="function" name="emit">
<description>Pickles the record's attribute dictionary and writes it to the socket in
binary format. If there is an error with the socket, silently drops the
packet. If the connection was previously lost, re-establishes the connection.
To unpickle the record at the receiving end into a LogRecord, use the
makeLogRecord function.</description>

</element>

<element kind="function" name="handleError">
<description>Handles an error which has occurred during emit(). The
most likely cause is a lost connection. Closes the socket so that
we can retry on the next event.</description>

</element>

<element kind="function" name="makeSocket">
<description>This is a factory method which allows subclasses to define the precise
type of socket they want. The default implementation creates a TCP
socket (socket.SOCK_STREAM).</description>

</element>

<element kind="function" name="makePickle">
<description>Pickles the record's attribute dictionary in binary format with a length
prefix, and returns it ready for transmission across the socket.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="send">
<description>Send a pickled string packet to the socket. This function allows
for partial sends which can happen when the network is busy.</description>

<properties><property kind="parameter" name="packetpacket" required="1"/></properties></element>

<element kind="function" name="DatagramHandler">
<description>Returns a new instance of the DatagramHandler class intended to
communicate with a remote machine whose address is given by host
and port.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port port" required="1"/></properties></element>

<element kind="function" name="emit">
<description>Pickles the record's attribute dictionary and writes it to the socket in
binary format. If there is an error with the socket, silently drops the
packet.
To unpickle the record at the receiving end into a LogRecord, use the
makeLogRecord function.</description>

</element>

<element kind="function" name="makeSocket">
<description>The factory method of SocketHandler is here overridden to create
a UDP socket (socket.SOCK_DGRAM).</description>

</element>

<element kind="function" name="send">
<description>Send a pickled string to a socket.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="SysLogHandler">
<description>Returns a new instance of the SysLogHandler class intended to
communicate with a remote machine whose address is given by
address in the form of a (host, port)
tuple. If address is not specified, ('localhost', 514) is
used. The address is used to open a UDP socket. If facility is
not specified, LOG_USER is used.</description>

<properties><property kind="parameter" name="address" required="1"/><property kind="parameter" name="facility"/></properties></element>

<element kind="function" name="close">
<description>Closes the socket to the remote host.</description>

</element>

<element kind="function" name="emit">
<description>The record is formatted, and then sent to the syslog server. If
exception information is present, it is not sent to the server.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="encodePriority">
<description>Encodes the facility and priority into an integer. You can pass in strings
or integers - if strings are passed, internal mapping dictionaries are used
to convert them to integers.</description>

<properties><property kind="parameter" name="facility" required="1"/><property kind="parameter" name="priority priority" required="1"/></properties></element>

<element kind="function" name="NTEventLogHandler">
<description>Returns a new instance of the NTEventLogHandler class. The
appname is used to define the application name as it appears in the
event log. An appropriate registry entry is created using this name.
The dllname should give the fully qualified pathname of a .dll or .exe
which contains message definitions to hold in the log (if not specified,
'win32service.pyd' is used - this is installed with the Win32
extensions and contains some basic placeholder message definitions.
Note that use of these placeholders will make your event logs big, as the
entire message source is held in the log. If you want slimmer logs, you have
to pass in the name of your own .dll or .exe which contains the message
definitions you want to use in the event log). The logtype is one of
'Application', 'System' or 'Security', and
defaults to 'Application'.</description>

<properties><property kind="parameter" name="appname" required="1"/><property kind="parameter" name="dllname"/><property kind="parameter" name="logtype"/></properties></element>

<element kind="function" name="close">
<description>At this point, you can remove the application name from the registry as a
source of event log entries. However, if you do this, you will not be able
to see the events as you intended in the Event Log Viewer - it needs to be
able to access the registry to get the .dll name. The current version does
not do this (in fact it doesn't do anything).</description>

</element>

<element kind="function" name="emit">
<description>Determines the message ID, event category and event type, and then logs the
message in the NT event log.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="getEventCategory">
<description>Returns the event category for the record. Override this if you
want to specify your own categories. This version returns 0.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="getEventType">
<description>Returns the event type for the record. Override this if you want
to specify your own types. This version does a mapping using the
handler's typemap attribute, which is set up in __init__()
to a dictionary which contains mappings for DEBUG,
INFO, WARNING, ERROR and
CRITICAL. If you are using your own levels, you will either need
to override this method or place a suitable dictionary in the
handler's typemap attribute.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="getMessageID">
<description>Returns the message ID for the record. If you are using your
own messages, you could do this by having the msg passed to the
logger being an ID rather than a format string. Then, in here,
you could use a dictionary lookup to get the message ID. This
version returns 1, which is the base message ID in
win32service.pyd.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="SMTPHandler">
<description>Returns a new instance of the SMTPHandler class. The
instance is initialized with the from and to addresses and subject
line of the email. The toaddrs should be a list of strings without
domain names (That's what the mailhost is for). To specify a
non-standard SMTP port, use the (host, port) tuple format for the
mailhost argument. If you use a string, the standard SMTP port
is used.</description>

<properties><property kind="parameter" name="mailhost" required="1"/><property kind="parameter" name="fromaddr" required="1"/><property kind="parameter" name="toaddrs" required="1"/><property kind="parameter" name="subject subject" required="1"/></properties></element>

<element kind="function" name="emit">
<description>Formats the record and sends it to the specified addressees.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="getSubject">
<description>If you want to specify a subject line which is record-dependent,
override this method.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="BufferingHandler">
<description>Initializes the handler with a buffer of the specified capacity.</description>

<properties><property kind="parameter" name="capacitycapacity" required="1"/></properties></element>

<element kind="function" name="emit">
<description>Appends the record to the buffer. If shouldFlush() returns true,
calls flush() to process the buffer.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="flush">
<description>You can override this to implement custom flushing behavior. This version
just zaps the buffer to empty.</description>

</element>

<element kind="function" name="shouldFlush">
<description>Returns true if the buffer is up to capacity. This method can be
overridden to implement custom flushing strategies.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="MemoryHandler">
<description>Returns a new instance of the MemoryHandler class. The
instance is initialized with a buffer size of capacity. If
flushLevel is not specified, ERROR is used. If no
target is specified, the target will need to be set using
setTarget() before this handler does anything useful.</description>

<properties><property kind="parameter" name="capacity" required="1"/><property kind="parameter" name="flushLevel"/><property kind="parameter" name="target"/></properties></element>

<element kind="function" name="close">
<description>Calls flush(), sets the target to None and
clears the buffer.</description>

</element>

<element kind="function" name="flush">
<description>For a MemoryHandler, flushing means just sending the buffered
records to the target, if there is one. Override if you want
different behavior.</description>

</element>

<element kind="function" name="setTarget">
<description>Sets the target handler for this handler.</description>

<properties><property kind="parameter" name="targettarget" required="1"/></properties></element>

<element kind="function" name="shouldFlush">
<description>Checks for buffer full or a record at the flushLevel or higher.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="HTTPHandler">
<description>Returns a new instance of the HTTPHandler class. The
instance is initialized with a host address, url and HTTP method.
If no method is specified, GET is used.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="url" required="1"/><property kind="parameter" name="method"/></properties></element>

<element kind="function" name="emit">
<description>Sends the record to the Web server as an URL-encoded dictionary.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

</group>
<group name="Formatter Objects">
<description>Formatters have the following attributes and methods. They are
responsible for converting a LogRecord to (usually) a string
which can be interpreted by either a human or an external system. The
base
Formatter allows a formatting string to be specified. If none is
supplied, the default value of '%(message)s\ is used.
A Formatter can be initialized with a format string which makes use of
knowledge of the LogRecord attributes - such as the default value
mentioned above making use of the fact that the user's message and
arguments are pre-formatted into a LogRecord's message
attribute. This format string contains standard python %-style
mapping keys. See section typesseq-strings, ``String Formatting
Operations,'' for more information on string formatting.
Currently, the useful mapping keys in a LogRecord are:
{l|l}{code}{Format}{Description}
%(name)s {Name of the logger (logging channel).}
%(levelno)s {Numeric logging level for the message
(DEBUG, INFO,
WARNING, ERROR,
CRITICAL).}
%(levelname)s{Text logging level for the message
('DEBUG', 'INFO',
'WARNING', 'ERROR',
'CRITICAL').}
%(pathname)s {Full pathname of the source file where the logging
call was issued (if available).}
%(filename)s {Filename portion of pathname.}
%(module)s {Module (name portion of filename).}
%(lineno)d {Source line number where the logging call was issued
(if available).}
%(created)f {Time when the LogRecord was created (as
returned by time.time()).}
%(asctime)s {Human-readable time when the LogRecord was created.
By default this is of the form
``2003-07-08 16:49:45,896'' (the numbers after the
comma are millisecond portion of the time).}
%(msecs)d {Millisecond portion of the time when the
LogRecord was created.}
%(thread)d {Thread ID (if available).}
%(process)d {Process ID (if available).}
%(message)s {The logged message, computed as msg % args.}
</description>
<element kind="function" name="Formatter">
<description>Returns a new instance of the Formatter class. The
instance is initialized with a format string for the message as a whole,
as well as a format string for the date/time portion of a message. If
no fmt is specified, '%(message)s' is used. If no datefmt
is specified, the ISO8601 date format is used.</description>

<properties><property kind="parameter" name="fmt" required="1"/><property kind="parameter" name="datefmt"/></properties></element>

<element kind="function" name="format">
<description>The record's attribute dictionary is used as the operand to a
string formatting operation. Returns the resulting string.
Before formatting the dictionary, a couple of preparatory steps
are carried out. The message attribute of the record is computed
using msg % args. If the formatting string contains
'(asctime)', formatTime() is called to format the
event time. If there is exception information, it is formatted using
formatException() and appended to the message.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

<element kind="function" name="formatTime">
<description>This method should be called from format() by a formatter which
wants to make use of a formatted time. This method can be overridden
in formatters to provide for any specific requirement, but the
basic behavior is as follows: if datefmt (a string) is specified,
it is used with time.strftime() to format the creation time of the
record. Otherwise, the ISO8601 format is used. The resulting
string is returned.</description>

<properties><property kind="parameter" name="record" required="1"/><property kind="parameter" name="datefmt"/></properties></element>

<element kind="function" name="formatException">
<description>Formats the specified exception information (a standard exception tuple
as returned by sys.exc_info()) as a string. This default
implementation just uses traceback.print_exception().
The resulting string is returned.</description>

<properties><property kind="parameter" name="exc_infoexc_info" required="1"/></properties></element>

</group>
<group name="Filter Objects">
<description>Filters can be used by Handlers and Loggers for
more sophisticated filtering than is provided by levels. The base filter
class only allows events which are below a certain point in the logger
hierarchy. For example, a filter initialized with &quot;A.B&quot; will allow events
logged by loggers &quot;A.B&quot;, &quot;A.B.C&quot;, &quot;A.B.C.D&quot;, &quot;A.B.D&quot; etc. but not &quot;A.BB&quot;,
&quot;B.A.B&quot; etc. If initialized with the empty string, all events are passed.
</description>
<element kind="function" name="Filter">
<description>Returns an instance of the Filter class. If name is specified,
it names a logger which, together with its children, will have its events
allowed through the filter. If no name is specified, allows every event.</description>

<properties><property kind="parameter" name="name" required="1"/></properties></element>

<element kind="function" name="filter">
<description>Is the specified record to be logged? Returns zero for no, nonzero for
yes. If deemed appropriate, the record may be modified in-place by this
method.</description>

<properties><property kind="parameter" name="recordrecord" required="1"/></properties></element>

</group>
<group name="LogRecord Objects">
<description>LogRecord instances are created every time something is logged. They
contain all the information pertinent to the event being logged. The
main information passed in is in msg and args, which are combined
using msg % args to create the message field of the record. The record
also includes information such as when the record was created, the
source line where the logging call was made, and any exception
information to be logged.
LogRecord has no methods; it's just a repository for information about the
logging event. The only reason it's a class rather than a dictionary is to
facilitate extension.
</description>
<element kind="function" name="LogRecord">
<description>Returns an instance of LogRecord initialized with interesting
information. The name is the logger name; lvl is the
numeric level; pathname is the absolute pathname of the source
file in which the logging call was made; lineno is the line
number in that file where the logging call is found; msg is the
user-supplied message (a format string); args is the tuple
which, together with msg, makes up the user message; and
exc_info is the exception tuple obtained by calling
sys.exc_info() (or None, if no exception information
is available).</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="lvl" required="1"/><property kind="parameter" name="pathname" required="1"/><property kind="parameter" name="lineno" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="args" required="1"/><property kind="parameter" name="exc_info                              exc_info" required="1"/></properties></element>

</group>
<group name="Thread Safety">
<description>The logging module is intended to be thread-safe without any special work
needing to be done by its clients. It achieves this though using threading
locks; there is one lock to serialize access to the module's shared data,
and each handler also creates a lock to serialize access to its underlying
I/O.
</description>
</group>
<group name="Configuration">
<description>Configuration functions
The following functions allow the logging module to be
configured. Before they can be used, you must import
logging.config. Their use is optional --- you can configure
the logging module entirely by making calls to the main API (defined
in logging itself) and defining handlers which are declared
either in logging or logging.handlers.
</description>
<element kind="function" name="fileConfig">
<description>Reads the logging configuration from a ConfigParser-format file named
fname. This function can be called several times from an application,
allowing an end user the ability to select from various pre-canned
configurations (if the developer provides a mechanism to present the
choices and load the chosen configuration). Defaults to be passed to
ConfigParser can be specified in the defaults argument.</description>

<properties><property kind="parameter" name="fname" required="1"/><property kind="parameter" name="defaults"/></properties></element>

<element kind="function" name="listen">
<description>Starts up a socket server on the specified port, and listens for new
configurations. If no port is specified, the module's default
DEFAULT_LOGGING_CONFIG_PORT is used. Logging configurations
will be sent as a file suitable for processing by fileConfig().
Returns a Thread instance on which you can call start()
to start the server, and which you can join() when appropriate.
To stop the server, call stopListening().</description>

<properties><property kind="parameter" name="port" required="1"/></properties></element>

<element kind="function" name="stopListening">
<description>Stops the listening server which was created with a call to
listen(). This is typically called before calling join()
on the return value from listen().</description>

</element>

</group>
<group name="Using the logging package">
</group>
</group>
<group name="platform --- Access to underlying platform's identifying data.">
<description>Retrieves as much platform identifying data as possible.
New in version 2.3
Specific platforms listed alphabetically, with Linux included in the
section.
</description>
<group name="Cross Platform">
<element kind="function" name="architecture">
<description>Queries the given executable (defaults to the Python interpreter
binary) for various architecture informations.
Returns a tuple (bits, linkage) which contain information about
the bit architecture and the linkage format used for the
executable. Both values are returned as strings.
Values that cannot be determined are returned as given by the
parameter presets. If bits is given as '', the
sizeof(pointer)
(or sizeof(long) on Python version &lt; 1.5.2) is used as
indicator for the supported pointer size.
The function relies on the system's file command to do the
actual work. This is available on most if not all platforms and some non- platforms and then only if the
executable points to the Python interpreter. Reasonable defaults
are used when the above needs are not met.</description>

<properties><property default="sys.executable" kind="parameter" name="executable" required="1"/><property default="''" kind="parameter" name="bits" required="1"/><property default="'' linkage=''" kind="parameter" name="linkage" required="1"/></properties></element>

<element kind="function" name="machine">
<description>Returns the machine type, e.g. 'i386'.
An empty string is returned if the value cannot be determined.</description>

</element>

<element kind="function" name="node">
<description>Returns the computer's network name (may not be fully qualified!).
An empty string is returned if the value cannot be determined.</description>

</element>

<element kind="function" name="platform">
<description>Returns a single string identifying the underlying platform
with as much useful information as possible.
The output is intended to be human readable rather than
machine parseable. It may look different on different platforms and
this is intended.
If aliased is true, the function will use aliases for various
platforms that report system names which differ from their common
names, for example SunOS will be reported as Solaris. The
system_alias() function is used to implement this.
Setting terse to true causes the function to return only the
absolute minimum information needed to identify the platform.</description>

<properties><property default="0" kind="parameter" name="aliased" required="1"/><property default="0 terse=0" kind="parameter" name="terse" required="1"/></properties></element>

<element kind="function" name="processor">
<description>Returns the (real) processor name, e.g. 'amdk6'.
An empty string is returned if the value cannot be determined. Note
that many platforms do not provide this information or simply return
the same value as for machine(). NetBSD does this.</description>

</element>

<element kind="function" name="python_build">
<description>Returns a tuple (buildno, builddate) stating the
Python build number and date as strings.</description>

</element>

<element kind="function" name="python_compiler">
<description>Returns a string identifying the compiler used for compiling Python.</description>

</element>

<element kind="function" name="python_version">
<description>Returns the Python version as string 'major.minor.patchlevel'
Note that unlike the Python sys.version, the returned value
will always include the patchlevel (it defaults to 0).</description>

</element>

<element kind="function" name="python_version_tuple">
<description>Returns the Python version as tuple (major, minor,
patchlevel) of strings.
Note that unlike the Python sys.version, the returned value
will always include the patchlevel (it defaults to '0').</description>

</element>

<element kind="function" name="release">
<description>Returns the system's release, e.g. '2.2.0' or 'NT'
An empty string is returned if the value cannot be determined.</description>

</element>

<element kind="function" name="system">
<description>Returns the system/OS name, e.g. 'Linux', 'Windows',
or 'Java'.
An empty string is returned if the value cannot be determined.</description>

</element>

<element kind="function" name="system_alias">
<description>Returns (system, release, version) aliased
to common marketing names used for some systems. It also does some
reordering of the information in some cases where it would otherwise
cause confusion.</description>

<properties><property kind="parameter" name="system" required="1"/><property kind="parameter" name="release" required="1"/><property kind="parameter" name="version version" required="1"/></properties></element>

<element kind="function" name="version">
<description>Returns the system's release version, e.g. ' degas'.
An empty string is returned if the value cannot be determined.</description>

</element>

<element kind="function" name="uname">
<description>Fairly portable uname interface. Returns a tuple of strings
(system, node, release, version,
machine, processor) identifying the underlying
platform.
Note that unlike the os.uname() function this also returns
possible processor information as additional tuple entry.
Entries which cannot be determined are set to ''.</description>

</element>

</group>
<group name="Java Platform">
<element kind="function" name="java_ver">
<description>Version interface for JPython.
Returns a tuple (release, vendor, vminfo,
osinfo) with vminfo being a tuple (vm_name,
vm_release, vm_vendor) and osinfo being a tuple
(os_name, os_version, os_arch).
Values which cannot be determined are set to the defaults
given as parameters (which all default to '').</description>

<properties><property default="''" kind="parameter" name="release" required="1"/><property default="''" kind="parameter" name="vendor" required="1"/><property default="(''" kind="parameter" name="vminfo" required="1"/><property kind="parameter" name="''" required="1"/><property kind="parameter" name="'')" required="1"/><property default="(''" kind="parameter" name="osinfo" required="1"/><property kind="parameter" name="''" required="1"/><property kind="parameter" name="'')'')" required="1"/></properties></element>

</group>
<group name="Windows Platform">
<element kind="function" name="win32_ver">
<description>Get additional version information from the Windows Registry
and return a tuple (version, csd, ptype)
referring to version number, CSD level and OS type (multi/single
processor).
As a hint: ptype is 'Uniprocessor Free' on single
processor NT machines and 'Multiprocessor Free' on multi
processor machines. The 'Free' refers to the OS version being
free of debugging code. It could also state 'Checked' which
means the OS version uses debugging code, i.e. code that
checks arguments, ranges, etc.
[note]
This function only works if Mark Hammond's win32all
package is installed and (obviously) only runs on Win32
compatible platforms.
</description>

<properties><property default="''" kind="parameter" name="release" required="1"/><property default="''" kind="parameter" name="version" required="1"/><property default="''" kind="parameter" name="csd" required="1"/><property default="'' ptype=''" kind="parameter" name="ptype" required="1"/></properties></element>

<element kind="function" name="popen">
<description>Portable popen() interface. Find a working popen
implementation preferring win32pipe.popen(). On Windows
NT, win32pipe.popen() should work; on Windows 9x it hangs
due to bugs in the MS C library.
% This KnowledgeBase article appears to be missing...
%See also MS KnowledgeBase article Q150956{}.</description>

<properties><property kind="parameter" name="cmd" required="1"/><property default="'r'" kind="parameter" name="mode" required="1"/><property default="None bufsize=None" kind="parameter" name="bufsize" required="1"/></properties></element>

</group>
<group name="Mac OS Platform">
<element kind="function" name="mac_ver">
<description>Get Mac OS version information and return it as tuple
(release, versioninfo, machine) with
versioninfo being a tuple (version,
dev_stage, non_release_version).
Entries which cannot be determined are set to ''. All tuple
entries are strings.
Documentation for the underlying gestalt() API is
available online at http://www.rgaros.nl/gestalt/.</description>

<properties><property default="''" kind="parameter" name="release" required="1"/><property default="(''" kind="parameter" name="versioninfo" required="1"/><property kind="parameter" name="''" required="1"/><property kind="parameter" name="'')" required="1"/><property default="'' machine=''" kind="parameter" name="machine" required="1"/></properties></element>

</group>
<group name="Platforms">
<element kind="function" name="dist">
<description>Tries to determine the name of the OS distribution name
Returns a tuple (distname, version, id)
which defaults to the args given as parameters.</description>

<properties><property default="''" kind="parameter" name="distname" required="1"/><property default="''" kind="parameter" name="version" required="1"/><property default="''" kind="parameter" name="id" required="1"/><property default="('SuSE'" kind="parameter" name="supported_dists" required="1"/><property kind="parameter" name="'debian'" required="1"/><property kind="parameter" name="'redhat'" required="1"/><property kind="parameter" name="'mandrake')'mandrake')" required="1"/></properties></element>

<element kind="function" name="libc_ver">
<description>Tries to determine the libc version against which the file
executable (defaults to the Python interpreter) is linked. Returns
a tuple of strings (lib, version) which default
to the given parameters in case the lookup fails.
Note that this function has intimate knowledge of how different
libc versions add symbols to the executable is probably only
useable for executables compiled using gcc.
The file is read and scanned in chunks of chunksize bytes.</description>

<properties><property default="sys.executable" kind="parameter" name="executable" required="1"/><property default="''" kind="parameter" name="lib" required="1"/><property default="''" kind="parameter" name="version" required="1"/><property default="2048 chunksize=2048" kind="parameter" name="chunksize" required="1"/></properties></element>

</group>
</group>
</group>
<group name="Optional Operating System Services">
<group name="signal --- Set handlers for asynchronous events">
<description>Set handlers for asynchronous events.
This module provides mechanisms to use signal handlers in Python.
Some general rules for working with signals and their handlers:
A handler for a particular signal, once set, remains installed until
it is explicitly reset (Python emulates the BSD style interface
regardless of the underlying implementation), with the exception of
the handler for SIGCHLD, which follows the underlying
implementation.
There is no way to ``block'' signals temporarily from critical
sections (since this is not supported by all flavors).
Although Python signal handlers are called asynchronously as far as
the Python user is concerned, they can only occur between the
``atomic'' instructions of the Python interpreter. This means that
signals arriving during long calculations implemented purely in C
(such as regular expression matches on large bodies of text) may be
delayed for an arbitrary amount of time.
When a signal arrives during an I/O operation, it is possible that the
I/O operation raises an exception after the signal handler returns.
This is dependent on the underlying system's semantics regarding
interrupted system calls.
Because the signal handler always returns, it makes little sense to
catch synchronous errors like SIGFPE or SIGSEGV.
Python installs a small number of signal handlers by default:
SIGPIPE is ignored (so write errors on pipes and sockets can be
reported as ordinary Python exceptions) and SIGINT is translated
into a KeyboardInterrupt exception. All of these can be
overridden.
Some care must be taken if both signals and threads are used in the
same program. The fundamental thing to remember in using signals and
threads simultaneously is: perform signal() operations
in the main thread of execution. Any thread can perform an
alarm(), getsignal(), or pause();
only the main thread can set a new signal handler, and the main thread
will be the only one to receive signals (this is enforced by the
Python signal module, even if the underlying thread
implementation supports sending signals to individual threads). This
means that signals can't be used as a means of inter-thread
communication. Use locks instead.
The variables defined in the signal module are:
{SIG_DFL}
This is one of two standard signal handling options; it will simply
perform the default function for the signal. For example, on most
systems the default action for SIGQUIT is to dump core
and exit, while the default action for SIGCLD is to
simply ignore it.
{SIG_IGN}
This is another standard signal handler, which will simply ignore
the given signal.
{SIG*}
All the signal numbers are defined symbolically. For example, the
hangup signal is defined as signal.SIGHUP; the variable names
are identical to the names used in C programs, as found in
&lt;signal.h&gt;.
The man page for `signal()' lists the existing
signals (on some systems this is signal{2}, on others the
list is in signal{7}).
Note that not all systems define the same set of signal names; only
those names defined by the system are defined by this module.
{NSIG}
One more than the number of the highest signal number.
The signal module defines the following functions:
</description>
<element kind="function" name="alarm">
<description>If time is non-zero, this function requests that a
SIGALRM signal be sent to the process in time seconds.
Any previously scheduled alarm is canceled (only one alarm can
be scheduled at any time). The returned value is then the number of
seconds before any previously set alarm was to have been delivered.
If time is zero, no alarm id scheduled, and any scheduled
alarm is canceled. The return value is the number of seconds
remaining before a previously scheduled alarm. If the return value
is zero, no alarm is currently scheduled. (See the man page
alarm{2}.)
Availability: .</description>

<properties><property kind="parameter" name="timetime" required="1"/></properties></element>

<element kind="function" name="getsignal">
<description>Return the current signal handler for the signal signalnum.
The returned value may be a callable Python object, or one of the
special values signal.SIG_IGN, signal.SIG_DFL or
None. Here, signal.SIG_IGN means that the
signal was previously ignored, signal.SIG_DFL means that the
default way of handling the signal was previously in use, and
None means that the previous signal handler was not installed
from Python.</description>

<properties><property kind="parameter" name="signalnumsignalnum" required="1"/></properties></element>

<element kind="function" name="pause">
<description>Cause the process to sleep until a signal is received; the
appropriate handler will then be called. Returns nothing. Not on
Windows. (See the man page signal{2}.)</description>

</element>

<element kind="function" name="signal">
<description>Set the handler for signal signalnum to the function
handler. handler can be a callable Python object
taking two arguments (see below), or
one of the special values signal.SIG_IGN or
signal.SIG_DFL. The previous signal handler will be returned
(see the description of getsignal() above). (See the
man page signal{2}.)
When threads are enabled, this function can only be called from the
main thread; attempting to call it from other threads will cause a
ValueError exception to be raised.
The handler is called with two arguments: the signal number
and the current stack frame (None or a frame object; see the
reference manual for a description of frame objects).
frame</description>

<properties><property kind="parameter" name="signalnum" required="1"/><property kind="parameter" name="handler handler" required="1"/></properties></element>

<group name="Example">
</group>
</group>
<group name="socket --- Low-level networking interface">
<description>Low-level networking interface.
This module provides access to the BSD socket interface.
It is available on all modern systems, Windows, MacOS, BeOS,
OS/2, and probably additional platforms.
For an introduction to socket programming (in C), see the following
papers: An Introductory 4.3BSD Interprocess Communication
Tutorial, by Stuart Sechrest and An Advanced 4.3BSD
Interprocess Communication Tutorial, by Samuel J. Leffler et al,
both in the Programmer's Manual, Supplementary Documents 1
(sections PS1:7 and PS1:8). The platform-specific reference material
for the various socket-related system calls are also a valuable source
of information on the details of socket semantics. For , refer
to the manual pages; for Windows, see the WinSock (or Winsock 2)
specification.
For IPv6-ready APIs, readers may want to refer to 2553 titled
Basic Socket Interface Extensions for IPv6.
The Python interface is a straightforward transliteration of the
system call and library interface for sockets to Python's
object-oriented style: the socket() function returns a
socket objectsocket whose methods implement the
various socket system calls. Parameter types are somewhat
higher-level than in the C interface: as with read() and
write() operations on Python files, buffer allocation on
receive operations is automatic, and buffer length is implicit on send
operations.
Socket addresses are represented as follows:
A single string is used for the AF_UNIX address family.
A pair (host, port) is used for the
AF_INET address family, where host is a string
representing either a hostname in Internet domain notation like
'daring.cwi.nl' or an IPv4 address like '100.50.200.5',
and port is an integral port number.
For AF_INET6 address family, a four-tuple
(host, port, flowinfo, scopeid) is
used, where flowinfo and scopeid represents
sin6_flowinfo and sin6_scope_id member in
struct sockaddr_in6 in C.
For socket module methods, flowinfo and scopeid
can be omitted just for backward compatibility. Note, however,
omission of scopeid can cause problems in manipulating scoped
IPv6 addresses. Other address families are currently not supported.
The address format required by a particular socket object is
automatically selected based on the address family specified when the
socket object was created.
For IPv4 addresses, two special forms are accepted instead of a host
address: the empty string represents INADDR_ANY, and the string
'&lt;broadcast&gt;' represents INADDR_BROADCAST.
The behavior is not available for IPv6 for backward compatibility,
therefore, you may want to avoid these if you intend to support IPv6 with
your Python programs.
If you use a hostname in the host portion of IPv4/v6 socket
address, the program may show a nondeterministic behavior, as Python
uses the first address returned from the DNS resolution. The socket
address will be resolved differently into an actual IPv4/v6 address,
depending on the results from DNS resolution and/or the host
configuration. For deterministic behavior use a numeric address in
host portion.
All errors raise exceptions. The normal exceptions for invalid
argument types and out-of-memory conditions can be raised; errors
related to socket or address semantics raise the error
socket.error.
Non-blocking mode is supported through
setblocking(). A generalization of this based on timeouts
is supported through settimeout().
The module socket exports the following constants and functions:
{error}
This exception is raised for socket-related errors.
The accompanying value is either a string telling what went wrong or a
pair (errno, string)
representing an error returned by a system
call, similar to the value accompanying os.error.
See the module errnoerrno, which contains
names for the error codes defined by the underlying operating system.
{herror}
This exception is raised for address-related errors, i.e. for
functions that use h_errno in the C API, including
gethostbyname_ex() and gethostbyaddr().
The accompanying value is a pair (h_errno, string)
representing an error returned by a library call. string
represents the description of h_errno, as returned by
the hstrerror() C function.
{gaierror}
This exception is raised for address-related errors, for
getaddrinfo() and getnameinfo().
The accompanying value is a pair (error, string)
representing an error returned by a library call.
string represents the description of error, as returned
by the gai_strerror() C function.
{timeout}
This exception is raised when a timeout occurs on a socket which has
had timeouts enabled via a prior call to settimeout(). The
accompanying value is a string whose value is currently always ``timed
out''.
New in version 2.3
{AF_UNIX}
AF_INET
AF_INET6
These constants represent the address (and protocol) families,
used for the first argument to socket(). If the
AF_UNIX constant is not defined then this protocol is
unsupported.
{SOCK_STREAM}
SOCK_DGRAM
SOCK_RAW
SOCK_RDM
SOCK_SEQPACKET
These constants represent the socket types,
used for the second argument to socket().
(Only SOCK_STREAM and
SOCK_DGRAM appear to be generally useful.)
{SO_*}
SOMAXCONN
MSG_*
SOL_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*
Many constants of these forms, documented in the documentation on
sockets and/or the IP protocol, are also defined in the socket module.
They are generally used in arguments to the setsockopt() and
getsockopt() methods of socket objects. In most cases, only
those symbols that are defined in the header files are defined;
for a few symbols, default values are provided.
{has_ipv6}
This constant contains a boolean value which indicates if IPv6 is
supported on this platform.
New in version 2.3
</description>
<element kind="function" name="getaddrinfo">
<description>Resolves the host/port argument, into a sequence of
5-tuples that contain all the necessary argument for the sockets
manipulation. host is a domain name, a string representation of
IPv4/v6 address or None.
port is a string service name (like 'http'), a numeric
port number or None.
The rest of the arguments are optional and must be numeric if
specified. For host and port, by passing either an empty
string or None, you can pass NULL to the C API. The
getaddrinfo() function returns a list of 5-tuples with
the following structure:
(family, socktype, proto, canonname,
sockaddr)
family, socktype, proto are all integer and are meant to
be passed to the socket() function.
canonname is a string representing the canonical name of the host.
It can be a numeric IPv4/v6 address when AI_CANONNAME is specified
for a numeric host.
sockaddr is a tuple describing a socket address, as described above.
See the source for the httplib and other library modules
for a typical usage of the function.
New in version 2.2</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port" required="1"/><property kind="parameter" name="family"/><property kind="parameter" name="socktype"/><property kind="parameter" name="proto"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="getfqdn">
<description>Return a fully qualified domain name for name.
If name is omitted or empty, it is interpreted as the local
host. To find the fully qualified name, the hostname returned by
gethostbyaddr() is checked, then aliases for the host, if
available. The first name which includes a period is selected. In
case no fully qualified domain name is available, the hostname is
returned.
New in version 2.0</description>

<properties><property kind="parameter" name="name" required="1"/></properties></element>

<element kind="function" name="gethostbyname">
<description>Translate a host name to IPv4 address format. The IPv4 address is
returned as a string, such as '100.50.200.5'. If the host name
is an IPv4 address itself it is returned unchanged. See
gethostbyname_ex() for a more complete interface.
gethostbyname() does not support IPv6 name resolution, and
getaddrinfo() should be used instead for IPv4/v6 dual stack support.</description>

<properties><property kind="parameter" name="hostnamehostname" required="1"/></properties></element>

<element kind="function" name="gethostbyname_ex">
<description>Translate a host name to IPv4 address format, extended interface.
Return a triple (hostname, aliaslist,
ipaddrlist) where
hostname is the primary host name responding to the given
ip_address, aliaslist is a (possibly empty) list of
alternative host names for the same address, and ipaddrlist is
a list of IPv4 addresses for the same interface on the same
host (often but not always a single address).
gethostbyname_ex() does not support IPv6 name resolution, and
getaddrinfo() should be used instead for IPv4/v6 dual stack support.</description>

<properties><property kind="parameter" name="hostnamehostname" required="1"/></properties></element>

<element kind="function" name="gethostname">
<description>Return a string containing the hostname of the machine where the Python interpreter is currently executing.
If you want to know the current machine's IP address, you may want to use
gethostbyname(gethostname()).
This operation assumes that there is a valid address-to-host mapping for
the host, and the assumption does not always hold.
Note: gethostname() doesn't always return the fully qualified
domain name; use gethostbyaddr(gethostname())
(see below).</description>

</element>

<element kind="function" name="gethostbyaddr">
<description>Return a triple (hostname, aliaslist,
ipaddrlist) where hostname is the primary host name
responding to the given ip_address, aliaslist is a
(possibly empty) list of alternative host names for the same address,
and ipaddrlist is a list of IPv4/v6 addresses for the same interface
on the same host (most likely containing only a single address).
To find the fully qualified domain name, use the function
getfqdn().
gethostbyaddr supports both IPv4 and IPv6.</description>

<properties><property kind="parameter" name="ip_addressip_address" required="1"/></properties></element>

<element kind="function" name="getnameinfo">
<description>Translate a socket address sockaddr into a 2-tuple
(host, port).
Depending on the settings of flags, the result can contain a
fully-qualified domain name or numeric address representation in
host. Similarly, port can contain a string port name or a
numeric port number.
New in version 2.2</description>

<properties><property kind="parameter" name="sockaddr" required="1"/><property kind="parameter" name="flags flags" required="1"/></properties></element>

<element kind="function" name="getprotobyname">
<description>Translate an Internet protocol name (for example, 'icmp') to a constant
suitable for passing as the (optional) third argument to the
socket() function. This is usually only needed for sockets
opened in ``raw'' mode (SOCK_RAW); for the normal socket
modes, the correct protocol is chosen automatically if the protocol is
omitted or zero.</description>

<properties><property kind="parameter" name="protocolnameprotocolname" required="1"/></properties></element>

<element kind="function" name="getservbyname">
<description>Translate an Internet service name and protocol name to a port number
for that service. The protocol name should be 'tcp' or
'udp'.</description>

<properties><property kind="parameter" name="servicename" required="1"/><property kind="parameter" name="protocolname protocolname" required="1"/></properties></element>

<element kind="function" name="socket">
<description>Create a new socket using the given address family, socket type and
protocol number. The address family should be AF_INET, AF_INET6 or
AF_UNIX. The socket type should be SOCK_STREAM,
SOCK_DGRAM or perhaps one of the other SOCK_ constants.
The protocol number is usually zero and may be omitted in that case.</description>

<properties><property kind="parameter" name="family" required="1"/><property kind="parameter" name="type" required="1"/><property kind="parameter" name="proto"/></properties></element>

<element kind="function" name="ssl">
<description>Initiate a SSL connection over the socket sock. keyfile is
the name of a PEM formatted file that contains your private
key. certfile is a PEM formatted certificate chain file. On
success, a new SSLObject is returned.
This does not do any certificate verification!</description>

<properties><property kind="parameter" name="sock" required="1"/><property kind="parameter" name="keyfile"/><property kind="parameter" name="certfile"/></properties></element>

<element kind="function" name="fromfd">
<description>Build a socket object from an existing file descriptor (an integer as
returned by a file object's fileno() method). Address family,
socket type and protocol number are as for the socket() function
above. The file descriptor should refer to a socket, but this is not
checked --- subsequent operations on the object may fail if the file
descriptor is invalid. This function is rarely needed, but can be
used to get or set socket options on a socket passed to a program as
standard input or output (such as a server started by the inet
daemon). The socket is assumed to be in blocking mode.
Availability: .</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="family" required="1"/><property kind="parameter" name="type" required="1"/><property kind="parameter" name="proto"/></properties></element>

<element kind="function" name="ntohl">
<description>Convert 32-bit integers from network to host byte order. On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 4-byte swap operation.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="ntohs">
<description>Convert 16-bit integers from network to host byte order. On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 2-byte swap operation.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="htonl">
<description>Convert 32-bit integers from host to network byte order. On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 4-byte swap operation.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="htons">
<description>Convert 16-bit integers from host to network byte order. On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 2-byte swap operation.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="inet_aton">
<description>Convert an IPv4 address from dotted-quad string format (for example,
'123.45.67.89') to 32-bit packed binary format, as a string four
characters in length. This is useful when conversing with a program
that uses the standard C library and needs objects of type
struct in_addr, which is the C type for the 32-bit packed
binary this function returns.
If the IPv4 address string passed to this function is invalid,
socket.error will be raised. Note that exactly what is
valid depends on the underlying C implementation of
inet_aton().
inet_aton() does not support IPv6, and
getnameinfo() should be used instead for IPv4/v6 dual stack
support.</description>

<properties><property kind="parameter" name="ip_stringip_string" required="1"/></properties></element>

<element kind="function" name="inet_ntoa">
<description>Convert a 32-bit packed IPv4 address (a string four characters in
length) to its standard dotted-quad string representation (for
example, '123.45.67.89'). This is useful when conversing with a
program that uses the standard C library and needs objects of type
struct in_addr, which is the C type for the 32-bit packed
binary data this function takes as an argument.
If the string passed to this function is not exactly 4 bytes in
length, socket.error will be raised.
inet_ntoa() does not support IPv6, and
getnameinfo() should be used instead for IPv4/v6 dual stack
support.</description>

<properties><property kind="parameter" name="packed_ippacked_ip" required="1"/></properties></element>

<element kind="function" name="inet_pton">
<description>Convert an IP address from its family-specific string format to a packed,
binary format.
inet_pton() is useful when a library or network protocol calls for
an object of type struct in_addr (similar to inet_aton())
or struct in6_addr.
Supported values for address_family are currently
AF_INET and AF_INET6.
If the IP address string ip_string is invalid,
socket.error will be raised. Note that exactly what is valid
depends on both the value of address_family and the underlying
implementation of inet_pton().
Availability: (maybe not all platforms).
New in version 2.3</description>

<properties><property kind="parameter" name="address_family" required="1"/><property kind="parameter" name="ip_string ip_string" required="1"/></properties></element>

<element kind="function" name="inet_ntop">
<description>Convert a packed IP address (a string of some number of characters) to
its standard, family-specific string representation (for example,
'7.10.0.5' or '5aef:2b::8')
inet_ntop() is useful when a library or network protocol returns
an object of type struct in_addr (similar to inet_ntoa())
or struct in6_addr.
Supported values for address_family are currently
AF_INET and AF_INET6.
If the string packed_ip is not the correct length for the
specified address family, ValueError will be raised. A
socket.error is raised for errors from the call to
inet_ntop().
Availability: (maybe not all platforms).
New in version 2.3</description>

<properties><property kind="parameter" name="address_family" required="1"/><property kind="parameter" name="packed_ip packed_ip" required="1"/></properties></element>

<element kind="function" name="getdefaulttimeout">
<description>Return the default timeout in floating seconds for new socket objects.
A value of None indicates that new socket objects have no timeout.
When the socket module is first imported, the default is None.
New in version 2.3</description>

</element>

<element kind="function" name="setdefaulttimeout">
<description>Set the default timeout in floating seconds for new socket objects.
A value of None indicates that new socket objects have no timeout.
When the socket module is first imported, the default is None.
New in version 2.3</description>

<properties><property kind="parameter" name="timeouttimeout" required="1"/></properties></element>

<group name="Socket Objects">
<description>Socket objects have the following methods. Except for
makefile() these correspond to system calls
applicable to sockets.
</description>
<element kind="function" name="accept">
<description>Accept a connection.
The socket must be bound to an address and listening for connections.
The return value is a pair (conn, address)
where conn is a new socket object usable to send and
receive data on the connection, and address is the address bound
to the socket on the other end of the connection.</description>

</element>

<element kind="function" name="bind">
<description>Bind the socket to address. The socket must not already be bound.
(The format of address depends on the address family --- see
above.) This method has historically accepted a pair
of parameters for AF_INET addresses instead of only a
tuple. This was never intentional and is no longer be available in
Python 2.0.</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="close">
<description>Close the socket. All future operations on the socket object will fail.
The remote end will receive no more data (after queued data is flushed).
Sockets are automatically closed when they are garbage-collected.</description>

</element>

<element kind="function" name="connect">
<description>Connect to a remote socket at address.
(The format of address depends on the address family --- see
above.) This method has historically accepted a pair
of parameters for AF_INET addresses instead of only a
tuple. This was never intentional and is no longer available in
Python 2.0 and later.</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="connect_ex">
<description>Like connect(address), but return an error indicator
instead of raising an exception for errors returned by the C-level
connect() call (other problems, such as ``host not found,''
can still raise exceptions). The error indicator is 0 if the
operation succeeded, otherwise the value of the errno
variable. This is useful to support, for example, asynchronous connects.
This method has historically accepted a pair of
parameters for AF_INET addresses instead of only a tuple.
This was never intentional and is no longer be available in Python
2.0 and later.</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="fileno">
<description>Return the socket's file descriptor (a small integer). This is useful
with select.select().
Under Windows the small integer returned by this method cannot be used where
a file descriptor can be used (such as os.fdopen()). does
not have this limitation.</description>

</element>

<element kind="function" name="getpeername">
<description>Return the remote address to which the socket is connected. This is
useful to find out the port number of a remote IPv4/v6 socket, for instance.
(The format of the address returned depends on the address family ---
see above.) On some systems this function is not supported.</description>

</element>

<element kind="function" name="getsockname">
<description>Return the socket's own address. This is useful to find out the port
number of an IPv4/v6 socket, for instance.
(The format of the address returned depends on the address family ---
see above.)</description>

</element>

<element kind="function" name="getsockopt">
<description>Return the value of the given socket option (see the man page
getsockopt{2}). The needed symbolic constants
(SO_* etc.) are defined in this module. If buflen
is absent, an integer option is assumed and its integer value
is returned by the function. If buflen is present, it specifies
the maximum length of the buffer used to receive the option in, and
this buffer is returned as a string. It is up to the caller to decode
the contents of the buffer (see the optional built-in module
struct for a way to decode C structures encoded as strings).</description>

<properties><property kind="parameter" name="level" required="1"/><property kind="parameter" name="optname" required="1"/><property kind="parameter" name="buflen"/></properties></element>

<element kind="function" name="listen">
<description>Listen for connections made to the socket. The backlog argument
specifies the maximum number of queued connections and should be at
least 1; the maximum value is system-dependent (usually 5).</description>

<properties><property kind="parameter" name="backlogbacklog" required="1"/></properties></element>

<element kind="function" name="makefile">
<description>Return a file object associated with the socket. (File objects
are described in bltin-file-objects, ``File Objects.'')
The file object references a dup()ped version of the
socket file descriptor, so the file object and socket object may be
closed or garbage-collected independently.
The socket should be in blocking mode.
</description>

<properties><property kind="parameter" name="mode" required="1"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="recv">
<description>Receive data from the socket. The return value is a string representing
the data received. The maximum amount of data to be received
at once is specified by bufsize. See the manual page
recv{2} for the meaning of the optional argument
flags; it defaults to zero.</description>

<properties><property kind="parameter" name="bufsize" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="recvfrom">
<description>Receive data from the socket. The return value is a pair
(string, address) where string is a string
representing the data received and address is the address of the
socket sending the data. The optional flags argument has the
same meaning as for recv() above.
(The format of address depends on the address family --- see above.)</description>

<properties><property kind="parameter" name="bufsize" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="send">
<description>Send data to the socket. The socket must be connected to a remote
socket. The optional flags argument has the same meaning as for
recv() above. Returns the number of bytes sent.
Applications are responsible for checking that all data has been sent;
if only some of the data was transmitted, the application needs to
attempt delivery of the remaining data.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="sendall">
<description>Send data to the socket. The socket must be connected to a remote
socket. The optional flags argument has the same meaning as for
recv() above. Unlike send(), this method continues
to send data from string until either all data has been sent or
an error occurs. None is returned on success. On error, an
exception is raised, and there is no way to determine how much data,
if any, was successfully sent.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="flags"/></properties></element>

<element kind="function" name="sendto">
<description>Send data to the socket. The socket should not be connected to a
remote socket, since the destination socket is specified by
address. The optional flags argument has the same
meaning as for recv() above. Return the number of bytes sent.
(The format of address depends on the address family --- see above.)</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="flags"/><property kind="parameter" name="address address"/></properties></element>

<element kind="function" name="setblocking">
<description>Set blocking or non-blocking mode of the socket: if flag is 0,
the socket is set to non-blocking, else to blocking mode. Initially
all sockets are in blocking mode. In non-blocking mode, if a
recv() call doesn't find any data, or if a
send() call can't immediately dispose of the data, a
error exception is raised; in blocking mode, the calls
block until they can proceed.
s.setblocking(0) is equivalent to s.settimeout(0);
s.setblocking(1) is equivalent to s.settimeout(None).</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="settimeout">
<description>Set a timeout on blocking socket operations. The value argument
can be a nonnegative float expressing seconds, or None.
If a float is
given, subsequent socket operations will raise an timeout
exception if the timeout period value has elapsed before the
operation has completed. Setting a timeout of None disables
timeouts on socket operations.
s.settimeout(0.0) is equivalent to s.setblocking(0);
s.settimeout(None) is equivalent to s.setblocking(1).
New in version 2.3</description>

<properties><property kind="parameter" name="valuevalue" required="1"/></properties></element>

<element kind="function" name="gettimeout">
<description>Returns the timeout in floating seconds associated with socket
operations, or None if no timeout is set. This reflects
the last call to setblocking() or settimeout().
New in version 2.3</description>

</element>

<element kind="function" name="setsockopt">
<description>Set the value of the given socket option (see the manual page
setsockopt{2}). The needed symbolic constants are defined in
the socket module (SO_* etc.). The value can be an
integer or a string representing a buffer. In the latter case it is
up to the caller to ensure that the string contains the proper bits
(see the optional built-in module
structstruct for a way to encode C
structures as strings).</description>

<properties><property kind="parameter" name="level" required="1"/><property kind="parameter" name="optname" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="shutdown">
<description>Shut down one or both halves of the connection. If how is
SHUT_RD, further receives are disallowed. If how is SHUT_WR,
further sends are disallowed. If how is SHUT_RDWR, further sends
and receives are disallowed.</description>

<properties><property kind="parameter" name="howhow" required="1"/></properties></element>

</group>
<group name="SSL Objects">
<description>SSL objects have the following methods.
</description>
<element kind="function" name="write">
<description>Writes the string s to the on the object's SSL connection.
The return value is the number of bytes written.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="read">
<description>If n is provided, read n bytes from the SSL connection, otherwise
read until EOF. The return value is a string of the bytes read.</description>

<properties><property kind="parameter" name="n" required="1"/></properties></element>

</group>
<group name="Example">
</group>
</group>
<group name="select --- Waiting for I/O completion">
<description>Wait for I/O completion on multiple streams.
This module provides access to the select()
and poll() functions
available in most operating systems. Note that on Windows, it only
works for sockets; on other operating systems, it also works for other
file types (in particular, on , it works on pipes). It cannot
be used on regular files to determine whether a file has grown since
it was last read.
The module defines the following:
{error}
The exception raised when an error occurs. The accompanying value is
a pair containing the numeric error code from errno and the
corresponding string, as would be printed by the function
perror().
</description>
<element kind="function" name="poll">
<description>(Not supported by all operating systems.) Returns a polling object,
which supports registering and unregistering file descriptors, and
then polling them for I/O events;
see section~poll-objects below for the methods supported by
polling objects.</description>

</element>

<element kind="function" name="select">
<description>This is a straightforward interface to the select()
system call. The first three arguments are sequences of `waitable
objects': either integers representing file descriptors or
objects with a parameterless method named fileno() returning
such an integer. The three sequences of waitable objects are for input,
output and `exceptional conditions', respectively. Empty sequences are
allowed, but acceptance of three empty sequences is platform-dependent.
(It is known to work on but not on Windows.) The optional
timeout argument specifies a time-out as a floating point number
in seconds. When the timeout argument is omitted the function
blocks until at least one file descriptor is ready. A time-out value
of zero specifies a poll and never blocks.
The return value is a triple of lists of objects that are ready:
subsets of the first three arguments. When the time-out is reached
without a file descriptor becoming ready, three empty lists are
returned.
Among the acceptable object types in the sequences are Python file
objects (e.g. sys.stdin, or objects returned by
open() or os.popen()), socket objects
returned by socket.socket().%
(in module socket){socket()}
(in module os){popen()}
You may also define a wrapper class yourself, as long as it has
an appropriate fileno() method (that really returns a file
descriptor, not just a random integer).
File objects on Windows are not acceptable, but sockets
are.</description>

<properties><property kind="parameter" name="iwtd" required="1"/><property kind="parameter" name="owtd" required="1"/><property kind="parameter" name="ewtd" required="1"/><property kind="parameter" name="timeout"/></properties></element>

<group name="Polling Objects">
<description>The poll() system call, supported on most systems,
provides better scalability for network servers that service many,
many clients at the same time.
poll() scales better because the system call only
requires listing the file descriptors of interest, while select()
builds a bitmap, turns on bits for the fds of interest, and then
afterward the whole bitmap has to be linearly scanned again.
select() is O(highest file descriptor), while
poll() is O(number of file descriptors).
</description>
<element kind="function" name="register">
<description>Register a file descriptor with the polling object. Future calls to
the poll() method will then check whether the file descriptor
has any pending I/O events. fd can be either an integer, or an
object with a fileno() method that returns an integer. File
objects implement
fileno(), so they can also be used as the argument.
eventmask is an optional bitmask describing the type of events you
want to check for, and can be a combination of the constants
POLLIN, POLLPRI, and POLLOUT,
described in the table below. If not specified, the default value
used will check for all 3 types of events.
{l|l}{constant}{Constant}{Meaning}
POLLIN{There is data to read}
POLLPRI{There is urgent data to read}
POLLOUT{Ready for output: writing will not block}
POLLERR{Error condition of some sort}
POLLHUP{Hung up}
POLLNVAL{Invalid request: descriptor not open}
Registering a file descriptor that's already registered is not an
error, and has the same effect as registering the descriptor exactly
once.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="eventmask"/></properties></element>

<element kind="function" name="unregister">
<description>Remove a file descriptor being tracked by a polling object. Just like
the register() method, fd can be an integer or an
object with a fileno() method that returns an integer.
Attempting to remove a file descriptor that was never registered
causes a KeyError exception to be raised.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="poll">
<description>Polls the set of registered file descriptors, and returns a
possibly-empty list containing (fd, event) 2-tuples
for the descriptors that have events or errors to report.
fd is the file descriptor, and event is a bitmask
with bits set for the reported events for that descriptor
--- POLLIN for waiting input,
POLLOUT to indicate that the descriptor can be written to, and
so forth.
An empty list indicates that the call timed out and no file
descriptors had any events to report.
If timeout is given, it specifies the length of time in
milliseconds which the system will wait for events before returning.
If timeout is omitted, negative, or None, the call will
block until there is an event for this poll object.</description>

<properties><property kind="parameter" name="timeout" required="1"/></properties></element>

</group>
</group>
<group name="thread --- Multiple threads of control">
<description>Create multiple threads of control within one interpreter.
This module provides low-level primitives for working with multiple
threads (a.k.a. light-weight processes or tasks) --- multiple
threads of control sharing their global data space. For
synchronization, simple locks (a.k.a. mutexes or binary
semaphores) are provided.
</description>
<element kind="function" name="start_new_thread">
<description>Start a new thread and return its identifier. The thread executes the function
function with the argument list args (which must be a tuple). The
optional kwargs argument specifies a dictionary of keyword arguments.
When the function returns, the thread silently exits. When the function
terminates with an unhandled exception, a stack trace is printed and
then the thread exits (but other threads continue to run).</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="args" required="1"/><property kind="parameter" name="kwargs"/></properties></element>

<element kind="function" name="interrupt_main">
<description>Raise a KeyboardInterrupt in the main thread. A subthread can use this
function to interrupt the main thread.
New in version 2.3</description>

</element>

<element kind="function" name="exit">
<description>Raise the SystemExit exception. When not caught, this
will cause the thread to exit silently.</description>

</element>

<element kind="function" name="exit_prog">
<description>%Exit all threads and report the value of the integer argument
%status as the exit status of the entire program.
%Caveat: code in pending finally clauses, in this thread
%or in other threads, is not executed.
%</description>

<properties><property kind="parameter" name="statusstatus" required="1"/></properties></element>

<element kind="function" name="allocate_lock">
<description>Return a new lock object. Methods of locks are described below. The
lock is initially unlocked.</description>

</element>

<element kind="function" name="get_ident">
<description>Return the `thread identifier' of the current thread. This is a
nonzero integer. Its value has no direct meaning; it is intended as a
magic cookie to be used e.g. to index a dictionary of thread-specific
data. Thread identifiers may be recycled when a thread exits and
another thread is created.</description>

</element>

<element kind="function" name="acquire">
<description>Without the optional argument, this method acquires the lock
unconditionally, if necessary waiting until it is released by another
thread (only one thread at a time can acquire a lock --- that's their
reason for existence), and returns None. If the integer
waitflag argument is present, the action depends on its
value: if it is zero, the lock is only acquired if it can be acquired
immediately without waiting, while if it is nonzero, the lock is
acquired unconditionally as before. If an argument is present, the
return value is True if the lock is acquired successfully,
False if not.</description>

<properties><property kind="parameter" name="waitflag" required="1"/></properties></element>

<element kind="function" name="release">
<description>Releases the lock. The lock must have been acquired earlier, but not
necessarily by the same thread.</description>

</element>

<element kind="function" name="locked">
<description>Return the status of the lock: True if it has been acquired by
some thread, False if not.</description>

</element>

</group>
<group name="threading --- Higher-level threading interface">
<description>Higher-level threading interface.
This module constructs higher-level threading interfaces on top of the lower level thread module.
The dummy_threading module is provided for
situations where threading cannot be used because
thread is missing.
This module defines the following functions and objects:
</description>
<element kind="function" name="activeCount">
<description>Return the number of currently active Thread objects.
The returned count is equal to the length of the list returned by
enumerate().
A function that returns the number of currently active threads.</description>

</element>

<element kind="function" name="Condition">
<description>A factory function that returns a new condition variable object.
A condition variable allows one or more threads to wait until they
are notified by another thread.</description>

</element>

<element kind="function" name="currentThread">
<description>Return the current Thread object, corresponding to the
caller's thread of control. If the caller's thread of control was not
created through the
threading module, a dummy thread object with limited functionality
is returned.</description>

</element>

<element kind="function" name="enumerate">
<description>Return a list of all currently active Thread objects.
The list includes daemonic threads, dummy thread objects created
by currentThread(), and the main thread. It excludes terminated
threads and threads that have not yet been started.</description>

</element>

<element kind="function" name="Event">
<description>A factory function that returns a new event object. An event manages
a flag that can be set to true with the set() method and
reset to false with the clear() method. The wait()
method blocks until the flag is true.</description>

</element>

<element kind="function" name="Lock">
<description>A factory function that returns a new primitive lock object. Once
a thread has acquired it, subsequent attempts to acquire it block,
until it is released; any thread may release it.</description>

</element>

<element kind="function" name="RLock">
<description>A factory function that returns a new reentrant lock object.
A reentrant lock must be released by the thread that acquired it.
Once a thread has acquired a reentrant lock, the same thread may
acquire it again without blocking; the thread must release it once
for each time it has acquired it.</description>

</element>

<element kind="function" name="Semaphore">
<description>A factory function that returns a new semaphore object. A
semaphore manages a counter representing the number of release()
calls minus the number of acquire() calls, plus an initial value.
The acquire() method blocks if necessary until it can return
without making the counter negative. If not given, value defaults to
1.</description>

<properties><property kind="parameter" name="value" required="1"/></properties></element>

<element kind="function" name="BoundedSemaphore">
<description>A factory function that returns a new bounded semaphore object. A bounded
semaphore checks to make sure its current value doesn't exceed its initial
value. If it does, ValueError is raised. In most situations
semaphores are used to guard resources with limited capacity. If the
semaphore is released too many times it's a sign of a bug. If not given,
value defaults to 1.</description>

<properties><property kind="parameter" name="value" required="1"/></properties></element>

<element kind="function" name="settrace">
<description>Set a trace function</description>

<properties><property kind="parameter" name="funcfunc" required="1"/></properties></element>

<element kind="function" name="setprofile">
<description>Set a profile function</description>

<properties><property kind="parameter" name="funcfunc" required="1"/></properties></element>

<group name="Lock Objects">
<description>A primitive lock is a synchronization primitive that is not owned
by a particular thread when locked. In Python, it is currently
the lowest level synchronization primitive available, implemented
directly by the thread extension module.
A primitive lock is in one of two states, ``locked'' or ``unlocked''.
It is created in the unlocked state. It has two basic methods,
acquire() and release(). When the state is
unlocked, acquire() changes the state to locked and returns
immediately. When the state is locked, acquire() blocks
until a call to release() in another thread changes it to
unlocked, then the acquire() call resets it to locked and
returns. The release() method should only be called in the
locked state; it changes the state to unlocked and returns
immediately. When more than one thread is blocked in
acquire() waiting for the state to turn to unlocked, only one
thread proceeds when a release() call resets the state to
unlocked; which one of the waiting threads proceeds is not defined,
and may vary across implementations.
All methods are executed atomically.
</description>
<element kind="function" name="acquire">
<description>Acquire a lock, blocking or non-blocking.
When invoked without arguments, block until the lock is
unlocked, then set it to locked, and return. There is no
return value in this case.
When invoked with the blocking argument set to true, do the
same thing as when called without arguments, and return true.
When invoked with the blocking argument set to false, do not
block. If a call without an argument would block, return false
immediately; otherwise, do the same thing as when called
without arguments, and return true.</description>

<properties><property default=" 1" kind="parameter" name="blocking" required="1"/></properties></element>

<element kind="function" name="release">
<description>Release a lock.
When the lock is locked, reset it to unlocked, and return. If
any other threads are blocked waiting for the lock to become
unlocked, allow exactly one of them to proceed.
Do not call this method when the lock is unlocked.
There is no return value.</description>

</element>

</group>
<group name="RLock Objects">
<description>A reentrant lock is a synchronization primitive that may be
acquired multiple times by the same thread. Internally, it uses
the concepts of ``owning thread'' and ``recursion level'' in
addition to the locked/unlocked state used by primitive locks. In
the locked state, some thread owns the lock; in the unlocked
state, no thread owns it.
To lock the lock, a thread calls its acquire() method; this
returns once the thread owns the lock. To unlock the lock, a
thread calls its release() method.
acquire()/release() call pairs may be nested; only
the final release() (the release() of the outermost
pair) resets the lock to unlocked and allows another thread blocked in
acquire() to proceed.
</description>
<element kind="function" name="acquire">
<description>Acquire a lock, blocking or non-blocking.
When invoked without arguments: if this thread already owns
the lock, increment the recursion level by one, and return
immediately. Otherwise, if another thread owns the lock,
block until the lock is unlocked. Once the lock is unlocked
(not owned by any thread), then grab ownership, set the
recursion level to one, and return. If more than one thread
is blocked waiting until the lock is unlocked, only one at a
time will be able to grab ownership of the lock. There is no
return value in this case.
When invoked with the blocking argument set to true, do the
same thing as when called without arguments, and return true.
When invoked with the blocking argument set to false, do not
block. If a call without an argument would block, return false
immediately; otherwise, do the same thing as when called
without arguments, and return true.</description>

<properties><property default=" 1" kind="parameter" name="blocking" required="1"/></properties></element>

<element kind="function" name="release">
<description>Release a lock, decrementing the recursion level. If after the
decrement it is zero, reset the lock to unlocked (not owned by any
thread), and if any other threads are blocked waiting for the lock to
become unlocked, allow exactly one of them to proceed. If after the
decrement the recursion level is still nonzero, the lock remains
locked and owned by the calling thread.
Only call this method when the calling thread owns the lock.
Do not call this method when the lock is unlocked.
There is no return value.</description>

</element>

</group>
<group name="Condition Objects">
<description>A condition variable is always associated with some kind of lock;
this can be passed in or one will be created by default. (Passing
one in is useful when several condition variables must share the
same lock.)
A condition variable has acquire() and release()
methods that call the corresponding methods of the associated lock.
It also has a wait() method, and notify() and
notifyAll() methods. These three must only be called when
the calling thread has acquired the lock.
The wait() method releases the lock, and then blocks until it
is awakened by a notify() or notifyAll() call for
the same condition variable in another thread. Once awakened, it
re-acquires the lock and returns. It is also possible to specify a
timeout.
The notify() method wakes up one of the threads waiting for
the condition variable, if any are waiting. The notifyAll()
method wakes up all threads waiting for the condition variable.
Note: the notify() and notifyAll() methods don't
release the lock; this means that the thread or threads awakened will
not return from their wait() call immediately, but only when
the thread that called notify() or notifyAll()
finally relinquishes ownership of the lock.
Tip: the typical programming style using condition variables uses the
lock to synchronize access to some shared state; threads that are
interested in a particular change of state call wait()
repeatedly until they see the desired state, while threads that modify
the state call notify() or notifyAll() when they
change the state in such a way that it could possibly be a desired
state for one of the waiters. For example, the following code is a
generic producer-consumer situation with unlimited buffer capacity:
# Consume one item
cv.acquire()
while not an_item_is_available():
cv.wait()
get_an_available_item()
cv.release()
# Produce one item
cv.acquire()
make_an_item_available()
cv.notify()
cv.release()
To choose between notify() and notifyAll(), consider
whether one state change can be interesting for only one or several
waiting threads. E.g. in a typical producer-consumer situation,
adding one item to the buffer only needs to wake up one consumer
thread.
</description>
<element kind="function" name="Condition">
<description>If the lock argument is given and not None, it must be a
Lock or RLock object, and it is used as the underlying
lock. Otherwise, a new RLock object is created and used as
the underlying lock.</description>

<properties><property kind="parameter" name="lock" required="1"/></properties></element>

<element kind="function" name="acquire">
<description>Acquire the underlying lock.
This method calls the corresponding method on the underlying
lock; the return value is whatever that method returns.</description>

<properties><property kind="parameter" name="*args*args" required="1"/></properties></element>

<element kind="function" name="release">
<description>Release the underlying lock.
This method calls the corresponding method on the underlying
lock; there is no return value.</description>

</element>

<element kind="function" name="wait">
<description>Wait until notified or until a timeout occurs.
This must only be called when the calling thread has acquired the
lock.
This method releases the underlying lock, and then blocks until it is
awakened by a notify() or notifyAll() call for the
same condition variable in another thread, or until the optional
timeout occurs. Once awakened or timed out, it re-acquires the lock
and returns.
When the timeout argument is present and not None, it
should be a floating point number specifying a timeout for the
operation in seconds (or fractions thereof).
When the underlying lock is an RLock, it is not released using
its release() method, since this may not actually unlock the
lock when it was acquired multiple times recursively. Instead, an
internal interface of the RLock class is used, which really
unlocks it even when it has been recursively acquired several times.
Another internal interface is then used to restore the recursion level
when the lock is reacquired.</description>

<properties><property kind="parameter" name="timeout" required="1"/></properties></element>

<element kind="function" name="notify">
<description>Wake up a thread waiting on this condition, if any.
This must only be called when the calling thread has acquired the
lock.
This method wakes up one of the threads waiting for the condition
variable, if any are waiting; it is a no-op if no threads are waiting.
The current implementation wakes up exactly one thread, if any are
waiting. However, it's not safe to rely on this behavior. A future,
optimized implementation may occasionally wake up more than one
thread.
Note: the awakened thread does not actually return from its
wait() call until it can reacquire the lock. Since
notify() does not release the lock, its caller should.</description>

</element>

<element kind="function" name="notifyAll">
<description>Wake up all threads waiting on this condition. This method acts like
notify(), but wakes up all waiting threads instead of one.</description>

</element>

</group>
<group name="Semaphore Objects">
<description>This is one of the oldest synchronization primitives in the history of
computer science, invented by the early Dutch computer scientist
Edsger W. Dijkstra (he used P() and V() instead of
acquire() and release()).
A semaphore manages an internal counter which is decremented by each
acquire() call and incremented by each release()
call. The counter can never go below zero; when acquire()
finds that it is zero, it blocks, waiting until some other thread
calls release().
</description>
<element kind="function" name="Semaphore">
<description>The optional argument gives the initial value for the internal
counter; it defaults to 1.</description>

<properties><property kind="parameter" name="value" required="1"/></properties></element>

<element kind="function" name="acquire">
<description>Acquire a semaphore.
When invoked without arguments: if the internal counter is larger than
zero on entry, decrement it by one and return immediately. If it is
zero on entry, block, waiting until some other thread has called
release() to make it larger than zero. This is done with
proper interlocking so that if multiple acquire() calls are
blocked, release() will wake exactly one of them up. The
implementation may pick one at random, so the order in which blocked
threads are awakened should not be relied on. There is no return
value in this case.
When invoked with blocking set to true, do the same thing as
when called without arguments, and return true.
When invoked with blocking set to false, do not block. If a
call without an argument would block, return false immediately;
otherwise, do the same thing as when called without arguments, and
return true.</description>

<properties><property kind="parameter" name="blocking" required="1"/></properties></element>

<element kind="function" name="release">
<description>Release a semaphore,
incrementing the internal counter by one. When it was zero on
entry and another thread is waiting for it to become larger
than zero again, wake up that thread.</description>

</element>

</group>
<group name="Event Objects">
<description>This is one of the simplest mechanisms for communication between
threads: one thread signals an event and other threads wait for it.
An event object manages an internal flag that can be set to true with
the set() method and reset to false with the clear()
method. The wait() method blocks until the flag is true.
</description>
<element kind="function" name="Event">
<description>The internal flag is initially false.</description>

</element>

<element kind="function" name="isSet">
<description>Return true if and only if the internal flag is true.</description>

</element>

<element kind="function" name="set">
<description>Set the internal flag to true.
All threads waiting for it to become true are awakened.
Threads that call wait() once the flag is true will not block
at all.</description>

</element>

<element kind="function" name="clear">
<description>Reset the internal flag to false.
Subsequently, threads calling wait() will block until
set() is called to set the internal flag to true again.</description>

</element>

<element kind="function" name="wait">
<description>Block until the internal flag is true.
If the internal flag is true on entry, return immediately. Otherwise,
block until another thread calls set() to set the flag to
true, or until the optional timeout occurs.
When the timeout argument is present and not None, it should be a
floating point number specifying a timeout for the operation in
seconds (or fractions thereof).</description>

<properties><property kind="parameter" name="timeout" required="1"/></properties></element>

</group>
<group name="Thread Objects">
<description>This class represents an activity that is run in a separate thread
of control. There are two ways to specify the activity: by
passing a callable object to the constructor, or by overriding the
run() method in a subclass. No other methods (except for the
constructor) should be overridden in a subclass. In other words, only override the __init__() and run()
methods of this class.
Once a thread object is created, its activity must be started by
calling the thread's start() method. This invokes the
run() method in a separate thread of control.
Once the thread's activity is started, the thread is considered
'alive' and 'active' (these concepts are almost, but not quite
exactly, the same; their definition is intentionally somewhat
vague). It stops being alive and active when its run()
method terminates -- either normally, or by raising an unhandled
exception. The isAlive() method tests whether the thread is
alive.
Other threads can call a thread's join() method. This blocks
the calling thread until the thread whose join() method is
called is terminated.
A thread has a name. The name can be passed to the constructor,
set with the setName() method, and retrieved with the
getName() method.
A thread can be flagged as a ``daemon thread''. The significance
of this flag is that the entire Python program exits when only
daemon threads are left. The initial value is inherited from the
creating thread. The flag can be set with the setDaemon()
method and retrieved with the isDaemon() method.
There is a ``main thread'' object; this corresponds to the
initial thread of control in the Python program. It is not a
daemon thread.
There is the possibility that ``dummy thread objects'' are
created. These are thread objects corresponding to ``alien
threads''. These are threads of control started outside the
threading module, such as directly from C code. Dummy thread objects
have limited functionality; they are always considered alive,
active, and daemonic, and cannot be join()ed. They are never deleted, since it is impossible to detect the termination of alien
threads.
</description>
<element kind="function" name="Thread">
<description>This constructor should always be called with keyword
arguments. Arguments are:
group should be None; reserved for future extension when
a ThreadGroup class is implemented.
target is the callable object to be invoked by the
run() method. Defaults to None, meaning nothing is
called.
name is the thread name. By default, a unique name is
constructed of the form ``Thread-N'' where N is a small
decimal number.
args is the argument tuple for the target invocation. Defaults
to ().
kwargs is a dictionary of keyword arguments for the target
invocation. Defaults to {}.
If the subclass overrides the constructor, it must make sure
to invoke the base class constructor (Thread.__init__())
before doing anything else to the thread.</description>

<properties><property default="None" kind="parameter" name="group" required="1"/><property default="None" kind="parameter" name="target" required="1"/><property default="None" kind="parameter" name="name" required="1"/><property default="()" kind="parameter" name="args" required="1"/><property kind="parameter" name="kwargs" required="1"/></properties></element>

<element kind="function" name="start">
<description>Start the thread's activity.
This must be called at most once per thread object. It
arranges for the object's run() method to be invoked in a
separate thread of control.</description>

</element>

<element kind="function" name="run">
<description>Method representing the thread's activity.
You may override this method in a subclass. The standard
run() method invokes the callable object passed to the
object's constructor as the target argument, if any, with
sequential and keyword arguments taken from the args and
kwargs arguments, respectively.</description>

</element>

<element kind="function" name="join">
<description>Wait until the thread terminates.
This blocks the calling thread until the thread whose join()
method is called terminates -- either normally or through an
unhandled exception -- or until the optional timeout occurs.
When the timeout argument is present and not None, it
should be a floating point number specifying a timeout for the
operation in seconds (or fractions thereof).
A thread can be join()ed many times.
A thread cannot join itself because this would cause a
deadlock.
It is an error to attempt to join() a thread before it has
been started.</description>

<properties><property kind="parameter" name="timeout" required="1"/></properties></element>

<element kind="function" name="getName">
<description>Return the thread's name.</description>

</element>

<element kind="function" name="setName">
<description>Set the thread's name.
The name is a string used for identification purposes only.
It has no semantics. Multiple threads may be given the same
name. The initial name is set by the constructor.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="isAlive">
<description>Return whether the thread is alive.
Roughly, a thread is alive from the moment the start() method
returns until its run() method terminates.</description>

</element>

<element kind="function" name="isDaemon">
<description>Return the thread's daemon flag.</description>

</element>

<element kind="function" name="setDaemon">
<description>Set the thread's daemon flag to the Boolean value daemonic.
This must be called before start() is called.
The initial value is inherited from the creating thread.
The entire Python program exits when no active non-daemon
threads are left.</description>

<properties><property kind="parameter" name="daemonicdaemonic" required="1"/></properties></element>

</group>
<group name="Timer Objects">
<description>This class represents an action that should be run only after a
certain amount of time has passed --- a timer. Timer is a
subclass of Thread and as such also functions as an example of
creating custom threads.
Timers are started, as with threads, by calling their start()
method. The timer can be stopped (before its action has begun) by
calling the cancel() method. The interval the timer will
wait before executing its action may not be exactly the same as the
interval specified by the user.
For example:
def hello():
print &quot;hello, world&quot;
t = Timer(30.0, hello)
t.start() # after 30 seconds, &quot;hello, world&quot; will be printed
</description>
<element kind="function" name="Timer">
<description>Create a timer that will run function with arguments args and keyword arguments kwargs, after interval seconds have passed.</description>

<properties><property kind="parameter" name="interval" required="1"/><property kind="parameter" name="function" required="1"/><property default="[]" kind="parameter" name="args" required="1"/><property kind="parameter" name="kwargs" required="1"/></properties></element>

<element kind="function" name="cancel">
<description>Stop the timer, and cancel the execution of the timer's action. This
will only work if the timer is still in its waiting stage.</description>

</element>

</group>
</group>
<group name="dummy_thread --- Drop-in replacement for the thread module">
</group>
<group name="dummy_threading --- Drop-in replacement for the threading module">
</group>
<group name="Queue --- A synchronized queue class">
<description>A synchronized queue class.
The Queue module implements a multi-producer, multi-consumer
FIFO queue. It is especially useful in threads programming when
information must be exchanged safely between multiple threads. The
Queue class in this module implements all the required locking
semantics. It depends on the availability of thread support in
Python.
bisect{PriorityQueue example using the Queue class}
The Queue module defines the following class and exception:
</description>
<element kind="function" name="Queue">
<description>Constructor for the class. maxsize is an integer that sets the
upperbound limit on the number of items that can be placed in the
queue. Insertion will block once this size has been reached, until
queue items are consumed. If maxsize is less than or equal to
zero, the queue size is infinite.</description>

<properties><property kind="parameter" name="maxsizemaxsize" required="1"/></properties></element>

<group name="Queue Objects">
<element kind="function" name="qsize">
<description>Return the approximate size of the queue. Because of multithreading
semantics, this number is not reliable.</description>

</element>

<element kind="function" name="empty">
<description>Return True if the queue is empty, False otherwise.
Becauseof multithreading semantics, this is not reliable.</description>

</element>

<element kind="function" name="full">
<description>Return True if the queue is full, False otherwise.
Because of multithreading semantics, this is not reliable.</description>

</element>

<element kind="function" name="put">
<description>Put item into the queue. If optional args block is true
and timeout is None (the default), block if necessary until a
free slot is available. If timeout is a positive number, it
blocks at most timeout seconds and raises the Full
exception if no free slot was available within that time.
Otherwise (block is false), put an item on the queue if a free
slot is immediately available, else raise the Full
exception (timeout is ignored in that case).
New in version 2.3</description>

<properties><property kind="parameter" name="item" required="1"/><property kind="parameter" name="block"/><property kind="parameter" name="timeout"/></properties></element>

<element kind="function" name="put_nowait">
<description>Equivalent to put(item, False).</description>

<properties><property kind="parameter" name="itemitem" required="1"/></properties></element>

<element kind="function" name="get">
<description>Remove and return an item from the queue. If optional args
block is true and timeout is None (the default),
block if necessary until an item is available. If timeout is
a positive number, it blocks at most timeout seconds and raises
the Empty exception if no item was available within that
time. Otherwise (block is false), return an item if one is
immediately available, else raise the Empty exception
(timeout is ignored in that case).
New in version 2.3</description>

<properties><property kind="parameter" name="block" required="1"/><property kind="parameter" name="timeout"/></properties></element>

<element kind="function" name="get_nowait">
<description>Equivalent to get(False).</description>

</element>

</group>
</group>
<group name="mmap --- Memory-mapped file support">
<description>Interface to memory-mapped files for Windows.
Memory-mapped file objects behave like both strings and like
file objects. Unlike normal string objects, however, these are
mutable. You can use mmap objects in most places where strings
are expected; for example, you can use the re module to
search through a memory-mapped file. Since they're mutable, you can
change a single character by doing obj[index] = 'a', or
change a substring by assigning to a slice:
obj[i1:i2] = '...'. You can also read and write
data starting at the current file position, and seek()
through the file to different positions.
A memory-mapped file is created by the mmap() function,
which is different on and on Windows. In either case you must
provide a file descriptor for a file opened for update.
If you wish to map an existing Python file object, use its
fileno() method to obtain the correct value for the
fileno parameter. Otherwise, you can open the file using the
os.open() function, which returns a file descriptor
directly (the file still needs to be closed when done).
For both the and Windows versions of the function,
access may be specified as an optional keyword parameter.
access accepts one of three values: ACCESS_READ,
ACCESS_WRITE, or ACCESS_COPY to specify
readonly, write-through or copy-on-write memory respectively.
access can be used on both and Windows. If
access is not specified, Windows mmap returns a write-through
mapping. The initial memory values for all three access types are
taken from the specified file. Assignment to an
ACCESS_READ memory map raises a TypeError
exception. Assignment to an ACCESS_WRITE memory map
affects both memory and the underlying file. Assigment to an
ACCESS_COPY memory map affects memory but does not update
the underlying file.
</description>
<element kind="function" name="mmap">
<description>(Windows version) Maps length bytes from the file
specified by the file handle fileno, and returns a mmap
object. If length is 0, the maximum length of the map
will be the current size of the file when mmap() is
called.
tagname, if specified and not None, is a string giving
a tag name for the mapping. Windows allows you to have many
different mappings against the same file. If you specify the name
of an existing tag, that tag is opened, otherwise a new tag of this
name is created. If this parameter is omitted or None, the
mapping is created without a name. Avoiding the use of the tag
parameter will assist in keeping your code portable between and Windows.</description>

<properties><property kind="parameter" name="fileno" required="1"/><property kind="parameter" name="length" required="1"/><property kind="parameter" name="tagname"/><property kind="parameter" name="access"/></properties></element>

<element kind="function" name="close">
<description>Close the file. Subsequent calls to other methods of the object
will result in an exception being raised.</description>

</element>

<element kind="function" name="find">
<description>Returns the lowest index in the object where the substring
string is found. Returns -1 on failure. start
is the index at which the search begins, and defaults to zero.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="start"/></properties></element>

<element kind="function" name="flush">
<description>Flushes changes made to the in-memory copy of a file back to disk.
Without use of this call there is no guarantee that changes are
written back before the object is destroyed. If offset and
size are specified, only changes to the given range of bytes
will be flushed to disk; otherwise, the whole extent of the mapping
is flushed.</description>

<properties><property kind="parameter" name="offset" required="1"/><property kind="parameter" name="size"/></properties></element>

<element kind="function" name="move">
<description>Copy the count bytes starting at offset src to the
destination index dest. If the mmap was created with
ACCESS_READ, then calls to move will throw a
TypeError exception.</description>

<properties><property kind="parameter" name="dest" required="1"/><property kind="parameter" name="src" required="1"/><property kind="parameter" name="count" required="1"/></properties></element>

<element kind="function" name="read">
<description>Return a string containing up to num bytes starting from the
current file position; the file position is updated to point after the
bytes that were returned.</description>

<properties><property kind="parameter" name="num" required="1"/></properties></element>

<element kind="function" name="read_byte">
<description>Returns a string of length 1 containing the character at the current
file position, and advances the file position by 1.</description>

</element>

<element kind="function" name="readline">
<description>Returns a single line, starting at the current file position and up to the next newline.</description>

</element>

<element kind="function" name="resize">
<description>If the mmap was created with ACCESS_READ or
ACCESS_COPY, resizing the map will throw a TypeError exception.</description>

<properties><property kind="parameter" name="newsize" required="1"/></properties></element>

<element kind="function" name="seek">
<description>Set the file's current position. whence argument is optional
and defaults to 0 (absolute file positioning); other values
are 1 (seek relative to the current position) and 2
(seek relative to the file's end).</description>

<properties><property kind="parameter" name="pos" required="1"/><property kind="parameter" name="whence"/></properties></element>

<element kind="function" name="size">
<description>Return the length of the file, which can be larger than the size of
the memory-mapped area.</description>

</element>

<element kind="function" name="tell">
<description>Returns the current position of the file pointer.</description>

</element>

<element kind="function" name="write">
<description>Write the bytes in string into memory at the current position
of the file pointer; the file position is updated to point after the
bytes that were written. If the mmap was created with
ACCESS_READ, then writing to it will throw a
TypeError exception.</description>

<properties><property kind="parameter" name="string" required="1"/></properties></element>

<element kind="function" name="write_byte">
<description>Write the single-character string byte into memory at the
current position of the file pointer; the file position is advanced
by 1.If the mmap was created with ACCESS_READ,
then writing to it will throw a TypeError exception.</description>

<properties><property kind="parameter" name="byte" required="1"/></properties></element>

</group>
<group name="anydbm --- Generic access to DBM-style databases">
<description>Generic interface to DBM-style database modules.
anydbm is a generic interface to variants of the DBM
database --- dbhashdbhash (requires
bsddbbsddb),
gdbmgdbm, or
dbmdbm. If none of these modules is
installed, the slow-but-simple implementation in module
dumbdbmdumbdbm will be used.
</description>
<element kind="function" name="open">
<description>Open the database file filename and return a corresponding object.
If the database file already exists, the whichdb module is used to determine its type and the appropriate module is used; if it
does not exist, the first module listed above that can be imported is
used.
The optional flag argument can be
'r' to open an existing database for reading only,
'w' to open an existing database for reading and writing,
'c' to create the database if it doesn't exist, or
'n', which will always create a new empty database. If not
specified, the default value is 'r'.
The optional mode argument is the 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).</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/></properties></element>

</group>
<group name="dbhash --- DBM-style interface to the BSD database library">
<description>Unix, Windows
DBM-style interface to the BSD database library.
The dbhash module provides a function to open databases using
the BSD db library. This module mirrors the interface of the
other Python database modules that provide access to DBM-style
databases. The bsddbbsddb module is required to use dbhash.
This module provides an exception and a function:
{error}
Exception raised on database errors other than
KeyError. It is a synonym for bsddb.error.
</description>
<element kind="function" name="open">
<description>Open a db database and return the database object. The
path argument is the name of the database file.
The flag argument can be
'r' (the default), 'w',
'c' (which creates the database if it doesn't exist), or
'n' (which always creates a new empty database).
For platforms on which the BSD db library supports locking,
an l can be appended to indicate that locking should be
used.
The optional mode parameter is used to indicate the permission bits that should be set if a new database must be
created; this will be masked by the current umask value for the
process.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/></properties></element>

<group name="Database Objects">
<description>The database objects returned by open() provide the methods common to all the DBM-style databases and mapping objects. The following
methods are available in addition to the standard methods.
</description>
<element kind="function" name="first">
<description>It's possible to loop over every key/value pair in the database using
this method and the next() method. The traversal is ordered by
the databases internal hash values, and won't be sorted by the key
values. This method returns the starting key.</description>

</element>

<element kind="function" name="last">
<description>Return the last key/value pair in a database traversal. This may be used to
begin a reverse-order traversal; see previous().</description>

</element>

<element kind="function" name="next">
<description>Returns the key next key/value pair in a database traversal. The
following code prints every key in the database db, without
having to create a list in memory that contains them all:
print db.first()
for i in xrange(1, len(db)):
print db.next()
</description>

</element>

<element kind="function" name="previous">
<description>Returns the previous key/value pair in a forward-traversal of the database.
In conjunction with last(), this may be used to implement
a reverse-order traversal.</description>

</element>

<element kind="function" name="sync">
<description>This method forces any unwritten data to be written to the disk.</description>

</element>

</group>
</group>
<group name="whichdb --- Guess which DBM module created a database">
<description>Guess which DBM-style module created a given database.
The single function in this module attempts to guess which of the
several simple database modules available--dbm,
gdbm, or dbhash--should be used to open a
given file.
</description>
<element kind="function" name="whichdb">
<description>Returns one of the following values: None if the file can't be
opened because it's unreadable or doesn't exist; the empty string
('') if the file's format can't be guessed; or a string
containing the required module name, such as 'dbm' or
'gdbm'.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

</group>
<group name="bsddb --- Interface to Berkeley DB library">
<description>Unix, Windows
Interface to Berkeley DB database library
The bsddb module provides an interface to the Berkeley DB
library. Users can create hash, btree or record based library files
using the appropriate open call. Bsddb objects behave generally like
dictionaries. Keys and values must be strings, however, so to use
other objects as keys or to store other kinds of objects the user must
serialize them somehow, typically using marshal.dumps or pickle.dumps.
Starting with Python 2.3 the bsddb module requires the
Berkeley DB library version 3.2 or later (it is known to work with 3.2
thru 4.2 at the time of this writing).
http://pybsddb.sourceforge.net/{Website with documentation
for the new python Berkeley DB interface that closely mirrors the sleepycat object oriented interface provided in Berkeley DB 3 and 4.}
http://www.sleepycat.com/{Sleepycat Software produces the
modern Berkeley DB library.}
The following is a description of the legacy bsddb interface
compatible with the old python bsddb module. For details about the more
modern Db and DbEnv object oriented interface see the above mentioned
pybsddb URL.
The bsddb module defines the following functions that create
objects that access the appropriate type of Berkeley DB file. The
first two arguments of each function are the same. For ease of
portability, only the first two arguments should be used in most
instances.
</description>
<element kind="function" name="hashopen">
<description>Open the hash format file named filename. Files never intended
to be preserved on disk may be created by passing None as the filename. The optional
flag identifies the mode used to open the file. It may be
r (read only, default), w (read-write) ,
c (read-write - create if necessary) or
n (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level
dbopen() function. Consult the Berkeley DB documentation
for their use and interpretation.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/><property kind="parameter" name="bsize"/><property kind="parameter" name="ffactor"/><property kind="parameter" name="nelem"/><property kind="parameter" name="cachesize"/><property kind="parameter" name="hash"/><property kind="parameter" name="lorder"/></properties></element>

<element kind="function" name="btopen">
<description>Open the btree format file named filename. Files never intended to be preserved on disk may be created by passing None as the filename. The optional
flag identifies the mode used to open the file. It may be
r (read only, default), w (read-write),
c (read-write - create if necessary) or
n (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level dbopen
function. Consult the Berkeley DB documentation for their use and
interpretation.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/><property kind="parameter" name="btflags"/><property kind="parameter" name="cachesize"/><property kind="parameter" name="maxkeypage"/><property kind="parameter" name="minkeypage"/><property kind="parameter" name="psize"/><property kind="parameter" name="lorder"/></properties></element>

<element kind="function" name="rnopen">
<description>Open a DB record format file named filename. Files never intended to be preserved on disk may be created by passing None as the filename. The optional
flag identifies the mode used to open the file. It may be
r (read only, default), w (read-write),
c (read-write - create if necessary) or
n (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level dbopen
function. Consult the Berkeley DB documentation for their use and
interpretation.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/><property kind="parameter" name="rnflags"/><property kind="parameter" name="cachesize"/><property kind="parameter" name="psize"/><property kind="parameter" name="lorder"/><property kind="parameter" name="reclen"/><property kind="parameter" name="bval"/><property kind="parameter" name="bfname"/></properties></element>

<group name="Hash, BTree and Record Objects">
<description>Once instantiated, hash, btree and record objects support
the same methods as dictionaries. In addition, they support
the methods listed below.
Changed in version 2.3.1: Added dictionary methods
</description>
<element kind="function" name="close">
<description>Close the underlying file. The object can no longer be accessed. Since
there is no open open method for these objects, to open the file
again a new bsddb module open function must be called.</description>

</element>

<element kind="function" name="keys">
<description>Return the list of keys contained in the DB file. The order of the list is
unspecified and should not be relied on. In particular, the order of the
list returned is different for different file formats.</description>

</element>

<element kind="function" name="has_key">
<description>Return 1 if the DB file contains the argument as a key.</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="set_location">
<description>Set the cursor to the item indicated by key and return a tuple
containing the key and its value. For binary tree databases (opened
using btopen()), if key does not actually exist in
the database, the cursor will point to the next item in sorted order
and return that key and value. For other databases,
KeyError will be raised if key is not found in the
database.</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="first">
<description>Set the cursor to the first item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases.</description>

</element>

<element kind="function" name="next">
<description>Set the cursor to the next item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases.</description>

</element>

<element kind="function" name="previous">
<description>Set the cursor to the previous item in the DB file and return it. The
order of keys in the file is unspecified, except in the case of B-Tree
databases. This is not supported on hashtable databases (those opened
with hashopen()).</description>

</element>

<element kind="function" name="last">
<description>Set the cursor to the last item in the DB file and return it. The
order of keys in the file is unspecified. This is not supported on
hashtable databases (those opened with hashopen()).</description>

</element>

<element kind="function" name="sync">
<description>Synchronize the database on disk.</description>

</element>

</group>
</group>
<group name="dumbdbm --- Portable DBM implementation">
<description>Portable implementation of the simple DBM interface.
</description>
<element kind="function" name="open">
<description>Open a dumbdbm database and return a dumbdbm object. The filename
argument is the basename of the database file (without any specific
extensions). When a dumbdbm database is created, files with .dat and
.dir extensions are created.
The optional flag argument is currently ignored; the database is
always opened for update, and will be created if it does not exist.
The optional mode argument is the 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).
Changed in version 2.2: The mode argument was ignored in earlier
versions</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/></properties></element>

<group name="Dumbdbm Objects">
<description>In addition to the methods provided by the UserDict.DictMixin class,
dumbdbm objects provide the following methods.
</description>
<element kind="function" name="sync">
<description>Synchronize the on-disk directory and data files. This method is called by
the sync method of Shelve objects.</description>

</element>

</group>
</group>
<group name="zlib --- Compression compatible with gzip">
<description>Low-level interface to compression and decompression
routines compatible with gzip.
For applications that require data compression, the functions in this
module allow compression and decompression, using the zlib library.
The zlib library has its own home page at
http://www.gzip.org/zlib/. Version 1.1.3 is the
most recent version as of September 2000; use a later version if one
is available. There are known incompatibilities between the Python
module and earlier versions of the zlib library.
The available exception and functions in this module are:
{error}
Exception raised on compression and decompression errors.
</description>
<element kind="function" name="adler32">
<description>Computes a Adler-32 checksum of string. (An Adler-32
checksum is almost as reliable as a CRC32 but can be computed much
more quickly.) If value is present, it is used as the
starting value of the checksum; otherwise, a fixed default value is
used. This allows computing a running checksum over the
concatenation of several input strings. The algorithm is not
cryptographically strong, and should not be used for
authentication or digital signatures. Since the algorithm is
designed for use as a checksum algorithm, it is not suitable for
use as a general hash algorithm.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="value"/></properties></element>

<element kind="function" name="compress">
<description>Compresses the data in string, returning a string contained
compressed data. level is an integer from 1 to
9 controlling the level of compression; 1 is fastest
and produces the least compression, 9 is slowest and produces
the most. The default value is 6. Raises the
error exception if any error occurs.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="level"/></properties></element>

<element kind="function" name="compressobj">
<description>Returns a compression object, to be used for compressing data streams
that won't fit into memory at once. level is an integer from
1 to 9 controlling the level of compression; 1 is
fastest and produces the least compression, 9 is slowest and
produces the most. The default value is 6.</description>

<properties><property kind="parameter" name="level" required="1"/></properties></element>

<element kind="function" name="crc32">
<description>Computes a CRC (Cyclic Redundancy Check)%
</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="value"/></properties></element>

<element kind="function" name="decompress">
<description>Decompresses the data in string, returning a string containing
the uncompressed data. The wbits parameter controls the size of
the window buffer. If bufsize is given, it is used as the
initial size of the output buffer. Raises the error
exception if any error occurs.
The absolute value of wbits is the base two logarithm of the
size of the history buffer (the ``window size'') used when compressing
data. Its absolute value should be between 8 and 15 for the most
recent versions of the zlib library, larger values resulting in better
compression at the expense of greater memory usage. The default value
is 15. When wbits is negative, the standard
gzip header is suppressed; this is an undocumented feature
of the zlib library, used for compatibility with unzip's
compression file format.
bufsize is the initial size of the buffer used to hold
decompressed data. If more space is required, the buffer size will be
increased as needed, so you don't have to get this value exactly
right; tuning it will only save a few calls to malloc(). The
default size is 16384.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="wbits"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="decompressobj">
<description>Returns a decompression object, to be used for decompressing data
streams that won't fit into memory at once. The wbits
parameter controls the size of the window buffer.</description>

<properties><property kind="parameter" name="wbits" required="1"/></properties></element>

<element kind="function" name="compress">
<description>Compress string, returning a string containing compressed data
for at least part of the data in string. This data should be
concatenated to the output produced by any preceding calls to the
compress() method. Some input may be kept in internal buffers
for later processing.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="flush">
<description>All pending input is processed, and a string containing the remaining
compressed output is returned. mode can be selected from the
constants Z_SYNC_FLUSH, Z_FULL_FLUSH, or Z_FINISH, defaulting to Z_FINISH. Z_SYNC_FLUSH and Z_FULL_FLUSH allow compressing further strings of data and
are used to allow partial error recovery on decompression, while
Z_FINISH finishes the compressed stream and prevents compressing any more data. After calling
flush() with mode set to Z_FINISH, the
compress() method cannot be called again; the only realistic
action is to delete the object.</description>

<properties><property kind="parameter" name="mode" required="1"/></properties></element>

<element kind="function" name="decompress">
<description>{max_length}
Decompress string, returning a string containing the
uncompressed data corresponding to at least part of the data in
string. This data should be concatenated to the output produced
by any preceding calls to the
decompress() method. Some of the input data may be preserved
in internal buffers for later processing.
If the optional parameter max_length is supplied then the return value
will be no longer than max_length. This may mean that not all of the
compressed input can be processed; and unconsumed data will be stored
in the attribute unconsumed_tail. This string must be passed
to a subsequent call to decompress() if decompression is to
continue. If max_length is not supplied then the whole input is
decompressed, and unconsumed_tail is an empty string.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="flush">
<description>All pending input is processed, and a string containing the remaining
uncompressed output is returned. After calling flush(), the
decompress() method cannot be called again; the only realistic
action is to delete the object.</description>

</element>

</group>
<group name="gzip --- Support for gzip files">
<description>Interfaces for gzip compression and
decompression using file objects.
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. Note that additional file formats which can be
decompressed by the gzip and gunzip programs, such as those produced by compress and pack, are not
supported by this module.
The module defines the following items:
</description>
<element kind="function" name="GzipFile">
<description>Constructor for the GzipFile class, which simulates most of
the methods of a file object, with the exception of the readinto()
and truncate() methods. At least one of
fileobj and filename must be given a non-trivial value.
The new class instance is based on fileobj, which can be a
regular file, a StringIO object, or any other object which
simulates a file. It defaults to None, in which case
filename is opened to provide a file object.
When fileobj is not None, the filename argument is
only used to be included in the gzip file header, which may
includes the original filename of the uncompressed file. It defaults
to the filename of fileobj, if discernible; otherwise, it
defaults to the empty string, and in this case the original filename
is not included in the header.
The mode argument can be any of 'r', 'rb',
'a', 'ab', 'w', or 'wb', depending on
whether the file will be read or written. The default is the mode of
fileobj if discernible; otherwise, the default is 'rb'.
If not given, the 'b' flag will be added to the mode to ensure the
file is opened in binary mode for cross-platform portability.
The compresslevel argument 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 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.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="compresslevel"/><property kind="parameter" name="fileobj"/></properties></element>

<element kind="function" name="open">
<description>This is a shorthand for GzipFile(filename,
mode, compresslevel). The filename
argument is required; mode defaults to 'rb' and
compresslevel defaults to 9.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="compresslevel"/></properties></element>

</group>
<group name="bz2 --- Compression compatible with bzip2">
<description>Interface to compression and decompression
routines compatible with bzip2.
New in version 2.3
This module provides a comprehensive interface for the bz2 compression library.
It implements a complete file interface, one-shot (de)compression functions,
and types for sequential (de)compression.
Here is a resume of the features offered by the bz2 module:
BZ2File class implements a complete file interface, including
readline(), readlines(),
writelines(), seek(), etc;
BZ2File class implements emulated seek() support;
BZ2File class implements universal newline support;
BZ2File class offers an optimized line iteration using
the readahead algorithm borrowed from file objects;
Sequential (de)compression supported by BZ2Compressor and
BZ2Decompressor classes;
One-shot (de)compression supported by compress() and
decompress() functions;
Thread safety uses individual locking mechanism;
Complete inline documentation;
</description>
<group name="(De)compression of files">
<description>Handling of compressed files is offered by the BZ2File class.
</description>
<element kind="function" name="BZ2File">
<description>Open a bz2 file. Mode can be either 'r' or 'w', for reading (default) or writing. When opened for writing, the file will be created if
it doesn't exist, and truncated otherwise. If buffering is given,
0 means unbuffered, and larger numbers specify the buffer size;
the default is 0. If
compresslevel is given, it must be a number between 1 and
9; the default is 9.
Add a U to mode to open the file for input with universal newline
support. Any line ending in the input file will be seen as a
\n in Python. Also, a file so opened gains the
attribute newlines; the value for this attribute is one of
None (no newline read yet), '\r', '\n',
'\r\n' or a tuple containing all the newline types
seen. Universal newlines are available only when reading.
Instances support iteration in the same way as normal file
instances.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="buffering"/><property kind="parameter" name="compresslevel"/></properties></element>

</group>
<group name="Sequential (de)compression">
<description>Sequential compression and decompression is done using the classes
BZ2Compressor and BZ2Decompressor.
</description>
<element kind="function" name="BZ2Compressor">
<description>Create a new compressor object. This object may be used to compress
data sequentially. If you want to compress data in one shot, use the
compress() function instead. The compresslevel parameter,
if given, must be a number between 1 and 9; the default
is 9.</description>

<properties><property kind="parameter" name="compresslevel" required="1"/></properties></element>

<element kind="function" name="BZ2Decompressor">
<description>Create a new decompressor object. This object may be used to decompress
data sequentially. If you want to decompress data in one shot, use the
decompress() function instead.</description>

</element>

</group>
<group name="One-shot (de)compression">
<description>One-shot compression and decompression is provided through the
compress() and decompress() functions.
</description>
<element kind="function" name="compress">
<description>Compress data in one shot. If you want to compress data sequentially,
use an instance of BZ2Compressor instead. The compresslevel
parameter, if given, must be a number between 1 and 9;
the default is 9.</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="compresslevel"/></properties></element>

<element kind="function" name="decompress">
<description>Decompress data in one shot. If you want to decompress data
sequentially, use an instance of BZ2Decompressor instead.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

</group>
</group>
<group name="zipfile --- Work with ZIP archives">
<description>Read and write ZIP-format archive files.
% LaTeX markup by Fred L. Drake, Jr. &lt;fdrake@acm.org&gt;
New in version 1.6
The ZIP file format is a common archive and compression standard.
This module provides tools to create, read, write, append, and list a
ZIP file. Any advanced use of this module will require an
understanding of the format, as defined in
PKZIP Application
Note.
This module does not currently handle ZIP files which have appended
comments, or multi-disk ZIP files.
The available attributes of this module are:
{error}
The error raised for bad ZIP files.
{ZipFile}
The class for reading and writing ZIP files. See
``ZipFile Objects'' (section zipfile-objects) for
constructor details.
{PyZipFile}
Class for creating ZIP archives containing Python libraries.
</description>
<element kind="function" name="ZipInfo">
<description>Class used the represent infomation about a member of an archive.
Instances of this class are returned by the getinfo() and
infolist() methods of ZipFile objects. Most users
of the zipfile module will not need to create these, but
only use those created by this module.
filename should be the full name of the archive member, and
date_time should be a tuple containing six fields which
describe the time of the last modification to the file; the fields
are described in section zipinfo-objects, ``ZipInfo Objects.''</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="date_time"/></properties></element>

<element kind="function" name="is_zipfile">
<description>Returns True if filename is a valid ZIP file based on its magic
number, otherwise returns False. This module does not currently
handle ZIP files which have appended comments.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<group name="ZipFile Objects">
<element kind="function" name="ZipFile">
<description>Open a ZIP file, where file can be either a path to a file
(a string) or a file-like object. The mode parameter
should be 'r' to read an existing file, 'w' to
truncate and write a new file, or 'a' to append to an
existing file. For mode is 'a' and file
refers to an existing ZIP file, then additional files are added to
it. If file does not refer to a ZIP file, then a new ZIP
archive is appended to the file. This is meant for adding a ZIP
archive to another file, such as python.exe. Using
cat myzip.zip &gt;&gt; python.exe
also works, and at least WinZip can read such files.
compression is the ZIP compression method to use when writing
the archive, and should be ZIP_STORED or
ZIP_DEFLATED; unrecognized values will cause
RuntimeError to be raised. If ZIP_DEFLATED
is specified but the zlib module is not available,
RuntimeError is also raised. The default is
ZIP_STORED.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="compression"/></properties></element>

<element kind="function" name="close">
<description>Close the archive file. You must call close() before
exiting your program or essential records will not be written.</description>

</element>

<element kind="function" name="getinfo">
<description>Return a ZipInfo object with information about the archive
member name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="infolist">
<description>Return a list containing a ZipInfo object for each member of
the archive. The objects are in the same order as their entries in
the actual ZIP file on disk if an existing archive was opened.</description>

</element>

<element kind="function" name="namelist">
<description>Return a list of archive members by name.</description>

</element>

<element kind="function" name="printdir">
<description>Print a table of contents for the archive to sys.stdout.</description>

</element>

<element kind="function" name="read">
<description>Return the bytes of the file in the archive. The archive must be
open for read or append.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="testzip">
<description>Read all the files in the archive and check their CRC's. Return the
name of the first bad file, or else return None.</description>

</element>

<element kind="function" name="write">
<description>Write the file named filename to the archive, giving it the
archive name arcname (by default, this will be the same as
filename). If given, compress_type overrides the value
given for the compression parameter to the constructor for
the new entry. The archive must be open with mode 'w' or
'a'.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="arcname"/><property kind="parameter" name="compress_type"/></properties></element>

<element kind="function" name="writestr">
<description>Write the string bytes to the archive; zinfo_or_arcname
is either the file name it will be given in the archive, or a
ZipInfo instance. If it's an instance, at least the
filename, date, and time must be given. If it's a name, the date
and time is set to the current date and time. The archive must be
opened with mode 'w' or 'a'.</description>

<properties><property kind="parameter" name="zinfo_or_arcname" required="1"/><property kind="parameter" name="bytes bytes" required="1"/></properties></element>

</group>
<group name="PyZipFile Objects">
<description>The PyZipFile constructor takes the same parameters as the
ZipFile constructor. Instances have one method in addition to
those of ZipFile objects.
</description>
<element kind="function" name="writepy">
<description>Search for files *.py and add the corresponding file to the
archive. The corresponding file is a *.pyo file if
available, else a *.pyc file, compiling if necessary. If the
pathname is a file, the filename must end with .py, and just
the (corresponding *.py[co]) file is added at the top level
(no path information). If it is a directory, and the directory is
not a package directory, then all the files *.py[co] are
added at the top level. If the directory is a package directory,
then all *.py[oc] are added under the package name as a file
path, and if any subdirectories are package directories, all of
these are added recursively. basename is intended for
internal use only. The writepy() method makes archives
with file names like this:
string.pyc # Top level name test/__init__.pyc # Package directory test/testall.pyc # Module test.testall
test/bogus/__init__.pyc # Subpackage directory test/bogus/myfile.pyc # Submodule test.bogus.myfile
</description>

<properties><property kind="parameter" name="pathname" required="1"/><property kind="parameter" name="basename"/></properties></element>

</group>
<group name="ZipInfo Objects">
</group>
</group>
<group name="tarfile --- Read and write tar archive files">
<description>Read and write tar-format archive files.
New in version 2.3
The tarfile module makes it possible to read and create tar archives.
Some facts and figures:
reads and writes gzip and bzip2 compressed archives.
creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
reads GNU tar extensions longname, longlink and
sparse.
stores pathnames of unlimited length using GNU tar extensions.
handles directories, regular files, hardlinks, symbolic links, fifos,
character devices and block devices and is able to acquire and
restore file information like timestamp, access permissions and owner.
can handle tape devices.
</description>
<element kind="function" name="open">
<description>Return a TarFile object for the pathname name.
For detailed information on TarFile objects,
see TarFile Objects (section tarfile-objects).
mode has to be a string of the form 'filemode[:compression]',
it defaults to 'r'. Here is a full list of mode combinations:
{c|l}{code}{mode}{action}
'r'{Open for reading with transparent compression (recommended).}
'r:'{Open for reading exclusively without compression.}
'r:gz'{Open for reading with gzip compression.}
'r:bz2'{Open for reading with bzip2 compression.}
'a' or 'a:'{Open for appending with no compression.}
'w' or 'w:'{Open for uncompressed writing.}
'w:gz'{Open for gzip compressed writing.}
'w:bz2'{Open for bzip2 compressed writing.}
Note that 'a:gz' or 'a:bz2' is not possible.
If mode is not suitable to open a certain (compressed) file for
reading, ReadError is raised. Use mode 'r' to
avoid this. If a compression method is not supported,
CompressionError is raised.
If fileobj is specified, it is used as an alternative to
a file object opened for name.
For special purposes, there is a second format for mode:
'filemode|[compression]'. open will return a TarFile
object that processes its data as a stream of blocks. No random
seeking will be done on the file. If given, fileobj may be any
object that has a read() resp. write() method.
bufsize specifies the blocksize and defaults to 20 * 512
bytes. Use this variant in combination with e.g. sys.stdin, a socket
file object or a tape device.
However, such a TarFile object is limited in that it does not allow
to be accessed randomly, see Examples (section
tar-examples).
The currently possible modes:
{c|l}{code}{mode}{action}
'r|'{Open a stream of uncompressed tar blocks for reading.}
'r|gz'{Open a gzip compressed stream for reading.}
'r|bz2'{Open a bzip2 compressed stream for reading.}
'w|'{Open an uncompressed stream for writing.}
'w|gz'{Open an gzip compressed stream for writing.}
'w|bz2'{Open an bzip2 compressed stream for writing.}
</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="fileobj"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="is_tarfile">
<description>Return True if name is a tar archive file, that the
tarfile module can read.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="TarFileCompat">
<description>Class for limited access to tar archives with a zipfile-like
interface. Please consult the documentation of zipfile for more
details.
compression must be one of the following constants:
{TAR_PLAIN}
Constant for an uncompressed tar archive.
{TAR_GZIPPED}
Constant for a gzip compressed tar archive.
</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="compression"/></properties></element>

<group name="TarFile Objects">
<description>The TarFile object provides an interface to a tar archive. A tar
archive is a sequence of blocks. An archive member (a stored file) is made up
of a header block followed by data blocks. It is possible, to store a file in a
tar archive several times. Each archive member is represented by a
TarInfo object, see TarInfo Objects (section
tarinfo-objects) for details.
</description>
<element kind="function" name="TarFile">
<description>Open an (uncompressed) tar archive name.
mode is either 'r' to read from an existing archive,
'a' to append data to an existing file or 'w' to create a new
file overwriting an existing one. mode defaults to 'r'.
If fileobj is given, it is used for reading or writing data.
If it can be determined, mode is overridden by fileobj's mode.
fileobj is not closed, when TarFile is closed.
</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="fileobj"/></properties></element>

<element kind="function" name="open">
<description>Alternative constructor. The open() function on module level is
actually a shortcut to this classmethod. See section module-tarfile
for details.</description>

<properties><property kind="parameter" name="......" required="1"/></properties></element>

<element kind="function" name="getmember">
<description>Return a TarInfo object for member name. If name can
not be found in the archive, KeyError is raised.
If a member occurs more than once in the archive, its last
occurence is assumed to be the most up-to-date version.
</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getmembers">
<description>Return the members of the archive as a list of TarInfo objects.
The list has the same order as the members in the archive.</description>

</element>

<element kind="function" name="getnames">
<description>Return the members as a list of their names. It has the same order as
the list returned by getmembers().</description>

</element>

<element kind="function" name="list">
<description>Print a table of contents to sys.stdout. If verbose is
False, only the names of the members are printed. If it is
True, an &quot;ls -l&quot;-like output is produced.</description>

<properties><property default="Trueverbose=True" kind="parameter" name="verbose" required="1"/></properties></element>

<element kind="function" name="next">
<description>Return the next member of the archive as a TarInfo object, when
TarFile is opened for reading. Return None if there is no
more available.</description>

</element>

<element kind="function" name="extract">
<description>Extract a member from the archive to the current working directory,
using its full name. Its file information is extracted as accurately as
possible.
member may be a filename or a TarInfo object.
You can specify a different directory using path.</description>

<properties><property kind="parameter" name="member" required="1"/><property kind="parameter" name="path"/></properties></element>

<element kind="function" name="extractfile">
<description>Extract a member from the archive as a file object.
member may be a filename or a TarInfo object.
If member is a regular file, a file-like object is returned.
If member is a link, a file-like object is constructed from the
link's target.
If member is none of the above, None is returned.
The file-like object is read-only and provides the following methods:
read(), readline(), readlines(),
seek(), tell().
</description>

<properties><property kind="parameter" name="membermember" required="1"/></properties></element>

<element kind="function" name="add">
<description>Add the file name to the archive. name may be any type
of file (directory, fifo, symbolic link, etc.).
If given, arcname specifies an alternative name for the file in the
archive. Directories are added recursively by default.
This can be avoided by setting recursive to False.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="arcname"/><property default="True" kind="parameter" name="recursive"/></properties></element>

<element kind="function" name="addfile">
<description>Add the TarInfo object tarinfo to the archive.
If fileobj is given, tarinfo.size bytes are read
from it and added to the archive. You can create TarInfo objects
using gettarinfo().
On Windows platforms, fileobj should always be opened with mode
'rb' to avoid irritation about the file size.
</description>

<properties><property kind="parameter" name="tarinfo" required="1"/><property kind="parameter" name="fileobj"/></properties></element>

<element kind="function" name="gettarinfo">
<description>Create a TarInfo object for either the file name or the
file object fileobj (using os.fstat() on its file descriptor).
You can modify some of the TarInfo's attributes before you add it
using addfile().
If given, arcname specifies an alternative name for the file in the
archive.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="arcname"/><property kind="parameter" name="fileobj"/></properties></element>

<element kind="function" name="close">
<description>Close the TarFile. In write-mode, two finishing zero blocks are
appended to the archive.</description>

</element>

</group>
<group name="TarInfo Objects">
<description>A TarInfo object represents one member in a TarFile. Aside from
storing all required attributes of a file (like file type, size, time,
permissions, owner etc.), it provides some useful methods to determine its
type. It does not contain the file's data itself.
TarInfo objects are returned by TarFile's methods
getmember(), getmembers() and gettarinfo().
</description>
<element kind="function" name="TarInfo">
<description>Create a TarInfo object.</description>

<properties><property kind="parameter" name="name" required="1"/></properties></element>

<element kind="function" name="frombuf">
<description>Create and return a TarInfo object from a string buffer.</description>

</element>

<element kind="function" name="tobuf">
<description>Create a string buffer from a TarInfo object.</description>

</element>

<element kind="function" name="isfile">
<description>Return True if the Tarinfo object is a regular file.</description>

</element>

<element kind="function" name="isreg">
<description>Same as isfile().</description>

</element>

<element kind="function" name="isdir">
<description>Return True if it is a directory.</description>

</element>

<element kind="function" name="issym">
<description>Return True if it is a symbolic link.</description>

</element>

<element kind="function" name="islnk">
<description>Return True if it is a hard link.</description>

</element>

<element kind="function" name="ischr">
<description>Return True if it is a character device.</description>

</element>

<element kind="function" name="isblk">
<description>Return True if it is a block device.</description>

</element>

<element kind="function" name="isfifo">
<description>Return True if it is a FIFO.</description>

</element>

<element kind="function" name="isdev">
<description>Return True if it is one of character device, block device or FIFO.</description>

</element>

</group>
<group name="Examples">
</group>
</group>
<group name="readline --- GNU readline interface">
<description>Unix
GNU readline support for Python.
The readline module defines a number of functions used either
directly or from the rlcompleter module to facilitate
completion and history file read and write from the Python
interpreter.
The readline module defines the following functions:
</description>
<element kind="function" name="parse_and_bind">
<description>Parse and execute single line of a readline init file.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="get_line_buffer">
<description>Return the current contents of the line buffer.</description>

</element>

<element kind="function" name="insert_text">
<description>Insert text into the command line.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="read_init_file">
<description>Parse a readline initialization file.
The default filename is the last filename used.</description>

<properties><property kind="parameter" name="filename" required="1"/></properties></element>

<element kind="function" name="read_history_file">
<description>Load a readline history file.
The default filename is .</description>

<properties><property kind="parameter" name="filename" required="1"/></properties></element>

<element kind="function" name="write_history_file">
<description>Save a readline history file.
The default filename is .</description>

<properties><property kind="parameter" name="filename" required="1"/></properties></element>

<element kind="function" name="clear_history">
<description>Clear the current history. (Note: this function is not available if
the installed version of GNU readline doesn't support it.)
New in version 2.4</description>

</element>

<element kind="function" name="get_history_length">
<description>Return the desired length of the history file. Negative values imply
unlimited history file size.</description>

</element>

<element kind="function" name="set_history_length">
<description>Set the number of lines to save in the history file.
write_history_file() uses this value to truncate the
history file when saving. Negative values imply unlimited history
file size.</description>

<properties><property kind="parameter" name="lengthlength" required="1"/></properties></element>

<element kind="function" name="set_startup_hook">
<description>Set or remove the startup_hook function. If function is specified,
it will be used as the new startup_hook function; if omitted or
None, any hook function already installed is removed. The
startup_hook function is called with no arguments just
before readline prints the first prompt.</description>

<properties><property kind="parameter" name="function" required="1"/></properties></element>

<element kind="function" name="set_pre_input_hook">
<description>Set or remove the pre_input_hook function. If function is specified,
it will be used as the new pre_input_hook function; if omitted or
None, any hook function already installed is removed. The
pre_input_hook function is called with no arguments after the first prompt
has been printed and just before readline starts reading input characters.</description>

<properties><property kind="parameter" name="function" required="1"/></properties></element>

<element kind="function" name="set_completer">
<description>Set or remove the completer function. If function is specified,
it will be used as the new completer function; if omitted or
None, any completer function already installed is removed. The
completer function is called as function(text,
state), for state in 0, 1, 2, ...,
until it returns a non-string value. It should return the next
possible completion starting with text.</description>

<properties><property kind="parameter" name="function" required="1"/></properties></element>

<element kind="function" name="get_completer">
<description>Get the completer function, or None if no completer function
has been set. New in version 2.3</description>

</element>

<element kind="function" name="get_begidx">
<description>Get the beginning index of the readline tab-completion scope.</description>

</element>

<element kind="function" name="get_endidx">
<description>Get the ending index of the readline tab-completion scope.</description>

</element>

<element kind="function" name="set_completer_delims">
<description>Set the readline word delimiters for tab-completion.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="get_completer_delims">
<description>Get the readline word delimiters for tab-completion.</description>

</element>

<element kind="function" name="add_history">
<description>Append a line to the history buffer, as if it was the last line typed.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<group name="Example">
</group>
</group>
<group name="rlcompleter --- Completion function for GNU readline">
<description>Unix
Python identifier completion for the GNU readline library.
The rlcompleter module defines a completion function for
the readline module by completing valid Python identifiers
and keywords.
This module is -specific due to its dependence on the
readline module.
The rlcompleter module defines the Completer class.
Example:
&gt;&gt;&gt; import rlcompleter
&gt;&gt;&gt; import readline
&gt;&gt;&gt; readline.parse_and_bind(&quot;tab: complete&quot;)
&gt;&gt;&gt; readline. &lt;TAB PRESSED&gt;
readline.__doc__ readline.get_line_buffer readline.read_init_file
readline.__file__ readline.insert_text readline.set_completer
readline.__name__ readline.parse_and_bind
&gt;&gt;&gt; readline.
The rlcompleter module is designed for use with Python's
interactive mode. A user can add the following lines to his or her
initialization file (identified by the PYTHONSTARTUP
environment variable) to get automatic Tab completion:
try:
import readline
except ImportError:
print &quot;Module readline not available.&quot;
else:
import rlcompleter
readline.parse_and_bind(&quot;tab: complete&quot;)
</description>
<group name="Completer Objects">
<description>Completer objects have the following method:
</description>
<element kind="function" name="complete">
<description>Return the stateth completion for text.
If called for text that doesn't include a period character
(.), it will complete from names currently defined in
__main__, __builtin__ and
keywords (as defined by the keyword module).
If called for a dotted name, it will try to evaluate anything without
obvious side-effects (functions will not be evaluated, but it
can generate calls to __getattr__()) up to the last part, and
find matches for the rest via the dir() function.</description>

<properties><property kind="parameter" name="text" required="1"/><property kind="parameter" name="state state" required="1"/></properties></element>

</group>
</group>
</group>
<group name="Unix Specific Services">
<group name="posix --- The most common system calls">
<description>Unix
The most common calls (normally used
via module os).
This module provides access to operating system functionality that is
standardized by the C Standard and the standard (a thinly
disguised interface).
Do not import this module directly. Instead, import the
module os, which provides a portable version of this
interface. On , the os module provides a superset of
the posix interface. On non- operating systems the
posix module is not available, but a subset is always
available through the os interface. Once os is
imported, there is no performance penalty in using it instead
of posix. In addition, osos
provides some additional functionality, such as automatically calling
putenv() when an entry in os.environ is changed.
The descriptions below are very terse; refer to the corresponding
manual (or documentation) entry for more information.
Arguments called path refer to a pathname given as a string.
Errors are reported as exceptions; the usual exceptions are given for
type errors, while errors reported by the system calls raise
error (a synonym for the standard exception
OSError), described below.
</description>
<group name="Large File Support">
</group>
<group name="Module Contents">
</group>
</group>
<group name="pwd --- The password database">
<description>Unix
The password database (getpwnam() and friends).
This module provides access to the user account and password
database. It is available on all versions.
Password database entries are reported as a tuple-like object, whose
attributes correspond to the members of the passwd structure
(Attribute field below, see &lt;pwd.h&gt;):
{r|l|l}{textrm}{Index}{Attribute}{Meaning}
0{pw_name}{Login name}
1{pw_passwd}{Optional encrypted password}
2{pw_uid}{Numerical user ID}
3{pw_gid}{Numerical group ID}
4{pw_gecos}{User name or comment field}
5{pw_dir}{User home directory}
6{pw_shell}{User command interpreter}
The uid and gid items are integers, all others are strings.
KeyError is raised if the entry asked for cannot be found.
In traditional the field pw_passwd usually
contains a password encrypted with a DES derived algorithm (see module
cryptcrypt). However most modern unices use a so-called shadow password system. On those unices the
field pw_passwd only contains a asterisk ('*') or the letter x where the encrypted password is stored in a file
/etc/shadow which is not world readable.
It defines the following items:
</description>
<element kind="function" name="getpwuid">
<description>Return the password database entry for the given numeric user ID.</description>

<properties><property kind="parameter" name="uiduid" required="1"/></properties></element>

<element kind="function" name="getpwnam">
<description>Return the password database entry for the given user name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getpwall">
<description>Return a list of all available password database entries, in arbitrary order.</description>

</element>

</group>
<group name="grp --- The group database">
<description>Unix
The group database (getgrnam() and friends).
This module provides access to the group database.
It is available on all versions.
Group database entries are reported as a tuple-like object, whose
attributes correspond to the members of the group structure
(Attribute field below, see &lt;pwd.h&gt;):
{r|l|l}{textrm}{Index}{Attribute}{Meaning}
0{gr_name}{the name of the group}
1{gr_passwd}{the (encrypted) group password; often empty}
2{gr_gid}{the numerical group ID}
3{gr_mem}{all the group member's user names}
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. Check both
databases to get complete membership information.)
It defines the following items:
</description>
<element kind="function" name="getgrgid">
<description>Return the group database entry for the given numeric group ID.
KeyError is raised if the entry asked for cannot be found.</description>

<properties><property kind="parameter" name="gidgid" required="1"/></properties></element>

<element kind="function" name="getgrnam">
<description>Return the group database entry for the given group name.
KeyError is raised if the entry asked for cannot be found.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getgrall">
<description>Return a list of all available group entries, in arbitrary order.</description>

</element>

</group>
<group name="crypt --- Function to check passwords">
<description>Unix
The crypt() function used to check
.
This module implements an interface to the
crypt{3}</description>
<element kind="function" name="crypt">
<description>word will usually be a user's password as typed at a prompt or in a graphical interface. salt is usually a random
two-character string which will be used to perturb the DES algorithm
in one of 4096 ways. The characters in salt must be in the
set [./a-zA-Z0-9]. Returns the hashed password as a
string, which will be composed of characters from the same alphabet
as the salt (the first two characters represent the salt itself).</description>

<properties><property kind="parameter" name="word" required="1"/><property kind="parameter" name="salt salt" required="1"/></properties></element>

</group>
<group name="dl --- Call C functions in shared objects">
<description>Unix %?????????? Anyone????????????
Call C functions in shared objects.
The dl module defines an interface to the
dlopen() function, which is the most common interface on
platforms for handling dynamically linked libraries. It allows
the program to call arbitrary functions in such a library.
This module will not work unless
sizeof(int) == sizeof(long) == sizeof(char *)
If this is not the case, SystemError will be raised on
import.
The dl module defines the following function:
</description>
<element kind="function" name="open">
<description>Open a shared object file, and return a handle. Mode
signifies late binding (RTLD_LAZY) or immediate binding
(RTLD_NOW). Default is RTLD_LAZY. Note that some
systems do not support RTLD_NOW.
Return value is a dlobject.</description>

<properties><property kind="parameter" name="name" required="1"/><property default=" RTLD_LAZY" kind="parameter" name="mode"/></properties></element>

<group name="Dl Objects">
<description>Dl objects, as returned by open() above, have the
following methods:
</description>
<element kind="function" name="close">
<description>Free all resources, except the memory.</description>

</element>

<element kind="function" name="sym">
<description>Return the pointer for the function named name, as a number, if
it exists in the referenced shared object, otherwise None. This
is useful in code like:
&gt;&gt;&gt; if a.sym('time'): ... a.call('time')
... else: ... time.time()
(Note that this function will return a non-zero number, as zero is the
pointer)</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="call">
<description>Call the function named name in the referenced shared object.
The arguments must be either Python integers, which will be passed as is, Python strings, to which a pointer will be passed, or None, which will be passed as . Note that strings should only be passed to functions as const char*, as
Python will not like its string mutated.
There must be at most 10 arguments, and arguments not given will be
treated as None. The function's return value must be a C
long, which is a Python integer.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="arg1"/><property kind="parameter" name="arg2ldots"/></properties></element>

</group>
</group>
<group name="dbm --- Simple ``database'' interface">
<description>Unix
The standard ``database'' interface, based on ndbm.
The dbm module provides an interface to the (n)dbm library. Dbm objects behave like mappings
(dictionaries), except that keys and values are always strings.
Printing a dbm object doesn't print the keys and values, and the
items() and values() methods are not supported.
This module can be used with the ``classic'' ndbm interface, the BSD
DB compatibility interface, or the GNU GDBM compatibility interface.
On , the configure script will attempt to locate the
appropriate header file to simplify building this module.
The module defines the following:
{error}
Raised on dbm-specific errors, such as I/O errors.
KeyError is raised for general mapping errors like
specifying an incorrect key.
{library}
Name of the ndbm implementation library used.
</description>
<element kind="function" name="open">
<description>Open a dbm database and return a dbm object. The filename
argument is the name of the database file (without the .dir or
.pag extensions; note that the BSD DB implementation of the
interface will append the extension .db and only create one
file).
The optional flag argument must be one of these values:
{c|l}{code}{Value}{Meaning}
'r'{Open existing database for reading only (default)}
'w'{Open existing database for reading and writing}
'c'{Open database for reading and writing, creating it if
it doesn't exist}
'n'{Always create a new, empty database, open for reading
and writing}
The optional mode argument is the mode of the file, used
only when the database has to be created. It defaults to octal
0666.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag"/><property kind="parameter" name="mode"/></properties></element>

</group>
<group name="gdbm --- GNU's reinterpretation of dbm">
<description>Unix
GNU's reinterpretation of dbm.
This module is quite similar to the dbmdbm
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:
{error}
Raised on gdbm-specific errors, such as I/O errors.
KeyError is raised for general mapping errors like
specifying an incorrect key.
</description>
<element kind="function" name="open">
<description>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).
The following additional characters may be appended to the flag to
control how the database is opened:
'f' --- Open the database in fast mode. Writes to the database
will not be syncronized.
's' --- Synchronized mode. This will cause changes to the database
will be immediately written to the file.
'u' --- Do not lock database. Not all flags are valid for all versions of gdbm. The
module constant open_flags is a string of supported flag
characters. The exception error is raised if an invalid
flag is specified.
The optional mode argument is the mode of the file, used
only when the database has to be created. It defaults to octal
0666.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="flag" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="firstkey">
<description>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.</description>

</element>

<element kind="function" name="nextkey">
<description>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)
</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="reorganize">
<description>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.</description>

</element>

<element kind="function" name="sync">
<description>When the database has been opened in fast mode, this method forces any unwritten data to be written to the disk.</description>

</element>

</group>
<group name="termios --- style tty control">
<description>Unix
tty control.
This module provides an interface to the calls for tty I/O
control. For a complete description of these calls, see the or
manual pages. It is only available for those versions
that support termios style tty I/O control (and then
only if configured at installation time).
All functions in this module take a file descriptor fd as their
first argument. This can be an integer file descriptor, such as
returned by sys.stdin.fileno(), or a file object, such as
sys.stdin itself.
This module also defines all the constants needed to work with the
functions provided here; these have the same name as their
counterparts in C. Please refer to your system documentation for more
information on using these terminal control interfaces.
The module defines the following functions:
</description>
<element kind="function" name="tcgetattr">
<description>Return a list containing the tty attributes for file descriptor
fd, as follows: [iflag, oflag, cflag,
lflag, ispeed, ospeed, cc] where
cc is a list of the tty special characters (each a string of
length 1, except the items with indices VMIN and
VTIME, which are integers when these fields are
defined). The interpretation of the flags and the speeds as well as
the indexing in the cc array must be done using the symbolic
constants defined in the termios
module.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="tcsetattr">
<description>Set the tty attributes for file descriptor fd from the
attributes, which is a list like the one returned by
tcgetattr(). The when argument determines when the
attributes are changed: TCSANOW to change immediately,
TCSADRAIN to change after transmitting all queued output,
or TCSAFLUSH to change after transmitting all queued
output and discarding all queued input.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="when" required="1"/><property kind="parameter" name="attributes attributes" required="1"/></properties></element>

<element kind="function" name="tcsendbreak">
<description>Send a break on file descriptor fd. A zero duration sends
a break for 0.25--0.5 seconds; a nonzero duration has a system
dependent meaning.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="duration duration" required="1"/></properties></element>

<element kind="function" name="tcdrain">
<description>Wait until all output written to file descriptor fd has been
transmitted.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="tcflush">
<description>Discard queued data on file descriptor fd. The queue
selector specifies which queue: TCIFLUSH for the input
queue, TCOFLUSH for the output queue, or
TCIOFLUSH for both queues.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="queue queue" required="1"/></properties></element>

<element kind="function" name="tcflow">
<description>Suspend or resume input or output on file descriptor fd. The
action argument can be TCOOFF to suspend output,
TCOON to restart output, TCIOFF to suspend
input, or TCION to restart input.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="action action" required="1"/></properties></element>

<group name="Example">
</group>
</group>
<group name="tty --- Terminal control functions">
<description>Unix
Utility functions that perform common terminal control
operations.
The tty module defines functions for putting the tty into
cbreak and raw modes.
Because it requires the termios module, it will work
only on .
The tty module defines the following functions:
</description>
<element kind="function" name="setraw">
<description>Change the mode of the file descriptor fd to raw. If when
is omitted, it defaults to TERMIOS.TCAFLUSH, and is passed
to termios.tcsetattr().</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="when"/></properties></element>

<element kind="function" name="setcbreak">
<description>Change the mode of file descriptor fd to cbreak. If when
is omitted, it defaults to TERMIOS.TCAFLUSH, and is passed
to termios.tcsetattr().</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="when"/></properties></element>

</group>
<group name="pty --- Pseudo-terminal utilities">
<description>IRIX, Linux
Pseudo-Terminal Handling for SGI and Linux.
The pty module defines operations for handling the
pseudo-terminal concept: starting another process and being able to
write to and read from its controlling terminal programmatically.
Because pseudo-terminal handling is highly platform dependant, there
is code to do it only for SGI and Linux. (The Linux code is supposed
to work on other platforms, but hasn't been tested yet.)
The pty module defines the following functions:
</description>
<element kind="function" name="fork">
<description>Fork. Connect the child's controlling terminal to a pseudo-terminal.
Return value is (pid, fd). Note that the child gets pid 0, and the fd is invalid. The parent's
return value is the pid of the child, and fd is a file
descriptor connected to the child's controlling terminal (and also
to the child's standard input and output).</description>

</element>

<element kind="function" name="openpty">
<description>Open a new pseudo-terminal pair, using os.openpty() if
possible, or emulation code for SGI and generic systems.
Return a pair of file descriptors (master, slave),
for the master and the slave end, respectively.</description>

</element>

<element kind="function" name="spawn">
<description>Spawn a process, and connect its controlling terminal with the current process's standard io. This is often used to baffle programs which
insist on reading from the controlling terminal.
The functions master_read and stdin_read should be
functions which read from a file-descriptor. The defaults try to read
1024 bytes each time they are called.</description>

<properties><property kind="parameter" name="argv" required="1"/><property kind="parameter" name="master_read"/><property kind="parameter" name="stdin_read"/></properties></element>

</group>
<group name="fcntl --- The fcntl() and ioctl() system calls">
<description>Unix
The fcntl() and ioctl() system calls.
This module performs file control and I/O control on file descriptors.
It is an interface to the fcntl() and ioctl()
routines.
All functions in this module take a file descriptor fd as their
first argument. This can be an integer file descriptor, such as
returned by sys.stdin.fileno(), or a file object, such as
sys.stdin itself, which provides a fileno() which
returns a genuine file descriptor.
The module defines the following functions:
</description>
<element kind="function" name="fcntl">
<description>Perform the requested operation on file descriptor fd (file
objects providing a fileno() method are accepted as well).
The operation is defined by op and is operating system
dependent. These codes are also found in the fcntl
module. The argument arg is optional, and defaults to the
integer value 0. When present, it can either be an integer
value, or a string. With the argument missing or an integer value,
the return value of this function is the integer return value of the
C fcntl() call. When the argument is a string it
represents a binary structure, e.g. by
struct.pack(). The binary data is copied to a buffer
whose address is passed to the C fcntl() call. The
return value after a successful call is the contents of the buffer,
converted to a string object. The length of the returned string
will be the same as the length of the arg argument. This is
limited to 1024 bytes. If the information returned in the buffer by
the operating system is larger than 1024 bytes, this is most likely
to result in a segmentation violation or a more subtle data
corruption.
If the fcntl() fails, an IOError is
raised.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="op" required="1"/><property kind="parameter" name="arg"/></properties></element>

<element kind="function" name="ioctl">
<description>This function is identical to the fcntl() function,
except that the operations are typically defined in the library
module termios and the argument handling is even more
complicated.
The parameter arg can be one of an integer, absent (treated
identically to the integer 0), an object supporting the
read-only buffer interface (most likely a plain Python string) or an
object supporting the read-write buffer interface.
In all but the last case, behaviour is as for the fcntl()
function.
If a mutable buffer is passed, then the behaviour is determined by
the value of the mutate_flag parameter.
If it is false, the buffer's mutability is ignored and behaviour is
as for a read-only buffer, except that the 1024 byte limit mentioned
above is avoided -- so long as the buffer you pass is longer than
what the operating system wants to put there, things should work.
If mutate_flag is true, then the buffer is (in effect) passed
to the underlying ioctl() system call, the latter's
return code is passed back to the calling Python, and the buffer's
new contents reflect the action of the ioctl. This is a
slight simplification, because if the supplied buffer is less than
1024 bytes long it is first copied into a static buffer 1024 bytes
long which is then passed to ioctl and copied back into
the supplied buffer.
If mutate_flag is not supplied, then in 2.3 it defaults to
false. This is planned to change over the next few Python versions:
in 2.4 failing to supply mutate_flag will get a warning but
the same behavior and in versions later than 2.5 it will default to
true.
An example:
&gt;&gt;&gt; import array, fcntl, struct, termios, os
&gt;&gt;&gt; os.getpgrp()
13341
&gt;&gt;&gt; struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, &quot; &quot;))[0]
13341
&gt;&gt;&gt; buf = array.array('h', [0])
&gt;&gt;&gt; fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
&gt;&gt;&gt; buf
array('h', [13341])
</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="op" required="1"/><property kind="parameter" name="arg"/><property kind="parameter" name="mutate_flag"/></properties></element>

<element kind="function" name="flock">
<description>Perform the lock operation op on file descriptor fd (file
objects providing a fileno() method are accepted as well).
See the manual flock{3} for details. (On some
systems, this function is emulated using fcntl().)</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="op op" required="1"/></properties></element>

<element kind="function" name="lockf">
<description>This is essentially a wrapper around the fcntl() locking
calls. fd is the file descriptor of the file to lock or unlock,
and operation is one of the following values:
LOCK_UN -- unlock
LOCK_SH -- acquire a shared lock
LOCK_EX -- acquire an exclusive lock
When operation is LOCK_SH or LOCK_EX, it
can also be bit-wise OR'd with LOCK_NB to avoid blocking on
lock acquisition. If LOCK_NB is used and the lock cannot
be acquired, an IOError will be raised and the exception
will have an errno attribute set to EACCES or
EAGAIN (depending on the operating system; for portability,
check for both values). On at least some systems, LOCK_EX
can only be used if the file descriptor refers to a file opened for
writing.
length is the number of bytes to lock, start is the byte
offset at which the lock starts, relative to whence, and
whence is as with fileobj.seek(), specifically:
0 -- relative to the start of the file
(SEEK_SET)
1 -- relative to the current buffer position
(SEEK_CUR)
2 -- relative to the end of the file
(SEEK_END)
The default for start is 0, which means to start at the
beginning of the file. The default for length is 0 which means
to lock to the end of the file. The default for whence is also
0.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="operation" required="1"/><property kind="parameter" name="len" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="whence"/></properties></element>

</group>
<group name="pipes --- Interface to shell pipelines">
<description>Unix
A Python interface to pipelines.
The pipes module defines a class to abstract the concept of
a pipeline --- a sequence of convertors from one file to another.
Because the module uses /bin/sh command lines, a or
compatible shell for os.system() and os.popen()
is required.
The pipes module defines the following class:
</description>
<element kind="function" name="Template">
<description>An abstraction of a pipeline.</description>

</element>

<group name="Template Objects">
<description>Template objects following methods:
</description>
<element kind="function" name="reset">
<description>Restore a pipeline template to its initial state.</description>

</element>

<element kind="function" name="clone">
<description>Return a new, equivalent, pipeline template.</description>

</element>

<element kind="function" name="debug">
<description>If flag is true, turn debugging on. Otherwise, turn debugging
off. When debugging is on, commands to be executed are printed, and
the shell is given set -x command to be more verbose.</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="append">
<description>Append a new action at the end. The cmd variable must be a valid
bourne shell command. The kind variable consists of two letters.
The first letter can be either of '-' (which means the command
reads its standard input), 'f' (which means the commands reads
a given file on the command line) or '.' (which means the commands
reads no input, and hence must be first.)
Similarly, the second letter can be either of '-' (which means the command writes to standard output), 'f' (which means the command writes a file on the command line) or '.' (which means
the command does not write anything, and hence must be last.)</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="kind kind" required="1"/></properties></element>

<element kind="function" name="prepend">
<description>Add a new action at the beginning. See append() for explanations
of the arguments.</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="kind kind" required="1"/></properties></element>

<element kind="function" name="open">
<description>Return a file-like object, open to file, but read from or
written to by the pipeline. Note that only one of 'r',
'w' may be given.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode mode" required="1"/></properties></element>

<element kind="function" name="copy">
<description>Copy infile to outfile through the pipe.</description>

<properties><property kind="parameter" name="infile" required="1"/><property kind="parameter" name="outfile outfile" required="1"/></properties></element>

</group>
</group>
<group name="posixfile --- File-like objects with locking support">
<description>Unix
A file-like object with support for locking.
1.5{The locking operation that this module provides is
done better and more portably by the
fcntl.lockf() call.
(in module fcntl){lockf()}}
This module implements some additional functionality over the built-in
file objects. In particular, it implements file locking, control over
the file flags, and an easy interface to duplicate the file object.
The module defines a new file object, the posixfile object. It
has all the standard file object methods and adds the methods
described below. This module only works for certain flavors of
, since it uses fcntl.fcntl() for file locking.%
(in module fcntl){fcntl()}
To instantiate a posixfile object, use the open() function
in the posixfile module. The resulting object looks and
feels roughly the same as a standard file object.
The posixfile module defines the following constants:
{SEEK_SET}
Offset is calculated from the start of the file.
{SEEK_CUR}
Offset is calculated from the current position in the file.
{SEEK_END}
Offset is calculated from the end of the file.
The posixfile module defines the following functions:
</description>
<element kind="function" name="open">
<description>Create a new posixfile object with the given filename and mode. The
filename, mode and bufsize arguments are
interpreted the same way as by the built-in open()
function.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="fileopen">
<description>Create a new posixfile object with the given standard file object.
The resulting object has the same filename and mode as the original
file object.</description>

<properties><property kind="parameter" name="fileobjectfileobject" required="1"/></properties></element>

<element kind="function" name="lock">
<description>Lock the specified section of the file that the file object is
referring to. The format is explained
below in a table. The len argument specifies the length of the
section that should be locked. The default is 0. start
specifies the starting offset of the section, where the default is
0. The whence argument specifies where the offset is
relative to. It accepts one of the constants SEEK_SET,
SEEK_CUR or SEEK_END. The default is
SEEK_SET. For more information about the arguments refer
to the fcntl{2} manual page on your system.</description>

<properties><property kind="parameter" name="fmt" required="1"/><property kind="parameter" name="len" required="1"/><property kind="parameter" name="start"/><property kind="parameter" name="whence"/></properties></element>

<element kind="function" name="flags">
<description>Set the specified flags for the file that the file object is referring
to. The new flags are ORed with the old flags, unless specified
otherwise. The format is explained below in a table. Without
the flags argument
a string indicating the current flags is returned (this is
the same as the ? modifier). For more information about the
flags refer to the fcntl{2} manual page on your system.</description>

<properties><property kind="parameter" name="flags" required="1"/></properties></element>

<element kind="function" name="dup">
<description>Duplicate the file object and the underlying file pointer and file
descriptor. The resulting object behaves as if it were newly
opened.</description>

</element>

<element kind="function" name="dup2">
<description>Duplicate the file object and the underlying file pointer and file
descriptor. The new object will have the given file descriptor.
Otherwise the resulting object behaves as if it were newly opened.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

<element kind="function" name="file">
<description>Return the standard file object that the posixfile object is based
on. This is sometimes necessary for functions that insist on a
standard file object.</description>

</element>

</group>
<group name="resource --- Resource usage information">
<description>Unix
An interface to provide resource usage information on
the current process.
This module provides basic mechanisms for measuring and controlling
system resources utilized by a program.
Symbolic constants are used to specify particular system resources and
to request usage information about either the current process or its
children.
A single exception is defined for errors:
{error}
The functions described below may raise this error if the underlying
system call failures unexpectedly.
</description>
<group name="Resource Limits">
<description>Resources usage can be limited using the setrlimit() function
described below. Each resource is controlled by a pair of limits: a
soft limit and a hard limit. The soft limit is the current limit, and
may be lowered or raised by a process over time. The soft limit can
never exceed the hard limit. The hard limit can be lowered to any
value greater than the soft limit, but not raised. (Only processes with
the effective UID of the super-user can raise a hard limit.)
The specific resources that can be limited are system dependent. They
are described in the getrlimit{2} man page. The resources
listed below are supported when the underlying operating system
supports them; resources which cannot be checked or controlled by the
operating system are not defined in this module for those platforms.
</description>
<element kind="function" name="getrlimit">
<description>Returns a tuple (soft, hard) with the current
soft and hard limits of resource. Raises ValueError if
an invalid resource is specified, or error if the
underyling system call fails unexpectedly.</description>

<properties><property kind="parameter" name="resourceresource" required="1"/></properties></element>

<element kind="function" name="setrlimit">
<description>Sets new limits of consumption of resource. The limits
argument must be a tuple (soft, hard) of two
integers describing the new limits. A value of -1 can be used to
specify the maximum possible upper limit.
Raises ValueError if an invalid resource is specified,
if the new soft limit exceeds the hard limit, or if a process tries
to raise its hard limit (unless the process has an effective UID of
super-user). Can also raise error if the underyling
system call fails.</description>

<properties><property kind="parameter" name="resource" required="1"/><property kind="parameter" name="limits limits" required="1"/></properties></element>

</group>
<group name="Resource Usage">
<description>These functions are used to retrieve resource usage information:
</description>
<element kind="function" name="getrusage">
<description>This function returns an object that describes the resources
consumed by either the current process or its children, as specified
by the who parameter. The who parameter should be
specified using one of the RUSAGE_* constants described
below.
The fields of the return value each describe how a particular system
resource has been used, e.g. amount of time spent running is user mode
or number of times the process was swapped out of main memory. Some
values are dependent on the clock tick internal, e.g. the amount of
memory the process is using.
For backward compatibility, the return value is also accessible as
a tuple of 16 elements.
The fields ru_utime and ru_stime of the return value
are floating point values representing the amount of time spent
executing in user mode and the amount of time spent executing in system
mode, respectively. The remaining values are integers. Consult the
getrusage{2} man page for detailed information about these
values. A brief summary is presented here:
{r|l|l}{code}{Index}{Field}{Resource}
0{ru_utime}{time in user mode (float)}
1{ru_stime}{time in system mode (float)}
2{ru_maxrss}{maximum resident set size}
3{ru_ixrss}{shared memory size}
4{ru_idrss}{unshared memory size}
5{ru_isrss}{unshared stack size}
6{ru_minflt}{page faults not requiring I/O}
7{ru_majflt}{page faults requiring I/O}
8{ru_nswap}{number of swap outs}
9{ru_inblock}{block input operations}
10{ru_oublock}{block output operations}
11{ru_msgsnd}{messages sent}
12{ru_msgrcv}{messages received}
13{ru_nsignals}{signals received}
14{ru_nvcsw}{voluntary context switches}
15{ru_nivcsw}{involuntary context switches}
This function will raise a ValueError if an invalid
who parameter is specified. It may also raise
error exception in unusual circumstances.
Changed in version 2.3: Added access to values as attributes of the
returned object</description>

<properties><property kind="parameter" name="whowho" required="1"/></properties></element>

<element kind="function" name="getpagesize">
<description>Returns the number of bytes in a system page. (This need not be the
same as the hardware page size.) This function is useful for
determining the number of bytes of memory a process is using. The
third element of the tuple returned by getrusage() describes
memory usage in pages; multiplying by page size produces number of
bytes.</description>

</element>

</group>
</group>
<group name="nis --- Interface to Sun's NIS (Yellow Pages)">
<description>UNIX
Interface to Sun's NIS (Yellow Pages) library.
The nis module gives a thin wrapper around the NIS library, useful
for central administration of several hosts.
Because NIS exists only on systems, this module is
only available for .
The nis module defines the following functions:
</description>
<element kind="function" name="match">
<description>Return the match for key in map mapname, or raise an
error (nis.error) if there is none.
Both should be strings, key is 8-bit clean.
Return value is an arbitrary array of bytes (may contain NULL
and other joys).
Note that mapname is first checked if it is an alias to another
name.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="mapname mapname" required="1"/></properties></element>

<element kind="function" name="cat">
<description>Return a dictionary mapping key to value such that
match(key, mapname)==value.
Note that both keys and values of the dictionary are arbitrary
arrays of bytes.
Note that mapname is first checked if it is an alias to another
name.</description>

<properties><property kind="parameter" name="mapnamemapname" required="1"/></properties></element>

<element kind="function" name="maps">
<description>Return a list of all valid maps.</description>

</element>

</group>
<group name="syslog --- syslog library routines">
<description>Unix
An interface to the library routines.
This module provides an interface to the syslog library
routines. Refer to the manual pages for a detailed description
of the syslog facility.
The module defines the following functions:
</description>
<element kind="function" name="syslog">
<description>Send the string message to the system logger. A trailing
newline is added if necessary. Each message is tagged with a priority
composed of a facility and a level. The optional
priority argument, which defaults to LOG_INFO,
determines the message priority. If the facility is not encoded in
priority using logical-or (LOG_INFO | LOG_USER), the
value given in the openlog() call is used.</description>

<properties><property kind="parameter" name="priority" required="1"/><property kind="parameter" name="message message"/></properties></element>

<element kind="function" name="openlog">
<description>Logging options other than the defaults can be set by explicitly
opening the log file with openlog() prior to calling
syslog(). The defaults are (usually) ident =
'syslog', logopt = 0, facility =
LOG_USER. The ident argument is a string which is
prepended to every message. The optional logopt argument is a
bit field - see below for possible values to combine. The optional
facility argument sets the default facility for messages which
do not have a facility explicitly encoded.</description>

<properties><property kind="parameter" name="ident" required="1"/><property kind="parameter" name="logopt"/><property kind="parameter" name="facility"/></properties></element>

<element kind="function" name="closelog">
<description>Close the log file.</description>

</element>

<element kind="function" name="setlogmask">
<description>Set the priority mask to maskpri and return the
previous mask value. Calls to syslog() with a priority
level not set in maskpri are ignored. The default is to log all
priorities. The function LOG_MASK(pri) calculates the
mask for the individual priority pri. The function
LOG_UPTO(pri) calculates the mask for all priorities up
to and including pri.</description>

<properties><property kind="parameter" name="maskprimaskpri" required="1"/></properties></element>

</group>
<group name="commands --- Utilities for running commands">
<description>Unix
Utility functions for running external commands.
The commands module contains wrapper functions for
os.popen() which take a system command as a string and
return any output generated by the command and, optionally, the exit
status.
The commands module defines the following functions:
</description>
<element kind="function" name="getstatusoutput">
<description>Execute the string cmd in a shell with os.popen() and
return a 2-tuple (status, output). cmd is
actually run as { cmd ; } 2&gt;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().</description>

<properties><property kind="parameter" name="cmdcmd" required="1"/></properties></element>

<element kind="function" name="getoutput">
<description>Like getstatusoutput(), except the exit status is ignored
and the return value is a string containing the command's output.</description>

<properties><property kind="parameter" name="cmdcmd" required="1"/></properties></element>

<element kind="function" name="getstatus">
<description>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.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

</group>
</group>
<group name="The Python Debugger">
<group name="Debugger Commands">
</group>
</group>
<group name="The Python Profiler">
<group name="Introduction to the profiler">
<description>Profiler Introduction
A profiler is a program that describes the run time performance
of a program, providing a variety of statistics. This documentation
describes the profiler functionality provided in the modules
profile and pstats. This profiler provides
deterministic profiling of any Python programs. It also
provides a series of report generation tools to allow users to rapidly
examine the results of a profile operation.
</description>
<element kind="function" name="run">
<description>This function takes a single argument that has can be passed to the
exec statement, and an optional file name. In all cases this
routine attempts to exec its first argument, and gather profiling
statistics from the execution. If no file name is present, then this
function automatically prints a simple profiling report, sorted by the
standard name string (file/line/function-name) that is presented in
each line. The following is a typical output from such a call:
main()
2706 function calls (2004 primitive calls) in 4.504 CPU seconds
Ordered by: standard name
ncalls tottime percall cumtime percall filename:lineno(function)
2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
...
The first line indicates that this profile was generated by the call:
profile.run('main()'), and hence the exec'ed string is
'main()'. The second line indicates that 2706 calls were
monitored. Of those calls, 2004 were primitive. We define
primitive to mean that the call was not induced via recursion.
The next line: Ordered by: name, indicates that
the text string in the far right column was used to sort the output.
The column headings include:
[ncalls ]
for the number of calls,
[tottime ]
for the total time spent in the given function (and excluding time
made in calls to sub-functions),
[percall ]
is the quotient of tottime divided by ncalls
[cumtime ]
is the total time spent in this and all subfunctions (from invocation
till exit). This figure is accurate even for recursive
functions.
[percall ]
is the quotient of cumtime divided by primitive calls
[filename:lineno(function) ]
provides the respective data of each function
When there are two numbers in the first column (for example,
43/3), then the latter is the number of primitive calls, and
the former is the actual number of calls. Note that when the function
does not recurse, these two values are the same, and only the single
figure is printed.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="filename"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="Stats">
<description>This class constructor creates an instance of a ``statistics object''
from a filename (or set of filenames). Stats objects are
manipulated by methods, in order to print useful reports.
The file selected by the above constructor must have been created by
the corresponding version of profile. To be specific, there is
no file compatibility guaranteed with future versions of this
profiler, and there is no compatibility with files produced by other
profilers (such as the old system profiler).
If several files are provided, all the statistics for identical
functions will be coalesced, so that an overall view of several
processes can be considered in a single report. If additional files
need to be combined with data in an existing Stats object, the
add() method can be used.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="..."/></properties></element>

<group name="The Stats Class">
<description>Stats objects have the following methods:
</description>
<element kind="function" name="strip_dirs">
<description>This method for the Stats class removes all leading path
information from file names. It is very useful in reducing the size
of the printout to fit within (close to) 80 columns. This method
modifies the object, and the stripped information is lost. After
performing a strip operation, the object is considered to have its
entries in a ``random'' order, as it was just after object
initialization and loading. If strip_dirs() causes two
function names to be indistinguishable (they are on the same
line of the same filename, and have the same function name), then the
statistics for these two entries are accumulated into a single entry.</description>

</element>

<element kind="function" name="add">
<description>This method of the Stats class accumulates additional
profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding
version of profile.run(). Statistics for identically named
(re: file, line, name) functions are automatically accumulated into
single function statistics.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="dump_stats">
<description>Save the data loaded into the Stats object to a file named
filename. The file is created if it does not exist, and is
overwritten if it already exists. This is equivalent to the method of
the same name on the profile.Profile class.
New in version 2.3</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="sort_stats">
<description>This method modifies the Stats object by sorting it according
to the supplied criteria. The argument is typically a string
identifying the basis of a sort (example: 'time' or
'name').
When more than one key is provided, then additional keys are used as
secondary criteria when there is equality in all keys selected
before them. For example, sort_stats('name', 'file') will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous. The following are the keys currently
defined:
{l|l}{code}{Valid Arg}{Meaning}
'calls'{call count}
'cumulative'{cumulative time}
'file'{file name}
'module'{file name}
'pcalls'{primitive call count}
'line'{line number}
'name'{function name}
'nfl'{name/file/line}
'stdname'{standard name}
'time'{internal time}
Note that all sorts on statistics are in descending order (placing
most time consuming items first), where as name, file, and line number
searches are in ascending order (alphabetical). The subtle
distinction between 'nfl' and 'stdname' is that the
standard name is a sort of the name as printed, which means that the
embedded line numbers get compared in an odd way. For example, lines
3, 20, and 40 would (if the file names were the same) appear in the
string order 20, 3 and 40. In contrast, 'nfl' does a numeric
compare of the line numbers. In fact, sort_stats('nfl') is the
same as sort_stats('name', 'file', 'line').
For compatibility with the old profiler, the numeric arguments
-1, 0, 1, and 2 are permitted. They are
interpreted as 'stdname', 'calls', 'time', and
'cumulative' respectively. If this old style format (numeric)
is used, only one sort key (the numeric key) will be used, and
additional arguments will be silently ignored.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="reverse_order">
<description>This method for the Stats class reverses the ordering of the basic
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on
the sort key of choice.</description>

</element>

<element kind="function" name="print_stats">
<description>This method for the Stats class prints out a report as described
in the profile.run() definition.
The order of the printing is based on the last sort_stats()
operation done on the object (subject to caveats in add() and
strip_dirs()).
The arguments provided (if any) can be used to limit the list down to
the significant entries. Initially, the list is taken to be the
complete set of profiled functions. Each restriction is either an
integer (to select a count of lines), or a decimal fraction between
0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
expression (to pattern match the standard name that is printed; as of
Python 1.5b1, this uses the Perl-style regular expression syntax
defined by the re module). If several restrictions are
provided, then they are applied sequentially. For example:
print_stats(.1, 'foo:')
would first limit the printing to first 10% of list, and then only
print functions that were part of filename .*foo:. In
contrast, the command:
print_stats('foo:', .1)
would limit the list to all functions having file names .*foo:,
and then proceed to only print the first 10% of them.</description>

<properties><property kind="parameter" name="restriction" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="print_callers">
<description>This method for the Stats class prints a list of all functions
that called each function in the profiled database. The ordering is
identical to that provided by print_stats(), and the definition
of the restricting argument is also identical. For convenience, a
number is shown in parentheses after each caller to show how many
times this specific call was made. A second non-parenthesized number
is the cumulative time spent in the function at the right.</description>

<properties><property kind="parameter" name="restriction" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="print_callees">
<description>This method for the Stats class prints a list of all function
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the print_callers() method.</description>

<properties><property kind="parameter" name="restriction" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="ignore">
<description>1.5.1{This is not needed in modern versions of
Python.
This was once necessary, when Python would print any unused expression
result that was not None. The method is still defined for
backward compatibility.}</description>

</element>

</group>
</group>
<group name="hotshot --- High performance logging profiler">
<description>High performance logging profiler, mostly written in C.
New in version 2.2
This module provides a nicer interface to the _hotshot C module.
Hotshot is a replacement for the existing profile module. As it's
written mostly in C, it should result in a much smaller performance impact
than the existing profile module.
</description>
<element kind="function" name="Profile">
<description>The profiler object. The argument logfile is the name of a log
file to use for logged profile data. The argument lineevents
specifies whether to generate events for every source line, or just on
function call/return. It defaults to 0 (only log function
call/return). The argument linetimings specifies whether to
record timing information. It defaults to 1 (store timing
information).</description>

<properties><property kind="parameter" name="logfile" required="1"/><property default="0" kind="parameter" name="lineevents"/><property default="1" kind="parameter" name="linetimings"/></properties></element>

<group name="Profile Objects">
<description>Profile objects have the following methods:
</description>
<element kind="function" name="addinfo">
<description>Add an arbitrary labelled value to the profile output.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="close">
<description>Close the logfile and terminate the profiler.</description>

</element>

<element kind="function" name="fileno">
<description>Return the file descriptor of the profiler's log file.</description>

</element>

<element kind="function" name="run">
<description>Profile an exec-compatible string in the script environment.
The globals from the __main__ module are used as
both the globals and locals for the script.</description>

<properties><property kind="parameter" name="cmdcmd" required="1"/></properties></element>

<element kind="function" name="runcall">
<description>Profile a single call of a callable.
Additional positional and keyword arguments may be passed
along; the result of the call is returned, and exceptions are
allowed to propogate cleanly, while ensuring that profiling is
disabled on the way out.</description>

<properties><property kind="parameter" name="func" required="1"/><property kind="parameter" name="*args" required="1"/><property kind="parameter" name="**keywords **keywords" required="1"/></properties></element>

<element kind="function" name="runctx">
<description>Evaluate an exec-compatible string in a specific environment.
The string is compiled before profiling begins.</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="globals" required="1"/><property kind="parameter" name="locals locals" required="1"/></properties></element>

<element kind="function" name="start">
<description>Start the profiler.</description>

</element>

<element kind="function" name="stop">
<description>Stop the profiler.</description>

</element>

</group>
<group name="Using hotshot data">
<description>Statistical analysis for Hotshot
New in version 2.2
This module loads hotshot profiling data into the standard pstats
Stats objects.
</description>
<element kind="function" name="load">
<description>Load hotshot data from filename. Returns an instance
of the pstats.Stats class.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

</group>
<group name="Example Usage">
</group>
</group>
<group name="timeit --- Measure execution time of small code snippets">
<description>Measure the execution time of small code snippets.
New in version 2.3
</description>
<element kind="function" name="Timer">
<description>Class for timing execution speed of small code snippets.
The constructor takes a statement to be timed, an additional statement
used for setup, and a timer function. Both statements default to
'pass'; the timer function is platform-dependent (see the
module doc string). The statements may contain newlines, as long as
they don't contain multi-line string literals.
To measure the execution time of the first statement, use the
timeit() method. The repeat() method is a
convenience to call timeit() multiple times and return a list
of results.</description>

<properties><property default="'pass'" kind="parameter" name="stmt" required="1"/><property default="'pass'" kind="parameter" name="setup"/><property default="&lt;timer function&gt;" kind="parameter" name="timer"/></properties></element>

<element kind="function" name="print_exc">
<description>Helper to print a traceback from the timed code.
Typical use:
t = Timer(...) # outside the try/except
try:
t.timeit(...) # or t.repeat(...)
except:
t.print_exc()
The advantage over the standard traceback is that source lines in the
compiled template will be displayed.
The optional file argument directs where the traceback is sent;
it defaults to sys.stderr.</description>

<properties><property default="None" kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="repeat">
<description>Call timeit() a few times.
This is a convenience function that calls the timeit()
repeatedly, returning a list of results. The first argument specifies
how many times to call timeit(). The second argument
specifies the number argument for timeit().
It's tempting to calculate mean and standard deviation from the result
vector and report these. However, this is not very useful. In a typical
case, the lowest value gives a lower bound for how fast your machine can run
the given code snippet; higher values in the result vector are typically not
caused by variability in Python's speed, but by other processes interfering
with your timing accuracy. So the min() of the result is
probably the only number you should be interested in. After that, you
should look at the entire vector and apply common sense rather than
statistics.
</description>

<properties><property default="3" kind="parameter" name="repeat" required="1"/><property default="1000000" kind="parameter" name="number"/></properties></element>

<element kind="function" name="timeit">
<description>Time number executions of the main statement.
This executes the setup statement once, and then
returns the time it takes to execute the main statement a number of
times, measured in seconds as a float. The argument is the number of
times through the loop, defaulting to one million. The main
statement, the setup statement and the timer function to be used are
passed to the constructor.</description>

<properties><property default="1000000" kind="parameter" name="number" required="1"/></properties></element>

<group name="Command Line Interface">
<description>When called as a program from the command line, the following form is used:
python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
where the following options are understood:
[-n N/number=N] how many times to execute 'statement'
[-r N/repeat=N] how many times to repeat the timer (default 3)
[-s S/setup=S] statement to be executed once initially (default
'pass')
[-t/time] use time.time()
(default on all platforms but Windows)
[-c/clock] use time.clock() (default on Windows)
[-v/verbose] print raw timing results; repeat for more digits
precision
[-h/help] print a short usage message and exit
A multi-line statement may be given by specifying each line as a
separate statement argument; indented lines are possible by enclosing
an argument in quotes and using leading spaces. Multiple
-s options are treated similarly.
If -n is not given, a suitable number of loops is
calculated by trying successive powers of 10 until the total time is
at least 0.2 seconds.
The default timer function is platform dependent. On Windows,
time.clock() has microsecond granularity but
time.time()'s granularity is 1/60th of a second; on ,
time.clock() has 1/100th of a second granularity and
time.time() is much more precise. On either platform, the
default timer functions measure wall clock time, not the CPU time.
This means that other processes running on the same computer may
interfere with the timing. The best thing to do when accurate timing
is necessary is to repeat the timing a few times and use the best
time. The -r option is good for this; the default of 3
repetitions is probably enough in most cases. On , you can use
time.clock() to measure CPU time.
There is a certain baseline overhead associated with executing a
pass statement. The code here doesn't try to hide it, but you
should be aware of it. The baseline overhead can be measured by
invoking the program without arguments.
The baseline overhead differs between Python versions! Also, to
fairly compare older Python versions to Python 2.3, you may want to
use Python's -O option for the older versions to avoid
timing SET_LINENO instructions.
</description>
</group>
<group name="Examples">
</group>
</group>
</group>
<group name="Internet Protocols and Support">
<group name="webbrowser --- Convenient Web-browser controller">
<description>Easy-to-use controller for Web browsers.
The webbrowser module provides a very high-level interface to
allow displaying Web-based documents to users. The controller objects
are easy to use and are platform-independent. Under most
circumstances, simply calling the open() function from this
module will do the right thing.
Under , graphical browsers are preferred under X11, but text-mode
browsers will be used if graphical browsers are not available or an X11
display isn't available. If text-mode browsers are used, the calling
process will block until the user exits the browser.
Under , if the environment variable BROWSER exists, it
is interpreted to override the platform default list of browsers, as a
colon-separated list of browsers to try in order. When the value of
a list part contains the string , then it is interpreted as
a literal browser command line to be used with the argument URL
substituted for the ; if the part does not contain
, it is simply interpreted as the name of the browser to
launch.
For non- platforms, or when X11 browsers are available on
, the controlling process will not wait for the user to finish
with the browser, but allow the browser to maintain its own window on
the display.
The following exception is defined:
{Error}
Exception raised when a browser control error occurs.
The following functions are defined:
</description>
<element kind="function" name="open">
<description>Display url using the default browser. If new is true,
a new browser window is opened if possible. If autoraise is
true, the window is raised if possible (note that under many window
managers this will occur regardless of the setting of this variable).</description>

<properties><property kind="parameter" name="url" required="1"/><property default="0" kind="parameter" name="new"/><property default="1" kind="parameter" name="autoraise"/></properties></element>

<element kind="function" name="open_new">
<description>Open url in a new window of the default browser, if possible,
otherwise, open url in the only browser window.</description>

<properties><property kind="parameter" name="urlurl" required="1"/></properties></element>

<element kind="function" name="get">
<description>Return a controller object for the browser type name. If
name is empty, return a controller for a default browser
appropriate to the caller's environment.</description>

<properties><property kind="parameter" name="name" required="1"/></properties></element>

<element kind="function" name="register">
<description>Register the browser type name. Once a browser type is
registered, the get() function can return a controller
for that browser type. If instance is not provided, or is
None, constructor will be called without parameters to
create an instance when needed. If instance is provided,
constructor will never be called, and may be None.
This entry point is only useful if you plan to either set the
BROWSER variable or call get with a nonempty
argument matching the name of a handler you declare.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="constructor" required="1"/><property kind="parameter" name="instance"/></properties></element>

<group name="Browser Controller Objects">
<description>Browser controllers provide two methods which parallel two of the
module-level convenience functions:
</description>
<element kind="function" name="open">
<description>Display url using the browser handled by this controller. If
new is true, a new browser window is opened if possible.</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="new"/></properties></element>

<element kind="function" name="open_new">
<description>Open url in a new window of the browser handled by this
controller, if possible, otherwise, open url in the only
browser window.</description>

<properties><property kind="parameter" name="urlurl" required="1"/></properties></element>

</group>
</group>
<group name="cgi --- Common Gateway Interface support.">
<description>Common Gateway Interface support, used to interpret
forms in server-side scripts.
</description>
<group name="Introduction">
<description>cgi-intro
A CGI script is invoked by an HTTP server, usually to process user
input submitted through an HTML &lt;FORM&gt; or &lt;ISINDEX&gt; element.
Most often, CGI scripts live in the server's special cgi-bin
directory. The HTTP server places all sorts of information about the
request (such as the client's hostname, the requested URL, the query
string, and lots of other goodies) in the script's shell environment,
executes the script, and sends the script's output back to the client.
The script's input is connected to the client too, and sometimes the
form data is read this way; at other times the form data is passed via
the ``query string'' part of the URL. This module is intended
to take care of the different cases and provide a simpler interface to
the Python script. It also provides a number of utilities that help
in debugging scripts, and the latest addition is support for file
uploads from a form (if your browser supports it --- Grail 0.3 and
Netscape 2.0 do).
The output of a CGI script should consist of two sections, separated
by a blank line. The first section contains a number of headers,
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
print &quot;Content-Type: text/html&quot; # 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 &quot;&lt;TITLE&gt;CGI script output&lt;/TITLE&gt;&quot;
print &quot;&lt;H1&gt;This is my first CGI script&lt;/H1&gt;&quot;
print &quot;Hello, world!&quot;
</description>
</group>
<group name="Using the cgi module">
<description>Using the cgi module
Begin by writing import cgi. Do not use from cgi import
* --- the module defines all sorts of names for its own use or for
backward compatibility that you don't want in your namespace.
When you write a new script, consider adding the line:
import cgitb; cgitb.enable()
This activates a special exception handler that will display detailed
reports in the Web browser if any errors occur. If you'd rather not
show the guts of your program to users of your script, you can have
the reports saved to files instead, with a line like this:
import cgitb; cgitb.enable(display=0, logdir=&quot;/tmp&quot;)
It's very helpful to use this feature during script development.
The reports produced by cgitb provide information that
can save you a lot of time in tracking down bugs. You can always
remove the cgitb line later when you have tested your script
and are confident that it works correctly.
To get at submitted form data,
it's best to use the FieldStorage class. The other classes
defined in this module are provided mostly for backward compatibility.
Instantiate it exactly once, without arguments. This reads the form
contents from standard input or the environment (depending on the
value of various environment variables set according to the CGI
standard). Since it may consume standard input, it should be
instantiated only once.
The FieldStorage instance can be indexed like a Python
dictionary, and also supports the standard dictionary methods
has_key() and keys(). The built-in len()
is also supported. Form fields containing empty strings are ignored
and do not appear in the dictionary; to keep such values, provide
a true value for the optional keep_blank_values keyword
parameter when creating the FieldStorage instance.
For instance, the following code (which assumes that the Content-Type header and blank line have already been
printed) checks that the fields name and addr are both
set to a non-empty string:
form = cgi.FieldStorage()
if not (form.has_key(&quot;name&quot;) and form.has_key(&quot;addr&quot;)):
print &quot;&lt;H1&gt;Error&lt;/H1&gt;&quot;
print &quot;Please fill in the name and addr fields.&quot;
return
print &quot;&lt;p&gt;name:&quot;, form[&quot;name&quot;].value
print &quot;&lt;p&gt;addr:&quot;, form[&quot;addr&quot;].value
...further form processing here...
Here the fields, accessed through form[key], are
themselves instances of FieldStorage (or
MiniFieldStorage, depending on the form encoding).
The value attribute of the instance yields the string value
of the field. The getvalue() method returns this string value
directly; it also accepts an optional second argument as a default to
return if the requested key is not present.
If the submitted form data contains more than one field with the same
name, the object retrieved by form[key] is not a
FieldStorage or MiniFieldStorage
instance but a list of such instances. Similarly, in this situation,
form.getvalue(key) would return a list of strings.
If you expect this possibility
(when your HTML form contains multiple fields with the same name), use
the isinstance() built-in function to determine whether you
have a single instance or a list of instances. For example, this
code concatenates any number of username fields, separated by
commas:
value = form.getvalue(&quot;username&quot;, &quot;&quot;)
if isinstance(value, list):
# Multiple username fields specified
usernames = &quot;,&quot;.join(value)
else:
# Single or no username field specified
usernames = value
If a field represents an uploaded file, accessing the value via the
value attribute or the getvalue() method reads the
entire file in memory as a string. This may not be what you want.
You can test for an uploaded file by testing either the filename
attribute or the file attribute. You can then read the data at
leisure from the file attribute:
fileitem = form[&quot;userfile&quot;]
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 be
multipart/form-data (or perhaps another MIME type matching
multipart/*). In this case, it can be iterated over
recursively just like the top-level form object.
When a form is submitted in the ``old'' format (as the query string or
as a single data part of type
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.
</description>
</group>
<group name="Higher Level Interface">
<description>New in version 2.2 % XXX: Is this true ? The previous section explains how to read CGI form data using the
FieldStorage class. This section describes a higher level
interface which was added to this class to allow one to do it in a
more readable and intuitive way. The interface doesn't make the
techniques described in previous sections obsolete --- they are still
useful to process file uploads efficiently, for example.
The interface consists of two simple methods. Using the methods
you can process form data in a generic way, without the need to worry
whether only one or more values were posted under one name.
In the previous section, you learned to write following code anytime
you expected a user to post more than one value under one name:
item = form.getvalue(&quot;item&quot;)
if isinstance(item, list):
# The user is requesting more than one item.
else:
# The user is requesting only one item.
This situation is common for example when a form contains a group of
multiple checkboxes with the same name:
&lt;input type=&quot;checkbox&quot; name=&quot;item&quot; value=&quot;1&quot; /&gt;
&lt;input type=&quot;checkbox&quot; name=&quot;item&quot; value=&quot;2&quot; /&gt;
In most situations, however, there's only one form control with a
particular name in a form and then you expect and need only one value
associated with this name. So you write a script containing for
example this code:
user = form.getvalue(&quot;user&quot;).toupper()
The problem with the code is that you should never expect that a
client will provide valid input to your scripts. For example, if a
curious user appends another user=foo pair to the query string,
then the script would crash, because in this situation the
getvalue(&quot;user&quot;) method call returns a list instead of a
string. Calling the toupper() method on a list is not valid
(since lists do not have a method of this name) and results in an
AttributeError exception.
Therefore, the appropriate way to read form data values was to always
use the code which checks whether the obtained value is a single value
or a list of values. That's annoying and leads to less readable
scripts.
A more convenient approach is to use the methods getfirst()
and getlist() provided by this higher level interface.
</description>
<element kind="function" name="getfirst">
<description>Thin method always returns only one value associated with form field
name. The method returns only the first value in case that
more values were posted under such name. Please note that the order
in which the values are received may vary from browser to browser
and should not be counted on.Note that some recent
versions of the HTML specification do state what order the
field values should be supplied in, but knowing whether a
request was received from a conforming browser, or even from a
browser at all, is tedious and error-prone. If no such form
field or value exists then the method returns the value specified by
the optional parameter default. This parameter defaults to
None if not specified.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="getlist">
<description>This method always returns a list of values associated with form
field name. The method returns an empty list if no such form
field or value exists for name. It returns a list consisting
of one item if only one such value exists.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
<group name="Old classes">
<description>These classes, present in earlier versions of the cgi module,
are still supported for backward compatibility. New applications
should use the FieldStorage class.
SvFormContentDict stores single value form content as
dictionary; it assumes each field name occurs in the form only once.
FormContentDict stores multiple value form content as a
dictionary (the form items are lists of values). Useful if your form
contains multiple fields with the same name.
Other classes (FormContent, InterpFormContentDict) are
present for backwards compatibility with really old applications only.
If you still use these and would be inconvenienced when they
disappeared from a next version of this module, drop me a note.
</description>
</group>
<group name="Functions">
<description>Functions in cgi module
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.
</description>
<element kind="function" name="parse">
<description>Parse a query in the environment or from a file (the file defaults
to sys.stdin). The keep_blank_values and
strict_parsing parameters are passed to parse_qs()
unchanged.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="keep_blank_values"/><property kind="parameter" name="strict_parsing"/></properties></element>

<element kind="function" name="parse_qs">
<description>Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are
returned as a dictionary. The dictionary keys are the unique query
variable names and the values are lists of values for each name.
The optional argument keep_blank_values is
a flag indicating whether blank values in
URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that
blank values are to be ignored and treated as if they were
not included.
The optional argument strict_parsing is a flag indicating what
to do with parsing errors. If false (the default), errors
are silently ignored. If true, errors raise a ValueError
exception.
Use the urllib.urlencode() function to convert
such dictionaries into query strings.</description>

<properties><property kind="parameter" name="qs" required="1"/><property kind="parameter" name="keep_blank_values"/><property kind="parameter" name="strict_parsing"/></properties></element>

<element kind="function" name="parse_qsl">
<description>Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are
returned as a list of name, value pairs.
The optional argument keep_blank_values is
a flag indicating whether blank values in
URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that
blank values are to be ignored and treated as if they were
not included.
The optional argument strict_parsing is a flag indicating what
to do with parsing errors. If false (the default), errors
are silently ignored. If true, errors raise a ValueError
exception.
Use the urllib.urlencode() function to convert
such lists of pairs into query strings.</description>

<properties><property kind="parameter" name="qs" required="1"/><property kind="parameter" name="keep_blank_values"/><property kind="parameter" name="strict_parsing"/></properties></element>

<element kind="function" name="parse_multipart">
<description>Parse input of type multipart/form-data (for file uploads). Arguments are fp for the input file and
pdict for a dictionary containing other parameters in
the Content-Type header.
Returns a dictionary just like parse_qs() keys are the
field names, each value is a list of values for that field. This is
easy to use but not much good if you are expecting megabytes to be
uploaded --- in that case, use the FieldStorage class instead
which is much more flexible.
Note that this does not parse nested multipart parts --- use
FieldStorage for that.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="pdict pdict" required="1"/></properties></element>

<element kind="function" name="parse_header">
<description>Parse a MIME header (such as Content-Type) into a main
value and a dictionary of parameters.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="test">
<description>Robust test CGI script, usable as main program.
Writes minimal HTTP headers and formats all information provided to
the script in HTML form.</description>

</element>

<element kind="function" name="print_environ">
<description>Format the shell environment in HTML.</description>

</element>

<element kind="function" name="print_form">
<description>Format a form in HTML.</description>

<properties><property kind="parameter" name="formform" required="1"/></properties></element>

<element kind="function" name="print_directory">
<description>Format the current directory in HTML.</description>

</element>

<element kind="function" name="print_environ_usage">
<description>Print a list of useful (used by CGI) environment variables in
HTML.</description>

</element>

<element kind="function" name="escape">
<description>Convert the characters
&amp;, &lt; and &gt; 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 (&quot;) is also translated;
this helps for inclusion in an HTML attribute value, as in &lt;A
HREF=&quot;...&quot;&gt;. If the value to be quoted might include single- or
double-quote characters, or both, consider using the
quoteattr() function in the xml.sax.saxutils
module instead.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="quote"/></properties></element>

</group>
<group name="Caring about security">
<description>There's one important rule: if you invoke an external program (via the
os.system() or os.popen() functions. or others
with similar functionality), 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.
</description>
</group>
<group name="Installing your CGI script on a">
<description>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
file mode should be 0755 octal (use chmod 0755
filename). Make sure that the first line of the script contains
! starting in column 1 followed by the pathname of the Python
interpreter, for instance:
#!/usr/local/bin/python
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
readable or writable, respectively, by ``others'' --- their mode
should be 0644 for readable and 0666 for writable. This
is because, for security reasons, the HTTP server executes your script
as user ``nobody'', without any special privileges. It can only read
(write, execute) files that everybody can read (write, execute). The
current directory at execution time is also different (it is usually
the server's cgi-bin directory) and the set of environment variables
is also different from what you get when you log in. 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. For example:
import sys
sys.path.insert(0, &quot;/usr/home/joe/lib/python&quot;)
sys.path.insert(0, &quot;/usr/local/lib/python&quot;)
(This way, the directory inserted last will be searched first!)
Instructions for non- systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).
</description>
</group>
<group name="Testing your CGI script">
<description>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.
</description>
</group>
<group name="Debugging CGI scripts">
<description>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&amp;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, 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 (for
whatever reason: 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 files, or be discarded altogether.
Fortunately, once you have managed to get your script to execute
some code, you can easily send tracebacks to the Web browser
using the cgitb module. If you haven't done so already,
just add the line:
import cgitb; cgitb.enable()
to the top of your script. Then try running it again; when a
problem occurs, you should see a detailed report that will
likely make apparent the cause of the crash.
If you suspect that there may be a problem in importing the
cgitb module, you can use an even more robust approach
(which only uses built-in modules):
import sys
sys.stderr = sys.stdout
print &quot;Content-Type: text/plain&quot;
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 be
readable.
</description>
</group>
<group name="Common problems and solutions">
</group>
</group>
<group name="cgitb --- Traceback manager for CGI scripts">
<description>Configurable traceback handler for CGI scripts.
New in version 2.2
</description>
<element kind="function" name="enable">
<description>This function causes the cgitb module to take over the
interpreter's default handling for exceptions by setting the
value of sys.excepthook.
(in module sys){excepthook()}
The optional argument display defaults to 1 and can be set
to 0 to suppress sending the traceback to the browser.
If the argument logdir is present, the traceback reports are
written to files. The value of logdir should be a directory
where these files will be placed.
The optional argument context is the number of lines of
context to display around the current line of source code in the
traceback; this defaults to 5.
If the optional argument format is &quot;html&quot;, the output is
formatted as HTML. Any other value forces plain text output. The default
value is &quot;html&quot;.</description>

<properties><property kind="parameter" name="display" required="1"/><property kind="parameter" name="logdir"/><property kind="parameter" name="context"/><property kind="parameter" name="format"/></properties></element>

<element kind="function" name="handler">
<description>This function handles an exception using the default settings
(that is, show a report in the browser, but don't log to a file).
This can be used when you've caught an exception and want to
report it using cgitb. The optional info argument
should be a 3-tuple containing an exception type, exception
value, and traceback object, exactly like the tuple returned by
sys.exc_info(). If the info argument
is not supplied, the current exception is obtained from
sys.exc_info().</description>

<properties><property kind="parameter" name="info" required="1"/></properties></element>

</group>
<group name="urllib --- Open arbitrary resources by URL">
<description>Open an arbitrary network resource by URL (requires sockets).
</description>
<element kind="function" name="urlopen">
<description>Open a network object denoted by a URL for reading. If the URL does
not have a scheme identifier, or if it has file: as its scheme
identifier, this opens a local file (without universal newlines);
otherwise it opens a socket to a server somewhere on the network. If
the connection cannot be made, or if the server returns an error code,
the IOError exception is raised. If all went well, a
file-like object is returned. This supports the following methods:
read(), readline(), readlines(), fileno(),
close(), info() and geturl(). It also has
proper support for the iterator protocol.
Except for the info() and geturl() methods,
these methods have the same interface as for
file objects --- see section bltin-file-objects in this
manual. (It is not a built-in file object, however, so it can't be
used at those few places where a true built-in file object is
required.)
The info() method returns an instance of the class
mimetools.Message containing meta-information associated
with the URL. When the method is HTTP, these headers are those
returned by the server at the head of the retrieved HTML page
(including Content-Length and Content-Type). When the method is FTP,
a Content-Length header will be present if (as is now usual) the
server passed back a file length in response to the FTP retrieval
request. A Content-Type header will be present if the MIME type can
be guessed. When the method is local-file, returned headers will include
a Date representing the file's last-modified time, a Content-Length
giving file size, and a Content-Type containing a guess at the file's
type. See also the description of the
mimetoolsmimetools module.
The geturl() method returns the real URL of the page. In
some cases, the HTTP server redirects a client to another URL. The
urlopen() function handles this transparently, but in some
cases the caller needs to know which URL the client was redirected
to. The geturl() method can be used to get at this
redirected URL.
If the url uses the http: scheme identifier, the optional
data argument may be given to specify a POST request
(normally the request type is GET). The data argument
must be in standard application/x-www-form-urlencoded format;
see the urlencode() function below.
The urlopen() function works transparently with proxies
which do not require authentication. In a or Windows
environment, set the http_proxy, ftp_proxy or
gopher_proxy environment variables to a URL that identifies
the proxy server before starting the Python interpreter. For example
(the % is the command prompt):
% http_proxy=&quot;http://www.someproxy.com:3128&quot;
% export http_proxy
% python
...
In a Windows environment, if no proxy environment variables are set,
proxy settings are obtained from the registry's Internet Settings
section.
In a Macintosh environment, urlopen() will retrieve proxy
information from Internet</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="data"/><property kind="parameter" name="proxies"/></properties></element>

<element kind="function" name="urlretrieve">
<description>Copy a network object denoted by a URL to a local file, if necessary.
If the URL points to a local file, or a valid cached copy of the
object exists, the object is not copied. Return a tuple
(filename, headers) where filename is the
local file name under which the object can be found, and headers
is whatever the info() method of the object returned by
urlopen() returned (for a remote object, possibly cached).
Exceptions are the same as for urlopen().
The second argument, if present, specifies the file location to copy
to (if absent, the location will be a tempfile with a generated name).
The third argument, if present, is a hook function that will be called
once on establishment of the network connection and once after each
block read thereafter. The hook will be passed three arguments; a
count of blocks transferred so far, a block size in bytes, and the
total size of the file. The third argument may be -1 on older
FTP servers which do not return a file size in response to a retrieval
request.
If the url uses the http: scheme identifier, the optional
data argument may be given to specify a POST request
(normally the request type is GET). The data argument
must in standard application/x-www-form-urlencoded format;
see the urlencode() function below.</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="filename"/><property kind="parameter" name="reporthook"/><property kind="parameter" name="data"/></properties></element>

<element kind="function" name="urlcleanup">
<description>Clear the cache that may have been built up by previous calls to
urlretrieve().</description>

</element>

<element kind="function" name="quote">
<description>Replace special characters in string using the escape.
Letters, digits, and the characters _.- are never quoted.
The optional safe parameter specifies additional characters
that should not be quoted --- its default value is '/'.
Example: quote('//') yields '/%7econnolly/'.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="safe"/></properties></element>

<element kind="function" name="quote_plus">
<description>Like quote(), but also replaces spaces by plus signs, as
required for quoting HTML form values. Plus signs in the original
string are escaped unless they are included in safe. It also
does not have safe default to '/'.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="safe"/></properties></element>

<element kind="function" name="unquote">
<description>Replace escapes by their single-character equivalent.
Example: unquote('/%7Econnolly/') yields '//'.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="unquote_plus">
<description>Like unquote(), but also replaces plus signs by spaces, as
required for unquoting HTML form values.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="urlencode">
<description>Convert a mapping object or a sequence of two-element tuples to a
``url-encoded'' string, suitable to pass to
urlopen() above as the optional data argument. This
is useful to pass a dictionary of form fields to a POST
request. The resulting string is a series of
key=value pairs separated by &amp;
characters, where both key and value are quoted using
quote_plus() above. If the optional parameter doseq is
present and evaluates to true, individual key=value pairs
are generated for each element of the sequence.
When a sequence of two-element tuples is used as the query argument,
the first element of each tuple is a key and the second is a value. The
order of parameters in the encoded string will match the order of parameter
tuples in the sequence.
The cgi module provides the functions
parse_qs() and parse_qsl() which are used to
parse query strings into Python data structures.</description>

<properties><property kind="parameter" name="query" required="1"/><property kind="parameter" name="doseq"/></properties></element>

<element kind="function" name="pathname2url">
<description>Convert the pathname path from the local syntax for a path to
the form used in the path component of a URL. This does not produce a
complete URL. The return value will already be quoted using the
quote() function.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="url2pathname">
<description>Convert the path component path from an encoded URL to the local
syntax for a path. This does not accept a complete URL. This
function uses unquote() to decode path.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="URLopener">
<description>Base class for opening and reading URLs. Unless you need to support
opening objects using schemes other than http:, ftp:,
gopher: or file:, you probably want to use
FancyURLopener.
By default, the URLopener class sends a
User-Agent header of urllib/VVV, where
VVV is the urllib version number. Applications can
define their own User-Agent header by subclassing
URLopener or FancyURLopener and setting the instance
attribute version to an appropriate string value before the
open() method is called.
The optional proxies parameter should be a dictionary mapping
scheme names to proxy URLs, where an empty dictionary turns proxies
off completely. Its default value is None, in which case
environmental proxy settings will be used if present, as discussed in
the definition of urlopen(), above.
Additional keyword parameters, collected in x509, are used for
authentication with the https: scheme. The keywords
key_file and cert_file are supported; both are needed to
actually retrieve a resource at an https: URL.</description>

<properties><property kind="parameter" name="proxies" required="1"/><property kind="parameter" name="**x509"/></properties></element>

<element kind="function" name="FancyURLopener">
<description>FancyURLopener subclasses URLopener providing default
handling for the following HTTP response codes: 301, 302, 303, 307 and
401. For the 30x response codes listed above, the
Location header is used to fetch the actual URL. For 401
response codes (authentication required), basic HTTP authentication is
performed. For the 30x response codes, recursion is bounded by the
value of the maxtries attribute, which defaults to 10.
According to the letter of 2616, 301 and 302 responses to
POST requests must not be automatically redirected without
confirmation by the user. In reality, browsers do allow automatic
redirection of these responses, changing the POST to a GET, and
urllib reproduces this behaviour.
The parameters to the constructor are the same as those for
URLopener.
When performing basic authentication, a
FancyURLopener instance calls its
prompt_user_passwd() method. The default implementation asks
the users for the required information on the controlling terminal. A
subclass may override this method to support more appropriate behavior
if needed.</description>

<properties><property kind="parameter" name="......" required="1"/></properties></element>

<group name="URLopener Objects">
<description>URLopener and FancyURLopener objects have the
following attributes.
</description>
<element kind="function" name="open">
<description>Open fullurl using the appropriate protocol. This method sets
up cache and proxy information, then calls the appropriate open method with
its input arguments. If the scheme is not recognized,
open_unknown() is called. The data argument
has the same meaning as the data argument of urlopen().</description>

<properties><property kind="parameter" name="fullurl" required="1"/><property kind="parameter" name="data"/></properties></element>

<element kind="function" name="open_unknown">
<description>Overridable interface to open unknown URL types.</description>

<properties><property kind="parameter" name="fullurl" required="1"/><property kind="parameter" name="data"/></properties></element>

<element kind="function" name="retrieve">
<description>Retrieves the contents of url and places it in filename. The
return value is a tuple consisting of a local filename and either a
mimetools.Message object containing the response headers (for remote
URLs) or None (for local URLs). The caller must then open and read the
contents of filename. If filename is not given and the URL
refers to a local file, the input filename is returned. If the URL is
non-local and filename is not given, the filename is the output of
tempfile.mktemp() with a suffix that matches the suffix of the last
path component of the input URL. If reporthook is given, it must be
a function accepting three numeric parameters. It will be called after each
chunk of data is read from the network. reporthook is ignored for
local URLs.
If the url uses the http: scheme identifier, the optional
data argument may be given to specify a POST request
(normally the request type is GET). The data argument
must in standard application/x-www-form-urlencoded format;
see the urlencode() function below.</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="filename"/><property kind="parameter" name="reporthook"/><property kind="parameter" name="data"/></properties></element>

<element kind="function" name="prompt_user_passwd">
<description>Return information needed to authenticate the user at the given host
in the specified security realm. The return value should be a tuple,
(user, password), which can be used for basic
authentication.
The implementation prompts for this information on the terminal; an
application should override this method to use an appropriate
interaction model in the local environment.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="realm realm" required="1"/></properties></element>

</group>
<group name="Examples">
</group>
</group>
<group name="urllib2 --- extensible library for opening URLs">
<description>An extensible library for opening URLs using a variety of protocols
The urllib2 module defines functions and classes which help
in opening URLs (mostly HTTP) in a complex world --- basic and digest
authentication, redirections and more.
The urllib2 module defines the following functions:
</description>
<element kind="function" name="urlopen">
<description>Open the URL url, which can be either a string or a Request
object (currently the code checks that it really is a Request
instance, or an instance of a subclass of Request).
data should be a string, which specifies additional data to
send to the server. In HTTP requests, which are the only ones that
support data, it should be a buffer in the format of
application/x-www-form-urlencoded, for example one returned
from urllib.urlencode().
This function returns a file-like object with two additional methods:
geturl() --- return the URL of the resource retrieved
info() --- return the meta-information of the page, as
a dictionary-like object
Raises URLError on errors.</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="data"/></properties></element>

<element kind="function" name="install_opener">
<description>Install an OpenerDirector instance as the default opener.
The code does not check for a real OpenerDirector, and any
class with the appropriate interface will work.</description>

<properties><property kind="parameter" name="openeropener" required="1"/></properties></element>

<element kind="function" name="build_opener">
<description>Return an OpenerDirector instance, which chains the
handlers in the order given. handlers can be either instances
of BaseHandler, or subclasses of BaseHandler (in
which case it must be possible to call the constructor without
any parameters). Instances of the following classes will be in
front of the handlers, unless the handlers contain
them, instances of them or subclasses of them:
ProxyHandler, UnknownHandler, HTTPHandler,
HTTPDefaultErrorHandler, HTTPRedirectHandler,
FTPHandler, FileHandler, HTTPErrorProcessor.
If the Python installation has SSL support (socket.ssl()
exists), HTTPSHandler will also be added.
Beginning in Python 2.3, a BaseHandler subclass may also
change its handler_order member variable to modify its
position in the handlers list. Besides ProxyHandler, which has
handler_order of 100, all handlers currently have it
set to 500.</description>

<properties><property kind="parameter" name="handler" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="Request">
<description>This class is an abstraction of a URL request.
url should be a string which is a valid URL. For a description
of data see the add_data() description.
headers should be a dictionary, and will be treated as if
add_header() was called with each key and value as arguments.</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="data"/><property kind="parameter" name="headers"/></properties></element>

<element kind="function" name="OpenerDirector">
<description>The OpenerDirector class opens URLs via BaseHandlers
chained together. It manages the chaining of handlers, and recovery
from errors.</description>

</element>

<element kind="function" name="BaseHandler">
<description>This is the base class for all registered handlers --- and handles only
the simple mechanics of registration.</description>

</element>

<element kind="function" name="HTTPDefaultErrorHandler">
<description>A class which defines a default handler for HTTP error responses; all
responses are turned into HTTPError exceptions.</description>

</element>

<element kind="function" name="HTTPRedirectHandler">
<description>A class to handle redirections.</description>

</element>

<element kind="function" name="ProxyHandler">
<description>Cause requests to go through a proxy.
If proxies is given, it must be a dictionary mapping
protocol names to URLs of proxies.
The default is to read the list of proxies from the environment
variables protocol_proxy.</description>

<properties><property kind="parameter" name="proxies" required="1"/></properties></element>

<element kind="function" name="HTTPPasswordMgr">
<description>Keep a database of (realm, uri) -&gt; (user, password)
mappings.</description>

</element>

<element kind="function" name="HTTPPasswordMgrWithDefaultRealm">
<description>Keep a database of (realm, uri) -&gt; (user, password) mappings.
A realm of None is considered a catch-all realm, which is searched
if no other realm fits.</description>

</element>

<element kind="function" name="AbstractBasicAuthHandler">
<description>This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
password_mgr, if given, should be something that is compatible
with HTTPPasswordMgr; refer to section~http-password-mgr
for information on the interface that must be supported.</description>

<properties><property kind="parameter" name="password_mgr" required="1"/></properties></element>

<element kind="function" name="HTTPBasicAuthHandler">
<description>Handle authentication with the remote host.
password_mgr, if given, should be something that is compatible
with HTTPPasswordMgr; refer to section~http-password-mgr
for information on the interface that must be supported.</description>

<properties><property kind="parameter" name="password_mgr" required="1"/></properties></element>

<element kind="function" name="ProxyBasicAuthHandler">
<description>Handle authentication with the proxy.
password_mgr, if given, should be something that is compatible
with HTTPPasswordMgr; refer to section~http-password-mgr
for information on the interface that must be supported.</description>

<properties><property kind="parameter" name="password_mgr" required="1"/></properties></element>

<element kind="function" name="AbstractDigestAuthHandler">
<description>This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
password_mgr, if given, should be something that is compatible
with HTTPPasswordMgr; refer to section~http-password-mgr
for information on the interface that must be supported.</description>

<properties><property kind="parameter" name="password_mgr" required="1"/></properties></element>

<element kind="function" name="HTTPDigestAuthHandler">
<description>Handle authentication with the remote host.
password_mgr, if given, should be something that is compatible
with HTTPPasswordMgr; refer to section~http-password-mgr
for information on the interface that must be supported.</description>

<properties><property kind="parameter" name="password_mgr" required="1"/></properties></element>

<element kind="function" name="ProxyDigestAuthHandler">
<description>Handle authentication with the proxy.
password_mgr, if given, should be something that is compatible
with HTTPPasswordMgr; refer to section~http-password-mgr
for information on the interface that must be supported.</description>

<properties><property kind="parameter" name="password_mgr" required="1"/></properties></element>

<element kind="function" name="HTTPHandler">
<description>A class to handle opening of HTTP URLs.</description>

</element>

<element kind="function" name="HTTPSHandler">
<description>A class to handle opening of HTTPS URLs.</description>

</element>

<element kind="function" name="FileHandler">
<description>Open local files.</description>

</element>

<element kind="function" name="FTPHandler">
<description>Open FTP URLs.</description>

</element>

<element kind="function" name="CacheFTPHandler">
<description>Open FTP URLs, keeping a cache of open FTP connections to minimize
delays.</description>

</element>

<element kind="function" name="GopherHandler">
<description>Open gopher URLs.</description>

</element>

<element kind="function" name="UnknownHandler">
<description>A catch-all class to handle unknown URLs.</description>

</element>

<group name="Request Objects">
<description>The following methods describe all of Request's public interface,
and so all must be overridden in subclasses.
</description>
<element kind="function" name="add_data">
<description>Set the Request data to data. This is ignored
by all handlers except HTTP handlers --- and there it should be an
application/x-www-form-encoded buffer, and will change the
request to be POST rather than GET.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="get_method">
<description>Return a string indicating the HTTP request method. This is only
meaningful for HTTP requests, and currently always takes one of the
values (&quot;GET&quot;, &quot;POST&quot;).</description>

</element>

<element kind="function" name="has_data">
<description>Return whether the instance has a non-None data.</description>

</element>

<element kind="function" name="get_data">
<description>Return the instance's data.</description>

</element>

<element kind="function" name="add_header">
<description>Add another header to the request. Headers are currently ignored by
all handlers except HTTP handlers, where they are added to the list
of headers sent to the server. Note that there cannot be more than
one header with the same name, and later calls will overwrite
previous calls in case the key collides. Currently, this is
no loss of HTTP functionality, since all headers which have meaning
when used more than once have a (header-specific) way of gaining the
same functionality using only one header.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="val val" required="1"/></properties></element>

<element kind="function" name="add_unredirected_header">
<description>Add a header that will not be added to a redirected request.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="header header" required="1"/></properties></element>

<element kind="function" name="has_header">
<description>Return whether the instance has the named header (checks both regular
and unredirected).</description>

<properties><property kind="parameter" name="headerheader" required="1"/></properties></element>

<element kind="function" name="get_full_url">
<description>Return the URL given in the constructor.</description>

</element>

<element kind="function" name="get_type">
<description>Return the type of the URL --- also known as the scheme.</description>

</element>

<element kind="function" name="get_host">
<description>Return the host to which a connection will be made.</description>

</element>

<element kind="function" name="get_selector">
<description>Return the selector --- the part of the URL that is sent to
the server.</description>

</element>

<element kind="function" name="set_proxy">
<description>Prepare the request by connecting to a proxy server. The host
and type will replace those of the instance, and the instance's
selector will be the original URL given in the constructor.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="type type" required="1"/></properties></element>

</group>
<group name="OpenerDirector Objects">
<description>OpenerDirector instances have the following methods:
</description>
<element kind="function" name="add_handler">
<description>handler should be an instance of BaseHandler. The
following methods are searched, and added to the possible chains.
protocol_open() ---
signal that the handler knows how to open protocol URLs.
protocol_error_type() ---
signal that the handler knows how to handle type errors from
protocol.
protocol_request() ---
signal that the handler knows how to pre-process protocol
requests.
protocol_response() ---
signal that the handler knows how to post-process protocol
responses.
</description>

<properties><property kind="parameter" name="handlerhandler" required="1"/></properties></element>

<element kind="function" name="close">
<description>Explicitly break cycles, and delete all the handlers.
Because the OpenerDirector needs to know the registered handlers,
and a handler needs to know who the OpenerDirector who called
it is, there is a reference cycle. Even though recent versions of Python
have cycle-collection, it is sometimes preferable to explicitly break
the cycles.</description>

</element>

<element kind="function" name="open">
<description>Open the given url (which can be a request object or a string),
optionally passing the given data.
Arguments, return values and exceptions raised are the same as those
of urlopen() (which simply calls the open() method
on the default installed OpenerDirector).</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="data"/></properties></element>

<element kind="function" name="error">
<description>Handle an error in a given protocol. This will call the registered
error handlers for the given protocol with the given arguments (which
are protocol specific). The HTTP protocol is a special case which
uses the HTTP response code to determine the specific error handler;
refer to the http_error_*() methods of the handler classes.
Return values and exceptions raised are the same as those
of urlopen().</description>

<properties><property kind="parameter" name="proto" required="1"/><property kind="parameter" name="arg"/><property kind="parameter" name="moreargs"/></properties></element>

</group>
<group name="BaseHandler Objects">
<description>BaseHandler objects provide a couple of methods that are
directly useful, and others that are meant to be used by derived
classes. These are intended for direct use:
</description>
<element kind="function" name="add_parent">
<description>Add a director as parent.</description>

<properties><property kind="parameter" name="directordirector" required="1"/></properties></element>

<element kind="function" name="close">
<description>Remove any parents.</description>

</element>

<element kind="function" name="default_open">
<description>This method is not defined in BaseHandler, but
subclasses should define it if they want to catch all URLs.
This method, if implemented, will be called by the parent
OpenerDirector. It should return a file-like object as
described in the return value of the open() of
OpenerDirector, or None. It should raise
URLError, unless a truly exceptional thing happens (for
example, MemoryError should not be mapped to
URLError).
This method will be called before any protocol-specific open method.</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

<element kind="function" name="unknown_open">
<description>This method is not defined in BaseHandler, but
subclasses should define it if they want to catch all URLs with no
specific registered handler to open it.
This method, if implemented, will be called by the parent OpenerDirector. Return values should be the same as for default_open().</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

<element kind="function" name="http_error_default">
<description>This method is not defined in BaseHandler, but
subclasses should override it if they intend to provide a catch-all
for otherwise unhandled HTTP errors. It will be called automatically
by the OpenerDirector getting the error, and should not
normally be called in other circumstances.
req will be a Request object, fp will be a
file-like object with the HTTP error body, code will be the
three-digit code of the error, msg will be the user-visible
explanation of the code and hdrs will be a mapping object with
the headers of the error.
Return values and exceptions raised should be the same as those
of urlopen().</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>


</group>
<group name="HTTPRedirectHandler Objects">
<description>Some HTTP redirections require action from this module's client
code. If this is the case, HTTPError is raised. See
2616 for details of the precise meanings of the various
redirection codes.
</description>
<element kind="function" name="redirect_request">
<description>Return a Request or None in response to a redirect.
This is called by the default implementations of the
http_error_30*() methods when a redirection is received
from the server. If a redirection should take place, return a new
Request to allow http_error_30*() to perform the
redirect. Otherwise, raise HTTPError if no other
Handler should try to handle this URL, or return None
if you can't but another Handler might.
The default implementation of this method does not strictly
follow 2616, which says that 301 and 302 responses to POST
requests must not be automatically redirected without confirmation by
the user. In reality, browsers do allow automatic redirection of
these responses, changing the POST to a GET, and the default
implementation reproduces this behavior.
</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

<element kind="function" name="http_error_301">
<description>Redirect to the Location: URL. This method is called by
the parent OpenerDirector when getting an HTTP
`moved permanently' response.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

<element kind="function" name="http_error_302">
<description>The same as http_error_301(), but called for the
`found' response.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

<element kind="function" name="http_error_303">
<description>The same as http_error_301(), but called for the
`see other' response.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

<element kind="function" name="http_error_307">
<description>The same as http_error_301(), but called for the
`temporary redirect' response.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

</group>
<group name="ProxyHandler Objects">
<description>[ProxyHandler]{protocol_open}{request}
The ProxyHandler will have a method
protocol_open() for every protocol which has a
proxy in the proxies dictionary given in the constructor. The
method will modify requests to go through the proxy, by calling
request.set_proxy(), and call the next handler in the chain to
actually execute the protocol.
</description>
</group>
<group name="HTTPPasswordMgr Objects">
<description>These methods are available on HTTPPasswordMgr and
HTTPPasswordMgrWithDefaultRealm objects.
</description>
<element kind="function" name="add_password">
<description>uri can be either a single URI, or a sequene of URIs. realm,
user and passwd must be strings. This causes
(user, passwd) to be used as authentication tokens
when authentication for realm and a super-URI of any of the
given URIs is given.</description>

<properties><property kind="parameter" name="realm" required="1"/><property kind="parameter" name="uri" required="1"/><property kind="parameter" name="user" required="1"/><property kind="parameter" name="passwd passwd" required="1"/></properties></element>

<element kind="function" name="find_user_password">
<description>Get user/password for given realm and URI, if any. This method will
return (None, None) if there is no matching user/password.
For HTTPPasswordMgrWithDefaultRealm objects, the realm
None will be searched if the given realm has no matching
user/password.</description>

<properties><property kind="parameter" name="realm" required="1"/><property kind="parameter" name="authuri authuri" required="1"/></properties></element>

</group>
<group name="AbstractBasicAuthHandler Objects">
<element kind="function" name="handle_authentication_request">
<description>Handle an authentication request by getting a user/password pair, and
re-trying the request. authreq should be the name of the header
where the information about the realm is included in the request,
host is the host to authenticate to, req should be the
(failed) Request object, and headers should be the error
headers.</description>

<properties><property kind="parameter" name="authreq" required="1"/><property kind="parameter" name="host" required="1"/><property kind="parameter" name="req" required="1"/><property kind="parameter" name="headers headers" required="1"/></properties></element>

</group>
<group name="HTTPBasicAuthHandler Objects">
<element kind="function" name="http_error_401">
<description>Retry the request with authentication information, if available.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

</group>
<group name="ProxyBasicAuthHandler Objects">
<element kind="function" name="http_error_407">
<description>Retry the request with authentication information, if available.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

</group>
<group name="AbstractDigestAuthHandler Objects">
<element kind="function" name="handle_authentication_request">
<description>authreq should be the name of the header where the information about
the realm is included in the request, host should be the host to
authenticate to, req should be the (failed) Request
object, and headers should be the error headers.</description>

<properties><property kind="parameter" name="authreq" required="1"/><property kind="parameter" name="host" required="1"/><property kind="parameter" name="req" required="1"/><property kind="parameter" name="headers headers" required="1"/></properties></element>

</group>
<group name="HTTPDigestAuthHandler Objects">
<element kind="function" name="http_error_401">
<description>Retry the request with authentication information, if available.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

</group>
<group name="ProxyDigestAuthHandler Objects">
<element kind="function" name="http_error_407">
<description>Retry the request with authentication information, if available.</description>

<properties><property kind="parameter" name="req" required="1"/><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="code" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="hdrs hdrs" required="1"/></properties></element>

</group>
<group name="HTTPHandler Objects">
<element kind="function" name="http_open">
<description>Send an HTTP request, which can be either GET or POST, depending on
req.has_data().</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

</group>
<group name="HTTPSHandler Objects">
<element kind="function" name="https_open">
<description>Send an HTTPS request, which can be either GET or POST, depending on
req.has_data().</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

</group>
<group name="FileHandler Objects">
<element kind="function" name="file_open">
<description>Open the file locally, if there is no host name, or
the host name is 'localhost'. Change the
protocol to ftp otherwise, and retry opening
it using parent.</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

</group>
<group name="FTPHandler Objects">
<element kind="function" name="ftp_open">
<description>Open the FTP file indicated by req.
The login is always done with empty username and password.</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

</group>
<group name="CacheFTPHandler Objects">
<description>CacheFTPHandler objects are FTPHandler objects with
the following additional methods:
</description>
<element kind="function" name="setTimeout">
<description>Set timeout of connections to t seconds.</description>

<properties><property kind="parameter" name="tt" required="1"/></properties></element>

<element kind="function" name="setMaxConns">
<description>Set maximum number of cached connections to m.</description>

<properties><property kind="parameter" name="mm" required="1"/></properties></element>

</group>
<group name="GopherHandler Objects">
<element kind="function" name="gopher_open">
<description>Open the gopher resource indicated by req.</description>

<properties><property kind="parameter" name="reqreq" required="1"/></properties></element>

</group>
<group name="UnknownHandler Objects">
<element kind="function" name="unknown_open">
<description>Raise a URLError exception.</description>

</element>

</group>
<group name="HTTPErrorProcessor Objects">
<element kind="function" name="unknown_open">
<description>Process HTTP error responses.
For 200 error codes, the response object is returned immediately.
For non-200 error codes, this simply passes the job on to the
protocol_error_code() handler methods, via
OpenerDirector.error(). Eventually,
urllib2.HTTPDefaultErrorHandler will raise an
HTTPError if no other handler handles the error.</description>

</element>

</group>
<group name="Examples">
</group>
</group>
<group name="httplib --- HTTP protocol client">
<description>HTTP and HTTPS protocol client (requires sockets).
</description>
<element kind="function" name="HTTPConnection">
<description>An HTTPConnection 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. For example, the following calls all create instances that connect to
the server at the same host and port:
&gt;&gt;&gt; h1 = httplib.HTTPConnection('www.cwi.nl')
&gt;&gt;&gt; h2 = httplib.HTTPConnection('www.cwi.nl:80')
&gt;&gt;&gt; h3 = httplib.HTTPConnection('www.cwi.nl', 80)
New in version 2.0</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="HTTPSConnection">
<description>A subclass of HTTPConnection that uses SSL for communication with
secure servers. Default port is 443.
key_file is
the name of a PEM formatted file that contains your private
key. cert_file is a PEM formatted certificate chain file.
This does not do any certificate verification!
New in version 2.0</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/><property kind="parameter" name="key_file"/><property kind="parameter" name="cert_file"/></properties></element>

<element kind="function" name="HTTPResponse">
<description>Class whose instances are returned upon successful connection. Not
instantiated directly by user.
New in version 2.0</description>

<properties><property kind="parameter" name="sock" required="1"/><property default="0" kind="parameter" name="debuglevel"/><property default="0" kind="parameter" name="strict"/></properties></element>

<group name="HTTPConnection Objects">
<description>HTTPConnection instances have the following methods:
</description>
<element kind="function" name="request">
<description>This will send a request to the server using the HTTP request method
method and the selector url. If the body argument is
present, it should be a string of data to send after the headers are finished.
The header Content-Length is automatically set to the correct value.
The headers argument should be a mapping of extra HTTP headers to send
with the request.</description>

<properties><property kind="parameter" name="method" required="1"/><property kind="parameter" name="url" required="1"/><property kind="parameter" name="body"/><property kind="parameter" name="headers"/></properties></element>

<element kind="function" name="getresponse">
<description>Should be called after a request is sent to get the response from the server.
Returns an HTTPResponse instance.</description>

</element>

<element kind="function" name="set_debuglevel">
<description>Set the debugging level (the amount of debugging output printed).
The default debug level is 0, meaning no debugging output is
printed.</description>

<properties><property kind="parameter" name="levellevel" required="1"/></properties></element>

<element kind="function" name="connect">
<description>Connect to the server specified when the object was created.</description>

</element>

<element kind="function" name="close">
<description>Close the connection to the server.</description>

</element>

<element kind="function" name="send">
<description>Send data to the server. This should be used directly only after the
endheaders() method has been called and before
getreply() has been called.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="putrequest">
<description>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.1). To disable automatic sending of Host: or
Accept-Encoding: headers (for example to accept additional
content encodings), specify skip_host or skip_accept_encoding
with non-False values.
Changed in version 2.4: skip_accept_encoding argument added</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="selector" required="1"/><property kind="parameter" name="skip_host"/><property kind="parameter" name="skip_accept_encoding"/></properties></element>

<element kind="function" name="putheader">
<description>Send an 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.</description>

<properties><property kind="parameter" name="header" required="1"/><property kind="parameter" name="argument" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="endheaders">
<description>Send a blank line to the server, signalling the end of the headers.</description>

</element>

</group>
<group name="HTTPResponse Objects">
<description>HTTPResponse instances have the following methods and attributes:
</description>
<element kind="function" name="read">
<description>Reads and returns the response body, or up to the next amt bytes.</description>

<properties><property kind="parameter" name="amt" required="1"/></properties></element>

<element kind="function" name="getheader">
<description>Get the contents of the header name, or default if there is no
matching header.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="default"/></properties></element>

</group>
<group name="Examples">
</group>
</group>
<group name="ftplib --- FTP protocol client">
<description>FTP protocol client (requires sockets).
</description>
<element kind="function" name="FTP">
<description>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).</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="user"/><property kind="parameter" name="passwd"/><property kind="parameter" name="acct"/></properties></element>

<group name="FTP Objects">
<description>Several methods are available in two flavors: one for handling text
files and another for binary files. These are named for the command
which is used followed by lines for the text version or
binary for the binary version.
FTP instances have the following methods:
</description>
<element kind="function" name="set_debuglevel">
<description>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.</description>

<properties><property kind="parameter" name="levellevel" required="1"/></properties></element>

<element kind="function" name="connect">
<description>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.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="getwelcome">
<description>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.)</description>

</element>

<element kind="function" name="login">
<description>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
'anonymous@'. 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.</description>

<properties><property kind="parameter" name="user" required="1"/><property kind="parameter" name="passwd"/><property kind="parameter" name="acct"/></properties></element>

<element kind="function" name="abort">
<description>Abort a file transfer that is in progress. Using this does not always
work, but it's worth a try.</description>

</element>

<element kind="function" name="sendcmd">
<description>Send a simple command string to the server and return the response
string.</description>

<properties><property kind="parameter" name="commandcommand" required="1"/></properties></element>

<element kind="function" name="voidcmd">
<description>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.</description>

<properties><property kind="parameter" name="commandcommand" required="1"/></properties></element>

<element kind="function" name="retrbinary">
<description>Retrieve a file in binary transfer mode. command should be an
appropriate RETR command: 'RETR filename'.
The callback function is called for each block of data received,
with a single string argument giving the data block.
The optional maxblocksize argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer
(which will also be the largest size of the data blocks passed to
callback). A reasonable default is chosen. rest means the
same thing as in the transfercmd() method.</description>

<properties><property kind="parameter" name="command" required="1"/><property kind="parameter" name="callback" required="1"/><property kind="parameter" name="maxblocksize"/><property kind="parameter" name="rest"/></properties></element>

<element kind="function" name="retrlines">
<description>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.</description>

<properties><property kind="parameter" name="command" required="1"/><property kind="parameter" name="callback"/></properties></element>

<element kind="function" name="set_pasv">
<description>Enable ``passive'' mode if boolean is true, other disable
passive mode. (In Python 2.0 and before, passive mode was off by
default; in Python 2.1 and later, it is on by default.)</description>

<properties><property kind="parameter" name="booleanboolean" required="1"/></properties></element>

<element kind="function" name="storbinary">
<description>Store a file in binary transfer mode. command should be an
appropriate STOR command: &quot;STOR filename&quot;.
file is an open file object which is read until using its
read() method in blocks of size blocksize to provide the
data to be stored. The blocksize argument defaults to 8192.
Changed in version 2.1: default for blocksize added</description>

<properties><property kind="parameter" name="command" required="1"/><property kind="parameter" name="file" required="1"/><property kind="parameter" name="blocksize"/></properties></element>

<element kind="function" name="storlines">
<description>Store a file in ASCII transfer mode. command should be an
appropriate STOR command (see storbinary()). Lines are
read until from the open file object file using its
readline() method to provide the data to be stored.</description>

<properties><property kind="parameter" name="command" required="1"/><property kind="parameter" name="file file" required="1"/></properties></element>

<element kind="function" name="transfercmd">
<description>Initiate a transfer over the data connection. If the transfer is
active, send a EPRT or PORT command and the transfer command specified
by cmd, and accept the connection. If the server is passive,
send a EPSV or PASV command, connect to it, and start the transfer
command. Either way, return the socket for the connection.
If optional rest is given, a REST command is
sent to the server, passing rest as an argument. rest is
usually a byte offset into the requested file, telling the server to
restart sending the file's bytes at the requested offset, skipping
over the initial bytes. Note however that RFC
959 requires only that rest be a string containing characters
in the printable range from ASCII code 33 to ASCII code 126. The
transfercmd() method, therefore, converts
rest to a string, but no check is
performed on the string's contents. If the server does
not recognize the REST command, an
error_reply exception will be raised. If this happens,
simply call transfercmd() without a rest argument.</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="rest"/></properties></element>

<element kind="function" name="ntransfercmd">
<description>Like transfercmd(), but returns a tuple of the data
connection and the expected size of the data. If the expected size
could not be computed, None will be returned as the expected
size. cmd and rest means the same thing as in
transfercmd().</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="rest"/></properties></element>

<element kind="function" name="nlst">
<description>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.</description>

<properties><property kind="parameter" name="argument" required="1"/><property kind="parameter" name="ldots"/></properties></element>

<element kind="function" name="dir">
<description>Produce a directory listing as returned by the LIST command,
printing it to standard output. 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(); the default
prints to sys.stdout. This method returns None.</description>

<properties><property kind="parameter" name="argument" required="1"/><property kind="parameter" name="ldots"/></properties></element>

<element kind="function" name="rename">
<description>Rename file fromname on the server to toname.</description>

<properties><property kind="parameter" name="fromname" required="1"/><property kind="parameter" name="toname toname" required="1"/></properties></element>

<element kind="function" name="delete">
<description>Remove the file named filename from the server. If successful,
returns the text of the response, otherwise raises
error_perm on permission errors or
error_reply on other errors.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="cwd">
<description>Set the current directory on the server.</description>

<properties><property kind="parameter" name="pathnamepathname" required="1"/></properties></element>

<element kind="function" name="mkd">
<description>Create a new directory on the server.</description>

<properties><property kind="parameter" name="pathnamepathname" required="1"/></properties></element>

<element kind="function" name="pwd">
<description>Return the pathname of the current directory on the server.</description>

</element>

<element kind="function" name="rmd">
<description>Remove the directory named dirname on the server.</description>

<properties><property kind="parameter" name="dirnamedirname" required="1"/></properties></element>

<element kind="function" name="size">
<description>Request the size of the file named filename on the server. On
success, the size of the file is returned as an integer, otherwise
None is returned. Note that the SIZE command is not standardized, but is supported by many common server implementations.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="quit">
<description>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. This implies a call to the close()
method which renders the FTP instance useless for subsequent
calls (see below).</description>

</element>

<element kind="function" name="close">
<description>Close the connection unilaterally. This should not be applied to an
already closed connection such as after a successful call to
quit(). After this call the FTP instance should not
be used any more (after a call to close() or
quit() you cannot reopen the connection by issuing another
login() method).</description>

</element>

</group>
</group>
<group name="gopherlib --- Gopher protocol client">
<description>Gopher protocol client (requires sockets).
This module provides a minimal implementation of client side of the
Gopher protocol. It is used by the module urllib to
handle URLs that use the Gopher protocol.
The module defines the following functions:
</description>
<element kind="function" name="send_selector">
<description>Send a selector string to the gopher server at host and
port (default 70). Returns an open file object from
which the returned document can be read.</description>

<properties><property kind="parameter" name="selector" required="1"/><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="send_query">
<description>Send a selector string and a query string to a gopher
server at host and port (default 70). Returns an
open file object from which the returned document can be read.</description>

<properties><property kind="parameter" name="selector" required="1"/><property kind="parameter" name="query" required="1"/><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

</group>
<group name="poplib --- POP3 protocol client">
<description>POP3 protocol client (requires sockets).
%By Andrew T. Csillag
%Even though I put it into LaTeX, I cannot really claim that I wrote
%it since I just stole most of it from the poplib.py source code and
%the imaplib ``chapter''.
%Revised by ESR, January 2000
This module defines a class, POP3, which encapsulates a
connection to a POP3 server and implements the protocol as defined in
1725. The POP3 class supports both the minimal and
optional command sets. Additionally, this module provides a class
POP3_SSL, which provides support for connecting to POP3
servers that use SSL as an underlying protocol layer.
Note that POP3, though widely supported, is obsolescent. The
implementation quality of POP3 servers varies widely, and too many are
quite poor. If your mailserver supports IMAP, you would be better off
using the imaplib.IMAP4 class, as IMAP
servers tend to be better implemented.
A single class is provided by the poplib module:
</description>
<element kind="function" name="POP3">
<description>This class implements the actual POP3 protocol. The connection is
created when the instance is initialized.
If port is omitted, the standard POP3 port (110) is used.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="POP3_SSL">
<description>This is a subclass of POP3 that connects to the server over an
SSL encrypted socket. If port is not specified, 995, the
standard POP3-over-SSL port is used. keyfile and certfile
are also optional - they can contain a PEM formatted private key and
certificate chain file for the SSL connection.
New in version 2.4</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/><property kind="parameter" name="keyfile"/><property kind="parameter" name="certfile"/></properties></element>

<group name="POP3 Objects">
<description>All POP3 commands are represented by methods of the same name,
in lower-case; most return the response text sent by the server.
An POP3 instance has the following methods:
</description>
<element kind="function" name="set_debuglevel">
<description>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.</description>

<properties><property kind="parameter" name="levellevel" required="1"/></properties></element>

<element kind="function" name="getwelcome">
<description>Returns the greeting string sent by the POP3 server.</description>

</element>

<element kind="function" name="user">
<description>Send user command, response should indicate that a password is required.</description>

<properties><property kind="parameter" name="usernameusername" required="1"/></properties></element>

<element kind="function" name="pass_">
<description>Send password, response includes message count and mailbox size.
Note: the mailbox on the server is locked until quit() is
called.</description>

<properties><property kind="parameter" name="passwordpassword" required="1"/></properties></element>

<element kind="function" name="apop">
<description>Use the more secure APOP authentication to log into the POP3 server.</description>

<properties><property kind="parameter" name="user" required="1"/><property kind="parameter" name="secret secret" required="1"/></properties></element>

<element kind="function" name="rpop">
<description>Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.</description>

<properties><property kind="parameter" name="useruser" required="1"/></properties></element>

<element kind="function" name="stat">
<description>Get mailbox status. The result is a tuple of 2 integers:
(message count, mailbox size).</description>

</element>

<element kind="function" name="list">
<description>Request message list, result is in the form
(response, ['mesg_num octets', ...]). If which is
set, it is the message to list.</description>

<properties><property kind="parameter" name="which" required="1"/></properties></element>

<element kind="function" name="retr">
<description>Retrieve whole message number which, and set its seen flag.
Result is in form (response, ['line', ...], octets).</description>

<properties><property kind="parameter" name="whichwhich" required="1"/></properties></element>

<element kind="function" name="dele">
<description>Flag message number which for deletion. On most servers
deletions are not actually performed until QUIT (the major exception is
Eudora QPOP, which deliberately violates the RFCs by doing pending
deletes on any disconnect).</description>

<properties><property kind="parameter" name="whichwhich" required="1"/></properties></element>

<element kind="function" name="rset">
<description>Remove any deletion marks for the mailbox.</description>

</element>

<element kind="function" name="noop">
<description>Do nothing. Might be used as a keep-alive.</description>

</element>

<element kind="function" name="quit">
<description>Signoff: commit changes, unlock mailbox, drop connection.</description>

</element>

<element kind="function" name="top">
<description>Retrieves the message header plus howmuch lines of the message
after the header of message number which. Result is in form
(response, ['line', ...], octets).
The POP3 TOP command this method uses, unlike the RETR command,
doesn't set the message's seen flag; unfortunately, TOP is poorly
specified in the RFCs and is frequently broken in off-brand servers.
Test this method by hand against the POP3 servers you will use before
trusting it.</description>

<properties><property kind="parameter" name="which" required="1"/><property kind="parameter" name="howmuch howmuch" required="1"/></properties></element>

<element kind="function" name="uidl">
<description>Return message digest (unique id) list.
If which is specified, result contains the unique id for that
message in the form 'response mesgnum uid,
otherwise result is list (response, ['mesgnum uid', ...],
octets).</description>

<properties><property kind="parameter" name="which" required="1"/></properties></element>

</group>
<group name="POP3 Example">
</group>
</group>
<group name="imaplib --- IMAP4 protocol client">
<description>IMAP4 protocol client (requires sockets).
% Based on HTML documentation by Piers Lauder &lt;piers@communitysolutions.com.au&gt;;
% converted by Fred L. Drake, Jr. &lt;fdrake@acm.org&gt;.
% Revised by ESR, January 2000.
% Changes for IMAP4_SSL by Tino Lange &lt;Tino.Lange@isg.de&gt;, March 2002 % Changes for IMAP4_stream by Piers Lauder &lt;piers@communitysolutions.com.au&gt;, November 2002 This module defines three classes, IMAP4, IMAP4_SSL and IMAP4_stream, which encapsulate a
connection to an IMAP4 server and implement a large subset of the
IMAP4rev1 client protocol as defined in 2060. It is backward
compatible with IMAP4 (1730) servers, but note that the
STATUS command is not supported in IMAP4.
Three classes are provided by the imaplib module, IMAP4 is the base class:
</description>
<element kind="function" name="IMAP4">
<description>This class implements the actual IMAP4 protocol. The connection is
created and protocol version (IMAP4 or IMAP4rev1) is determined when
the instance is initialized.
If host is not specified, '' (the local host) is used.
If port is omitted, the standard IMAP4 port (143) is used.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="IMAP4_SSL">
<description>This is a subclass derived from IMAP4 that connects over an SSL encrypted socket (to use this class you need a socket module that was compiled with SSL support).
If host is not specified, '' (the local host) is used.
If port is omitted, the standard IMAP4-over-SSL port (993) is used.
keyfile and certfile are also optional - they can contain a PEM formatted
private key and certificate chain file for the SSL connection.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/><property kind="parameter" name="keyfile"/><property kind="parameter" name="certfile"/></properties></element>

<element kind="function" name="IMAP4_stream">
<description>This is a subclass derived from IMAP4 that connects
to the stdin/stdout file descriptors created by passing command to os.popen2().
New in version 2.3</description>

<properties><property kind="parameter" name="commandcommand" required="1"/></properties></element>

<element kind="function" name="Internaldate2tuple">
<description>Converts an IMAP4 INTERNALDATE string to Coordinated Universal
Time. Returns a time module tuple.</description>

<properties><property kind="parameter" name="datestrdatestr" required="1"/></properties></element>

<element kind="function" name="Int2AP">
<description>Converts an integer into a string representation using characters
from the set [A .. P].</description>

<properties><property kind="parameter" name="numnum" required="1"/></properties></element>

<element kind="function" name="ParseFlags">
<description>Converts an IMAP4 FLAGS response to a tuple of individual
flags.</description>

<properties><property kind="parameter" name="flagstrflagstr" required="1"/></properties></element>

<element kind="function" name="Time2Internaldate">
<description>Converts a time module tuple to an IMAP4
INTERNALDATE representation. Returns a string in the form:
&quot;DD-Mmm-YYYY HH:MM:SS +HHMM&quot; (including double-quotes).</description>

<properties><property kind="parameter" name="date_timedate_time" required="1"/></properties></element>

<group name="IMAP4 Objects">
<description>All IMAP4rev1 commands are represented by methods of the same name,
either upper-case or lower-case.
All arguments to commands are converted to strings, except for
AUTHENTICATE, and the last argument to APPEND which is
passed as an IMAP4 literal. If necessary (the string contains IMAP4
protocol-sensitive characters and isn't enclosed with either
parentheses or double quotes) each string is quoted. However, the
password argument to the LOGIN command is always quoted.
If you want to avoid having an argument string quoted
(eg: the flags argument to STORE) then enclose the string in
parentheses (eg: r'(\Deleted)').
Each command returns a tuple: (type, [data,
...]) where type is usually 'OK' or 'NO',
and data is either the text from the command response, or
mandated results from the command. Each data
is either a string, or a tuple. If a tuple, then the first part
is the header of the response, and the second part contains
the data (ie: 'literal' value).
An IMAP4 instance has the following methods:
</description>
<element kind="function" name="append">
<description>Append message to named mailbox.</description>

<properties><property kind="parameter" name="mailbox" required="1"/><property kind="parameter" name="flags" required="1"/><property kind="parameter" name="date_time" required="1"/><property kind="parameter" name="message message" required="1"/></properties></element>

<element kind="function" name="authenticate">
<description>Authenticate command --- requires response processing. This is
currently unimplemented, and raises an exception.</description>

<properties><property kind="parameter" name="funcfunc" required="1"/></properties></element>

<element kind="function" name="check">
<description>Checkpoint mailbox on server.</description>

</element>

<element kind="function" name="close">
<description>Close currently selected mailbox. Deleted messages are removed from
writable mailbox. This is the recommended command before
LOGOUT.</description>

</element>

<element kind="function" name="copy">
<description>Copy message_set messages onto end of new_mailbox.</description>

<properties><property kind="parameter" name="message_set" required="1"/><property kind="parameter" name="new_mailbox new_mailbox" required="1"/></properties></element>

<element kind="function" name="create">
<description>Create new mailbox named mailbox.</description>

<properties><property kind="parameter" name="mailboxmailbox" required="1"/></properties></element>

<element kind="function" name="delete">
<description>Delete old mailbox named mailbox.</description>

<properties><property kind="parameter" name="mailboxmailbox" required="1"/></properties></element>

<element kind="function" name="expunge">
<description>Permanently remove deleted items from selected mailbox. Generates an
EXPUNGE response for each deleted message. Returned data
contains a list of EXPUNGE message numbers in order
received.</description>

</element>

<element kind="function" name="fetch">
<description>Fetch (parts of) messages. message_parts should be
a string of message part names enclosed within parentheses,
eg: &quot;(UID BODY[TEXT])&quot;. Returned data are tuples
of message part envelope and data.</description>

<properties><property kind="parameter" name="message_set" required="1"/><property kind="parameter" name="message_parts message_parts" required="1"/></properties></element>

<element kind="function" name="getacl">
<description>Get the ACLs for mailbox.
The method is non-standard, but is supported by the Cyrus server.</description>

<properties><property kind="parameter" name="mailboxmailbox" required="1"/></properties></element>

<element kind="function" name="getquota">
<description>Get the quota root's resource usage and limits.
This method is part of the IMAP4 QUOTA extension defined in rfc2087.
New in version 2.3</description>

<properties><property kind="parameter" name="rootroot" required="1"/></properties></element>

<element kind="function" name="getquotaroot">
<description>Get the list of quota roots for the named mailbox.
This method is part of the IMAP4 QUOTA extension defined in rfc2087.
New in version 2.3</description>

<properties><property kind="parameter" name="mailboxmailbox" required="1"/></properties></element>

<element kind="function" name="list">
<description>List mailbox names in directory matching
pattern. directory defaults to the top-level mail
folder, and pattern defaults to match anything. Returned data
contains a list of LIST responses.</description>

<properties><property kind="parameter" name="directory" required="1"/><property kind="parameter" name="pattern"/></properties></element>

<element kind="function" name="login">
<description>Identify the client using a plaintext password.
The password will be quoted.</description>

<properties><property kind="parameter" name="user" required="1"/><property kind="parameter" name="password password" required="1"/></properties></element>

<element kind="function" name="login_cram_md5">
<description>Force use of CRAM-MD5 authentication when identifying the client to protect the password.
Will only work if the server CAPABILITY response includes the phrase AUTH=CRAM-MD5.
New in version 2.3</description>

<properties><property kind="parameter" name="user" required="1"/><property kind="parameter" name="password password" required="1"/></properties></element>

<element kind="function" name="logout">
<description>Shutdown connection to server. Returns server BYE response.</description>

</element>

<element kind="function" name="lsub">
<description>List subscribed mailbox names in directory matching pattern.
directory defaults to the top level directory and
pattern defaults to match any mailbox.
Returned data are tuples of message part envelope and data.</description>

<properties><property kind="parameter" name="directory" required="1"/><property kind="parameter" name="pattern"/></properties></element>

<element kind="function" name="noop">
<description>Send NOOP to server.</description>

</element>

<element kind="function" name="open">
<description>Opens socket to port at host.
The connection objects established by this method
will be used in the read, readline, send, and shutdown methods.
You may override this method.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port port" required="1"/></properties></element>

<element kind="function" name="partial">
<description>Fetch truncated part of a message.
Returned data is a tuple of message part envelope and data.</description>

<properties><property kind="parameter" name="message_num" required="1"/><property kind="parameter" name="message_part" required="1"/><property kind="parameter" name="start" required="1"/><property kind="parameter" name="length length" required="1"/></properties></element>

<element kind="function" name="proxyauth">
<description>Assume authentication as user.
Allows an authorised administrator to proxy into any user's mailbox.
New in version 2.3</description>

<properties><property kind="parameter" name="useruser" required="1"/></properties></element>

<element kind="function" name="read">
<description>Reads size bytes from the remote server.
You may override this method.</description>

<properties><property kind="parameter" name="sizesize" required="1"/></properties></element>

<element kind="function" name="readline">
<description>Reads one line from the remote server.
You may override this method.</description>

</element>

<element kind="function" name="recent">
<description>Prompt server for an update. Returned data is None if no new
messages, else value of RECENT response.</description>

</element>

<element kind="function" name="rename">
<description>Rename mailbox named oldmailbox to newmailbox.</description>

<properties><property kind="parameter" name="oldmailbox" required="1"/><property kind="parameter" name="newmailbox newmailbox" required="1"/></properties></element>

<element kind="function" name="response">
<description>Return data for response code if received, or
None. Returns the given code, instead of the usual type.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="search">
<description>Search mailbox for matching messages. Returned data contains a space
separated list of matching message numbers. charset may be
None, in which case no CHARSET will be specified in the
request to the server. The IMAP protocol requires that at least one
criterion be specified; an exception will be raised when the server
returns an error.
Example:
# M is a connected IMAP4 instance...
msgnums = M.search(None, 'FROM', '&quot;LDJ&quot;')
# or:
msgnums = M.search(None, '(FROM &quot;LDJ&quot;)')
</description>

<properties><property kind="parameter" name="charset" required="1"/><property kind="parameter" name="criterion" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="select">
<description>Select a mailbox. Returned data is the count of messages in
mailbox (EXISTS response). The default mailbox
is 'INBOX'. If the readonly flag is set, modifications
to the mailbox are not allowed.</description>

<properties><property kind="parameter" name="mailbox" required="1"/><property kind="parameter" name="readonly"/></properties></element>

<element kind="function" name="send">
<description>Sends data to the remote server.
You may override this method.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="setacl">
<description>Set an ACL for mailbox.
The method is non-standard, but is supported by the Cyrus server.</description>

<properties><property kind="parameter" name="mailbox" required="1"/><property kind="parameter" name="who" required="1"/><property kind="parameter" name="what what" required="1"/></properties></element>

<element kind="function" name="setquota">
<description>Set the quota root's resource limits.
This method is part of the IMAP4 QUOTA extension defined in rfc2087.
New in version 2.3</description>

<properties><property kind="parameter" name="root" required="1"/><property kind="parameter" name="limits limits" required="1"/></properties></element>

<element kind="function" name="shutdown">
<description>Close connection established in open.
You may override this method.</description>

</element>

<element kind="function" name="socket">
<description>Returns socket instance used to connect to server.</description>

</element>

<element kind="function" name="sort">
<description>The sort command is a variant of search with sorting semantics for
the results. Returned data contains a space
separated list of matching message numbers.
Sort has two arguments before the search_criterion
argument(s); a parenthesized list of sort_criteria, and the searching charset.
Note that unlike search, the searching charset argument is mandatory.
There is also a uid sort command which corresponds to sort the way
that uid search corresponds to search.
The sort command first searches the mailbox for messages that
match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then
returns the numbers of matching messages.
This is an IMAP4rev1 extension command.</description>

<properties><property kind="parameter" name="sort_criteria" required="1"/><property kind="parameter" name="charset" required="1"/><property kind="parameter" name="search_criterion" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="status">
<description>Request named status conditions for mailbox.</description>

<properties><property kind="parameter" name="mailbox" required="1"/><property kind="parameter" name="names names" required="1"/></properties></element>

<element kind="function" name="store">
<description>Alters flag dispositions for messages in mailbox.</description>

<properties><property kind="parameter" name="message_set" required="1"/><property kind="parameter" name="command" required="1"/><property kind="parameter" name="flag_list flag_list" required="1"/></properties></element>

<element kind="function" name="subscribe">
<description>Subscribe to new mailbox.</description>

<properties><property kind="parameter" name="mailboxmailbox" required="1"/></properties></element>

<element kind="function" name="thread">
<description>The thread command is a variant of search with threading semantics for
the results. Returned data contains a space
separated list of thread members.
Thread members consist of zero or more messages numbers, delimited by spaces,
indicating successive parent and child.
Thread has two arguments before the search_criterion
argument(s); a threading_algorithm, and the searching charset.
Note that unlike search, the searching charset argument is mandatory.
There is also a uid thread command which corresponds to thread the way
that uid search corresponds to search.
The thread command first searches the mailbox for messages that
match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It thren
returns the matching messages threaded according to the specified
threading algorithm.
This is an IMAP4rev1 extension command. New in version 2.4</description>

<properties><property kind="parameter" name="threading_algorithm" required="1"/><property kind="parameter" name="charset" required="1"/><property kind="parameter" name="search_criterion" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="uid">
<description>Execute command args with messages identified by UID, rather than
message number. Returns response appropriate to command. At least
one argument must be supplied; if none are provided, the server will
return an error and an exception will be raised.</description>

<properties><property kind="parameter" name="command" required="1"/><property kind="parameter" name="arg" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="unsubscribe">
<description>Unsubscribe from old mailbox.</description>

<properties><property kind="parameter" name="mailboxmailbox" required="1"/></properties></element>

<element kind="function" name="xatom">
<description>Allow simple extension commands notified by server in
CAPABILITY response.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="arg"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="ssl">
<description>Returns SSLObject instance used for the secure connection with the server.</description>

</element>

</group>
<group name="IMAP4 Example">
</group>
</group>
<group name="nntplib --- NNTP protocol client">
<description>NNTP protocol client (requires sockets).
</description>
<element kind="function" name="NNTP">
<description>Return a new instance of the NNTP class, representing a
connection to the NNTP server running on host host, listening at
port port. The default port is 119. If the optional
user and password are provided, or if suitable credentials are present in ~/.netrc,
the AUTHINFO USER and AUTHINFO PASS commands are used to
identify and authenticate the user to the server. If the optional
flag readermode is true, then a mode reader command is
sent before authentication is performed. Reader mode is sometimes
necessary if you are connecting to an NNTP server on the local machine
and intend to call reader-specific commands, such as group. If
you get unexpected NNTPPermanentErrors, you might need to set
readermode. readermode defaults to None.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/><property kind="parameter" name="user"/><property kind="parameter" name="password"/><property kind="parameter" name="readermode"/></properties></element>

<element kind="function" name="NNTPError">
<description>Derived from the standard exception Exception, this is the base
class for all exceptions raised by the nntplib module.</description>

</element>

<element kind="function" name="NNTPReplyError">
<description>Exception raised when an unexpected reply is received from the
server. For backwards compatibility, the exception error_reply
is equivalent to this class.</description>

</element>

<element kind="function" name="NNTPTemporaryError">
<description>Exception raised when an error code in the range 400--499 is
received. For backwards compatibility, the exception
error_temp is equivalent to this class.</description>

</element>

<element kind="function" name="NNTPPermanentError">
<description>Exception raised when an error code in the range 500--599 is
received. For backwards compatibility, the exception
error_perm is equivalent to this class.</description>

</element>

<element kind="function" name="NNTPProtocolError">
<description>Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5. For backwards
compatibility, the exception error_proto is equivalent to this
class.</description>

</element>

<element kind="function" name="NNTPDataError">
<description>Exception raised when there is some error in the response data. For
backwards compatibility, the exception error_data is
equivalent to this class.</description>

</element>

<group name="NNTP Objects">
<description>NNTP instances have the following methods. The response that is
returned as the first item in the return tuple of almost all methods
is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.
</description>
<element kind="function" name="getwelcome">
<description>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.)</description>

</element>

<element kind="function" name="set_debuglevel">
<description>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 or response. A value of
2 or higher produces the maximum amount of debugging output,
logging each line sent and received on the connection (including
message text).</description>

<properties><property kind="parameter" name="levellevel" required="1"/></properties></element>

<element kind="function" name="newgroups">
<description>Send a NEWGROUPS command. The date argument should be a
string of the form 'yymmdd' indicating the
date, and time should be a string of the form
'hhmmss' indicating the time. Return a pair
(response, groups) where groups is a list of
group names that are new since the given date and time.
If the file parameter is supplied, then the output of the NEWGROUPS command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.</description>

<properties><property kind="parameter" name="date" required="1"/><property kind="parameter" name="time" required="1"/><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="newnews">
<description>Send a NEWNEWS command. Here, group is a group name or
'*', and date and time have the same meaning as for
newgroups(). Return a pair (response,
articles) where articles is a list of article ids.
If the file parameter is supplied, then the output of the NEWNEWS command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.</description>

<properties><property kind="parameter" name="group" required="1"/><property kind="parameter" name="date" required="1"/><property kind="parameter" name="time" required="1"/><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="list">
<description>Send a LIST command. Return a pair (response,
list) where list is a list of tuples. Each tuple has the
form (group, last, first, flag), where
group is a group name, last and first are the last
and first article numbers (as strings), and flag is
'y' if posting is allowed, 'n' if not, and 'm' if
the newsgroup is moderated. (Note the ordering: last,
first.)
If the file parameter is supplied, then the output of the LIST command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.</description>

<properties><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="group">
<description>Send a GROUP command, where name is the group name.
Return a tuple (response, count, first,
last, name) where count is the (estimated) number
of articles in the group, first is the first article number in
the group, last is the last article number in the group, and
name is the group name. The numbers are returned as strings.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="help">
<description>Send a HELP command. Return a pair (response,
list) where list is a list of help strings.
If the file parameter is supplied, then the output of the HELP command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.</description>

<properties><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="stat">
<description>Send a STAT command, where id is the message id (enclosed
in &lt; and &gt;) or an article number (as a string).
Return a triple (response, number, id) where
number is the article number (as a string) and id is the
article id (enclosed in &lt; and &gt;).</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="next">
<description>Send a NEXT command. Return as for stat().</description>

</element>

<element kind="function" name="last">
<description>Send a LAST command. Return as for stat().</description>

</element>

<element kind="function" name="head">
<description>Send a HEAD command, where id has the same meaning as for
stat(). Return a tuple
(response, number, id, list)
where the first three are the same as for stat(),
and list is a list of the article's headers (an uninterpreted
list of lines, without trailing newlines).</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="body">
<description>Send a BODY command, where id has the same meaning as for
stat(). If the file parameter is supplied, then
the body is stored in a file. If file is a string, then
the method will open a file object with that name, write to it then close it.
If file is a file object, then it will start calling
write() on it to store the lines of the body.
Return as for head(). If file is supplied, then
the returned list is an empty list.</description>

<properties><property kind="parameter" name="id" required="1"/><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="article">
<description>Send an ARTICLE command, where id has the same meaning as
for stat(). Return as for head().</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="slave">
<description>Send a SLAVE command. Return the server's response.</description>

</element>

<element kind="function" name="xhdr">
<description>Send an XHDR command. This command is not defined in the RFC
but is a common extension. The header argument is a header
keyword, e.g. 'subject'. The string argument should have
the form 'first-last' where first and
last are the first and last article numbers to search. Return a
pair (response, list), where list is a list of
pairs (id, text), where id is an article id
(as a string) and text is the text of the requested header for
that article.
If the file parameter is supplied, then the output of the XHDR command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.</description>

<properties><property kind="parameter" name="header" required="1"/><property kind="parameter" name="string" required="1"/><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="post">
<description>Post an article using the POST command. The file
argument is an open file object which is read until EOF using its
readline() method. It should be a well-formed news article,
including the required headers. The post() method
automatically escapes lines beginning with ..</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="ihave">
<description>Send an IHAVE command. If the response is not an error, treat
file exactly as for the post() method.</description>

<properties><property kind="parameter" name="id" required="1"/><property kind="parameter" name="file file" required="1"/></properties></element>

<element kind="function" name="date">
<description>Return a triple (response, date, time),
containing the current date and time in a form suitable for the
newnews() and newgroups() methods.
This is an optional NNTP extension, and may not be supported by all
servers.</description>

</element>

<element kind="function" name="xgtitle">
<description>Process an XGTITLE command, returning a pair (response,
list), where list is a list of tuples containing
(name, title).
% XXX huh? Should that be name, description?
If the file parameter is supplied, then the output of the XGTITLE command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.
This is an optional NNTP extension, and may not be supported by all
servers.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="xover">
<description>Return a pair (resp, list). list is a list
of tuples, one for each article in the range delimited by the start
and end article numbers. Each tuple is of the form
(article number, subject, poster, date,
id, references, size, lines).
If the file parameter is supplied, then the output of the XOVER command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start
calling write() on it to store the lines of the command output.
If file is supplied, then the returned list is an empty list.
This is an optional NNTP extension, and may not be supported by all
servers.</description>

<properties><property kind="parameter" name="start" required="1"/><property kind="parameter" name="end" required="1"/><property kind="parameter" name="file" required="1"/></properties></element>

<element kind="function" name="xpath">
<description>Return a pair (resp, path), where path is the
directory path to the article with message ID id. This is an
optional NNTP extension, and may not be supported by all servers.</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="quit">
<description>Send a QUIT command and close the connection. Once this method
has been called, no other methods of the NNTP object should be called.</description>

</element>

</group>
</group>
<group name="smtplib --- SMTP protocol client">
<description>SMTP protocol client (requires sockets).
</description>
<element kind="function" name="SMTP">
<description>A SMTP instance encapsulates an SMTP connection. It has
methods that support a full repertoire of SMTP and ESMTP
operations. If the optional host and port parameters are given, the
SMTP connect() method is called with those parameters during
initialization. An SMTPConnectError is raised if the
specified host doesn't respond correctly.
For normal use, you should only require the initialization/connect,
sendmail(), and quit() methods. An example is
included below.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/><property kind="parameter" name="local_hostname"/></properties></element>

<group name="SMTP Objects">
<description>An SMTP instance has the following methods:
</description>
<element kind="function" name="set_debuglevel">
<description>Set the debug output level. A true value for level results in
debug messages for connection and for all messages sent to and
received from the server.</description>

<properties><property kind="parameter" name="levellevel" required="1"/></properties></element>

<element kind="function" name="connect">
<description>Connect to a host on a given port. The defaults are to connect to the
local host at the standard SMTP port (25).
If the hostname ends with a colon (:) followed by a
number, that suffix will be stripped off and the number interpreted as
the port number to use.
This method is automatically invoked by the constructor if a
host is specified during instantiation.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="docmd">
<description>Send a command cmd to the server. The optional argument
argstring is simply concatenated to the command, separated by a
space.
This returns a 2-tuple composed of a numeric response code and the
actual response line (multiline responses are joined into one long
line.)
In normal operation it should not be necessary to call this method
explicitly. It is used to implement other methods and may be useful
for testing private extensions.
If the connection to the server is lost while waiting for the reply,
SMTPServerDisconnected will be raised.</description>

<properties><property kind="parameter" name="cmd" required="1"/><property kind="parameter" name="argstring"/></properties></element>

<element kind="function" name="helo">
<description>Identify yourself to the SMTP server using HELO. The hostname
argument defaults to the fully qualified domain name of the local
host.
In normal operation it should not be necessary to call this method
explicitly. It will be implicitly called by the sendmail()
when necessary.</description>

<properties><property kind="parameter" name="hostname" required="1"/></properties></element>

<element kind="function" name="ehlo">
<description>Identify yourself to an ESMTP server using EHLO. The hostname
argument defaults to the fully qualified domain name of the local
host. Examine the response for ESMTP option and store them for use by
has_extn().
Unless you wish to use has_extn() before sending
mail, it should not be necessary to call this method explicitly. It
will be implicitly called by sendmail() when necessary.</description>

<properties><property kind="parameter" name="hostname" required="1"/></properties></element>

<element kind="function" name="has_extn">
<description>Return 1 if name is in the set of SMTP service extensions
returned by the server, 0 otherwise. Case is ignored.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="verify">
<description>Check the validity of an address on this server using SMTP VRFY.
Returns a tuple consisting of code 250 and a full 822 address
(including human name) if the user address is valid. Otherwise returns
an SMTP error code of 400 or greater and an error string.
Many sites disable SMTP VRFY in order to foil spammers.</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="login">
<description>Log in on an SMTP server that requires authentication.
The arguments are the username and the password to authenticate with.
If there has been no previous EHLO or HELO command this
session, this method tries ESMTP EHLO first.
This method will return normally if the authentication was successful,
or may raise the following exceptions:
[SMTPHeloError]
The server didn't reply properly to the HELO greeting.
[SMTPAuthenticationError]
The server didn't accept the username/password combination.
[SMTPError]
No suitable authentication method was found.
</description>

<properties><property kind="parameter" name="user" required="1"/><property kind="parameter" name="password password" required="1"/></properties></element>

<element kind="function" name="starttls">
<description>Put the SMTP connection in TLS (Transport Layer Security) mode. All
SMTP commands that follow will be encrypted. You should then call
ehlo() again.
If keyfile and certfile are provided, these are passed to
the socket module's ssl() function.</description>

<properties><property kind="parameter" name="keyfile" required="1"/><property kind="parameter" name="certfile"/></properties></element>

<element kind="function" name="sendmail">
<description>Send mail. The required arguments are an 822 from-address
string, a list of 822 to-address strings, and a message string.
The caller may pass a list of ESMTP options (such as 8bitmime)
to be used in MAIL FROM commands as mail_options. ESMTP
options (such as DSN commands) that should be used with all
RCPT commands can be passed as rcpt_options. (If you
need to use different ESMTP options to different recipients you have
to use the low-level methods such as mail, rcpt and
data to send the message.)
The from_addr and to_addrs parameters are
used to construct the message envelope used by the transport agents.
The SMTP does not modify the message headers in any way.
If there has been no previous EHLO or HELO command this
session, this method tries ESMTP EHLO first. If the server does
ESMTP, message size and each of the specified options will be passed
to it (if the option is in the feature set the server advertises). If
EHLO fails, HELO will be tried and ESMTP options
suppressed.
This method will return normally if the mail is accepted for at least
one recipient. Otherwise it will throw an exception. That is, if this
method does not throw an exception, then someone should get your mail.
If this method does not throw an exception, it returns a dictionary,
with one entry for each recipient that was refused. Each entry
contains a tuple of the SMTP error code and the accompanying error
message sent by the server.
This method may raise the following exceptions:
[SMTPRecipientsRefused]
All recipients were refused. Nobody got the mail. The
recipients attribute of the exception object is a dictionary
with information about the refused recipients (like the one returned
when at least one recipient was accepted).
[SMTPHeloError]
The server didn't reply properly to the HELO greeting.
[SMTPSenderRefused]
The server didn't accept the from_addr.
[SMTPDataError]
The server replied with an unexpected error code (other than a refusal
of a recipient).
Unless otherwise noted, the connection will be open even after
an exception is raised.</description>

<properties><property kind="parameter" name="from_addr" required="1"/><property kind="parameter" name="to_addrs" required="1"/><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="mail_options"/><property kind="parameter" name="rcpt_options"/></properties></element>

<element kind="function" name="quit">
<description>Terminate the SMTP session and close the connection.</description>

</element>

</group>
<group name="SMTP Example">
</group>
</group>
<group name="telnetlib --- Telnet client">
<description>Telnet client class.
</description>
<element kind="function" name="Telnet">
<description>Telnet represents a connection to a Telnet server. The
instance is initially not connected by default; the open()
method must be used to establish a connection. Alternatively, the
host name and optional port number can be passed to the constructor,
to, in which case the connection to the server will be established
before the constructor returns.
Do not reopen an already connected instance.
This class has many read_*() methods. Note that some of them raise EOFError when the end of the connection is read,
because they can return an empty string for other reasons. See the
individual descriptions below.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<group name="Telnet Objects">
<description>Telnet instances have the following methods:
</description>
<element kind="function" name="read_until">
<description>Read until a given string, expected, is encountered or until
timeout seconds have passed.
When no match is found, return whatever is available instead,
possibly the empty string. Raise EOFError if the connection
is closed and no cooked data is available.</description>

<properties><property kind="parameter" name="expected" required="1"/><property kind="parameter" name="timeout"/></properties></element>

<element kind="function" name="read_all">
<description>Read all data until ; block until connection closed.</description>

</element>

<element kind="function" name="read_some">
<description>Read at least one byte of cooked data unless is hit.
Return '' if is hit. Block if no data is immediately
available.</description>

</element>

<element kind="function" name="read_very_eager">
<description>Read everything that can be without blocking in I/O (eager).
Raise EOFError if connection closed and no cooked data
available. Return '' if no cooked data available otherwise.
Do not block unless in the midst of an IAC sequence.</description>

</element>

<element kind="function" name="read_eager">
<description>Read readily available data.
Raise EOFError if connection closed and no cooked data
available. Return '' if no cooked data available otherwise.
Do not block unless in the midst of an IAC sequence.</description>

</element>

<element kind="function" name="read_lazy">
<description>Process and return data already in the queues (lazy).
Raise EOFError if connection closed and no data available.
Return '' if no cooked data available otherwise. Do not block
unless in the midst of an IAC sequence.</description>

</element>

<element kind="function" name="read_very_lazy">
<description>Return any data available in the cooked queue (very lazy).
Raise EOFError if connection closed and no data available.
Return '' if no cooked data available otherwise. This method
never blocks.</description>

</element>

<element kind="function" name="read_sb_data">
<description>Return the data collected between a SB/SE pair (suboption begin/end).
The callback should access these data when it was invoked with a
SE command. This method never blocks.
New in version 2.3</description>

</element>

<element kind="function" name="open">
<description>Connect to a host.
The optional second argument is the port number, which
defaults to the standard Telnet port (23).
Do not try to reopen an already connected instance.</description>

<properties><property kind="parameter" name="host" required="1"/><property kind="parameter" name="port"/></properties></element>

<element kind="function" name="msg">
<description>Print a debug message when the debug level is &gt; 0.
If extra arguments are present, they are substituted in the
message using the standard string formatting operator.</description>

<properties><property kind="parameter" name="msg" required="1"/><property kind="parameter" name="*args"/></properties></element>

<element kind="function" name="set_debuglevel">
<description>Set the debug level. The higher the value of debuglevel, the
more debug output you get (on sys.stdout).</description>

<properties><property kind="parameter" name="debugleveldebuglevel" required="1"/></properties></element>

<element kind="function" name="close">
<description>Close the connection.</description>

</element>

<element kind="function" name="get_socket">
<description>Return the socket object used internally.</description>

</element>

<element kind="function" name="fileno">
<description>Return the file descriptor of the socket object used internally.</description>

</element>

<element kind="function" name="write">
<description>Write a string to the socket, doubling any IAC characters.
This can block if the connection is blocked. May raise
socket.error if the connection is closed.</description>

<properties><property kind="parameter" name="bufferbuffer" required="1"/></properties></element>

<element kind="function" name="interact">
<description>Interaction function, emulates a very dumb Telnet client.</description>

</element>

<element kind="function" name="mt_interact">
<description>Multithreaded version of interact().</description>

</element>

<element kind="function" name="expect">
<description>Read until one from a list of a regular expressions matches.
The first argument is a list of regular expressions, either
compiled (re.RegexObject instances) or uncompiled (strings).
The optional second argument is a timeout, in seconds; the default
is to block indefinitely.
Return a tuple of three items: the index in the list of the
first regular expression that matches; the match object
returned; and the text read up till and including the match.
If end of file is found and no text was read, raise
EOFError. Otherwise, when nothing matches, return
(-1, None, text) where text is the text received so
far (may be the empty string if a timeout happened).
If a regular expression ends with a greedy match (such as .*)
or if more than one expression can match the same input, the
results are indeterministic, and may depend on the I/O timing.</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="timeout"/></properties></element>

<element kind="function" name="set_option_negotiation_callback">
<description>Each time a telnet option is read on the input flow, this
callback (if set) is called with the following parameters :
callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other
action is done afterwards by telnetlib.</description>

<properties><property kind="parameter" name="callbackcallback" required="1"/></properties></element>

</group>
<group name="Telnet Example">
</group>
</group>
<group name="urlparse --- Parse URLs into components">
<description>Parse URLs into components.
</description>
<element kind="function" name="urlparse">
<description>Parse a URL into 6 components, returning a 6-tuple: (addressing
scheme, network location, path, parameters, query, fragment
identifier). This corresponds to the general structure of a URL:
scheme://netloc/path;parameters?query#fragment.
Each tuple item is a string, possibly empty.
The components are not broken up in smaller parts (e.g. the network
location is a single string), and % escapes are not expanded.
The delimiters as shown above are not part of the tuple items,
except for a leading slash in the path component, which is
retained if present.
Example:
urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
yields the tuple
('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
If the default_scheme argument is specified, it gives the
default addressing scheme, to be used only if the URL string does not
specify one. The default value for this argument is the empty string.
If the allow_fragments argument is zero, fragment identifiers
are not allowed, even if the URL's addressing scheme normally does
support them. The default value for this argument is 1.</description>

<properties><property kind="parameter" name="urlstring" required="1"/><property kind="parameter" name="default_scheme"/><property kind="parameter" name="allow_fragments"/></properties></element>

<element kind="function" name="urlunparse">
<description>Construct a URL string from a tuple as returned by urlparse().
This may result in a slightly different, but equivalent URL, if the
URL that was parsed originally had redundant delimiters, e.g. a ? with
an empty query (the draft states that these are equivalent).</description>

<properties><property kind="parameter" name="tupletuple" required="1"/></properties></element>

<element kind="function" name="urlsplit">
<description>This is similar to urlparse(), but does not split the
params from the URL. This should generally be used instead of
urlparse() if the more recent URL syntax allowing
parameters to be applied to each segment of the path portion of
the URL (see 2396). A separate function is needed to separate
the path segments and parameters. This function returns a 5-tuple:
(addressing scheme, network location, path, query, fragment
identifier).
New in version 2.2</description>

<properties><property kind="parameter" name="urlstring" required="1"/><property kind="parameter" name="default_scheme"/><property kind="parameter" name="allow_fragments"/></properties></element>

<element kind="function" name="urlunsplit">
<description>Combine the elements of a tuple as returned by urlsplit()
into a complete URL as a string.
New in version 2.2</description>

<properties><property kind="parameter" name="tupletuple" required="1"/></properties></element>

<element kind="function" name="urljoin">
<description>Construct a full (``absolute'') URL by combining a ``base URL''
(base) with a ``relative URL'' (url). Informally, this
uses components of the base URL, in particular the addressing scheme,
the network location and (part of) the path, to provide missing
components in the relative URL.
Example:
urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
yields the string
'http://www.cwi.nl/%7Eguido/FAQ.html'
The allow_fragments argument has the same meaning as for
urlparse().</description>

<properties><property kind="parameter" name="base" required="1"/><property kind="parameter" name="url" required="1"/><property kind="parameter" name="allow_fragments"/></properties></element>

<element kind="function" name="urldefrag">
<description>If url contains a fragment identifier, returns a modified
version of url with no fragment identifier, and the fragment
identifier as a separate string. If there is no fragment identifier
in url, returns url unmodified and an empty string.</description>

<properties><property kind="parameter" name="urlurl" required="1"/></properties></element>

</group>
<group name="SocketServer --- A framework for network servers">
<description>A framework for network servers.
The SocketServer module simplifies the task of writing network
servers.
There are four basic server classes: TCPServer uses the
Internet TCP protocol, which provides for continuous streams of data
between the client and server. UDPServer uses datagrams, which
are discrete packets of information that may arrive out of order or be
lost while in transit. The more infrequently used
UnixStreamServer and UnixDatagramServer classes are
similar, but use domain sockets; they're not available on
non- platforms. For more details on network programming, consult
a book such as W. Richard Steven's UNIX Network Programming
or Ralph Davis's Win32 Network Programming.
These four classes process requests synchronously; each request
must be completed before the next request can be started. This isn't
suitable if each request takes a long time to complete, because it
requires a lot of computation, or because it returns a lot of data
which the client is slow to process. The solution is to create a
separate process or thread to handle each request; the
ForkingMixIn and ThreadingMixIn mix-in classes can be
used to support asynchronous behaviour.
Creating a server requires several steps. First, you must create a
request handler class by subclassing the BaseRequestHandler
class and overriding its handle() method; this method will
process incoming requests. Second, you must instantiate one of the
server classes, passing it the server's address and the request
handler class. Finally, call the handle_request() or
serve_forever() method of the server object to process one or
many requests.
When inheriting from ThreadingMixIn for threaded connection
behavior, you should explicitly declare how you want your threads
to behave on an abrupt shutdown. The ThreadingMixIn class
defines an attribute daemon_threads, which indicates whether
or not the server should wait for thread termination. You should
set the flag explicitly if you would like threads to behave
autonomously; the default is False, meaning that Python
will not exit until all threads created by ThreadingMixIn have
exited.
Server classes have the same external methods and attributes, no
matter what network protocol they use:
</description>
<element kind="function" name="fileno">
<description>Return an integer file descriptor for the socket on which the server
is listening. This function is most commonly passed to
select.select(), to allow monitoring multiple servers in the
same process.</description>

</element>

<element kind="function" name="handle_request">
<description>Process a single request. This function calls the following methods
in order: get_request(), verify_request(), and
process_request(). If the user-provided handle()
method of the handler class raises an exception, the server's
handle_error() method will be called.</description>

</element>

<element kind="function" name="serve_forever">
<description>Handle an infinite number of requests. This simply calls
handle_request() inside an infinite loop.</description>

</element>

<element kind="function" name="finish_request">
<description>Actually processes the request by instantiating
RequestHandlerClass and calling its handle() method.</description>

</element>

<element kind="function" name="get_request">
<description>Must accept a request from the socket, and return a 2-tuple containing
the new socket object to be used to communicate with the
client, and the client's address.</description>

</element>

<element kind="function" name="handle_error">
<description>This function is called if the RequestHandlerClass's
handle() method raises an exception. The default action is
to print the traceback to standard output and continue handling
further requests.</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="client_address client_address" required="1"/></properties></element>

<element kind="function" name="process_request">
<description>Calls finish_request() to create an instance of the
RequestHandlerClass. If desired, this function can create a
new process or thread to handle the request; the ForkingMixIn
and ThreadingMixIn classes do this.</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="client_address client_address" required="1"/></properties></element>

<element kind="function" name="server_activate">
<description>Called by the server's constructor to activate the server.
May be overridden.</description>

</element>

<element kind="function" name="server_bind">
<description>Called by the server's constructor to bind the socket to the desired
address. May be overridden.</description>

</element>

<element kind="function" name="verify_request">
<description>Must return a Boolean value; if the value is true, the request will be
processed, and if it's false, the request will be denied.
This function can be overridden to implement access controls for a server.
The default implementation always return true.</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="client_address client_address" required="1"/></properties></element>

<element kind="function" name="finish">
<description>Called after the handle() method to perform any clean-up
actions required. The default implementation does nothing. If
setup() or handle() raise an exception, this
function will not be called.</description>

</element>

<element kind="function" name="handle">
<description>This function must do all the work required to service a request.
Several instance attributes are available to it; the request is
available as self.request; the client address as
self.client_address; and the server instance as
self.server, in case it needs access to per-server
information.
The type of self.request is different for datagram or stream
services. For stream services, self.request is a socket
object; for datagram services, self.request is a string.
However, this can be hidden by using the mix-in request handler
classes
StreamRequestHandler or DatagramRequestHandler, which
override the setup() and finish() methods, and
provides self.rfile and self.wfile attributes.
self.rfile and self.wfile can be read or written,
respectively, to get the request data or return data to the client.</description>

</element>

<element kind="function" name="setup">
<description>Called before the handle() method to perform any
initialization actions required. The default implementation does
nothing.</description>

</element>

</group>
<group name="BaseHTTPServer --- Basic HTTP server">
<description>Basic HTTP server (base class for
SimpleHTTPServer and CGIHTTPServer).
</description>
<element kind="function" name="HTTPServer">
<description>This class builds on the TCPServer class by
storing the server address as instance
variables named server_name and server_port. The
server is accessible by the handler, typically through the handler's
server instance variable.</description>

<properties><property kind="parameter" name="server_address" required="1"/><property kind="parameter" name="RequestHandlerClass RequestHandlerClass" required="1"/></properties></element>

<element kind="function" name="BaseHTTPRequestHandler">
<description>This class is used
to handle the HTTP requests that arrive at the server. By itself,
it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (e.g. GET or POST).
BaseHTTPRequestHandler provides a number of class and instance
variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a
method specific to the request type. The method name is constructed
from the request. For example, for the request method SPAM, the
do_SPAM() method will be called with no arguments. All of
the relevant information is stored in instance variables of the
handler. Subclasses should not need to override or extend the
__init__() method.</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="client_address" required="1"/><property kind="parameter" name="server server" required="1"/></properties></element>

<element kind="function" name="handle">
<description>Calls handle_one_request() once (or, if persistent connections
are enabled, multiple times) to handle incoming HTTP requests.
You should never need to override it; instead, implement appropriate
do_*() methods.</description>

</element>

<element kind="function" name="handle_one_request">
<description>This method will parse and dispatch
the request to the appropriate do_*() method. You should
never need to override it.</description>

</element>

<element kind="function" name="send_error">
<description>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.</description>

<properties><property kind="parameter" name="code" required="1"/><property kind="parameter" name="message"/></properties></element>

<element kind="function" name="send_response">
<description>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.</description>

<properties><property kind="parameter" name="code" required="1"/><property kind="parameter" name="message"/></properties></element>

<element kind="function" name="send_header">
<description>Writes a specific MIME header to the output stream. keyword
should specify the header keyword, with value specifying
its value.</description>

<properties><property kind="parameter" name="keyword" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="end_headers">
<description>Sends a blank line, indicating the end of the MIME headers in
the response.</description>

</element>

<element kind="function" name="log_request">
<description>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.</description>

<properties><property kind="parameter" name="code" required="1"/><property kind="parameter" name="size"/></properties></element>

<element kind="function" name="log_error">
<description>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).</description>

<properties><property kind="parameter" name="......" required="1"/></properties></element>

<element kind="function" name="log_message">
<description>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.</description>

<properties><property kind="parameter" name="format" required="1"/><property kind="parameter" name="... ..." required="1"/></properties></element>

<element kind="function" name="version_string">
<description>Returns the server software's version string. This is a combination
of the server_version and sys_version class variables.</description>

</element>

<element kind="function" name="date_time_string">
<description>Returns the current date and time, formatted for a message header.</description>

</element>

<element kind="function" name="log_data_time_string">
<description>Returns the current date and time, formatted for logging.</description>

</element>

<element kind="function" name="address_string">
<description>Returns the client address, formatted for logging. A name lookup
is performed on the client's IP address.</description>

</element>

</group>
<group name="SimpleHTTPServer --- Simple HTTP request handler">
<description>This module provides a basic request handler for HTTP
servers.
The SimpleHTTPServer module defines a request-handler class,
interface compatible with BaseHTTPServer.BaseHTTPRequestHandler
which serves files only from a base directory.
The SimpleHTTPServer module defines the following class:
</description>
<element kind="function" name="SimpleHTTPRequestHandler">
<description>This class is used, to serve files from current directory and below,
directly mapping the directory structure to HTTP requests.
A lot of the work is done by the base class
BaseHTTPServer.BaseHTTPRequestHandler, such as parsing the
request. This class implements the do_GET() and
do_HEAD() functions.</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="client_address" required="1"/><property kind="parameter" name="server server" required="1"/></properties></element>

<element kind="function" name="do_HEAD">
<description>This method serves the 'HEAD' request type: it sends the
headers it would send for the equivalent GET request. See the
do_GET() method for more complete explanation of the possible
headers.</description>

</element>

<element kind="function" name="do_GET">
<description>The request is mapped to a local file by interpreting the request as
a path relative to the current working directory.
If the request was mapped to a directory, a 403 respond is output,
followed by the explanation 'Directory listing not supported'.
Any IOError exception in opening the requested file, is mapped
to a 404, 'File not found' error. Otherwise, the content
type is guessed using the extensions_map variable.
A 'Content-type:' with the guessed content type is output, and
then a blank line, signifying end of headers, and then the contents of
the file. The file is always opened in binary mode.
For example usage, see the implementation of the test()
function.</description>

</element>

</group>
<group name="CGIHTTPServer --- CGI-capable HTTP request handler">
<description>This module provides a request handler for HTTP servers
which can run CGI scripts.
The CGIHTTPServer module defines a request-handler class,
interface compatible with
BaseHTTPServer.BaseHTTPRequestHandler and inherits behavior
from SimpleHTTPServer.SimpleHTTPRequestHandler but can also
run CGI scripts.
This module can run CGI scripts on and Windows systems;
on Mac OS it will only be able to run Python scripts within the same
process as itself.
The CGIHTTPServer module defines the following class:
</description>
<element kind="function" name="CGIHTTPRequestHandler">
<description>This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic
structure to local directory structure is exactly as in
SimpleHTTPServer.SimpleHTTPRequestHandler.
The class will however, run the CGI script, instead of serving it as a
file, if it guesses it to be a CGI script. Only directory-based CGI
are used --- the other common server configuration is to treat special
extensions as denoting CGI scripts.
The do_GET() and do_HEAD() functions are
modified to run CGI scripts and serve the output, instead of serving
files, if the request leads to somewhere below the
cgi_directories path.</description>

<properties><property kind="parameter" name="request" required="1"/><property kind="parameter" name="client_address" required="1"/><property kind="parameter" name="server server" required="1"/></properties></element>

<element kind="function" name="do_POST">
<description>This method serves the 'POST' request type, only allowed for
CGI scripts. Error 501, &quot;Can only POST to CGI scripts&quot;, is output
when trying to POST to a non-CGI url.</description>

</element>

</group>
<group name="Cookie --- HTTP state management">
<description>Support for HTTP state management (cookies).
The Cookie module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simple
string-only cookies, and provides an abstraction for having any serializable
data-type as cookie value.
The module formerly strictly applied the parsing rules described in
the 2109 and 2068 specifications. It has since been discovered
that MSIE 3.0x doesn't follow the character rules outlined in those
specs. As a result, the parsing rules used are a bit less strict.
{CookieError}
Exception failing because of 2109 invalidity: incorrect
attributes, incorrect Set-Cookie header, etc.
</description>
<element kind="function" name="BaseCookie">
<description>This class is a dictionary-like object whose keys are strings and
whose values are Morsel instances. Note that upon setting a key to
a value, the value is first converted to a Morsel containing
the key and the value.
If input is given, it is passed to the load() method.</description>

<properties><property kind="parameter" name="input" required="1"/></properties></element>

<element kind="function" name="SimpleCookie">
<description>This class derives from BaseCookie and overrides
value_decode() and value_encode() to be the identity
and str() respectively.</description>

<properties><property kind="parameter" name="input" required="1"/></properties></element>

<element kind="function" name="SerialCookie">
<description>This class derives from BaseCookie and overrides
value_decode() and value_encode() to be the
pickle.loads() and pickle.dumps().
2.3{Reading pickled values from untrusted
cookie data is a huge security hole, as pickle strings can be crafted
to cause arbitrary code to execute on your server. It is supported
for backwards compatibility only, and may eventually go away.}</description>

<properties><property kind="parameter" name="input" required="1"/></properties></element>

<element kind="function" name="SmartCookie">
<description>This class derives from BaseCookie. It overrides
value_decode() to be pickle.loads() if it is a
valid pickle, and otherwise the value itself. It overrides
value_encode() to be pickle.dumps() unless it is a
string, in which case it returns the value itself.
2.3{The same security warning from SerialCookie
applies here.}</description>

<properties><property kind="parameter" name="input" required="1"/></properties></element>

<group name="Cookie Objects">
<element kind="function" name="value_decode">
<description>Return a decoded value from a string representation. Return value can
be any type. This method does nothing in BaseCookie --- it exists
so it can be overridden.</description>

<properties><property kind="parameter" name="valval" required="1"/></properties></element>

<element kind="function" name="value_encode">
<description>Return an encoded value. val can be any type, but return value
must be a string. This method does nothing in BaseCookie --- it exists
so it can be overridden
In general, it should be the case that value_encode() and value_decode() are inverses on the range of value_decode.</description>

<properties><property kind="parameter" name="valval" required="1"/></properties></element>

<element kind="function" name="output">
<description>Return a string representation suitable to be sent as HTTP headers.
attrs and header are sent to each Morsel's
output() method. sep is used to join the headers
together, and is by default a newline.</description>

<properties><property kind="parameter" name="attrs" required="1"/><property kind="parameter" name="header"/><property kind="parameter" name="sep"/></properties></element>

<element kind="function" name="js_output">
<description>Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP headers was sent.
The meaning for attrs is the same as in output().</description>

<properties><property kind="parameter" name="attrs" required="1"/></properties></element>

<element kind="function" name="load">
<description>If rawdata is a string, parse it as an HTTP_COOKIE and add
the values found there as Morsels. If it is a dictionary, it
is equivalent to:
for k, v in rawdata.items():
cookie[k] = v
</description>

<properties><property kind="parameter" name="rawdatarawdata" required="1"/></properties></element>

</group>
<group name="Morsel Objects">
<element kind="function" name="Morsel">
<description>Abstract a key/value pair, which has some 2109 attributes.
Morsels are dictionary-like objects, whose set of keys is constant ---
the valid 2109 attributes, which are
expires
path
comment
domain
max-age
secure
version
The keys are case-insensitive.</description>

</element>

<element kind="function" name="set">
<description>Set the key, value and coded_value members.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="value" required="1"/><property kind="parameter" name="coded_value coded_value" required="1"/></properties></element>

<element kind="function" name="isReservedKey">
<description>Whether K is a member of the set of keys of a Morsel.</description>

<properties><property kind="parameter" name="KK" required="1"/></properties></element>

<element kind="function" name="output">
<description>Return a string representation of the Morsel, suitable
to be sent as an HTTP header. By default, all the attributes are included,
unless attrs is given, in which case it should be a list of attributes
to use. header is by default &quot;Set-Cookie:&quot;.</description>

<properties><property kind="parameter" name="attrs" required="1"/><property kind="parameter" name="header"/></properties></element>

<element kind="function" name="js_output">
<description>Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP header was sent.
The meaning for attrs is the same as in output().</description>

<properties><property kind="parameter" name="attrs" required="1"/></properties></element>

<element kind="function" name="OutputString">
<description>Return a string representing the Morsel, without any surrounding HTTP
or JavaScript.
The meaning for attrs is the same as in output().</description>

<properties><property kind="parameter" name="attrs" required="1"/></properties></element>

</group>
<group name="Example">
</group>
</group>
<group name="xmlrpclib --- XML-RPC client access">
<description>XML-RPC client access.
% Not everyting is documented yet. It might be good to describe % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
New in version 2.2
XML-RPC is a Remote Procedure Call method that uses XML passed via
HTTP as a transport. With it, a client can call methods with
parameters on a remote server (the server is named by a URI) and get back
structured data. This module supports writing XML-RPC client code; it
handles all the details of translating between conformable Python
objects and XML on the wire.
</description>
<element kind="function" name="ServerProxy">
<description>A ServerProxy instance is an object that manages communication
with a remote XML-RPC server. The required first argument is a URI
(Uniform Resource Indicator), and will normally be the URL of the
server. The optional second argument is a transport factory instance;
by default it is an internal SafeTransport instance for https:
URLs and an internal HTTP Transport instance otherwise. The
optional third argument is an encoding, by default UTF-8. The optional
fourth argument is a debugging flag. If allow_none is true, the Python constant None will be translated into XML; the
default behaviour is for None to raise a TypeError.
This is a commonly-used extension to the XML-RPC specification, but isn't
supported by all clients and servers; see
http://ontosys.com/xml-rpc/extensions.html for a description. Both the HTTP and HTTPS transports support the URL syntax extension for
HTTP Basic Authentication: http://user:pass@host:port/path. The user:pass portion will be base64-encoded as an HTTP `Authorization'
header, and sent to the remote server as part of the connection process
when invoking an XML-RPC method. You only need to use this if the
remote server requires a Basic Authentication user and password.
The returned instance is a proxy object with methods that can be used
to invoke corresponding RPC calls on the remote server. If the remote
server supports the introspection API, the proxy can also be used to query
the remote server for the methods it supports (service discovery) and
fetch other server-associated metadata.
ServerProxy instance methods take Python basic types and objects as arguments and return Python basic types and classes. Types that are
conformable (e.g. that can be marshalled through XML), include the
following (and except where noted, they are unmarshalled as the same
Python type):
{l|l}{constant}{Name}{Meaning}
boolean{The True and False constants}
integers{Pass in directly}
floating-point numbers{Pass in directly}
strings{Pass in directly}
arrays{Any Python sequence type containing conformable
elements. Arrays are returned as lists}
structures{A Python dictionary. Keys must be strings,
values may be any conformable type.}
dates{in seconds since the epoch; pass in an instance of the
DateTime wrapper class}
binary data{pass in an instance of the Binary
wrapper class}
This is the full set of data types supported by XML-RPC. Method calls
may also raise a special Fault instance, used to signal
XML-RPC server errors, or ProtocolError used to signal an
error in the HTTP/HTTPS transport layer. Note that even though starting
with Python 2.2 you can subclass builtin types, the xmlrpclib module
currently does not marshal instances of such subclasses.
When passing strings, characters special to XML such as &lt;,
&gt;, and &amp; will be automatically escaped. However, it's
the caller's responsibility to ensure that the string is free of
characters that aren't allowed in XML, such as the control characters
with ASCII values between 0 and 31; failing to do this will result in
an XML-RPC request that isn't well-formed XML. If you have to pass
arbitrary strings via XML-RPC, use the Binary wrapper class
described below.
Server is retained as an alias for ServerProxy for backwards
compatibility. New code should use ServerProxy.</description>

<properties><property kind="parameter" name="uri" required="1"/><property kind="parameter" name="transport"/><property kind="parameter" name="encoding"/><property kind="parameter" name="verbose"/><property kind="parameter" name="allow_none"/></properties></element>

<group name="ServerProxy Objects">
<description>A ServerProxy instance has a method corresponding to
each remote procedure call accepted by the XML-RPC server. Calling
the method performs an RPC, dispatched by both name and argument
signature (e.g. the same method name can be overloaded with multiple
argument signatures). The RPC finishes by returning a value, which
may be either returned data in a conformant type or a Fault or
ProtocolError object indicating an error.
Servers that support the XML introspection API support some common
methods grouped under the reserved system member:
</description>
<element kind="function" name="system.listMethods">
<description>This method returns a list of strings, one for each (non-system)
method supported by the XML-RPC server.</description>

</element>

<element kind="function" name="system.methodSignature">
<description>This method takes one parameter, the name of a method implemented by
the XML-RPC server.It returns an array of possible signatures for this
method. A signature is an array of types. The first of these types is
the return type of the method, the rest are parameters.
Because multiple signatures (ie. overloading) is permitted, this method
returns a list of signatures rather than a singleton.
Signatures themselves are restricted to the top level parameters
expected by a method. For instance if a method expects one array of
structs as a parameter, and it returns a string, its signature is
simply &quot;string, array&quot;. If it expects three integers and returns a
string, its signature is &quot;string, int, int, int&quot;.
If no signature is defined for the method, a non-array value is
returned. In Python this means that the type of the returned value will be something other that list.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="system.methodHelp">
<description>This method takes one parameter, the name of a method implemented by
the XML-RPC server. It returns a documentation string describing the
use of that method. If no such string is available, an empty string is
returned. The documentation string may contain HTML markup.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
<group name="Boolean Objects">
<description>This class may be initialized from any Python value; the instance
returned depends only on its truth value. It supports various Python
operators through __cmp__(), __repr__(),
__int__(), and __nonzero__() methods, all
implemented in the obvious ways.
It also has the following method, supported mainly for internal use by
the unmarshalling code:
</description>
<element kind="function" name="encode">
<description>Write the XML-RPC encoding of this Boolean item to the out stream object.</description>

<properties><property kind="parameter" name="outout" required="1"/></properties></element>

</group>
<group name="DateTime Objects">
<description>This class may initialized from date in seconds since the epoch, a
time tuple, or an ISO 8601 time/date string. It has the following
methods, supported mainly for internal use by the
marshalling/unmarshalling code:
</description>
<element kind="function" name="decode">
<description>Accept a string as the instance's new time value.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="encode">
<description>Write the XML-RPC encoding of this DateTime item to the out stream object.</description>

<properties><property kind="parameter" name="outout" required="1"/></properties></element>

</group>
<group name="Binary Objects">
<description>This class may initialized from string data (which may include NULs).
The primary acess to the content of a Binary object is
provided by an attribute:
[Binary]{data}
The binary data encapsulated by the Binary instance. The data
is provided as an 8-bit string.
Binary objects have the following methods, supported mainly
for internal use by the marshalling/unmarshalling code:
</description>
<element kind="function" name="decode">
<description>Accept a base64 string and decode it as the instance's new data.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="encode">
<description>Write the XML-RPC base 64 encoding of this binary item to the out
stream object.</description>

<properties><property kind="parameter" name="outout" required="1"/></properties></element>

</group>
<group name="Fault Objects">
<description>A Fault object encapsulates the content of an XML-RPC fault tag.
Fault objects have the following members:
{faultCode}
A string indicating the fault type.
{faultString}
A string containing a diagnostic message associated with the fault.
</description>
</group>
<group name="ProtocolError Objects">
<description>A ProtocolError object describes a protocol error in the
underlying transport layer (such as a 404 `not found' error if the
server named by the URI does not exist). It has the following
members:
{url}
The URI or URL that triggered the error.
{errcode}
The error code.
{errmsg}
The error message or diagnostic string.
{headers}
A string containing the headers of the HTTP/HTTPS request that
triggered the error.
</description>
</group>
<group name="MultiCall Objects">
<description>New in version 2.4
In http://www.xmlrpc.com/discuss/msgReader8, an approach
is presented to encapsulate multiple calls to a remote server into
a single request.
</description>
<element kind="function" name="MultiCall">
<description>Create an object used to boxcar method calls. server is the
eventual target of the call. Calls can be made to the result object,
but they will immediately return None, and only store the
call name and parameters in the MultiCall object. Calling
the object itself causes all stored calls to be transmitted as
a single system.multicall request. The result of this call
is a generator; iterating over this generator yields the individual
results.</description>

<properties><property kind="parameter" name="serverserver" required="1"/></properties></element>

</group>
<group name="Convenience Functions">
<element kind="function" name="boolean">
<description>Convert any Python value to one of the XML-RPC Boolean constants,
True or False.</description>

<properties><property kind="parameter" name="valuevalue" required="1"/></properties></element>

<element kind="function" name="binary">
<description>Trivially convert any Python string to a Binary object.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="dumps">
<description>Convert params into an XML-RPC request.
or into a response if methodresponse is true.
params can be either a tuple of arguments or an instance of the Fault exception class. If methodresponse is true,
only a single value can be returned, meaning that params must be of length 1.
encoding, if supplied, is the encoding to use in the generated
XML; the default is UTF-8. Python's None value cannot be
used in standard XML-RPC; to allow using it via an extension, provide a true value for allow_none.</description>

<properties><property kind="parameter" name="params" required="1"/><property kind="parameter" name="methodname"/><property kind="parameter" name="methodresponse"/><property kind="parameter" name="encoding"/><property kind="parameter" name="allow_none"/></properties></element>

<element kind="function" name="loads">
<description>Convert an XML-RPC request or response into Python objects, a
(params, methodname). params is a tuple of argument; methodname
is a string, or None if no method name is present in the packet.
If the XML-RPC packet represents a fault condition, this
function will raise a Fault exception.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

</group>
<group name="Example of Client Usage">
</group>
</group>
<group name="SimpleXMLRPCServer --- Basic XML-RPC server">
<description>Basic XML-RPC server implementation.
The SimpleXMLRPCServer module provides a basic server
framework for XML-RPC servers written in Python. Servers can either
be free standing, using SimpleXMLRPCServer, or embedded in a
CGI environment, using CGIXMLRPCRequestHandler.
</description>
<element kind="function" name="SimpleXMLRPCServer">
<description>Create a new server instance. The requestHandler parameter
should be a factory for request handler instances; it defaults to
SimpleXMLRPCRequestHandler. The addr and
requestHandler parameters are passed to the
SocketServer.TCPServer constructor. If
logRequests is true (the default), requests will be logged;
setting this parameter to false will turn off logging. This class
provides methods for registration of functions that can be called by
the XML-RPC protocol.</description>

<properties><property kind="parameter" name="addr" required="1"/><property kind="parameter" name="requestHandler"/><property kind="parameter" name="logRequests"/></properties></element>

<element kind="function" name="CGIXMLRPCRequestHandler">
<description>Create a new instance to handle XML-RPC requests in a CGI
environment. New in version 2.3</description>

</element>

<element kind="function" name="SimpleXMLRPCRequestHandler">
<description>Create a new request handler instance. This request handler
supports POST requests and modifies logging so that the
logRequests parameter to the SimpleXMLRPCServer
constructor parameter is honored.</description>

</element>

<group name="SimpleXMLRPCServer Objects">
<description>The SimpleXMLRPCServer class is based on
SocketServer.TCPServer and provides a means of creating
simple, stand alone XML-RPC servers.
</description>
<element kind="function" name="register_function">
<description>Register a function that can respond to XML-RPC requests. If
name is given, it will be the method name associated with
function, otherwise function.__name__ will be
used. name can be either a normal or Unicode string, and may
contain characters not legal in Python identifiers, including the
period character.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="name"/></properties></element>

<element kind="function" name="register_instance">
<description>Register an object which is used to expose method names which have
not been registered using register_function(). If
instance contains a _dispatch() method, it is called
with the requested method name and the parameters from the request;
the return value is returned to the client as the result. If
instance does not have a _dispatch() method, it is
searched for an attribute matching the name of the requested method;
if the requested method name contains periods, each component of the
method name is searched for individually, with the effect that a
simple hierarchical search is performed. The value found from this
search is then called with the parameters from the request, and the
return value is passed back to the client.</description>

<properties><property kind="parameter" name="instanceinstance" required="1"/></properties></element>

<element kind="function" name="register_introspection_functions">
<description>Registers the XML-RPC introspection functions system.listMethods,
system.methodHelp and system.methodSignature. New in version 2.3</description>

</element>

<element kind="function" name="register_multicall_functions">
<description>Registers the XML-RPC multicall function system.multicall.</description>

</element>

</group>
<group name="CGIXMLRPCRequestHandler">
<description>The CGIXMLRPCRequestHandler class can be used to handle XML-RPC requests sent to Python CGI scripts.
</description>
<element kind="function" name="register_function">
<description>Register a function that can respond to XML-RPC requests. If name is given, it will be the method name associated with function, otherwise function.__name__ will be used. name
can be either a normal or Unicode string, and may contain characters not legal in Python identifiers, including the period
character.</description>

<properties><property kind="parameter" name="function" required="1"/><property kind="parameter" name="name"/></properties></element>

<element kind="function" name="register_instance">
<description>Register an object which is used to expose method names which have not been registered using register_function(). If instance contains a _dispatch() method, it is called with the requested method name and the parameters from the request; the return value is returned to the client as the result.
If instance does not have a _dispatch() method, it is searched for an attribute matching the name of the requested method; if the requested method name contains periods, each component of the method name is searched for individually, with the effect that a simple hierarchical search is performed. The value found from this search is then called with the parameters from the request, and the return value is passed back to the client.</description>

<properties><property kind="parameter" name="instanceinstance" required="1"/></properties></element>

<element kind="function" name="register_introspection_functions">
<description>Register the XML-RPC introspection functions system.listMethods, system.methodHelp and system.methodSignature.</description>

</element>

<element kind="function" name="register_multicall_functions">
<description>Register the XML-RPC multicall function system.multicall.</description>

</element>

<element kind="function" name="handle_request">
<description>Handle a XML-RPC request. If request_text is given, it should be the POST data provided by the HTTP server, otherwise the contents of stdin will be used.</description>

<properties><property default=" None" kind="parameter" name="request_text" required="1"/></properties></element>

</group>
</group>
<group name="DocXMLRPCServer --- Self-documenting XML-RPC server">
<description>Self-documenting XML-RPC server implementation.
New in version 2.3
The DocXMLRPCServer module extends the classes found in
SimpleXMLRPCServer to serve HTML documentation in response to
HTTP GET requests. Servers can either be free standing, using
DocXMLRPCServer, or embedded in a CGI environment, using
DocCGIXMLRPCRequestHandler.
</description>
<element kind="function" name="DocXMLRPCServer">
<description>Create a new server instance. All parameters have the same meaning as
for SimpleXMLRPCServer.SimpleXMLRPCServer;
requestHandler defaults to DocXMLRPCRequestHandler.</description>

<properties><property kind="parameter" name="addr" required="1"/><property kind="parameter" name="requestHandler"/><property kind="parameter" name="logRequests"/></properties></element>

<element kind="function" name="DocCGIXMLRPCRequestHandler">
<description>Create a new instance to handle XML-RPC requests in a CGI environment.</description>

</element>

<element kind="function" name="DocXMLRPCRequestHandler">
<description>Create a new request handler instance. This request handler supports
XML-RPC POST requests, documentation GET requests, and modifies
logging so that the logRequests parameter to the
DocXMLRPCServer constructor parameter is honored.</description>

</element>

<group name="DocXMLRPCServer Objects">
<description>The DocXMLRPCServer class is derived from
SimpleXMLRPCServer.SimpleXMLRPCServer and provides a means of
creating self-documenting, stand alone XML-RPC servers. HTTP POST
requests are handled as XML-RPC method calls. HTTP GET requests are
handled by generating pydoc-style HTML documentation. This allows a
server to provide its own web-based documentation.
</description>
<element kind="function" name="set_server_title">
<description>Set the title used in the generated HTML documentation. This title
will be used inside the HTML &quot;title&quot; element.</description>

<properties><property kind="parameter" name="server_titleserver_title" required="1"/></properties></element>

<element kind="function" name="set_server_name">
<description>Set the name used in the generated HTML documentation. This name will
appear at the top of the generated documentation inside a &quot;h1&quot;
element.</description>

<properties><property kind="parameter" name="server_nameserver_name" required="1"/></properties></element>

<element kind="function" name="set_server_documentation">
<description>Set the description used in the generated HTML documentation. This
description will appear as a paragraph, below the server name, in the
documentation.</description>

<properties><property kind="parameter" name="server_documentationserver_documentation" required="1"/></properties></element>

</group>
<group name="DocCGIXMLRPCRequestHandler">
<description>The DocCGIXMLRPCRequestHandler class is derived from
SimpleXMLRPCServer.CGIXMLRPCRequestHandler and provides a means
of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests
are handled as XML-RPC method calls. HTTP GET requests are handled by
generating pydoc-style HTML documentation. This allows a server to
provide its own web-based documentation.
</description>
<element kind="function" name="set_server_title">
<description>Set the title used in the generated HTML documentation. This title
will be used inside the HTML &quot;title&quot; element.</description>

<properties><property kind="parameter" name="server_titleserver_title" required="1"/></properties></element>

<element kind="function" name="set_server_name">
<description>Set the name used in the generated HTML documentation. This name will
appear at the top of the generated documentation inside a &quot;h1&quot;
element.</description>

<properties><property kind="parameter" name="server_nameserver_name" required="1"/></properties></element>

<element kind="function" name="set_server_documentation">
<description>Set the description used in the generated HTML documentation. This
description will appear as a paragraph, below the server name, in the
documentation.</description>

<properties><property kind="parameter" name="server_documentationserver_documentation" required="1"/></properties></element>

</group>
</group>
<group name="asyncore --- Asynchronous socket handler">
<description>A base class for developing asynchronous socket handling services.
% Heavily adapted from original documentation by Sam Rushing.
This module provides the basic infrastructure for writing asynchronous socket service clients and servers.
There are only two ways to have a program on a single processor do ``more than one thing at a time.'' Multi-threaded programming is the simplest and most popular way to do it, but there is another very different technique, that lets you have nearly all the advantages of multi-threading, without actually using multiple threads. It's really only practical if your program is largely I/O bound. If your program is processor bound, then pre-emptive scheduled threads are probably what you really need. Network servers are rarely processor bound, however.
If your operating system supports the select() system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the ``background.'' Although this strategy can seem strange and complex, especially at first, it is in many ways easier to understand and control than multi-threaded programming. The asyncore module solves many of the difficult problems for you, making the task of building sophisticated high-performance network servers and clients a snap. For ``conversational'' applications
and protocols the companion asynchat module is invaluable.
The basic idea behind both modules is to create one or more network
channels, instances of class asyncore.dispatcher and
asynchat.async_chat. Creating the channels adds them to a global
map, used by the loop() function if you do not provide it
with your own map.
Once the initial channel(s) is(are) created, calling the loop()
function activates channel service, which continues until the last
channel (including any that have been added to the map during asynchronous
service) is closed.
</description>
<element kind="function" name="loop">
<description>Enter a polling loop that only terminates after all open channels
have been closed. All arguments are optional. The timeout
argument sets the timeout parameter for the appropriate
select() or poll() call, measured in seconds;
the default is 30 seconds. The use_poll parameter, if true,
indicates that poll() should be used in preference to
select() (the default is False). The map parameter
is a dictionary whose items are the channels to watch. As channels
are closed they are deleted from their map. If map is
omitted, a global map is used (this map is updated by the default
class __init__()
-- make sure you extend, rather than override, __init__()
if you want to retain this behavior).
Channels (instances of asyncore.dispatcher, asynchat.async_chat
and subclasses thereof) can freely be mixed in the map.</description>

<properties><property kind="parameter" name="timeout" required="1"/><property kind="parameter" name="use_poll"/><property kind="parameter" name="map"/></properties></element>

<element kind="function" name="dispatcher">
<description>The dispatcher class is a thin wrapper around a low-level socket object.
To make it more useful, it has a few methods for event-handling which are called
from the asynchronous loop. Otherwise, it can be treated as a normal non-blocking socket object.
Two class attributes can be modified, to improve performance,
or possibly even to conserve memory.
{ac_in_buffer_size}
The asynchronous input buffer size (default 4096).
{ac_out_buffer_size}
The asynchronous output buffer size (default 4096).
The firing of low-level events at certain times or in certain connection
states tells the asynchronous loop that certain higher-level events have
taken place. For example, if we have asked for a socket to connect to
another host, we know that the connection has been made when the socket
becomes writable for the first time (at this point you know that you may
write to it with the expectation of success). The implied higher-level
events are:
{l|l}{code}{Event}{Description}
handle_connect(){Implied by the first write event}
handle_close(){Implied by a read event with no data available}
handle_accept(){Implied by a read event on a listening socket}
During asynchronous processing, each mapped channel's readable()
and writable() methods are used to determine whether the channel's
socket should be added to the list of channels select()ed or
poll()ed for read and write events.</description>

</element>

<element kind="function" name="handle_read">
<description>Called when the asynchronous loop detects that a read()
call on the channel's socket will succeed.</description>

</element>

<element kind="function" name="handle_write">
<description>Called when the asynchronous loop detects that a writable socket
can be written. Often this method will implement the necessary buffering for performance. For example:
def handle_write(self):
sent = self.send(self.buffer)
self.buffer = self.buffer[sent:]
</description>

</element>

<element kind="function" name="handle_expt">
<description>Called when there is out of band (OOB) data for a socket connection. This will almost never happen, as OOB is tenuously supported and rarely used.</description>

</element>

<element kind="function" name="handle_connect">
<description>Called when the active opener's socket actually makes a connection.
Might send a ``welcome'' banner, or initiate a protocol
negotiation with the remote endpoint, for example.</description>

</element>

<element kind="function" name="handle_close">
<description>Called when the socket is closed.</description>

</element>

<element kind="function" name="handle_error">
<description>Called when an exception is raised and not otherwise handled. The default
version prints a condensed traceback.</description>

</element>

<element kind="function" name="handle_accept">
<description>Called on listening channels (passive openers) when a connection can be established with a new remote endpoint that
has issued a connect() call for the local endpoint.</description>

</element>

<element kind="function" name="readable">
<description>Called each time around the asynchronous loop to determine whether a
channel's socket should be added to the list on which read events can
occur. The default method simply returns True, indicating that by default, all channels will be interested in
read events.</description>

</element>

<element kind="function" name="writable">
<description>Called each time around the asynchronous loop to determine whether a
channel's socket should be added to the list on which write events can
occur. The default method simply returns True, indicating that by default, all channels will be interested in
write events.</description>

</element>

<element kind="function" name="create_socket">
<description>This is identical to the creation of a normal socket, and will use the same options for creation. Refer to the
socket documentation for information on creating
sockets.</description>

<properties><property kind="parameter" name="family" required="1"/><property kind="parameter" name="type type" required="1"/></properties></element>

<element kind="function" name="connect">
<description>As with the normal socket object, address is a tuple with the first element the host to connect to, and the second the port number.</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="send">
<description>Send data to the remote end-point of the socket.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="recv">
<description>Read at most buffer_size bytes from the socket's remote end-point.
An empty string implies that the channel has been closed from the other
end.</description>

<properties><property kind="parameter" name="buffer_sizebuffer_size" required="1"/></properties></element>

<element kind="function" name="listen">
<description>Listen for connections made to the socket. The backlog
argument specifies the maximum number of queued connections
and should be at least 1; the maximum value is
system-dependent (usually 5).</description>

<properties><property kind="parameter" name="backlogbacklog" required="1"/></properties></element>

<element kind="function" name="bind">
<description>Bind the socket to address. The socket must not already
be bound. (The format of address depends on the address
family --- see above.)</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="accept">
<description>Accept a connection. The socket must be bound to an address
and listening for connections. The return value is a pair
(conn, address) where conn is a
new socket object usable to send and receive data on
the connection, and address is the address bound to the
socket on the other end of the connection.</description>

</element>

<element kind="function" name="close">
<description>Close the socket. All future operations on the socket object
will fail. The remote end-point will receive no more data (after
queued data is flushed). Sockets are automatically closed
when they are garbage-collected.</description>

</element>

<group name="asyncore Example basic HTTP client">
</group>
</group>
<group name="asynchat --- Asynchronous socket command/response handler">
<description>Support for asynchronous command/response protocols.
This module builds on the asyncore infrastructure,
simplifying asynchronous clients and servers and making it easier to
handle protocols whose elements are terminated by arbitrary strings, or
are of variable length. asynchat defines the abstract class
async_chat that you subclass, providing implementations of the
collect_incoming_data() and found_terminator()
methods. It uses the same asynchronous loop as asyncore, and
the two types of channel, asyncore.dispatcher and
asynchat.async_chat, can freely be mixed in the channel map.
Typically an asyncore.dispatcher server channel generates new
asynchat.async_chat channel objects as it receives incoming
connection requests. </description>
<element kind="function" name="async_chat">
<description>This class is an abstract subclass of asyncore.dispatcher. To make
practical use of the code you must subclass async_chat, providing
meaningful collect_incoming_data() and found_terminator()
methods. The asyncore.dispatcher methods can be
used, although not all make sense in a message/response context. Like asyncore.dispatcher, async_chat defines a set of events
that are generated by an analysis of socket conditions after a
select() call. Once the polling loop has been started the
async_chat object's methods are called by the event-processing
framework with no action on the part of the programmer.
Unlike asyncore.dispatcher, async_chat allows you to define
a first-in-first-out queue (fifo) of producers. A producer need have
only one method, more(), which should return data to be transmitted
on the channel. The producer indicates exhaustion (i.e. that it contains
no more data) by having its more() method return the empty string. At
this point the async_chat object removes the producer from the fifo
and starts using the next producer, if any. When the producer fifo is empty
the handle_write() method does nothing. You use the channel object's
set_terminator() method to describe how to recognize the end
of, or an important breakpoint in, an incoming transmission from the
remote endpoint.
To build a functioning async_chat subclass your input methods collect_incoming_data() and
found_terminator() must handle the data that the channel receives
asynchronously. The methods are described below.</description>

</element>

<element kind="function" name="close_when_done">
<description>Pushes a None on to the producer fifo. When this producer is
popped off the fifo it causes the channel to be closed.</description>

</element>

<element kind="function" name="collect_incoming_data">
<description>Called with data holding an arbitrary amount of received data.
The default method, which must be overridden, raises a NotImplementedError exception.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="discard_buffers">
<description>In emergencies this method will discard any data held in the input and/or
output buffers and the producer fifo.</description>

</element>

<element kind="function" name="found_terminator">
<description>Called when the incoming data stream matches the termination condition
set by set_terminator. The default method, which must be overridden,
raises a NotImplementedError exception. The buffered input data should
be available via an instance attribute.</description>

</element>

<element kind="function" name="get_terminator">
<description>Returns the current terminator for the channel.</description>

</element>

<element kind="function" name="handle_close">
<description>Called when the channel is closed. The default method silently closes
the channel's socket.</description>

</element>

<element kind="function" name="handle_read">
<description>Called when a read event fires on the channel's socket in the
asynchronous loop. The default method checks for the termination
condition established by set_terminator(), which can be either
the appearance of a particular string in the input stream or the receipt
of a particular number of characters. When the terminator is found,
handle_read calls the found_terminator() method after
calling collect_incoming_data() with any data preceding the
terminating condition.</description>

</element>

<element kind="function" name="handle_write">
<description>Called when the application may write data to the channel. The default method calls the initiate_send() method, which in turn
will call refill_buffer() to collect data from the producer
fifo associated with the channel.</description>

</element>

<element kind="function" name="push">
<description>Creates a simple_producer object (see below) containing the data and
pushes it on to the channel's producer_fifo to ensure its
transmission. This is all you need to do to have the channel write
the data out to the network, although it is possible to use your
own producers in more complex schemes to implement encryption and
chunking, for example.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="push_with_producer">
<description>Takes a producer object and adds it to the producer fifo associated with
the channel. When all currently-pushed producers have been exhausted
the channel will consume this producer's data by calling its
more() method and send the data to the remote endpoint.</description>

<properties><property kind="parameter" name="producerproducer" required="1"/></properties></element>

<element kind="function" name="readable">
<description>Should return True for the channel to be included in the set of
channels tested by the select() loop for readability.</description>

</element>

<element kind="function" name="refill_buffer">
<description>Refills the output buffer by calling the more() method of the
producer at the head of the fifo. If it is exhausted then the
producer is popped off the fifo and the next producer is activated.
If the current producer is, or becomes, None then the channel
is closed.</description>

</element>

<element kind="function" name="set_terminator">
<description>Sets the terminating condition to be recognised on the channel. term
may be any of three types of value, corresponding to three different ways
to handle incoming protocol data.
{l|l}{}{term}{Description}
string{Will call found_terminator() when the
string is found in the input stream}
integer{Will call found_terminator() when the
indicated number of characters have been received}
None{The channel continues to collect data forever}
Note that any data following the terminator will be available for reading by
the channel after found_terminator() is called.</description>

<properties><property kind="parameter" name="termterm" required="1"/></properties></element>

<element kind="function" name="writable">
<description>Should return True as long as items remain on the producer fifo,
or the channel is connected and the channel's output buffer is non-empty.</description>

</element>

<group name="asynchat - Auxiliary Classes and Functions">
<element kind="function" name="simple_producer">
<description>A simple_producer takes a chunk of data and an optional buffer size.
Repeated calls to its more() method yield successive chunks of the
data no larger than buffer_size.</description>

<properties><property kind="parameter" name="data" required="1"/><property default="512" kind="parameter" name="buffer_size"/></properties></element>

<element kind="function" name="more">
<description>Produces the next chunk of information from the producer, or returns the empty string.</description>

</element>

<element kind="function" name="fifo">
<description>Each channel maintains a fifo holding data which has been pushed by the
application but not yet popped for writing to the channel.
A fifo is a list used to hold data and/or producers until they are required.
If the list argument is provided then it should contain producers or
data items to be written to the channel.</description>

<properties><property default="None" kind="parameter" name="list" required="1"/></properties></element>

<element kind="function" name="is_empty">
<description>Returns True iff the fifo is empty.</description>

</element>

<element kind="function" name="first">
<description>Returns the least-recently push()ed item from the fifo.</description>

</element>

<element kind="function" name="push">
<description>Adds the given data (which may be a string or a producer object) to the
producer fifo.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="pop">
<description>If the fifo is not empty, returns True, first(), deleting the popped
item. Returns False, None for an empty fifo.</description>

</element>

<element kind="function" name="find_prefix_at_end">
<description>Returns True if string haystack ends with any non-empty
prefix of string needle.</description>

<properties><property kind="parameter" name="haystack" required="1"/><property kind="parameter" name="needle needle" required="1"/></properties></element>

</group>
<group name="asynchat Example">
</group>
</group>
</group>
<group name="Internet Data Handling">
<group name="formatter --- Generic output formatting">
<description>Generic output formatter and device interface.
This module supports two interface definitions, each with multiple
implementations. The formatter interface is used by the
HTMLParser class of the htmllib module, and the
writer interface is required by the formatter interface.
(class in htmllib){HTMLParser}
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.
</description>
<group name="The Formatter Interface">
<description>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:
[formatter]{writer}
The writer instance with which the formatter interacts.
</description>
<element kind="function" name="end_paragraph">
<description>Close any open paragraphs and insert at least blanklines
before the next paragraph.</description>

<properties><property kind="parameter" name="blanklinesblanklines" required="1"/></properties></element>

<element kind="function" name="add_line_break">
<description>Add a hard line break if one does not already exist. This does not
break the logical paragraph.</description>

</element>

<element kind="function" name="add_hor_rule">
<description>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.</description>

<properties><property kind="parameter" name="*args" required="1"/><property kind="parameter" name="**kw **kw" required="1"/></properties></element>

<element kind="function" name="add_flowing_data">
<description>Provide data which should be formatted with collapsed whitespace.
Whitespace from preceding and successive calls to
add_flowing_data() is considered as well when the whitespace
collapse is performed. The data which is passed to this method is
expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the
need to rely on device and font information.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="add_literal_data">
<description>Provide data which should be passed to the writer unchanged.
Whitespace, including newline and tab characters, are considered legal
in the value of data.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="add_label_data">
<description>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.</description>

<properties><property kind="parameter" name="format" required="1"/><property kind="parameter" name="counter counter" required="1"/></properties></element>

<element kind="function" name="flush_softspace">
<description>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.</description>

</element>

<element kind="function" name="push_alignment">
<description>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.</description>

<properties><property kind="parameter" name="alignalign" required="1"/></properties></element>

<element kind="function" name="pop_alignment">
<description>Restore the previous alignment.</description>

</element>

<element kind="function" name="push_font">
<description>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.</description>

<properties><property kind="parameter" name="(size" required="1"/><property kind="parameter" name="italic" required="1"/><property kind="parameter" name="bold" required="1"/><property kind="parameter" name="teletype)" required="1"/></properties></element>

<element kind="function" name="pop_font">
<description>Restore the previous font.</description>

</element>

<element kind="function" name="push_margin">
<description>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.</description>

<properties><property kind="parameter" name="marginmargin" required="1"/></properties></element>

<element kind="function" name="pop_margin">
<description>Restore the previous margin.</description>

</element>

<element kind="function" name="push_style">
<description>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.</description>

<properties><property kind="parameter" name="*styles*styles" required="1"/></properties></element>

<element kind="function" name="pop_style">
<description>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.</description>

<properties><property default=" 1" kind="parameter" name="n" required="1"/></properties></element>

<element kind="function" name="set_spacing">
<description>Set the spacing style for the writer.</description>

<properties><property kind="parameter" name="spacingspacing" required="1"/></properties></element>

<element kind="function" name="assert_line_data">
<description>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.</description>

<properties><property default=" 1" kind="parameter" name="flag" required="1"/></properties></element>

</group>
<group name="Formatter Implementations">
<description>Two implementations of formatter objects are provided by this module.
Most applications may use one of these classes without modification or
subclassing.
</description>
<element kind="function" name="NullFormatter">
<description>A formatter which does nothing. If writer is omitted, a
NullWriter instance is created. No methods of the writer are
called by NullFormatter instances. Implementations should
inherit from this class if implementing a writer interface but don't
need to inherit any implementation.</description>

<properties><property kind="parameter" name="writer" required="1"/></properties></element>

<element kind="function" name="AbstractFormatter">
<description>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.</description>

<properties><property kind="parameter" name="writerwriter" required="1"/></properties></element>

</group>
<group name="The Writer Interface">
<description>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.
</description>
<element kind="function" name="flush">
<description>Flush any buffered output or device control events.</description>

</element>

<element kind="function" name="new_alignment">
<description>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'.</description>

<properties><property kind="parameter" name="alignalign" required="1"/></properties></element>

<element kind="function" name="new_font">
<description>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 values specifying which of those
font attributes should be used.</description>

<properties><property kind="parameter" name="fontfont" required="1"/></properties></element>

<element kind="function" name="new_margin">
<description>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.</description>

<properties><property kind="parameter" name="margin" required="1"/><property kind="parameter" name="level level" required="1"/></properties></element>

<element kind="function" name="new_spacing">
<description>Set the spacing style to spacing.</description>

<properties><property kind="parameter" name="spacingspacing" required="1"/></properties></element>

<element kind="function" name="new_styles">
<description>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.</description>

<properties><property kind="parameter" name="stylesstyles" required="1"/></properties></element>

<element kind="function" name="send_line_break">
<description>Break the current line.</description>

</element>

<element kind="function" name="send_paragraph">
<description>Produce a paragraph separation of at least blankline blank
lines, or the equivalent. The blankline value will be an
integer. Note that the implementation will receive a call to
send_line_break() before this call if a line break is needed; this method should not include ending the last line of the paragraph.
It is only responsible for vertical spacing between paragraphs.</description>

<properties><property kind="parameter" name="blanklineblankline" required="1"/></properties></element>

<element kind="function" name="send_hor_rule">
<description>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().</description>

<properties><property kind="parameter" name="*args" required="1"/><property kind="parameter" name="**kw **kw" required="1"/></properties></element>

<element kind="function" name="send_flowing_data">
<description>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.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="send_literal_data">
<description>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.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="send_label_data">
<description>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.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

</group>
<group name="Writer Implementations">
<description>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.
</description>
<element kind="function" name="NullWriter">
<description>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.</description>

</element>

<element kind="function" name="AbstractWriter">
<description>A writer which can be used in debugging formatters, but not much
else. Each method simply announces itself by printing its name and
arguments on standard output.</description>

</element>

<element kind="function" name="DumbWriter">
<description>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.</description>

<properties><property kind="parameter" name="file" required="1"/><property default=" 72" kind="parameter" name="maxcol"/></properties></element>

</group>
</group>
<group name="email --- An email and MIME handling package">
<description>Package supporting the parsing, manipulating, and
generating email messages, including MIME documents.
New in version 2.2
The email package is a library for managing email messages,
including MIME and other 2822-based message documents. It
subsumes most of the functionality in several older standard modules
such as rfc822, mimetools,
multifile, and other non-standard packages such as
mimecntl. It is specifically not designed to do any
sending of email messages to SMTP (2821) servers; that is the
function of the smtplib module. The email
package attempts to be as RFC-compliant as possible, supporting in
addition to 2822, such MIME-related RFCs as
2045-2047, and 2231.
The primary distinguishing feature of the email package is
that it splits the parsing and generating of email messages from the
internal object model representation of email. Applications
using the email package deal primarily with objects; you can
add sub-objects to messages, remove sub-objects from messages,
completely re-arrange the contents, etc. There is a separate parser
and a separate generator which handles the transformation from flat
text to the object model, and then back to flat text again. There
are also handy subclasses for some common MIME object types, and a few
miscellaneous utilities that help with such common tasks as extracting
and parsing message field values, creating RFC-compliant dates, etc.
The following sections describe the functionality of the
email package. The ordering follows a progression that
should be common in applications: an email message is read as flat
text from a file or other source, the text is parsed to produce the
object structure of the email message, this structure is manipulated,
and finally rendered back into flat text.
It is perfectly feasible to create the object structure out of whole
cloth --- i.e. completely from scratch. From there, a similar
progression can be taken as above.
Also included are detailed specifications of all the classes and
modules that the email package provides, the exception
classes you might encounter while using the email package,
some auxiliary utilities, and a few examples. For users of the older
mimelib package, or previous versions of the email
package, a section on differences and porting is provided.
smtplib{SMTP protocol client}
</description>
<group name="Representing an email message">
<description>emailmessage
</description>
</group>
<group name="Parsing email messages">
<description>emailparser
</description>
</group>
<group name="Generating MIME documents">
<description>emailgenerator
</description>
</group>
<group name="Creating email and MIME objects from scratch">
<description>emailmimebase
</description>
</group>
<group name="Internationalized headers">
<description>emailheaders
</description>
</group>
<group name="Representing character sets">
<description>emailcharsets
</description>
</group>
<group name="Encoders">
<description>emailencoders
</description>
</group>
<group name="Exception classes">
<description>emailexc
</description>
</group>
<group name="Miscellaneous utilities">
<description>emailutil
</description>
</group>
<group name="Iterators">
<description>emailiter
</description>
</group>
<group name="Differences from email v1 (up to Python 2.2.1)">
<description>Version 1 of the email package was bundled with Python
releases up to Python 2.2.1. Version 2 was developed for the Python
2.3 release, and backported to Python 2.2.2. It was also available as
a separate distutils based package. email version 2 is
almost entirely backward compatible with version 1, with the
following differences:
The email.Header and email.Charset modules
have been added.
The pickle format for Message instances has changed.
Since this was never (and still isn't) formally defined, this
isn't considered a backward incompatibility. However if your
application pickles and unpickles Message instances, be
aware that in email version 2, Message
instances now have private variables _charset and
_default_type.
Several methods in the Message class have been
deprecated, or their signatures changed. Also, many new methods
have been added. See the documentation for the Message
class for details. The changes should be completely backward
compatible.
The object structure has changed in the face of
message/rfc822 content types. In email
version 1, such a type would be represented by a scalar payload,
i.e. the container message's is_multipart() returned
false, get_payload() was not a list object, but a single
Message instance.
This structure was inconsistent with the rest of the package, so
the object representation for message/rfc822 content
types was changed. In email version 2, the container
does return True from is_multipart(), and
get_payload() returns a list containing a single
Message item.
Note that this is one place that backward compatibility could
not be completely maintained. However, if you're already
testing the return type of get_payload(), you should be
fine. You just need to make sure your code doesn't do a
set_payload() with a Message instance on a
container with a content type of message/rfc822.
The Parser constructor's strict argument was
added, and its parse() and parsestr() methods
grew a headersonly argument. The strict flag was
also added to functions email.message_from_file()
and email.message_from_string().
Generator.__call__() is deprecated; use
Generator.flatten() instead. The Generator
class has also grown the clone() method.
The DecodedGenerator class in the
email.Generator module was added.
The intermediate base classes MIMENonMultipart and
MIMEMultipart have been added, and interposed in the
class hierarchy for most of the other MIME-related derived
classes.
The _encoder argument to the MIMEText constructor
has been deprecated. Encoding now happens implicitly based
on the _charset argument.
The following functions in the email.Utils module have
been deprecated: dump_address_pairs(),
decode(), and encode(). The following
functions have been added to the module:
make_msgid(), decode_rfc2231(),
encode_rfc2231(), and decode_params().
The non-public function email.Iterators._structure()
was added.
</description>
</group>
<group name="Differences from mimelib">
<description>The email package was originally prototyped as a separate
library called
mimelib{http://mimelib.sf.net/}.
Changes have been made so that
method names are more consistent, and some methods or modules have
either been added or removed. The semantics of some of the methods
have also changed. For the most part, any functionality available in
mimelib is still available in the email package,
albeit often in a different way. Backward compatibility between
the mimelib package and the email package was not a
priority.
Here is a brief description of the differences between the
mimelib and the email packages, along with hints on
how to port your applications.
Of course, the most visible difference between the two packages is
that the package name has been changed to email. In
addition, the top-level package has the following differences:
messageFromString() has been renamed to
message_from_string().
messageFromFile() has been renamed to
message_from_file().
The Message class has the following differences:
The method asString() was renamed to as_string().
The method ismultipart() was renamed to
is_multipart().
The get_payload() method has grown a decode
optional argument.
The method getall() was renamed to get_all().
The method addheader() was renamed to add_header().
The method gettype() was renamed to get_type().
The methodgetmaintype() was renamed to
get_main_type().
The method getsubtype() was renamed to
get_subtype().
The method getparams() was renamed to
get_params().
Also, whereas getparams() returned a list of strings,
get_params() returns a list of 2-tuples, effectively
the key/value pairs of the parameters, split on the =
sign.
The method getparam() was renamed to get_param().
The method getcharsets() was renamed to
get_charsets().
The method getfilename() was renamed to
get_filename().
The method getboundary() was renamed to
get_boundary().
The method setboundary() was renamed to
set_boundary().
The method getdecodedpayload() was removed. To get
similar functionality, pass the value 1 to the decode flag
of the {get_payload()} method.
The method getpayloadastext() was removed. Similar
functionality
is supported by the DecodedGenerator class in the
email.Generator module.
The method getbodyastext() was removed. You can get
similar functionality by creating an iterator with
typed_subpart_iterator() in the
email.Iterators module.
The Parser class has no differences in its public interface.
It does have some additional smarts to recognize
message/delivery-status type messages, which it represents as
a Message instance containing separate Message
subparts for each header block in the delivery status
notificationDelivery Status Notifications (DSN) are defined
in 1894..
The Generator class has no differences in its public
interface. There is a new class in the email.Generator
module though, called DecodedGenerator which provides most of
the functionality previously available in the
Message.getpayloadastext() method.
The following modules and classes have been changed:
The MIMEBase class constructor arguments _major
and _minor have changed to _maintype and
_subtype respectively.
The Image class/module has been renamed to
MIMEImage. The _minor argument has been renamed to
_subtype.
The Text class/module has been renamed to
MIMEText. The _minor argument has been renamed to
_subtype.
The MessageRFC822 class/module has been renamed to
MIMEMessage. Note that an earlier version of
mimelib called this class/module RFC822, but
that clashed with the Python standard library module
rfc822 on some case-insensitive file systems.
Also, the MIMEMessage class now represents any kind of
MIME message with main type message. It takes an
optional argument _subtype which is used to set the MIME
subtype. _subtype defaults to rfc822.
mimelib provided some utility functions in its
address and date modules. All of these functions
have been moved to the email.Utils module.
The MsgReader class/module has been removed. Its functionality
is most closely supported in the body_line_iterator()
function in the email.Iterators module.
</description>
</group>
<group name="Examples">
</group>
</group>
<group name="mailcap --- Mailcap file handling.">
<description>Mailcap file handling.
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 . Then, if the user encounters an email
message or Web document with the MIME type video/mpeg,
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 1524, ``A User Agent
Configuration Mechanism For Multimedia Mail Format Information,'' but
is not an Internet standard. However, mailcap files are supported on
most systems.
</description>
<element kind="function" name="findmatch">
<description>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 1524 for a complete list of these
fields.
filename is the filename to be substituted for 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 (such as 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.</description>

<properties><property kind="parameter" name="caps" required="1"/><property kind="parameter" name="MIMEtype%" required="1"/><property kind="parameter" name="key"/><property kind="parameter" name="filename"/><property kind="parameter" name="plist"/></properties></element>

<element kind="function" name="getcaps">
<description>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 /.mailcap
will override settings in the system mailcap files
/etc/mailcap, /usr/etc/mailcap, and
/usr/local/etc/mailcap.</description>

</element>

</group>
<group name="mailbox --- Read various mailbox formats">
<description>Read various mailbox formats.
This module defines a number of classes that allow easy and uniform
access to mail messages in a () mailbox.
</description>
<element kind="function" name="UnixMailbox">
<description>Access to a classic -style mailbox, where all messages are
contained in a single file and separated by From (a.k.a. From_) lines. The file object fp points to the
mailbox file. The optional factory parameter is a callable that
should create new message objects. factory is called with one
argument, fp by the next() method of the mailbox
object. The default is the rfc822.Message class (see the
rfc822 module -- and the note below).
For maximum portability, messages in a -style mailbox are
separated by any line that begins exactly with the string 'From
' (note the trailing space) if preceded by exactly two newlines.
Because of the wide-range of variations in practice, nothing else on
the From_ line should be considered. However, the current
implementation doesn't check for the leading two newlines. This is
usually fine for most applications.
The UnixMailbox class implements a more strict version of
From_ line checking, using a regular expression that usually correctly
matched From_ delimiters. It considers delimiter line to be separated
by From name time lines. For maximum portability,
use the PortableUnixMailbox class instead. This class is
identical to UnixMailbox except that individual messages are
separated by only From lines.
For more information, see
Configuring
Netscape Mail on : Why the Content-Length Format is Bad.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="factory"/></properties></element>

<element kind="function" name="PortableUnixMailbox">
<description>A less-strict version of UnixMailbox, which considers only the
From at the beginning of the line separating messages. The
``name time'' portion of the From line is ignored, to
protect against some variations that are observed in practice. This
works since lines in the message which begin with 'From ' are
quoted by mail handling software at delivery-time.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="factory"/></properties></element>

<element kind="function" name="MmdfMailbox">
<description>Access an MMDF-style mailbox, where all messages are contained
in a single file and separated by lines consisting of 4 control-A
characters. The file object fp points to the mailbox file.
Optional factory is as with the UnixMailbox class.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="factory"/></properties></element>

<element kind="function" name="MHMailbox">
<description>Access an MH mailbox, a directory with each message in a separate
file with a numeric name.
The name of the mailbox directory is passed in dirname.
factory is as with the UnixMailbox class.</description>

<properties><property kind="parameter" name="dirname" required="1"/><property kind="parameter" name="factory"/></properties></element>

<element kind="function" name="Maildir">
<description>Access a Qmail mail directory. All new and current mail for the
mailbox specified by dirname is made available.
factory is as with the UnixMailbox class.</description>

<properties><property kind="parameter" name="dirname" required="1"/><property kind="parameter" name="factory"/></properties></element>

<element kind="function" name="BabylMailbox">
<description>Access a Babyl mailbox, which is similar to an MMDF mailbox. In
Babyl format, each message has two sets of headers, the
original headers and the visible headers. The original
headers appear before a line containing only '*** EOOH ***'
(End-Of-Original-Headers) and the visible headers appear after the
EOOH line. Babyl-compliant mail readers will show you only the
visible headers, and BabylMailbox objects will return messages
containing only the visible headers. You'll have to do your own
parsing of the mailbox file to get at the original headers. Mail
messages start with the EOOH line and end with a line containing only
'037014'. factory is as with the
UnixMailbox class.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="factory"/></properties></element>

<group name="Mailbox Objects">
<description>All implementations of mailbox objects are iterable objects, and
have one externally visible method. This method is used by iterators
created from mailbox objects and may also be used directly.
</description>
<element kind="function" name="next">
<description>Return the next message in the mailbox, created with the optional
factory argument passed into the mailbox object's constructor.
By default this is an rfc822.Message
object (see the rfc822 module). 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. If no more messages are available,
this method returns None.</description>

</element>

</group>
</group>
<group name="mhlib --- Access to MH mailboxes">
<description>% LaTeX'ized from the comments in the module by Skip Montanaro
% &lt;skip@mojam.com&gt;.
Manipulate MH mailboxes from Python.
The mhlib module provides a Python interface to MH folders and
their contents.
The module contains three basic classes, MH, which represents a
particular collection of folders, Folder, which represents a single
folder, and Message, which represents a single message.
</description>
<element kind="function" name="MH">
<description>MH represents a collection of MH folders.</description>

<properties><property kind="parameter" name="path" required="1"/><property kind="parameter" name="profile"/></properties></element>

<element kind="function" name="Folder">
<description>The Folder class represents a single folder and its messages.</description>

<properties><property kind="parameter" name="mh" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="Message">
<description>Message objects represent individual messages in a folder. The
Message class is derived from mimetools.Message.</description>

<properties><property kind="parameter" name="folder" required="1"/><property kind="parameter" name="number" required="1"/><property kind="parameter" name="name"/></properties></element>

<group name="MH Objects">
<description>MH instances have the following methods:
</description>
<element kind="function" name="error">
<description>Print an error message -- can be overridden.</description>

<properties><property kind="parameter" name="format" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="getprofile">
<description>Return a profile entry (None if not set).</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="getpath">
<description>Return the mailbox pathname.</description>

</element>

<element kind="function" name="getcontext">
<description>Return the current folder name.</description>

</element>

<element kind="function" name="setcontext">
<description>Set the current folder name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="listfolders">
<description>Return a list of top-level folders.</description>

</element>

<element kind="function" name="listallfolders">
<description>Return a list of all folders.</description>

</element>

<element kind="function" name="listsubfolders">
<description>Return a list of direct subfolders of the given folder.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="listallsubfolders">
<description>Return a list of all subfolders of the given folder.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="makefolder">
<description>Create a new folder.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="deletefolder">
<description>Delete a folder -- must have no subfolders.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="openfolder">
<description>Return a new open folder object.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
<group name="Folder Objects">
<description>Folder instances represent open folders and have the following
methods:
</description>
<element kind="function" name="error">
<description>Print an error message -- can be overridden.</description>

<properties><property kind="parameter" name="format" required="1"/><property kind="parameter" name="..."/></properties></element>

<element kind="function" name="getfullname">
<description>Return the folder's full pathname.</description>

</element>

<element kind="function" name="getsequencesfilename">
<description>Return the full pathname of the folder's sequences file.</description>

</element>

<element kind="function" name="getmessagefilename">
<description>Return the full pathname of message n of the folder.</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="listmessages">
<description>Return a list of messages in the folder (as numbers).</description>

</element>

<element kind="function" name="getcurrent">
<description>Return the current message number.</description>

</element>

<element kind="function" name="setcurrent">
<description>Set the current message number to n.</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="parsesequence">
<description>Parse msgs syntax into list of messages.</description>

<properties><property kind="parameter" name="seqseq" required="1"/></properties></element>

<element kind="function" name="getlast">
<description>Get last message, or 0 if no messages are in the folder.</description>

</element>

<element kind="function" name="setlast">
<description>Set last message (internal use only).</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="getsequences">
<description>Return dictionary of sequences in folder. The sequence names are used as keys, and the values are the lists of message numbers in the
sequences.</description>

</element>

<element kind="function" name="putsequences">
<description>Return dictionary of sequences in folder {name: list}.</description>

<properties><property kind="parameter" name="dictdict" required="1"/></properties></element>

<element kind="function" name="removemessages">
<description>Remove messages in list from folder.</description>

<properties><property kind="parameter" name="listlist" required="1"/></properties></element>

<element kind="function" name="refilemessages">
<description>Move messages in list to other folder.</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="tofolder tofolder" required="1"/></properties></element>

<element kind="function" name="movemessage">
<description>Move one message to a given destination in another folder.</description>

<properties><property kind="parameter" name="n" required="1"/><property kind="parameter" name="tofolder" required="1"/><property kind="parameter" name="ton ton" required="1"/></properties></element>

<element kind="function" name="copymessage">
<description>Copy one message to a given destination in another folder.</description>

<properties><property kind="parameter" name="n" required="1"/><property kind="parameter" name="tofolder" required="1"/><property kind="parameter" name="ton ton" required="1"/></properties></element>

</group>
<group name="Message Objects">
<description>The Message class adds one method to those of
mimetools.Message:
</description>
<element kind="function" name="openmessage">
<description>Return a new open message object (costs a file descriptor).</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

</group>
</group>
<group name="mimetools --- Tools for parsing MIME messages">
<description>Tools for parsing MIME-style message bodies.
2.3{The email package should be used in
preference to the mimetools module. This
module is present only to maintain backward
compatibility.}
This module defines a subclass of the
rfc822rfc822 module's
Message class and a number of utility functions that are
useful for the manipulation for MIME multipart or encoded message.
It defines the following items:
</description>
<element kind="function" name="Message">
<description>Return a new instance of the Message class. This is a
subclass of the rfc822.Message class, with some additional
methods (see below). The seekable argument has the same meaning
as for rfc822.Message.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="seekable"/></properties></element>

<element kind="function" name="choose_boundary">
<description>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'.</description>

</element>

<element kind="function" name="decode">
<description>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', 'uuencode',
'x-uuencode', 'uue', 'x-uue', '7bit', and '8bit'. Decoding messages encoded in '7bit' or '8bit'
has no effect. The input is simply copied to the output.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output" required="1"/><property kind="parameter" name="encoding encoding" required="1"/></properties></element>

<element kind="function" name="encode">
<description>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().</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output" required="1"/><property kind="parameter" name="encoding encoding" required="1"/></properties></element>

<element kind="function" name="copyliteral">
<description>Read lines from open file input until and write them to
open file output.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output output" required="1"/></properties></element>

<element kind="function" name="copybinary">
<description>Read blocks until from open file input and write them to
open file output. The block size is currently fixed at 8192.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output output" required="1"/></properties></element>

<group name="Additional Methods of Message Objects">
<description>The Message class defines the following methods in
addition to the rfc822.Message methods:
</description>
<element kind="function" name="getplist">
<description>Return the parameter list of the Content-Type header.
This is a list of 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'].</description>

</element>

<element kind="function" name="getparam">
<description>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
`&lt;...&gt;' or `&quot;...&quot;', these are removed.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getencoding">
<description>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.</description>

</element>

<element kind="function" name="gettype">
<description>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.</description>

</element>

<element kind="function" name="getmaintype">
<description>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.</description>

</element>

<element kind="function" name="getsubtype">
<description>Return the subtype as specified in the Content-Type
header. If no such header exists, return 'plain'. The subtype
is converted to lower case.</description>

</element>

</group>
</group>
<group name="mimetypes --- Map filenames to MIME types">
<description>Mapping of filename extensions to MIME types.
The mimetypes module converts between a filename or URL and
the MIME type associated with the filename extension. Conversions are
provided from filename to MIME type and from MIME type to filename
extension; encodings are not supported for the latter conversion.
The module provides one class and a number of convenience functions.
The functions are the normal interface to this module, but some
applications may be interested in the class as well.
The functions described below provide the primary interface for this
module. If the module has not been initialized, they will call
init() if they rely on the information init()
sets up.
</description>
<element kind="function" name="guess_type">
<description>Guess the type of a file based on its filename or URL, given by
filename. The return value is a tuple (type,
encoding) where type is None if the type can't be
guessed (missing or unknown suffix) or a string of the form
'type/subtype', usable for a MIME
content-type header.
encoding is None for no encoding or the name of the
program used to encode (e.g. compress or gzip).
The encoding is suitable for use as a Content-Encoding
header, not as a Content-Transfer-Encoding header.
The mappings are table driven. Encoding suffixes are case sensitive;
type suffixes are first tried case sensitively, then case
insensitively.
Optional strict is a flag specifying whether the list of known
MIME types is limited to only the official types registered
with IANA{http://www.isi.edu/in-notes/iana/assignments/media-types}
are recognized. When strict is true (the default), only the
IANA types are supported; when strict is false, some additional
non-standard but commonly used MIME types are also recognized.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="strict"/></properties></element>

<element kind="function" name="guess_all_extensions">
<description>Guess the extensions for a file based on its MIME type, given by
type.
The return value is a list of strings giving all possible filename extensions,
including the leading dot (.). The extensions are not guaranteed
to have been associated with any particular data stream, but would be mapped
to the MIME type type by guess_type().
Optional strict has the same meaning as with the
guess_type() function.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="strict"/></properties></element>

<element kind="function" name="guess_extension">
<description>Guess the extension for a file based on its MIME type, given by
type.
The return value is a string giving a filename extension, including the
leading dot (.). The extension is not guaranteed to have been
associated with any particular data stream, but would be mapped to the MIME type type by guess_type(). If no extension can
be guessed for type, None is returned.
Optional strict has the same meaning as with the
guess_type() function.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="strict"/></properties></element>

<element kind="function" name="init">
<description>Initialize the internal data structures. If given, files must
be a sequence of file names which should be used to augment the
default type map. If omitted, the file names to use are taken from
knownfiles. Each file named in files or
knownfiles takes precedence over those named before it.
Calling init() repeatedly is allowed.</description>

<properties><property kind="parameter" name="files" required="1"/></properties></element>

<element kind="function" name="read_mime_types">
<description>Load the type map given in the file filename, if it exists. The type map is returned as a dictionary mapping filename extensions,
including the leading dot (.), to strings of the form
'type/subtype'. If the file filename does
not exist or cannot be read, None is returned.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="add_type">
<description>Add a mapping from the mimetype type to the extension ext.
When the extension is already known, the new type will replace the old
one. When the type is already known the extension will be added
to the list of known extensions.
When strict is the mapping will added to the official
MIME types, otherwise to the non-standard ones.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="ext" required="1"/><property kind="parameter" name="strict"/></properties></element>

<element kind="function" name="MimeTypes">
<description>This class represents a MIME-types database. By default, it
provides access to the same database as the rest of this module.
The initial database is a copy of that provided by the module, and
may be extended by loading additional mime.types-style files
into the database using the read() or readfp()
methods. The mapping dictionaries may also be cleared before
loading additional data if the default data is not desired.
The optional filenames parameter can be used to cause
additional files to be loaded ``on top'' of the default database.
New in version 2.2</description>

<properties><property kind="parameter" name="filenames" required="1"/></properties></element>

<group name="MimeTypes Objects">
<description>MimeTypes instances provide an interface which is very like
that of the mimetypes module.
{suffix_map}
Dictionary mapping suffixes to suffixes. This is used to allow
recognition of encoded files for which the encoding and the type are
indicated by the same extension. For example, the .tgz
extension is mapped to .tar.gz to allow the encoding and type
to be recognized separately. This is initially a copy of the global
suffix_map defined in the module.
{encodings_map}
Dictionary mapping filename extensions to encoding types. This is
initially a copy of the global encodings_map defined in the
module.
{types_map}
Dictionary mapping filename extensions to MIME types. This is
initially a copy of the global types_map defined in the
module.
{common_types}
Dictionary mapping filename extensions to non-standard, but commonly
found MIME types. This is initially a copy of the global
common_types defined in the module.
</description>
<element kind="function" name="guess_extension">
<description>Similar to the guess_extension() function, using the
tables stored as part of the object.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="strict"/></properties></element>

<element kind="function" name="guess_type">
<description>Similar to the guess_type() function, using the tables
stored as part of the object.</description>

<properties><property kind="parameter" name="url" required="1"/><property kind="parameter" name="strict"/></properties></element>

<element kind="function" name="read">
<description>Load MIME information from a file named path. This uses
readfp() to parse the file.</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="readfp">
<description>Load MIME type information from an open file. The file must have
the format of the standard mime.types files.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

</group>
</group>
<group name="MimeWriter --- Generic MIME file writer">
<description>Generic MIME file writer.
2.3{The email package should be used in
preference to the MimeWriter module. This
module is present only to maintain backward
compatibility.}
This module defines the class MimeWriter. The
MimeWriter class implements a basic formatter for creating
MIME multi-part files. It doesn't seek around the output file nor
does it use large amounts of buffer space. You must write the parts
out in the order that they should occur in the final
file. MimeWriter does buffer the headers you add, allowing you to rearrange their order.
</description>
<element kind="function" name="MimeWriter">
<description>Return a new instance of the MimeWriter class. The only
argument passed, fp, is a file object to be used for
writing. Note that a StringIO object could also be used.</description>

<properties><property kind="parameter" name="fpfp" required="1"/></properties></element>

<group name="MimeWriter Objects">
<description>MimeWriter instances have the following methods:
</description>
<element kind="function" name="addheader">
<description>Add a header line to the MIME message. The key is the name of
the header, where the value obviously provides the value of the
header. The optional argument prefix determines where the header is inserted; 0 means append at the end, 1 is insert at
the start. The default is to append.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="value" required="1"/><property kind="parameter" name="prefix"/></properties></element>

<element kind="function" name="flushheaders">
<description>Causes all headers accumulated so far to be written out (and
forgotten). This is useful if you don't need a body part at all,
e.g. a subpart of type message/rfc822 that's (mis)used
to store some header-like information.</description>

</element>

<element kind="function" name="startbody">
<description>Returns a file-like object which can be used to write to the
body of the message. The content-type is set to the provided
ctype, and the optional parameter plist provides
additional parameters for the content-type declaration. prefix
functions as in addheader() except that the default is to
insert at the start.</description>

<properties><property kind="parameter" name="ctype" required="1"/><property kind="parameter" name="plist"/><property kind="parameter" name="prefix"/></properties></element>

<element kind="function" name="startmultipartbody">
<description>Returns a file-like object which can be used to write to the
body of the message. Additionally, this method initializes the
multi-part code, where subtype provides the multipart subtype,
boundary may provide a user-defined boundary specification, and
plist provides optional parameters for the subtype.
prefix functions as in startbody(). Subparts should be
created using nextpart().</description>

<properties><property kind="parameter" name="subtype" required="1"/><property kind="parameter" name="boundary"/><property kind="parameter" name="plist"/><property kind="parameter" name="prefix"/></properties></element>

<element kind="function" name="nextpart">
<description>Returns a new instance of MimeWriter which represents an
individual part in a multipart message. This may be used to write the part as well as used for creating recursively complex multipart
messages. The message must first be initialized with
startmultipartbody() before using nextpart().</description>

</element>

<element kind="function" name="lastpart">
<description>This is used to designate the last part of a multipart message, and
should always be used when writing multipart messages.</description>

</element>

</group>
</group>
<group name="mimify --- MIME processing of mail messages">
<description>Mimification and unmimification of mail messages.
2.3{The email package should be used in
preference to the mimify module. This
module is present only to maintain backward
compatibility.}
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 . 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:
</description>
<element kind="function" name="mimify">
<description>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.</description>

<properties><property kind="parameter" name="infile" required="1"/><property kind="parameter" name="outfile outfile" required="1"/></properties></element>

<element kind="function" name="unmimify">
<description>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.</description>

<properties><property kind="parameter" name="infile" required="1"/><property kind="parameter" name="outfile" required="1"/><property kind="parameter" name="decode_base64"/></properties></element>

<element kind="function" name="mime_decode_header">
<description>Return a decoded version of the encoded header line in line.
This only supports the ISO 8859-1 charset (Latin-1).</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="mime_encode_header">
<description>Return a MIME-encoded version of the header line in line.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

</group>
<group name="multifile --- Support for files containing distinct parts">
<description>Support for reading files which contain distinct
parts, such as some MIME data.
The MultiFile object enables you to treat sections of a text
file as file-like input objects, with '' being returned by
readline() when a given delimiter pattern is encountered. The
defaults of this class are designed to make it useful for parsing
MIME multipart messages, but by subclassing it and overriding methods it can be easily adapted for more general use.
</description>
<element kind="function" name="MultiFile">
<description>Create a multi-file. You must instantiate this class with an input
object argument for the MultiFile instance to get lines from,
such as a file object returned by open().
MultiFile only ever looks at the input object's
readline(), seek() and tell() methods, and
the latter two are only needed if you want random access to the
individual MIME parts. To use MultiFile on a non-seekable
stream object, set the optional seekable argument to false; this
will prevent using the input object's seek() and
tell() methods.</description>

<properties><property kind="parameter" name="fp" required="1"/><property kind="parameter" name="seekable"/></properties></element>

<group name="MultiFile Objects">
<description>A MultiFile instance has the following methods:
</description>
<element kind="function" name="readline">
<description>Read a line. If the line is data (not a section-divider or end-marker
or real EOF) return it. If the line matches the most-recently-stacked
boundary, return '' and set self.last to 1 or 0 according as
the match is or is not an end-marker. If the line matches any other
stacked boundary, raise an error. On encountering end-of-file on the
underlying stream object, the method raises Error unless
all boundaries have been popped.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="readlines">
<description>Return all lines remaining in this part as a list of strings.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="read">
<description>Read all lines, up to the next section. Return them as a single
(multiline) string. Note that this doesn't take a size argument!</description>

</element>

<element kind="function" name="seek">
<description>Seek. Seek indices are relative to the start of the current section.
The pos and whence arguments are interpreted as for a file
seek.</description>

<properties><property kind="parameter" name="pos" required="1"/><property kind="parameter" name="whence"/></properties></element>

<element kind="function" name="tell">
<description>Return the file position relative to the start of the current section.</description>

</element>

<element kind="function" name="next">
<description>Skip lines to the next section (that is, read lines until a
section-divider or end-marker has been consumed). Return true if
there is such a section, false if an end-marker is seen. Re-enable
the most-recently-pushed boundary.</description>

</element>

<element kind="function" name="is_data">
<description>Return true if str is data and false if it might be a section
boundary. As written, it tests for a prefix other than '--' at
start of line (which all MIME boundaries have) but it is declared so
it can be overridden in derived classes.
Note that this test is used intended as a fast guard for the real
boundary tests; if it always returns false it will merely slow
processing, not cause it to fail.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="push">
<description>Push a boundary string. When an appropriately decorated version of
this boundary is found as an input line, it will be interpreted as a
section-divider or end-marker. All subsequent
reads will return the empty string to indicate end-of-file, until a
call to pop() removes the boundary a or next() call
reenables it.
It is possible to push more than one boundary. Encountering the
most-recently-pushed boundary will return EOF; encountering any other
boundary will raise an error.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="pop">
<description>Pop a section boundary. This boundary will no longer be interpreted
as EOF.</description>

</element>

<element kind="function" name="section_divider">
<description>Turn a boundary into a section-divider line. By default, this
method prepends '--' (which MIME section boundaries have) but
it is declared so it can be overridden in derived classes. This
method need not append LF or CR-LF, as comparison with the result
ignores trailing whitespace.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="end_marker">
<description>Turn a boundary string into an end-marker line. By default, this
method prepends '--' and appends '--' (like a
MIME-multipart end-of-message marker) but it is declared so it can be
overridden in derived classes. This method need not append LF or
CR-LF, as comparison with the result ignores trailing whitespace.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

</group>
<group name="MultiFile Example">
</group>
</group>
<group name="rfc822 --- Parse RFC 2822 mail headers">
<description>Parse 2822 style mail messages.
2.3{The email package should be used in
preference to the rfc822 module. This
module is present only to maintain backward
compatibility.}
This module defines a class, Message, which represents an
``email message'' as defined by the Internet standard
2822.This module originally conformed to 822,
hence the name. Since then, 2822 has been released as an
update to 822. This module should be considered
2822-conformant, especially in cases where the
syntax or semantics have changed since 822. Such messages
consist of a collection of message headers, and a message body. This
module also defines a helper class
AddressList for parsing 2822 addresses. Please refer to
the RFC for information on the specific syntax of 2822 messages.
The mailboxmailbox module provides classes to read mailboxes produced by various end-user mail programs.
</description>
<element kind="function" name="Message">
<description>A Message instance is instantiated with an input object as
parameter. Message relies only on the input object having a
readline() method; in particular, ordinary file objects
qualify. Instantiation reads headers from the input object up to a
delimiter line (normally a blank line) and stores them in the
instance. The message body, following the headers, is not consumed.
This class can work with any input object that supports a
readline() method. If the input object has seek and tell
capability, the rewindbody() method will work; also, illegal
lines will be pushed back onto the input stream. If the input object
lacks seek but has an unread() method that can push back a
line of input, Message will use that to push back illegal
lines. Thus this class can be used to parse messages coming from a
buffered stream.
The optional seekable argument is provided as a workaround for
certain stdio libraries in which tell() discards buffered
data before discovering that the lseek() system call
doesn't work. For maximum portability, you should set the seekable
argument to zero to prevent that initial tell() when passing
in an unseekable object such as a file object created from a socket
object.
Input lines as read from the file may either be terminated by CR-LF or
by a single linefeed; a terminating CR-LF is replaced by a single
linefeed before the line is stored.
All header matching is done independent of upper or lower case;
e.g. m['From'], m['from'] and
m['FROM'] all yield the same result.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="seekable"/></properties></element>

<element kind="function" name="AddressList">
<description>You may instantiate the AddressList helper class using a single
string parameter, a comma-separated list of 2822 addresses to be
parsed. (The parameter None yields an empty list.)</description>

<properties><property kind="parameter" name="fieldfield" required="1"/></properties></element>

<element kind="function" name="quote">
<description>Return a new string with backslashes in str replaced by two
backslashes and double quotes replaced by backslash-double quote.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="unquote">
<description>Return a new string which is an unquoted version of str.
If str ends and begins with double quotes, they are stripped
off. Likewise if str ends and begins with angle brackets, they
are stripped off.</description>

<properties><property kind="parameter" name="strstr" required="1"/></properties></element>

<element kind="function" name="parseaddr">
<description>Parse address, which should be the value of some
address-containing field such as To or Cc,
into its constituent ``realname'' and ``email address'' parts.
Returns a tuple of that information, unless the parse fails, in which
case a 2-tuple (None, None) is returned.</description>

<properties><property kind="parameter" name="addressaddress" required="1"/></properties></element>

<element kind="function" name="dump_address_pair">
<description>The inverse of parseaddr(), this takes a 2-tuple of the form
(realname, email_address) and returns the string
value suitable for a To or Cc header. If
the first element of pair is false, then the second element is
returned unmodified.</description>

<properties><property kind="parameter" name="pairpair" required="1"/></properties></element>

<element kind="function" name="parsedate">
<description>Attempts to parse a date according to the rules in 2822.
however, some mailers don't follow that format as specified, so
parsedate() tries to guess correctly in such cases. date is a string containing an 2822 date, such as 'Mon, 20 Nov 1995 19:12:08 -0500'. If it succeeds in parsing
the date, parsedate() returns a 9-tuple that can be passed
directly to time.mktime(); otherwise None will be
returned. Note that fields 6, 7, and 8 of the result tuple are not
usable.</description>

<properties><property kind="parameter" name="datedate" required="1"/></properties></element>

<element kind="function" name="parsedate_tz">
<description>Performs the same function as parsedate(), but returns
either None or a 10-tuple; the first 9 elements make up a tuple
that can be passed directly to time.mktime(), and the tenth
is the offset of the date's timezone from UTC (which is the official
term for Greenwich Mean Time). (Note that the sign of the timezone
offset is the opposite of the sign of the time.timezone
variable for the same timezone; the latter variable follows the
standard while this module follows 2822.) If the input
string has no timezone, the last element of the tuple returned is
None. Note that fields 6, 7, and 8 of the result tuple are not
usable.</description>

<properties><property kind="parameter" name="datedate" required="1"/></properties></element>

<element kind="function" name="mktime_tz">
<description>Turn a 10-tuple as returned by parsedate_tz() into a UTC
timestamp. If the timezone item in the tuple is None, assume
local time. Minor deficiency: this first interprets the first 8
elements as a local time and then compensates for the timezone
difference; this may yield a slight error around daylight savings time
switch dates. Not enough to worry about for common use.</description>

<properties><property kind="parameter" name="tupletuple" required="1"/></properties></element>

<group name="Message Objects">
<description>A Message instance has the following methods:
</description>
<element kind="function" name="rewindbody">
<description>Seek to the start of the message body. This only works if the file
object is seekable.</description>

</element>

<element kind="function" name="isheader">
<description>Returns a line's canonicalized fieldname (the dictionary key that will
be used to index it) if the line is a legal 2822 header; otherwise
returns None (implying that parsing should stop here and the
line be pushed back on the input stream). It is sometimes useful to
override this method in a subclass.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="islast">
<description>Return true if the given line is a delimiter on which Message should
stop. The delimiter line is consumed, and the file object's read
location positioned immediately after it. By default this method just
checks that the line is blank, but you can override it in a subclass.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="iscomment">
<description>Return True if the given line should be ignored entirely, just skipped.
By default this is a stub that always returns False, but you can
override it in a subclass.</description>

<properties><property kind="parameter" name="lineline" required="1"/></properties></element>

<element kind="function" name="getallmatchingheaders">
<description>Return a list of lines consisting of all headers matching
name, if any. Each physical line, whether it is a continuation
line or not, is a separate list item. Return the empty list if no
header matches name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getfirstmatchingheader">
<description>Return a list of lines comprising the first header matching
name, and its continuation line(s), if any. Return
None if there is no header matching name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getrawheader">
<description>Return a single string consisting of the text after the colon in the
first header matching name. This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present. Return None if there is
no header matching name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getheader">
<description>Like getrawheader(name), but strip leading and trailing
whitespace. Internal whitespace is not stripped. The optional
default argument can be used to specify a different default to
be returned when there is no header matching name.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="get">
<description>An alias for getheader(), to make the interface more compatible with regular dictionaries.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="default"/></properties></element>

<element kind="function" name="getaddr">
<description>Return a pair (full name, email address) parsed
from the string returned by getheader(name). If no
header matching name exists, return (None, None);
otherwise both the full name and the address are (possibly empty)
strings.
Example: If m's first From header contains the
string 'jack@cwi.nl (Jack Jansen)', then
m.getaddr('From') will yield the pair
('Jack Jansen', 'jack@cwi.nl').
If the header contained
'Jack Jansen &lt;jack@cwi.nl&gt;' instead, it would yield the
exact same result.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getaddrlist">
<description>This is similar to getaddr(list), but parses a header
containing a list of email addresses (e.g. To header) and
returns a list of (full name, email address) pairs
(even if there was only one address in the header). If there is no
header matching name, return an empty list.
If multiple headers exist that match the named header (e.g. if there
are several Cc headers), all are parsed for addresses.
Any continuation lines the named headers contain are also parsed.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getdate">
<description>Retrieve a header using getheader() and parse it into a 9-tuple
compatible with time.mktime(); note that fields 6, 7, and 8 are not usable. If there is no header matching
name, or it is unparsable, return None.
Date parsing appears to be a black art, and not all mailers adhere to
the standard. While it has been tested and found correct on a large
collection of email from many sources, it is still possible that this
function may occasionally yield an incorrect result.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getdate_tz">
<description>Retrieve a header using getheader() and parse it into a
10-tuple; the first 9 elements will make a tuple compatible with
time.mktime(), and the 10th is a number giving the offset
of the date's timezone from UTC. Note that fields 6, 7, and 8 are not usable. Similarly to getdate(), if
there is no header matching name, or it is unparsable, return
None.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
<group name="AddressList Objects">
<description>An AddressList instance has the following methods:
</description>
<element kind="function" name="__len__">
<description>Return the number of addresses in the address list.</description>

</element>

<element kind="function" name="__str__">
<description>Return a canonicalized string representation of the address list.
Addresses are rendered in &quot;name&quot; &lt;host@domain&gt; form, comma-separated.</description>

</element>

<element kind="function" name="__add__">
<description>Return a new AddressList instance that contains all addresses
in both AddressList operands, with duplicates removed (set
union).</description>

<properties><property kind="parameter" name="alistalist" required="1"/></properties></element>

<element kind="function" name="__iadd__">
<description>In-place version of __add__(); turns this AddressList
instance into the union of itself and the right-hand instance,
alist.</description>

<properties><property kind="parameter" name="alistalist" required="1"/></properties></element>

<element kind="function" name="__sub__">
<description>Return a new AddressList instance that contains every address
in the left-hand AddressList operand that is not present in
the right-hand address operand (set difference).</description>

<properties><property kind="parameter" name="alistalist" required="1"/></properties></element>

<element kind="function" name="__isub__">
<description>In-place version of __sub__(), removing addresses in this
list which are also in alist.</description>

<properties><property kind="parameter" name="alistalist" required="1"/></properties></element>

</group>
</group>
<group name="base64 --- Encode and decode MIME base64 data">
<description>Encode and decode files using the MIME base64 data.
</description>
<element kind="function" name="decode">
<description>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.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output output" required="1"/></properties></element>

<element kind="function" name="decodestring">
<description>Decode the string s, which must contain one or more lines of
base64 encoded data, and return a string containing the resulting
binary data.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="encode">
<description>Encode the contents of the input file and write the resulting
base64 encoded data to the output file.
input and output must either be file objects or objects that
mimic the file object interface. input will be read until
input.read() returns an empty string. encode()
returns the encoded data plus a trailing newline character
('\n').</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output output" required="1"/></properties></element>

<element kind="function" name="encodestring">
<description>Encode the string s, which can contain arbitrary binary data,
and return a string containing one or more lines of
base64-encoded data. encodestring() returns a
string containing one or more lines of base64-encoded data
always including an extra trailing newline ('\n').</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

</group>
<group name="binascii --- Convert between binary and">
<description>Tools for converting between binary and various
-encoded binary representations.
The binascii module contains a number of methods to convert
between binary and various -encoded binary
representations. Normally, you will not use these functions directly
but use wrapper modules like uuuu or
binhexbinhex instead, this module solely
exists because bit-manipulation of large amounts of data is slow in
Python.
The binascii module defines the following functions:
</description>
<element kind="function" name="a2b_uu">
<description>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.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="b2a_uu">
<description>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.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="a2b_base64">
<description>Convert a block of base64 data back to binary and return the
binary data. More than one line may be passed at a time.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="b2a_base64">
<description>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.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="a2b_qp">
<description>Convert a block of quoted-printable data back to binary and return the
binary data. More than one line may be passed at a time.
If the optional argument header is present and true, underscores
will be decoded as spaces.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="header"/></properties></element>

<element kind="function" name="b2a_qp">
<description>Convert binary data to a line(s) of ASCII characters in
quoted-printable encoding. The return value is the converted line(s).
If the optional argument quotetabs is present and true, all tabs
and spaces will be encoded. If the optional argument header is
present and true, spaces will be encoded as underscores per RFC1522.
If the optional argument header is present and false, newline
characters will be encoded as well, otherwise linefeed conversion might
corrupt the binary data stream.</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="quotetabs"/><property kind="parameter" name="istext"/><property kind="parameter" name="header"/></properties></element>

<element kind="function" name="a2b_hqx">
<description>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.</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="rledecode_hqx">
<description>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.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="rlecode_hqx">
<description>Perform binhex4 style RLE-compression on data and return the
result.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="b2a_hqx">
<description>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).</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="crc_hqx">
<description>Compute the binhex4 crc value of data, starting with an initial
crc and returning the result.</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="crc crc" required="1"/></properties></element>

<element kind="function" name="crc32">
<description>Compute CRC-32, the 32-bit checksum of data, starting with an initial
crc. This is consistent with the ZIP file checksum. Since the
algorithm is designed for use as a checksum algorithm, it is not
suitable for use as a general hash algorithm. Use as follows:
print binascii.crc32(&quot;hello world&quot;)
# Or, in two pieces:
crc = binascii.crc32(&quot;hello&quot;)
crc = binascii.crc32(&quot; world&quot;, crc)
print crc
</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="crc"/></properties></element>

<element kind="function" name="b2a_hex">
<description>hexlify{data}
Return the hexadecimal representation of the binary data. Every
byte of data is converted into the corresponding 2-digit hex
representation. The resulting string is therefore twice as long as
the length of data.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="a2b_hex">
<description>unhexlify{hexstr}
Return the binary data represented by the hexadecimal string
hexstr. This function is the inverse of b2a_hex().
hexstr must contain an even number of hexadecimal digits (which
can be upper or lower case), otherwise a TypeError is
raised.</description>

<properties><property kind="parameter" name="hexstrhexstr" required="1"/></properties></element>

</group>
<group name="binhex --- Encode and decode binhex4 files">
<description>Encode and decode files in binhex4 format.
This module encodes and decodes files in binhex4 format, a format
allowing representation of Macintosh files in . 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:
</description>
<element kind="function" name="binhex">
<description>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).</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output output" required="1"/></properties></element>

<element kind="function" name="hexbin">
<description>Decode a binhex file input. input may be a filename or a
file-like object supporting read() and close() methods.
The resulting file is written to a file named output, unless the
argument is omitted in which case the output filename is read from the
binhex file.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output"/></properties></element>

<group name="Notes">
</group>
</group>
<group name="quopri --- Encode and decode MIME quoted-printable data">
<description>Encode and decode files using the MIME
quoted-printable encoding.
This module performs quoted-printable transport encoding and decoding,
as defined in 1521: ``MIME (Multipurpose Internet Mail
Extensions) Part One: Mechanisms for Specifying and Describing the
Format of Internet Message Bodies''. The quoted-printable encoding is
designed for data where there are relatively few nonprintable
characters; the base64 encoding scheme available via the
base64 module is more compact if there are many such
characters, as when sending a graphics file.
</description>
<element kind="function" name="decode">
<description>Decode the contents of the input file and write the resulting
decoded 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.readline() returns an empty string.
If the optional argument header is present and true, underscore
will be decoded as space. This is used to decode
``Q''-encoded headers as described in 1522: ``MIME (Multipurpose Internet Mail Extensions)
Part Two: Message Header Extensions for Non-ASCII Text''.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output" required="1"/><property kind="parameter" name="header"/></properties></element>

<element kind="function" name="encode">
<description>Encode the contents of the input file and write the resulting
quoted-printable 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.readline() returns an empty string.
quotetabs is a flag which controls whether to encode embedded
spaces and tabs; when true it encodes such embedded whitespace, and
when false it leaves them unencoded. Note that spaces and tabs
appearing at the end of lines are always encoded, as per 1521.</description>

<properties><property kind="parameter" name="input" required="1"/><property kind="parameter" name="output" required="1"/><property kind="parameter" name="quotetabs quotetabs" required="1"/></properties></element>

<element kind="function" name="decodestring">
<description>Like decode(), except that it accepts a source string and
returns the corresponding decoded string.</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="header"/></properties></element>

<element kind="function" name="encodestring">
<description>Like encode(), except that it accepts a source string and
returns the corresponding encoded string. quotetabs is optional
(defaulting to 0), and is passed straight through to
encode().</description>

<properties><property kind="parameter" name="s" required="1"/><property kind="parameter" name="quotetabs"/></properties></element>

</group>
<group name="uu --- Encode and decode uuencode files">
<description>Encode and decode files in uuencode format.
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.
This code was contributed by Lance Ellinghouse, and modified by Jack
Jansen.
</description>
<element kind="function" name="encode">
<description>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.</description>

<properties><property kind="parameter" name="in_file" required="1"/><property kind="parameter" name="out_file" required="1"/><property kind="parameter" name="name"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="decode">
<description>This call decodes uuencoded file in_file placing the result on
file out_file. If out_file is a pathname, mode is
used to set the permission bits if the file must be
created. Defaults for out_file and mode are taken from
the uuencode header. However, if the file specified in the header
already exists, a uu.Error is raised.</description>

<properties><property kind="parameter" name="in_file" required="1"/><property kind="parameter" name="out_file"/><property kind="parameter" name="mode"/></properties></element>

</group>
<group name="xdrlib --- Encode and decode XDR data">
<description>Encoders and decoders for the External Data
Representation (XDR).
</description>
<element kind="function" name="Packer">
<description>Packer is the class for packing data into XDR representation.
The Packer class is instantiated with no arguments.</description>

</element>

<element kind="function" name="Unpacker">
<description>Unpacker is the complementary class which unpacks XDR data
values from a string buffer. The input buffer is given as
data.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<group name="Packer Objects">
<description>Packer instances have the following methods:
</description>
<element kind="function" name="get_buffer">
<description>Returns the current pack buffer as a string.</description>

</element>

<element kind="function" name="reset">
<description>Resets the pack buffer to the empty string.</description>

</element>

<element kind="function" name="pack_float">
<description>Packs the single-precision floating point number value.</description>

<properties><property kind="parameter" name="valuevalue" required="1"/></properties></element>

<element kind="function" name="pack_double">
<description>Packs the double-precision floating point number value.</description>

<properties><property kind="parameter" name="valuevalue" required="1"/></properties></element>

<element kind="function" name="pack_fstring">
<description>Packs a fixed length string, s. n is the length of the
string but it is not packed into the data buffer. The string
is padded with null bytes if necessary to guaranteed 4 byte alignment.</description>

<properties><property kind="parameter" name="n" required="1"/><property kind="parameter" name="s s" required="1"/></properties></element>

<element kind="function" name="pack_fopaque">
<description>Packs a fixed length opaque data stream, similarly to
pack_fstring().</description>

<properties><property kind="parameter" name="n" required="1"/><property kind="parameter" name="data data" required="1"/></properties></element>

<element kind="function" name="pack_string">
<description>Packs a variable length string, s. The length of the string is
first packed as an unsigned integer, then the string data is packed
with pack_fstring().</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

<element kind="function" name="pack_opaque">
<description>Packs a variable length opaque data string, similarly to
pack_string().</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="pack_bytes">
<description>Packs a variable length byte stream, similarly to pack_string().</description>

<properties><property kind="parameter" name="bytesbytes" required="1"/></properties></element>

<element kind="function" name="pack_list">
<description>Packs a list of homogeneous items. This method is useful for
lists with an indeterminate size; i.e. the size is not available until
the entire list has been walked. For each item in the list, an
unsigned integer 1 is packed first, followed by the data value
from the list. pack_item is the function that is called to pack
the individual item. At the end of the list, an unsigned integer
0 is packed.
For example, to pack a list of integers, the code might appear like
this:
import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)
</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="pack_item pack_item" required="1"/></properties></element>

<element kind="function" name="pack_farray">
<description>Packs a fixed length list (array) of homogeneous items. n
is the length of the list; it is not packed into the buffer,
but a ValueError exception is raised if
len(array) is not equal to n. As above,
pack_item is the function used to pack each element.</description>

<properties><property kind="parameter" name="n" required="1"/><property kind="parameter" name="array" required="1"/><property kind="parameter" name="pack_item pack_item" required="1"/></properties></element>

<element kind="function" name="pack_array">
<description>Packs a variable length list of homogeneous items. First, the
length of the list is packed as an unsigned integer, then each element
is packed as in pack_farray() above.</description>

<properties><property kind="parameter" name="list" required="1"/><property kind="parameter" name="pack_item pack_item" required="1"/></properties></element>

</group>
<group name="Unpacker Objects">
<description>The Unpacker class offers the following methods:
</description>
<element kind="function" name="reset">
<description>Resets the string buffer with the given data.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="get_position">
<description>Returns the current unpack position in the data buffer.</description>

</element>

<element kind="function" name="set_position">
<description>Sets the data buffer unpack position to position. You should be
careful about using get_position() and set_position().</description>

<properties><property kind="parameter" name="positionposition" required="1"/></properties></element>

<element kind="function" name="get_buffer">
<description>Returns the current unpack data buffer as a string.</description>

</element>

<element kind="function" name="done">
<description>Indicates unpack completion. Raises an Error exception
if all of the data has not been unpacked.</description>

</element>

<element kind="function" name="unpack_float">
<description>Unpacks a single-precision floating point number.</description>

</element>

<element kind="function" name="unpack_double">
<description>Unpacks a double-precision floating point number, similarly to
unpack_float().</description>

</element>

<element kind="function" name="unpack_fstring">
<description>Unpacks and returns a fixed length string. n is the number of
characters expected. Padding with null bytes to guaranteed 4 byte
alignment is assumed.</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="unpack_fopaque">
<description>Unpacks and returns a fixed length opaque data stream, similarly to
unpack_fstring().</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="unpack_string">
<description>Unpacks and returns a variable length string. The length of the
string is first unpacked as an unsigned integer, then the string data
is unpacked with unpack_fstring().</description>

</element>

<element kind="function" name="unpack_opaque">
<description>Unpacks and returns a variable length opaque data string, similarly to
unpack_string().</description>

</element>

<element kind="function" name="unpack_bytes">
<description>Unpacks and returns a variable length byte stream, similarly to
unpack_string().</description>

</element>

<element kind="function" name="unpack_list">
<description>Unpacks and returns a list of homogeneous items. The list is unpacked
one element at a time
by first unpacking an unsigned integer flag. If the flag is 1,
then the item is unpacked and appended to the list. A flag of
0 indicates the end of the list. unpack_item is the
function that is called to unpack the items.</description>

<properties><property kind="parameter" name="unpack_itemunpack_item" required="1"/></properties></element>

<element kind="function" name="unpack_farray">
<description>Unpacks and returns (as a list) a fixed length array of homogeneous
items. n is number of list elements to expect in the buffer.
As above, unpack_item is the function used to unpack each element.</description>

<properties><property kind="parameter" name="n" required="1"/><property kind="parameter" name="unpack_item unpack_item" required="1"/></properties></element>

<element kind="function" name="unpack_array">
<description>Unpacks and returns a variable length list of homogeneous items.
First, the length of the list is unpacked as an unsigned integer, then
each element is unpacked as in unpack_farray() above.</description>

<properties><property kind="parameter" name="unpack_itemunpack_item" required="1"/></properties></element>

</group>
<group name="Exceptions">
</group>
</group>
<group name="netrc --- netrc file processing">
<description>% Note the needed for ... ;-(
Loading of .netrc files.
New in version 1.5.2
The netrc class parses and encapsulates the netrc file format
used by the ftp program and other FTP clients.
</description>
<element kind="function" name="netrc">
<description>A netrc instance or subclass instance encapsulates data from a netrc file. The initialization argument, if present, specifies the
file to parse. If no argument is given, the file .netrc in the
user's home directory will be read. Parse errors will raise
NetrcParseError with diagnostic information including the
file name, line number, and terminating token.</description>

<properties><property kind="parameter" name="file" required="1"/></properties></element>

<group name="netrc Objects">
<description>A netrc instance has the following methods:
</description>
<element kind="function" name="authenticators">
<description>Return a 3-tuple (login, account, password)
of authenticators for host. If the netrc file did not
contain an entry for the given host, return the tuple associated with
the `default' entry. If neither matching host nor default entry is
available, return None.</description>

<properties><property kind="parameter" name="hosthost" required="1"/></properties></element>

<element kind="function" name="__repr__">
<description>Dump the class data as a string in the format of a netrc file.
(This discards comments and may reorder the entries.)</description>

</element>

</group>
</group>
<group name="robotparser --- Parser for robots.txt">
<description>Loads a robots.txt file and
answers questions about fetchability of other URLs.
</description>
<element kind="function" name="RobotFileParser">
<description>This class provides a set of methods to read, parse and answer questions
about a single robots.txt file.
{set_url}{url}
Sets the URL referring to a robots.txt file.</description>

</element>

<element kind="function" name="read">
<description>Reads the robots.txt URL and feeds it to the parser.</description>

</element>

<element kind="function" name="parse">
<description>Parses the lines argument.</description>

<properties><property kind="parameter" name="lineslines" required="1"/></properties></element>

<element kind="function" name="can_fetch">
<description>Returns True if the useragent is allowed to fetch the url
according to the rules contained in the parsed robots.txt file.</description>

<properties><property kind="parameter" name="useragent" required="1"/><property kind="parameter" name="url url" required="1"/></properties></element>

<element kind="function" name="mtime">
<description>Returns the time the robots.txt file was last fetched. This is
useful for long-running web spiders that need to check for new
robots.txt files periodically.</description>

</element>

<element kind="function" name="modified">
<description>Sets the time the robots.txt file was last fetched to the current
time.</description>

</element>

</group>
<group name="csv --- CSV File Reading and Writing">
<description>Write and read tabular data to and from delimited files.
New in version 2.3
</description>
<group name="Module Contents">
<description>The csv module defines the following functions:
</description>
<element kind="function" name="reader">
<description>Return a reader object which will iterate over lines in the given
{}csvfile. csvfile can be any object which supports the
iterator protocol and returns a string each time its next
method is called. If csvfile is a file object, it must be opened with
the 'b' flag on platforms where that makes a difference. An optional
{}dialect parameter can be given
which is used to define a set of parameters specific to a particular CSV
dialect. It may be an instance of a subclass of the Dialect
class or one of the strings returned by the list_dialects
function. The other optional {}fmtparam keyword arguments can be
given to override individual formatting parameters in the current
dialect. For more information about the dialect and formatting
parameters, see section~csv-fmt-params, ``Dialects and Formatting
Parameters'' for details of these parameters.
All data read are returned as strings. No automatic data type
conversion is performed.</description>

<properties><property kind="parameter" name="csvfile" required="1"/><property default="'excel'" kind="parameter" name="dialect"/><property kind="parameter" name="fmtparam"/></properties></element>

<element kind="function" name="writer">
<description>Return a writer object responsible for converting the user's data into
delimited strings on the given file-like object. csvfile can be any
object with a write method. If csvfile is a file object,
it must be opened with the 'b' flag on platforms where that makes a
difference. An optional
{}dialect parameter can be given which is used to define a set of
parameters specific to a particular CSV dialect. It may be an instance
of a subclass of the Dialect class or one of the strings
returned by the list_dialects function. The other optional
{}fmtparam keyword arguments can be given to override individual
formatting parameters in the current dialect. For more information
about the dialect and formatting parameters, see
section~csv-fmt-params, ``Dialects and Formatting Parameters'' for
details of these parameters. To make it as easy as possible to
interface with modules which implement the DB API, the value
None is written as the empty string. While this isn't a
reversible transformation, it makes it easier to dump SQL NULL data values
to CSV files without preprocessing the data returned from a
cursor.fetch*() call. All other non-string data are stringified
with str() before being written.</description>

<properties><property kind="parameter" name="csvfile" required="1"/><property default="'excel'" kind="parameter" name="dialect"/><property kind="parameter" name="fmtparam"/></properties></element>

<element kind="function" name="register_dialect">
<description>Associate dialect with name. dialect must be a subclass
of csv.Dialect. name must be a string or Unicode object.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="dialect dialect" required="1"/></properties></element>

<element kind="function" name="unregister_dialect">
<description>Delete the dialect associated with name from the dialect registry. An
Error is raised if name is not a registered dialect
name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="get_dialect">
<description>Return the dialect associated with name. An Error is
raised if name is not a registered dialect name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="list_dialects">
<description>Return the names of all registered dialects.</description>

</element>

<element kind="function" name="DictReader">
<description>Create an object which operates like a regular reader but maps the
information read into a dict whose keys are given by the optional
{} fieldnames
parameter. If the fieldnames parameter is omitted, the values in
the first row of the csvfile will be used as the fieldnames.
If the row read has fewer fields than the fieldnames sequence,
the value of restval will be used as the default value. If the row
read has more fields than the fieldnames sequence, the remaining data is
added as a sequence keyed by the value of restkey. If the row read
has fewer fields than the fieldnames sequence, the remaining keys take the
value of the optional restval parameter. All other parameters are
interpreted as for reader objects.</description>

<properties><property kind="parameter" name="csvfile" required="1"/><property default="None" kind="parameter" name="fieldnames"/><property default="None" kind="parameter" name="restkey"/><property default="None" kind="parameter" name="restval"/><property default="'excel'" kind="parameter" name="dialect"/><property kind="parameter" name="fmtparam"/></properties></element>

<element kind="function" name="DictWriter">
<description>Create an object which operates like a regular writer but maps dictionaries
onto output rows. The fieldnames parameter identifies the order in
which values in the dictionary passed to the writerow() method are
written to the csvfile. The optional restval parameter
specifies the value to be written if the dictionary is missing a key in
fieldnames. If the dictionary passed to the writerow()
method contains a key not found in fieldnames, the optional
extrasaction parameter indicates what action to take. If it is set
to 'raise' a ValueError is raised. If it is set to
'ignore', extra values in the dictionary are ignored. All other
parameters are interpreted as for writer objects.
Note that unlike the DictReader class, the fieldnames
parameter of the DictWriter is not optional. Since Python's
dict objects are not ordered, there is not enough information
available to deduce the order in which the row should be written to the
csvfile.</description>

<properties><property kind="parameter" name="csvfile" required="1"/><property kind="parameter" name="fieldnames" required="1"/><property default="&quot;&quot;" kind="parameter" name="restval"/><property default="'raise'" kind="parameter" name="extrasaction"/><property default="'excel'" kind="parameter" name="dialect"/><property kind="parameter" name="fmtparam"/></properties></element>

<element kind="function" name="Sniffer">
<description>The Sniffer class is used to deduce the format of a CSV file.</description>

</element>

<element kind="function" name="sniff">
<description>Analyze the given sample and return a Dialect subclass
reflecting the parameters found. If the optional delimiters parameter
is given, it is interpreted as a string containing possible valid delimiter
characters.</description>

<properties><property kind="parameter" name="sample" required="1"/><property default="None" kind="parameter" name="delimiters"/></properties></element>

<element kind="function" name="has_header">
<description>Analyze the sample text (presumed to be in CSV format) and return
True if the first row appears to be a series of column
headers.</description>

<properties><property kind="parameter" name="samplesample" required="1"/></properties></element>

</group>
<group name="Dialects and Formatting Parameters">
<description>To make it easier to specify the format of input and output records,
specific formatting parameters are grouped together into dialects. A
dialect is a subclass of the Dialect class having a set of specific
methods and a single validate() method. When creating reader
or writer objects, the programmer can specify a string or a subclass
of the Dialect class as the dialect parameter. In addition to, or
instead of, the dialect parameter, the programmer can also specify
individual formatting parameters, which have the same names as the
attributes defined below for the Dialect class.
Dialects support the following attributes:
[Dialect]{delimiter}
A one-character string used to separate fields. It defaults to ','.
[Dialect]{doublequote}
Controls how instances of quotechar appearing inside a field should be
themselves be quoted. When True, the character is doubledd.
When False, the escapechar must be a one-character string
which is used as a prefix to the quotechar. It defaults to
True.
[Dialect]{escapechar}
A one-character string used to escape the delimiter if quoting
is set to QUOTE_NONE. It defaults to None.
[Dialect]{lineterminator}
The string used to terminate lines in the CSV file. It defaults to
'\r\n'.
[Dialect]{quotechar}
A one-character string used to quote elements containing the delimiter
or which start with the quotechar. It defaults to '&quot;'.
[Dialect]{quoting}
Controls when quotes should be generated by the writer. It can take on any
of the QUOTE_* constants (see section~csv-contents)
and defaults to QUOTE_MINIMAL. [Dialect]{skipinitialspace}
When True, whitespace immediately following the delimiter
is ignored. The default is False.
</description>
</group>
<group name="Reader Objects">
<description>Reader objects (DictReader instances and objects returned by
the reader() function) have the following public methods:
[csv reader]{next}{}
Return the next row of the reader's iterable object as a list, parsed
according to the current dialect.
</description>
</group>
<group name="Writer Objects">
<description>Writer objects (DictWriter instances and objects returned by
the writer() function) have the following public methods:
[csv writer]{writerow}{row}
Write the row parameter to the writer's file object, formatted
according to the current dialect.
[csv writer]{writerows}{rows}
Write all the rows parameters to the writer's file object, formatted
according to the current dialect.
</description>
</group>
<group name="Examples">
</group>
</group>
</group>
<group name="Structured Markup Processing Tools">
<group name="HTMLParser --- Simple HTML and XHTML parser">
<description>A simple parser that can handle HTML and XHTML.
This module defines a class HTMLParser which serves as the
basis for parsing text files formatted in HTML</description>
<element kind="function" name="HTMLParser">
<description>The HTMLParser class is instantiated without arguments.
An HTMLParser instance is fed HTML data and calls handler functions
when tags begin and end. The HTMLParser class is meant to be
overridden by the user to provide a desired behavior.
Unlike the parser in htmllib, this parser does not check
that end tags match start tags or call the end-tag handler for
elements which are closed implicitly by closing an outer element.</description>

</element>

<element kind="function" name="reset">
<description>Reset the instance. Loses all unprocessed data. This is called
implicitly at instantiation time.</description>

</element>

<element kind="function" name="feed">
<description>Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is
fed or close() is called.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="close">
<description>Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the
redefined version should always call the HTMLParser base class
method close().</description>

</element>

<element kind="function" name="getpos">
<description>Return current line number and offset.</description>

</element>

<element kind="function" name="get_starttag_text">
<description>Return the text of the most recently opened start tag. This should
not normally be needed for structured processing, but may be useful in
dealing with HTML ``as deployed'' or for re-generating input with
minimal changes (whitespace between attributes can be preserved,
etc.).</description>

</element>

<element kind="function" name="handle_starttag">
<description>This method is called to handle the start of a tag. It is intended to
be overridden by a derived class; the base class implementation does
nothing. The tag argument is the name of the tag converted to
lower case. The attrs argument is a list of (name,
value) pairs containing the attributes found inside the tag's
&lt;&gt; brackets. The name will be translated to lower case
and double quotes and backslashes in the value have been
interpreted. For instance, for the tag &lt;A
HREF=&quot;http://www.cwi.nl/&quot;&gt;, this method would be called as
handle_starttag('a', [('href', 'http://www.cwi.nl/')]).</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="attrs attrs" required="1"/></properties></element>

<element kind="function" name="handle_startendtag">
<description>Similar to handle_starttag(), but called when the parser
encounters an XHTML-style empty tag (&lt;a .../&gt;). This method
may be overridden by subclasses which require this particular lexical
information; the default implementation simple calls
handle_starttag() and handle_endtag().</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="attrs attrs" required="1"/></properties></element>

<element kind="function" name="handle_endtag">
<description>This method is called to handle the end tag of an element. It is
intended to be overridden by a derived class; the base class
implementation does nothing. The tag argument is the name of
the tag converted to lower case.</description>

<properties><property kind="parameter" name="tagtag" required="1"/></properties></element>

<element kind="function" name="handle_data">
<description>This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does
nothing.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="handle_charref">
<description>This method is called to
process a character reference of the form #ref;. It
is intended to be overridden by a derived class; the base class
implementation does nothing.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="handle_entityref">
<description>This method is called to process a general entity reference of the
form &amp;name; where name is an general entity
reference. It is intended to be overridden by a derived class; the
base class implementation does nothing.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="handle_comment">
<description>This method is called when a comment is encountered. The
comment argument is a string containing the text between the
{-}{-} and {-}{-} delimiters, but not the delimiters
themselves. For example, the comment &lt;!{-}{-}text{-}{-}&gt; will
cause this method to be called with the argument 'text'. It is
intended to be overridden by a derived class; the base class
implementation does nothing.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="handle_decl">
<description>Method called when an SGML declaration is read by the parser. The
decl parameter will be the entire contents of the declaration
inside the &lt;!...&gt; markup.It is intended to be overridden
by a derived class; the base class implementation does nothing.</description>

<properties><property kind="parameter" name="decldecl" required="1"/></properties></element>

<element kind="function" name="handle_pi">
<description>Method called when a processing instruction is encountered. The
data parameter will contain the entire processing instruction.
For example, for the processing instruction &lt;?proc color='red'&gt;,
this method would be called as handle_pi(&quot;proc color='red'&quot;). It
is intended to be overridden by a derived class; the base class
implementation does nothing.
The HTMLParser class uses the SGML syntactic rules for
processing instruction. An XHTML processing instruction using the
trailing ? will cause the ? to be included in
data.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<group name="Example HTML Parser Application">
</group>
</group>
<group name="sgmllib --- Simple SGML parser">
<description>Only as much of an SGML parser as needed to parse HTML.
</description>
<element kind="function" name="SGMLParser">
<description>The SGMLParser class is instantiated without arguments.
The parser is hardcoded to recognize the following
constructs:
Opening and closing tags of the form
&lt;tag attr=&quot;value&quot; ...&gt; and
&lt;/tag&gt;, respectively.
Numeric character references of the form #name;.
Entity references of the form &amp;name;.
SGML comments of the form &lt;!--text--&gt;. Note that
spaces, tabs, and newlines are allowed between the trailing
&gt; and the immediately preceding --.
</description>

</element>

<element kind="function" name="reset">
<description>Reset the instance. Loses all unprocessed data. This is called
implicitly at instantiation time.</description>

</element>

<element kind="function" name="setnomoretags">
<description>Stop processing tags. Treat all following input as literal input
(CDATA). (This is only provided so the HTML tag
&lt;PLAINTEXT&gt; can be implemented.)</description>

</element>

<element kind="function" name="setliteral">
<description>Enter literal mode (CDATA mode).</description>

</element>

<element kind="function" name="feed">
<description>Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is
fed or close() is called.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="close">
<description>Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the
redefined version should always call close().</description>

</element>

<element kind="function" name="get_starttag_text">
<description>Return the text of the most recently opened start tag. This should
not normally be needed for structured processing, but may be useful in
dealing with HTML ``as deployed'' or for re-generating input with
minimal changes (whitespace between attributes can be preserved,
etc.).</description>

</element>

<element kind="function" name="handle_starttag">
<description>This method is called to handle start tags for which either a
start_tag() or do_tag() method has been
defined. The tag argument is the name of the tag converted to
lower case, and the method argument is the bound method which
should be used to support semantic interpretation of the start tag.
The attributes argument is a list of (name,
value) pairs containing the attributes found inside the tag's
&lt;&gt; brackets. The name has been translated to lower case
and double quotes and backslashes in the value have been interpreted.
For instance, for the tag &lt;A HREF=&quot;http://www.cwi.nl/&quot;&gt;, this
method would be called as unknown_starttag('a', [('href',
'http://www.cwi.nl/')]). The base implementation simply calls
method with attributes as the only argument.</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="method" required="1"/><property kind="parameter" name="attributes attributes" required="1"/></properties></element>

<element kind="function" name="handle_endtag">
<description>This method is called to handle endtags for which an
end_tag() method has been defined. The
tag argument is the name of the tag converted to lower case, and
the method argument is the bound method which should be used to
support semantic interpretation of the end tag. If no
end_tag() method is defined for the closing element,
this handler is not called. The base implementation simply calls
method.</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="method method" required="1"/></properties></element>

<element kind="function" name="handle_data">
<description>This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does
nothing.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="handle_charref">
<description>This method is called to process a character reference of the form
#ref;. In the base implementation, ref must
be a decimal number in the
range 0-255. It translates the character to ASCII and calls the
method handle_data() with the character as argument. If
ref is invalid or out of range, the method
unknown_charref(ref) is called to handle the error. A
subclass must override this method to provide support for named
character entities.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

<element kind="function" name="handle_entityref">
<description>This method is called to process a general entity reference of the
form &amp;ref; where ref is an general entity
reference. It looks for ref in the instance (or class)
variable entitydefs which should be a mapping from entity
names to corresponding translations. If a translation is found, it
calls the method handle_data() with the translation;
otherwise, it calls the method unknown_entityref(ref).
The default entitydefs defines translations for
;, , ;, ;, and
;.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

<element kind="function" name="handle_comment">
<description>This method is called when a comment is encountered. The
comment argument is a string containing the text between the
&lt;!-- and --&gt; delimiters, but not the delimiters
themselves. For example, the comment &lt;!--text--&gt; will
cause this method to be called with the argument 'text'. The
default method does nothing.</description>

<properties><property kind="parameter" name="commentcomment" required="1"/></properties></element>

<element kind="function" name="handle_decl">
<description>Method called when an SGML declaration is read by the parser. In
practice, the DOCTYPE declaration is the only thing observed in
HTML, but the parser does not discriminate among different (or broken)
declarations. Internal subsets in a DOCTYPE declaration are
not supported. The data parameter will be the entire contents
of the declaration inside the &lt;!...&gt; markup. The
default implementation does nothing.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="report_unbalanced">
<description>This method is called when an end tag is found which does not
correspond to any open element.</description>

<properties><property kind="parameter" name="tagtag" required="1"/></properties></element>

<element kind="function" name="unknown_starttag">
<description>This method is called to process an unknown start tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="attributes attributes" required="1"/></properties></element>

<element kind="function" name="unknown_endtag">
<description>This method is called to process an unknown end tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.</description>

<properties><property kind="parameter" name="tagtag" required="1"/></properties></element>

<element kind="function" name="unknown_charref">
<description>This method is called to process unresolvable numeric character
references. Refer to handle_charref() to determine what is
handled by default. It is intended to be overridden by a derived
class; the base class implementation does nothing.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

<element kind="function" name="unknown_entityref">
<description>This method is called to process an unknown entity reference. It is
intended to be overridden by a derived class; the base class
implementation does nothing.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

</group>
<group name="htmllib --- A parser for HTML documents">
<description>A parser for HTML documents.
</description>
<element kind="function" name="HTMLParser">
<description>This is the basic HTML parser class. It supports all entity names
required by the XHTML 1.0 Recommendation (http://www.w3.org/TR/xhtml1). It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.</description>

<properties><property kind="parameter" name="formatterformatter" required="1"/></properties></element>

<group name="HTMLParser Objects">
<description>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 &lt;PRE&gt; element. The default value is false. This
affects the operation of handle_data() and save_end().
</description>
<element kind="function" name="anchor_bgn">
<description>This method is called at the start of an anchor region. The arguments
correspond to the attributes of the &lt;A&gt; tag with the same
names. The default implementation maintains a list of hyperlinks
(defined by the HREF attribute for &lt;A&gt; tags) within the
document. The list of hyperlinks is available as the data attribute
anchorlist.</description>

<properties><property kind="parameter" name="href" required="1"/><property kind="parameter" name="name" required="1"/><property kind="parameter" name="type type" required="1"/></properties></element>

<element kind="function" name="anchor_end">
<description>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().</description>

</element>

<element kind="function" name="handle_image">
<description>This method is called to handle images. The default implementation
simply passes the alt value to the handle_data()
method.</description>

<properties><property kind="parameter" name="source" required="1"/><property kind="parameter" name="alt" required="1"/><property kind="parameter" name="ismap"/><property kind="parameter" name="align"/><property kind="parameter" name="width"/><property kind="parameter" name="height"/></properties></element>

<element kind="function" name="save_bgn">
<description>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.</description>

</element>

<element kind="function" name="save_end">
<description>Ends buffering character data and returns all data saved since the
preceding call to save_bgn(). If the nofill flag is
false, whitespace is collapsed to single spaces. A call to this
method without a preceding call to save_bgn() will raise a
TypeError exception.</description>

</element>

</group>
</group>
<group name="xml.parsers.expat --- Fast XML parsing using Expat">
<description>% Markup notes:
%
% Many of the attributes of the XMLParser objects are callbacks.
% Since signature information must be presented, these are described
% using the methoddesc environment. Since they are attributes which
% are set by client code, in-text references to these attributes
% should be marked using the macro and should not include the
% parentheses used when marking functions and methods.
An interface to the Expat non-validating XML parser.
New in version 2.0
The xml.parsers.expat module is a Python interface to the
Expat</description>
<element kind="function" name="ErrorString">
<description>Returns an explanatory string for a given error number errno.</description>

<properties><property kind="parameter" name="errnoerrno" required="1"/></properties></element>

<element kind="function" name="ParserCreate">
<description>Creates and returns a new xmlparser object. encoding, if specified, must be a string naming the encoding used by the XML data. Expat doesn't support as many encodings as
Python does, and its repertoire of encodings can't be extended; it
supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If
encoding is given it will override the implicit or explicit
encoding of the document.
Expat can optionally do XML namespace processing for you, enabled by
providing a value for namespace_separator. The value must be a
one-character string; a ValueError will be raised if the
string has an illegal length (None is considered the same as
omission). When namespace processing is enabled, element type names
and attribute names that belong to a namespace will be expanded. The
element name passed to the element handlers
StartElementHandler and EndElementHandler
will be the concatenation of the namespace URI, the namespace
separator character, and the local part of the name. If the namespace
separator is a zero byte (chr(0)) then the namespace URI and
the local part will be concatenated without any separator.
For example, if namespace_separator is set to a space character
( ) and the following document is parsed:
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;root xmlns = &quot;http://default-namespace.org/&quot;
xmlns:py = &quot;http://www.python.org/ns/&quot;&gt;
&lt;py:elem1 /&gt;
&lt;elem2 xmlns=&quot;&quot; /&gt;
&lt;/root&gt;
StartElementHandler will receive the following strings
for each element:
http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2
</description>

<properties><property kind="parameter" name="encoding" required="1"/><property kind="parameter" name="namespace_separator"/></properties></element>

<group name="XMLParser Objects">
<description>xmlparser objects have the following methods:
</description>
<element kind="function" name="Parse">
<description>Parses the contents of the string data, calling the appropriate
handler functions to process the parsed data. isfinal must be
true on the final call to this method. data can be the empty
string at any time.</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="isfinal"/></properties></element>

<element kind="function" name="ParseFile">
<description>Parse XML data reading from the object file. file only
needs to provide the read(nbytes) method, returning the
empty string when there's no more data.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="SetBase">
<description>Sets the base to be used for resolving relative URIs in system
identifiers in declarations. Resolving relative identifiers is left
to the application: this value will be passed through as the
base argument to the ExternalEntityRefHandler,
NotationDeclHandler, and
UnparsedEntityDeclHandler functions.</description>

<properties><property kind="parameter" name="basebase" required="1"/></properties></element>

<element kind="function" name="GetBase">
<description>Returns a string containing the base set by a previous call to
SetBase(), or None if SetBase() hasn't been called.</description>

</element>

<element kind="function" name="GetInputContext">
<description>Returns the input data that generated the current event as a string.
The data is in the encoding of the entity which contains the text.
When called while an event handler is not active, the return value is
None.
New in version 2.1</description>

</element>

<element kind="function" name="ExternalEntityParserCreate">
<description>Create a ``child'' parser which can be used to parse an external
parsed entity referred to by content parsed by the parent parser. The
context parameter should be the string passed to the
ExternalEntityRefHandler() handler function, described below.
The child parser is created with the ordered_attributes,
returns_unicode and specified_attributes set to the
values of this parser.</description>

<properties><property kind="parameter" name="context" required="1"/><property kind="parameter" name="encoding"/></properties></element>

<element kind="function" name="XmlDeclHandler">
<description>Called when the XML declaration is parsed. The XML declaration is the
(optional) declaration of the applicable version of the XML
recommendation, the encoding of the document text, and an optional
``standalone'' declaration. version and encoding will be
strings of the type dictated by the returns_unicode
attribute, and standalone will be 1 if the document is
declared standalone, 0 if it is declared not to be standalone,
or -1 if the standalone clause was omitted.
This is only available with Expat version 1.95.0 or newer.
New in version 2.1</description>

<properties><property kind="parameter" name="version" required="1"/><property kind="parameter" name="encoding" required="1"/><property kind="parameter" name="standalone standalone" required="1"/></properties></element>

<element kind="function" name="StartDoctypeDeclHandler">
<description>Called when Expat begins parsing the document type declaration
(&lt;!DOCTYPE ...). The doctypeName is provided exactly
as presented. The systemId and publicId parameters give
the system and public identifiers if specified, or None if
omitted. has_internal_subset will be true if the document
contains and internal document declaration subset.
This requires Expat version 1.2 or newer.</description>

<properties><property kind="parameter" name="doctypeName" required="1"/><property kind="parameter" name="systemId" required="1"/><property kind="parameter" name="publicId" required="1"/><property kind="parameter" name="has_internal_subset                                                        has_internal_subset" required="1"/></properties></element>

<element kind="function" name="EndDoctypeDeclHandler">
<description>Called when Expat is done parsing the document type delaration.
This requires Expat version 1.2 or newer.</description>

</element>

<element kind="function" name="ElementDeclHandler">
<description>Called once for each element type declaration. name is the name
of the element type, and model is a representation of the
content model.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="model model" required="1"/></properties></element>

<element kind="function" name="AttlistDeclHandler">
<description>Called for each declared attribute for an element type. If an
attribute list declaration declares three attributes, this handler is
called three times, once for each attribute. elname is the name
of the element to which the declaration applies and attname is
the name of the attribute declared. The attribute type is a string
passed as type; the possible values are 'CDATA',
'ID', 'IDREF', ...
default gives the default value for the attribute used when the
attribute is not specified by the document instance, or None if
there is no default value ( values). If the attribute
is required to be given in the document instance, required will
be true.
This requires Expat version 1.95.0 or newer.</description>

<properties><property kind="parameter" name="elname" required="1"/><property kind="parameter" name="attname" required="1"/><property kind="parameter" name="type" required="1"/><property kind="parameter" name="default" required="1"/><property kind="parameter" name="required required" required="1"/></properties></element>

<element kind="function" name="StartElementHandler">
<description>Called for the start of every element. name is a string
containing the element name, and attributes is a dictionary
mapping attribute names to their values.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="attributes attributes" required="1"/></properties></element>

<element kind="function" name="EndElementHandler">
<description>Called for the end of every element.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="ProcessingInstructionHandler">
<description>Called for every processing instruction.</description>

<properties><property kind="parameter" name="target" required="1"/><property kind="parameter" name="data data" required="1"/></properties></element>

<element kind="function" name="CharacterDataHandler">
<description>Called for character data. This will be called for normal character
data, CDATA marked content, and ignorable whitespace. Applications
which must distinguish these cases can use the
StartCdataSectionHandler, EndCdataSectionHandler,
and ElementDeclHandler callbacks to collect the required
information.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="UnparsedEntityDeclHandler">
<description>Called for unparsed (NDATA) entity declarations. This is only present
for version 1.2 of the Expat library; for more recent versions, use
EntityDeclHandler instead. (The underlying function in the
Expat library has been declared obsolete.)</description>

<properties><property kind="parameter" name="entityName" required="1"/><property kind="parameter" name="base" required="1"/><property kind="parameter" name="systemId" required="1"/><property kind="parameter" name="publicId" required="1"/><property kind="parameter" name="notationName                                                          notationName" required="1"/></properties></element>

<element kind="function" name="EntityDeclHandler">
<description>Called for all entity declarations. For parameter and internal
entities, value will be a string giving the declared contents
of the entity; this will be None for external entities. The
notationName parameter will be None for parsed entities,
and the name of the notation for unparsed entities.
is_parameter_entity will be true if the entity is a paremeter
entity or false for general entities (most applications only need to
be concerned with general entities).
This is only available starting with version 1.95.0 of the Expat
library.
New in version 2.1</description>

<properties><property kind="parameter" name="entityName" required="1"/><property kind="parameter" name="is_parameter_entity" required="1"/><property kind="parameter" name="value" required="1"/><property kind="parameter" name="base" required="1"/><property kind="parameter" name="systemId" required="1"/><property kind="parameter" name="publicId" required="1"/><property kind="parameter" name="notationName                                                  notationName" required="1"/></properties></element>

<element kind="function" name="NotationDeclHandler">
<description>Called for notation declarations. notationName, base, and
systemId, and publicId are strings if given. If the
public identifier is omitted, publicId will be None.</description>

<properties><property kind="parameter" name="notationName" required="1"/><property kind="parameter" name="base" required="1"/><property kind="parameter" name="systemId" required="1"/><property kind="parameter" name="publicId publicId" required="1"/></properties></element>

<element kind="function" name="StartNamespaceDeclHandler">
<description>Called when an element contains a namespace declaration. Namespace
declarations are processed before the StartElementHandler is
called for the element on which declarations are placed.</description>

<properties><property kind="parameter" name="prefix" required="1"/><property kind="parameter" name="uri uri" required="1"/></properties></element>

<element kind="function" name="EndNamespaceDeclHandler">
<description>Called when the closing tag is reached for an element that contained a namespace declaration. This is called once for each
namespace declaration on the element in the reverse of the order for
which the StartNamespaceDeclHandler was called to indicate
the start of each namespace declaration's scope. Calls to this
handler are made after the corresponding EndElementHandler
for the end of the element.</description>

<properties><property kind="parameter" name="prefixprefix" required="1"/></properties></element>

<element kind="function" name="CommentHandler">
<description>Called for comments. data is the text of the comment, excluding
the leading `&lt;!--' and trailing `--&gt;'.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="StartCdataSectionHandler">
<description>Called at the start of a CDATA section. This and
StartCdataSectionHandler are needed to be able to identify
the syntactical start and end for CDATA sections.</description>

</element>

<element kind="function" name="EndCdataSectionHandler">
<description>Called at the end of a CDATA section.</description>

</element>

<element kind="function" name="DefaultHandler">
<description>Called for any characters in the XML document for
which no applicable handler has been specified. This means
characters that are part of a construct which could be reported, but
for which no handler has been supplied.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="DefaultHandlerExpand">
<description>This is the same as the DefaultHandler, but doesn't inhibit expansion of internal entities.
The entity reference will not be passed to the default handler.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="NotStandaloneHandler">
<description>Called if the
XML document hasn't been declared as being a standalone document.
This happens when there is an external subset or a reference to a
parameter entity, but the XML declaration does not set standalone to
yes in an XML declaration. If this handler returns 0,
then the parser will throw an XML_ERROR_NOT_STANDALONE
error. If this handler is not set, no exception is raised by the
parser for this condition.</description>

</element>

<element kind="function" name="ExternalEntityRefHandler">
<description>Called for references to external entities. base is the current
base, as set by a previous call to SetBase(). The public and
system identifiers, systemId and publicId, are strings if
given; if the public identifier is not given, publicId will be
None. The context value is opaque and should only be
used as described below.
For external entities to be parsed, this handler must be implemented.
It is responsible for creating the sub-parser using
ExternalEntityParserCreate(context), initializing it with
the appropriate callbacks, and parsing the entity. This handler
should return an integer; if it returns 0, the parser will
throw an XML_ERROR_EXTERNAL_ENTITY_HANDLING error,
otherwise parsing will continue.
If this handler is not provided, external entities are reported by the
DefaultHandler callback, if provided.</description>

<properties><property kind="parameter" name="context" required="1"/><property kind="parameter" name="base" required="1"/><property kind="parameter" name="systemId" required="1"/><property kind="parameter" name="publicId publicId" required="1"/></properties></element>

</group>
<group name="ExpatError Exceptions">
<description>ExpatError exceptions have a number of interesting
attributes:
[ExpatError]{code}
Expat's internal error number for the specific error. This will
match one of the constants defined in the errors object from
this module.
New in version 2.1
[ExpatError]{lineno}
Line number on which the error was detected. The first line is
numbered 1.
New in version 2.1
[ExpatError]{offset}
Character offset into the line where the error occurred. The first
column is numbered 0.
New in version 2.1
</description>
</group>
<group name="Example">
<description>The following program defines three handlers that just print out their
arguments.
import xml.parsers.expat
# 3 handler functions
def start_element(name, attrs):
print 'Start element:', name, attrs
def end_element(name):
print 'End element:', name
def char_data(data):
print 'Character data:', repr(data)
p = xml.parsers.expat.ParserCreate()
p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data
p.Parse(&quot;&quot;&quot;&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;parent id=&quot;top&quot;&gt;&lt;child1 name=&quot;paul&quot;&gt;Text goes here&lt;/child1&gt;
&lt;child2 name=&quot;fred&quot;&gt;More text&lt;/child2&gt;
&lt;/parent&gt;&quot;&quot;&quot;, 1)
The output from this program is:
Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: ''
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: ''
End element: parent
</description>
</group>
<group name="Content Model Descriptions">
<description>Content modules are described using nested tuples. Each tuple
contains four values: the type, the quantifier, the name, and a tuple
of children. Children are simply additional content module
descriptions.
The values of the first two fields are constants defined in the
model object of the xml.parsers.expat module. These
constants can be collected in two groups: the model type group and the
quantifier group.
The constants in the model type group are:
{XML_CTYPE_ANY}
The element named by the model name was declared to have a content
model of ANY.
{XML_CTYPE_CHOICE}
The named element allows a choice from a number of options; this is
used for content models such as (A | B | C).
{XML_CTYPE_EMPTY}
Elements which are declared to be EMPTY have this model type.
{XML_CTYPE_MIXED}
{XML_CTYPE_NAME}
{XML_CTYPE_SEQ}
Models which represent a series of models which follow one after the
other are indicated with this model type. This is used for models
such as (A, B, C).
The constants in the quantifier group are:
{XML_CQUANT_NONE}
No modifier is given, so it can appear exactly once, as for A.
{XML_CQUANT_OPT}
The model is optional: it can appear once or not at all, as for
A?.
{XML_CQUANT_PLUS}
The model must occur one or more times (like A+).
{XML_CQUANT_REP}
The model must occur zero or more times, as for A*.
</description>
</group>
<group name="Expat error constants">
</group>
</group>
<group name="xml.dom --- The Document Object Model API">
<description>Document Object Model API for Python.
New in version 2.0
The Document Object Model, or ``DOM,'' is a cross-language API from
the World Wide Web Consortium (W3C) for accessing and modifying XML
documents. A DOM implementation presents an XML document as a tree
structure, or allows client code to build such a structure from
scratch. It then gives access to the structure through a set of
objects which provided well-known interfaces.
The DOM is extremely useful for random-access applications. SAX only
allows you a view of one bit of the document at a time. If you are
looking at one SAX element, you have no access to another. If you are
looking at a text node, you have no access to a containing element.
When you write a SAX application, you need to keep track of your
program's position in the document somewhere in your own code. SAX
does not do it for you. Also, if you need to look ahead in the XML
document, you are just out of luck.
Some applications are simply impossible in an event driven model with
no access to a tree. Of course you could build some sort of tree
yourself in SAX events, but the DOM allows you to avoid writing that
code. The DOM is a standard tree representation for XML data.
%What if your needs are somewhere between SAX and the DOM? Perhaps
%you cannot afford to load the entire tree in memory but you find the
%SAX model somewhat cumbersome and low-level. There is also a module
%called xml.dom.pulldom that allows you to build trees of only the
%parts of a document that you need structured access to. It also has
%features that allow you to find your way around the DOM.
% See http://www.prescod.net/python/pulldom
The Document Object Model is being defined by the W3C in stages, or
``levels'' in their terminology. The Python mapping of the API is
substantially based on the DOM Level~2 recommendation. The mapping of
the Level~3 specification, currently only available in draft form, is
being developed by the Python XML Special Interest
Group{http://www.python.org/sigs/xml-sig/} as part of the
PyXML package{http://pyxml.sourceforge.net/}. Refer to the
documentation bundled with that package for information on the current
state of DOM Level~3 support.
DOM applications typically start by parsing some XML into a DOM. How
this is accomplished is not covered at all by DOM Level~1, and Level~2
provides only limited improvements: There is a
DOMImplementation object class which provides access to
Document creation methods, but no way to access an XML
reader/parser/Document builder in an implementation-independent way.
There is also no well-defined way to access these methods without an
existing Document object. In Python, each DOM implementation
will provide a function getDOMImplementation(). DOM Level~3
adds a Load/Store specification, which defines an interface to the
reader, but this is not yet available in the Python standard library.
Once you have a DOM document object, you can access the parts of your
XML document through its properties and methods. These properties are
defined in the DOM specification; this portion of the reference manual
describes the interpretation of the specification in Python.
The specification provided by the W3C defines the DOM API for Java,
ECMAScript, and OMG IDL. The Python mapping defined here is based in
large part on the IDL version of the specification, but strict
compliance is not required (though implementations are free to support
the strict mapping from IDL). See section dom-conformance,
``Conformance,'' for a detailed discussion of mapping requirements.
See also Document Object
Model (DOM) Level~2 Specification - {The W3C recommendation upon which the Python DOM API is
based.}
\seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
Model (DOM) Level~1 Specification}
{The W3C recommendation for the
DOM supported by \module{xml.dom.minidom}.}
\seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a
full-featured implementation of DOM should use the PyXML
package.}
\seetitle[http://cgi.omg.org/cgi-bin/doc?orbos/99-08-02.pdf]{CORBA
Scripting with Python}
{This specifies the mapping from OMG IDL to Python.}
\end{seealso}
</description>
<group name="Module Contents">
<description>The xml.dom contains the following functions:
</description>
<element kind="function" name="registerDOMImplementation">
<description>Register the factory function with the name name. The
factory function should return an object which implements the
DOMImplementation interface. The factory function can return
the same object every time, or a new one for each call, as appropriate
for the specific implementation (e.g. if that implementation supports
some customization).</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="factory factory" required="1"/></properties></element>

<element kind="function" name="getDOMImplementation">
<description>Return a suitable DOM implementation. The name is either
well-known, the module name of a DOM implementation, or
None. If it is not None, imports the corresponding
module and returns a DOMImplementation object if the import
succeeds. If no name is given, and if the environment variable
PYTHON_DOM is set, this variable is used to find the
implementation.
If name is not given, this examines the available implementations to
find one with the required feature set. If no implementation can be
found, raise an ImportError. The features list must be a
sequence of (feature, version) pairs which are
passed to the hasFeature() method on available
DOMImplementation objects.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="features"/></properties></element>

</group>
<group name="Objects in the DOM">
<description>The definitive documentation for the DOM is the DOM specification from
the W3C.
Note that DOM attributes may also be manipulated as nodes instead of
as simple strings. It is fairly rare that you must do this, however,
so this usage is not yet documented.
{l|l|l}{class}{Interface}{Section}{Purpose}
DOMImplementation{dom-implementation-objects}
{Interface to the underlying implementation.}
Node{dom-node-objects}
{Base interface for most objects in a document.}
NodeList{dom-nodelist-objects}
{Interface for a sequence of nodes.}
DocumentType{dom-documenttype-objects}
{Information about the declarations needed to process a document.}
Document{dom-document-objects}
{Object which represents an entire document.}
Element{dom-element-objects}
{Element nodes in the document hierarchy.}
Attr{dom-attr-objects}
{Attribute value nodes on element nodes.}
Comment{dom-comment-objects}
{Representation of comments in the source document.}
Text{dom-text-objects}
{Nodes containing textual content from the document.}
ProcessingInstruction{dom-pi-objects}
{Processing instruction representation.}
An additional section describes the exceptions defined for working
with the DOM in Python.
DOMImplementation Objects
The DOMImplementation interface provides a way for
applications to determine the availability of particular features in
the DOM they are using. DOM Level~2 added the ability to create new
Document and DocumentType objects using the
DOMImplementation as well.
</description>
<element kind="function" name="hasFeature">
<description/>

<properties><property kind="parameter" name="feature" required="1"/><property kind="parameter" name="version version" required="1"/></properties></element>

<element kind="function" name="hasAttributes">
<description>Returns true if the node has any attributes.</description>

</element>

<element kind="function" name="hasChildNodes">
<description>Returns true if the node has any child nodes.</description>

</element>

<element kind="function" name="isSameNode">
<description>Returns true if other refers to the same node as this node.
This is especially useful for DOM implementations which use any sort
of proxy architecture (because more than one object can refer to the
same node).
This is based on a proposed DOM Level~3 API which is still in the
``working draft'' stage, but this particular interface appears
uncontroversial. Changes from the W3C will not necessarily affect
this method in the Python DOM interface (though any new W3C API for
this would also be supported).
</description>

<properties><property kind="parameter" name="otherother" required="1"/></properties></element>

<element kind="function" name="appendChild">
<description>Add a new child node to this node at the end of the list of children,
returning newChild.</description>

<properties><property kind="parameter" name="newChildnewChild" required="1"/></properties></element>

<element kind="function" name="insertBefore">
<description>Insert a new child node before an existing child. It must be the case
that refChild is a child of this node; if not,
ValueError is raised. newChild is returned.</description>

<properties><property kind="parameter" name="newChild" required="1"/><property kind="parameter" name="refChild refChild" required="1"/></properties></element>

<element kind="function" name="removeChild">
<description>Remove a child node. oldChild must be a child of this node; if
not, ValueError is raised. oldChild is returned on
success. If oldChild will not be used further, its
unlink() method should be called.</description>

<properties><property kind="parameter" name="oldChildoldChild" required="1"/></properties></element>

<element kind="function" name="replaceChild">
<description>Replace an existing node with a new node. It must be the case that oldChild is a child of this node; if not,
ValueError is raised.</description>

<properties><property kind="parameter" name="newChild" required="1"/><property kind="parameter" name="oldChild oldChild" required="1"/></properties></element>

<element kind="function" name="normalize">
<description>Join adjacent text nodes so that all stretches of text are stored as
single Text instances. This simplifies processing text from a
DOM tree for many applications.
New in version 2.1</description>

</element>

<element kind="function" name="cloneNode">
<description>Clone this node. Setting deep means to clone all child nodes as
well. This returns the clone.</description>

<properties><property kind="parameter" name="deepdeep" required="1"/></properties></element>

<element kind="function" name="item">
<description>Return the i'th item from the sequence, if there is one, or
None. The index i is not allowed to be less then zero
or greater than or equal to the length of the sequence.</description>

<properties><property kind="parameter" name="ii" required="1"/></properties></element>

<element kind="function" name="createElement">
<description>Create and return a new element node. The element is not inserted
into the document when it is created. You need to explicitly insert
it with one of the other methods such as insertBefore() or
appendChild().</description>

<properties><property kind="parameter" name="tagNametagName" required="1"/></properties></element>

<element kind="function" name="createElementNS">
<description>Create and return a new element with a namespace. The
tagName may have a prefix. The element is not inserted into the
document when it is created. You need to explicitly insert it with
one of the other methods such as insertBefore() or
appendChild().</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="tagName tagName" required="1"/></properties></element>

<element kind="function" name="createTextNode">
<description>Create and return a text node containing the data passed as a
parameter. As with the other creation methods, this one does not
insert the node into the tree.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="createComment">
<description>Create and return a comment node containing the data passed as a
parameter. As with the other creation methods, this one does not
insert the node into the tree.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="createProcessingInstruction">
<description>Create and return a processing instruction node containing the
target and data passed as parameters. As with the other
creation methods, this one does not insert the node into the tree.</description>

<properties><property kind="parameter" name="target" required="1"/><property kind="parameter" name="data data" required="1"/></properties></element>

<element kind="function" name="createAttribute">
<description>Create and return an attribute node. This method does not associate
the attribute node with any particular element. You must use
setAttributeNode() on the appropriate Element object
to use the newly created attribute instance.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="createAttributeNS">
<description>Create and return an attribute node with a namespace. The
tagName may have a prefix. This method does not associate the
attribute node with any particular element. You must use
setAttributeNode() on the appropriate Element object
to use the newly created attribute instance.</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="qualifiedName qualifiedName" required="1"/></properties></element>

<element kind="function" name="getElementsByTagName">
<description>Search for all descendants (direct children, children's children,
etc.) with a particular element type name.</description>

<properties><property kind="parameter" name="tagNametagName" required="1"/></properties></element>

<element kind="function" name="getElementsByTagNameNS">
<description>Search for all descendants (direct children, children's children,
etc.) with a particular namespace URI and localname. The localname is
the part of the namespace after the prefix.</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="localName localName" required="1"/></properties></element>

<element kind="function" name="getElementsByTagName">
<description>Same as equivalent method in the Document class.</description>

<properties><property kind="parameter" name="tagNametagName" required="1"/></properties></element>

<element kind="function" name="getElementsByTagNameNS">
<description>Same as equivalent method in the Document class.</description>

<properties><property kind="parameter" name="tagNametagName" required="1"/></properties></element>

<element kind="function" name="getAttribute">
<description>Return an attribute value as a string.</description>

<properties><property kind="parameter" name="attnameattname" required="1"/></properties></element>

<element kind="function" name="getAttributeNode">
<description>Return the Attr node for the attribute named by
attrname.</description>

<properties><property kind="parameter" name="attrnameattrname" required="1"/></properties></element>

<element kind="function" name="getAttributeNS">
<description>Return an attribute value as a string, given a namespaceURI and
localName.</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="localName localName" required="1"/></properties></element>

<element kind="function" name="getAttributeNodeNS">
<description>Return an attribute value as a node, given a namespaceURI and
localName.</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="localName localName" required="1"/></properties></element>

<element kind="function" name="removeAttribute">
<description>Remove an attribute by name. No exception is raised if there is no
matching attribute.</description>

<properties><property kind="parameter" name="attnameattname" required="1"/></properties></element>

<element kind="function" name="removeAttributeNode">
<description>Remove and return oldAttr from the attribute list, if present.
If oldAttr is not present, NotFoundErr is raised.</description>

<properties><property kind="parameter" name="oldAttroldAttr" required="1"/></properties></element>

<element kind="function" name="removeAttributeNS">
<description>Remove an attribute by name. Note that it uses a localName, not a
qname. No exception is raised if there is no matching attribute.</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="localName localName" required="1"/></properties></element>

<element kind="function" name="setAttribute">
<description>Set an attribute value from a string.</description>

<properties><property kind="parameter" name="attname" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="setAttributeNode">
<description>Add a new attibute node to the element, replacing an existing
attribute if necessary if the name attribute matches. If a
replacement occurs, the old attribute node will be returned. If
newAttr is already in use, InuseAttributeErr will be
raised.</description>

<properties><property kind="parameter" name="newAttrnewAttr" required="1"/></properties></element>

<element kind="function" name="setAttributeNodeNS">
<description>Add a new attibute node to the element, replacing an existing
attribute if necessary if the namespaceURI and
localName attributes match. If a replacement occurs, the old
attribute node will be returned. If newAttr is already in use,
InuseAttributeErr will be raised.</description>

<properties><property kind="parameter" name="newAttrnewAttr" required="1"/></properties></element>

<element kind="function" name="setAttributeNS">
<description>Set an attribute value from a string, given a namespaceURI and a
qname. Note that a qname is the whole attribute name. This is
different than above.</description>

<properties><property kind="parameter" name="namespaceURI" required="1"/><property kind="parameter" name="qname" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="item">
<description>Return an attribute with a particular index. The order you get the
attributes in is arbitrary but will be consistent for the life of a
DOM. Each item is an attribute node. Get its value with the
value attribbute.</description>

<properties><property kind="parameter" name="indexindex" required="1"/></properties></element>

</group>
<group name="Conformance">
</group>
</group>
<group name="xml.dom.minidom --- Lightweight DOM implementation">
<description>Lightweight Document Object Model (DOM) implementation.
New in version 2.0
xml.dom.minidom is a light-weight implementation of the
Document Object Model interface. It is intended to be
simpler than the full DOM and also significantly smaller.
DOM applications typically start by parsing some XML into a DOM. With
xml.dom.minidom, this is done through the parse functions:
from xml.dom.minidom import parse, parseString
dom1 = parse('c:.xml') # parse an XML file by name
datasource = open('c:.xml')
dom2 = parse(datasource) # parse an open file
dom3 = parseString('&lt;myxml&gt;Some data&lt;empty/&gt; some more data&lt;/myxml&gt;')
The parse() function can take either a filename or an open
file object.
</description>
<element kind="function" name="parse">
<description>Return a Document from the given input. filename_or_file
may be either a file name, or a file-like object. parser, if
given, must be a SAX2 parser object. This function will change the
document handler of the parser and activate namespace support; other
parser configuration (like setting an entity resolver) must have been
done in advance.</description>

<properties><property kind="parameter" name="filename_or_file{" required="1"/><property kind="parameter" name="parser" required="1"/></properties></element>

<element kind="function" name="parseString">
<description>Return a Document that represents the string. This
method creates a StringIO object for the string and passes
that on to parse.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="parser"/></properties></element>

<group name="DOM Objects">
<description>The definition of the DOM API for Python is given as part of the
xml.dom module documentation. This section lists the
differences between the API and xml.dom.minidom.
</description>
<element kind="function" name="unlink">
<description>Break internal references within the DOM so that it will be garbage
collected on versions of Python without cyclic GC. Even when cyclic
GC is available, using this can make large amounts of memory available
sooner, so calling this on DOM objects as soon as they are no longer
needed is good practice. This only needs to be called on the
Document object, but may be called on child nodes to discard
children of that node.</description>

</element>

<element kind="function" name="writexml">
<description>Write XML to the writer object. The writer should have a
write() method which matches that of the file object
interface.
New in version 2.1
New in version 2.3</description>

<properties><property kind="parameter" name="writerwriter" required="1"/></properties></element>

<element kind="function" name="toxml">
<description>Return the XML that the DOM represents as a string.
New in version 2.3
With no argument, the XML header does not specify an encoding, and the
result is Unicode string if the default encoding cannot represent all
characters in the document. Encoding this string in an encoding other
than UTF-8 is likely incorrect, since UTF-8 is the default encoding of
XML.
With an explicit encoding argument, the result is a byte string
in the specified encoding. It is recommended that this argument is
always specified. To avoid UnicodeError exceptions in case of
unrepresentable text data, the encoding argument should be specified
as &quot;utf-8&quot;.</description>

<properties><property kind="parameter" name="encoding" required="1"/></properties></element>

<element kind="function" name="toprettyxml">
<description>Return a pretty-printed version of the document. indent specifies
the indentation string and defaults to a tabulator; newl specifies
the string emitted at the end of each line and defaults to .
New in version 2.1
New in version 2.3</description>

<properties><property kind="parameter" name="indent" required="1"/><property kind="parameter" name="newl"/></properties></element>

<element kind="function" name="cloneNode">
<description>Although this method was present in the version of
xml.dom.minidom packaged with Python 2.0, it was seriously
broken. This has been corrected for subsequent releases.</description>

<properties><property kind="parameter" name="deepdeep" required="1"/></properties></element>

</group>
<group name="DOM Example">
<description>This example program is a fairly realistic example of a simple
program. In this particular case, we do not take much advantage
of the flexibility of the DOM.
minidom-example.py
</description>
</group>
<group name="minidom and the DOM standard">
</group>
</group>
<group name="xml.dom.pulldom --- Support for building partial DOM trees">
<description>Support for building partial DOM trees from SAX events.
New in version 2.0
xml.dom.pulldom allows building only selected portions of a
Document Object Model representation of a document from SAX events.
</description>
<element kind="function" name="PullDOM">
<description>xml.sax.handler.ContentHandler implementation that ...</description>

<properties><property kind="parameter" name="documentFactory" required="1"/></properties></element>

<element kind="function" name="DOMEventStream">
<description>...</description>

<properties><property kind="parameter" name="stream" required="1"/><property kind="parameter" name="parser" required="1"/><property kind="parameter" name="bufsize bufsize" required="1"/></properties></element>

<element kind="function" name="SAX2DOM">
<description>xml.sax.handler.ContentHandler implementation that ...</description>

<properties><property kind="parameter" name="documentFactory" required="1"/></properties></element>

<element kind="function" name="parse">
<description>...</description>

<properties><property kind="parameter" name="stream_or_string" required="1"/><property kind="parameter" name="parser"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="parseString">
<description>...</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="parser"/></properties></element>

<group name="DOMEventStream Objects">
<element kind="function" name="getEvent">
<description>...</description>

</element>

<element kind="function" name="expandNode">
<description>...</description>

<properties><property kind="parameter" name="nodenode" required="1"/></properties></element>

<element kind="function" name="reset">
<description>...</description>

</element>

</group>
</group>
<group name="xml.sax --- Support for SAX2 parsers">
<description>Package containing SAX2 base classes and convenience
functions.
New in version 2.0
The xml.sax package provides a number of modules which
implement the Simple API for XML (SAX) interface for Python. The
package itself provides the SAX exceptions and the convenience
functions which will be most used by users of the SAX API.
The convenience functions are:
</description>
<element kind="function" name="make_parser">
<description>Create and return a SAX XMLReader object. The first parser
found will be used. If parser_list is provided, it must be a
sequence of strings which name modules that have a function named
create_parser(). Modules listed in parser_list
will be used before modules in the default list of parsers.</description>

<properties><property kind="parameter" name="parser_list" required="1"/></properties></element>

<element kind="function" name="parse">
<description>Create a SAX parser and use it to parse a document. The document,
passed in as filename_or_stream, can be a filename or a file
object. The handler parameter needs to be a SAX
ContentHandler instance. If error_handler is given,
it must be a SAX ErrorHandler instance; if omitted, SAXParseException will be raised on all errors. There
is no return value; all work must be done by the handler
passed in.</description>

<properties><property kind="parameter" name="filename_or_stream" required="1"/><property kind="parameter" name="handler" required="1"/><property kind="parameter" name="error_handler"/></properties></element>

<element kind="function" name="parseString">
<description>Similar to parse(), but parses from a buffer string
received as a parameter.</description>

<properties><property kind="parameter" name="string" required="1"/><property kind="parameter" name="handler" required="1"/><property kind="parameter" name="error_handler"/></properties></element>

<group name="SAXException Objects">
<description>The SAXException exception class supports the following
methods:
</description>
<element kind="function" name="getMessage">
<description>Return a human-readable message describing the error condition.</description>

</element>

<element kind="function" name="getException">
<description>Return an encapsulated exception object, or None.</description>

</element>

</group>
</group>
<group name="xml.sax.handler --- Base classes for SAX handlers">
<description>Base classes for SAX event handlers.
New in version 2.0
The SAX API defines four kinds of handlers: content handlers, DTD
handlers, error handlers, and entity resolvers. Applications normally
only need to implement those interfaces whose events they are
interested in; they can implement the interfaces in a single object or
in multiple objects. Handler implementations should inherit from the
base classes provided in the module xml.sax, so that all
methods get default implementations.
{ContentHandler}
This is the main callback interface in SAX, and the one most
important to applications. The order of events in this interface
mirrors the order of the information in the document.
{DTDHandler}
Handle DTD events.
This interface specifies only those DTD events required for basic
parsing (unparsed entities and attributes).
{EntityResolver}
Basic interface for resolving entities. If you create an object
implementing this interface, then register the object with your
Parser, the parser will call the method in your object to resolve all
external entities.
{ErrorHandler}
Interface used by the parser to present error and warning messages
to the application. The methods of this object control whether errors
are immediately converted to exceptions or are handled in some other
way.
In addition to these classes, xml.sax.handler provides
symbolic constants for the feature and property names.
{feature_namespaces}
Value: &quot;http://xml.org/sax/features/namespaces&quot;: Perform Namespace processing.: Optionally do not perform Namespace processing
(implies namespace-prefixes; default).: (parsing) read-only; (not parsing) read/write
{feature_namespace_prefixes}
Value: &quot;http://xml.org/sax/features/namespace-prefixes&quot;: Report the original prefixed names and attributes used for Namespace
declarations.: Do not report attributes used for Namespace declarations, and
optionally do not report original prefixed names (default).: (parsing) read-only; (not parsing) read/write {feature_string_interning}
Value: &quot;http://xml.org/sax/features/string-interning&quot;
true: All element names, prefixes, attribute names, Namespace URIs, and
local names are interned using the built-in intern function.: Names are not necessarily interned, although they may be (default).: (parsing) read-only; (not parsing) read/write
{feature_validation}
Value: &quot;http://xml.org/sax/features/validation&quot;: Report all validation errors (implies external-general-entities and
external-parameter-entities).: Do not report validation errors.: (parsing) read-only; (not parsing) read/write
{feature_external_ges}
Value: &quot;http://xml.org/sax/features/external-general-entities&quot;: Include all external general (text) entities.: Do not include external general entities.: (parsing) read-only; (not parsing) read/write
{feature_external_pes}
Value: &quot;http://xml.org/sax/features/external-parameter-entities&quot;: Include all external parameter entities, including the external
DTD subset.: Do not include any external parameter entities, even the external
DTD subset.: (parsing) read-only; (not parsing) read/write
{all_features}
List of all features.
{property_lexical_handler}
Value: &quot;http://xml.org/sax/properties/lexical-handler&quot; type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2): An optional extension handler for lexical events like comments.: read/write
{property_declaration_handler}
Value: &quot;http://xml.org/sax/properties/declaration-handler&quot; type: xml.sax.sax2lib.DeclHandler (not supported in Python 2): An optional extension handler for DTD-related events other
than notations and unparsed entities.: read/write
{property_dom_node}
Value: &quot;http://xml.org/sax/properties/dom-node&quot; type: org.w3c.dom.Node (not supported in Python 2) : When parsing, the current DOM node being visited if this is
a DOM iterator; when not parsing, the root DOM node for
iteration.: (parsing) read-only; (not parsing) read/write {property_xml_string}
Value: &quot;http://xml.org/sax/properties/xml-string&quot; type: String: The literal string of characters that was the source for
the current event.: read-only
{all_properties}
List of all known property names.
</description>
<group name="ContentHandler Objects">
<description>Users are expected to subclass ContentHandler to support their
application. The following methods are called by the parser on the
appropriate events in the input document:
</description>
<element kind="function" name="setDocumentLocator">
<description>Called by the parser to give the application a locator for locating
the origin of document events.
SAX parsers are strongly encouraged (though not absolutely required)
to supply a locator: if it does so, it must supply the locator to
the application by invoking this method before invoking any of the
other methods in the DocumentHandler interface.
The locator allows the application to determine the end position of
any document-related event, even if the parser is not reporting an
error. Typically, the application will use this information for
reporting its own errors (such as character content that does not
match an application's business rules). The information returned by
the locator is probably not sufficient for use with a search engine.
Note that the locator will return correct information only during
the invocation of the events in this interface. The application
should not attempt to use it at any other time.</description>

<properties><property kind="parameter" name="locatorlocator" required="1"/></properties></element>

<element kind="function" name="startDocument">
<description>Receive notification of the beginning of a document.
The SAX parser will invoke this method only once, before any other
methods in this interface or in DTDHandler (except for
setDocumentLocator()).</description>

</element>

<element kind="function" name="endDocument">
<description>Receive notification of the end of a document.
The SAX parser will invoke this method only once, and it will be the
last method invoked during the parse. The parser shall not invoke
this method until it has either abandoned parsing (because of an
unrecoverable error) or reached the end of input.</description>

</element>

<element kind="function" name="startPrefixMapping">
<description>Begin the scope of a prefix-URI Namespace mapping.
The information from this event is not necessary for normal
Namespace processing: the SAX XML reader will automatically replace
prefixes for element and attribute names when the
feature_namespaces feature is enabled (the default).
%% XXX This is not really the default, is it? MvL
There are cases, however, when applications need to use prefixes in
character data or in attribute values, where they cannot safely be
expanded automatically; the startPrefixMapping() and
endPrefixMapping() events supply the information to the
application to expand prefixes in those contexts itself, if
necessary.
Note that startPrefixMapping() and
endPrefixMapping() events are not guaranteed to be properly
nested relative to each-other: all startPrefixMapping()
events will occur before the corresponding startElement()
event, and all endPrefixMapping() events will occur after
the corresponding endElement() event, but their order is
not guaranteed.</description>

<properties><property kind="parameter" name="prefix" required="1"/><property kind="parameter" name="uri uri" required="1"/></properties></element>

<element kind="function" name="endPrefixMapping">
<description>End the scope of a prefix-URI mapping.
See startPrefixMapping() for details. This event will
always occur after the corresponding endElement() event,
but the order of endPrefixMapping() events is not otherwise
guaranteed.</description>

<properties><property kind="parameter" name="prefixprefix" required="1"/></properties></element>

<element kind="function" name="startElement">
<description>Signals the start of an element in non-namespace mode.
The name parameter contains the raw XML 1.0 name of the
element type as a string and the attrs parameter holds an
object of the Attributes
interface{attributes-objects.html} containing the attributes of the
element. The object passed as attrs may be re-used by the
parser; holding on to a reference to it is not a reliable way to
keep a copy of the attributes. To keep a copy of the attributes,
use the copy() method of the attrs object.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="attrs attrs" required="1"/></properties></element>

<element kind="function" name="endElement">
<description>Signals the end of an element in non-namespace mode.
The name parameter contains the name of the element type, just
as with the startElement() event.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="startElementNS">
<description>Signals the start of an element in namespace mode.
The name parameter contains the name of the element type as a
(uri, localname) tuple, the qname parameter
contains the raw XML 1.0 name used in the source document, and the
attrs parameter holds an instance of the
AttributesNS interface{attributes-ns-objects.html}
containing the attributes of the element. If no namespace is
associated with the element, the uri component of name
will be None. The object passed as attrs may be
re-used by the parser; holding on to a reference to it is not a
reliable way to keep a copy of the attributes. To keep a copy of
the attributes, use the copy() method of the attrs
object.
Parsers may set the qname parameter to None, unless the
feature_namespace_prefixes feature is activated.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="qname" required="1"/><property kind="parameter" name="attrs attrs" required="1"/></properties></element>

<element kind="function" name="endElementNS">
<description>Signals the end of an element in namespace mode.
The name parameter contains the name of the element type, just
as with the startElementNS() method, likewise the
qname parameter.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="qname qname" required="1"/></properties></element>

<element kind="function" name="characters">
<description>Receive notification of character data.
The Parser will call this method to report each chunk of character
data. SAX parsers may return all contiguous character data in a
single chunk, or they may split it into several chunks; however, all
of the characters in any single event must come from the same
external entity so that the Locator provides useful information.
content may be a Unicode string or a byte string; the
expat reader module produces always Unicode strings.
The earlier SAX 1 interface provided by the Python
XML Special Interest Group used a more Java-like interface for this
method. Since most parsers used from Python did not take advantage
of the older interface, the simpler signature was chosen to replace
it. To convert old code to the new interface, use content
instead of slicing content with the old offset and
length parameters.</description>

<properties><property kind="parameter" name="contentcontent" required="1"/></properties></element>

<element kind="function" name="ignorableWhitespace">
<description>Receive notification of ignorable whitespace in element content.
Validating Parsers must use this method to report each chunk
of ignorable whitespace (see the W3C XML 1.0 recommendation,
section 2.10): non-validating parsers may also use this method
if they are capable of parsing and using content models.
SAX parsers may return all contiguous whitespace in a single
chunk, or they may split it into several chunks; however, all
of the characters in any single event must come from the same
external entity, so that the Locator provides useful
information.</description>

</element>

<element kind="function" name="processingInstruction">
<description>Receive notification of a processing instruction.
The Parser will invoke this method once for each processing
instruction found: note that processing instructions may occur
before or after the main document element.
A SAX parser should never report an XML declaration (XML 1.0,
section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
this method.</description>

<properties><property kind="parameter" name="target" required="1"/><property kind="parameter" name="data data" required="1"/></properties></element>

<element kind="function" name="skippedEntity">
<description>Receive notification of a skipped entity.
The Parser will invoke this method once for each entity
skipped. Non-validating processors may skip entities if they have
not seen the declarations (because, for example, the entity was
declared in an external DTD subset). All processors may skip
external entities, depending on the values of the
feature_external_ges and the
feature_external_pes properties.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
<group name="DTDHandler Objects">
<description>DTDHandler instances provide the following methods:
</description>
<element kind="function" name="notationDecl">
<description>Handle a notation declaration event.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="publicId" required="1"/><property kind="parameter" name="systemId systemId" required="1"/></properties></element>

<element kind="function" name="unparsedEntityDecl">
<description>Handle an unparsed entity declaration event.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="publicId" required="1"/><property kind="parameter" name="systemId" required="1"/><property kind="parameter" name="ndata ndata" required="1"/></properties></element>

</group>
<group name="EntityResolver Objects">
<element kind="function" name="resolveEntity">
<description>Resolve the system identifier of an entity and return either the
system identifier to read from as a string, or an InputSource to
read from. The default implementation returns systemId.</description>

<properties><property kind="parameter" name="publicId" required="1"/><property kind="parameter" name="systemId systemId" required="1"/></properties></element>

</group>
<group name="ErrorHandler Objects">
<description>Objects with this interface are used to receive error and warning
information from the XMLReader. If you create an object that
implements this interface, then register the object with your
XMLReader, the parser will call the methods in your object to
report all warnings and errors. There are three levels of errors
available: warnings, (possibly) recoverable errors, and unrecoverable
errors. All methods take a SAXParseException as the only
parameter. Errors and warnings may be converted to an exception by
raising the passed-in exception object.
</description>
<element kind="function" name="error">
<description>Called when the parser encounters a recoverable error. If this method
does not raise an exception, parsing may continue, but further document
information should not be expected by the application. Allowing the
parser to continue may allow additional errors to be discovered in the
input document.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="fatalError">
<description>Called when the parser encounters an error it cannot recover from;
parsing is expected to terminate when this method returns.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

<element kind="function" name="warning">
<description>Called when the parser presents minor warning information to the
application. Parsing is expected to continue when this method returns,
and document information will continue to be passed to the application.
Raising an exception in this method will cause parsing to end.</description>

<properties><property kind="parameter" name="exceptionexception" required="1"/></properties></element>

</group>
</group>
<group name="xml.sax.saxutils --- SAX Utilities">
<description>Convenience functions and classes for use with SAX.
New in version 2.0
The module xml.sax.saxutils contains a number of classes and
functions that are commonly useful when creating SAX applications,
either in direct use, or as base classes.
</description>
<element kind="function" name="escape">
<description>Escape &amp;, &lt;, and &gt; in a string
of data.
You can escape other strings of data by passing a dictionary as the
optional entities parameter. The keys and values must all be
strings; each key will be replaced with its corresponding value.</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="entities"/></properties></element>

<element kind="function" name="unescape">
<description>Unescape ;, ;, and ;
in a string of data.
You can unescape other strings of data by passing a dictionary as the
optional entities parameter. The keys and values must all be
strings; each key will be replaced with its corresponding value.
New in version 2.3</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="entities"/></properties></element>

<element kind="function" name="quoteattr">
<description>Similar to escape(), but also prepares data to be
used as an attribute value. The return value is a quoted version of
data with any additional required replacements.
quoteattr() will select a quote character based on the
content of data, attempting to avoid encoding any quote
characters in the string. If both single- and double-quote
characters are already in data, the double-quote characters
will be encoded and data will be wrapped in doule-quotes. The
resulting string can be used directly as an attribute value:
&gt;&gt;&gt; print &quot;&lt;element attr=%s&gt;&quot; % quoteattr(&quot;ab ' cd &quot;)
&lt;element attr=&quot;ab ' cd &amp;quot; ef&quot;&gt;
This function is useful when generating attribute values for HTML or
any SGML using the reference concrete syntax.
New in version 2.2</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="entities"/></properties></element>

<element kind="function" name="XMLGenerator">
<description>This class implements the ContentHandler interface by
writing SAX events back into an XML document. In other words, using
an XMLGenerator as the content handler will reproduce the
original document being parsed. out should be a file-like
object which will default to sys.stdout. encoding is the
encoding of the output stream which defaults to 'iso-8859-1'.</description>

<properties><property kind="parameter" name="out" required="1"/><property kind="parameter" name="encoding"/></properties></element>

<element kind="function" name="XMLFilterBase">
<description>This class is designed to sit between an XMLReader and the
client application's event handlers. By default, it does nothing
but pass requests up to the reader and events on to the handlers
unmodified, but subclasses can override specific methods to modify
the event stream or the configuration requests as they pass through.</description>

<properties><property kind="parameter" name="basebase" required="1"/></properties></element>

<element kind="function" name="prepare_input_source">
<description>This function takes an input source and an optional base URL and
returns a fully resolved InputSource object ready for
reading. The input source can be given as a string, a file-like
object, or an InputSource object; parsers will use this
function to implement the polymorphic source argument to their
parse() method.</description>

<properties><property kind="parameter" name="source" required="1"/><property kind="parameter" name="base"/></properties></element>

</group>
<group name="xml.sax.xmlreader --- Interface for XML parsers">
<description>Interface which SAX-compliant XML parsers must implement.
New in version 2.0
SAX parsers implement the XMLReader interface. They are
implemented in a Python module, which must provide a function
create_parser(). This function is invoked by xml.sax.make_parser() with no arguments to create a new parser object.
</description>
<element kind="function" name="XMLReader">
<description>Base class which can be inherited by SAX parsers.</description>

</element>

<element kind="function" name="IncrementalParser">
<description>In some cases, it is desirable not to parse an input source at once,
but to feed chunks of the document as they get available. Note that
the reader will normally not read the entire file, but read it in
chunks as well; still parse() won't return until the entire
document is processed. So these interfaces should be used if the
blocking behaviour of parse() is not desirable.
When the parser is instantiated it is ready to begin accepting data
from the feed method immediately. After parsing has been finished
with a call to close the reset method must be called to make the
parser ready to accept new data, either from feed or using the parse
method.
Note that these methods must not be called during parsing,
that is, after parse has been called and before it returns.
By default, the class also implements the parse method of the
XMLReader interface using the feed, close and reset methods of the
IncrementalParser interface as a convenience to SAX 2.0 driver
writers.</description>

</element>

<element kind="function" name="Locator">
<description>Interface for associating a SAX event with a document location. A
locator object will return valid results only during calls to
DocumentHandler methods; at any other time, the results are
unpredictable. If information is not available, methods may return
None.</description>

</element>

<element kind="function" name="InputSource">
<description>Encapsulation of the information needed by the XMLReader to
read entities.
This class may include information about the public identifier,
system identifier, byte stream (possibly with character encoding
information) and/or the character stream of an entity.
Applications will create objects of this class for use in the
XMLReader.parse() method and for returning from
EntityResolver.resolveEntity.
An InputSource belongs to the application, the
XMLReader is not allowed to modify InputSource objects
passed to it from the application, although it may make copies and
modify those.</description>

<properties><property kind="parameter" name="systemId" required="1"/></properties></element>

<element kind="function" name="AttributesImpl">
<description>This is an implementation of the Attributes
interface{attributes-objects.html} (see
section~attributes-objects). This is a dictionary-like
object which represents the element attributes in a
startElement() call. In addition to the most useful
dictionary operations, it supports a number of other methods as
described by the interface. Objects of this class should be
instantiated by readers; attrs must be a dictionary-like
object containing a mapping from attribute names to attribute
values.</description>

<properties><property kind="parameter" name="attrsattrs" required="1"/></properties></element>

<element kind="function" name="AttributesNSImpl">
<description>Namespace-aware variant of AttributesImpl, which will be
passed to startElementNS(). It is derived from
AttributesImpl, but understands attribute names as
two-tuples of namespaceURI and localname. In addition,
it provides a number of methods expecting qualified names as they
appear in the original document. This class implements the
AttributesNS interface{attributes-ns-objects.html}
(see section~attributes-ns-objects).</description>

<properties><property kind="parameter" name="attrs" required="1"/><property kind="parameter" name="qnames qnames" required="1"/></properties></element>

<group name="XMLReader Objects">
<description>The XMLReader interface supports the following methods:
</description>
<element kind="function" name="parse">
<description>Process an input source, producing SAX events. The source
object can be a system identifier (a string identifying the
input source -- typically a file name or an URL), a file-like
object, or an InputSource object. When parse()
returns, the input is completely processed, and the parser object
can be discarded or reset. As a limitation, the current implementation
only accepts byte streams; processing of character streams is for
further study.</description>

<properties><property kind="parameter" name="sourcesource" required="1"/></properties></element>

<element kind="function" name="getContentHandler">
<description>Return the current ContentHandler.</description>

</element>

<element kind="function" name="setContentHandler">
<description>Set the current ContentHandler. If no
ContentHandler is set, content events will be discarded.</description>

<properties><property kind="parameter" name="handlerhandler" required="1"/></properties></element>

<element kind="function" name="getDTDHandler">
<description>Return the current DTDHandler.</description>

</element>

<element kind="function" name="setDTDHandler">
<description>Set the current DTDHandler. If no DTDHandler is
set, DTD events will be discarded.</description>

<properties><property kind="parameter" name="handlerhandler" required="1"/></properties></element>

<element kind="function" name="getEntityResolver">
<description>Return the current EntityResolver.</description>

</element>

<element kind="function" name="setEntityResolver">
<description>Set the current EntityResolver. If no
EntityResolver is set, attempts to resolve an external
entity will result in opening the system identifier for the entity,
and fail if it is not available.</description>

<properties><property kind="parameter" name="handlerhandler" required="1"/></properties></element>

<element kind="function" name="getErrorHandler">
<description>Return the current ErrorHandler.</description>

</element>

<element kind="function" name="setErrorHandler">
<description>Set the current error handler. If no ErrorHandler is set,
errors will be raised as exceptions, and warnings will be printed.</description>

<properties><property kind="parameter" name="handlerhandler" required="1"/></properties></element>

<element kind="function" name="setLocale">
<description>Allow an application to set the locale for errors and warnings. SAX parsers are not required to provide localization for errors and
warnings; if they cannot support the requested locale, however, they
must throw a SAX exception. Applications may request a locale change
in the middle of a parse.</description>

<properties><property kind="parameter" name="localelocale" required="1"/></properties></element>

<element kind="function" name="getFeature">
<description>Return the current setting for feature featurename. If the
feature is not recognized, SAXNotRecognizedException is
raised. The well-known featurenames are listed in the module
xml.sax.handler.</description>

<properties><property kind="parameter" name="featurenamefeaturename" required="1"/></properties></element>

<element kind="function" name="setFeature">
<description>Set the featurename to value. If the feature is not
recognized, SAXNotRecognizedException is raised. If the
feature or its setting is not supported by the parser,
SAXNotSupportedException is raised.</description>

<properties><property kind="parameter" name="featurename" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="getProperty">
<description>Return the current setting for property propertyname. If the
property is not recognized, a SAXNotRecognizedException
is raised. The well-known propertynames are listed in the module
xml.sax.handler.</description>

<properties><property kind="parameter" name="propertynamepropertyname" required="1"/></properties></element>

<element kind="function" name="setProperty">
<description>Set the propertyname to value. If the property is not
recognized, SAXNotRecognizedException is raised. If the
property or its setting is not supported by the parser,
SAXNotSupportedException is raised.</description>

<properties><property kind="parameter" name="propertyname" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

</group>
<group name="IncrementalParser Objects">
<description>Instances of IncrementalParser offer the following additional
methods:
</description>
<element kind="function" name="feed">
<description>Process a chunk of data.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="close">
<description>Assume the end of the document. That will check well-formedness
conditions that can be checked only at the end, invoke handlers, and
may clean up resources allocated during parsing.</description>

</element>

<element kind="function" name="reset">
<description>This method is called after close has been called to reset the
parser so that it is ready to parse new documents. The results of
calling parse or feed after close without calling reset are
undefined.</description>

</element>

</group>
<group name="Locator Objects">
<description>Instances of Locator provide these methods:
</description>
<element kind="function" name="getColumnNumber">
<description>Return the column number where the current event ends.</description>

</element>

<element kind="function" name="getLineNumber">
<description>Return the line number where the current event ends.</description>

</element>

<element kind="function" name="getPublicId">
<description>Return the public identifier for the current event.</description>

</element>

<element kind="function" name="getSystemId">
<description>Return the system identifier for the current event.</description>

</element>

</group>
<group name="InputSource Objects">
<element kind="function" name="setPublicId">
<description>Sets the public identifier of this InputSource.</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="getPublicId">
<description>Returns the public identifier of this InputSource.</description>

</element>

<element kind="function" name="setSystemId">
<description>Sets the system identifier of this InputSource.</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="getSystemId">
<description>Returns the system identifier of this InputSource.</description>

</element>

<element kind="function" name="setEncoding">
<description>Sets the character encoding of this InputSource.
The encoding must be a string acceptable for an XML encoding
declaration (see section 4.3.3 of the XML recommendation).
The encoding attribute of the InputSource is ignored if the
InputSource also contains a character stream.</description>

<properties><property kind="parameter" name="encodingencoding" required="1"/></properties></element>

<element kind="function" name="getEncoding">
<description>Get the character encoding of this InputSource.</description>

</element>

<element kind="function" name="setByteStream">
<description>Set the byte stream (a Python file-like object which does not
perform byte-to-character conversion) for this input source.
The SAX parser will ignore this if there is also a character stream
specified, but it will use a byte stream in preference to opening a
URI connection itself.
If the application knows the character encoding of the byte stream,
it should set it with the setEncoding method.</description>

<properties><property kind="parameter" name="bytefilebytefile" required="1"/></properties></element>

<element kind="function" name="getByteStream">
<description>Get the byte stream for this input source.
The getEncoding method will return the character encoding for this
byte stream, or None if unknown.</description>

</element>

<element kind="function" name="setCharacterStream">
<description>Set the character stream for this input source. (The stream must be
a Python 1.6 Unicode-wrapped file-like that performs conversion to
Unicode strings.)
If there is a character stream specified, the SAX parser will ignore
any byte stream and will not attempt to open a URI connection to the
system identifier.</description>

<properties><property kind="parameter" name="charfilecharfile" required="1"/></properties></element>

<element kind="function" name="getCharacterStream">
<description>Get the character stream for this input source.</description>

</element>

</group>
<group name="The Attributes Interface">
<description>Attributes objects implement a portion of the mapping
protocol, including the methods copy(), get(),
has_key(), items(), keys(), and
values(). The following methods are also provided:
</description>
<element kind="function" name="getLength">
<description>Return the number of attributes.</description>

</element>

<element kind="function" name="getNames">
<description>Return the names of the attributes.</description>

</element>

<element kind="function" name="getType">
<description>Returns the type of the attribute name, which is normally
'CDATA'.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getValue">
<description>Return the value of attribute name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

</group>
<group name="The AttributesNS Interface">
<description>This interface is a subtype of the Attributes
interface{attributes-objects.html} (see
section~attributes-objects). All methods supported by that
interface are also available on AttributesNS objects.
The following methods are also available:
</description>
<element kind="function" name="getValueByQName">
<description>Return the value for a qualified name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getNameByQName">
<description>Return the (namespace, localname) pair for a
qualified name.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getQNameByName">
<description>Return the qualified name for a (namespace,
localname) pair.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="getQNames">
<description>Return the qualified names of all attributes.</description>

</element>

</group>
</group>
<group name="xmllib --- A parser for XML documents">
<description>A parser for XML documents.
</description>
<element kind="function" name="XMLParser">
<description>The XMLParser class must be instantiated without
arguments.Actually, a number of keyword arguments are
recognized which influence the parser to accept certain non-standard
constructs. The following keyword arguments are currently
recognized. The defaults for all of these is 0 (false) except
for the last one for which the default is 1 (true).
accept_unquoted_attributes (accept certain attribute values
without requiring quotes), accept_missing_endtag_name (accept
end tags that look like &lt;/&gt;), map_case (map upper case to
lower case in tags and attributes), accept_utf8 (allow UTF-8
characters in input; this is required according to the XML standard,
but Python does not as yet deal properly with these characters, so
this is not the default), translate_attribute_references (don't
attempt to translate character and entity references in attribute values).</description>

</element>

<element kind="function" name="reset">
<description>Reset the instance. Loses all unprocessed data. This is called
implicitly at the instantiation time.</description>

</element>

<element kind="function" name="setnomoretags">
<description>Stop processing tags. Treat all following input as literal input
(CDATA).</description>

</element>

<element kind="function" name="setliteral">
<description>Enter literal mode (CDATA mode). This mode is automatically exited
when the close tag matching the last unclosed open tag is encountered.</description>

</element>

<element kind="function" name="feed">
<description>Feed some text to the parser. It is processed insofar as it consists
of complete tags; incomplete data is buffered until more data is
fed or close() is called.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="close">
<description>Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the
redefined version should always call close().</description>

</element>

<element kind="function" name="translate_references">
<description>Translate all entity and character references in data and
return the translated string.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="getnamespace">
<description>Return a mapping of namespace abbreviations to namespace URIs that are
currently in effect.</description>

</element>

<element kind="function" name="handle_xml">
<description>This method is called when the &lt;?xml ...?&gt; tag is processed.
The arguments are the values of the encoding and standalone attributes in the tag. Both encoding and standalone are optional. The values
passed to handle_xml() default to None and the string
'no' respectively.</description>

<properties><property kind="parameter" name="encoding" required="1"/><property kind="parameter" name="standalone standalone" required="1"/></properties></element>

<element kind="function" name="handle_doctype">
<description>This</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="pubid" required="1"/><property kind="parameter" name="syslit" required="1"/><property kind="parameter" name="data data" required="1"/></properties></element>

<element kind="function" name="handle_starttag">
<description>This method is called to handle start tags for which a start tag
handler is defined in the instance variable elements. The
tag argument is the name of the tag, and the
method argument is the function (method) which should be used to
support semantic interpretation of the start tag. The
attributes argument is a dictionary of attributes, the key being
the name and the value being the value of the attribute
found inside the tag's &lt;&gt; brackets. Character and entity
references in the value have been interpreted. For instance,
for the start tag &lt;A HREF=&quot;http://www.cwi.nl/&quot;&gt;, this method
would be called as handle_starttag('A', self.elements['A'][0],
{'HREF': 'http://www.cwi.nl/'}). The base implementation simply
calls method with attributes as the only argument.</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="method" required="1"/><property kind="parameter" name="attributes attributes" required="1"/></properties></element>

<element kind="function" name="handle_endtag">
<description>This method is called to handle endtags for which an end tag handler
is defined in the instance variable elements. The tag
argument is the name of the tag, and the method argument is the
function (method) which should be used to support semantic
interpretation of the end tag. For instance, for the endtag
&lt;/A&gt;, this method would be called as handle_endtag('A',
self.elements['A'][1]). The base implementation simply calls
method.</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="method method" required="1"/></properties></element>

<element kind="function" name="handle_data">
<description>This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does
nothing.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="handle_charref">
<description>This method is called to process a character reference of the form
#ref;. ref can either be a decimal number,
or a hexadecimal number when preceded by an x.
In the base implementation, ref must be a number in the
range 0-255. It translates the character to ASCII and calls the
method handle_data() with the character as argument. If
ref is invalid or out of range, the method
unknown_charref(ref) is called to handle the error. A
subclass must override this method to provide support for character
references outside of the ASCII range.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

<element kind="function" name="handle_comment">
<description>This method is called when a comment is encountered. The
comment argument is a string containing the text between the
&lt;!-- and --&gt; delimiters, but not the delimiters
themselves. For example, the comment &lt;!--text--&gt; will
cause this method to be called with the argument 'text'. The
default method does nothing.</description>

<properties><property kind="parameter" name="commentcomment" required="1"/></properties></element>

<element kind="function" name="handle_cdata">
<description>This method is called when a CDATA element is encountered. The
data argument is a string containing the text between the
&lt;![CDATA[ and ]]&gt; delimiters, but not the delimiters
themselves. For example, the entity &lt;![CDATA[text]]&gt; will
cause this method to be called with the argument 'text'. The
default method does nothing, and is intended to be overridden.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="handle_proc">
<description>This method is called when a processing instruction (PI) is
encountered. The name is the PI target, and the data
argument is a string containing the text between the PI target and the
closing delimiter, but not the delimiter itself. For example, the
instruction &lt;?XML text?&gt; will cause this method to be called
with the arguments 'XML' and 'text'. The default method
does nothing. Note that if a document starts with &lt;?xml
..?&gt;, handle_xml() is called to handle it.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="data data" required="1"/></properties></element>

<element kind="function" name="handle_special">
<description>This method is called when a declaration is encountered. The
data argument is a string containing the text between the
&lt;! and &gt; delimiters, but not the delimiters
themselves. For example, the </description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="syntax_error">
<description>This method is called when a syntax error is encountered. The
message is a description of what was wrong. The default method raises a RuntimeError exception. If this method is
overridden, it is permissible for it to return. This method is only
called when the error can be recovered from. Unrecoverable errors
raise a RuntimeError without first calling
syntax_error().</description>

<properties><property kind="parameter" name="messagemessage" required="1"/></properties></element>

<element kind="function" name="unknown_starttag">
<description>This method is called to process an unknown start tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.</description>

<properties><property kind="parameter" name="tag" required="1"/><property kind="parameter" name="attributes attributes" required="1"/></properties></element>

<element kind="function" name="unknown_endtag">
<description>This method is called to process an unknown end tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.</description>

<properties><property kind="parameter" name="tagtag" required="1"/></properties></element>

<element kind="function" name="unknown_charref">
<description>This method is called to process unresolvable numeric character
references. It is intended to be overridden by a derived class; the
base class implementation does nothing.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

<element kind="function" name="unknown_entityref">
<description>This method is called to process an unknown entity reference. It is
intended to be overridden by a derived class; the base class
implementation calls syntax_error() to signal an error.</description>

<properties><property kind="parameter" name="refref" required="1"/></properties></element>

<group name="XML Namespaces">
</group>
</group>
</group>
<group name="Multimedia Services">
<group name="audioop --- Manipulate raw audio data">
<description>Manipulate raw audio data.
The audioop module contains some useful operations on sound
fragments. It operates on sound fragments consisting of signed
integer samples 8, 16 or 32 bits wide, stored in Python strings. This
is the same format as used by the al and sunaudiodev
modules. All scalar items are integers, unless specified otherwise.
% This para is mostly here to provide an excuse for the index entries...
This module provides support for u-LAW and Intel/DVI ADPCM encodings.
</description>
<element kind="function" name="add">
<description>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.</description>

<properties><property kind="parameter" name="fragment1" required="1"/><property kind="parameter" name="fragment2" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="adpcm2lin">
<description>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.</description>

<properties><property kind="parameter" name="adpcmfragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="state state" required="1"/></properties></element>

<element kind="function" name="adpcm32lin">
<description>Decode an alternative 3-bit ADPCM code. See lin2adpcm3()
for details.</description>

<properties><property kind="parameter" name="adpcmfragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="state state" required="1"/></properties></element>

<element kind="function" name="avg">
<description>Return the average over all samples in the fragment.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="avgpp">
<description>Return the average peak-peak value over all samples in the fragment.
No filtering is done, so the usefulness of this routine is
questionable.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="bias">
<description>Return a fragment that is the original fragment with a bias added to
each sample.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="bias bias" required="1"/></properties></element>

<element kind="function" name="cross">
<description>Return the number of zero crossings in the fragment passed as an
argument.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="findfactor">
<description>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).</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="reference reference" required="1"/></properties></element>

<element kind="function" name="findfit">
<description>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().</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="reference reference" required="1"/></properties></element>

<element kind="function" name="findmax">
<description>Search fragment for a slice of length length samples (not
bytes!) 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).</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="length length" required="1"/></properties></element>

<element kind="function" name="getsample">
<description>Return the value of sample index from the fragment.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="index index" required="1"/></properties></element>

<element kind="function" name="lin2lin">
<description>Convert samples between 1-, 2- and 4-byte formats.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="newwidth newwidth" required="1"/></properties></element>

<element kind="function" name="lin2adpcm">
<description>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.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="state state" required="1"/></properties></element>

<element kind="function" name="lin2adpcm3">
<description>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.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="state state" required="1"/></properties></element>

<element kind="function" name="lin2ulaw">
<description>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.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="minmax">
<description>Return a tuple consisting of the minimum and maximum values of all
samples in the sound fragment.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="max">
<description>Return the maximum of the absolute value of all samples in a
fragment.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="maxpp">
<description>Return the maximum peak-peak value in the sound fragment.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="mul">
<description>Return a fragment that has all samples in the original fragment
multiplied by the floating-point value factor. Overflow is
silently ignored.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="factor factor" required="1"/></properties></element>

<element kind="function" name="ratecv">
<description>Convert the frame rate of the input fragment.
state is a tuple containing the state of the converter. The
converter returns a tuple (newfragment, newstate),
and newstate should be passed to the next call of
ratecv(). The initial call should pass None
as the state.
The weightA and weightB arguments are parameters for a
simple digital filter and default to 1 and 0 respectively.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="nchannels" required="1"/><property kind="parameter" name="inrate" required="1"/><property kind="parameter" name="outrate" required="1"/><property kind="parameter" name="state" required="1"/><property kind="parameter" name="weightA"/><property kind="parameter" name="weightB"/></properties></element>

<element kind="function" name="reverse">
<description>Reverse the samples in a fragment and returns the modified fragment.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="rms">
<description>Return the root-mean-square of the fragment, i.e.
`_=8
{S_{i}}^{2}{n}
This is a measure of the power in an audio signal.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

<element kind="function" name="tomono">
<description>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.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="lfactor" required="1"/><property kind="parameter" name="rfactor rfactor" required="1"/></properties></element>

<element kind="function" name="tostereo">
<description>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.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="lfactor" required="1"/><property kind="parameter" name="rfactor rfactor" required="1"/></properties></element>

<element kind="function" name="ulaw2lin">
<description>Convert sound fragments in u-LAW encoding to linearly encoded sound
fragments. u-LAW encoding always uses 8 bits samples, so width
refers only to the sample width of the output fragment here.</description>

<properties><property kind="parameter" name="fragment" required="1"/><property kind="parameter" name="width width" required="1"/></properties></element>

</group>
<group name="imageop --- Manipulate raw image data">
<description>Manipulate raw image data.
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:
{error}
This exception is raised on all errors, such as unknown number of bits
per pixel, etc.
</description>
<element kind="function" name="crop">
<description>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 gl.lrectread() parameters, i.e. 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.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="psize" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height" required="1"/><property kind="parameter" name="x0" required="1"/><property kind="parameter" name="y0" required="1"/><property kind="parameter" name="x1" required="1"/><property kind="parameter" name="y1 y1" required="1"/></properties></element>

<element kind="function" name="scale">
<description>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.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="psize" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height" required="1"/><property kind="parameter" name="newwidth" required="1"/><property kind="parameter" name="newheight newheight" required="1"/></properties></element>

<element kind="function" name="tovideo">
<description>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.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="psize" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="grey2mono">
<description>Convert a 8-bit deep greyscale image to a 1-bit deep image by
thresholding all the pixels. The resulting image is tightly packed and
is probably only useful as an argument to mono2grey().</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height" required="1"/><property kind="parameter" name="threshold threshold" required="1"/></properties></element>

<element kind="function" name="dither2mono">
<description>Convert an 8-bit greyscale image to a 1-bit monochrome image using a
(simple-minded) dithering algorithm.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="mono2grey">
<description>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.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height" required="1"/><property kind="parameter" name="p0" required="1"/><property kind="parameter" name="p1 p1" required="1"/></properties></element>

<element kind="function" name="grey2grey4">
<description>Convert an 8-bit greyscale image to a 4-bit greyscale image without
dithering.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="grey2grey2">
<description>Convert an 8-bit greyscale image to a 2-bit greyscale image without
dithering.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="dither2grey2">
<description>Convert an 8-bit greyscale image to a 2-bit greyscale image with
dithering. As for dither2mono(), the dithering algorithm
is currently very simple.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="grey42grey">
<description>Convert a 4-bit greyscale image to an 8-bit greyscale image.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="grey22grey">
<description>Convert a 2-bit greyscale image to an 8-bit greyscale image.</description>

<properties><property kind="parameter" name="image" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

</group>
<group name="aifc --- Read and write AIFF and AIFC files">
<description>Read and write audio files in AIFF or AIFC format.
This module provides support for reading and writing AIFF and AIFF-C
files. AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file. AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
</description>
<element kind="function" name="open">
<description>Open an AIFF or AIFF-C file and return an object instance with
methods that are described below. The argument file is either a
string naming a file or a file object. mode must be 'r'
or 'rb' when the file must be opened for reading, or 'w' or 'wb' when the file must be opened for writing. If omitted,
file.mode is used if it exists, otherwise 'rb' is
used. When used for writing, the file object should be seekable,
unless you know ahead of time how many samples you are going to write
in total and use writeframesraw() and setnframes().</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="getnchannels">
<description>Return the number of audio channels (1 for mono, 2 for stereo).</description>

</element>

<element kind="function" name="getsampwidth">
<description>Return the size in bytes of individual samples.</description>

</element>

<element kind="function" name="getframerate">
<description>Return the sampling rate (number of audio frames per second).</description>

</element>

<element kind="function" name="getnframes">
<description>Return the number of audio frames in the file.</description>

</element>

<element kind="function" name="getcomptype">
<description>Return a four-character string describing the type of compression used
in the audio file. For AIFF files, the returned value is
'NONE'.</description>

</element>

<element kind="function" name="getcompname">
<description>Return a human-readable description of the type of compression used in
the audio file. For AIFF files, the returned value is 'not
compressed'.</description>

</element>

<element kind="function" name="getparams">
<description>Return a tuple consisting of all of the above values in the above
order.</description>

</element>

<element kind="function" name="getmarkers">
<description>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).</description>

</element>

<element kind="function" name="getmark">
<description>Return the tuple as described in getmarkers() for the mark
with the given id.</description>

<properties><property kind="parameter" name="idid" required="1"/></properties></element>

<element kind="function" name="readframes">
<description>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.</description>

<properties><property kind="parameter" name="nframesnframes" required="1"/></properties></element>

<element kind="function" name="rewind">
<description>Rewind the read pointer. The next readframes() will start from
the beginning.</description>

</element>

<element kind="function" name="setpos">
<description>Seek to the specified frame number.</description>

<properties><property kind="parameter" name="pospos" required="1"/></properties></element>

<element kind="function" name="tell">
<description>Return the current frame number.</description>

</element>

<element kind="function" name="close">
<description>Close the AIFF file. After calling this method, the object can no
longer be used.</description>

</element>

<element kind="function" name="aiff">
<description>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.</description>

</element>

<element kind="function" name="aifc">
<description>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.</description>

</element>

<element kind="function" name="setnchannels">
<description>Specify the number of channels in the audio file.</description>

<properties><property kind="parameter" name="nchannelsnchannels" required="1"/></properties></element>

<element kind="function" name="setsampwidth">
<description>Specify the size in bytes of audio samples.</description>

<properties><property kind="parameter" name="widthwidth" required="1"/></properties></element>

<element kind="function" name="setframerate">
<description>Specify the sampling frequency in frames per second.</description>

<properties><property kind="parameter" name="raterate" required="1"/></properties></element>

<element kind="function" name="setnframes">
<description>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.</description>

<properties><property kind="parameter" name="nframesnframes" required="1"/></properties></element>

<element kind="function" name="setcomptype">
<description>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.
</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="setparams">
<description>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().</description>

<properties><property kind="parameter" name="nchannels" required="1"/><property kind="parameter" name="sampwidth" required="1"/><property kind="parameter" name="framerate" required="1"/><property kind="parameter" name="comptype" required="1"/><property kind="parameter" name="compname compname" required="1"/></properties></element>

<element kind="function" name="setmark">
<description>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().</description>

<properties><property kind="parameter" name="id" required="1"/><property kind="parameter" name="pos" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="tell">
<description>Return the current write position in the output file. Useful in
combination with setmark().</description>

</element>

<element kind="function" name="writeframes">
<description>Write data to the output file. This method can only be called after
the audio file parameters have been set.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="writeframesraw">
<description>Like writeframes(), except that the header of the audio file
is not updated.</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="close">
<description>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.</description>

</element>

</group>
<group name="sunau --- Read and write Sun AU files">
<description>Provide an interface to the Sun AU sound format.
The sunau module provides a convenient interface to the Sun
AU sound format. Note that this module is interface-compatible with
the modules aifc and wave.
An audio file consists of a header followed by the data. The fields
of the header are:
{l|l}{textrm}{Field}{Contents}
magic word{The four bytes .snd.}
header size{Size of the header, including info, in bytes.}
data size{Physical size of the data, in bytes.}
encoding{Indicates how the audio samples are encoded.}
sample rate{The sampling rate.}
channels{The number of channels in the samples.}
info{ASCII string giving a description of the audio
file (padded with null bytes).}
Apart from the info field, all header fields are 4 bytes in size.
They are all 32-bit unsigned integers encoded in big-endian byte
order.
The sunau module defines the following functions:
</description>
<element kind="function" name="open">
<description>If file is a string, open the file by that name, otherwise treat it
as a seekable file-like object. mode can be any of
['r'] Read only mode.
['w'] Write only mode.
Note that it does not allow read/write files.
A mode of 'r' returns a AU_read
object, while a mode of 'w' or 'wb' returns
a AU_write object.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode mode" required="1"/></properties></element>

<element kind="function" name="openfp">
<description>A synonym for open, maintained for backwards compatibility.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode mode" required="1"/></properties></element>

<group name="AU_read Objects">
<description>AU_read objects, as returned by open() above, have the
following methods:
[AU_read]{close}{}
Close the stream, and make the instance unusable. (This is called automatically on deletion.)
[AU_read]{getnchannels}{}
Returns number of audio channels (1 for mone, 2 for stereo).
[AU_read]{getsampwidth}{}
Returns sample width in bytes.
[AU_read]{getframerate}{}
Returns sampling frequency.
[AU_read]{getnframes}{}
Returns number of audio frames.
[AU_read]{getcomptype}{}
Returns compression type.
Supported compression types are 'ULAW', 'ALAW' and 'NONE'.
[AU_read]{getcompname}{}
Human-readable version of getcomptype(). The supported types have the respective names 'CCITT G.711
u-law', 'CCITT G.711 A-law' and 'not compressed'.
[AU_read]{getparams}{}
Returns a tuple (nchannels, sampwidth,
framerate, nframes, comptype, compname),
equivalent to output of the get*() methods.
[AU_read]{readframes}{n}
Reads and returns at most n frames of audio, as a string of
bytes. The data will be returned in linear format. If the original
data is in u-LAW format, it will be converted.
[AU_read]{rewind}{}
Rewind the file pointer to the beginning of the audio stream.
The following two methods define a term ``position'' which is compatible
between them, and is otherwise implementation dependent.
[AU_read]{setpos}{pos}
Set the file pointer to the specified position. Only values returned
from tell() should be used for pos.
[AU_read]{tell}{}
Return current file pointer position. Note that the returned value
has nothing to do with the actual position in the file.
The following two functions are defined for compatibility with the aifc, and don't do anything interesting.
[AU_read]{getmarkers}{}
Returns None.
[AU_read]{getmark}{id}
Raise an error.
</description>
</group>
<group name="AU_write Objects">
</group>
</group>
<group name="wave --- Read and write WAV files">
<description>Provide an interface to the WAV sound format.
The wave module provides a convenient interface to the WAV sound
format. It does not support compression/decompression, but it does support
mono/stereo.
The wave module defines the following function and exception:
</description>
<element kind="function" name="open">
<description>If file is a string, open the file by that name, other treat it
as a seekable file-like object. mode can be any of
['r', 'rb'] Read only mode.
['w', 'wb'] Write only mode.
Note that it does not allow read/write WAV files.
A mode of 'r' or 'rb' returns a Wave_read
object, while a mode of 'w' or 'wb' returns
a Wave_write object. If mode is omitted and a file-like object is passed as file, file.mode is used as the
default value for mode (the b flag is still added if necessary).</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode"/></properties></element>

<element kind="function" name="openfp">
<description>A synonym for open(), maintained for backwards compatibility.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="mode mode" required="1"/></properties></element>

<group name="Wave_read Objects">
<description>Wave_read objects, as returned by open(), have the
following methods:
[Wave_read]{close}{}
Close the stream, and make the instance unusable. This is
called automatically on object collection.
[Wave_read]{getnchannels}{}
Returns number of audio channels (1 for mono, 2 for
stereo).
[Wave_read]{getsampwidth}{}
Returns sample width in bytes.
[Wave_read]{getframerate}{}
Returns sampling frequency.
[Wave_read]{getnframes}{}
Returns number of audio frames.
[Wave_read]{getcomptype}{}
Returns compression type ('NONE' is the only supported type).
[Wave_read]{getcompname}{}
Human-readable version of getcomptype().
Usually 'not compressed' parallels 'NONE'.
[Wave_read]{getparams}{}
Returns a tuple
(nchannels, sampwidth, framerate,
nframes, comptype, compname), equivalent to output
of the get*() methods.
[Wave_read]{readframes}{n}
Reads and returns at most n frames of audio, as a string of bytes.
[Wave_read]{rewind}{}
Rewind the file pointer to the beginning of the audio stream.
The following two methods are defined for compatibility with the
aifc module, and don't do anything interesting.
[Wave_read]{getmarkers}{}
Returns None.
[Wave_read]{getmark}{id}
Raise an error.
The following two methods define a term ``position'' which is compatible
between them, and is otherwise implementation dependent.
[Wave_read]{setpos}{pos}
Set the file pointer to the specified position.
[Wave_read]{tell}{}
Return current file pointer position.
</description>
</group>
<group name="Wave_write Objects">
</group>
</group>
<group name="chunk --- Read IFF chunked data">
<description>Module to read IFF chunks.
This module provides an interface for reading files that use EA IFF 85
chunks.``EA IFF 85'' Standard for Interchange Format Files,
Jerry Morrison, Electronic Arts, January 1985. This format is used
in at least the Audio</description>
<element kind="function" name="Chunk">
<description>Class which represents a chunk. The file argument is expected
to be a file-like object. An instance of this class is specifically
allowed. The only method that is needed is read(). If the
methods seek() and tell() are present and don't
raise an exception, they are also used. If these methods are present
and raise an exception, they are expected to not have altered the
object. If the optional argument align is true, chunks are
assumed to be aligned on 2-byte boundaries. If align is
false, no alignment is assumed. The default value is true. If the
optional argument bigendian is false, the chunk size is assumed
to be in little-endian order. This is needed for WAVE audio files.
The default value is true. If the optional argument inclheader
is true, the size given in the chunk header includes the size of the
header. The default value is false.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="align"/><property kind="parameter" name="bigendian"/><property kind="parameter" name="inclheader"/></properties></element>

<element kind="function" name="getname">
<description>Returns the name (ID) of the chunk. This is the first 4 bytes of the
chunk.</description>

</element>

<element kind="function" name="getsize">
<description>Returns the size of the chunk.</description>

</element>

<element kind="function" name="close">
<description>Close and skip to the end of the chunk. This does not close the
underlying file.</description>

</element>

<element kind="function" name="isatty">
<description>Returns False.</description>

</element>

<element kind="function" name="seek">
<description>Set the chunk's current position. The whence argument is
optional and defaults to 0 (absolute file positioning); other
values are 1 (seek relative to the current position) and
2 (seek relative to the file's end). There is no return value.
If the underlying file does not allow seek, only forward seeks are
allowed.</description>

<properties><property kind="parameter" name="pos" required="1"/><property kind="parameter" name="whence"/></properties></element>

<element kind="function" name="tell">
<description>Return the current position into the chunk.</description>

</element>

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

<properties><property kind="parameter" name="size" required="1"/></properties></element>

<element kind="function" name="skip">
<description>Skip to the end of the chunk. All further calls to read()
for the chunk will return ''. If you are not interested in the
contents of the chunk, this method should be called so that the file
points to the start of the next chunk.</description>

</element>

</group>
<group name="colorsys --- Conversions between color systems">
<description>Conversion functions between RGB and other color systems.
The colorsys module defines bidirectional conversions of
color values between colors expressed in the RGB (Red Green Blue)
color space used in computer monitors and three other coordinate
systems: YIQ, HLS (Hue Lightness Saturation) and HSV (Hue Saturation
Value). Coordinates in all of these color spaces are floating point
values. In the YIQ space, the Y coordinate is between 0 and 1, but
the I and Q coordinates can be positive or negative. In all other
spaces, the coordinates are all between 0 and 1.
More information about color spaces can be found at http://www.poynton.com/ColorFAQ.html.
The colorsys module defines the following functions:
</description>
<element kind="function" name="rgb_to_yiq">
<description>Convert the color from RGB coordinates to YIQ coordinates.</description>

<properties><property kind="parameter" name="r" required="1"/><property kind="parameter" name="g" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="yiq_to_rgb">
<description>Convert the color from YIQ coordinates to RGB coordinates.</description>

<properties><property kind="parameter" name="y" required="1"/><property kind="parameter" name="i" required="1"/><property kind="parameter" name="q q" required="1"/></properties></element>

<element kind="function" name="rgb_to_hls">
<description>Convert the color from RGB coordinates to HLS coordinates.</description>

<properties><property kind="parameter" name="r" required="1"/><property kind="parameter" name="g" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="hls_to_rgb">
<description>Convert the color from HLS coordinates to RGB coordinates.</description>

<properties><property kind="parameter" name="h" required="1"/><property kind="parameter" name="l" required="1"/><property kind="parameter" name="s s" required="1"/></properties></element>

<element kind="function" name="rgb_to_hsv">
<description>Convert the color from RGB coordinates to HSV coordinates.</description>

<properties><property kind="parameter" name="r" required="1"/><property kind="parameter" name="g" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="hsv_to_rgb">
<description>Convert the color from HSV coordinates to RGB coordinates.</description>

<properties><property kind="parameter" name="h" required="1"/><property kind="parameter" name="s" required="1"/><property kind="parameter" name="v v" required="1"/></properties></element>

</group>
<group name="rgbimg --- Read and write ``SGI RGB'' files">
<description>Read and write image files in ``SGI RGB'' format (the module
is not SGI specific though!).
The rgbimg 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
enough in some cases. Currently, colormap files are not supported.
This module is only built by default for 32-bit platforms; it is
not expected to work properly on other systems.
The module defines the following variables and functions:
{error}
This exception is raised on all errors, such as unsupported file type, etc.
</description>
<element kind="function" name="sizeofimage">
<description>This function returns a tuple (x, y) where
x and y are the size of the image in pixels.
Only 4 byte RGBA pixels, 3 byte RGB pixels, and 1 byte greyscale pixels
are currently supported.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="longimagedata">
<description>This function reads and decodes the image on the specified file, and
returns it as a Python string. The string has 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.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="longstoimage">
<description>This function writes the RGBA data in data to image
file file. x and y give the size of the image.
z is 1 if the saved image should be 1 byte greyscale, 3 if the
saved image should be 3 byte RGB data, or 4 if the saved images should
be 4 byte RGBA data. The input data always contains 4 bytes per pixel.
These are the formats returned by gl.lrectread().</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="z" required="1"/><property kind="parameter" name="file file" required="1"/></properties></element>

<element kind="function" name="ttob">
<description>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.</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

</group>
<group name="imghdr --- Determine the type of an image">
<description>Determine the type of image contained in a file or
byte stream.
The imghdr module determines the type of image contained in a
file or byte stream.
The imghdr module defines the following function:
</description>
<element kind="function" name="what">
<description>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.</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="h"/></properties></element>

</group>
<group name="sndhdr --- Determine type of sound file">
<description>Determine type of a sound file.
% Based on comments in the module source file.
The sndhdr provides utility functions which attempt to
determine the type of sound data which is in a file. When these
functions are able to determine what type of sound data is stored in a
file, they return a tuple (type, sampling_rate,
channels, frames, bits_per_sample). The value for
type indicates the data type and will be one of the strings
'aifc', 'aiff', 'au', 'hcom',
'sndr', 'sndt', 'voc', 'wav',
'8svx', 'sb', 'ub', or 'ul'. The
sampling_rate will be either the actual value or 0 if
unknown or difficult to decode. Similarly, channels will be
either the number of channels or 0 if it cannot be determined
or if the value is difficult to decode. The value for frames
will be either the number of frames or -1. The last item in
the tuple, bits_per_sample, will either be the sample size in
bits or 'A' for A-LAW</description>
<element kind="function" name="what">
<description>Determines the type of sound data stored in the file filename
using whathdr(). If it succeeds, returns a tuple as
described above, otherwise None is returned.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="whathdr">
<description>Determines the type of sound data stored in a file based on the file header. The name of the file is given by filename. This
function returns a tuple as described above on success, or
None.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

</group>
<group name="ossaudiodev --- Access to OSS-compatible audio devices">
<description>Linux, FreeBSD, maybe other Unix-like systems
Access to OSS-compatible audio devices.
This module allows you to access the OSS (Open Sound System) audio
interface. OSS is available for a wide range of open-source and
commercial Unices, and is the standard audio interface for Linux and
recent versions of FreeBSD.
% Things will get more complicated for future Linux versions, since
% ALSA is in the standard kernel as of 2.5.x. Presumably if you
% use ALSA, you'll have to make sure its OSS compatibility layer
% is active to use ossaudiodev, but you're gonna need it for the vast
% majority of Linux audio apps anyways. %
% Sounds like things are also complicated for other BSDs. In response
% to my python-dev query, Thomas Wouters said:
%
% &gt; Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
% &gt; OSS installation manual tells you to remove references to OSS/Free from the
% &gt; kernel :)
%
% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
% from its &lt;soundcard.h&gt;:
% &gt; * WARNING! WARNING!
% &gt; * This is an OSS (Linux) audio emulator.
% &gt; * Use the Native NetBSD API for developing new code, and this
% &gt; * only for compiling Linux programs.
%
% There's also an ossaudio manpage on OpenBSD that explains things
% further. Presumably NetBSD and OpenBSD have a different standard
% audio interface. That's the great thing about standards, there are so
% many to choose from ... ;-) %
% This probably all warrants a footnote or two, but I don't understand
% things well enough right now to write it! --GPW
[http://www.opensound.com/pguide/oss.pdf]
{Open Sound System Programmer's Guide} {the official
documentation for the OSS C API}
The module defines a large number of constants supplied by
the OSS device driver; see &lt;sys/soundcard.h&gt; on either
Linux or FreeBSD for a listing .
ossaudiodev defines the following variables and functions:
{OSSAudioError}
This exception is raised on certain errors. The argument is a string
describing what went wrong.
(If ossaudiodev receives an error from a system call such as
open(), write(), or ioctl(), it
raises IOError. Errors detected directly by
ossaudiodev result in OSSAudioError.)
(For backwards compatibility, the exception class is also available as
ossaudiodev.error.)
</description>
<element kind="function" name="open">
<description>Open an audio device and return an OSS audio device object. This
object supports many file-like methods, such as read(),
write(), and fileno() (although there are subtle
differences between conventional Unix read/write semantics and those of
OSS audio devices). It also supports a number of audio-specific
methods; see below for the complete list of methods.
device is the audio device filename to use. If it is not
specified, this module first looks in the environment variable
AUDIODEV for a device to use. If not found, it falls back to
/dev/dsp.
mode is one of 'r' for read-only (record) access,
'w' for write-only (playback) access and 'rw' for both.
Since many sound cards only allow one process to have the recorder or
player open at a time, it is a good idea to open the device only for the
activity needed. Further, some sound cards are half-duplex: they can be
opened for reading or writing, but not both at once.
Note the unusual calling syntax: the first argument is optional,
and the second is required. This is a historical artifact for
compatibility with the older linuxaudiodev module which
ossaudiodev supersedes. % XXX it might also be motivated
% by my unfounded-but-still-possibly-true belief that the default
% audio device varies unpredictably across operating systems. -GW</description>

<properties><property kind="parameter" name="device" required="1"/><property kind="parameter" name="modemode"/></properties></element>

<element kind="function" name="openmixer">
<description>Open a mixer device and return an OSS mixer device object. device is the mixer device filename to use. If it is
not specified, this module first looks in the environment variable
MIXERDEV for a device to use. If not found, it falls back to
/dev/mixer.</description>

<properties><property kind="parameter" name="device" required="1"/></properties></element>

<group name="Audio Device Objects">
<description>Before you can write to or read from an audio device, you must call
three methods in the correct order:
setfmt() to set the output format
channels() to set the number of channels
speed() to set the sample rate
Alternately, you can use the setparameters() method to set all
three audio parameters at once. This is more convenient, but may not be
as flexible in all cases.
The audio device objects returned by open() define the
following methods:
[audio device]{close}{}
Explicitly close the audio device. When you are done writing to or
reading from an audio device, you should explicitly close it. A closed
device cannot be used again.
[audio device]{fileno}{}
Return the file descriptor associated with the device.
[audio device]{read}{size}
Read size bytes from the audio input and return them as a Python
string. Unlike most device drivers, OSS audio devices in
blocking mode (the default) will block read() until the
entire requested amount of data is available.
[audio device]{write}{data}
Write the Python string data to the audio device and return the
number of bytes written. If the audio device is in blocking mode (the
default), the entire string is always written (again, this is different
from usual device semantics). If the device is in non-blocking
mode, some data may not be written---see writeall().
[audio device]{writeall}{data}
Write the entire Python string data to the audio device: waits
until the audio device is able to accept data, writes as much data as it
will accept, and repeats until data has been completely written.
If the device is in blocking mode (the default), this has the same
effect as write(); writeall() is only useful in
non-blocking mode. Has no return value, since the amount of data
written is always equal to the amount of data supplied.
The following methods each map to exactly one
ioctl() system call. The correspondence is obvious: for
example, setfmt() corresponds to the SNDCTL_DSP_SETFMT
ioctl, and sync() to SNDCTL_DSP_SYNC (this can be useful
when consulting the OSS documentation). If the underlying
ioctl() fails, they all raise IOError.
[audio device]{nonblock}{}
Put the device into non-blocking mode. Once in non-blocking mode, there
is no way to return it to blocking mode.
[audio device]{getfmts}{}
Return a bitmask of the audio output formats supported by the
soundcard. On a typical Linux system, these formats are:
{l|l}{constant}{Format}{Description}
AFMT_MU_LAW
{a logarithmic encoding (used by Sun .au files and
/dev/audio)}
AFMT_A_LAW
{a logarithmic encoding}
AFMT_IMA_ADPCM
{a 4:1 compressed format defined by the Interactive Multimedia
Association} AFMT_U8
{Unsigned, 8-bit audio}
AFMT_S16_LE
{Unsigned, 16-bit audio, little-endian byte order (as used by
Intel processors)}
AFMT_S16_BE
{Unsigned, 16-bit audio, big-endian byte order (as used by 68k,
PowerPC, Sparc)}
AFMT_S8
{Signed, 8 bit audio}
AFMT_U16_LE
{Signed, 16-bit little-endian audio}
AFMT_U16_BE
{Signed, 16-bit big-endian audio}
Most systems support only a subset of these formats. Many devices only
support AFMT_U8; the most common format used today is
AFMT_S16_LE.
[audio device]{setfmt}{format}
Try to set the current audio format to format---see
getfmts() for a list. Returns the audio format that the device
was set to, which may not be the requested format. May also be used to
return the current audio format---do this by passing an ``audio format''
of
AFMT_QUERY. [audio device]{channels}{nchannels}
Set the number of output channels to nchannels. A value of 1
indicates monophonic sound, 2 stereophonic. Some devices may have more
than 2 channels, and some high-end devices may not support mono.
Returns the number of channels the device was set to.
[audio device]{speed}{samplerate}
Try to set the audio sampling rate to samplerate samples per
second. Returns the rate actually set. Most sound devices don't
support arbitrary sampling rates. Common rates are:
{l|l}{textrm}{Rate}{Description}
8000{default rate for /dev/audio}
11025{speech recording}
22050{}
44100{CD quality audio (at 16 bits/sample and 2 channels)}
96000{DVD quality audio (at 24 bits/sample)}
[audio device]{sync}{}
Wait until the sound device has played every byte in its buffer. (This
happens implicitly when the device is closed.) The OSS documentation
recommends closing and re-opening the device rather than using
sync().
[audio device]{reset}{}
Immediately stop playing or recording and return the device to a
state where it can accept commands. The OSS documentation recommends
closing and re-opening the device after calling reset().
[audio device]{post}{}
Tell the driver that there is likely to be a pause in the output, making
it possible for the device to handle the pause more intelligently. You
might use this after playing a spot sound effect, before waiting for
user input, or before doing disk I/O.
The following convenience methods combine several ioctls, or one ioctl
and some simple calculations.
[audio device]{setparameters}
{format, nchannels, samplerate , strict=False}
Set the key audio sampling parameters---sample format, number of
channels, and sampling rate---in one method call. format, nchannels, and samplerate should be as specified in the
setfmt(), channels(), and speed() methods. If strict is true, setparameters() checks to
see if each parameter was actually set to the requested value, and
raises OSSAudioError if not. Returns a tuple (format,
nchannels, samplerate) indicating the parameter values that
were actually set by the device driver (i.e., the same as the return
valus of setfmt(), channels(), and speed()).
For example,
(fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
is equivalent to
fmt = dsp.setfmt(fmt)
channels = dsp.channels(channels)
rate = dsp.rate(channels)
[audio device]{bufsize}{}
Returns the size of the hardware buffer, in samples.
[audio device]{obufcount}{}
Returns the number of samples that are in the hardware buffer yet to be
played.
[audio device]{obuffree}{}
Returns the number of samples that could be queued into the hardware
buffer to be played without blocking.
</description>
</group>
<group name="Mixer Device Objects">
</group>
</group>
</group>
<group name="Cryptographic Services">
<group name="hmac --- Keyed-Hashing for Message Authentication">
<description>Keyed-Hashing for Message Authentication (HMAC)
implementation for Python.
New in version 2.2
This module implements the HMAC algorithm as described by 2104.
</description>
<element kind="function" name="new">
<description>Return a new hmac object. If msg is present, the method call
update(msg) is made. digestmod is the digest
module for the HMAC object to use. It defaults to the
md5 module.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="msg"/><property kind="parameter" name="digestmod"/></properties></element>

<element kind="function" name="update">
<description>Update the hmac object with the string msg. Repeated calls
are equivalent to a single call with the concatenation of all the
arguments: m.update(a); m.update(b) is equivalent to
m.update(a + b).</description>

<properties><property kind="parameter" name="msgmsg" required="1"/></properties></element>

<element kind="function" name="digest">
<description>Return the digest of the strings passed to the update()
method so far. This is a 16-byte string (for md5) or a
20-byte string (for sha) which may contain non-ASCII
characters, including NUL bytes.</description>

</element>

<element kind="function" name="hexdigest">
<description>Like digest() except the digest is returned as a string of
length 32 for md5 (40 for sha), containing
only hexadecimal digits. This may be used to exchange the value
safely in email or other non-binary environments.</description>

</element>

<element kind="function" name="copy">
<description>Return a copy (``clone'') of the hmac object. This can be used to
efficiently compute the digests of strings that share a common
initial substring.</description>

</element>

</group>
<group name="md5 --- MD5 message digest algorithm">
<description>RSA's MD5 message digest algorithm.
This module implements the interface to RSA's MD5 message digest
</description>
<element kind="function" name="new">
<description>Return a new md5 object. If arg is present, the method call
update(arg) is made.</description>

<properties><property kind="parameter" name="arg" required="1"/></properties></element>

<element kind="function" name="md5">
<description>For backward compatibility reasons, this is an alternative name for the
new() function.</description>

<properties><property kind="parameter" name="arg" required="1"/></properties></element>

</group>
<group name="sha --- SHA-1 message digest algorithm">
<description>NIST's secure hash algorithm, SHA.
This module implements the interface to NIST's</description>
<element kind="function" name="new">
<description>Return a new sha object. If string is present, the method
call update(string) is made.</description>

<properties><property kind="parameter" name="string" required="1"/></properties></element>

<element kind="function" name="update">
<description>Update the sha object with the string arg. Repeated calls are
equivalent to a single call with the concatenation of all the
arguments: m.update(a); m.update(b) is equivalent to
m.update(a+b).</description>

<properties><property kind="parameter" name="argarg" required="1"/></properties></element>

<element kind="function" name="digest">
<description>Return the digest of the strings passed to the update()
method so far. This is a 20-byte string which may contain
non-ASCII characters, including null bytes.</description>

</element>

<element kind="function" name="hexdigest">
<description>Like digest() except the digest is returned as a string of
length 40, containing only hexadecimal digits. This may be used to exchange the value safely in email or other non-binary
environments.</description>

</element>

<element kind="function" name="copy">
<description>Return a copy (``clone'') of the sha object. This can be used to
efficiently compute the digests of strings that share a common initial
substring.</description>

</element>

</group>
<group name="mpz --- GNU arbitrary magnitude integers">
<description>Interface to the GNU MP library for arbitrary
precision arithmetic.
2.2{See the references at the end of this section for
information about packages which provide similar
functionality. This module will be removed in Python
2.3.}
This is an optional module. It is only available when Python is
configured to include it, which requires that the GNU MP software is
installed.
</description>
<element kind="function" name="mpz">
<description>Create a new mpz-number. value can be an integer, a long,
another mpz-number, or even a string. If it is a string, it is
interpreted as an array of radix-256 digits, least significant digit
first, resulting in a positive number. See also the binary()
method, described below.</description>

<properties><property kind="parameter" name="valuevalue" required="1"/></properties></element>

<element kind="function" name="powm">
<description>Return pow(base, exponent) % modulus. If
exponent == 0, return mpz(1). In contrast to the
library function, this version can handle negative exponents.</description>

<properties><property kind="parameter" name="base" required="1"/><property kind="parameter" name="exponent" required="1"/><property kind="parameter" name="modulus modulus" required="1"/></properties></element>

<element kind="function" name="gcd">
<description>Return the greatest common divisor of op1 and op2.</description>

<properties><property kind="parameter" name="op1" required="1"/><property kind="parameter" name="op2 op2" required="1"/></properties></element>

<element kind="function" name="gcdext">
<description>Return a tuple (g, s, t), such that
a*s + b*t == g == gcd(a, b).</description>

<properties><property kind="parameter" name="a" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="sqrt">
<description>Return the square root of op. The result is rounded towards zero.</description>

<properties><property kind="parameter" name="opop" required="1"/></properties></element>

<element kind="function" name="sqrtrem">
<description>Return a tuple (root, remainder), such that
root*root + remainder == op.</description>

<properties><property kind="parameter" name="opop" required="1"/></properties></element>

<element kind="function" name="divm">
<description>Returns a number q such that
q * denominator % modulus ==
numerator. One could also implement this function in Python,
using gcdext().</description>

<properties><property kind="parameter" name="numerator" required="1"/><property kind="parameter" name="denominator" required="1"/><property kind="parameter" name="modulus modulus" required="1"/></properties></element>

<element kind="function" name="binary">
<description>Convert this mpz-number to a binary string, where the number has been
stored as an array of radix-256 digits, least significant digit first.
The mpz-number must have a value greater than or equal to zero,
otherwise ValueError will be raised.</description>

</element>

</group>
<group name="rotor --- Enigma-like encryption and decryption">
<description>Enigma-like encryption and decryption.
2.3{The encryption algorithm is insecure.}
This module implements a rotor-based encryption algorithm, contributed by
Lance Ellinghouse</description>
<element kind="function" name="newrotor">
<description>Return a rotor object. key is a string containing the encryption key
for the object; it can contain arbitrary binary data but not null bytes.
The key will be used
to randomly generate the rotor permutations and their initial positions.
numrotors is the number of rotor permutations in the returned object;
if it is omitted, a default value of 6 will be used.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="numrotors"/></properties></element>

<element kind="function" name="setkey">
<description>Sets the rotor's key to key. The key should not contain null bytes.</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="encrypt">
<description>Reset the rotor object to its initial state and encrypt plaintext,
returning a string containing the ciphertext. The ciphertext is always the
same length as the original plaintext.</description>

<properties><property kind="parameter" name="plaintextplaintext" required="1"/></properties></element>

<element kind="function" name="encryptmore">
<description>Encrypt plaintext without resetting the rotor object, and return a
string containing the ciphertext.</description>

<properties><property kind="parameter" name="plaintextplaintext" required="1"/></properties></element>

<element kind="function" name="decrypt">
<description>Reset the rotor object to its initial state and decrypt ciphertext,
returning a string containing the plaintext. The plaintext string will
always be the same length as the ciphertext.</description>

<properties><property kind="parameter" name="ciphertextciphertext" required="1"/></properties></element>

<element kind="function" name="decryptmore">
<description>Decrypt ciphertext without resetting the rotor object, and return a
string containing the plaintext.</description>

<properties><property kind="parameter" name="ciphertextciphertext" required="1"/></properties></element>

</group>
</group>
<group name="Graphical User Interfaces with Tk">
<group name="Tkinter --- Python interface to Tcl/Tk">
<description>Interface to Tcl/Tk for graphical user interfaces
The Tkinter module (``Tk interface'') is the standard Python
interface to the Tk GUI toolkit. Both Tk and Tkinter are
available on most platforms, as well as on Windows and
Macintosh systems. (Tk itself is not part of Python; it is maintained
at ActiveState.)
[http://www.python.org/topics/tkinter/]
{Python Tkinter Resources}
{The Python Tkinter Topic Guide provides a great
deal of information on using Tk from Python and links to
other sources of information on Tk.}
[http://www.pythonware.com/library/an-introduction-to-tkinter.htm]
{An Introduction to Tkinter}
{Fredrik Lundh's on-line reference material.}
[http://www.nmt.edu/tcc/help/pubs/lang.html]
{Tkinter reference: a GUI for Python}
{On-line reference material.}
[http://jtkinter.sourceforge.net]
{Tkinter for JPython}
{The Jython interface to Tkinter.}
[http://www.amazon.com/exec/obidos/ASIN/1884777813]
{Python and Tkinter Programming}
{The book by John Grayson (ISBN 1-884777-81-3).}
</description>
<group name="Tkinter Modules">
<description>Most of the time, the Tkinter module is all you really
need, but a number of additional modules are available as well. The
Tk interface is located in a binary module named _tkinter.
This module contains the low-level interface to Tk, and should never
be used directly by application programmers. It is usually a shared
library (or DLL), but might in some cases be statically linked with
the Python interpreter.
In addition to the Tk interface module, Tkinter includes a
number of Python modules. The two most important modules are the
Tkinter module itself, and a module called
Tkconstants. The former automatically imports the latter, so
to use Tkinter, all you need to do is to import one module:
import Tkinter
Or, more often:
from Tkinter import *
</description>
<element kind="function" name="Tk">
<description>The Tk class is instantiated without arguments.
This creates a toplevel widget of Tk which usually is the main window
of an appliation. Each instance has its own associated Tcl interpreter.
% FIXME: The following keyword arguments are currently recognized:</description>

<properties><property default="None" kind="parameter" name="screenName" required="1"/><property default="None" kind="parameter" name="baseName" required="1"/><property default="'Tk' className='Tk'" kind="parameter" name="className" required="1"/></properties></element>

</group>
<group name="Tkinter Life Preserver">
<description>% Converted to LaTeX by Mike Clarkson.
This section is not designed to be an exhaustive tutorial on either
Tk or Tkinter. Rather, it is intended as a stop gap, providing some
introductory orientation on the system.
Credits:
Tkinter was written by Steen Lumholt and Guido van Rossum.
Tk was written by John Ousterhout while at Berkeley.
This Life Preserver was written by Matt Conway at
the University of Virginia.
The html rendering, and some liberal editing, was
produced from a FrameMaker version by Ken Manheimer.
Fredrik Lundh elaborated and revised the class interface descriptions,
to get them current with Tk 4.2.
Mike Clarkson converted the documentation to , and compiled the User Interface chapter of the reference manual.
How To Use This Section
This section is designed in two parts: the first half (roughly) covers
background material, while the second half can be taken to the
keyboard as a handy reference.
When trying to answer questions of the form ``how do I do blah'', it
is often best to find out how to do``blah'' in straight Tk, and then
convert this back into the corresponding Tkinter call.
Python programmers can often guess at the correct Python command by
looking at the Tk documentation. This means that in order to use
Tkinter, you will have to know a little bit about Tk. This document
can't fulfill that role, so the best we can do is point you to the
best documentation that exists. Here are some hints:
The authors strongly suggest getting a copy of the Tk man
pages. Specifically, the man pages in the mann directory are most
useful. The man3 man pages describe the C interface to the Tk
library and thus are not especially helpful for script writers. Addison-Wesley publishes a book called Tcl and the
Tk Toolkit by John Ousterhout (ISBN 0-201-63337-X) which is a good
introduction to Tcl and Tk for the novice. The book is not
exhaustive, and for many details it defers to the man pages. Tkinter.py is a last resort for most, but can be a good
place to go when nothing else makes sense. [http://tcl.activestate.com/]
{ActiveState Tcl Home Page}
{The Tk/Tcl development is largely taking place at
ActiveState.}
[http://www.amazon.com/exec/obidos/ASIN/020163337X]
{Tcl and the Tk Toolkit}
{The book by John Ousterhout, the inventor of Tcl .}
[http://www.amazon.com/exec/obidos/ASIN/0130220280]
{Practical Programming in Tcl and Tk}
{Brent Welch's encyclopedic book.}
A Simple Hello World Program % HelloWorld.html
%begin{latexonly}
%[hbtp]
%file=HelloWorld.gif,width=.9
%.5cm
%HelloWorld gadget image
%
%See also the hello-world notes{classes/HelloWorld-notes.html} and
%summary{classes/HelloWorld-summary.html}.
%end{latexonly}
from Tkinter import *
class Application(Frame):
def say_hi(self):
print &quot;hi there, everyone!&quot;
def createWidgets(self):
self.QUIT = Button(self)
self.QUIT[&quot;text&quot;] = &quot;QUIT&quot;
self.QUIT[&quot;fg&quot;] = &quot;red&quot;
self.QUIT[&quot;command&quot;] = self.quit
self.QUIT.pack({&quot;side&quot;: &quot;left&quot;})
self.hi_there = Button(self)
self.hi_there[&quot;text&quot;] = &quot;Hello&quot;,
self.hi_there[&quot;command&quot;] = self.say_hi
self.hi_there.pack({&quot;side&quot;: &quot;left&quot;})
def __init__(self, master=None):
Frame.__init__(self, master)
self.pack()
self.createWidgets()
app = Application()
app.mainloop()
</description>
</group>
<group name="A (Very) Quick Look at Tcl/Tk">
<description>% BriefTclTk.html
The class hierarchy looks complicated, but in actual practice,
application programmers almost always refer to the classes at the very
bottom of the hierarchy. Notes:
These classes are provided for the purposes of
organizing certain functions under one namespace. They aren't meant to
be instantiated independently.
The Tk class is meant to be instantiated only once in
an application. Application programmers need not instantiate one
explicitly, the system creates one whenever any of the other classes
are instantiated.
The Widget class is not meant to be instantiated, it
is meant only for subclassing to make ``real'' widgets (in Cpp, this
is called an `abstract class').
To make use of this reference material, there will be times when you
will need to know how to read short passages of Tk and how to identify
the various parts of a Tk command. (See section~tkinter-basic-mapping for the
Tkinter equivalents of what's below.)
Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are
just lists of tokens separated by spaces. A Tk widget is just its
class, the options that help configure it, and the
actions that make it do useful things. To make a widget in Tk, the command is always of the form: classCommand newPathname options
[classCommand]
denotes which kind of widget to make (a button, a label, a menu...)
[newPathname]
is the new name for this widget. All names in Tk must be unique. To
help enforce this, widgets in Tk are named with pathnames, just
like files in a file system. The top level widget, the root,
is called . (period) and children are delimited by more
periods. For example, .myApp.controlPanel.okButton might be
the name of a widget.
[options ]
configure the widget's appearance and in some cases, its
behavior. The options come in the form of a list of flags and values.
Flags are proceeded by a `-', like unix shell command flags, and
values are put in quotes if they are more than one word.
For example: button .fred -fg red -text &quot;hi there&quot;
^ ^ new options
command widget (-opt val -opt val ...)
Once created, the pathname to the widget becomes a new command. This
new widget command is the programmer's handle for getting the new
widget to perform some action. In C, you'd express this as
someAction(fred, someOptions), in Cpp, you would express this as
fred.someAction(someOptions), and in Tk, you say: .fred someAction someOptions Note that the object name, .fred, starts with a dot.
As you'd expect, the legal values for someAction will depend on
the widget's class: .fred disable works if fred is a
button (fred gets greyed out), but does not work if fred is a label
(disabling of labels is not supported in Tk). The legal values of someOptions is action dependent. Some
actions, like disable, require no arguments, others, like
a text-entry box's delete command, would need arguments
to specify what range of text to delete. </description>
</group>
<group name="Mapping Basic Tk into Tkinter">
<description>Class commands in Tk correspond to class constructors in Tkinter.
button .fred =====&gt; fred = Button()
The master of an object is implicit in the new name given to it at
creation time. In Tkinter, masters are specified explicitly.
button .panel.fred =====&gt; fred = Button(panel)
The configuration options in Tk are given in lists of hyphened tags
followed by values. In Tkinter, options are specified as
keyword-arguments in the instance constructor, and keyword-args for
configure calls or as instance indices, in dictionary style, for
established instances. See section~tkinter-setting-options on
setting options.
button .fred -fg red =====&gt; fred = Button(panel, fg = &quot;red&quot;)
.fred configure -fg red =====&gt; fred[&quot;fg&quot;] = red
OR ==&gt; fred.config(fg = &quot;red&quot;)
In Tk, to perform an action on a widget, use the widget name as a
command, and follow it with an action name, possibly with arguments
(options). In Tkinter, you call methods on the class instance to
invoke actions on the widget. The actions (methods) that a given
widget can perform are listed in the Tkinter.py module.
.fred invoke =====&gt; fred.invoke()
To give a widget to the packer (geometry manager), you call pack with
optional arguments. In Tkinter, the Pack class holds all this
functionality, and the various forms of the pack command are
implemented as methods. All widgets in Tkinter are
subclassed from the Packer, and so inherit all the packing
methods. See the Tix module documentation for additional
information on the Form geometry manager.
pack .fred -side left =====&gt; fred.pack(side = &quot;left&quot;)
</description>
</group>
<group name="How Tk and Tkinter are Related">
<description>% Relationship.html
This was derived from a graphical image; the image will be used
more directly in a subsequent version of this document.
From the top down:
[Your App Here (Python)]
A Python application makes a Tkinter call.
[Tkinter (Python Module)]
This call (say, for example, creating a button widget), is
implemented in the Tkinter module, which is written in
Python. This Python function will parse the commands and the
arguments and convert them into a form that makes them look as if they
had come from a Tk script instead of a Python script.
[tkinter (C)]
These commands and their arguments will be passed to a C function
in the tkinter - note the lowercase - extension module.
[Tk Widgets (C and Tcl)]
This C function is able to make calls into other C modules,
including the C functions that make up the Tk library. Tk is
implemented in C and some Tcl. The Tcl part of the Tk widgets is used
to bind certain default behaviors to widgets, and is executed once at
the point where the Python Tkinter module is
imported. (The user never sees this stage).
[Tk (C)]
The Tk part of the Tk Widgets implement the final mapping to ...
[Xlib (C)]
the Xlib library to draw graphics on the screen.
</description>
</group>
<group name="Handy Reference">
<description>Setting Options
Options control things like the color and border width of a widget.
Options can be set in three ways:
[At object creation time, using keyword arguments]:
fred = Button(self, fg = &quot;red&quot;, bg = &quot;blue&quot;)
[After object creation, treating the option name like a dictionary index]:
fred[&quot;fg&quot;] = &quot;red&quot;
fred[&quot;bg&quot;] = &quot;blue&quot;
[Use the config() method to update multiple attrs subesequent to
object creation]:
fred.config(fg = &quot;red&quot;, bg = &quot;blue&quot;)
For a complete explanation of a given option and its behavior, see the
Tk man pages for the widget in question.
Note that the man pages list &quot;STANDARD OPTIONS&quot; and &quot;WIDGET SPECIFIC
OPTIONS&quot; for each widget. The former is a list of options that are
common to many widgets, the latter are the options that are
ideosyncratic to that particular widget. The Standard Options are
documented on the options{3} man page.
No distinction between standard and widget-specific options is made in
this document. Some options don't apply to some kinds of widgets.
Whether a given widget responds to a particular option depends on the
class of the widget; buttons have a command option, labels do not. The options supported by a given widget are listed in that widget's
man page, or can be queried at runtime by calling the
config() method without arguments, or by calling the
keys() method on that widget. The return value of these
calls is a dictionary whose key is the name of the option as a string
(for example, 'relief') and whose values are 5-tuples.
Some options, like bg are synonyms for common options with long
names (bg is shorthand for &quot;background&quot;). Passing the
config() method the name of a shorthand option will return a
2-tuple, not 5-tuple. The 2-tuple passed back will contain the name of
the synonym and the ``real'' option (such as ('bg',
'background')).
{c|l|l}{textrm}{Index}{Meaning}{Example}
0{option name} {'relief'}
1{option name for database lookup} {'relief'}
2{option class for database lookup} {'Relief'}
3{default value} {'raised'}
4{current value} {'groove'}
Example:
&gt;&gt;&gt; print fred.config()
{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}
Of course, the dictionary printed will include all the options
available and their values. This is meant only as an example.
The Packer % Packer.html
</description>
</group>
<group name="Using Tix">
<element kind="function" name="Tix">
<description>Toplevel widget of Tix which represents mostly the main window
of an application. It has an associated Tcl interpreter.
Classes in the Tix module subclasses the classes in the
Tkinter module. The former imports the latter, so to use
Tix with Tkinter, all you need to do is to import one
module. In general, you can just import Tix, and replace
the toplevel call to Tkinter.Tk with Tix.Tk:
import Tix
from Tkconstants import *
root = Tix.Tk()
</description>

<properties><property kind="parameter" name="screenName" required="1"/><property kind="parameter" name="baseName"/><property kind="parameter" name="className"/></properties></element>

</group>
<group name="Tix Widgets">
<description>Tix
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm}
introduces over 40 widget classes to the Tkinter repertoire. There is a demo of all the Tix widgets in the
Demo/tix directory of the standard distribution.
% The Python sample code is still being added to Python, hence commented out
Basic Widgets
</description>
<element kind="function" name="Balloon">
<description>A Balloon
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm}
that pops up over a widget to provide help. When the user moves the
cursor inside a widget to which a Balloon widget has been bound, a
small pop-up window with a descriptive message will be shown on the
screen.</description>

</element>

<element kind="function" name="ButtonBox">
<description>The ButtonBox
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm}
widget creates a box of buttons, such as is commonly used for Ok
Cancel.</description>

</element>

<element kind="function" name="ComboBox">
<description>The ComboBox
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm}
widget is similar to the combo box control in MS Windows. The user can
select a choice by either typing in the entry subwdget or selecting
from the listbox subwidget.</description>

</element>

<element kind="function" name="Control">
<description>The Control
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm}
widget is also known as the SpinBox widget. The user can
adjust the value by pressing the two arrow buttons or by entering the
value directly into the entry. The new value will be checked against
the user-defined upper and lower limits.</description>

</element>

<element kind="function" name="LabelEntry">
<description>The LabelEntry
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm}
widget packages an entry widget and a label into one mega widget. It
can be used be used to simplify the creation of ``entry-form'' type of
interface.</description>

</element>

<element kind="function" name="LabelFrame">
<description>The LabelFrame
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm}
widget packages a frame widget and a label into one mega widget. To
create widgets inside a LabelFrame widget, one creates the new widgets
relative to the frame subwidget and manage them inside the
frame subwidget.</description>

</element>

<element kind="function" name="Meter">
<description>The Meter
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm}
widget can be used to show the progress of a background job which may
take a long time to execute.</description>

</element>

<element kind="function" name="OptionMenu">
<description>The OptionMenu
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm}
creates a menu button of options.</description>

</element>

<element kind="function" name="PopupMenu">
<description>The PopupMenu
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm}
widget can be used as a replacement of the tk_popup
command. The advantage of the Tix PopupMenu widget
is it requires less application code to manipulate.</description>

</element>

<element kind="function" name="Select">
<description>The Select
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm}
widget is a container of button subwidgets. It can be used to provide
radio-box or check-box style of selection options for the user.</description>

</element>

<element kind="function" name="StdButtonBox">
<description>The StdButtonBox
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm}
widget is a group of standard buttons for Motif-like dialog boxes.</description>

</element>

<element kind="function" name="DirList">
<description>The DirList
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm} widget
displays a list view of a directory, its previous directories and its
sub-directories. The user can choose one of the directories displayed
in the list or change to another directory.</description>

</element>

<element kind="function" name="DirTree">
<description>The DirTree
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm}
widget displays a tree view of a directory, its previous directories
and its sub-directories. The user can choose one of the directories
displayed in the list or change to another directory.</description>

</element>

<element kind="function" name="DirSelectDialog">
<description>The DirSelectDialog
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm}
widget presents the directories in the file system in a dialog
window. The user can use this dialog window to navigate through the
file system to select the desired directory.</description>

</element>

<element kind="function" name="DirSelectBox">
<description>The DirSelectBox is similar
to the standard Motif(TM) directory-selection box. It is generally used for
the user to choose a directory. DirSelectBox stores the directories mostly
recently selected into a ComboBox widget so that they can be quickly
selected again.</description>

</element>

<element kind="function" name="ExFileSelectBox">
<description>The ExFileSelectBox
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm}
widget is usually embedded in a tixExFileSelectDialog widget. It
provides an convenient method for the user to select files. The style
of the ExFileSelectBox widget is very similar to the standard
file dialog on MS Windows 3.1.</description>

</element>

<element kind="function" name="FileSelectBox">
<description>The FileSelectBox
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm}
is similar to the standard Motif(TM) file-selection box. It is
generally used for the user to choose a file. FileSelectBox stores the
files mostly recently selected into a ComboBox widget so that
they can be quickly selected again.</description>

</element>

<element kind="function" name="FileEntry">
<description>The FileEntry
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm}
widget can be used to input a filename. The user can type in the
filename manually. Alternatively, the user can press the button widget
that sits next to the entry, which will bring up a file selection
dialog.</description>

</element>

<element kind="function" name="HList">
<description>The HList
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm}
widget can be used to display any data that have a hierarchical
structure, for example, file system directory trees. The list entries
are indented and connected by branch lines according to their places
in the hierachy.</description>

</element>

<element kind="function" name="CheckList">
<description>The CheckList
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm}
widget displays a list of items to be selected by the user. CheckList
acts similarly to the Tk checkbutton or radiobutton widgets, except it
is capable of handling many more items than checkbuttons or
radiobuttons.</description>

</element>

<element kind="function" name="Tree">
<description>The Tree
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm}
widget can be used to display hierachical data in a tree form. The
user can adjust the view of the tree by opening or closing parts of
the tree.</description>

</element>

<element kind="function" name="TList">
<description>The TList
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm}
widget can be used to display data in a tabular format. The list
entries of a TList widget are similar to the entries in the Tk
listbox widget. The main differences are (1) the TList widget
can display the list entries in a two dimensional format and (2) you
can use graphical images as well as multiple colors and fonts for the
list entries.</description>

</element>

<element kind="function" name="PanedWindow">
<description>The PanedWindow
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm}
widget allows the user to interactively manipulate the sizes of
several panes. The panes can be arranged either vertically or
horizontally. The user changes the sizes of the panes by dragging the
resize handle between two panes.</description>

</element>

<element kind="function" name="ListNoteBook">
<description>The ListNoteBook
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm}
widget is very similar to the TixNoteBook widget: it can be
used to display many windows in a limited space using a notebook
metaphor. The notebook is divided into a stack of pages (windows). At
one time only one of these pages can be shown. The user can navigate
through these pages by choosing the name of the desired page in the
hlist subwidget.</description>

</element>

<element kind="function" name="NoteBook">
<description>The NoteBook
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm}
widget can be used to display many windows in a limited space using a
notebook metaphor. The notebook is divided into a stack of pages. At
one time only one of these pages can be shown. The user can navigate
through these pages by choosing the visual ``tabs'' at the top of the
NoteBook widget.</description>

</element>

<element kind="function" name="InputOnly">
<description>The InputOnly
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm}
widgets are to accept inputs from the user, which can be done with the
bind command ( only).</description>

</element>

<element kind="function" name="Form">
<description>The Form
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm}
geometry manager based on attachment rules for all Tk widgets.</description>

</element>

</group>
<group name="Tix Class Structure">
<description>%
%[hbtp]
%file=hierarchy.png,width=.9
%.5cm
%The Class Hierarchy of Tix Widgets
%
%end{latexonly}
</description>
</group>
<group name="Tix Commands">
<element kind="function" name="tixCommand">
<description>The tix commands
{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm}
provide access to miscellaneous elements of Tix's internal
state and the Tix application context. Most of the information
manipulated by these methods pertains to the application as a whole,
or to a screen or display, rather than to a particular window.
To view the current settings, the common usage is:
import Tix
root = Tix.Tk()
print root.tix_configure()
</description>

</element>

<element kind="function" name="tix_configure">
<description>Query or modify the configuration options of the Tix application
context. If no option is specified, returns a dictionary all of the
available options. If option is specified with no value, then the
method returns a list describing the one named option (this list will
be identical to the corresponding sublist of the value returned if no
option is specified). If one or more option-value pairs are
specified, then the method modifies the given option(s) to have the
given value(s); in this case the method returns an empty string.
Option may be any of the configuration options.</description>

<properties><property kind="parameter" name="cnf" required="1"/><property kind="parameter" name="**kw **kw"/></properties></element>

<element kind="function" name="tix_cget">
<description>Returns the current value of the configuration option given by
option. Option may be any of the configuration options.</description>

<properties><property kind="parameter" name="optionoption" required="1"/></properties></element>

<element kind="function" name="tix_getbitmap">
<description>Locates a bitmap file of the name name.xpm or name in
one of the bitmap directories (see the tix_addbitmapdir()
method). By using tix_getbitmap(), you can avoid hard
coding the pathnames of the bitmap files in your application. When
successful, it returns the complete pathname of the bitmap file,
prefixed with the character @. The returned value can be used to
configure the bitmap option of the Tk and Tix widgets.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="tix_addbitmapdir">
<description>Tix maintains a list of directories under which the
tix_getimage() and tix_getbitmap() methods will
search for image files. The standard bitmap directory is
_LIBRARY/bitmaps. The tix_addbitmapdir() method
adds directory into this list. By using this method, the image
files of an applications can also be located using the
tix_getimage() or tix_getbitmap() method.</description>

<properties><property kind="parameter" name="directorydirectory" required="1"/></properties></element>

<element kind="function" name="tix_filedialog">
<description>Returns the file selection dialog that may be shared among different
calls from this application. This method will create a file selection
dialog widget when it is called the first time. This dialog will be
returned by all subsequent calls to tix_filedialog(). An
optional dlgclass parameter can be passed as a string to specified
what type of file selection dialog widget is desired. Possible
options are tix, FileSelectDialog or
tixExFileSelectDialog.</description>

<properties><property kind="parameter" name="dlgclass" required="1"/></properties></element>

<element kind="function" name="tix_getimage">
<description>Locates an image file of the name name.xpm, name.xbm or
name.ppm in one of the bitmap directories (see the
tix_addbitmapdir() method above). If more than one file with
the same name (but different extensions) exist, then the image type is
chosen according to the depth of the X display: xbm images are chosen
on monochrome displays and color images are chosen on color
displays. By using tix_getimage(), you can avoid hard coding
the pathnames of the image files in your application. When successful,
this method returns the name of the newly created image, which can be
used to configure the image option of the Tk and Tix widgets.</description>

<properties><property kind="parameter" name="self" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="tix_option_get">
<description>Gets the options manitained by the Tix scheme mechanism.</description>

<properties><property kind="parameter" name="namename" required="1"/></properties></element>

<element kind="function" name="tix_resetoptions">
<description>Resets the scheme and fontset of the Tix application to
newScheme and newFontSet, respectively. This affects only
those widgets created after this call. Therefore, it is best to call
the resetoptions method before the creation of any widgets in a Tix
application.
The optional parameter newScmPrio can be given to reset the
priority level of the Tk options set by the Tix schemes.
Because of the way Tk handles the X option database, after Tix has
been has imported and inited, it is not possible to reset the color
schemes and font sets using the tix_config() method.
Instead, the tix_resetoptions() method must be used.</description>

<properties><property kind="parameter" name="newScheme" required="1"/><property kind="parameter" name="newFontSet" required="1"/><property kind="parameter" name="newScmPrio"/></properties></element>

</group>
<group name="Menus">
<description>File menu
[New window] create a new editing window
[Open...] open an existing file
[Open module...] open an existing module (searches sys.path)
[Class browser] show classes and methods in current file
[Path browser] show sys.path directories, modules, classes and methods
</description>
</group>
<group name="Basic editing and navigation">
<description>Backspace deletes to the left; Del deletes to the right
Arrow keys and Page Up/Page Down to move around
Home/End go to begin/end of line
C-Home/C-End go to begin/end of file
Some Emacs bindings may also work, including C-B,
C-P, C-A, C-E, C-D, C-L
Automatic indentation
After a block-opening statement, the next line is indented by 4 spaces
(in the Python Shell window by one tab). After certain keywords
(break, return etc.) the next line is dedented. In leading
indentation, Backspace deletes up to 4 spaces if they are there.
Tab inserts 1-4 spaces (in the Python Shell window one tab).
See also the indent/dedent region commands in the edit menu.
Python Shell window
C-C interrupts executing command
C-D sends end-of-file; closes window if typed at
a &gt;&gt;&gt;~ prompt
Alt-p retrieves previous command matching what you have typed
Alt-n retrieves next
Return while on any previous command retrieves that command
Alt-/ (Expand word) is also useful here
</description>
</group>
<group name="Syntax colors">
</group>
</group>
</group>
<group name="Restricted Execution">
<group name="rexec --- Restricted execution framework">
<description>Basic restricted execution framework.
Changed in version 2.3: Disabled module
[warning]
The documentation has been left in place to help in reading old code
that uses the module.
This module contains the RExec class, which supports
r_eval(), r_execfile(), r_exec(), and
r_import() methods, which are restricted versions of the standard
Python functions eval(), execfile() and
the exec and import statements.
Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you
can subclass RExec to add or remove capabilities as desired.
[warning]
While the rexec module is designed to perform as described
below, it does have a few known vulnerabilities which could be
exploited by carefully written code. Thus it should not be relied
upon in situations requiring ``production ready'' security. In such
situations, execution via sub-processes or very careful
``cleansing'' of both code and data to be processed may be
necessary. Alternatively, help in patching known rexec
vulnerabilities would be welcomed.
The RExec class can prevent code from performing unsafe
operations like reading or writing disk files, or using TCP/IP
sockets. However, it does not protect against code using extremely
large amounts of memory or processor time.
</description>
<element kind="function" name="RExec">
<description>Returns an instance of the RExec class. hooks is an instance of the RHooks class or a subclass of it.
If it is omitted or None, the default RHooks class is
instantiated.
Whenever the rexec module searches for a module (even a
built-in one) or reads a module's code, it doesn't actually go out to
the file system itself. Rather, it calls methods of an RHooks
instance that was passed to or created by its constructor. (Actually,
the RExec object doesn't make these calls --- they are made by
a module loader object that's part of the RExec object. This
allows another level of flexibility, which can be useful when changing
the mechanics of import within the restricted environment.)
By providing an alternate RHooks object, we can control the
file system accesses made to import a module, without changing the
actual algorithm that controls the order in which those accesses are
made. For instance, we could substitute an RHooks object that
passes all filesystem requests to a file server elsewhere, via some
RPC mechanism such as ILU. Grail's applet loader uses this to support
importing applets from a URL for a directory.
If verbose is true, additional debugging output may be sent to
standard output.</description>

<properties><property kind="parameter" name="hooks" required="1"/><property kind="parameter" name="verbose"/></properties></element>

<group name="RExec Objects">
<description>RExec instances support the following methods:
</description>
<element kind="function" name="r_eval">
<description>code must either be a string containing a Python expression, or
a compiled code object, which will be evaluated in the restricted
environment's __main__ module. The value of the expression or
code object will be returned.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="r_exec">
<description>code must either be a string containing one or more lines of
Python code, or a compiled code object, which will be executed in the
restricted environment's __main__ module.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="r_execfile">
<description>Execute the Python code contained in the file filename in the
restricted environment's __main__ module.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

<element kind="function" name="s_eval">
<description>code must be a string containing a Python expression, which will
be evaluated in the restricted environment.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="s_exec">
<description>code must be a string containing one or more lines of Python code,
which will be executed in the restricted environment.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="s_execfile">
<description>Execute the Python code contained in the file filename in the
restricted environment.</description>

<properties><property kind="parameter" name="codecode" required="1"/></properties></element>

<element kind="function" name="r_import">
<description>Import the module modulename, raising an ImportError
exception if the module is considered unsafe.</description>

<properties><property kind="parameter" name="modulename" required="1"/><property kind="parameter" name="globals"/><property kind="parameter" name="locals"/><property kind="parameter" name="fromlist"/></properties></element>

<element kind="function" name="r_open">
<description>Method called when open() is called in the restricted
environment. The arguments are identical to those of open(),
and a file object (or a class instance compatible with file objects)
should be returned. RExec's default behaviour is allow opening
any file for reading, but forbidding any attempt to write a file. See
the example below for an implementation of a less restrictive
r_open().</description>

<properties><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode"/><property kind="parameter" name="bufsize"/></properties></element>

<element kind="function" name="r_reload">
<description>Reload the module object module, re-parsing and re-initializing it.</description>

<properties><property kind="parameter" name="modulemodule" required="1"/></properties></element>

<element kind="function" name="r_unload">
<description>Unload the module object module (remove it from the
restricted environment's sys.modules dictionary).</description>

<properties><property kind="parameter" name="modulemodule" required="1"/></properties></element>

<element kind="function" name="s_import">
<description>Import the module modulename, raising an ImportError
exception if the module is considered unsafe.</description>

<properties><property kind="parameter" name="modulename" required="1"/><property kind="parameter" name="globals"/><property kind="parameter" name="locals"/><property kind="parameter" name="fromlist"/></properties></element>

<element kind="function" name="s_reload">
<description>Reload the module object module, re-parsing and re-initializing it.</description>

<properties><property kind="parameter" name="modulemodule" required="1"/></properties></element>

<element kind="function" name="s_unload">
<description>Unload the module object module. % XXX what are the semantics of this?</description>

<properties><property kind="parameter" name="modulemodule" required="1"/></properties></element>

</group>
<group name="Defining restricted environments">
<description>The RExec class has the following class attributes, which are
used by the __init__() method. Changing them on an existing
instance won't have any effect; instead, create a subclass of
RExec and assign them new values in the class definition.
Instances of the new class will then use those new values. All these
attributes are tuples of strings.
{nok_builtin_names}
Contains the names of built-in functions which will not be
available to programs running in the restricted environment. The
value for RExec is ('open', 'reload', '__import__').
(This gives the exceptions, because by far the majority of built-in
functions are harmless. A subclass that wants to override this
variable should probably start with the value from the base class and
concatenate additional forbidden functions --- when new dangerous
built-in functions are added to Python, they will also be added to
this module.)
{ok_builtin_modules}
Contains the names of built-in modules which can be safely imported.
The value for RExec is ('audioop', 'array', 'binascii',
'cmath', 'errno', 'imageop', 'marshal', 'math', 'md5', 'operator',
'parser', 'regex', 'rotor', 'select', 'sha', '_sre', 'strop',
'struct', 'time'). A similar remark about overriding this variable
applies --- use the value from the base class as a starting point.
{ok_path}
Contains the directories which will be searched when an import
is performed in the restricted environment. The value for RExec is the same as sys.path (at the time
the module is loaded) for unrestricted code.
{ok_posix_names}
% Should this be called ok_os_names?
Contains the names of the functions in the os module which will be
available to programs running in the restricted environment. The
value for RExec is ('error', 'fstat', 'listdir',
'lstat', 'readlink', 'stat', 'times', 'uname', 'getpid', 'getppid',
'getcwd', 'getuid', 'getgid', 'geteuid', 'getegid').
{ok_sys_names}
Contains the names of the functions and variables in the sys
module which will be available to programs running in the restricted
environment. The value for RExec is ('ps1', 'ps2',
'copyright', 'version', 'platform', 'exit', 'maxint').
{ok_file_types}
Contains the file types from which modules are allowed to be loaded.
Each file type is an integer constant defined in the imp module.
The meaningful values are PY_SOURCE, PY_COMPILED, and
C_EXTENSION. The value for RExec is (C_EXTENSION,
PY_SOURCE). Adding PY_COMPILED in subclasses is not recommended;
an attacker could exit the restricted execution mode by putting a forged
byte-compiled file (.pyc) anywhere in your file system, for example
by writing it to /tmp or uploading it to the /incoming
directory of your public FTP server.
</description>
</group>
<group name="An example">
</group>
</group>
<group name="Bastion --- Restricting access to objects">
<description>Providing restricted access to objects.
Changed in version 2.3: Disabled module
[warning]
The documentation has been left in place to help in reading old code
that uses the module.
% I'm concerned that the word 'bastion' won't be understood by people
% for whom English is a second language, making the module name
% somewhat mysterious. Thus, the brief definition... --amk
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.
% I've punted on the issue of documenting keyword arguments for now.
</description>
<element kind="function" name="Bastion">
<description>Protect the object object, returning a bastion for the
object. Any attempt to access one of the object's attributes will
have to be approved by the filter function; if the access is
denied an AttributeError exception will be raised.
If present, filter must be a function that accepts a string
containing an attribute name, and returns true if access to that
attribute will be permitted; if filter returns false, the access
is denied. The default filter denies access to any function beginning
with an underscore (_). The bastion's string representation
will be &lt;Bastion for name&gt; if a value for
name is provided; otherwise, repr(object) will be
used.
class, if present, should be a subclass of BastionClass; see the code in bastion.py for the details. Overriding the
default BastionClass will rarely be required.</description>

<properties><property kind="parameter" name="object" required="1"/><property kind="parameter" name="filter"/><property kind="parameter" name="name"/><property kind="parameter" name="class"/></properties></element>

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

<properties><property kind="parameter" name="getfunc" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

</group>
</group>
<group name="Python Language Services">
<group name="parser --- Access Python parse trees">
<description>% Copyright 1995 Virginia Polytechnic Institute and State University
% and Fred L. Drake, Jr. This copyright notice must be distributed on
% all copies, but this document otherwise may be distributed as part
% of the Python distribution. No fee may be charged for this document
% in any representation, either on paper or electronically. This
% restriction does not affect other elements in a distributed package
% in any way.
Access parse trees for Python source code.
</description>
<group name="Creating AST Objects">
<description>AST objects may be created from source code or from a parse tree.
When creating an AST object from source, different functions are used
to create the 'eval' and 'exec' forms.
</description>
<element kind="function" name="expr">
<description>The expr() function parses the parameter source
as if it were an input to compile(source, 'file.py',
'eval'). If the parse succeeds, an AST object is created to hold the
internal parse tree representation, otherwise an appropriate exception
is thrown.</description>

<properties><property kind="parameter" name="sourcesource" required="1"/></properties></element>

<element kind="function" name="suite">
<description>The suite() function parses the parameter source
as if it were an input to compile(source, 'file.py',
'exec'). If the parse succeeds, an AST object is created to hold the
internal parse tree representation, otherwise an appropriate exception
is thrown.</description>

<properties><property kind="parameter" name="sourcesource" required="1"/></properties></element>

<element kind="function" name="sequence2ast">
<description>This function accepts a parse tree represented as a sequence and
builds an internal representation if possible. If it can validate
that the tree conforms to the Python grammar and all nodes are valid
node types in the host version of Python, an AST object is created
from the internal representation and returned to the called. If there
is a problem creating the internal representation, or if the tree
cannot be validated, a ParserError exception is thrown. An AST
object created this way should not be assumed to compile correctly;
normal exceptions thrown by compilation may still be initiated when
the AST object is passed to compileast(). This may indicate
problems not related to syntax (such as a MemoryError
exception), but may also be due to constructs such as the result of
parsing del f(0), which escapes the Python parser but is
checked by the bytecode compiler.
Sequences representing terminal tokens may be represented as either
two-element lists of the form (1, 'name') or as three-element
lists of the form (1, 'name', 56). If the third element is
present, it is assumed to be a valid line number. The line number
may be specified for any subset of the terminal symbols in the input
tree.</description>

<properties><property kind="parameter" name="sequencesequence" required="1"/></properties></element>

<element kind="function" name="tuple2ast">
<description>This is the same function as sequence2ast(). This entry point
is maintained for backward compatibility.</description>

<properties><property kind="parameter" name="sequencesequence" required="1"/></properties></element>

</group>
<group name="Converting AST Objects">
<description>AST objects, regardless of the input used to create them, may be
converted to parse trees represented as list- or tuple- trees, or may
be compiled into executable code objects. Parse trees may be
extracted with or without line numbering information.
</description>
<element kind="function" name="ast2list">
<description>This function accepts an AST object from the caller in
ast and returns a Python list representing the
equivalent parse tree. The resulting list representation can be used
for inspection or the creation of a new parse tree in list form. This
function does not fail so long as memory is available to build the
list representation. If the parse tree will only be used for
inspection, ast2tuple() should be used instead to reduce memory
consumption and fragmentation. When the list representation is
required, this function is significantly faster than retrieving a
tuple representation and converting that to nested lists.
If line_info is true, line number information will be
included for all terminal tokens as a third element of the list
representing the token. Note that the line number provided specifies
the line on which the token ends. This information is
omitted if the flag is false or omitted.</description>

<properties><property kind="parameter" name="ast" required="1"/><property kind="parameter" name="line_info"/></properties></element>

<element kind="function" name="ast2tuple">
<description>This function accepts an AST object from the caller in
ast and returns a Python tuple representing the
equivalent parse tree. Other than returning a tuple instead of a
list, this function is identical to ast2list().
If line_info is true, line number information will be
included for all terminal tokens as a third element of the list
representing the token. This information is omitted if the flag is
false or omitted.</description>

<properties><property kind="parameter" name="ast" required="1"/><property kind="parameter" name="line_info"/></properties></element>

<element kind="function" name="compileast">
<description>The Python byte compiler can be invoked on an AST object to produce
code objects which can be used as part of an exec statement or
a call to the built-in eval()eval function.
This function provides the interface to the compiler, passing the
internal parse tree from ast to the parser, using the
source file name specified by the filename parameter.
The default value supplied for filename indicates that
the source was an AST object.
Compiling an AST object may result in exceptions related to
compilation; an example would be a SyntaxError caused by the
parse tree for del f(0): this statement is considered legal
within the formal grammar for Python but is not a legal language
construct. The SyntaxError raised for this condition is
actually generated by the Python byte-compiler normally, which is why
it can be raised at this point by the parser module. Most
causes of compilation failure can be diagnosed programmatically by
inspection of the parse tree.</description>

<properties><property kind="parameter" name="ast" required="1"/><property default=" '&lt;ast&gt;'" kind="parameter" name="filename"/></properties></element>

</group>
<group name="Queries on AST Objects">
<description>Two functions are provided which allow an application to determine if
an AST was created as an expression or a suite. Neither of these
functions can be used to determine if an AST was created from source
code via expr() or suite() or from a parse tree
via sequence2ast().
</description>
<element kind="function" name="isexpr">
<description>When ast represents an 'eval' form, this function
returns true, otherwise it returns false. This is useful, since code
objects normally cannot be queried for this information using existing
built-in functions. Note that the code objects created by
compileast() cannot be queried like this either, and are
identical to those created by the built-in
compile()compile function.</description>

<properties><property kind="parameter" name="astast" required="1"/></properties></element>

<element kind="function" name="issuite">
<description>This function mirrors isexpr() in that it reports whether an
AST object represents an 'exec' form, commonly known as a
``suite.'' It is not safe to assume that this function is equivalent
to not isexpr(ast), as additional syntactic fragments may
be supported in the future.</description>

<properties><property kind="parameter" name="astast" required="1"/></properties></element>

</group>
<group name="Exceptions and Error Handling">
<description>The parser module defines a single exception, but may also pass other
built-in exceptions from other portions of the Python runtime
environment. See each function for information about the exceptions
it can raise.
{ParserError}
Exception raised when a failure occurs within the parser module. This
is generally produced for validation failures rather than the built in
SyntaxError thrown during normal parsing.
The exception argument is either a string describing the reason of the
failure or a tuple containing a sequence causing the failure from a parse
tree passed to sequence2ast() and an explanatory string. Calls to
sequence2ast() need to be able to handle either type of exception,
while calls to other functions in the module will only need to be
aware of the simple string values.
Note that the functions compileast(), expr(), and
suite() may throw exceptions which are normally thrown by the
parsing and compilation process. These include the built in
exceptions MemoryError, OverflowError,
SyntaxError, and SystemError. In these cases, these
exceptions carry all the meaning normally associated with them. Refer
to the descriptions of each function for detailed information.
</description>
</group>
<group name="AST Objects">
<description>Ordered and equality comparisons are supported between AST objects.
Pickling of AST objects (using the pickle module) is also
supported.
{ASTType}
The type of the objects returned by expr(),
suite() and sequence2ast().
AST objects have the following methods:
</description>
<element kind="function" name="compile">
<description>Same as compileast(ast, filename).</description>

<properties><property kind="parameter" name="filename" required="1"/></properties></element>

<element kind="function" name="isexpr">
<description>Same as isexpr(ast).</description>

</element>

<element kind="function" name="issuite">
<description>Same as issuite(ast).</description>

</element>

<element kind="function" name="tolist">
<description>Same as ast2list(ast, line_info).</description>

<properties><property kind="parameter" name="line_info" required="1"/></properties></element>

<element kind="function" name="totuple">
<description>Same as ast2tuple(ast, line_info).</description>

<properties><property kind="parameter" name="line_info" required="1"/></properties></element>

</group>
<group name="Examples">
</group>
</group>
<group name="symbol --- Constants used with Python parse trees">
</group>
<group name="token --- Constants used with Python parse trees">
<description>Constants representing terminal nodes of the parse tree.
This module provides constants which represent the numeric values of
leaf nodes of the parse tree (terminal tokens). Refer to the file
Grammar/Grammar in the Python distribution for the definitions
of the names in the context of the language grammar. The specific
numeric values which the names map to may change between Python
versions.
This module also provides one data object and some functions. The
functions mirror definitions in the Python C header files.
{tok_name}
Dictionary mapping the numeric values of the constants defined in this
module back to name strings, allowing more human-readable
representation of parse trees to be generated.
</description>
<element kind="function" name="ISTERMINAL">
<description>Return true for terminal token values.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="ISNONTERMINAL">
<description>Return true for non-terminal token values.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

<element kind="function" name="ISEOF">
<description>Return true if x is the marker indicating the end of input.</description>

<properties><property kind="parameter" name="xx" required="1"/></properties></element>

</group>
<group name="keyword --- Testing for Python keywords">
<description>Test whether a string is a keyword in Python.
This module allows a Python program to determine if a string is a
keyword.
</description>
<element kind="function" name="iskeyword">
<description>Return true if s is a Python keyword.</description>

<properties><property kind="parameter" name="ss" required="1"/></properties></element>

</group>
<group name="tokenize --- Tokenizer for Python source">
<description>Lexical scanner for Python source code.
The tokenize module provides a lexical scanner for Python
source code, implemented in Python. The scanner in this module
returns comments as tokens as well, making it useful for implementing
``pretty-printers,'' including colorizers for on-screen displays.
The primary entry point is a generator:
</description>
<element kind="function" name="generate_tokens">
<description>The generate_tokens() generator requires one argment,
readline, which must be a callable object which
provides the same interface as the readline() method of
built-in file objects (see section~bltin-file-objects). Each
call to the function should return one line of input as a string.
The generator produces 5-tuples with these members:
the token type;
the token string;
a 2-tuple (srow, scol) of ints specifying the
row and column where the token begins in the source;
a 2-tuple (erow, ecol) of ints specifying the
row and column where the token ends in the source;
and the line on which the token was found.
The line passed is the logical line;
continuation lines are included.
New in version 2.2</description>

<properties><property kind="parameter" name="readlinereadline" required="1"/></properties></element>

<element kind="function" name="tokenize">
<description>The tokenize() function accepts two parameters: one
representing the input stream, and one providing an output mechanism
for tokenize().
The first parameter, readline, must be a callable object which
provides the same interface as the readline() method of
built-in file objects (see section~bltin-file-objects). Each
call to the function should return one line of input as a string.
The second parameter, tokeneater, must also be a callable
object. It is called once for each token, with five arguments,
corresponding to the tuples generated by generate_tokens().</description>

<properties><property kind="parameter" name="readline" required="1"/><property kind="parameter" name="tokeneater"/></properties></element>

</group>
<group name="tabnanny --- Detection of ambiguous indentation">
<description>% rudimentary documentation based on module comments, by Peter Funk
% &lt;pf@artcom-gmbh.de&gt;
Tool for detecting white space related problems
in Python source files in a directory tree.
For the time being this module is intended to be called as a script.
However it is possible to import it into an IDE and use the function
check() described below.
The API provided by this module is likely to change in future releases; such changes may not be backward compatible.
</description>
<element kind="function" name="check">
<description>If file_or_dir is a directory and not a symbolic link, then
recursively descend the directory tree named by file_or_dir,
checking all .py files along the way. If file_or_dir
is an ordinary Python source file, it is checked for whitespace
related problems. The diagnostic messages are written to standard
output using the print statement.</description>

<properties><property kind="parameter" name="file_or_dirfile_or_dir" required="1"/></properties></element>

<element kind="function" name="tokeneater">
<description>This function is used by check() as a callback parameter to
the function tokenize.tokenize().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="token" required="1"/><property kind="parameter" name="start" required="1"/><property kind="parameter" name="end" required="1"/><property kind="parameter" name="line line" required="1"/></properties></element>

</group>
<group name="pyclbr --- Python class browser support">
<description>Supports information extraction for a Python class
browser.
The pyclbr can be used to determine some limited information
about the classes, methods and top-level functions
defined in a module. The information
provided is sufficient to implement a traditional three-pane class
browser. The information is extracted from the source code rather
than by importing the module, so this module is safe to use with
untrusted source code. This restriction makes it impossible to use
this module with modules not implemented in Python, including many
standard and optional extension modules.
</description>
<element kind="function" name="readmodule">
<description>% The 'inpackage' parameter appears to be for internal use only....
Read a module and return a dictionary mapping class names to class
descriptor objects. The parameter module should be the name
of a module as a string; it may be the name of a module within a
package. The path parameter should be a sequence, and is used
to augment the value of sys.path, which is used to locate
module source code.</description>

<properties><property kind="parameter" name="module" required="1"/><property kind="parameter" name="path"/></properties></element>

<element kind="function" name="readmodule_ex">
<description>% The 'inpackage' parameter appears to be for internal use only....
Like readmodule(), but the returned dictionary, in addition
to mapping class names to class descriptor objects, also maps
top-level function names to function descriptor objects. Moreover, if
the module being read is a package, the key '__path__' in the
returned dictionary has as its value a list which contains the package
search path.</description>

<properties><property kind="parameter" name="module" required="1"/><property kind="parameter" name="path"/></properties></element>

<group name="Class Descriptor Objects">
<description>The class descriptor objects used as values in the dictionary returned
by readmodule() and readmodule_ex()
provide the following data members:
[class descriptor]{module}
The name of the module defining the class described by the class
descriptor.
[class descriptor]{name}
The name of the class.
[class descriptor]{super}
A list of class descriptors which describe the immediate base
classes of the class being described. Classes which are named as
superclasses but which are not discoverable by
readmodule() are listed as a string with the class name
instead of class descriptors.
[class descriptor]{methods}
A dictionary mapping method names to line numbers.
[class descriptor]{file}
Name of the file containing the class statement defining the class.
[class descriptor]{lineno}
The line number of the class statement within the file named by
file.
</description>
</group>
<group name="Function Descriptor Objects">
</group>
</group>
<group name="py_compile --- Compile Python source files">
<description>% Documentation based on module docstrings, by Fred L. Drake, Jr.
% &lt;fdrake@acm.org&gt;
Compile Python source files to byte-code files.
The py_compile module provides a function to generate a
byte-code file from a source file, and another function used when the
module source file is invoked as a script.
Though not often needed, this function can be useful when installing
modules for shared use, especially if some of the users may not have
permission to write the byte-code cache files in the directory
containing the source code.
{PyCompileError}
Exception raised when an error occurs while attempting to compile the file.
</description>
<element kind="function" name="compile">
<description>Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file name file. The byte-code is written to cfile, which defaults to file
+ 'c' ('o' if optimization is enabled in the
current interpreter). If dfile is specified, it is used as
the name of the source file in error messages instead of file. If doraise = True, a PyCompileError is raised when an error is encountered while compiling file. If doraise = False (the default), an error string is written to sys.stderr, but no exception is raised.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="cfile"/><property kind="parameter" name="dfile"/><property kind="parameter" name="doraise"/></properties></element>

<element kind="function" name="main">
<description>Compile several source files. The files named in args (or on
the command line, if args is not specified) are compiled and
the resulting bytecode is cached in the normal manner. This
function does not search a directory structure to locate source
files; it only compiles files named explicitly.</description>

<properties><property kind="parameter" name="args" required="1"/></properties></element>

</group>
<group name="compileall --- Byte-compile Python libraries">
<description>Tools for byte-compiling all Python source files in a
directory tree.
This module provides some utility functions to support installing
Python libraries. These functions compile Python source files in a
directory tree, allowing users without permission to write to the
libraries to take advantage of cached byte-code files.
The source file for this module may also be used as a script to
compile Python sources in directories named on the command line or in
sys.path.
</description>
<element kind="function" name="compile_dir">
<description>Recursively descend the directory tree named by dir, compiling
all .py files along the way. The maxlevels parameter
is used to limit the depth of the recursion; it defaults to
10. If ddir is given, it is used as the base path from which the filenames used in error messages will be generated. If
force is true, modules are re-compiled even if the timestamps
are up to date. If rx is given, it specifies a regular expression of file
names to exclude from the search; that expression is searched for in
the full path.
If quiet is true, nothing is printed to the standard output
in normal operation.</description>

<properties><property kind="parameter" name="dir" required="1"/><property kind="parameter" name="maxlevels"/><property kind="parameter" name="ddir"/><property kind="parameter" name="force"/><property kind="parameter" name="rx"/><property kind="parameter" name="quiet"/></properties></element>

<element kind="function" name="compile_path">
<description>Byte-compile all the .py files found along sys.path.
If skip_curdir is true (the default), the current directory is
not included in the search. The maxlevels and
force parameters default to 0 and are passed to the
compile_dir() function.</description>

<properties><property kind="parameter" name="skip_curdir" required="1"/><property kind="parameter" name="maxlevels"/><property kind="parameter" name="force"/></properties></element>

</group>
<group name="dis --- Disassembler for Python byte code">
<description>Disassembler for Python byte code.
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():
&gt;&gt;&gt; dis.dis(myfunc)
2 0 LOAD_GLOBAL 0 (len)
3 LOAD_FAST 0 (alist)
6 CALL_FUNCTION 1
9 RETURN_VALUE 10 LOAD_CONST 0 (None)
13 RETURN_VALUE
(The ``2'' is a line number).
The dis module defines the following functions and constants:
</description>
<element kind="function" name="dis">
<description>Disassemble the bytesource object. bytesource can denote
either a module, a class, a method, a function, or a code object. For a module, it disassembles all functions. 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.</description>

<properties><property kind="parameter" name="bytesource" required="1"/></properties></element>

<element kind="function" name="distb">
<description>Disassembles the top-of-stack function of a traceback, using the last
traceback if none was passed. The instruction causing the exception
is indicated.</description>

<properties><property kind="parameter" name="tb" required="1"/></properties></element>

<element kind="function" name="disassemble">
<description>Disassembles a code object, indicating the last instruction if lasti
was provided. The output is divided in the following columns:
the line number, for the first instruction of each line
the current instruction, indicated as --&gt;,
a labelled instruction, indicated with &gt;&gt;,
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.</description>

<properties><property kind="parameter" name="code" required="1"/><property kind="parameter" name="lasti"/></properties></element>

<element kind="function" name="disco">
<description>A synonym for disassemble. It is more convenient to type, and kept
for compatibility with earlier Python releases.</description>

<properties><property kind="parameter" name="code" required="1"/><property kind="parameter" name="lasti"/></properties></element>

<group name="Python Byte Code Instructions">
</group>
</group>
<group name="distutils --- Building and installing Python modules">
</group>
</group>
<group name="Python compiler package">
<group name="The basic interface">
<description>The top-level of the package defines four functions. If you import
compiler, you will get these functions and a collection of
modules contained in the package.
</description>
<element kind="function" name="parse">
<description>Returns an abstract syntax tree for the Python source code in buf.
The function raises SyntaxError if there is an error in the source
code. The return value is a compiler.ast.Module instance that
contains the tree.</description>

<properties><property kind="parameter" name="bufbuf" required="1"/></properties></element>

<element kind="function" name="parseFile">
<description>Return an abstract syntax tree for the Python source code in the file
specified by path. It is equivalent to
parse(open(path).read()).</description>

<properties><property kind="parameter" name="pathpath" required="1"/></properties></element>

<element kind="function" name="walk">
<description>Do a pre-order walk over the abstract syntax tree ast. Call the
appropriate method on the visitor instance for each node
encountered.</description>

<properties><property kind="parameter" name="ast" required="1"/><property kind="parameter" name="visitor" required="1"/><property kind="parameter" name="verbose"/></properties></element>

<element kind="function" name="compile">
<description>Compile the string source, a Python module, statement or
expression, into a code object that can be executed by the exec
statement or eval(). This function is a replacement for the
built-in compile() function.
The filename will be used for run-time error messages.
The mode must be 'exec' to compile a module, 'single' to compile a
single (interactive) statement, or 'eval' to compile an expression.
The flags and dont_inherit arguments affect future-related
statements, but are not supported yet.</description>

<properties><property kind="parameter" name="source" required="1"/><property kind="parameter" name="filename" required="1"/><property kind="parameter" name="mode" required="1"/><property default="None" kind="parameter" name="flags" required="1"/><property default="None     dont_inherit=None" kind="parameter" name="dont_inherit" required="1"/></properties></element>

<element kind="function" name="compileFile">
<description>Compiles the file source and generates a .pyc file.</description>

<properties><property kind="parameter" name="sourcesource" required="1"/></properties></element>

<group name="AST Nodes">
<description>The compiler.ast module is generated from a text file that
describes each node type and its elements. Each node type is
represented as a class that inherits from the abstract base class
compiler.ast.Node and defines a set of named attributes for
child nodes.
</description>
<element kind="function" name="Node">
<description>The Node instances are created automatically by the parser
generator. The recommended interface for specific Node
instances is to use the public attributes to access child nodes. A
public attribute may be bound to a single node or to a sequence of
nodes, depending on the Node type. For example, the
bases attribute of the Class node, is bound to a
list of base class nodes, and the doc attribute is bound to
a single node.
Each Node instance has a lineno attribute which may
be None. XXX Not sure what the rules are for which nodes
will have a useful lineno.</description>

</element>

<element kind="function" name="getChildren">
<description>Returns a flattened list of the child nodes and objects in the
order they occur. Specifically, the order of the nodes is the
order in which they appear in the Python grammar. Not all of the
children are Node instances. The names of functions and
classes, for example, are plain strings.</description>

</element>

<element kind="function" name="getChildNodes">
<description>Returns a flattened list of the child nodes in the order they
occur. This method is like getChildren(), except that it
only returns those children that are Node instances.</description>

</element>

</group>
<group name="Assignment nodes">
<description>There is a collection of nodes used to represent assignments. Each
assignment statement in the source code becomes a single
Assign node in the AST. The nodes attribute is a
list that contains a node for each assignment target. This is
necessary because assignment can be chained, e.g. a = b = 2.
Each Node in the list will be one of the following classes: AssAttr, AssList, AssName, or
AssTuple. Each target assignment node will describe the kind of object being
assigned to: AssName for a simple name, e.g. a = 1.
AssAttr for an attribute assigned, e.g. a.x = 1.
AssList and AssTuple for list and tuple expansion
respectively, e.g. a, b, c = a_tuple.
The target assignment nodes also have a flags attribute that
indicates whether the node is being used for assignment or in a delete
statement. The AssName is also used to represent a delete
statement, e.g. del x.
When an expression contains several attribute references, an
assignment or delete statement will contain only one AssAttr
node -- for the final attribute reference. The other attribute
references will be represented as Getattr nodes in the
expr attribute of the AssAttr instance.
</description>
</group>
<group name="Examples">
<description>This section shows several simple examples of ASTs for Python source
code. The examples demonstrate how to use the parse()
function, what the repr of an AST looks like, and how to access
attributes of an AST node.
The first module defines a single function. Assume it is stored in
/tmp/doublelib.py. &quot;&quot;&quot;This is an example module.
This is the docstring.
&quot;&quot;&quot;
def double(x):
&quot;Return twice the argument&quot;
return x * 2
In the interactive interpreter session below, I have reformatted the
long AST reprs for readability. The AST reprs use unqualified class
names. If you want to create an instance from a repr, you must import
the class names from the compiler.ast module.
&gt;&gt;&gt; import compiler
&gt;&gt;&gt; mod = compiler.parseFile(&quot;/tmp/doublelib.py&quot;)
&gt;&gt;&gt; mod
Module('This is an example module. is the docstring.', Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', Stmt([Return(Mul((Name('x'), Const(2))))]))]))
&gt;&gt;&gt; from compiler.ast import *
&gt;&gt;&gt; Module('This is an example module. is the docstring.', ... Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', ... Stmt([Return(Mul((Name('x'), Const(2))))]))]))
Module('This is an example module. is the docstring.', Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', Stmt([Return(Mul((Name('x'), Const(2))))]))]))
&gt;&gt;&gt; mod.doc
'This is an example module. is the docstring.'
&gt;&gt;&gt; for node in mod.node.nodes:
... print node
... Function('double', ['x'], [], 0, 'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))
&gt;&gt;&gt; func = mod.node.nodes[0]
&gt;&gt;&gt; func.code
Stmt([Return(Mul((Name('x'), Const(2))))])
Using Visitors to Walk ASTs
The visitor pattern is ... The compiler package uses a
variant on the visitor pattern that takes advantage of Python's
introspection features to elminiate the need for much of the visitor's
infrastructure.
The classes being visited do not need to be programmed to accept
visitors. The visitor need only define visit methods for classes it
is specifically interested in; a default visit method can handle the
rest. XXX The magic visit() method for visitors.
</description>
<element kind="function" name="walk">
<description/>

<properties><property kind="parameter" name="tree" required="1"/><property kind="parameter" name="visitor" required="1"/><property kind="parameter" name="verbose"/></properties></element>

<element kind="function" name="ASTVisitor">
<description>The ASTVisitor is responsible for walking over the tree in the
correct order. A walk begins with a call to preorder(). For
each node, it checks the visitor argument to preorder()
for a method named `visitNodeType,' where NodeType is the name of the
node's class, e.g. for a While node a visitWhile()
would be called. If the method exists, it is called with the node as
its first argument.
The visitor method for a particular node type can control how child
nodes are visited during the walk. The ASTVisitor modifies
the visitor argument by adding a visit method to the visitor; this
method can be used to visit a particular child node. If no visitor is
found for a particular node type, the default() method is
called.</description>

</element>

<element kind="function" name="default">
<description/>

<properties><property kind="parameter" name="node" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="dispatch">
<description/>

<properties><property kind="parameter" name="node" required="1"/><property kind="parameter" name="moreargs"/></properties></element>

<element kind="function" name="preorder">
<description/>

<properties><property kind="parameter" name="tree" required="1"/><property kind="parameter" name="visitor visitor" required="1"/></properties></element>

</group>
</group>
</group>
<group name="SGI IRIX Specific Services">
<group name="al --- Audio functions on the SGI">
<description>IRIX
Audio functions on the SGI.
This module provides access to the audio facilities of the SGI Indy
and Indigo workstations. See section 3A of the IRIX man pages for
details. You'll need to read those man pages to understand what these
functions do! Some of the functions are not available in IRIX
releases before 4.0.5. Again, see the manual to check whether a
specific function is available on your platform.
All functions and methods defined in this module are equivalent to
the C functions with AL prefixed to their name.
Symbolic constants from the C header file &lt;audio.h&gt; are
defined in the standard module
ALAL, see below.
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:
</description>
<element kind="function" name="openport">
<description>The name and direction arguments are strings. The optional
config argument is a configuration object as returned by
newconfig(). The return value is an audio port
object; methods of audio port objects are described below.</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="direction" required="1"/><property kind="parameter" name="config"/></properties></element>

<element kind="function" name="newconfig">
<description>The return value is a new audio configuration object; methods of
audio configuration objects are described below.</description>

</element>

<element kind="function" name="queryparams">
<description>The device argument is an integer. The return value is a list of
integers containing the data returned by ALqueryparams().</description>

<properties><property kind="parameter" name="devicedevice" required="1"/></properties></element>

<element kind="function" name="getparams">
<description>The device argument is an integer. The list argument is a list
such as returned by queryparams(); it is modified in place
(!).</description>

<properties><property kind="parameter" name="device" required="1"/><property kind="parameter" name="list list" required="1"/></properties></element>

<element kind="function" name="setparams">
<description>The device argument is an integer. The list argument is a
list such as returned by queryparams().</description>

<properties><property kind="parameter" name="device" required="1"/><property kind="parameter" name="list list" required="1"/></properties></element>

<group name="Configuration Objects">
<description>Configuration objects returned by newconfig() have the
following methods:
[audio configuration]{getqueuesize}{}
Return the queue size.
[audio configuration]{setqueuesize}{size}
Set the queue size.
[audio configuration]{getwidth}{}
Get the sample width.
[audio configuration]{setwidth}{width}
Set the sample width.
[audio configuration]{getchannels}{}
Get the channel count.
[audio configuration]{setchannels}{nchannels}
Set the channel count.
[audio configuration]{getsampfmt}{}
Get the sample format.
[audio configuration]{setsampfmt}{sampfmt}
Set the sample format.
[audio configuration]{getfloatmax}{}
Get the maximum value for floating sample formats.
[audio configuration]{setfloatmax}{floatmax}
Set the maximum value for floating sample formats.
</description>
</group>
<group name="Port Objects">
</group>
</group>
<group name="cd --- CD-ROM access on SGI systems">
<description>IRIX
Interface to the CD-ROM on Silicon Graphics systems.
This module provides an interface to the Silicon Graphics CD library.
It is available only on Silicon Graphics systems.
The way the library works is as follows. A program opens the CD-ROM
device with open() and creates a parser to parse the data
from the CD with createparser(). The object returned by
open() can be used to read data from the CD, but also to get
status information for the CD-ROM device, and to get information about
the CD, such as the table of contents. Data from the CD is passed to
the parser, which parses the frames, and calls any callback
functions that have previously been added.
An audio CD is divided into tracks or programs (the terms
are used interchangeably). Tracks can be subdivided into
indices. An audio CD contains a table of contents which
gives the starts of the tracks on the CD. Index 0 is usually the
pause before the start of a track. The start of the track as given by
the table of contents is normally the start of index 1.
Positions on a CD can be represented in two ways. Either a frame
number or a tuple of three values, minutes, seconds and frames. Most
functions use the latter representation. Positions can be both
relative to the beginning of the CD, and to the beginning of the
track.
Module cd defines the following functions and constants:
</description>
<element kind="function" name="createparser">
<description>Create and return an opaque parser object. The methods of the parser
object are described below.</description>

</element>

<element kind="function" name="msftoframe">
<description>Converts a (minutes, seconds, frames) triple
representing time in absolute time code into the corresponding CD
frame number.</description>

<properties><property kind="parameter" name="minutes" required="1"/><property kind="parameter" name="seconds" required="1"/><property kind="parameter" name="frames frames" required="1"/></properties></element>

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

<properties><property kind="parameter" name="device" required="1"/><property kind="parameter" name="mode"/></properties></element>

<group name="Player Objects">
</group>
<group name="Parser Objects">
</group>
</group>
<group name="fl --- FORMS library for graphical user interfaces">
<description>IRIX
FORMS library for applications with graphical user
interfaces.
This module provides an interface to the FORMS Library</description>
<group name="Functions Defined in Module fl">
<description>FL Functions
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:
</description>
<element kind="function" name="make_form">
<description>Create a form with given type, width and height. This returns a
form object, whose methods are described below.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="width" required="1"/><property kind="parameter" name="height height" required="1"/></properties></element>

<element kind="function" name="do_forms">
<description>The standard FORMS main loop. Returns a Python object representing
the FORMS object needing interaction, or the special value
FL.EVENT.</description>

</element>

<element kind="function" name="check_forms">
<description>Check for FORMS events. Returns what do_forms() above
returns, or None if there is no event that immediately needs
interaction.</description>

</element>

<element kind="function" name="set_event_call_back">
<description>Set the event callback function.</description>

<properties><property kind="parameter" name="functionfunction" required="1"/></properties></element>

<element kind="function" name="set_graphics_mode">
<description>Set the graphics modes.</description>

<properties><property kind="parameter" name="rgbmode" required="1"/><property kind="parameter" name="doublebuffering doublebuffering" required="1"/></properties></element>

<element kind="function" name="get_rgbmode">
<description>Return the current rgb mode. This is the value of the C global
variable fl_rgbmode.</description>

</element>

<element kind="function" name="show_message">
<description>Show a dialog box with a three-line message and an OK button.</description>

<properties><property kind="parameter" name="str1" required="1"/><property kind="parameter" name="str2" required="1"/><property kind="parameter" name="str3 str3" required="1"/></properties></element>

<element kind="function" name="show_question">
<description>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.</description>

<properties><property kind="parameter" name="str1" required="1"/><property kind="parameter" name="str2" required="1"/><property kind="parameter" name="str3 str3" required="1"/></properties></element>

<element kind="function" name="show_choice">
<description>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).</description>

<properties><property kind="parameter" name="str1" required="1"/><property kind="parameter" name="str2" required="1"/><property kind="parameter" name="str3" required="1"/><property kind="parameter" name="but1" required="1"/><property kind="parameter" name="but2"/><property kind="parameter" name="but3"/></properties></element>

<element kind="function" name="show_input">
<description>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.</description>

<properties><property kind="parameter" name="prompt" required="1"/><property kind="parameter" name="default default" required="1"/></properties></element>

<element kind="function" name="show_file_selector">
<description>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.</description>

<properties><property kind="parameter" name="message" required="1"/><property kind="parameter" name="directory" required="1"/><property kind="parameter" name="pattern" required="1"/><property kind="parameter" name="default default" required="1"/></properties></element>

<element kind="function" name="get_directory">
<description>get_pattern{}
get_filename{}
These functions return the directory, pattern and filename (the tail
part only) selected by the user in the last
show_file_selector() call.</description>

</element>

<element kind="function" name="qdevice">
<description>unqdevice{dev}
isqueued{dev}
qtest{}
qread{}
%blkqread{?}
qreset{}
qenter{dev, val}
get_mouse{}
tie{button, valuator1, valuator2}
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!</description>

<properties><property kind="parameter" name="devdev" required="1"/></properties></element>

<element kind="function" name="color">
<description>mapcolor{}
getmcolor{}
See the description in the FORMS documentation of
fl_color(), fl_mapcolor() and
fl_getmcolor().</description>

</element>

</group>
<group name="Form Objects">
<element kind="function" name="show_form">
<description>Show the form.</description>

<properties><property kind="parameter" name="placement" required="1"/><property kind="parameter" name="bordertype" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="hide_form">
<description>Hide the form.</description>

</element>

<element kind="function" name="redraw_form">
<description>Redraw the form.</description>

</element>

<element kind="function" name="set_form_position">
<description>Set the form's position.</description>

<properties><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y y" required="1"/></properties></element>

<element kind="function" name="freeze_form">
<description>Freeze the form.</description>

</element>

<element kind="function" name="unfreeze_form">
<description>Unfreeze the form.</description>

</element>

<element kind="function" name="activate_form">
<description>Activate the form.</description>

</element>

<element kind="function" name="deactivate_form">
<description>Deactivate the form.</description>

</element>

<element kind="function" name="bgn_group">
<description>Begin a new group of objects; return a group object.</description>

</element>

<element kind="function" name="end_group">
<description>End the current group of objects.</description>

</element>

<element kind="function" name="find_first">
<description>Find the first object in the form.</description>

</element>

<element kind="function" name="find_last">
<description>Find the last object in the form.</description>

</element>

<element kind="function" name="add_box">
<description>Add a box object to the form.
No extra methods.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_text">
<description>Add a text object to the form.
No extra methods.</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_bitmap">
<description>%Add a bitmap object to the form.
%</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_clock">
<description>Add a clock object to the form. :
get_clock().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_button">
<description>Add a button object to the form. :
get_button(),
set_button().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name  name" required="1"/></properties></element>

<element kind="function" name="add_lightbutton">
<description>Add a lightbutton object to the form. :
get_button(),
set_button().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_roundbutton">
<description>Add a roundbutton object to the form. :
get_button(),
set_button().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_slider">
<description>Add a slider object to the form. :
set_slider_value(),
get_slider_value(),
set_slider_bounds(),
get_slider_bounds(),
set_slider_return(),
set_slider_size(),
set_slider_precision(),
set_slider_step().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_valslider">
<description>Add a valslider object to the form. :
set_slider_value(),
get_slider_value(),
set_slider_bounds(),
get_slider_bounds(),
set_slider_return(),
set_slider_size(),
set_slider_precision(),
set_slider_step().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_dial">
<description>Add a dial object to the form. :
set_dial_value(),
get_dial_value(),
set_dial_bounds(),
get_dial_bounds().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_positioner">
<description>Add a positioner object to the form. :
set_positioner_xvalue(),
set_positioner_yvalue(),
set_positioner_xbounds(),
set_positioner_ybounds(),
get_positioner_xvalue(),
get_positioner_yvalue(),
get_positioner_xbounds(),
get_positioner_ybounds().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_counter">
<description>Add a counter object to the form. :
set_counter_value(),
get_counter_value(),
set_counter_bounds(),
set_counter_step(),
set_counter_precision(),
set_counter_return().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_input">
<description>Add a input object to the form. :
set_input(),
get_input(),
set_input_color(),
set_input_return().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_menu">
<description>Add a menu object to the form. :
set_menu(),
get_menu(),
addto_menu().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_choice">
<description>Add a choice object to the form. :
set_choice(),
get_choice(),
clear_choice(),
addto_choice(),
replace_choice(),
delete_choice(),
get_choice_text(),
set_choice_fontsize(),
set_choice_fontstyle().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_browser">
<description>Add a browser object to the form. :
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().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

<element kind="function" name="add_timer">
<description>Add a timer object to the form. :
set_timer(),
get_timer().</description>

<properties><property kind="parameter" name="type" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="name name" required="1"/></properties></element>

</group>
<group name="FORMS Objects">
</group>
</group>
<group name="fm --- Font Manager interface">
<description>IRIX
Font Manager interface for SGI workstations.
This module provides access to the IRIS Font Manager library.
</description>
<element kind="function" name="init">
<description>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.</description>

</element>

<element kind="function" name="findfont">
<description>Return a font handle object.
Calls fmfindfont(fontname).</description>

<properties><property kind="parameter" name="fontnamefontname" required="1"/></properties></element>

<element kind="function" name="enumerate">
<description>Returns a list of available font names.
This is an interface to fmenumerate().</description>

</element>

<element kind="function" name="prstr">
<description>Render a string using the current font (see the setfont() font
handle method below).
Calls fmprstr(string).</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="setpath">
<description>Sets the font search path.
Calls fmsetpath(string).
(XXX Does not work!?!)</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

<element kind="function" name="fontpath">
<description>Returns the current font search path.</description>

</element>

<element kind="function" name="scalefont">
<description>Returns a handle for a scaled version of this font.
Calls fmscalefont(fh, factor).</description>

<properties><property kind="parameter" name="factorfactor" required="1"/></properties></element>

<element kind="function" name="setfont">
<description>Makes this font the current font.
Note: the effect is undone silently when the font handle object is
deleted.
Calls fmsetfont(fh).</description>

</element>

<element kind="function" name="getfontname">
<description>Returns this font's name.
Calls fmgetfontname(fh).</description>

</element>

<element kind="function" name="getcomment">
<description>Returns the comment string associated with this font.
Raises an exception if there is none.
Calls fmgetcomment(fh).</description>

</element>

<element kind="function" name="getfontinfo">
<description>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).</description>

</element>

<element kind="function" name="getstrwidth">
<description>Returns the width, in pixels, of string when drawn in this font.
Calls fmgetstrwidth(fh, string).</description>

<properties><property kind="parameter" name="stringstring" required="1"/></properties></element>

</group>
<group name="gl --- Graphics Library interface">
<description>IRIX
Functions from the Silicon Graphics Graphics Library.
This module provides access to the Silicon Graphics
Graphics Library.
It is available only on Silicon Graphics machines.
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, &amp;red, &amp;green, &amp;blue)
is translated to Python as
red, green, blue = getmcolor(i)
The following functions are non-standard or have special argument
conventions:
</description>
<element kind="function" name="varray">
<description>%JHXXX the argument-argument added
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.</description>

<properties><property kind="parameter" name="argumentargument" required="1"/></properties></element>

<element kind="function" name="nvarray">
<description>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.</description>

</element>

<element kind="function" name="vnarray">
<description>Similar to nvarray()
but the pairs have the point first and the normal second.</description>

</element>

<element kind="function" name="nurbssurface">
<description>% XXX s_k[], t_k[], ctl[][]
Defines a nurbs surface.
The dimensions of
ctl[][]
are computed as follows:
[len(s_k) - s_ord],
[len(t_k) - t_ord].</description>

<properties><property kind="parameter" name="s_k" required="1"/><property kind="parameter" name="t_k" required="1"/><property kind="parameter" name="ctl" required="1"/><property kind="parameter" name="s_ord" required="1"/><property kind="parameter" name="t_ord" required="1"/><property kind="parameter" name="type type" required="1"/></properties></element>

<element kind="function" name="nurbscurve">
<description>Defines a nurbs curve.
The length of ctlpoints is
len(knots) - order.</description>

<properties><property kind="parameter" name="knots" required="1"/><property kind="parameter" name="ctlpoints" required="1"/><property kind="parameter" name="order" required="1"/><property kind="parameter" name="type type" required="1"/></properties></element>

<element kind="function" name="pwlcurve">
<description>Defines a piecewise-linear curve.
points
is a list of points.
type
must be
N_ST.</description>

<properties><property kind="parameter" name="points" required="1"/><property kind="parameter" name="type type" required="1"/></properties></element>

<element kind="function" name="pick">
<description>select{n}
The only argument to these functions specifies the desired size of the
pick or select buffer.</description>

<properties><property kind="parameter" name="nn" required="1"/></properties></element>

<element kind="function" name="endpick">
<description>endselect{}
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.</description>

</element>

</group>
<group name="imgfile --- Support for SGI imglib files">
<description>IRIX
Support for SGI imglib files.
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
enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:
{error}
This exception is raised on all errors, such as unsupported file type, etc.
</description>
<element kind="function" name="getsizes">
<description>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.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="read">
<description>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.</description>

<properties><property kind="parameter" name="filefile" required="1"/></properties></element>

<element kind="function" name="readscaled">
<description>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.</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="filter" required="1"/><property kind="parameter" name="blur"/></properties></element>

<element kind="function" name="ttob">
<description>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.</description>

<properties><property kind="parameter" name="flagflag" required="1"/></properties></element>

<element kind="function" name="write">
<description>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().</description>

<properties><property kind="parameter" name="file" required="1"/><property kind="parameter" name="data" required="1"/><property kind="parameter" name="x" required="1"/><property kind="parameter" name="y" required="1"/><property kind="parameter" name="z z" required="1"/></properties></element>

</group>
<group name="jpeg --- Read and write JPEG files">
<description>IRIX
Read and write image files in compressed JPEG format.
The module jpeg provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group
</description>
<element kind="function" name="compress">
<description>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 gl.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</description>

<properties><property kind="parameter" name="data" required="1"/><property kind="parameter" name="w" required="1"/><property kind="parameter" name="h" required="1"/><property kind="parameter" name="b b" required="1"/></properties></element>

<element kind="function" name="decompress">
<description>Data is a string containing a picture in JFIF</description>

<properties><property kind="parameter" name="datadata" required="1"/></properties></element>

<element kind="function" name="setoption">
<description>Set various options. Subsequent compress() and
decompress() calls will use these options. The following
options are available:
{l|p{3in}}{code}{Option}{Effect}
'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). This only affects
compression.}
'optimize'{%
Perform Huffman table optimization. Takes longer, but results in
smaller compressed image. This only affects compression.}
'smooth'{%
Perform inter-block smoothing on uncompressed image. Only useful
for low-quality images. This only affects decompression.}
</description>

<properties><property kind="parameter" name="name" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

</group>
<group name="panel --- None">
<description>None
Please note: The FORMS library, to which the
flfl module described above interfaces, is a
simpler and more accessible user interface library for use with GL
than the panel module (besides also being by a Dutch author).
This module should be used instead of the built-in module
pnlpnl
to interface with the
Panel Library.
The module is too large to document here in its entirety.
One interesting function:
</description>
<element kind="function" name="defpanellist">
<description>Parses a panel description file containing S-expressions written by the
Panel Editor
that accompanies the Panel Library and creates the described panels.
It returns a list of panel objects.</description>

<properties><property kind="parameter" name="filenamefilename" required="1"/></properties></element>

</group>
</group>
<group name="SunOS Specific Services">
<group name="sunaudiodev --- Access to Sun audio hardware">
<description>SunOS
Access to Sun audio hardware.
This module allows you to access the Sun audio interface. The Sun
audio hardware is capable of recording and playing back audio data
in u-LAW</description>
<element kind="function" name="open">
<description>This function opens the audio device and returns a Sun audio device
object. This object can then be used to do I/O on. The mode parameter
is one of 'r' for record-only access, 'w' for play-only
access, 'rw' for both and 'control' for access to the
control device. Since only one process is allowed to have the recorder
or player open at the same time it is a good idea to open the device
only for the activity needed. See audio{7I} for details.
As per the manpage, this module first looks in the environment
variable AUDIODEV for the base audio device filename. If not
found, it falls back to /dev/audio. The control device is
calculated by appending ``ctl'' to the base audio device.</description>

<properties><property kind="parameter" name="modemode" required="1"/></properties></element>

<group name="Audio Device Objects">
</group>
</group>
</group>
<group name="MS Windows Specific Services">
<group name="msvcrt -- Useful routines from the MS VCpp">
<description>Windows
Miscellaneous useful routines from the MS VCpp.
These functions provide access to some useful capabilities on Windows
platforms. Some higher-level modules use these functions to build the Windows implementations of their services. For example, the
getpass module uses this in the implementation of the
getpass() function.
Further documentation on these functions can be found in the Platform
API documentation.
</description>
<group name="File Operations">
<element kind="function" name="locking">
<description>Lock part of a file based on file descriptor fd from the C
runtime. Raises IOError on failure. The locked region
of the file extends from the current file position for nbytes
bytes, and may continue beyond the end of the file. mode must
be one of the LK_* constants listed below.
Multiple regions in a file may be locked at the same time, but may
not overlap. Adjacent regions are not merged; they must be unlocked
individually.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="mode" required="1"/><property kind="parameter" name="nbytes nbytes" required="1"/></properties></element>

<element kind="function" name="setmode">
<description>Set the line-end translation mode for the file descriptor fd.
To set it to text mode, flags should be os.O_TEXT;
for binary, it should be os.O_BINARY.</description>

<properties><property kind="parameter" name="fd" required="1"/><property kind="parameter" name="flags flags" required="1"/></properties></element>

<element kind="function" name="open_osfhandle">
<description>Create a C runtime file descriptor from the file handle
handle. The flags parameter should be a bit-wise OR of
os.O_APPEND, os.O_RDONLY, and
os.O_TEXT. The returned file descriptor may be used as a
parameter to os.fdopen() to create a file object.</description>

<properties><property kind="parameter" name="handle" required="1"/><property kind="parameter" name="flags flags" required="1"/></properties></element>

<element kind="function" name="get_osfhandle">
<description>Return the file handle for the file descriptor fd. Raises
IOError if fd is not recognized.</description>

<properties><property kind="parameter" name="fdfd" required="1"/></properties></element>

</group>
<group name="Console I/O">
<element kind="function" name="kbhit">
<description>Return true if a keypress is waiting to be read.</description>

</element>

<element kind="function" name="getch">
<description>Read a keypress and return the resulting character. Nothing is
echoed to the console. This call will block if a keypress is not
already available, but will not wait for Enter to be pressed.
If the pressed key was a special function key, this will return
'\00' or '\xe0'; the next call will return the
keycode. The Control-C keypress cannot be read with this
function.</description>

</element>

<element kind="function" name="getche">
<description>Similar to getch(), but the keypress will be echoed if it represents a printable character.</description>

</element>

<element kind="function" name="putch">
<description>Print the character char to the console without buffering.</description>

<properties><property kind="parameter" name="charchar" required="1"/></properties></element>

<element kind="function" name="ungetch">
<description>Cause the character char to be ``pushed back'' into the
console buffer; it will be the next character read by
getch() or getche().</description>

<properties><property kind="parameter" name="charchar" required="1"/></properties></element>

</group>
<group name="Other Functions">
<element kind="function" name="heapmin">
<description>Force the malloc() heap to clean itself up and return
unused blocks to the operating system. This only works on Windows
NT. On failure, this raises IOError.</description>

</element>

</group>
</group>
<group name="_winreg -- Windows registry access">
<description>Windows
Routines and objects for manipulating the Windows registry.
New in version 2.0
These functions expose the Windows registry API to Python. Instead of
using an integer as the registry handle, a handle object is used to
ensure that the handles are closed correctly, even if the programmer
neglects to explicitly close them.
This module exposes a very low-level interface to the Windows
registry; it is expected that in the future a new winreg module will be created offering a higher-level interface to the
registry API.
This module offers the following functions:
</description>
<element kind="function" name="CloseKey">
<description>Closes a previously opened registry key.
The hkey argument specifies a previously opened key.
Note that if hkey is not closed using this method, (or the
handle.Close() closed when the hkey object is destroyed by Python.</description>

<properties><property kind="parameter" name="hkeyhkey" required="1"/></properties></element>

<element kind="function" name="ConnectRegistry">
<description>Establishes a connection to a predefined registry handle on another computer, and returns a handle object
computer_name is the name of the remote computer, of the form r&quot;\e computername&quot;. If None, the local computer
is used.
key is the predefined handle to connect to.
The return value is the handle of the opened key.
If the function fails, an EnvironmentError exception is raised.</description>

<properties><property kind="parameter" name="computer_name" required="1"/><property kind="parameter" name="key key" required="1"/></properties></element>

<element kind="function" name="CreateKey">
<description>Creates or opens the specified key, returning a handle object
key is an already open key, or one of the predefined HKEY_* constants.
sub_key is a string that names the key this method opens or creates.
If key is one of the predefined keys, sub_key may be None. In that case, the handle returned is the same key handle passed in to the function.
If the key already exists, this function opens the existing key
The return value is the handle of the opened key.
If the function fails, an EnvironmentError exception is raised.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="sub_key sub_key" required="1"/></properties></element>

<element kind="function" name="DeleteKey">
<description>Deletes the specified key.
key is an already open key, or any one of the predefined HKEY_* constants.
sub_key is a string that must be a subkey of the key identified by the key parameter. This value must not be None, and the key may not have subkeys.
This method can not delete keys with subkeys.
If the method succeeds, the entire key, including all of its values,
is removed. If the method fails, an EnvironmentError exception is raised.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="sub_key sub_key" required="1"/></properties></element>

<element kind="function" name="DeleteValue">
<description>Removes a named value from a registry key.
key is an already open key, or one of the predefined HKEY_* constants.
value is a string that identifies the value to remove.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="EnumKey">
<description>Enumerates subkeys of an open registry key, returning a string.
key is an already open key, or any one of the predefined HKEY_* constants.
index is an integer that identifies the index of the key to retrieve.
The function retrieves the name of one subkey each time it is called. It is typically called repeatedly until an EnvironmentError exception is raised, indicating, no more values are available.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="index index" required="1"/></properties></element>

<element kind="function" name="EnumValue">
<description>Enumerates values of an open registry key, returning a tuple.
key is an already open key, or any one of the predefined HKEY_* constants.
index is an integer that identifies the index of the value to retrieve.
The function retrieves the name of one subkey each time it is called. It is typically called repeatedly, until an EnvironmentError exception is raised, indicating no more values.
The result is a tuple of 3 items:
{c|p{3in}}{code}{Index}{Meaning}
0{A string that identifies the value name}
1{An object that holds the value data, and whose
type depends on the underlying registry type}
2{An integer that identifies the type of the value data}
</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="index index" required="1"/></properties></element>

<element kind="function" name="FlushKey">
<description>Writes all the attributes of a key to the registry.
key is an already open key, or one of the predefined HKEY_* constants.
It is not necessary to call RegFlushKey to change a key.
Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are also flushed to disk at system shutdown. Unlike CloseKey(), the FlushKey() method returns only when all the data has been written to the registry.
An application should only call FlushKey() if it requires absolute certainty that registry changes are on disk.
If you don't know whether a FlushKey() call is required, it probably isn't.</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="RegLoadKey">
<description>Creates a subkey under the specified key and stores registration information from a specified file into that subkey.
key is an already open key, or any of the predefined
HKEY_* constants.
sub_key is a string that identifies the sub_key to load
{file_name} is the name of the file to load registry data from.
This file must have been created with the SaveKey() function.
Under the file allocation table (FAT) file system, the filename may not
have an extension.
A call to LoadKey() fails if the calling process does not have the
SE_RESTORE_PRIVILEGE privilege. Note that privileges
are different than permissions - see the Win32 documentation for
more details.
If key is a handle returned by ConnectRegistry(), then the path specified in fileName is relative to the remote computer.
The Win32 documentation implies key must be in the HKEY_USER or HKEY_LOCAL_MACHINE tree.
This may or may not be true.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="sub_key" required="1"/><property kind="parameter" name="file_name file_name" required="1"/></properties></element>

<element kind="function" name="OpenKey">
<description>Opens the specified key, returning a handle object
key is an already open key, or any one of the predefined
HKEY_* constants.
sub_key is a string that identifies the sub_key to open
res is a reserved integer, and must be zero. The default is zero.
sam is an integer that specifies an access mask that describes the desired security access for the key. Default is KEY_READ
The result is a new handle to the specified key
If the function fails, EnvironmentError is raised.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="sub_key" required="1"/><property default=" 0" kind="parameter" name="res"/><property default=" KEY_READ" kind="parameter" name="sam"/></properties></element>

<element kind="function" name="OpenKeyEx">
<description>The functionality of OpenKeyEx() is provided via
OpenKey(), by the use of default arguments.</description>

</element>

<element kind="function" name="QueryInfoKey">
<description>Returns information about a key, as a tuple.
key is an already open key, or one of the predefined HKEY_* constants.
The result is a tuple of 3 items:
{c|p{3in}}{code}{Index}{Meaning}
0{An integer giving the number of sub keys this key has.}
1{An integer giving the number of values this key has.}
2{A long integer giving when the key was last modified (if
available) as 100's of nanoseconds since Jan 1, 1600.}
</description>

<properties><property kind="parameter" name="keykey" required="1"/></properties></element>

<element kind="function" name="QueryValue">
<description>Retrieves the unnamed value for a key, as a string
key is an already open key, or one of the predefined HKEY_* constants.
sub_key is a string that holds the name of the subkey with which the value is associated. If this parameter is None or empty, the function retrieves the value set by the SetValue() method for the key identified by key.
Values in the registry have name, type, and data components. This method retrieves the data for a key's first value that has a NULL name.
But the underlying API call doesn't return the type, Lame Lame Lame,
DO NOT USE THIS!!!</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="sub_key sub_key" required="1"/></properties></element>

<element kind="function" name="QueryValueEx">
<description>Retrieves the type and data for a specified value name associated with an open registry key.
key is an already open key, or one of the predefined HKEY_* constants.
value_name is a string indicating the value to query.
The result is a tuple of 2 items:
{c|p{3in}}{code}{Index}{Meaning}
0{The value of the registry item.}
1{An integer giving the registry type for this value.}
</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="value_name value_name" required="1"/></properties></element>

<element kind="function" name="SaveKey">
<description>Saves the specified key, and all its subkeys to the specified file.
key is an already open key, or one of the predefined HKEY_* constants.
file_name is the name of the file to save registry data to.
This file cannot already exist. If this filename includes an extension,
it cannot be used on file allocation table (FAT) file systems by the
LoadKey(), ReplaceKey() or RestoreKey() methods.
If key represents a key on a remote computer, the path described by file_name is relative to the remote computer.
The caller of this method must possess the SeBackupPrivilege security privilege. Note that privileges are different than permissions - see the Win32 documentation for more details.
This function passes NULL for security_attributes to the API.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="file_name file_name" required="1"/></properties></element>

<element kind="function" name="SetValue">
<description>Associates a value with a specified key.
key is an already open key, or one of the predefined HKEY_* constants.
sub_key is a string that names the subkey with which the value is associated.
type is an integer that specifies the type of the data.
Currently this must be REG_SZ, meaning only strings are
supported. Use the SetValueEx() function for support for
other data types.
value is a string that specifies the new value.
If the key specified by the sub_key parameter does not exist,
the SetValue function creates it.
Value lengths are limited by available memory. Long values (more than
2048 bytes) should be stored as files with the filenames stored in
the configuration registry. This helps the registry perform
efficiently.
The key identified by the key parameter must have been opened with KEY_SET_VALUE access.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="sub_key" required="1"/><property kind="parameter" name="type" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<element kind="function" name="SetValueEx">
<description>Stores data in the value field of an open registry key.
key is an already open key, or one of the predefined HKEY_* constants.
sub_key is a string that names the subkey with which the value is associated.
type is an integer that specifies the type of the data. This should be one of the following constants defined in this module:
{l|p{3in}}{constant}{Constant}{Meaning}
REG_BINARY{Binary data in any form.}
REG_DWORD{A 32-bit number.}
REG_DWORD_LITTLE_ENDIAN{A 32-bit number in little-endian format.}
REG_DWORD_BIG_ENDIAN{A 32-bit number in big-endian format.}
REG_EXPAND_SZ{Null-terminated string containing references
to environment variables (%).}
REG_LINK{A Unicode symbolic link.}
REG_MULTI_SZ{A sequence of null-terminated strings, terminated by two null characters. (Python handles this termination automatically.)}
REG_NONE{No defined value type.}
REG_RESOURCE_LIST{A device-driver resource list.}
REG_SZ{A null-terminated string.}
reserved can be anything - zero is always passed to the API.
value is a string that specifies the new value.
This method can also set additional value and type information for the
specified key. The key identified by the key parameter must have been
opened with KEY_SET_VALUE access.
To open the key, use the CreateKeyEx() or OpenKey() methods.
Value lengths are limited by available memory. Long values (more than
2048 bytes) should be stored as files with the filenames stored in
the configuration registry. This helps the registry perform efficiently.</description>

<properties><property kind="parameter" name="key" required="1"/><property kind="parameter" name="value_name" required="1"/><property kind="parameter" name="reserved" required="1"/><property kind="parameter" name="type" required="1"/><property kind="parameter" name="value value" required="1"/></properties></element>

<group name="Registry Handle Objects">
<description>This object wraps a Windows HKEY object, automatically closing it when
the object is destroyed. To guarantee cleanup, you can call either
the Close() method on the object, or the CloseKey() function.
All registry functions in this module return one of these objects.
All registry functions in this module which accept a handle object also accept an integer, however, use of the handle object is encouraged.
Handle objects provide semantics for __nonzero__() - thus
if handle:
print &quot;Yes&quot;
will print Yes if the handle is currently valid (has not been
closed or detached).
The object also support comparison semantics, so handle
objects will compare true if they both reference the same
underlying Windows handle value.
Handle objects can be converted to an integer (eg, using the
builtin int() function, in which case the underlying
Windows handle value is returned. You can also use the Detach() method to return the integer handle, and
also disconnect the Windows handle from the handle object.
</description>
<element kind="function" name="Close">
<description>Closes the underlying Windows handle.
If the handle is already closed, no error is raised.</description>

</element>

<element kind="function" name="Detach">
<description>Detaches the Windows handle from the handle object.
The result is an integer (or long on 64 bit Windows) that holds
the value of the handle before it is detached. If the
handle is already detached or closed, this will return zero.
After calling this function, the handle is effectively invalidated,
but the handle is not closed. You would call this function when you need the underlying Win32 handle to exist beyond the lifetime of the handle object.</description>

</element>

</group>
</group>
<group name="winsound --- Sound-playing interface for Windows">
<description>Windows
Access to the sound-playing machinery for Windows.
New in version 1.5.2
The winsound module provides access to the basic
sound-playing machinery provided by Windows platforms. It includes
two functions and several constants.
</description>
<element kind="function" name="Beep">
<description>Beep the PC's speaker.
The frequency parameter specifies frequency, in hertz, of the
sound, and must be in the range 37 through 32,767.
The duration parameter specifies the number of milliseconds the
sound should last. If the system is not
able to beep the speaker, RuntimeError is raised.
Under Windows 95 and 98, the Windows Beep()
function exists but is useless (it ignores its arguments). In that
case Python simulates it via direct port manipulation (added in version
2.1). It's unknown whether that will work on all systems.
New in version 1.6</description>

<properties><property kind="parameter" name="frequency" required="1"/><property kind="parameter" name="duration duration" required="1"/></properties></element>

<element kind="function" name="PlaySound">
<description>Call the underlying PlaySound() function from the
Platform API. The sound parameter may be a filename, audio
data as a string, or None. Its interpretation depends on the
value of flags, which can be a bit-wise ORed combination of
the constants described below. If the system indicates an error,
RuntimeError is raised.</description>

<properties><property kind="parameter" name="sound" required="1"/><property kind="parameter" name="flags flags" required="1"/></properties></element>

<element kind="function" name="MessageBeep">
<description>Call the underlying MessageBeep() function from the
Platform API. This plays a sound as specified in the registry. The
type argument specifies which sound to play; possible values
are -1, MB_ICONASTERISK, MB_ICONEXCLAMATION,
MB_ICONHAND, MB_ICONQUESTION, and MB_OK, all
described below. The value -1 produces a ``simple beep'';
this is the final fallback if a sound cannot be played otherwise.
New in version 2.3</description>

<properties><property default="MB_OK" kind="parameter" name="type" required="1"/></properties></element>

</group>
</group>
</ref>