ConfigParser-objects.html | misc.html | module-xreadlines.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 5.11 fileinput --
Iterate over lines from multiple input streams
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:
```text

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:
The following functions use the global state created by
input(); if there is no active state,
RuntimeError is raised.
The class which implements the sequence behavior provided by the
module is available for subclassing as well:
Optional in-place filtering: if the keyword argument
`inplace =1` is passed to input() or to the
FileInput constructor, the file is moved to a backup file and
standard output is directed to the input file (if a file of the same
name as the backup file already exists, it will be replaced silently).
This makes it possible to write a filter that rewrites its input file
in place. If the keyword argument `backup ='.<some
extension>'` is also given, it specifies the extension for the backup
file, and the backup file remains around; by default, the extension is
`'.bak'` and it is deleted when the output file is closed. In-place
filtering is disabled when standard input is read.


forms-objects.html | sgi.html | module-flp.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.5 FL --
Constants used with the fl module
Availability: IRIX.
This module defines symbolic constants needed to use the built-in
module fl (module-fl.html) (see above); they are equivalent to those defined in
the C header file `<forms.h>` except that the name prefix
"FL_" is omitted. Read the module source for a complete list of
the defined names. Suggested use:
```text

import fl
from FL import *
```


cd-parser-objects.html | sgi.html | node589.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.4 fl --
FORMS library for graphical user interfaces
Availability: IRIX.
This module provides an interface to the FORMS Libraryby Mark Overmars. The source for the
library can be retrieved by anonymous ftp from host
"ftp.cs.ruu.nl", directory SGI/FORMS. It was last tested
with version 2.0b.
Most functions are literal translations of their C equivalents,
dropping the initial "fl_" from their name. Constants used by
the library are defined in module FL (module-fl-constants.html)
described below.
The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
form are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
fl_addto_form() and fl_end_form(), and the
equivalent of fl_bgn_form() is called
fl.make_form().
Watch out for the somewhat confusing terminology: FORMS uses the word
object for the buttons, sliders etc. that you can place in a form.
In Python, `object' means any value. The Python interface to FORMS
introduces two new Python object types: form objects (representing an
entire form) and FORMS objects (representing one button, slider etc.).
Hopefully this isn't too confusing.
There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python. The FORMS
interface to GL event handling is available, though, so you can mix
FORMS with pure GL windows.
Please note: importing fl implies a call to the GL
function foreground() and to the FORMS routine
fl_init().


module-fl-constants.html | sgi.html | module-fm.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.6 flp --
Functions for loading stored FORMS designs
Availability: IRIX.
This module defines functions that can read form definitions created
by the `form designer' (fdesign) program that comes with the
FORMS library (see module fl (module-fl.html) above).
For now, see the file flp.doc in the Python library source
directory for a description.


20.7 fm -- Font Manager interface

module-flp.html | sgi.html | module-gl.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.7 fm --
Font Manager interface
Availability: IRIX.
This module provides access to the IRIS Font Manager library.
It is available only on Silicon Graphics machines.
See also: 4Sight User's Guide, section 1, chapter 5: ``Using
the IRIS Font Manager.''
This is not yet a full interface to the IRIS Font Manager.
Among the unsupported features are: matrix operations; cache
operations; character operations (use string operations instead); some
details of font info; individual glyph metrics; and printer matching.
It supports the following operations:
Font handle objects support the following operations:


module-glob.html | allos.html | module-shutil.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.22 fnmatch --
Unix filename pattern matching
This module provides support for Unix shell-style wildcards, which
are not the same as regular expressions (which are documented
in the re (module-re.html)module). The special
characters used in shell-style wildcards are:
Note that the filename separator (`'/'` on Unix) is not
special to this module. See module
glob (module-glob.html)for pathname expansion
(glob (module-glob.html) uses fnmatch() to match pathname
segments). Similarly, filenames starting with a period are
not special for this module, and are matched by the `*` and
`?` patterns.


netdata.html | netdata.html | formatter-interface.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.1 formatter --
Generic output formatting
This module supports two interface definitions, each with multiple
implementations. The formatter interface is used by the
HTMLParser class of the htmllib (module-htmllib.html) module, and the
writer interface is required by the formatter interface.
Formatter objects transform an abstract flow of formatting events into
specific output events on writer objects. Formatters manage several
stack structures to allow various properties of a writer object to be
changed and restored; writers need not be able to handle relative
changes nor any sort of ``change back'' operation. Specific writer
properties which may be controlled via formatter objects are
horizontal alignment, font, and left margin indentations. A mechanism
is provided which supports providing arbitrary, non-exclusive style
settings to a writer as well. Additional interfaces facilitate
formatting events which are not reversible, such as paragraph
separation.
Writer objects encapsulate device interfaces. Abstract devices, such
as file formats, are supported as well as physical devices. The
provided implementations all work with abstract devices. The
interface makes available mechanisms for setting the properties which
formatter objects manage and inserting data into the output.


weakref-extension.html | python.html | fpectl-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.4 fpectl --
Floating point exception control
Availability: Unix.
Most computers carry out floating point operationsin conformance with the so-called IEEE-754 standard.
On any real computer,
some floating point operations produce results that cannot
be expressed as a normal floating point value.
For example, try
```text

>>> import math
>>> math.exp(1000)
inf
>>> math.exp(1000) / math.exp(1000)
nan
```
(The example above will work on many platforms.
DEC Alpha may be one exception.)
"Inf" is a special, non-numeric value in IEEE-754 that
stands for "infinity", and "nan" means "not a number."
Note that,
other than the non-numeric results,
nothing special happened when you asked Python
to carry out those calculations.
That is in fact the default behaviour prescribed in the IEEE-754 standard,
and if it works for you,
stop reading now.
In some circumstances,
it would be better to raise an exception and stop processing
at the point where the faulty operation was attempted.
The fpectl module
is for use in that situation.
It provides control over floating point
units from several hardware manufacturers,
allowing the user to turn on the generation
of SIGFPE whenever any of the
IEEE-754 exceptions Division by Zero, Overflow, or
Invalid Operation occurs.
In tandem with a pair of wrapper macros that are inserted
into the C code comprising your python system,
SIGFPE is trapped and converted into the Python
FloatingPointError exception.
The fpectl module defines the following functions and
may raise the given exception:


differ-examples.html | strings.html | module-StringIO.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 4.5 fpformat --
Floating point conversions
The fpformat module defines functions for dealing with
floating point numbers representations in 100% pure
Python. Note:
This module is unneeded: everything here could
be done via the `%` string interpolation operator.
The fpformat module defines the following functions and an
exception:
Example:


11.7 ftplib -- FTP protocol client

httplib-examples.html | internet.html | ftp-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 11.7 ftplib --
FTP protocol client
This module defines the class FTP and a few related items.
The FTP class implements the client side of the FTP
protocol. You can use this to write Python
programs that perform a variety of automated FTP jobs, such as
mirroring other ftp servers. It is also used by the module
urllib (module-urllib.html) to handle URLs that use FTP. For more information
on FTP (File Transfer Protocol), see Internet RFC 959 (http://www.faqs.org/rfcs/rfc959.html).
Here's a sample session using the ftplib module:
```text

>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
>>> ftp.login() # user anonymous, passwd user@hostname
>>> ftp.retrlines('LIST') # list directory contents
total 24418
drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
.
.
.
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()
```
The module defines the following items:
See Also:
The file Tools/scripts/ftpmirror.py in the Python source distribution is a script that can mirror
FTP sites, or portions thereof, using the ftplib module.
It can be used as an extended example that applies this module.


3.2 gc -- Garbage Collector interface

module-sys.html | python.html | module-weakref.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.2 gc --
Garbage Collector interface
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:
The following variable is provided for read-only access (you can
mutate its value but should not rebind it):
The following constants are provided for use with
set_debug():


module-dbm.html | unix.html | module-termios.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.7 gdbm --
GNU's reinterpretation of dbm
Availability: Unix.
This module is quite similar to the dbm (module-dbm.html)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:
In addition to the dictionary-like methods, `gdbm` objects have the
following methods:


curses-panel-objects.html | allos.html | module-tempfile.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.18 getopt --
Parser for command line options
This module helps scripts to parse the command line arguments in
`sys.argv`.
It supports the same conventions as the Unix getopt()
function (including the special meanings of arguments of the form
``-`' and ``-``-`').
Long options similar to those supported by
GNU software may be used as well via an optional third argument.
This module provides a single function and an exception:
An example using only Unix style options:
```text

>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
```
Using long option names is equally easy:
```text

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
'')]
>>> args
['a1', 'a2']
```
In a script, typical usage is something like this:


6.12 getpass -- Portable password input

mutex-objects.html | allos.html | module-curses.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.12 getpass
-- Portable password input
The getpass module provides two functions:


embedding-locale.html | allos.html | node200.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.25 gettext --
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.


module-DEVICE.html | sgi.html | module-imgfile.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.10 GL --
Constants used with the gl module
Availability: IRIX.


20.8 gl -- Graphics Library interface

module-fm.html | sgi.html | module-DEVICE.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.8 gl --
Graphics Library interface
Availability: IRIX.
This module provides access to the Silicon Graphics
Graphics Library.
It is available only on Silicon Graphics machines.
Warning:
Some illegal calls to the GL library cause the Python
interpreter to dump core.
In particular, the use of most GL calls is unsafe before the first
window is opened.
The module is too large to document here in its entirety, but the
following should help you to get started.
The parameter conventions for the C functions are translated to Python as
follows:
- All (short, long, unsigned) int values are represented by Python
integers.
- All float and double values are represented by Python floating point
numbers.
In most cases, Python integers are also allowed.
- All arrays are represented by one-dimensional Python lists.
In most cases, tuples are also allowed.
- All string and character arguments are represented by Python strings,
for instance,
`winopen('Hi There!')`
and
`rotate(900, 'z')`.
- All (short, long, unsigned) integer arguments or return values that are
only used to specify the length of an array argument are omitted.
For example, the C call
```text

lmdef(deftype, index, np, props)
```
is translated to Python as
```text

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
```text

getmcolor(i, &red, &green, &blue)
```
is translated to Python as
```text

red, green, blue = getmcolor(i)
```
The following functions are non-standard or have special argument
conventions:
Here is a tiny but complete example GL program in Python:
```text

import gl, GL, time

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

main()
```
See Also:


module-errno.html | allos.html | module-fnmatch.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.21 glob --
Unix style pathname pattern expansion
The glob module finds all the pathnames matching a specified
pattern according to the rules used by the Unix shell. No tilde
expansion is done, but `*`, `?`, and character ranges
expressed with `[]` will be correctly matched. This is done by
using the os.listdir() and fnmatch.fnmatch()
functions in concert, and not by actually invoking a subshell. (For
tilde and shell variable expansion, use os.path.expanduser()
and os.path.expandvars().)
For example, consider a directory containing only the following files:
1.gif, 2.txt, and card.gif. glob()
will produce the following results. Notice how any leading components
of the path are preserved.
```text

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


ftp-objects.html | internet.html | module-poplib.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 11.8 gopherlib --
Gopher protocol client
This module provides a minimal implementation of client side of the
the Gopher protocol. It is used by the module urllib (module-urllib.html) to
handle URLs that use the Gopher protocol.
The module defines the following functions:


8.3 grp -- The group database

module-pwd.html | unix.html | module-crypt.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.3 grp --
The group database
Availability: Unix.
This module provides access to the Unix group database.
It is available on all Unix versions.
Group database entries are reported as 4-tuples containing the
following items from the group database (see `<grp.h>`), in order:
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:


7.14 gzip -- Support for gzip files

module-zlib.html | someos.html | module-zipfile.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.14 gzip --
Support for gzip files
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:


crypto.html | crypto.html | module-md5.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 15.1 hmac --
Keyed-Hashing for Message Authentication
New in version 2.2.
This module implements the HMAC algorithm as described by RFC 2104 (http://www.faqs.org/rfcs/rfc2104.html).
An HMAC object has the following methods:


html-parser-objects.html | markup.html | module-xml.parsers.expat.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 13.4 htmlentitydefs --
Definitions of HTML general entities
This module defines a single dictionary, `entitydefs`, which is
used by the htmllib (module-htmllib.html) module to provide the
entitydefs member of the HTMLParser class. The
definition provided here contains all the entities defined by HTML 2.0
that can be handled using simple textual substitution in the Latin-1
character set (ISO-8859-1).


module-sgmllib.html | markup.html | html-parser-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 13.3 htmllib --
A parser for HTML documents
This module defines a class which can serve as a base for parsing text
files formatted in the HyperText Mark-up Language (HTML). The class
is not directly concerned with I/O -- it must be provided with input
in string form via a method, and makes calls to methods of a
``formatter'' object in order to produce output. The
HTMLParser class is designed to be used as a base class for
other classes in order to add functionality, and allows most of its
methods to be extended or overridden. In turn, this class is derived
from and extends the SGMLParser class defined in module
sgmllib (module-sgmllib.html). The HTMLParser
implementation supports the HTML 2.0 language as described in
RFC 1866 (http://www.faqs.org/rfcs/rfc1866.html). Two implementations of formatter objects are provided in
the formatter (module-formatter.html)module; refer to the
documentation for that module for information on the formatter
interface.
The following is a summary of the interface defined by
sgmllib.SGMLParser:
- The interface to feed data to an instance is through the feed()
method, which takes a string argument. This can be called with as
little or as much text at a time as desired; "p.feed(a);
p.feed(b)" has the same effect as "p.feed(a+b)". When the data
contains complete HTML tags, these are processed immediately;
incomplete elements are saved in a buffer. To force processing of all
unprocessed data, call the close() method.
For example, to parse the entire contents of a file, use:
```text

parser.feed(open('myfile.html').read())
parser.close()
```
- The interface to define semantics for HTML tags is very simple: derive
a class and define methods called start_tag(),
end_tag(), or do_tag(). The parser will
call these at appropriate moments: start_tag or
do_tag() is called when an opening tag of the form
`< tag ...>` is encountered; end_tag() is called
when a closing tag of the form `< tag >` is encountered. If
an opening tag requires a corresponding closing tag, like `<H1>`
... `</H1>`, the class should define the start_tag()
method; if a tag requires no closing tag, like `<P>`, the class
should define the do_tag() method.
The module defines a single class:
See Also:


markup.html | markup.html | htmlparser-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 13.1 HTMLParser --
Simple HTML and XHTML parser
This module defines a class HTMLParser which serves as the
basis for parsing text files formatted in HTML(HyperText
Mark-up Language) and XHTML. Unlike the parser in
htmllib (module-htmllib.html), this parser is not based on the SGML parser in
sgmllib (module-sgmllib.html).
HTMLParser instances have the following methods:


11.6 httplib -- HTTP protocol client

unknown-handler-objects.html | internet.html | httpconnection-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 11.6 httplib --
HTTP protocol client
This module defines classes which implement the client side of the
HTTP and HTTPS protocols. It is normally not used directly -- the
module urllib (module-urllib.html)uses it to handle URLs
that use HTTP and HTTPS. Note:
HTTPS support is only
available if the socket (module-socket.html) module was compiled with SSL
support.
The constants defined in this module are:
The module provides the following classes:
The following exceptions are raised as appropriate:


module-audioop.html | mmedia.html | module-aifc.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 14.2 imageop --
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-imgfile.html) module.
The module defines the following variables and functions:


11.10 imaplib -- IMAP4 protocol client

pop3-example.html | internet.html | imap4-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 11.10 imaplib --
IMAP4 protocol client
This module defines a class, IMAP4, which encapsulates a
connection to an IMAP4 server and implements a large subset of the
IMAP4rev1 client protocol as defined in RFC 2060 (http://www.faqs.org/rfcs/rfc2060.html). It is backward
compatible with IMAP4 (RFC 1730 (http://www.faqs.org/rfcs/rfc1730.html)) servers, but note that the
"STATUS" command is not supported in IMAP4.
A single class is provided by the imaplib module:
Two exceptions are defined as attributes of the IMAP4 class:
The following utility functions are defined:
Note that IMAP4 message numbers change as the mailbox changes; in
particular, after an "EXPUNGE" command performs deletions the
remaining messages are renumbered. So it is highly advisable to use
UIDs instead, with the UID command.
At the end of the module, there is a test section that contains a more
extensive example of usage.
See Also:
Documents describing the protocol, and sources and binaries
for servers implementing it, can all be found at the
University of Washington's IMAP Information Center
(http://www.cac.washington.edu/imap/).


module-gl-constants.html | sgi.html | module-jpeg.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.11 imgfile --
Support for SGI imglib files
Availability: IRIX.
The imgfile module allows Python programs to access SGI imglib image
files (also known as .rgb files). The module is far from
complete, but is provided anyway since the functionality that there is
is enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:


module-rgbimg.html | mmedia.html | module-sndhdr.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 14.9 imghdr --
Determine the type of an image
The imghdr module determines the type of image contained in a
file or byte stream.
The imghdr module defines the following function:
The following image types are recognized, as listed below with the
return value from what():
You can extend the list of file types imghdr can recognize by
appending to this variable:
Example:


3.21 imp -- Access the import internals

warning-functions.html | python.html | examples-imp.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.21 imp --
Access the import internals
Thismodule provides an interface to the mechanisms
used to implement the import statement. It defines the
following constants and functions:
The following constants with integer values, defined in this module,
are used to indicate the search result of find_module().
The following constant and functions are obsolete; their functionality
is available through find_module() or load_module().
They are kept around for backward compatibility:


3.11 inspect -- Inspect live objects

operator-map.html | python.html | inspect-types.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.11 inspect --
Inspect 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.


20.12 jpeg -- Read and write JPEG files

module-imgfile.html | sgi.html | sunos.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20.12 jpeg --
Read and write JPEG files
Availability: IRIX.
The module jpeg provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group
(IJG). JPEG is a standard for
compressing pictures; it is defined in ISO 10918. For details on JPEG
or the Independent JPEG Group software refer to the JPEG standard or
the documentation provided with the software.
A portable interface to JPEG image files is available with the Python
Imaging Library (PIL) by Fredrik Lundh. Information on PIL is
available at http://www.pythonware.com/products/pil/.
The jpeg module defines an exception and some functions.
See Also:


module-token.html | language.html | module-tokenize.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 18.4 keyword --
Testing for Python keywords
This module allows a Python program to determine if a string is a
keyword. A single function is provided:


traceback-example.html | python.html | module-pickle.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.13 linecache --
Random access to text lines
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-traceback.html) module to retrieve source lines for inclusion in
the formatted traceback.
The linecache module defines the following functions:
Example:


shutil-example.html | allos.html | node197.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.24 locale --
Internationalization services
The locale module opens access to the POSIX locale
database and functionality. The POSIX 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
_localemodule, which in turn uses an
ANSI C locale implementation if available.
The locale module defines the following exception and
functions:
The nl_langinfo function accepts one of the following keys.
Most descriptions are taken from the corresponding description in the
GNU C library.
Example:
```text

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL) # get current locale
>>> locale.setlocale(locale.LC_ALL, 'de') # use German locale
>>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
```


module-mailcap.html | netdata.html | mailbox-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.4 mailbox --
Read various mailbox formats
This module defines a number of classes that allow easy and uniform
access to mail messages in a (Unix) mailbox.
See Also:


12.3 mailcap -- Mailcap file handling.

node389.html | netdata.html | module-mailbox.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.3 mailcap --
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 %s". Then, if the user encounters an email
message or Web document with the MIME type video/mpeg,
"%s" will be replaced by a filename (usually one belonging to a
temporary file) and the xmpeg program can be automatically
started to view the file.
The mailcap format is documented in RFC 1524 (http://www.faqs.org/rfcs/rfc1524.html), ``A User Agent
Configuration Mechanism For Multimedia Mail Format Information,'' but
is not an Internet standard. However, mailcap files are supported on
most Unix systems.


module-builtin.html | python.html | strings.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.30 __main__ --
Top-level script environment
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes -- commands read either from
standard input, from a script file, or from an interactive prompt. It
is this environment in which the idiomatic ``conditional script''
stanza causes a script to run:
```text

if __name__ == "__main__":
main()
```


module-copy.html | python.html | module-warnings.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.19 marshal --
Internal Python object serialization
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).3.14 (#foot7455)
This is not a general ``persistence'' module. For general persistence
and transfer of Python objects through RPC calls, see the modules
pickle (module-pickle.html) and shelve (module-shelve.html). 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. There
may also be unknown security problems with
marshal3.15 (#foot7508).
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:


5.4 math -- Mathematical functions

testloader-objects.html | misc.html | module-cmath.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 5.4 math --
Mathematical functions
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-cmath.html) 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 provided by this module:
Note that frexp() and modf() have a different
call/return pattern than their C equivalents: they take a single
argument and return a pair of values, rather than returning their
second return value through an `output parameter' (there is no such
thing in Python).
The module also defines two mathematical constants:


module-hmac.html | crypto.html | module-sha.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 15.2 md5 --
MD5 message digest algorithm
This module implements the interface to RSA's MD5 message digest
algorithm (see also Internet RFC 1321 (http://www.faqs.org/rfcs/rfc1321.html)). Its use is quite
straightforward: use new() to create an md5 object.
You can now feed this object with arbitrary strings using the
update() method, and at any point you can ask it for the
digest (a strong kind of 128-bit checksum,
a.k.a. ``fingerprint'') of the concatenation of the strings fed to it
so far using the digest() method.
For example, to obtain the digest of the string `'Nobody inspects
the spammish repetition'`:
```text

>>> import md5
>>> m = md5.new()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
```
More condensed:
```text

>>> md5.new("Nobody inspects the spammish repetition").digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
```
The following values are provided as constants in the module and as
attributes of the md5 objects returned by new():
md5 objects support the following methods:
An md5 object has the following methods:


12.5 mhlib -- Access to MH mailboxes

mailbox-objects.html | netdata.html | mh-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.5 mhlib --
Access to MH mailboxes
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.


mh-message-objects.html | netdata.html | mimetools-message-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.6 mimetools --
Tools for parsing MIME messages
This module defines a subclass of the
rfc822 (module-rfc822.html)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:
See Also:


mimetools-message-objects.html | netdata.html | mimetypes-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.7 mimetypes --
Map filenames 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.
Some additional functions and data items are available for controlling
the behavior of the module.
The MimeTypes class may be useful for applications which may
want more than one MIME-type database:


mimetypes-objects.html | netdata.html | MimeWriter-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.8 MimeWriter --
Generic MIME file writer
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.


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

unmimify message
edit message
mimify message
send message
```
The modules defines the following user-callable functions and
user-settable variables:
This module can also be used from the command line. Usage is as
follows:
```text

mimify.py -e [-l length] [infile [outfile]]
mimify.py -d [-b] [infile [outfile]]
```
to encode (mimify) and decode (unmimify) respectively. infile
defaults to standard input, outfile defaults to standard output.
The same file can be specified for input and output.
If the -l option is given when encoding, if there are any lines
longer than the specified length, the containing part will be
encoded.
If the -b option is given when decoding, any base64 parts will
be decoded as well.


7.7 mmap --
Memory-mapped file support

QueueObjects.html | someos.html | module-anydbm.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.7 mmap --
Memory-mapped file support
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 Unix 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 Unix 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 Unix 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.
Memory-mapped file objects support the following methods:


module-sha.html | crypto.html | module-rotor.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 15.4 mpz --
GNU arbitrary magnitude integers
Deprecated since release 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.
This module implements the interface to part of the GNU MP library,
which defines arbitrary precision integer and rational number
arithmetic routines. Only the interfaces to the integer
(mpz_*()) routines are provided. If not stated
otherwise, the description in the GNU MP documentation can be applied.
Support for rational numberscan be
implemented in Python. For an example, see the
Rat module, provided as
Demos/classes/Rat.py in the Python source distribution.
In general, mpz-numbers can be used just like other standard
Python numbers, e.g., you can use the built-in operators like `+`,
`*`, etc., as well as the standard built-in functions like
abs(), int(), ..., divmod(),
pow(). Please note: the bitwise-xor
operation has been implemented as a bunch of ands,
inverts and ors, because the library lacks an
mpz_xor() function, and I didn't need one.
You create an mpz-number by calling the function mpz() (see
below for an exact description). An mpz-number is printed like this:
`mpz( value )`.
A number of extra functions are defined in this module. Non
mpz-arguments are converted to mpz-values first, and the functions
return mpz-numbers.
An mpz-number has one method:


node604.html | node604.html | msvcrt-files.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 22.1 msvcrt -
Useful routines from the MS VC++ runtime
Availability: Windows.
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-getpass.html) module uses this in the implementation of the
getpass() function.
Further documentation on these functions can be found in the Platform
API documentation.


module-mimify.html | netdata.html | MultiFile-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.10 multifile --
Support for files containing distinct parts
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.
It will be useful to know that in MultiFile's view of the world, text
is composed of three kinds of lines: data, section-dividers, and
end-markers. MultiFile is designed to support parsing of
messages that may have multiple nested message parts, each with its
own pattern for section-divider and end-marker lines.


6.11 mutex -- Mutual exclusion support

scheduler-objects.html | allos.html | mutex-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.11 mutex --
Mutual exclusion support
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:


12.18 netrc -- netrc file processing

xdr-exceptions.html | netdata.html | netrc-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.18 netrc --
netrc file processing
New in version 1.5.2.
The netrc class parses and encapsulates the netrc file format
used by the Unix ftp program and other FTP clients.


subclassing-reprs.html | python.html | module-site.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.26 new --
Creation of runtime internal 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:


node273.html | unix.html | module-syslog.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.16 nis --
Interface to Sun's NIS (Yellow Pages)
Availability: UNIX.
The nis module gives a thin wrapper around the NIS library, useful
for central administration of several hosts.
Because NIS exists only on Unix systems, this module is
only available for Unix.
The nis module defines the following functions:
The nis module defines the following exception:


11.11 nntplib -- NNTP protocol client

imap4-example.html | internet.html | nntp-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 11.11 nntplib --
NNTP protocol client
This module defines the class NNTP which implements the client
side of the NNTP protocol. It can be used to implement a news reader
or poster, or automated news processors. For more information on NNTP
(Network News Transfer Protocol), see Internet RFC 977 (http://www.faqs.org/rfcs/rfc977.html).
Here are two small examples of how it can be used. To list some
statistics about a newsgroup and print the subjects of the last 10
articles:
```text

>>> s = NNTP('news.cwi.nl')
>>> resp, count, first, last, name = s.group('comp.lang.python')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
Group comp.lang.python has 59 articles, range 3742 to 3803
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
3792 Re: Removing elements from a list while iterating...
3793 Re: Who likes Info files?
3794 Emacs and doc strings
3795 a few questions about the Mac implementation
3796 Re: executable python scripts
3797 Re: executable python scripts
3798 Re: a few questions about the Mac implementation
3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
3802 Re: executable python scripts
3803 Re: \POSIX{} wait and SIGCHLD
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
```
To post an article from a file (this assumes that the article has
valid headers):
```text

>>> s = NNTP('news.cwi.nl')
>>> f = open('/tmp/article')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
```
The module itself defines the following items:


module-UserString.html | python.html | operator-map.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.10 operator --
Standard operators as 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:
The logical operations are also generally applicable to all objects,
and support truth tests and Boolean operations:
The mathematical and bitwise operations are the most numerous:
Operations which work with sequences include:
The operator module also defines a few predicates to test the
type of objects. Note:
Be careful not to misinterpret the
results of these functions; only isCallable() has any
measure of reliability with instance objects. For example:
```text

>>> class C:
... pass
...
>>> import operator
>>> o = C()
>>> operator.isMappingType(o)
1
```
Example: Build a dictionary that maps the ordinals from `0` to
`256` to their character equivalents.
```text

>>> import operator
>>> d = {}
>>> keys = range(256)
>>> vals = map(chr, keys)
>>> map(operator.setitem, [d]*len(keys), keys, vals)
```


allos.html | allos.html | os-procinfo.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.1 os --
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 (module-posix.html) or nt.
This module searches for an operating system dependent built-in module like
mac or posix (module-posix.html) 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
POSIX 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!
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.


os-path.html | allos.html | module-dircache.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.2 os.path --
Common pathname manipulations
This module implements some useful functions on pathnames.
Warning:
On Windows, many of these functions do not properly
support UNC pathnames. splitunc() and ismount()
do handle them correctly.


language.html | language.html | node551.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 18.1 parser --
Access Python parse trees
The parser module provides an interface to Python's internal
parser and byte-code compiler. The primary purpose for this interface
is to allow Python code to edit the parse tree of a Python expression
and create executable code from this. This is better than trying
to parse and modify an arbitrary Python code fragment as a string
because parsing is performed in a manner identical to the code
forming the application. It is also faster.
There are a few things to note about this module which are important
to making use of the data structures created. This is not a tutorial
on editing the parse trees for Python code, but some examples of using
the parser module are presented.
Most importantly, a good understanding of the Python grammar processed
by the internal parser is required. For full information on the
language syntax, refer to the Python
Language Reference (../ref/ref.html). The parser itself is created from a grammar
specification defined in the file Grammar/Grammar in the
standard Python distribution. The parse trees stored in the AST
objects created by this module are the actual output from the internal
parser when created by the expr() or suite()
functions, described below. The AST objects created by
sequence2ast() faithfully simulate those structures. Be
aware that the values of the sequences which are considered
``correct'' will vary from one version of Python to another as the
formal grammar for the language is revised. However, transporting
code from one Python version to another as source text will always
allow correct parse trees to be created in the target version, with
the only restriction being that migrating to an older version of the
interpreter will not support more recent language constructs. The
parse trees are not typically compatible from one version to another,
whereas source code has always been forward-compatible.
Each element of the sequences returned by ast2list() or
ast2tuple() has a simple form. Sequences representing
non-terminal elements in the grammar always have a length greater than
one. The first element is an integer which identifies a production in
the grammar. These integers are given symbolic names in the C header
file Include/graminit.h and the Python module
symbol (module-symbol.html). Each additional element of the sequence represents
a component of the production as recognized in the input string: these
are always sequences which have the same form as the parent. An
important aspect of this structure which should be noted is that
keywords used to identify the parent node type, such as the keyword
if in an if_stmt, are included in the node tree without
any special treatment. For example, the if keyword is
represented by the tuple `(1, 'if')`, where `1` is the
numeric value associated with all NAME tokens, including
variable and function names defined by the user. In an alternate form
returned when line number information is requested, the same token
might be represented as `(1, 'if', 12)`, where the `12`
represents the line number at which the terminal symbol was found.
Terminal elements are represented in much the same way, but without
any child elements and the addition of the source text which was
identified. The example of the if keyword above is
representative. The various types of terminal symbols are defined in
the C header file Include/token.h and the Python module
token (module-token.html).
The AST objects are not required to support the functionality of this
module, but are provided for three purposes: to allow an application
to amortize the cost of processing complex parse trees, to provide a
parse tree representation which conserves memory space when compared
to the Python list or tuple representation, and to ease the creation
of additional modules in C which manipulate parse trees. A simple
``wrapper'' class may be created in Python to hide the use of AST
objects.
The parser module defines functions for a few distinct
purposes. The most important purposes are to create AST objects and
to convert AST objects to other representations such as parse trees
and compiled code objects, but there are also functions which serve to
query the type of parse tree represented by an AST object.
See Also:


9. The Python Debugger

module-commands.html | lib.html | debugger-commands.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 9. The Python Debugger
The module pdb defines an interactive source code
debuggerfor Python programs. It supports setting
(conditional) breakpoints and single stepping at the source line
level, inspection of stack frames, source code listing, and evaluation
of arbitrary Python code in the context of any stack frame. It also
supports post-mortem debugging and can be called under program
control.
The debugger is extensible -- it is actually defined as the class
Pdb.
This is currently undocumented but easily understood by reading the
source. The extension interface uses the modules
bdb(undocumented) and
cmd (module-cmd.html).
The debugger's prompt is "(Pdb) ".
Typical usage to run a program under control of the debugger is:
```text

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)
```
pdb.py can also be invoked as
a script to debug other scripts. For example:
```text

python /usr/local/lib/python1.5/pdb.py myscript.py
```
Typical usage to inspect a crashed program is:
```text

>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "./mymodule.py", line 4, in test
test2()
File "./mymodule.py", line 3, in test2
print spam
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print spam
(Pdb)
```
The module defines the following functions; each enters the debugger
in a slightly different way:


module-linecache.html | python.html | node59.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.14 pickle -- Python object serialization
The pickle module implements a fundamental, but powerful
algorithm for serializing and de-serializing a Python object
structure. ``Pickling'' is the process whereby a Python object
hierarchy is converted into a byte stream, and ``unpickling'' is the
inverse operation, whereby a byte stream is converted back into an
object hierarchy. Pickling (and unpickling) is alternatively known as
``serialization'', ``marshalling,''3.2 (#foot6912) or ``flattening'',
however the preferred term used here is ``pickling'' and
``unpickling'' to avoid confusing.
This documentation describes both the pickle module and the
cPickle (module-cPickle.html) module.
---
#### Footnotes


module-fcntl.html | unix.html | template-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.13 pipes --
Interface to shell pipelines
Availability: Unix.
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 POSIX or
compatible shell for os.system() and os.popen()
is required.
The pipes module defines the following class:
Example:
```text

>>> import pipes
>>> t=pipes.Template()
>>> t.append('tr a-z A-Z', '--')
>>> f=t.open('/tmp/1', 'w')
>>> f.write('hello world')
>>> f.close()
>>> open('/tmp/1').read()
'HELLO WORLD'
```


dircmp-objects.html | allos.html | popen3-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.8 popen2 --
Subprocesses with accessible I/O streams
Availability: Unix, Windows.
This module allows you to spawn processes and connect to their
input/output/error pipes and obtain their return codes under
Unix and Windows.
Note that starting with Python 2.0, this functionality is available
using functions from the os (module-os.html) 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-os.html) 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
Unix. This information is not available when using the
popen2(), popen3(), and popen4()
functions, or the equivalent functions in the os (module-os.html) module.
On Unix, a class defining the objects returned by the factory
functions is also available. These are not used for the Windows
implementation, and are not available on that platform.


11.9 poplib -- POP3 protocol client

module-gopherlib.html | internet.html | pop3-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 11.9 poplib --
POP3 protocol client
This module defines a class, POP3, which encapsulates a
connection to an POP3 server and implements the protocol as defined in
RFC 1725 (http://www.faqs.org/rfcs/rfc1725.html). The POP3 class supports both the minimal and
optional command sets.
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:
One exception is defined as an attribute of the poplib module:
See Also:


unix.html | unix.html | posix-large-files.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.1 posix --
The most common POSIX system calls
Availability: Unix.
This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly
disguised Unix interface).
Do not import this module directly. Instead, import the
module os (module-os.html), which provides a portable version of this
interface. On Unix, the os (module-os.html) module provides a superset of
the posix interface. On non-Unix operating systems the
posix module is not available, but a subset is always
available through the os (module-os.html) interface. Once os (module-os.html) is
imported, there is no performance penalty in using it instead
of posix. In addition, os (module-os.html)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
Unix manual (or POSIX 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.


template-objects.html | unix.html | module-resource.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.14 posixfile --
File-like objects with locking support
Availability: Unix.
Deprecated since release 1.5.
The locking operation that this module provides is
done better and more portably by the
fcntl (module-fcntl.html).lockf() call.
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
Unix, since it uses fcntl.fcntl() for file locking.
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:
The posixfile module defines the following functions:
The posixfile object defines the following additional methods:
All methods raise IOError when the request fails.
Format characters for the lock() method have the following
meaning:
In addition the following modifiers can be added to the format:
Note:
(1): The lock returned is in the format `( mode , len , start , whence , pid )` where mode is a character
representing the type of lock ('r' or 'w'). This modifier prevents a
request from being granted; it is for query purposes only.
Format characters for the flags() method have the following
meanings:
In addition the following modifiers can be added to the format:
Notes:
(1): The "!" and "=" modifiers are mutually exclusive.
(2): This string represents the flags after they may have been altered
by the same call.
Examples:


3.24 pprint -- Data pretty printer

module-codeop.html | python.html | node85.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.24 pprint --
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:
The PrettyPrinter class supports several derivative functions:
One more support function is also defined:
```text

>>> pprint.saferepr(stuff)
"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
```


10.5 Reference Manual

node284.html | profile.html | profile-stats.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 10.5 Reference Manual
The primary entry point for the profiler is the global function
profile.run(). It is typically used to create any profile
information. The reports are formatted and printed using methods of
the class pstats.Stats. The following is a description of all
of these standard entry points and functions. For a more in-depth
view of some of the code, consider reading the later section on
Profiler Extensions, which includes discussion of how to derive
``better'' profilers from the classes presented, or reading the source
code for these modules.
Analysis of the profiler data is done using this class from the
pstats module:


8.11 pty -- Pseudo-terminal utilities

module-tty.html | unix.html | module-fcntl.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.11 pty --
Pseudo-terminal utilities
Availability: IRIX, 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:


8.2 pwd -- The password database

posix-contents.html | unix.html | module-grp.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.2 pwd --
The password database
Availability: Unix.
This module provides access to the Unix user account and password
database. It is available on all Unix versions.
Password database entries are reported as 7-tuples containing the
following items from the password database (see `<pwd.h>`), in order:
The uid and gid items are integers, all others are strings.
KeyError is raised if the entry asked for cannot be found.
Note:
In traditional Unix the field `pw_passwd` usually
contains a password encrypted with a DES derived algorithm (see module
crypt (module-crypt.html)). 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:


module-tabnanny.html | language.html | pyclbr-class-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 18.7 pyclbr --
Python class browser support
The pyclbr can be used to determine some limited information
about the classes and methods 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 from an imported 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.


pyclbr-class-objects.html | language.html | module-compileall.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 18.8 py_compile --
Compile Python source files
The py_compile module provides a single function to generate
a byte-code file from a source file.
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.


misc.html | misc.html | module-doctest.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 5.1 pydoc --
Documentation generator and online help system
New in version 2.1.
The pydoc module automatically generates documentation from
Python modules. The documentation can be presented as pages of text
on the console, served to a Web browser, or saved to HTML files.
The built-in function help() invokes the online help system
in the interactive interpreter, which uses pydoc to generate
its documentation as text on the console. The same text documentation
can also be viewed from outside the Python interpreter by running
pydoc as a script at the operating system's command prompt.
For example, running
```text

pydoc sys
```
at a shell prompt will display documentation on the sys (module-sys.html)
module, in a style similar to the manual pages shown by the Unix
man command. The argument to pydoc can be the name
of a function, module, or package, or a dotted reference to a class,
method, or function within a module or module in a package. If the
argument to pydoc looks like a path (that is, it contains the
path separator for your operating system, such as a slash in Unix),
and refers to an existing Python source file, then documentation is
produced for that file.
Specifying a -w flag before the argument will cause HTML
documentation to be written out to a file in the current directory,
instead of displaying text on the console.
Specifying a -k flag before the argument will search the
synopsis lines of all available modules for the keyword given as the
argument, again in a manner similar to the Unix man
command. The synopsis line of a module is the first line of its
documentation string.
You can also use pydoc to start an HTTP server on the local
machine that will serve documentation to visiting Web browsers.
pydoc -p 1234 will start a HTTP server on port
1234, allowing you to browse the documentation at
`http://localhost:1234/` in your preferred Web browser.
pydoc -g will start the server and additionally
bring up a small Tkinter (module-Tkinter.html)-based graphical interface to help
you search for documentation pages.


7.6 Queue -- A synchronized queue class

timer-objects.html | someos.html | QueueObjects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.6 Queue --
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.
The Queue module defines the following class and exception:


binhex-notes.html | netdata.html | module-uu.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.15 quopri --
Encode and decode MIME quoted-printable data
This module performs quoted-printable transport encoding and decoding,
as defined in RFC 1521 (http://www.faqs.org/rfcs/rfc1521.html): ``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-base64.html) module is more compact if there are many such
characters, as when sending a graphics file.


module-cmath.html | misc.html | module-whrandom.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 5.6 random --
Generate pseudo-random numbers
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, and a function to
generate a random permutation of a list in-place.
On the real line, there are functions to compute uniform, normal (Gaussian),
lognormal, negative exponential, gamma, and beta distributions.
For generating distribution of angles, the circular uniform and
von Mises distributions are 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 standard Wichmann-Hill
generator, combining three pure multiplicative congruential
generators of modulus 30269, 30307 and 30323. Its period (how many
numbers it generates before repeating the sequence exactly) is
6,953,607,871,644. While of much higher quality than the rand()
function supplied by most C libraries, the theoretical properties
are much the same as for a single linear congruential generator of
large modulus. It is not suitable for all purposes, and is completely
unsuitable for cryptographic purposes.
The functions in this module are not threadsafe: if you want to call these
functions from multiple threads, you should explicitly serialize the calls.
Else, because no critical sections are implemented internally, calls
from different threads may see the same return values.
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 (see example
below).
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.
Here's one way to create threadsafe distinct and non-overlapping generators:
```text

def create_generators(num, delta, firstseed=None):
"""Return list of num distinct generators.
Each generator has its own unique segment of delta elements
from Random.random()'s full period.
Seed the first generator with optional arg firstseed (default
is None, to seed from current time).
"""

from random import Random
g = Random(firstseed)
result = [g]
for i in range(num - 1):
laststate = g.getstate()
g = Random()
g.setstate(laststate)
g.jumpahead(delta)
result.append(g)
return result

gens = create_generators(10, 1000000)
```
That creates 10 distinct generators, which can be passed out to 10
distinct threads. The generators don't share state so can be called
safely in parallel. So long as no thread calls its `g.random()`
more than a million times (the second argument to
create_generators(), the sequences seen by each thread will
not overlap. The period of the underlying Wichmann-Hill generator
limits how far this technique can be pushed.
Just for fun, note that since we know the period, jumpahead()
can also be used to ``move backward in time:''
```text

>>> g = Random(42) # arbitrary
>>> g.random()
0.25420336316883324
>>> g.jumpahead(6953607871644L - 1) # move *back* one
>>> g.random()
0.25420336316883324
```
Bookkeeping functions:
Functions for integers:
Functions for sequences:
The following functions generate specific real-valued distributions.
Function parameters are named after the corresponding variables in the
distribution's equation, as used in common mathematical practice; most of
these equations can be found in any statistics text.


4.2 re -- Regular expression operations

module-string.html | strings.html | re-syntax.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 4.2 re --
Regular expression operations
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
`'\\\\'` as the pattern string, because the regular expression
must be "\\", and each backslash must be expressed as
"\\" 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"\n"` is a
two-character string containing "\" and "n",
while `"\n"` is a one-character string containing a newline.
Usually patterns will be expressed in Python code using this raw
string notation.
Implementation note:
The remodule has two distinct
implementations: sre is the default implementation and
includes Unicode support, but may run into stack limitations for some
patterns. Though this will be fixed for a future release of Python,
the older implementation (without Unicode support) is still available
as the premodule.
See Also:


7.16 readline -- GNU readline interface

zipinfo-objects.html | someos.html | readline-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.16 readline --
GNU readline interface
Availability: Unix.
The readline module defines a number of functions used either
directly or from the rlcompleter (module-rlcompleter.html) module to facilitate
completion and history file read and write from the Python
interpreter.
The readline module defines the following functions:
See Also:


node85.html | python.html | Repr-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.25 repr --
Alternate repr() implementation
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:


module-posixfile.html | unix.html | node272.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 8.15 resource --
Resource usage information
Availability: Unix.
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:


restricted.html | restricted.html | rexec-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 17.1 rexec --
Restricted execution framework
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.
Note:
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.
It is important to be aware that code running in a restricted
environment can still call the sys.exit() function. To
disallow restricted code from exiting the interpreter, always protect
calls that cause restricted code to run with a
try/except statement that catches the
SystemExit exception. Removing the sys.exit()
function from the restricted environment is not sufficient -- the
restricted code could still use `raise SystemExit`. Removing
SystemExit is not a reasonable option; some library code
makes use of this and would break were it not available.
See Also:


multifile-example.html | netdata.html | message-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.11 rfc822 --
Parse RFC 2822 mail headers
This module defines a class, Message, which represents an
``email message'' as defined by the Internet standard
RFC 2822 (http://www.faqs.org/rfcs/rfc2822.html).12.6 (#foot38387) Such messages
consist of a collection of message headers, and a message body. This
module also defines a helper class
AddressList for parsing RFC 2822 (http://www.faqs.org/rfcs/rfc2822.html) addresses. Please refer to
the RFC for information on the specific syntax of RFC 2822 (http://www.faqs.org/rfcs/rfc2822.html) messages.
The mailbox (module-mailbox.html)module provides classes
to read mailboxes produced by various end-user mail programs.
See Also:
---
#### Footnotes


module-colorsys.html | mmedia.html | module-imghdr.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 14.8 rgbimg --
Read and write ``SGI RGB'' files
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.
Note:
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:


readline-example.html | someos.html | completer-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.17 rlcompleter --
Completion function for GNU readline
Availability: Unix.
The rlcompleter module defines a completion function for
the readline (module-readline.html) module by completing valid Python identifiers
and keywords.
This module is Unix-specific due to its dependence on the
readline (module-readline.html) module.
The rlcompleter module defines the Completer class.
Example:
```text

>>> import rlcompleter
>>> import readline
>>> readline.parse_and_bind("tab: complete")
>>> readline. <TAB PRESSED>
readline.__doc__ readline.get_line_buffer readline.read_init_file
readline.__file__ readline.insert_text readline.set_completer
readline.__name__ readline.parse_and_bind
>>> 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:
```text

try:
import readline
except ImportError:
print "Module readline not available."
else:
import rlcompleter
readline.parse_and_bind("tab: complete")
```


netrc-objects.html | netdata.html | markup.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12.19 robotparser --
Parser for robots.txt
This module provides a single class, RobotFileParser, which answers
questions about whether or not a particular user agent can fetch a URL on
the Web site that published the robots.txt file. For more details on
the structure of robots.txt files, see
http://info.webcrawler.com/mak/projects/robots/norobots.html.
The following example demonstrates basic use of the RobotFileParser class.
```text

>>> import robotparser
>>> rp = robotparser.RobotFileParser()
>>> rp.set_url("http://www.musi-cal.com/robots.txt")
>>> rp.read()
>>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
0
>>> rp.can_fetch("*", "http://www.musi-cal.com/")
1
```


module-mpz.html | crypto.html | tkinter.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 15.5 rotor --
Enigma-like encryption and decryption
This module implements a rotor-based encryption algorithm, contributed by
Lance Ellinghouse. The design is derived
from the Enigma device, a machine
used during World War II to encipher messages. A rotor is simply a
permutation. For example, if the character `A' is the origin of the rotor,
then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
To encrypt, we choose several different rotors, and set the origins of the
rotors to known positions; their initial position is the ciphering key. To
encipher a character, we permute the original character by the first rotor,
and then apply the second rotor's permutation to the result. We continue
until we've applied all the rotors; the resulting character is our
ciphertext. We then change the origin of the final rotor by one position,
from `A' to `B'; if the final rotor has made a complete revolution, then we
rotate the next-to-last rotor by one position, and apply the same procedure
recursively. In other words, after enciphering one character, we advance
the rotors in the same fashion as a car's odometer. Decoding works in the
same way, except we reverse the permutations and apply them in the opposite
order.
The available functions in this module are:
Rotor objects have the following methods:
An example usage:
```text

>>> import rotor
>>> rt = rotor.newrotor('key', 12)
>>> rt.encrypt('bar')
'\xab4\xf3'
>>> rt.encryptmore('bar')
'\xef\xfd$'
>>> rt.encrypt('bar')
'\xab4\xf3'
>>> rt.decrypt('\xab4\xf3')
'bar'
>>> rt.decryptmore('\xef\xfd$')
'bar'
>>> rt.decrypt('\xef\xfd$')
'l(\xcd'
>>> del rt
```
The module's code is not an exact simulation of the original Enigma
device; it implements the rotor encryption scheme differently from the
original. The most important difference is that in the original
Enigma, there were only 5 or 6 different rotors in existence, and they
were applied twice to each character; the cipher key was the order in
which they were placed in the machine. The Python rotor
module uses the supplied key to initialize a random number generator;
the rotor permutations and their initial positions are then randomly
generated. The original device only enciphered the letters of the
alphabet, while this module can handle any 8-bit binary data; it also
produces binary output. This module can also operate with an
arbitrary number of rotors.
The original Enigma cipher was broken in 1944. The version implemented here is probably a good deal more difficult to crack
(especially if you use many rotors), but it won't be impossible for
a truly skillful and determined attacker to break the cipher. So if you want
to keep the NSA out of your files, this rotor cipher may well be unsafe, but
for discouraging casual snooping through your files, it will probably be
just fine, and may be somewhat safer than using the Unix crypt
command.


6.10 sched -- Event scheduler

module-time.html | allos.html | scheduler-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 6.10 sched --
Event scheduler
The sched module defines a class which implements a general
purpose event scheduler:
Example:
```text

>>> import sched, time
>>> s=sched.scheduler(time.time, time.sleep)
>>> def print_time(): print "From print_time", time.time()
...
>>> def print_some_times():
... print time.time()
... s.enter(5, 1, print_time, ())
... s.enter(10, 1, print_time, ())
... s.run()
... print time.time()
...
>>> print_some_times()
930343690.257
From print_time 930343695.274
From print_time 930343700.273
930343700.276
```


node527.html | tkinter.html | module-turtle.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 16.3 ScrolledText --
Scrolled Text Widget
Availability: Tk.
The ScrolledText module provides a class of the same name
which implements a basic text widget which has a vertical scroll bar
configured to do the ``right thing.'' Using the ScrolledText
class is a lot easier than setting up a text widget and scroll bar
directly. The constructor is the same as that of the
Tkinter.Text class.
The text widget and scrollbar are packed together in a Frame,
and the methods of the Grid and Pack geometry managers
are acquired from the Frame object. This allows the
ScrolledText widget to be used directly to achieve most normal
geometry management behavior.
Should more specific control be necessary, the following attributes
are available:


socket-example.html | someos.html | poll-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.3 select --
Waiting for I/O completion
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 Unix, 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:


13.2 sgmllib -- Simple SGML parser

htmlparser-example.html | markup.html | module-htmllib.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 13.2 sgmllib --
Simple SGML parser
This module defines a class SGMLParser which serves as the
basis for parsing text files formatted in SGML (Standard Generalized
Mark-up Language). In fact, it does not provide a full SGML parser
-- it only parses SGML insofar as it is used by HTML, and the module
only exists as a base for the htmllib (module-htmllib.html) module. Another
HTML parser which supports XHTML and offers a somewhat different
interface is available in the HTMLParser (module-HTMLParser.html) module.
SGMLParser instances have the following interface methods:
Apart from overriding or extending the methods listed above, derived
classes may also define methods of the following form to define
processing of specific tags. Tag names in the input stream are case
independent; the tag occurring in method names must be in lower
case:


module-md5.html | crypto.html | module-mpz.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 15.3 sha --
SHA message digest algorithm
This module implements the interface to NIST'ssecure hash
algorithm,known as SHA. It is used in
the same way as the md5 (module-md5.html) module: use new()
to create an sha object, then feed this object with arbitrary strings
using the update() method, and at any point you can ask it
for the digest of the concatenation of the strings fed to it
so far. SHA digests are 160 bits instead of
MD5's 128 bits.
The following values are provided as constants in the module and as
attributes of the sha objects returned by new():
An sha object has the same methods as md5 objects:


module-copyreg.html | python.html | module-copy.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 3.17 shelve --
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-pickle.html) module can handle. This includes most class
instances, recursive data types, and objects containing lots of shared
sub-objects. The keys are ordinary strings.
To summarize the interface (`key` is a string, `data` is an
arbitrary object):
```text

import shelve

d = shelve.open(filename) # open, with (g)dbm filename -- no suffix

d[key] = data # store data at key (overwrites old data if
# using an existing key)
data = d[key] # retrieve data at key (raise KeyError if no
# such key)
del d[key] # delete data stored at key (raises KeyError
# if no such key)
flag = d.has_key(key) # true if the key exists
list = d.keys() # a list of all existing keys (slow!)

d.close() # close it
```
Restrictions:
- The choice of which database package will be used
(e.g. dbm (module-dbm.html) or gdbm (module-gdbm.html)) depends on which interface
is available. Therefore it is not safe to open the database directly
using dbm (module-dbm.html). The database is also (unfortunately) subject
to the limitations of dbm (module-dbm.html), 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.
- Dependent on the implementation, closing a persistent dictionary may
or may not be necessary to flush changes to disk.
- 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. Unix file locking can
be used to solve this, but this differs across Unix versions and
requires knowledge about the database implementation used.


5.15 shlex -- Simple lexical analysis

Cmd-objects.html | misc.html | shlex-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 5.15 shlex --
Simple lexical analysis
New in version 1.5.2.
The shlex class makes it easy to write lexical analyzers for
simple syntaxes resembling that of the Unix shell. This will often
be useful for writing minilanguages, e.g. in run control files for
Python applications.
See Also: