bsddb-objects.html | someos.html | module-gzip.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 7.14 zlib --
Compression compatible with gzip
For applications that require data compression, the functions in this
module allow compression and decompression, using the zlib library.
The zlib library has its own home page at
http://www.info-zip.org/pub/infozip/zlib/. Version 1.1.3 is the
most recent version as of September 2000; use a later version if one
is available. There are known incompatibilities between the Python
module and earlier versions of the zlib library.
The available exception and functions in this module are:
Compression objects support the following methods:
Decompression objects support the following methods, and a single attribute:


11.17.2 Morsel Objects

cookie-objects.html | module-Cookie.html | cookie-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.17.2 Morsel Objects
.


20.1.2 Console I/O

msvcrt-files.html | module-msvcrt.html | msvcrt-other.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 20.1.2 Console I/O


20.1.1 File Operations

module-msvcrt.html | module-msvcrt.html | msvcrt-console.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 20.1.1 File Operations


20.1.3 Other Functions

msvcrt-console.html | module-msvcrt.html | module--winreg.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 20.1.3 Other Functions


12.5.2 MultiFile Example

MultiFile-objects.html | module-multifile.html | module-binhex.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 12.5.2 MultiFile Example


12.5.1 MultiFile Objects

module-multifile.html | module-multifile.html | multifile-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 12.5.1 MultiFile Objects
A MultiFile instance has the following methods:
Finally, MultiFile instances have two public instance variables:


7.6.1 Mutex Objects

module-mutex.html | module-mutex.html | module-Queue.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 7.6.1 Mutex Objects
mutex objects have following methods:


12. Internet Data Handling

asyncore-example.html | lib.html | module-formatter.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 12. Internet Data Handling
This chapter describes modules which support handling data formats
commonly used on the internet. Some, like SGML and XML, may be useful
for other applications as well.


12.17.1 netrc Objects

module-netrc.html | module-netrc.html | module-robotparser.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 12.17.1 netrc Objects
A netrc instance has the following methods:
Instances of netrc have public instance variables:


11.9.1 NNTP Objects

module-nntplib.html | module-nntplib.html | module-smtplib.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.9.1 NNTP Objects
NNTP instances have the following methods. The response that is
returned as the first item in the return tuple of almost all methods
is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.


6.12.3 Constants

curses-window-objects.html | module-curses.html | module-curses.textpad.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.12.3 Constants
The curses module defines the following data members:
Several constants are available to specify character cell attributes:
Keys are referred to by integer constants with names starting with
"KEY_". The exact keycaps available are system dependent.
On VT100s and their software emulations, such as X terminal emulators,
there are normally at least four function keys (KEY_F1,
KEY_F2, KEY_F3, KEY_F4) available,
and the arrow keys mapped to KEY_UP, KEY_DOWN,
KEY_LEFT and KEY_RIGHT in the obvious way. If
your machine has a PC keybboard, it is safe to expect arrow keys and
twelve function keys (older PC keyboards may have only ten function
keys); also, the following keypad mappings are standard:
The following table lists characters from the alternate character set.
These are inherited from the VT100 terminal, and will generally be
available on software emulations such as X terminals. When there
is no graphic available, curses falls back on a crude printable ASCII
approximation.
Note: These are available only after initscr() has
been called.
The following table lists the predefined colors:


module-locale.html | module-locale.html | embedding-locale.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.22.1 Background, details, hints, tips and caveats
The C standard defines the locale as a program-wide property that may
be relatively expensive to change. On top of that, some
implementation are broken in such a way that frequent locale changes
may cause core dumps. This makes the locale somewhat painful to use
correctly.
Initially, when a program is started, the locale is the "C" locale, no
matter what the user's preferred locale is. The program must
explicitly say that it wants the user's preferred locale settings by
calling `setlocale(LC_ALL, "")`.
It is generally a bad idea to call setlocale() in some library
routine, since as a side effect it affects the entire program. Saving
and restoring it is almost as bad: it is expensive and affects other
threads that happen to run before the settings have been restored.
If, when coding a module for general use, you need a locale
independent version of an operation that is affected by the locale
(e.g. string.lower(), or certain formats used with
time.strftime())), you will have to find a way to do it
without using the standard library routine. Even better is convincing
yourself that using locale settings is okay. Only as a last resort
should you document that your module is not compatible with
non-"C" locale settings.
The case conversion functions in the
string (module-string.html) and
strop modules are affected by the locale
settings. When a call to the setlocale() function changes
the LC_CTYPE settings, the variables
`string.lowercase`, `string.uppercase` and
`string.letters` (and their counterparts in strop) are
recalculated. Note that this code that uses these variable through
`from ... import ...', e.g. `from string
import letters`, is not affected by subsequent setlocale()
calls.
The only way to perform numeric operations according to the locale
is to use the special functions defined by this module:
atof(), atoi(), format(),
str().


6.23.1 GNU gettext API

module-gettext.html | module-gettext.html | node145.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.23.1 GNU gettext API
The gettext module defines the following API, which is very
similar to the GNU gettext API. If you use this API you
will affect the translation of your entire application globally. Often
this is what you want if your application is monolingual, with the choice
of language dependent on the locale of your user. If you are
localizing a Python module, or if your application needs to switch
languages on the fly, you probably want to use the class-based API
instead.
Note that GNU gettext also defines a dcgettext()
method, but this was deemed not useful and so it is currently
unimplemented.
Here's an example of typical usage for this API:
```text

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')
```


6.23.2 Class-based API

node144.html | module-gettext.html | node146.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.23.2 Class-based API
The class-based API of the gettext module gives you more
flexibility and greater convenience than the GNU gettext
API. It is the recommended way of localizing your Python applications and
modules. gettext defines a ``translations'' class which
implements the parsing of GNU .mo format files, and has methods
for returning either standard 8-bit strings or Unicode strings.
Translations instances can also install themselves in the built-in
namespace as the function _().
---
#### Footnotes


6.23.2.1 The NullTranslations class

node145.html | node145.html | node147.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.2.1 The NullTranslations class
Translation classes are what actually implement the translation of
original source file message strings to translated message strings.
The base class used by all translation classes is
NullTranslations; this provides the basic interface you can use
to write your own specialized translation classes.  Here are the
methods of NullTranslations:


6.23.2.2 The GNUTranslations class

node146.html | node145.html | node148.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.2.2 The GNUTranslations class
The gettext module provides one additional class derived from
NullTranslations: GNUTranslations. This class
overrides _parse() to enable reading GNU gettext
format .mo files in both big-endian and little-endian format.
It also parses optional meta-data out of the translation catalog. It
is convention with GNU gettext to include meta-data as the
translation for the empty string. This meta-data is in RFC 822 (http://www.ietf.org/rfc/rfc0822.txt)-style
`key: value` pairs. If the key `Content-Type` is found,
then the `charset` property is used to initialize the
``protected'' _charset instance variable. The entire set of
key/value pairs are placed into a dictionary and set as the
``protected'' _info instance variable.
If the .mo file's magic number is invalid, or if other problems
occur while reading the file, instantiating a GNUTranslations class
can raise IOError.
The other usefully overridden method is ugettext(), which
returns a Unicode string by passing both the translated message string
and the value of the ``protected'' _charset variable to the
builtin unicode() function.


node147.html | node145.html | node149.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.2.3 Solaris message catalog support
The Solaris operating system defines its own binary
.mo file format, but since no documentation can be found on
this format, it is not supported at this time.


6.23.2.4 The Catalog constructor

node148.html | node145.html | node150.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.2.4 The Catalog constructor
GNOME uses a version of the gettext module by
James Henstridge, but this version has a slightly different API. Its
documented usage was:
```text

import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print _('hello world')
```
For compatibility with this older module, the function
Catalog() is an alias for the the translation()
function described above.
One difference between this module and Henstridge's: his catalog
objects supported access through a mapping API, but this appears to be
unused and so is not currently supported.


node149.html | module-gettext.html | node151.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.23.3 Internationalizing your programs and modules
Internationalization (I18N) refers to the operation by which a program
is made aware of multiple languages.  Localization (L10N) refers to
the adaptation of your program, once internationalized, to the local
language and cultural habits.  In order to provide multilingual
messages for your Python programs, you need to take the following
steps:
1. prepare your program or module by specially marking
translatable strings
2. run a suite of tools over your marked files to generate raw
messages catalogs
3. create language specific translations of the message catalogs
4. use the gettext module so that message strings are
properly translated
In order to prepare your code for I18N, you need to look at all the
strings in your files. Any string that needs to be translated
should be marked by wrapping it in `_('...')` - i.e. a call to
the function _(). For example:
```text

filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()
```
In this example, the string `'writing a log message'` is marked as
a candidate for translation, while the strings `'mylog.txt'` and
`'w'` are not.
The GNU `gettext` package provides a tool, called
xgettext, that scans C and C++ source code looking for these
specially marked strings. xgettext generates what are
called .pot files, essentially structured human readable files
which contain every marked string in the source code. These
.pot files are copied and handed over to human translators who write
language-specific versions for every supported natural language.
For I18N Python programs however, xgettext won't work; it
doesn't understand the myriad of string types support by Python. The
standard Python distribution provides a tool called
pygettext that does though (found in the Tools/i18n/
directory).6.3 (#foot17313) This is a command line script that
supports a similar interface as xgettext; see its
documentation for details. Once you've used pygettext to
create your .pot files, you can use the standard GNU
gettext tools to generate your machine-readable .mo
files, which are readable by the GNUTranslations class.
How you use the gettext module in your code depends on
whether you are internationalizing your entire application or a single
module.
---
#### Footnotes


6.23.3.1 Localizing your module

node150.html | node150.html | node152.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.3.1 Localizing your module
If you are localizing your module, you must take care not to make
global changes, e.g. to the built-in namespace. You should not use
the GNU `gettext` API but instead the class-based API.
Let's say your module is called ``spam'' and the module's various
natural language translation .mo files reside in
/usr/share/locale in GNU gettext format. Here's what
you would put at the top of your module:
```text

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext
```
If your translators were providing you with Unicode strings in their
.po files, you'd instead do:
```text

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.ugettext
```


6.23.3.2 Localizing your application

node151.html | node150.html | node153.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.3.2 Localizing your application
If you are localizing your application, you can install the _()
function globally into the built-in namespace, usually in the main driver file
of your application. This will let all your application-specific
files just use `_('...')` without having to explicitly install it in
each file.
In the simple case then, you need only add the following bit of code
to the main driver file of your application:
```text

import gettext
gettext.install('myapplication')
```
If you need to set the locale directory or the unicode flag,
you can pass these into the install() function:
```text

import gettext
gettext.install('myapplication', '/usr/share/locale', unicode=1)
```


6.23.3.3 Changing languages on the fly

node152.html | node150.html | node154.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.3.3 Changing languages on the fly
If your program needs to support many languages at the same time, you
may want to create multiple translation instances and then switch
between them explicitly, like so:
```text

import gettext

lang1 = gettext.translation(languages=['en'])
lang2 = gettext.translation(languages=['fr'])
lang3 = gettext.translation(languages=['de'])

# start by using language1
lang1.install()

# ... time goes by, user selects language 2
lang2.install()

# ... more time goes by, user selects language 3
lang3.install()
```


6.23.3.4 Deferred translations

node153.html | node150.html | node155.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 6.23.3.4 Deferred translations
In most coding situations, strings are translated were they are coded.
Occasionally however, you need to mark strings for translation, but
defer actual translation until later. A classic example is:
```text

animals = ['mollusk',
'albatross',
'rat',
'penguin',
'python',
]
# ...
for a in animals:
print a
```
Here, you want to mark the strings in the `animals` list as being
translatable, but you don't actually want to translate them until they
are printed.
Here is one way you can handle this situation:
```text

def _(message): return message

animals = [_('mollusk'),
_('albatross'),
_('rat'),
_('penguin'),
_('python'),
]

del _

# ...
for a in animals:
print _(a)
```
This works because the dummy definition of _() simply returns
the string unchanged. And this dummy definition will temporarily
override any definition of _() in the built-in namespace
(until the del command).
Take care, though if you have a previous definition of _ in
the local namespace.
Note that the second use of _() will not identify ``a'' as
being translatable to the pygettext program, since it is not
a string.
Another way to handle this is with the following example:
```text

def N_(message): return message

animals = [N_('mollusk'),
N_('albatross'),
N_('rat'),
N_('penguin'),
N_('python'),
]

# ...
for a in animals:
print _(a)
```
In this case, you are marking translatable strings with the function
N_(),6.4 (#foot17314) which won't conflict with any definition of
_(). However, you will need to teach your message extraction
program to look for translatable strings marked with N_().
pygettext and xpot both support this through the
use of command line switches.


6.23.4 Acknowledgements

node154.html | module-gettext.html | someos.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.23.4 Acknowledgements
The following people contributed code, feedback, design suggestions,
previous implementations, and valuable experience to the creation of
this module:
- Peter Funk
- James Henstridge
- Marc-André Lemburg
- Martin von Löwis
- François Pinard
- Barry Warsaw


7.14 zipfile -- Work with ZIP archives

module-gzip.html | someos.html | zipfile-objects.html | Python Library Reference | contents.html | genindex.html
---
# 7.14 zipfile --
Work with ZIP archives
The ZIP file format is a common archive and compression standard.
This module provides tools to create, read, write, append, and list a
ZIP file.
The available attributes of this module are:
See Also:
XXX point to ZIP format definition
XXX point to Info-ZIP home page; mention WiZ


8.15.1 Resource Limits

module-resource.html | module-resource.html | node201.html | Python Library Reference | contents.html | genindex.html
---
## 8.15.1 Resource Limits
Resources usage can be limited using the setrlimit() function
described below. Each resource is controlled by a pair of limits: a
soft limit and a hard limit. The soft limit is the current limit, and
may be lowered or raised by a process over time. The soft limit can
never exceed the hard limit. The hard limit can be lowered to any
value greater than the soft limit, but not raised. (Only processes with
the effective UID of the super-user can raise a hard limit.)
The specific resources that can be limited are system dependent. They
are described in the getrlimit(2) man page. The resources
listed below are supported when the underlying operating system
supports them; resources which cannot be checked or controlled by the
operating system are not defined in this module for those platforms.
These symbols define resources whose consumption can be controlled
using the setrlimit() and getrlimit() functions
described below. The values of these symbols are exactly the constants
used by C programs.
The Unix man page for getrlimit(2) lists the available
resources. Note that not all systems use the same symbol or same
value to denote the same resource.


8.15.2 Resource Usage

node200.html | module-resource.html | module-nis.html | Python Library Reference | contents.html | genindex.html
---
## 8.15.2 Resource Usage
These functiona are used to retrieve resource usage information:
The following RUSAGE_* symbols are passed to the
getrusage() function to specify which processes information
should be provided for.


9.2 How It Works

debugger-commands.html | module-pdb.html | profile.html | Python Library Reference | contents.html | genindex.html
---
# 9.2 How It Works
Some changes were made to the interpreter:
- `sys.settrace( func )` sets the global trace function
- there can also a local trace function (see later)
Trace functions have three arguments: frame, event, and
arg. frame is the current stack frame. event is a
string: `'call'`, `'line'`, `'return'` or
`'exception'`. arg depends on the event type.
The global trace function is invoked (with event set to
`'call'`) whenever a new local scope is entered; it should return
a reference to the local trace function to be used that scope, or
`None` if the scope shouldn't be traced.
The local trace function should return a reference to itself (or to
another function for further tracing in that scope), or `None` to
turn off tracing in that scope.
Instance methods are accepted (and very useful!) as trace functions.
The events have the following meaning:
`'call'`: A function is called (or some other code block entered). The global
trace function is called; arg is the argument list to the function;
the return value specifies the local trace function.
`'line'`: The interpreter is about to execute a new line of code (sometimes
multiple line events on one line exist). The local trace function is
called; arg in None; the return value specifies the new local trace
function.
`'return'`: A function (or other code block) is about to return. The local trace
function is called; arg is the value that will be returned. The trace
function's return value is ignored.
`'exception'`: An exception has occurred. The local trace function is called; arg is
a triple (exception, value, traceback); the return value specifies the
new local trace function
Note that as an exception is propagated down the chain of callers, an
`'exception'` event is generated at each level.
For more information on code and frame objects, refer to the
Python Reference Manual (../ref/ref.html).


8.15.1 Resource Limits

module-resource.html | module-resource.html | node216.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 8.15.1 Resource Limits
Resources usage can be limited using the setrlimit() function
described below. Each resource is controlled by a pair of limits: a
soft limit and a hard limit. The soft limit is the current limit, and
may be lowered or raised by a process over time. The soft limit can
never exceed the hard limit. The hard limit can be lowered to any
value greater than the soft limit, but not raised. (Only processes with
the effective UID of the super-user can raise a hard limit.)
The specific resources that can be limited are system dependent. They
are described in the getrlimit(2) man page. The resources
listed below are supported when the underlying operating system
supports them; resources which cannot be checked or controlled by the
operating system are not defined in this module for those platforms.
These symbols define resources whose consumption can be controlled
using the setrlimit() and getrlimit() functions
described below. The values of these symbols are exactly the constants
used by C programs.
The Unix man page for getrlimit(2) lists the available
resources. Note that not all systems use the same symbol or same
value to denote the same resource.


8.15.2 Resource Usage

node215.html | module-resource.html | module-nis.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 8.15.2 Resource Usage
These functiona are used to retrieve resource usage information:
The following RUSAGE_* symbols are passed to the
getrusage() function to specify which processes information
should be provided for.


9.2 How It Works

debugger-commands.html | module-pdb.html | profile.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 9.2 How It Works
Some changes were made to the interpreter:
- `sys.settrace( func )` sets the global trace function
- there can also a local trace function (see later)
Trace functions have three arguments: frame, event, and
arg. frame is the current stack frame. event is a
string: `'call'`, `'line'`, `'return'` or
`'exception'`. arg depends on the event type.
The global trace function is invoked (with event set to
`'call'`) whenever a new local scope is entered; it should return
a reference to the local trace function to be used that scope, or
`None` if the scope shouldn't be traced.
The local trace function should return a reference to itself (or to
another function for further tracing in that scope), or `None` to
turn off tracing in that scope.
Instance methods are accepted (and very useful!) as trace functions.
The events have the following meaning:
`'call'`: A function is called (or some other code block entered). The global
trace function is called; arg is the argument list to the function;
the return value specifies the local trace function.
`'line'`: The interpreter is about to execute a new line of code (sometimes
multiple line events on one line exist). The local trace function is
called; arg in None; the return value specifies the new local trace
function.
`'return'`: A function (or other code block) is about to return. The local trace
function is called; arg is the value that will be returned. The trace
function's return value is ignored.
`'exception'`: An exception has occurred. The local trace function is called; arg is
a triple (exception, value, traceback); the return value specifies the
new local trace function
Note that as an exception is propagated down the chain of callers, an
`'exception'` event is generated at each level.
For more information on code and frame objects, refer to the
Python Reference Manual (../ref/ref.html).


11.1.3 Old classes

Using_the_cgi_module.html | module-cgi.html | Functions_in_cgi_module.html | Python Library Reference | contents.html | genindex.html
---
## 11.1.3 Old classes
These classes, present in earlier versions of the cgi module,
are still supported for backward compatibility. New applications
should use the FieldStorage class.
SvFormContentDict stores single value form content as
dictionary; it assumes each field name occurs in the form only once.
FormContentDict stores multiple value form content as a
dictionary (the form items are lists of values). Useful if your form
contains multiple fields with the same name.
Other classes (FormContent, InterpFormContentDict) are
present for backwards compatibility with really old applications only.
If you still use these and would be inconvenienced when they
disappeared from a next version of this module, drop me a note.


11.1.5 Caring about security

Functions_in_cgi_module.html | module-cgi.html | node229.html | Python Library Reference | contents.html | genindex.html
---
## 11.1.5 Caring about security
There's one important rule: if you invoke an external program (e.g.
via the os.system() or os.popen() functions),
make very sure you don't pass arbitrary strings received from the
client to the shell. This is a well-known security hole whereby
clever hackers anywhere on the web can exploit a gullible CGI script
to invoke arbitrary shell commands. Even parts of the URL or field
names cannot be trusted, since the request doesn't have to come from
your form!
To be on the safe side, if you must pass a string gotten from a form
to a shell command, you should make sure the string contains only
alphanumeric characters, dashes, underscores, and periods.


node228.html | module-cgi.html | node230.html | Python Library Reference | contents.html | genindex.html
---
## 11.1.6 Installing your CGI script on a Unix system
Read the documentation for your HTTP server and check with your local
system administrator to find the directory where CGI scripts should be
installed; usually this is in a directory cgi-bin in the server tree.
Make sure that your script is readable and executable by ``others''; the
Unix file mode should be `0755` octal (use "chmod 0755
filename"). Make sure that the first line of the script contains
`#!` starting in column 1 followed by the pathname of the Python
interpreter, for instance:
```text

#!/usr/local/bin/python
```
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
readable or writable, respectively, by ``others'' -- their mode
should be `0644` for readable and `0666` for writable. This
is because, for security reasons, the HTTP server executes your script
as user ``nobody'', without any special privileges. It can only read
(write, execute) files that everybody can read (write, execute). The
current directory at execution time is also different (it is usually
the server's cgi-bin directory) and the set of environment variables
is also different from what you get at login. In particular, don't
count on the shell's search path for executables ($PATH) or
the Python module search path ($PYTHONPATH) to be set to
anything interesting.
If you need to load modules from a directory which is not on Python's
default module search path, you can change the path in your script,
before importing other modules, e.g.:
```text

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
```
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).


11.1.7 Testing your CGI script

node229.html | module-cgi.html | node231.html | Python Library Reference | contents.html | genindex.html
---
## 11.1.7 Testing your CGI script
Unfortunately, a CGI script will generally not run when you try it
from the command line, and a script that works perfectly from the
command line may fail mysteriously when run from the server. There's
one reason why you should still test your script from the command
line: if it contains a syntax error, the Python interpreter won't
execute it at all, and the HTTP server will most likely send a cryptic
error to the client.
Assuming your script has no syntax errors, yet it does not work, you
have no choice but to read the next section.


11.1.8 Debugging CGI scripts

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

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
```
If this gives an error of type 404, the server cannot find the script
- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
you should fix before trying to go any further. If you get a nicely
formatted listing of the environment and form content (in this
example, the fields should be listed as ``addr'' with value ``At Home''
and ``name'' with value ``Joe Blow''), the cgi.py script has been
installed correctly. If you follow the same procedure for your own
script, you should now be able to debug it.
The next step could be to call the cgi module's
test() function from your script: replace its main code
with the single statement
```text

cgi.test()
```
This should produce the same results as those gotten from installing
the cgi.py file itself.
When an ordinary Python script raises an unhandled exception
(e.g. because of a typo in a module name, a file that can't be opened,
etc.), the Python interpreter prints a nice traceback and exits.
While the Python interpreter will still do this when your CGI script
raises an exception, most likely the traceback will end up in one of
the HTTP server's log file, or be discarded altogether.
Fortunately, once you have managed to get your script to execute
some code, it is easy to catch exceptions and cause a traceback
to be printed. The test() function below in this module is
an example. Here are the rules:
1. Import the traceback module before entering the try
... except statement
2. Assign `sys.stderr` to be `sys.stdout`
3. Make sure you finish printing the headers and the blank line
early
4. Wrap all remaining code in a try ... except
statement
5. In the except clause, call traceback.print_exc()
For example:
```text

import sys
import traceback
print "Content-type: text/html"
print
sys.stderr = sys.stdout
try:
...your code here...
except:
print "\n\n<PRE>"
traceback.print_exc()
```
Notes: The assignment to `sys.stderr` is needed because the
traceback prints to `sys.stderr`.
The `print "\n\n<PRE>"` statement is necessary to
disable the word wrapping in HTML.
If you suspect that there may be a problem in importing the traceback
module, you can use an even more robust approach (which only uses
built-in modules):
```text

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


11.1.9 Common problems and solutions

node231.html | module-cgi.html | module-urllib.html | Python Library Reference | contents.html | genindex.html
---
## 11.1.9 Common problems and solutions


11.3.1 HTTP Objects

module-httplib.html | module-httplib.html | HTTP_Example.html | Python Library Reference | contents.html | genindex.html
---
## 11.3.1 HTTP Objects
HTTP instances have the following methods:


11.2.3 Old classes

Using_the_cgi_module.html | module-cgi.html | Functions_in_cgi_module.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.2.3 Old classes
These classes, present in earlier versions of the cgi module,
are still supported for backward compatibility. New applications
should use the FieldStorage class.
SvFormContentDict stores single value form content as
dictionary; it assumes each field name occurs in the form only once.
FormContentDict stores multiple value form content as a
dictionary (the form items are lists of values). Useful if your form
contains multiple fields with the same name.
Other classes (FormContent, InterpFormContentDict) are
present for backwards compatibility with really old applications only.
If you still use these and would be inconvenienced when they
disappeared from a next version of this module, drop me a note.


11.2.5 Caring about security

Functions_in_cgi_module.html | module-cgi.html | node244.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.2.5 Caring about security
There's one important rule: if you invoke an external program (e.g.
via the os.system() or os.popen() functions),
make very sure you don't pass arbitrary strings received from the
client to the shell. This is a well-known security hole whereby
clever hackers anywhere on the web can exploit a gullible CGI script
to invoke arbitrary shell commands. Even parts of the URL or field
names cannot be trusted, since the request doesn't have to come from
your form!
To be on the safe side, if you must pass a string gotten from a form
to a shell command, you should make sure the string contains only
alphanumeric characters, dashes, underscores, and periods.


node243.html | module-cgi.html | node245.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.2.6 Installing your CGI script on a Unix system
Read the documentation for your HTTP server and check with your local
system administrator to find the directory where CGI scripts should be
installed; usually this is in a directory cgi-bin in the server tree.
Make sure that your script is readable and executable by ``others''; the
Unix file mode should be `0755` octal (use "chmod 0755
filename"). Make sure that the first line of the script contains
`#!` starting in column 1 followed by the pathname of the Python
interpreter, for instance:
```text

#!/usr/local/bin/python
```
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
readable or writable, respectively, by ``others'' -- their mode
should be `0644` for readable and `0666` for writable. This
is because, for security reasons, the HTTP server executes your script
as user ``nobody'', without any special privileges. It can only read
(write, execute) files that everybody can read (write, execute). The
current directory at execution time is also different (it is usually
the server's cgi-bin directory) and the set of environment variables
is also different from what you get at login. In particular, don't
count on the shell's search path for executables ($PATH) or
the Python module search path ($PYTHONPATH) to be set to
anything interesting.
If you need to load modules from a directory which is not on Python's
default module search path, you can change the path in your script,
before importing other modules, e.g.:
```text

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
```
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).


11.2.7 Testing your CGI script

node244.html | module-cgi.html | node246.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.2.7 Testing your CGI script
Unfortunately, a CGI script will generally not run when you try it
from the command line, and a script that works perfectly from the
command line may fail mysteriously when run from the server. There's
one reason why you should still test your script from the command
line: if it contains a syntax error, the Python interpreter won't
execute it at all, and the HTTP server will most likely send a cryptic
error to the client.
Assuming your script has no syntax errors, yet it does not work, you
have no choice but to read the next section.


11.2.8 Debugging CGI scripts

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

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
```
If this gives an error of type 404, the server cannot find the script
- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
you should fix before trying to go any further. If you get a nicely
formatted listing of the environment and form content (in this
example, the fields should be listed as ``addr'' with value ``At Home''
and ``name'' with value ``Joe Blow''), the cgi.py script has been
installed correctly. If you follow the same procedure for your own
script, you should now be able to debug it.
The next step could be to call the cgi module's
test() function from your script: replace its main code
with the single statement
```text

cgi.test()
```
This should produce the same results as those gotten from installing
the cgi.py file itself.
When an ordinary Python script raises an unhandled exception
(e.g. because of a typo in a module name, a file that can't be opened,
etc.), the Python interpreter prints a nice traceback and exits.
While the Python interpreter will still do this when your CGI script
raises an exception, most likely the traceback will end up in one of
the HTTP server's log file, or be discarded altogether.
Fortunately, once you have managed to get your script to execute
some code, it is easy to catch exceptions and cause a traceback
to be printed. The test() function below in this module is
an example. Here are the rules:
1. Import the traceback module before entering the try
... except statement
2. Assign `sys.stderr` to be `sys.stdout`
3. Make sure you finish printing the headers and the blank line
early
4. Wrap all remaining code in a try ... except
statement
5. In the except clause, call traceback.print_exc()
For example:
```text

import sys
import traceback
print "Content-Type: text/html"
print
sys.stderr = sys.stdout
try:
...your code here...
except:
print "\n\n<PRE>"
traceback.print_exc()
```
Notes: The assignment to `sys.stderr` is needed because the
traceback prints to `sys.stderr`.
The `print "\n\n<PRE>"` statement is necessary to
disable the word wrapping in HTML.
If you suspect that there may be a problem in importing the traceback
module, you can use an even more robust approach (which only uses
built-in modules):
```text

import sys
sys.stderr = sys.stdout
print "Content-Type: text/plain"
print
...your code here...
```
This relies on the Python interpreter to print the traceback. The
content type of the output is set to plain text, which disables all
HTML processing. If your script works, the raw HTML will be displayed
by your client. If it raises an exception, most likely after the
first two lines have been printed, a traceback will be displayed.
Because no HTML interpretation is going on, the traceback will
readable.


11.2.9 Common problems and solutions

node246.html | module-cgi.html | module-urllib.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.2.9 Common problems and solutions


11.4.1 HTTP Objects

module-httplib.html | module-httplib.html | HTTP_Examples.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.4.1 HTTP Objects
HTTP instances have the following methods:


13.1.1 An example

module-rexec.html | module-rexec.html | module-Bastion.html | Python Library Reference | contents.html | genindex.html
---
## 13.1.1 An example
Let us say that we want a slightly more relaxed policy than the
standard RExec class. For example, if we're willing to allow
files in /tmp to be written, we can subclass the RExec
class:


18. MS Windows Specific Services

module-sunaudiodev-constants.html | lib.html | module-msvcrt.html | Python Library Reference | contents.html | genindex.html
---
# 18. MS Windows Specific Services
This chapter describes modules that are only available on MS Windows
platforms.


19.1 Frameworks

undoc.html | undoc.html | node363.html | Python Library Reference | contents.html | genindex.html
---
# 19.1 Frameworks
Frameworks tend to be harder to document, but are well worth the
effort spent.
Tkinter: -- Interface to Tcl/Tk for graphical user interfaces; Fredrik Lundh
is working on this one! See
An Introduction to
Tkinter (http://www.pythonware.com/library.htm) at http://www.pythonware.com/library.htm for on-line
reference material.
Tkdnd: -- Drag-and-drop support for Tkinter.
turtle: -- Turtle graphics in a Tk window.
test: -- Regression testing framework. This is used for the Python
regression test, but is useful for other Python libraries as well.
This is a package rather than a module.


19.2 Miscellaneous useful utilities

node362.html | undoc.html | node364.html | Python Library Reference | contents.html | genindex.html
---
# 19.2 Miscellaneous useful utilities
Some of these are very old and/or not very robust; marked with ``hmm.''
dircmp: -- Class to build directory diff tools on (may become a demo or tool).
Deprecated since release 1.6.
The filecmp (module-filecmp.html) module will replace
dircmp.
bdb: -- A generic Python debugger base class (used by pdb)
ihooks: -- Import hook support (for rexec (module-rexec.html); may become obsolete)
tzparse: -- Parse a timezone specification (unfinished; may disappear in the
future)


19.3 Platform specific modules

node363.html | undoc.html | node365.html | Python Library Reference | contents.html | genindex.html
---
# 19.3 Platform specific modules
These modules are used to implement the os.path (module-os.path.html) module,
and are not documented beyond this mention. There's little need to
document these.
dospath: -- implementation of os.path on MS-DOS
ntpath: -- implementation on os.path on 32-bit Windows
posixpath: -- implementation on os.path on POSIX


19.4 Multimedia

node364.html | undoc.html | obsolete-modules.html | Python Library Reference | contents.html | genindex.html
---
# 19.4 Multimedia
audiodev: -- Platform-independent API for playing audio data
sunaudio: -- Interpret Sun audio headers (may become obsolete or a tool/demo)
toaiff: -- Convert "arbitrary" sound files to AIFF files; should probably
become a tool or demo. Requires the external program sox.


16.1.1 An example

module-rexec.html | module-rexec.html | module-Bastion.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.1.1 An example
Let us say that we want a slightly more relaxed policy than the
standard RExec class. For example, if we're willing to allow
files in /tmp to be written, we can subclass the RExec
class:


19.6 Extension modules

obsolete-modules.html | undoc.html | modindex.html | Python Library Reference | contents.html | genindex.html
---
# 19.6 Extension modules
stdwin: -- Interface to STDWIN (an old, unsupported
platform-independent GUI package). Obsolete; use Tkinter for
a platform-independent GUI instead.
The following are SGI specific, and may be out of touch with the
current version of reality.
cl: -- Interface to the SGI compression library.
sv: -- Interface to the ``simple video'' board on SGI Indigo
(obsolete hardware).


17.1.6.1 Emulation of compile()

AST_Examples.html | AST_Examples.html | node377.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 17.1.6.1 Emulation of compile()
While many useful operations may take place between parsing and
bytecode generation, the simplest operation is to do nothing. For
this purpose, using the parser module to produce an
intermediate data structure is equivalent to the code
```text

>>> code = compile('a + 5', 'file.py', 'eval')
>>> a = 5
>>> eval(code)
10
```
The equivalent operation using the parser module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
```text

>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = ast.compile('file.py')
>>> a = 5
>>> eval(code)
10
```
An application which needs both AST and code objects can package this
code into readily available functions:
```text

import parser

def load_suite(source_string):
ast = parser.suite(source_string)
return ast, ast.compile()

def load_expression(source_string):
ast = parser.expr(source_string)
return ast, ast.compile()
```


17.1.6.2 Information Discovery

node376.html | AST_Examples.html | module-symbol.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 17.1.6.2 Information Discovery
Some applications benefit from direct access to the parse tree. The
remainder of this section demonstrates how the parse tree provides
access to module documentation defined in
docstrings without
requiring that the code being examined be loaded into a running
interpreter via import. This can be very useful for
performing analyses of untrusted code.
Generally, the example will demonstrate how the parse tree may be
traversed to distill interesting information. Two functions and a set
of classes are developed which provide programmatic access to high
level function and class definitions provided by a module. The
classes extract information from the parse tree and provide access to
the information at a useful semantic level, one function provides a
simple low-level pattern matching capability, and the other function
defines a high-level interface to the classes by handling file
operations on behalf of the caller. All source files mentioned here
which are not part of the Python installation are located in the
Demo/parser/ directory of the distribution.
The dynamic nature of Python allows the programmer a great deal of
flexibility, but most modules need only a limited measure of this when
defining classes, functions, and methods. In this example, the only
definitions that will be considered are those which are defined in the
top level of their context, e.g., a function defined by a def
statement at column zero of a module, but not a function defined
within a branch of an if ... else construct, though
there are some good reasons for doing so in some situations. Nesting
of definitions will be handled by the code developed in the example.
To construct the upper-level extraction methods, we need to know what
the parse tree structure looks like and how much of it we actually
need to be concerned about. Python uses a moderately deep parse tree
so there are a large number of intermediate nodes. It is important to
read and understand the formal grammar used by Python. This is
specified in the file Grammar/Grammar in the distribution.
Consider the simplest case of interest when searching for docstrings:
a module consisting of a docstring and nothing else. (See file
docstring.py.)
```text

"""Some documentation.
"""
```
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
```text

>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
>>> tup = ast.totuple()
>>> pprint.pprint(tup)
(257,
(264,
(265,
(266,
(267,
(307,
(287,
(288,
(289,
(290,
(292,
(293,
(294,
(295,
(296,
(297,
(298,
(299,
(300, (3, '"""Some documentation.\012"""'))))))))))))))))),
(4, ''))),
(4, ''),
(0, ''))
```
The numbers at the first element of each node in the tree are the node
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
internal representation, and the Python structures generated do not
change that. However, the symbol (module-symbol.html) and token (module-token.html) modules
provide symbolic names for the node types and dictionaries which map
from the integers to the symbolic names for the node types.
In the output presented above, the outermost tuple contains four
elements: the integer `257` and three additional tuples. Node
type `257` has the symbolic name file_input. Each of
these inner tuples contains an integer as the first element; these
integers, `264`, `4`, and `0`, represent the node types
stmt, NEWLINE, and ENDMARKER,
respectively.
Note that these values may change depending on the version of Python
you are using; consult symbol.py and token.py for
details of the mapping. It should be fairly clear that the outermost
node is related primarily to the input source rather than the contents
of the file, and may be disregarded for the moment. The stmt
node is much more interesting. In particular, all docstrings are
found in subtrees which are formed exactly as this node is formed,
with the only difference being the string itself. The association
between the docstring in a similar tree and the defined entity (class,
function, or module) which it describes is given by the position of
the docstring subtree within the tree defining the described
structure.
By replacing the actual docstring with something to signify a variable
component of the tree, we allow a simple pattern matching approach to
check any given subtree for equivalence to the general pattern for
docstrings. Since the example demonstrates information extraction, we
can safely require that the tree be in tuple form rather than list
form, allowing a simple variable representation to be
`['variable_name']`. A simple recursive function can implement
the pattern matching, returning a boolean and a dictionary of variable
name to value mappings. (See file example.py.)
```text

from types import ListType, TupleType

def match(pattern, data, vars=None):
if vars is None:
vars = {}
if type(pattern) is ListType:
vars[pattern[0]] = data
return 1, vars
if type(pattern) is not TupleType:
return (pattern == data), vars
if len(data) != len(pattern):
return 0, vars
for pattern, data in map(None, pattern, data):
same, vars = match(pattern, data, vars)
if not same:
break
return same, vars
```
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file example.py.)
```text

import symbol
import token

DOCSTRING_STMT_PATTERN = (
symbol.stmt,
(symbol.simple_stmt,
(symbol.small_stmt,
(symbol.expr_stmt,
(symbol.testlist,
(symbol.test,
(symbol.and_test,
(symbol.not_test,
(symbol.comparison,
(symbol.expr,
(symbol.xor_expr,
(symbol.and_expr,
(symbol.shift_expr,
(symbol.arith_expr,
(symbol.term,
(symbol.factor,
(symbol.power,
(symbol.atom,
(token.STRING, ['docstring'])
)))))))))))))))),
(token.NEWLINE, '')
))
```
Using the match() function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
```text

>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\012"""'}
```
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
fairly simple: the docstring is the first stmt node in a code
block (file_input or suite node types). A module
consists of a single file_input node, and class and function
definitions each contain exactly one suite node. Classes and
functions are readily identified as subtrees of code block nodes which
start with `(stmt, (compound_stmt, (classdef, ...` or
`(stmt, (compound_stmt, (funcdef, ...`. Note that these subtrees
cannot be matched by match() since it does not support multiple
sibling nodes to match without regard to number. A more elaborate
matching function could be used to overcome this limitation, but this
is sufficient for the example.
Given the ability to determine whether a statement might be a
docstring and extract the actual string from the statement, some work
needs to be performed to walk the parse tree for an entire module and
extract information about the names defined in each context of the
module and associate any docstrings with the names. The code to
perform this work is not complicated, but bears some explanation.
The public interface to the classes is straightforward and should
probably be somewhat more flexible. Each ``major'' block of the
module is described by an object providing several methods for inquiry
and a constructor which accepts at least the subtree of the complete
parse tree which it represents. The ModuleInfo constructor
accepts an optional name parameter since it cannot
otherwise determine the name of the module.
The public classes include ClassInfo, FunctionInfo,
and ModuleInfo. All objects provide the
methods get_name(), get_docstring(),
get_class_names(), and get_class_info(). The
ClassInfo objects support get_method_names() and
get_method_info() while the other classes provide
get_function_names() and get_function_info().
Within each of the forms of code block that the public classes
represent, most of the required information is in the same form and is
accessed in the same way, with classes having the distinction that
functions defined at the top level are referred to as ``methods.''
Since the difference in nomenclature reflects a real semantic
distinction from functions defined outside of a class, the
implementation needs to maintain the distinction.
Hence, most of the functionality of the public classes can be
implemented in a common base class, SuiteInfoBase, with the
accessors for function and method information provided elsewhere.
Note that there is only one class which represents function and method
information; this parallels the use of the def statement to
define both types of elements.
Most of the accessor functions are declared in SuiteInfoBase
and do not need to be overridden by subclasses. More importantly, the
extraction of most information from a parse tree is handled through a
method called by the SuiteInfoBase constructor. The example
code for most of the classes is clear when read alongside the formal
grammar, but the method which recursively creates new information
objects requires further examination. Here is the relevant part of
the SuiteInfoBase definition from example.py:
```text

class SuiteInfoBase:
_docstring = ''
_name = ''

def __init__(self, tree = None):
self._class_info = {}
self._function_info = {}
if tree:
self._extract_info(tree)

def _extract_info(self, tree):
# extract docstring
if len(tree) == 2:
found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
else:
found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
if found:
self._docstring = eval(vars['docstring'])
# discover inner definitions
for node in tree[1:]:
found, vars = match(COMPOUND_STMT_PATTERN, node)
if found:
cstmt = vars['compound']
if cstmt[0] == symbol.funcdef:
name = cstmt[2][1]
self._function_info[name] = FunctionInfo(cstmt)
elif cstmt[0] == symbol.classdef:
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
```
After initializing some internal state, the constructor calls the
_extract_info() method. This method performs the bulk of the
information extraction which takes place in the entire example. The
extraction has two distinct phases: the location of the docstring for
the parse tree passed in, and the discovery of additional definitions
within the code block represented by the parse tree.
The initial if test determines whether the nested suite is of
the ``short form'' or the ``long form.'' The short form is used when
the code block is on the same line as the definition of the code
block, as in
```text

def square(x): "Square an argument."; return x ** 2
```
while the long form uses an indented block and allows nested
definitions:
```text

def make_power(exp):
"Make a function that raises an argument to the exponent `exp'."
def raiser(x, y=exp):
return x ** y
return raiser
```
When the short form is used, the code block may contain a docstring as
the first, and possibly only, small_stmt element. The
extraction of such a docstring is slightly different and requires only
a portion of the complete pattern used in the more common case. As
implemented, the docstring will only be found if there is only
one small_stmt node in the simple_stmt node.
Since most functions and methods which use the short form do not
provide a docstring, this may be considered sufficient. The
extraction of the docstring proceeds using the match() function
as described above, and the value of the docstring is stored as an
attribute of the SuiteInfoBase object.
After docstring extraction, a simple definition discovery
algorithm operates on the stmt nodes of the
suite node. The special case of the short form is not
tested; since there are no stmt nodes in the short form,
the algorithm will silently skip the single simple_stmt
node and correctly not discover any nested definitions.
Each statement in the code block is categorized as
a class definition, function or method definition, or
something else. For the definition statements, the name of the
element defined is extracted and a representation object
appropriate to the definition is created with the defining subtree
passed as an argument to the constructor. The representation objects
are stored in instance variables and may be retrieved by name using
the appropriate accessor methods.
The public classes provide any accessors required which are more
specific than those provided by the SuiteInfoBase class, but
the real extraction algorithm remains common to all forms of code
blocks. A high-level function can be used to extract the complete set
of information from a source file. (See file example.py.)
```text

def get_docs(fileName):
import os
import parser

source = open(fileName).read()
basename = os.path.basename(os.path.splitext(fileName)[0])
ast = parser.suite(source)
return ModuleInfo(ast.totuple(), basename)
```


20. MS Windows Specific Services

module-sunaudiodev-constants.html | lib.html | module-msvcrt.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 20. MS Windows Specific Services
This chapter describes modules that are only available on MS Windows
platforms.


A.1 Frameworks

undoc.html | undoc.html | node423.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.1 Frameworks
Frameworks tend to be harder to document, but are well worth the
effort spent.
Tkinter: -- Interface to Tcl/Tk for graphical user interfaces; Fredrik Lundh
is working on this one! See
An Introduction to
Tkinter (http://www.pythonware.com/library.htm) at http://www.pythonware.com/library.htm for on-line
reference material.
Tkdnd: -- Drag-and-drop support for Tkinter.
turtle: -- Turtle graphics in a Tk window.
test: -- Regression testing framework. This is used for the Python
regression test, but is useful for other Python libraries as well.
This is a package rather than a single module.


A.2 Miscellaneous useful utilities

node422.html | undoc.html | node424.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.2 Miscellaneous useful utilities
Some of these are very old and/or not very robust; marked with ``hmm.''
bdb: -- A generic Python debugger base class (used by pdb).
ihooks: -- Import hook support (for rexec (module-rexec.html); may become obsolete).
tzparse: -- Parse a timezone specification (unfinished; may disappear in the
future).


A.3 Platform specific modules

node423.html | undoc.html | node425.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.3 Platform specific modules
These modules are used to implement the os.path (module-os.path.html) module,
and are not documented beyond this mention. There's little need to
document these.
dospath: -- Implementation of os.path on MS-DOS.
ntpath: -- Implementation on os.path on Win32, Win64, WinCE, and
OS/2 platforms.
posixpath: -- Implementation on os.path on POSIX.


A.4 Multimedia

node424.html | undoc.html | obsolete-modules.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.4 Multimedia
audiodev: -- Platform-independent API for playing audio data.
sunaudio: -- Interpret Sun audio headers (may become obsolete or a tool/demo).
toaiff: -- Convert "arbitrary" sound files to AIFF files; should probably
become a tool or demo. Requires the external program sox.


A.6 SGI-specific Extension modules

obsolete-modules.html | undoc.html | reporting-bugs.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.6 SGI-specific Extension modules
The following are SGI specific, and may be out of touch with the
current version of reality.


3.16.6.1 Emulation of compile()

AST_Examples.html | AST_Examples.html | node56.html | Python Library Reference | contents.html | genindex.html
---
### 3.16.6.1 Emulation of compile()
While many useful operations may take place between parsing and
bytecode generation, the simplest operation is to do nothing. For
this purpose, using the parser module to produce an
intermediate data structure is equivalent to the code
```text

>>> code = compile('a + 5', 'file.py', 'eval')
>>> a = 5
>>> eval(code)
10
```
The equivalent operation using the parser module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
```text

>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = ast.compile('file.py')
>>> a = 5
>>> eval(code)
10
```
An application which needs both AST and code objects can package this
code into readily available functions:
```text

import parser

def load_suite(source_string):
ast = parser.suite(source_string)
return ast, ast.compile()

def load_expression(source_string):
ast = parser.expr(source_string)
return ast, ast.compile()
```


3.16.6.2 Information Discovery

node55.html | AST_Examples.html | module-symbol.html | Python Library Reference | contents.html | genindex.html
---
### 3.16.6.2 Information Discovery
Some applications benefit from direct access to the parse tree. The
remainder of this section demonstrates how the parse tree provides
access to module documentation defined in
docstrings without
requiring that the code being examined be loaded into a running
interpreter via import. This can be very useful for
performing analyses of untrusted code.
Generally, the example will demonstrate how the parse tree may be
traversed to distill interesting information. Two functions and a set
of classes are developed which provide programmatic access to high
level function and class definitions provided by a module. The
classes extract information from the parse tree and provide access to
the information at a useful semantic level, one function provides a
simple low-level pattern matching capability, and the other function
defines a high-level interface to the classes by handling file
operations on behalf of the caller. All source files mentioned here
which are not part of the Python installation are located in the
Demo/parser/ directory of the distribution.
The dynamic nature of Python allows the programmer a great deal of
flexibility, but most modules need only a limited measure of this when
defining classes, functions, and methods. In this example, the only
definitions that will be considered are those which are defined in the
top level of their context, e.g., a function defined by a def
statement at column zero of a module, but not a function defined
within a branch of an if ... else construct, though
there are some good reasons for doing so in some situations. Nesting
of definitions will be handled by the code developed in the example.
To construct the upper-level extraction methods, we need to know what
the parse tree structure looks like and how much of it we actually
need to be concerned about. Python uses a moderately deep parse tree
so there are a large number of intermediate nodes. It is important to
read and understand the formal grammar used by Python. This is
specified in the file Grammar/Grammar in the distribution.
Consider the simplest case of interest when searching for docstrings:
a module consisting of a docstring and nothing else. (See file
docstring.py.)
```text

"""Some documentation.
"""
```
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
```text

>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
>>> tup = ast.totuple()
>>> pprint.pprint(tup)
(257,
(264,
(265,
(266,
(267,
(307,
(287,
(288,
(289,
(290,
(292,
(293,
(294,
(295,
(296,
(297,
(298,
(299,
(300, (3, '"""Some documentation.\012"""'))))))))))))))))),
(4, ''))),
(4, ''),
(0, ''))
```
The numbers at the first element of each node in the tree are the node
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
internal representation, and the Python structures generated do not
change that. However, the symbol (module-symbol.html) and token (module-token.html) modules
provide symbolic names for the node types and dictionaries which map
from the integers to the symbolic names for the node types.
In the output presented above, the outermost tuple contains four
elements: the integer `257` and three additional tuples. Node
type `257` has the symbolic name file_input. Each of
these inner tuples contains an integer as the first element; these
integers, `264`, `4`, and `0`, represent the node types
stmt, NEWLINE, and ENDMARKER,
respectively.
Note that these values may change depending on the version of Python
you are using; consult symbol.py and token.py for
details of the mapping. It should be fairly clear that the outermost
node is related primarily to the input source rather than the contents
of the file, and may be disregarded for the moment. The stmt
node is much more interesting. In particular, all docstrings are
found in subtrees which are formed exactly as this node is formed,
with the only difference being the string itself. The association
between the docstring in a similar tree and the defined entity (class,
function, or module) which it describes is given by the position of
the docstring subtree within the tree defining the described
structure.
By replacing the actual docstring with something to signify a variable
component of the tree, we allow a simple pattern matching approach to
check any given subtree for equivalence to the general pattern for
docstrings. Since the example demonstrates information extraction, we
can safely require that the tree be in tuple form rather than list
form, allowing a simple variable representation to be
`['variable_name']`. A simple recursive function can implement
the pattern matching, returning a boolean and a dictionary of variable
name to value mappings. (See file example.py.)
```text

from types import ListType, TupleType

def match(pattern, data, vars=None):
if vars is None:
vars = {}
if type(pattern) is ListType:
vars[pattern[0]] = data
return 1, vars
if type(pattern) is not TupleType:
return (pattern == data), vars
if len(data) != len(pattern):
return 0, vars
for pattern, data in map(None, pattern, data):
same, vars = match(pattern, data, vars)
if not same:
break
return same, vars
```
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file example.py.)
```text

import symbol
import token

DOCSTRING_STMT_PATTERN = (
symbol.stmt,
(symbol.simple_stmt,
(symbol.small_stmt,
(symbol.expr_stmt,
(symbol.testlist,
(symbol.test,
(symbol.and_test,
(symbol.not_test,
(symbol.comparison,
(symbol.expr,
(symbol.xor_expr,
(symbol.and_expr,
(symbol.shift_expr,
(symbol.arith_expr,
(symbol.term,
(symbol.factor,
(symbol.power,
(symbol.atom,
(token.STRING, ['docstring'])
)))))))))))))))),
(token.NEWLINE, '')
))
```
Using the match() function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
```text

>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\012"""'}
```
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
fairly simple: the docstring is the first stmt node in a code
block (file_input or suite node types). A module
consists of a single file_input node, and class and function
definitions each contain exactly one suite node. Classes and
functions are readily identified as subtrees of code block nodes which
start with `(stmt, (compound_stmt, (classdef, ...` or
`(stmt, (compound_stmt, (funcdef, ...`. Note that these subtrees
cannot be matched by match() since it does not support multiple
sibling nodes to match without regard to number. A more elaborate
matching function could be used to overcome this limitation, but this
is sufficient for the example.
Given the ability to determine whether a statement might be a
docstring and extract the actual string from the statement, some work
needs to be performed to walk the parse tree for an entire module and
extract information about the names defined in each context of the
module and associate any docstrings with the names. The code to
perform this work is not complicated, but bears some explanation.
The public interface to the classes is straightforward and should
probably be somewhat more flexible. Each ``major'' block of the
module is described by an object providing several methods for inquiry
and a constructor which accepts at least the subtree of the complete
parse tree which it represents. The ModuleInfo constructor
accepts an optional name parameter since it cannot
otherwise determine the name of the module.
The public classes include ClassInfo, FunctionInfo,
and ModuleInfo. All objects provide the
methods get_name(), get_docstring(),
get_class_names(), and get_class_info(). The
ClassInfo objects support get_method_names() and
get_method_info() while the other classes provide
get_function_names() and get_function_info().
Within each of the forms of code block that the public classes
represent, most of the required information is in the same form and is
accessed in the same way, with classes having the distinction that
functions defined at the top level are referred to as ``methods.''
Since the difference in nomenclature reflects a real semantic
distinction from functions defined outside of a class, the
implementation needs to maintain the distinction.
Hence, most of the functionality of the public classes can be
implemented in a common base class, SuiteInfoBase, with the
accessors for function and method information provided elsewhere.
Note that there is only one class which represents function and method
information; this parallels the use of the def statement to
define both types of elements.
Most of the accessor functions are declared in SuiteInfoBase
and do not need to be overriden by subclasses. More importantly, the
extraction of most information from a parse tree is handled through a
method called by the SuiteInfoBase constructor. The example
code for most of the classes is clear when read alongside the formal
grammar, but the method which recursively creates new information
objects requires further examination. Here is the relevant part of
the SuiteInfoBase definition from example.py:
```text

class SuiteInfoBase:
_docstring = ''
_name = ''

def __init__(self, tree = None):
self._class_info = {}
self._function_info = {}
if tree:
self._extract_info(tree)

def _extract_info(self, tree):
# extract docstring
if len(tree) == 2:
found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
else:
found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
if found:
self._docstring = eval(vars['docstring'])
# discover inner definitions
for node in tree[1:]:
found, vars = match(COMPOUND_STMT_PATTERN, node)
if found:
cstmt = vars['compound']
if cstmt[0] == symbol.funcdef:
name = cstmt[2][1]
self._function_info[name] = FunctionInfo(cstmt)
elif cstmt[0] == symbol.classdef:
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
```
After initializing some internal state, the constructor calls the
_extract_info() method. This method performs the bulk of the
information extraction which takes place in the entire example. The
extraction has two distinct phases: the location of the docstring for
the parse tree passed in, and the discovery of additional definitions
within the code block represented by the parse tree.
The initial if test determines whether the nested suite is of
the ``short form'' or the ``long form.'' The short form is used when
the code block is on the same line as the definition of the code
block, as in
```text

def square(x): "Square an argument."; return x ** 2
```
while the long form uses an indented block and allows nested
definitions:
```text

def make_power(exp):
"Make a function that raises an argument to the exponent `exp'."
def raiser(x, y=exp):
return x ** y
return raiser
```
When the short form is used, the code block may contain a docstring as
the first, and possibly only, small_stmt element. The
extraction of such a docstring is slightly different and requires only
a portion of the complete pattern used in the more common case. As
implemented, the docstring will only be found if there is only
one small_stmt node in the simple_stmt node.
Since most functions and methods which use the short form do not
provide a docstring, this may be considered sufficient. The
extraction of the docstring proceeds using the match() function
as described above, and the value of the docstring is stored as an
attribute of the SuiteInfoBase object.
After docstring extraction, a simple definition discovery
algorithm operates on the stmt nodes of the
suite node. The special case of the short form is not
tested; since there are no stmt nodes in the short form,
the algorithm will silently skip the single simple_stmt
node and correctly not discover any nested definitions.
Each statement in the code block is categorized as
a class definition, function or method definition, or
something else. For the definition statements, the name of the
element defined is extracted and a representation object
appropriate to the definition is created with the defining subtree
passed as an argument to the constructor. The repesentation objects
are stored in instance variables and may be retrieved by name using
the appropriate accessor methods.
The public classes provide any accessors required which are more
specific than those provided by the SuiteInfoBase class, but
the real extraction algorithm remains common to all forms of code
blocks. A high-level function can be used to extract the complete set
of information from a source file. (See file example.py.)
```text

def get_docs(fileName):
import os
import parser

source = open(fileName).read()
basename = os.path.basename(os.path.splitext(fileName)[0])
ast = parser.suite(source)
return ModuleInfo(ast.totuple(), basename)
```


4.7.1 Codec Base Classes

module-codecs.html | module-codecs.html | codec-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 4.7.1 Codec Base Classes
The codecs defines a set of base classes which define the
interface and can also be used to easily write you own codecs for use
in Python.
Each codec has to define four interfaces to make it usable as codec in
Python: stateless encoder, stateless decoder, stream reader and stream
writer. The stream reader and writers typically reuse the stateless
encoder/decoder to implement the file protocols.
The Codec class defines the interface for stateless
encoders/decoders.
To simplify and standardize error handling, the encode() and
decode() methods may implement different error handling
schemes by providing the errors string argument. The following
string values are defined and implemented by all standard Python
codecs:
- `'strict'` Raise ValueError (or a subclass);
this is the default.
- `'ignore'` Ignore the character and continue with the next.
- `'replace'` Replace with a suitable replacement character;
Python will use the official U+FFFD REPLACEMENT
CHARACTER for the builtin Unicode codecs.


4.3.1 Regular Expressions

module-regex.html | module-regex.html | Contents_of_Module_regex.html | Python Library Reference | contents.html | genindex.html
---
## 4.3.1 Regular Expressions
A regular expression (or RE) specifies a set of strings that matches
it; the functions in this module let you check if a particular string
matches a given regular expression (or if a given regular expression
matches a particular string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular
expressions; if A and B are both regular expressions,
then AB is also an regular expression. If a string p
matches A and another string q matches B, the string pq
will match AB. Thus, complex expressions can easily be constructed
from simpler ones like the primitives described here. For details of
the theory and implementation of regular expressions, consult almost
any textbook about compiler construction.
A brief explanation of the format of regular expressions follows.
Regular expressions can contain both special and ordinary characters.
Ordinary characters, like '`A`', '`a`', or '`0`', are
the simplest regular expressions; they simply match themselves. You
can concatenate ordinary characters, so '`last`' matches the
characters 'last'. (In the rest of this section, we'll write RE's in
`this special font`, usually without quotes, and strings to be
matched 'in single quotes'.)
Special characters either stand for classes of ordinary characters, or
affect how the regular expressions around them are interpreted.
The special characters are:
`.`: (Dot.) Matches any character except a newline.
`^`: (Caret.) Matches the start of the string.
`$`: Matches the end of the string.
`foo` matches both 'foo' and 'foobar', while the regular
expression '`foo$`' matches only 'foo'.
`*`: Causes the resulting RE to
match 0 or more repetitions of the preceding RE. `ab*` will
match 'a', 'ab', or 'a' followed by any number of 'b's.
`+`: Causes the
resulting RE to match 1 or more repetitions of the preceding RE.
`ab+` will match 'a' followed by any non-zero number of 'b's; it
will not match just 'a'.
`?`: Causes the resulting RE to
match 0 or 1 repetitions of the preceding RE. `ab?` will
match either 'a' or 'ab'.
`\`: Either escapes special characters (permitting you to match
characters like '*?+&$'), or signals a special sequence; special
sequences are discussed below. Remember that Python also uses the
backslash as an escape sequence in string literals; if the escape
sequence isn't recognized by Python's parser, the backslash and
subsequent character are included in the resulting string. However,
if Python would recognize the resulting sequence, the backslash should
be repeated twice.
`[]`: Used to indicate a set of characters. Characters can
be listed individually, or a range is indicated by giving two
characters and separating them by a '-'. Special characters are
not active inside sets. For example, `[akm$]`will match any of the characters 'a', 'k', 'm', or '$'; `[a-z]` will
match any lowercase letter.
If you want to include a `]` inside a
set, it must be the first character of the set; to include a `-`,
place it as the first or last character.
Characters not within a range can be matched by including a
`^` as the first character of the set; `^` elsewhere will
simply match the '`^`' character.
The special sequences consist of '`\`' and a character
from the list below. If the ordinary character is not on the list,
then the resulting RE will match the second character. For example,
`\$` matches the character '$'. Ones where the backslash
should be doubled in string literals are indicated.
`\|`: `A\|B`, where A and B can be arbitrary REs,
creates a regular expression that will match either A or B. This can
be used inside groups (see below) as well.
`\( \)`: Indicates the start and end of a group; the
contents of a group can be matched later in the string with the
`\[1-9]` special sequence, described next.
`\\1, ... \\7, \8, \9`: Matches the contents of the group of the same
number. For example, `\(.+\) \\1` matches 'the the' or
'55 55', but not 'the end' (note the space after the group). This
special sequence can only be used to match one of the first 9 groups;
groups with higher numbers can be matched using the `\v`sequence. (`\8` and `\9` don't need a double backslash
because they are not octal digits.)
`\\b`: Matches the empty string, but only at the
beginning or end of a word. A word is defined as a sequence of
alphanumeric characters, so the end of a word is indicated by
whitespace or a non-alphanumeric character.
`\B`: Matches the empty string, but when it is not at the
beginning or end of a word.
`\v`: Must be followed by a two digit decimal number, and
matches the contents of the group of the same number. The group
number must be between 1 and 99, inclusive.
`\w`: Matches any alphanumeric character; this is
equivalent to the set `[a-zA-Z0-9]`.
`\W`: Matches any non-alphanumeric character; this is
equivalent to the set `[â-zA-Z0-9]`.
`\<`: Matches the empty string, but only at the beginning of a
word. A word is defined as a sequence of alphanumeric characters, so
the end of a word is indicated by whitespace or a non-alphanumeric
character.
`\>`: Matches the empty string, but only at the end of a
word.
`\\\\`: Matches a literal backslash.
`\``: Like `^`, this only matches at the start of the
string.
`\\'`: Like `$`, this only matches at the end of
the string.


A.5 Obsolete

node425.html | undoc.html | node427.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.5 Obsolete
These modules are not normally available for import; additional work
must be done to make them available.
Those which are written in Python will be installed into the directory
lib-old/ installed as part of the standard library. To use
these, the directory must be added to `sys.path`, possibly using
$PYTHONPATH.
Obsolete extension modules written in C are not built by default.
Under Unix, these must be enabled by uncommenting the appropriate
lines in Modules/Setup in the build tree and either rebuilding
Python if the modules are statically linked, or building and
installing the shared object if using dynamically-loaded extensions.
addpack: -- Alternate approach to packages. Use the built-in package support
instead.
cmp: -- File comparison function. Use the newer filecmp (module-filecmp.html) instead.
cmpcache: -- Caching version of the obsolete cmp module. Use the
newer filecmp (module-filecmp.html) instead.
codehack: -- Extract function name or line number from a function
code object (these are now accessible as attributes:
co.co_name, func.func_name,
co.co_firstlineno).
dircmp: -- Class to build directory diff tools on (may become a demo or tool).
Deprecated since release 2.0.
The filecmp (module-filecmp.html) module replaces
dircmp.
dump: -- Print python code that reconstructs a variable.
fmt: -- Text formatting abstractions (too slow).
lockfile: -- Wrapper around FCNTL file locking (use
fcntl.lockf()/flock() instead; see fcntl (module-fcntl.html)).
newdir: -- New dir() function (the standard dir() is
now just as good).
Para: -- Helper for fmt.
poly: -- Polynomials.
regex: -- Emacs-style regular expression support; may still be used in some
old code (extension module). Refer to the
Python
1.6 Documentation (http://www.python.org/doc/1.6/lib/module-regex.html) for documentation.
regsub: -- Regular expression based string replacement utilities, for use
with regex (extension module). Refer to the
Python
1.6 Documentation (http://www.python.org/doc/1.6/lib/module-regsub.html) for documentation.
tb: -- Print tracebacks, with a dump of local variables (use
pdb.pm() or traceback (module-traceback.html) instead).
timing: -- Measure time intervals to high resolution (use
time.clock() instead). (This is an extension module.)
util: -- Useful functions that don't fit elsewhere.
whatsound: -- Recognize sound files; use sndhdr (module-sndhdr.html) instead.
zmod: -- Compute properties of mathematical ``fields.''
The following modules are obsolete, but are likely to re-surface as
tools or scripts:
find: -- Find files matching pattern in directory tree.
grep: -- grep implementation in Python.
packmail: -- Create a self-unpacking Unix shell archive.
The following modules were documented in previous versions of this
manual, but are now considered obsolete. The source for the
documentation is still available as part of the documentation source
archive.
ni: -- Import modules in ``packages.'' Basic package support is now
built in. The built-in support is very similar to what is provided in
this module.
rand: -- Old interface to the random number generator.
soundex: -- Algorithm for collapsing names which sound similar to a shared
key. The specific algorithm doesn't seem to match any published
algorithm. (This is an extension module.)


6.1.3 File Descriptor Operations

os-newstreams.html | module-os.html | os-file-dir.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.3 File Descriptor Operations
These functions operate on I/O streams referred to
using file descriptors.
The following data items are available for use in constructing the
flags parameter to the open() function.


6.1.4 Files and Directories

os-fd-ops.html | module-os.html | os-process.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.4 Files and Directories


6.1.2 File Object Creation

os-procinfo.html | module-os.html | os-fd-ops.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.2 File Object Creation
These functions create new file objects.
For each of these popen() variants, 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'`.
This functionality is also available in the popen2 (module-popen2.html) module
using functions of the same names, but the return values of those
functions have a different order.


6.1.6 Miscellaneous System Information

os-process.html | module-os.html | module-os.path.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.6 Miscellaneous System Information
The follow data values are used to support path manipulation
operations. These are defined for all platforms.
Higher-level operations on pathnames are defined in the
os.path (module-os.path.html) module.


6.1.5 Process Management

os-file-dir.html | module-os.html | os-path.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.5 Process Management
These functions may be used to create and manage processes.
The various exec*() functions take a list of arguments for
the new program loaded into the process. In each case, the first of
these arguments is passed to the new program as its own name rather
than as an argument a user may have typed on a command line. For the
C programmer, this is the `argv[0]` passed to a program's
main(). For example, "os.execv('/bin/echo', ['foo',
'bar'])" will only print "bar" on standard output; "foo"will seem to be ignored.
The following functions take a process status code as returned by
system(), wait(), or waitpid() as a
parameter. They may be used to determine the disposition of a
process.


6.1.1 Process Parameters

module-os.html | module-os.html | os-newstreams.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.1 Process Parameters
These functions and data items provide information and operate on the
current process and user.


3.11.1 Example

module-pickle.html | module-pickle.html | module-cPickle.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.11.1 Example
Here's a simple example of how to modify pickling behavior for a
class. The TextReader class opens a text file, and returns
the line number and line contents each time its readline()
method is called. If a TextReader instance is pickled, all
attributes except the file object member are saved. When the
instance is unpickled, the file is reopened, and reading resumes from
the last location. The __setstate__() and
__getstate__() methods are used to implement this behavior.
```text

# illustrate __setstate__ and __getstate__ methods
# used in pickling.

class TextReader:
"Print and number lines in a text file."
def __init__(self,file):
self.file = file
self.fh = open(file,'r')
self.lineno = 0

def readline(self):
self.lineno = self.lineno + 1
line = self.fh.readline()
if not line:
return None
return "%d: %s" % (self.lineno,line[:-1])

# return data representation for pickled object
def __getstate__(self):
odict = self.__dict__ # get attribute dictionary
del odict['fh'] # remove filehandle entry
return odict

# restore object state from data representation generated
# by __getstate__
def __setstate__(self,dict):
fh = open(dict['file']) # reopen file
count = dict['lineno'] # read from file...
while count: # until line count is restored
fh.readline()
count = count - 1
dict['fh'] = fh # create filehandle entry
self.__dict__ = dict # make dict our attribute dictionary
```
A sample usage might be something like this:
```text

>>> import TextReader
>>> obj = TextReader.TextReader("TextReader.py")
>>> obj.readline()
'1: #!/usr/local/bin/python'
>>> # (more invocations of obj.readline() here)
... obj.readline()
'7: class TextReader:'
>>> import pickle
>>> pickle.dump(obj,open('save.p','w'))

(start another Python session)

>>> import pickle
>>> reader = pickle.load(open('save.p'))
>>> reader.readline()
'8: "Print and number lines in a text file."'
```


18.3.1 Player Objects

module-cd.html | module-cd.html | cd-parser-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.3.1 Player Objects
Player objects (returned by open()) have the following
methods:


7.3.1 Polling Objects

module-select.html | module-select.html | module-thread.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 7.3.1 Polling Objects
The poll() system call, supported on most Unix systems,
provides better scalability for network servers that service many,
many clients at the same time.
poll() scales better because the system call only
requires listing the file descriptors of interest, while select()
builds a bitmap, turns on bits for the fds of interest, and then
afterward the whole bitmap has to be linearly scanned again.
select() is O(highest file descriptor), while
poll() is O(number of file descriptors).


11.7.2 POP3 Example

pop3-objects.html | module-poplib.html | module-imaplib.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.7.2 POP3 Example
Here is a minimal example (without error checking) that opens a
mailbox and retrieves and prints all messages:
```text

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
for j in M.retr(i+1)[1]:
print j
```


11.7.1 POP3 Objects

module-poplib.html | module-poplib.html | pop3-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.7.1 POP3 Objects
All POP3 commands are represented by methods of the same name,
in lower-case; most return the response text sent by the server.
An POP3 instance has the following methods:


6.8.1 Popen3 and Popen4 Objects

module-popen2.html | module-popen2.html | module-time.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.8.1 Popen3 and Popen4 Objects
Instances of the Popen3 and Popen4 classes have the
following methods:
The following attributes are also available:


8.1.2 Module Contents

posix-large-files.html | module-posix.html | module-pwd.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 8.1.2 Module Contents
Module posix defines the following data item:


8.1.1 Large File Support

module-posix.html | module-posix.html | posix-contents.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 8.1.1 Large File Support
Several operating systems (including AIX, HPUX, Irix and Solaris)
provide support for files that are larger than 2 Gb from a C
programming model where int and long are 32-bit
values. This is typically accomplished by defining the relevant size
and offset types as 64-bit values. Such files are sometimes referred
to as large files.
Large file support is enabled in Python when the size of an
off_t is larger than a long and the long long
type is available and is at least as large as an off_t. Python
longs are then used to represent file sizes, offsets and other values
that can exceed the range of a Python int. It may be necessary to
configure and compile Python with certain compiler flags to enable
this mode. For example, it is enabled by default with recent versions
of Irix, but with Solaris 2.6 and 2.7 you need to do something like:
```text

CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
configure
```


3.20.1 PrettyPrinter Objects

module-pprint.html | module-pprint.html | module-repr.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.20.1 PrettyPrinter Objects
PrettyPrinter instances have the following methods:
The following methods provide the implementations for the
corresponding functions of the same names. Using these methods on an
instance is slightly more efficient since new PrettyPrinter
objects don't need to be created.