16.1 Built-in Module stdwin

node193.html node191.html node191.html node1.html node221.html
---
# 16.1 Built-in Module `stdwin`
This module defines several new object types and functions that
provide access to the functionality of STDWIN.
On Unix running X11, it can only be used if the `DISPLAY`
environment variable is set or an explicit `-display
displayname' argument is passed to the Python interpreter.
Functions have names that usually resemble their C STDWIN counterparts
with the initial `w' dropped.
Points are represented by pairs of integers; rectangles
by pairs of points.
For a complete description of STDWIN please refer to the documentation
of STDWIN for C programmers (aforementioned CWI report).
---
- 16.1.1 Functions Defined in Module `stdwin` (node193.html#SECTION001711000000000000000)
16.1.2 Window Objects (node194.html#SECTION001712000000000000000)
16.1.3 Drawing Objects (node195.html#SECTION001713000000000000000)
16.1.4 Menu Objects (node196.html#SECTION001714000000000000000)
16.1.5 Bitmap Objects (node197.html#SECTION001715000000000000000)
16.1.6 Text-edit Objects (node198.html#SECTION001716000000000000000)
16.1.7 Example (node199.html#SECTION001717000000000000000)
---
guido@cnri.reston.va.us


16.1.1 Functions Defined in Module stdwin

node194.html node192.html node192.html node1.html node221.html
---
## 16.1.1 Functions Defined in Module `stdwin`
The following functions are defined in the `stdwin` module:
---
node194.html node192.html node192.html node1.html node221.html
guido@cnri.reston.va.us


16.1.2 Window Objects

node195.html node192.html node193.html node1.html node221.html
---
## 16.1.2 Window Objects
Window objects are created by `stdwin.open()`. They are closed
by their `close()` method or when they are garbage-collected.
Window objects have the following methods:
---
node195.html node192.html node193.html node1.html node221.html
guido@cnri.reston.va.us


16.1.3 Drawing Objects

node196.html node192.html node194.html node1.html node221.html
---
## 16.1.3 Drawing Objects
Drawing objects are created exclusively by the window method
`begindrawing()`.
Only one drawing object can exist at any given time; the drawing object
must be deleted to finish drawing.
No drawing object may exist when
`stdwin.getevent()`
is called.
Drawing objects have the following methods:
---
node196.html node192.html node194.html node1.html node221.html
guido@cnri.reston.va.us


16.1.4 Menu Objects

node197.html node192.html node195.html node1.html node221.html
---
## 16.1.4 Menu Objects
A menu object represents a menu.
The menu is destroyed when the menu object is deleted.
The following methods are defined:
---
guido@cnri.reston.va.us


16.1.5 Bitmap Objects

node198.html node192.html node196.html node1.html node221.html
---
## 16.1.5 Bitmap Objects
A bitmap represents a rectangular array of bits.
The top left bit has coordinate (0, 0).
A bitmap can be drawn with the `bitmap` method of a drawing object.
Bitmaps are currently not available on the Macintosh.
The following methods are defined:
---
guido@cnri.reston.va.us


16.1.6 Text-edit Objects

node199.html node192.html node197.html node1.html node221.html
---
## 16.1.6 Text-edit Objects
A text-edit object represents a text-edit block.
For semantics, see the STDWIN documentation for C programmers.
The following methods exist:
---
node199.html node192.html node197.html node1.html node221.html
guido@cnri.reston.va.us


16.1.7 Example

node200.html node192.html node198.html node1.html node221.html
---
## 16.1.7 Example
Here is a minimal example of using STDWIN in Python.
It creates a window and draws the string ``Hello world'' in the top
left corner of the window.
The window will be correctly redrawn when covered and re-exposed.
The program quits when the close icon or menu item is requested.
```text
import stdwin
from stdwinevents import *

def main():
mywin = stdwin.open('Hello')
#
while 1:
(type, win, detail) = stdwin.getevent()
if type == WE_DRAW:
draw = win.begindrawing()
draw.text((0, 0), 'Hello, world')
del draw
elif type == WE_CLOSE:
break

main()
```
---
guido@cnri.reston.va.us


1 Introduction

node3.html lib.html node1.html node1.html node221.html
---
# 1 Introduction
The ``Python library'' contains several different kinds of components.
It contains data types that would normally be considered part of the
``core'' of a language, such as numbers and lists. For these types,
the Python language core defines the form of literals and places some
constraints on their semantics, but does not fully define the
semantics. (On the other hand, the language core does define
syntactic properties like the spelling and priorities of operators.)
The library also contains built-in functions and exceptions --
objects that can be used by all Python code without the need of an
`import` statement. Some of these are defined by the core
language, but many are not essential for the core semantics and are
only described here.
The bulk of the library, however, consists of a collection of modules.
There are many ways to dissect this collection. Some modules are
written in C and built in to the Python interpreter; others are
written in Python and imported in source form. Some modules provide
interfaces that are highly specific to Python, like printing a stack
trace; some provide interfaces that are specific to particular
operating systems, like socket I/O; others provide interfaces that are
specific to a particular application domain, like the World-Wide Web.
Some modules are avaiable in all versions and ports of Python; others
are only available when the underlying system supports or requires
them; yet others are available only when a particular configuration
option was chosen at the time when Python was compiled and installed.
This manual is organized ``from the inside out'': it first describes
the built-in data types, then the built-in functions and exceptions,
and finally the modules, grouped in chapters of related modules. The
ordering of the chapters as well as the ordering of the modules within
each chapter is roughly from most relevant to least important.
This means that if you start reading this manual from the start, and
skip to the next chapter when you get bored, you will get a reasonable
overview of the available modules and application areas that are
supported by the Python library. Of course, you don't have to
read it like a novel -- you can also browse the table of contents (in
front of the manual), or look for a specific function, module or term
in the index (in the back). And finally, if you enjoy learning about
random subjects, you choose a random page number (see module
`rand`) and read a section or two.
Let the show begin!
---
node3.html lib.html node1.html node1.html node221.html
guido@cnri.reston.va.us


Type Objects

node21.html node14.html node19.html node1.html node221.html
---
### Type Objects
Type objects represent the various object types. An object's type is
accessed by the built-in function `type()`. There are no special
operations on types. The standard module `types` defines names
for all standard built-in types.
Types are written like this: `<type 'int'>`.
---
guido@cnri.reston.va.us


16.2 Standard Module stdwinevents

node201.html node191.html node199.html node1.html node221.html
---
# 16.2 Standard Module `stdwinevents`
This module defines constants used by STDWIN for event types
(`WE_ACTIVATE` etc.), command codes (`WC_LEFT` etc.)
and selection types (`WS_PRIMARY` etc.).
Read the file for details.
Suggested usage is
```text
>>> from stdwinevents import *
>>>
```
---
guido@cnri.reston.va.us


16.3 Standard Module rect

node202.html node191.html node200.html node1.html node221.html
---
# 16.3 Standard Module `rect`
This module contains useful operations on rectangles.
A rectangle is defined as in module
`stdwin`:
a pair of points, where a point is a pair of integers.
For example, the rectangle
```text
(10, 20), (90, 80)
```
is a rectangle whose left, top, right and bottom edges are 10, 20, 90
and 80, respectively.
Note that the positive vertical axis points down (as in
`stdwin`).
The module defines the following objects:
---
node202.html node191.html node200.html node1.html node221.html
guido@cnri.reston.va.us


17 SGI IRIX Specific Services

node203.html lib.html node201.html node1.html node221.html
---
# 17 SGI IRIX Specific Services
The modules described in this chapter provide interfaces to features
that are unique to SGI's IRIX operating system (versions 4 and 5).
---
- 17.1 Built-in Module `al` (node203.html#SECTION001810000000000000000)
- 17.1.1 Configuration Objects (node204.html#SECTION001811000000000000000)
17.1.2 Port Objects (node205.html#SECTION001812000000000000000)
17.2 Standard Module `AL` (node206.html#SECTION001820000000000000000)
17.3 Built-in Module `cd` (node207.html#SECTION001830000000000000000)
17.4 Built-in Module `fl` (node208.html#SECTION001840000000000000000)
- 17.4.1 Functions Defined in Module `fl` (node209.html#SECTION001841000000000000000)
17.4.2 Form Objects (node210.html#SECTION001842000000000000000)
17.4.3 FORMS Objects (node211.html#SECTION001843000000000000000)
17.5 Standard Module `FL` (node212.html#SECTION001850000000000000000)
17.6 Standard Module `flp` (node213.html#SECTION001860000000000000000)
17.7 Built-in Module `fm` (node214.html#SECTION001870000000000000000)
17.8 Built-in Module `gl` (node215.html#SECTION001880000000000000000)
17.9 Standard Modules `GL` and `DEVICE` (node216.html#SECTION001890000000000000000)
17.10 Built-in Module `imgfile` (node217.html#SECTION0018100000000000000000)
---
guido@cnri.reston.va.us


17.1 Built-in Module al

node204.html node202.html node202.html node1.html node221.html
---
# 17.1 Built-in Module `al`
This module provides access to the audio facilities of the SGI Indy
and Indigo workstations. See section 3A of the IRIX man pages for
details. You'll need to read those man pages to understand what these
functions do! Some of the functions are not available in IRIX
releases before 4.0.5. Again, see the manual to check whether a
specific function is available on your platform.
All functions and methods defined in this module are equivalent to
the C functions with `AL' prefixed to their name.
Symbolic constants from the C header file ``<audio.h>`' are defined
in the standard module `AL`, see below.
Warning: the current version of the audio library may dump core
when bad argument values are passed rather than returning an error
status. Unfortunately, since the precise circumstances under which
this may happen are undocumented and hard to check, the Python
interface can provide no protection against this kind of problems.
(One example is specifying an excessive queue size -- there is no
documented upper limit.)
The module defines the following functions:
---
- 17.1.1 Configuration Objects (node204.html#SECTION001811000000000000000)
17.1.2 Port Objects (node205.html#SECTION001812000000000000000)
---
node204.html node202.html node202.html node1.html node221.html
guido@cnri.reston.va.us


17.1.1 Configuration Objects

node205.html node203.html node203.html node1.html node221.html
---
## 17.1.1 Configuration Objects
Configuration objects (returned by `al.newconfig()` have the
following methods:
---
guido@cnri.reston.va.us


17.1.2 Port Objects

node206.html node203.html node204.html node1.html node221.html
---
## 17.1.2 Port Objects
Port objects (returned by `al.openport()` have the following
methods:
---
guido@cnri.reston.va.us


17.2 Standard Module AL

node207.html node202.html node205.html node1.html node221.html
---
# 17.2 Standard Module `AL`
This module defines symbolic constants needed to use the built-in
module `al` (see above); they are equivalent to those defined in
the C header file ``<audio.h>`' except that the name prefix
`AL_' is omitted. Read the module source for a complete list of
the defined names. Suggested use:
```text
import al
from AL import *
```
---
guido@cnri.reston.va.us


17.3 Built-in Module cd

node208.html node202.html node206.html node1.html node221.html
---
# 17.3 Built-in Module `cd`
This module provides an interface to the Silicon Graphics CD library.
It is available only on Silicon Graphics systems.
The way the library works is as follows. A program opens the CD-ROM
device with `cd.open()` and creates a parser to parse the data
from the CD with `cd.createparser()`. The object returned by
`cd.open()` can be used to read data from the CD, but also to get
status information for the CD-ROM device, and to get information about
the CD, such as the table of contents. Data from the CD is passed to
the parser, which parses the frames, and calls any callback
functions that have previously been added.
An audio CD is divided into tracks or programs (the terms
are used interchangeably). Tracks can be subdivided into
indices. An audio CD contains a table of contents which
gives the starts of the tracks on the CD. Index 0 is usually the
pause before the start of a track. The start of the track as given by
the table of contents is normally the start of index 1.
Positions on a CD can be represented in two ways. Either a frame
number or a tuple of three values, minutes, seconds and frames. Most
functions use the latter representation. Positions can be both
relative to the beginning of the CD, and to the beginning of the
track.
Module `cd` defines the following functions and constants:
The module defines the following variables:
The following variables are states as returned by `getstatus`:
Player objects (returned by `cd.open()`) have the following
methods:
Parser objects (returned by `cd.createparser()`) have the
following methods:
---
node208.html node202.html node206.html node1.html node221.html
guido@cnri.reston.va.us


17.4 Built-in Module fl

node209.html node202.html node207.html node1.html node221.html
---
# 17.4 Built-in Module `fl`
This module provides an interface to the FORMS Library by Mark
Overmars. The source for the library can be retrieved by anonymous
ftp from host `ftp.cs.ruu.nl', directory ``SGI/FORMS`'. It
was last tested with version 2.0b.
Most functions are literal translations of their C equivalents,
dropping the initial `fl_' from their name. Constants used by
the library are defined in module `FL` described below.
The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
form are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
`fl_addto_form` and `fl_end_form`, and the equivalent of
`fl_bgn_form` is called `fl.make_form`.
Watch out for the somewhat confusing terminology: FORMS uses the word
object for the buttons, sliders etc. that you can place in a form.
In Python, `object' means any value. The Python interface to FORMS
introduces two new Python object types: form objects (representing an
entire form) and FORMS objects (representing one button, slider etc.).
Hopefully this isn't too confusing...
There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python. The FORMS
interface to GL event handling is available, though, so you can mix
FORMS with pure GL windows.
Please note: importing `fl` implies a call to the GL function
`foreground()` and to the FORMS routine `fl_init()`.
---
- 17.4.1 Functions Defined in Module `fl` (node209.html#SECTION001841000000000000000)
17.4.2 Form Objects (node210.html#SECTION001842000000000000000)
17.4.3 FORMS Objects (node211.html#SECTION001843000000000000000)
---
guido@cnri.reston.va.us


17.4.1 Functions Defined in Module fl

node210.html node208.html node208.html node1.html node221.html
---
## 17.4.1 Functions Defined in Module `fl`
Module `fl` defines the following functions. For more information
about what they do, see the description of the equivalent C function
in the FORMS documentation:
---
node210.html node208.html node208.html node1.html node221.html
guido@cnri.reston.va.us


The Null Object

node22.html node14.html node20.html node1.html node221.html
---
### The Null Object
This object is returned by functions that don't explicitly return a
value. It supports no special operations. There is exactly one null
object, named `None` (a built-in name).
It is written as `None`.
---
guido@cnri.reston.va.us


17.4.2 Form Objects

node211.html node208.html node209.html node1.html node221.html
---
## 17.4.2 Form Objects
Form objects (returned by `fl.make_form()` above) have the
following methods. Each method corresponds to a C function whose name
is prefixed with `fl_'; and whose first argument is a form
pointer; please refer to the official FORMS documentation for
descriptions.
All the `add_...' functions return a Python object representing
the FORMS object. Methods of FORMS objects are described below. Most
kinds of FORMS object also have some methods specific to that kind;
these methods are listed here.
Form objects have the following data attributes; see the FORMS
documentation:
---
node211.html node208.html node209.html node1.html node221.html
guido@cnri.reston.va.us


17.4.3 FORMS Objects

node212.html node208.html node210.html node1.html node221.html
---
## 17.4.3 FORMS Objects
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
FORMS objects have these data attributes; see the FORMS documentation:
---
guido@cnri.reston.va.us


17.5 Standard Module FL

node213.html node202.html node211.html node1.html node221.html
---
# 17.5 Standard Module `FL`
This module defines symbolic constants needed to use the built-in
module `fl` (see above); they are equivalent to those defined in
the C header file ``<forms.h>`' except that the name prefix
`FL_' is omitted. Read the module source for a complete list of
the defined names. Suggested use:
```text
import fl
from FL import *
```
---
guido@cnri.reston.va.us


17.6 Standard Module flp

node214.html node202.html node212.html node1.html node221.html
---
# 17.6 Standard Module `flp`
This module defines functions that can read form definitions created
by the `form designer' (`fdesign`) program that comes with the
FORMS library (see module `fl` above).
For now, see the file ``flp.doc`' in the Python library source
directory for a description.
XXX A complete description should be inserted here!
---
guido@cnri.reston.va.us


17.7 Built-in Module fm

node215.html node202.html node213.html node1.html node221.html
---
# 17.7 Built-in Module `fm`
This module provides access to the IRIS Font Manager library.
It is available only on Silicon Graphics machines.
See also: 4Sight User's Guide, Section 1, Chapter 5: Using the IRIS
Font Manager.
This is not yet a full interface to the IRIS Font Manager.
Among the unsupported features are: matrix operations; cache
operations; character operations (use string operations instead); some
details of font info; individual glyph metrics; and printer matching.
It supports the following operations:
Font handle objects support the following operations:
---
node215.html node202.html node213.html node1.html node221.html
guido@cnri.reston.va.us


17.8 Built-in Module gl

node216.html node202.html node214.html node1.html node221.html
---
# 17.8 Built-in Module `gl`
This module provides access to the Silicon Graphics
Graphics Library.
It is available only on Silicon Graphics machines.
Warning:
Some illegal calls to the GL library cause the Python interpreter to dump
core.
In particular, the use of most GL calls is unsafe before the first
window is opened.
The module is too large to document here in its entirety, but the
following should help you to get started.
The parameter conventions for the C functions are translated to Python as
follows:
- All (short, long, unsigned) int values are represented by Python
integers.All float and double values are represented by Python floating point
numbers.
In most cases, Python integers are also allowed.All arrays are represented by one-dimensional Python lists.
In most cases, tuples are also allowed.All string and character arguments are represented by Python strings,
for instance,
`winopen('Hi There!')`
and
`rotate(900, 'z')`.All (short, long, unsigned) integer arguments or return values that are
only used to specify the length of an array argument are omitted.
For example, the C call
```text
lmdef(deftype, index, np, props)
```
is translated to Python as
```text
lmdef(deftype, index, props)
```
Output arguments are omitted from the argument list; they are
transmitted as function return values instead.
If more than one value must be returned, the return value is a tuple.
If the C function has both a regular return value (that is not omitted
because of the previous rule) and an output argument, the return value
comes first in the tuple.
Examples: the C call
```text
getmcolor(i, &red, &green, &blue)
```
is translated to Python as
```text
red, green, blue = getmcolor(i)
```
The following functions are non-standard or have special argument
conventions:
Here is a tiny but complete example GL program in Python:
```text
import gl, GL, time

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

main()
```
---
node216.html node202.html node214.html node1.html node221.html
guido@cnri.reston.va.us


17.9 Standard Modules GL and DEVICE

node217.html node202.html node215.html node1.html node221.html
---
# 17.9 Standard Modules `GL` and `DEVICE`
These modules define the constants used by the Silicon Graphics
Graphics Library
that C programmers find in the header files
``<gl/gl.h>`'
and
``<gl/device.h>`'.
Read the module source files for details.
---
guido@cnri.reston.va.us


17.10 Built-in Module imgfile

node218.html node202.html node216.html node1.html node221.html
---
# 17.10 Built-in Module `imgfile`
The imgfile module allows python programs to access SGI imglib image
files (also known as ``.rgb`' files). The module is far from
complete, but is provided anyway since the functionality that there is
is enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:
---
node218.html node202.html node216.html node1.html node221.html
guido@cnri.reston.va.us


18 SunOS Specific Services

node219.html lib.html node217.html node1.html node221.html
---
# 18 SunOS Specific Services
The modules described in this chapter provide interfaces to features
that are unique to the SunOS operating system (versions 4 and 5; the
latter is also known as Solaris version 2).
---
- 18.1 Built-in Module `sunaudiodev` (node219.html#SECTION001910000000000000000)
- 18.1.1 Audio Device Objects (node220.html#SECTION001911000000000000000)
---
guido@cnri.reston.va.us


18.1 Built-in Module sunaudiodev

node220.html node218.html node218.html node1.html node221.html
---
# 18.1 Built-in Module `sunaudiodev`
This module allows you to access the sun audio interface. The sun
audio hardware is capable of recording and playing back audio data
in U-LAW format with a sample rate of 8K per second. A full
description can be gotten with `man audio'.
The module defines the following variables and functions:
---
- 18.1.1 Audio Device Objects (node220.html#SECTION001911000000000000000)
---
guido@cnri.reston.va.us


File Objects

node23.html node14.html node21.html node1.html node221.html
---
### File Objects
File objects are implemented using C's `stdio` package and can be
created with the built-in function `open()` described under
Built-in Functions below. They are also returned by some other
built-in functions and methods, e.g. `posix.popen()` and
`posix.fdopen()` and the `makefile()` method of socket
objects.
When a file operation fails for an I/O-related reason, the exception
`IOError` is raised. This includes situations where the
operation is not defined for some reason, like `seek()` on a tty
device or writing a file opened for reading.
Files have the following methods:
---
node23.html node14.html node21.html node1.html node221.html
guido@cnri.reston.va.us


18.1.1 Audio Device Objects

node221.html node219.html node219.html node1.html node221.html
---
## 18.1.1 Audio Device Objects
The audio device objects are returned by `open` define the
following methods (except `control` objects which only provide
getinfo, setinfo and drain):
There is a companion module, `SUNAUDIODEV`, which defines useful
symbolic constants like `MIN_GAIN`, `MAX_GAIN`,
`SPEAKER`, etc. The names of
the constants are the same names as used in the C include file
``<sun/audioio.h>`', with the leading string `AUDIO_' stripped.
Useability of the control device is limited at the moment, since there
is no way to use the ``wait for something to happen'' feature the
device provides.
---
node221.html node219.html node219.html node1.html node221.html
guido@cnri.reston.va.us


Index

node222.html lib.html node220.html node1.html
---
## Index
---
guido@cnri.reston.va.us


About this document ...

lib.html node221.html node1.html node221.html
---
# About this document ...
Python Library Reference
This document was generated using the LaTeX2HTML (http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/) translator Version 96.1 (Feb 5, 1996) Copyright © 1993, 1994, 1995, 1996, Nikos Drakos (http://cbl.leeds.ac.uk/nikos/personal.html), Computer Based Learning Unit, University of Leeds.
The command line arguments were:
latex2html -address guido@cnri.reston.va.us lib.tex.
The translation was initiated by Fred L. Drake on Fri Dec 6 09:14:53 EST 1996
---
guido@cnri.reston.va.us


Internal Objects

node24.html node14.html node22.html node1.html node221.html
---
### Internal Objects
(See the Python Reference Manual for these.)
---
guido@cnri.reston.va.us


2.1.8 Special Attributes

node25.html node4.html node23.html node1.html node221.html
---
## 2.1.8 Special Attributes
The implementation adds a few special read-only attributes to several
object types, where they are relevant:
- `x .__dict__` is a dictionary of some sort used to store an
object's (writable) attributes;`x .__methods__` lists the methods of many built-in object types,
e.g., `[].__methods__` yields
`['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']`;`x .__members__` lists data attributes;`x .__class__` is the class to which a class instance belongs;`x .__bases__` is the tuple of base classes of a class object.
---
guido@cnri.reston.va.us


2.2 Built-in Exceptions

node26.html node3.html node24.html node1.html node221.html
---
# 2.2 Built-in Exceptions
Exceptions are string objects. Two distinct string objects with the
same value are different exceptions. This is done to force programmers
to use exception names rather than their string value when specifying
exception handlers. The string value of all built-in exceptions is
their name, but this is not a requirement for user-defined exceptions
or exceptions defined by library modules.
The following exceptions can be generated by the interpreter or
built-in functions. Except where mentioned, they have an `associated
value' indicating the detailed cause of the error. This may be a
string or a tuple containing several items of information (e.g., an
error code and a string explaining the code).
User code can raise built-in exceptions. This can be used to test an
exception handler or to report an error condition `just like' the
situation in which the interpreter raises the same exception; but
beware that there is nothing to prevent user code from raising an
inappropriate error.
---
node26.html node3.html node24.html node1.html node221.html
guido@cnri.reston.va.us


2.3 Built-in Functions

node27.html node3.html node25.html node1.html node221.html
---
# 2.3 Built-in Functions
The Python interpreter has a number of functions built into it that
are always available. They are listed here in alphabetical order.
---
node27.html node3.html node25.html node1.html node221.html
guido@cnri.reston.va.us


3 Python Services

node28.html lib.html node26.html node1.html node221.html
---
# 3 Python Services
The modules described in this chapter provide a wide range of services
related to the Python interpreter and its interaction with its
environment. Here's an overview:
---
- 3.1 Built-in Module `sys` (node28.html#SECTION00410000000000000000)
3.2 Standard Module `types` (node29.html#SECTION00420000000000000000)
3.3 Standard Module `traceback` (node30.html#SECTION00430000000000000000)
3.4 Standard Module `pickle` (node31.html#SECTION00440000000000000000)
3.5 Standard Module `shelve` (node32.html#SECTION00450000000000000000)
3.6 Standard Module `copy` (node33.html#SECTION00460000000000000000)
3.7 Built-in Module `marshal` (node34.html#SECTION00470000000000000000)
3.8 Built-in Module `imp` (node35.html#SECTION00480000000000000000)
- 3.8.1 Examples (node36.html#SECTION00481000000000000000)
3.9 Built-in Module `parser` (node37.html#SECTION00490000000000000000)
- 3.9.1 Creating AST Objects (node38.html#SECTION00491000000000000000)
3.9.2 Converting AST Objects (node39.html#SECTION00492000000000000000)
3.9.3 Queries on AST Objects (node40.html#SECTION00493000000000000000)
3.9.4 Exceptions and Error Handling (node41.html#SECTION00494000000000000000)
3.9.5 AST Objects (node42.html#SECTION00495000000000000000)
3.9.6 Examples (node43.html#SECTION00496000000000000000)
- Emulation of `compile()` (node44.html#SECTION00496100000000000000)
Information Discovery (node45.html#SECTION00496200000000000000)
3.10 Built-in Module `__builtin__` (node46.html#SECTION004100000000000000000)
3.11 Built-in Module `__main__` (node47.html#SECTION004110000000000000000)
---
guido@cnri.reston.va.us


3.1 Built-in Module sys

node29.html node27.html node27.html node1.html node221.html
---
# 3.1 Built-in Module `sys`
This module provides access to some variables used or maintained by the
interpreter and to functions that interact strongly with the interpreter.
It is always available.
---
node29.html node27.html node27.html node1.html node221.html
guido@cnri.reston.va.us


3.2 Standard Module types

node30.html node27.html node28.html node1.html node221.html
---
# 3.2 Standard Module `types`
This module defines names for all object types that are used by the
standard Python interpreter (but not for the types defined by various
extension modules). It is safe to use ```from types import *`'' --
the module does not export any other names besides the ones listed
here. New names exported by future versions of this module will
all end in `Type`.
Typical use is for functions that do different things depending on
their argument types, like the following:
```text
from types import *
def delete(list, item):
if type(item) is IntType:
del list[item]
else:
list.remove(item)
```
The module defines the following names:
---
node30.html node27.html node28.html node1.html node221.html
guido@cnri.reston.va.us


node4.html lib.html node2.html node1.html node221.html
---
# 2 Built-in Types, Exceptions and Functions
Names for built-in exceptions and functions are found in a separate
symbol table. This table is searched last when the interpreter looks
up the meaning of a name, so local and global
user-defined names can override built-in names. Built-in types are
described together here for easy reference.footnode.html#25
The tables in this chapter document the priorities of operators by
listing them in order of ascending priority (within a table) and
grouping operators that have the same priority in the same box.
Binary operators of the same priority group from left to right.
(Unary operators group from right to left, but there you have no real
choice.) See Chapter 5 of the Python Reference Manual for the
complete picture on operator priorities.
---
- 2.1 Built-in Types (node4.html#SECTION00310000000000000000)
- 2.1.1 Truth Value Testing (node5.html#SECTION00311000000000000000)
2.1.2 Boolean Operations (node6.html#SECTION00312000000000000000)
2.1.3 Comparisons (node7.html#SECTION00313000000000000000)
2.1.4 Numeric Types (node8.html#SECTION00314000000000000000)
- Bit-string Operations on Integer Types (node9.html#SECTION00314100000000000000)
2.1.5 Sequence Types (node10.html#SECTION00315000000000000000)
- More String Operations (node11.html#SECTION00315100000000000000)
Mutable Sequence Types (node12.html#SECTION00315200000000000000)
2.1.6 Mapping Types (node13.html#SECTION00316000000000000000)
2.1.7 Other Built-in Types (node14.html#SECTION00317000000000000000)
- Modules (node15.html#SECTION00317100000000000000)
Classes and Class Instances (node16.html#SECTION00317200000000000000)
Functions (node17.html#SECTION00317300000000000000)
Methods (node18.html#SECTION00317400000000000000)
Code Objects (node19.html#SECTION00317500000000000000)
Type Objects (node20.html#SECTION00317600000000000000)
The Null Object (node21.html#SECTION00317700000000000000)
File Objects (node22.html#SECTION00317800000000000000)
Internal Objects (node23.html#SECTION00317900000000000000)
2.1.8 Special Attributes (node24.html#SECTION00318000000000000000)
2.2 Built-in Exceptions (node25.html#SECTION00320000000000000000)
2.3 Built-in Functions (node26.html#SECTION00330000000000000000)
---
guido@cnri.reston.va.us


3.3 Standard Module traceback

node31.html node27.html node29.html node1.html node221.html
---
# 3.3 Standard Module `traceback`
This module provides a standard interface to format and print stack
traces of Python programs. It exactly mimics the behavior of the
Python interpreter when it prints a stack trace. This is useful when
you want to print stack traces under program control, e.g. in a
``wrapper'' around the interpreter.
The module uses traceback objects -- this is the object type
that is stored in the variables `sys.exc_traceback` and
`sys.last_traceback`.
The module defines the following functions:
---
guido@cnri.reston.va.us


3.4 Standard Module pickle

node32.html node27.html node30.html node1.html node221.html
---
# 3.4 Standard Module `pickle`
The `pickle` module implements a basic but powerful algorithm for
``pickling'' (a.k.a. serializing, marshalling or flattening) nearly
arbitrary Python objects. This is the act of converting objects to a
stream of bytes (and back: ``unpickling'').
This is a more primitive notion than
persistency -- although `pickle` reads and writes file objects,
it does not handle the issue of naming persistent objects, nor the
(even more complicated) area of concurrent access to persistent
objects. The `pickle` module can transform a complex object into
a byte stream and it can transform the byte stream into an object with
the same internal structure. The most obvious thing to do with these
byte streams is to write them onto a file, but it is also conceivable
to send them across a network or store them in a database. The module
`shelve` provides a simple interface to pickle and unpickle
objects on ``dbm''-style database files.
Unlike the built-in module `marshal`, `pickle` handles the
following correctly:
- recursive objects (objects containing references to themselves)object sharing (references to the same object in different places)user-defined classes and their instances
The data format used by `pickle` is Python-specific. This has
the advantage that there are no restrictions imposed by external
standards such as CORBA (which probably can't represent pointer
sharing or recursive objects); however it means that non-Python
programs may not be able to reconstruct pickled Python objects.
The `pickle` data format uses a printable ASCII representation.
This is slightly more voluminous than a binary representation.
However, small integers actually take less space when
represented as minimal-size decimal strings than when represented as
32-bit binary numbers, and strings are only much longer if they
contain many control characters or 8-bit characters. The big
advantage of using printable ASCII (and of some other characteristics
of `pickle`'s representation) is that for debugging or recovery
purposes it is possible for a human to read the pickled file with a
standard text editor. (I could have gone a step further and used a
notation like S-expressions, but the parser
(currently written in Python) would have been
considerably more complicated and slower, and the files would probably
have become much larger.)
The `pickle` module doesn't handle code objects, which the
`marshal` module does. I suppose `pickle` could, and maybe
it should, but there's probably no great need for it right now (as
long as `marshal` continues to be used for reading and writing
code objects), and at least this avoids the possibility of smuggling
Trojan horses into a program.
For the benefit of persistency modules written using `pickle`, it
supports the notion of a reference to an object outside the pickled
data stream. Such objects are referenced by a name, which is an
arbitrary string of printable ASCII characters. The resolution of
such names is not defined by the `pickle` module -- the
persistent object module will have to implement a method
`persistent_load`. To write references to persistent objects,
the persistent module must define a method `persistent_id` which
returns either `None` or the persistent ID of the object.
There are some restrictions on the pickling of class instances.
First of all, the class must be defined at the top level in a module.
Next, it must normally be possible to create class instances by
calling the class without arguments. Usually, this is best
accomplished by providing default values for all arguments to its
`__init__` method (if it has one). If this is undesirable, the
class can define a method `__getinitargs__()`, which should
return a tuple containing the arguments to be passed to the
class constructor (`__init__()`).
Classes can further influence how their instances are pickled -- if the class
defines the method `__getstate__()`, it is called and the return
state is pickled as the contents for the instance, and if the class
defines the method `__setstate__()`, it is called with the
unpickled state. (Note that these methods can also be used to
implement copying class instances.) If there is no
`__getstate__()` method, the instance's `__dict__` is
pickled. If there is no `__setstate__()` method, the pickled
object must be a dictionary and its items are assigned to the new
instance's dictionary. (If a class defines both `__getstate__()`
and `__setstate__()`, the state object needn't be a dictionary
-- these methods can do what they want.) This protocol is also used
by the shallow and deep copying operations defined in the `copy`
module.
Note that when class instances are pickled, their class's code and
data are not pickled along with them. Only the instance data are
pickled. This is done on purpose, so you can fix bugs in a class or
add methods and still load objects that were created with an earlier
version of the class. If you plan to have long-lived objects that
will see many versions of a class, it may be worthwhile to put a version
number in the objects so that suitable conversions can be made by the
class's `__setstate__()` method.
When a class itself is pickled, only its name is pickled -- the class
definition is not pickled, but re-imported by the unpickling process.
Therefore, the restriction that the class must be defined at the top
level in a module applies to pickled classes as well.
The interface can be summarized as follows.
To pickle an object `x` onto a file `f`, open for writing:
```text
p = pickle.Pickler(f)
p.dump(x)
```
A shorthand for this is:
```text
pickle.dump(x, f)
```
To unpickle an object `x` from a file `f`, open for reading:
```text
u = pickle.Unpickler(f)
x = u.load()
```
A shorthand is:
```text
x = pickle.load(f)
```
The `Pickler` class only calls the method `f.write` with a
string argument. The `Unpickler` calls the methods `f.read`
(with an integer argument) and `f.readline` (without argument),
both returning a string. It is explicitly allowed to pass non-file
objects here, as long as they have the right methods.
The following types can be pickled:
- `None`integers, long integers, floating point numbersstringstuples, lists and dictionaries containing only picklable objectsclasses that are defined at the top level in a moduleinstances of such classes whose `__dict__` or
`__setstate__()` is picklable
Attempts to pickle unpicklable objects will raise the
`PicklingError` exception; when this happens, an unspecified
number of bytes may have been written to the file.
It is possible to make multiple calls to the `dump()` method of
the same `Pickler` instance. These must then be matched to the
same number of calls to the `load()` instance of the
corresponding `Unpickler` instance. If the same object is
pickled by multiple `dump()` calls, the `load()` will all
yield references to the same object. Warning: this is intended
for pickling multiple objects without intervening modifications to the
objects or their parts. If you modify an object and then pickle it
again using the same `Pickler` instance, the object is not
pickled again -- a reference to it is pickled and the
`Unpickler` will return the old value, not the modified one.
(There are two problems here: (a) detecting changes, and (b)
marshalling a minimal set of changes. I have no answers. Garbage
Collection may also become a problem here.)
Apart from the `Pickler` and `Unpickler` classes, the
module defines the following functions, and an exception:
---
node32.html node27.html node30.html node1.html node221.html
guido@cnri.reston.va.us


3.5 Standard Module shelve

node33.html node27.html node31.html node1.html node221.html
---
# 3.5 Standard Module `shelve`
A ``shelf'' is a persistent, dictionary-like object. The difference
with ``dbm'' databases is that the values (not the keys!) in a shelf
can be essentially arbitrary Python objects -- anything that the
`pickle` module can handle. This includes most class instances,
recursive data types, and objects containing lots of shared
sub-objects. The keys are ordinary strings.
To summarize the interface (`key` is a string, `data` is an
arbitrary object):
```text
import shelve

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

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

d.close() # close it
```
Restrictions:
- The choice of which database package will be used (e.g. dbm or gdbm)
depends on which interface is available. Therefore it isn't safe to
open the database directly using dbm. The database is also
(unfortunately) subject to the limitations of dbm, if it is used --
this means that (the pickled representation of) the objects stored in
the database should be fairly small, and in rare cases key collisions
may cause the database to refuse updates.Dependent on the implementation, closing a persistent dictionary may
or may not be necessary to flush changes to disk.The `shelve` module does not support concurrent read/write
access to shelved objects. (Multiple simultaneous read accesses are
safe.) When a program has a shelf open for writing, no other program
should have it open for reading or writing. Unix file locking can
be used to solve this, but this differs across Unix versions and
requires knowledge about the database implementation used.
---
guido@cnri.reston.va.us


3.6 Standard Module copy

node34.html node27.html node32.html node1.html node221.html
---
# 3.6 Standard Module `copy`
This module provides generic (shallow and deep) copying operations.
Interface summary:
```text
import copy

x = copy.copy(y) # make a shallow copy of y
x = copy.deepcopy(y) # make a deep copy of y
```
For module specific errors, `copy.error` is raised.
The difference between shallow and deep copying is only relevant for
compound objects (objects that contain other objects, like lists or
class instances):
- A shallow copy constructs a new compound object and then (to the
extent possible) inserts references into it to the objects found
in the original.A deep copy constructs a new compound object and then,
recursively, inserts copies into it of the objects found in the
original.
Two problems often exist with deep copy operations that don't exist
with shallow copy operations:
- Recursive objects (compound objects that, directly or indirectly,
contain a reference to themselves) may cause a recursive loop.Because deep copy copies everything it may copy too much, e.g.\
administrative data structures that should be shared even between
copies.
Python's `deepcopy()` operation avoids these problems by:
- keeping a table of objects already copied during the current
copying pass; andletting user-defined classes override the copying operation or the
set of components copied.
This version does not copy types like module, class, function, method,
nor stack trace, stack frame, nor file, socket, window, nor array, nor
any similar types.
Classes can use the same interfaces to control copying that they use
to control pickling: they can define methods called
`__getinitargs__()`, `__getstate__()` and
`__setstate__()`. See the description of module `pickle`
for information on these methods.
---
guido@cnri.reston.va.us


3.7 Built-in Module marshal

node35.html node27.html node33.html node1.html node221.html
---
# 3.7 Built-in Module `marshal`
This module contains functions that can read and write Python
values in a binary format. The format is specific to Python, but
independent of machine architecture issues (e.g., you can write a
Python value to a file on a PC, transport the file to a Sun, and read
it back there). Details of the format are undocumented on purpose;
it may change between Python versions (although it rarely does).footnode.html#1971
This is not a general ``persistency'' module. For general persistency
and transfer of Python objects through RPC calls, see the modules
`pickle` and `shelve`. The `marshal` module exists
mainly to support reading and writing the ``pseudo-compiled'' code for
Python modules of `.pyc' files.
Not all Python object types are supported; in general, only objects
whose value is independent from a particular invocation of Python can
be written and read by this module. The following types are supported:
`None`, integers, long integers, floating point numbers,
strings, tuples, lists, dictionaries, and code objects, where it
should be understood that tuples, lists and dictionaries are only
supported as long as the values contained therein are themselves
supported; and recursive lists and dictionaries should not be written
(they will cause infinite loops).
Caveat: On machines where C's `long int` type has more than
32 bits (such as the DEC Alpha), it
is possible to create plain Python integers that are longer than 32
bits. Since the current `marshal` module uses 32 bits to
transfer plain Python integers, such values are silently truncated.
This particularly affects the use of very long integer literals in
Python modules -- these will be accepted by the parser on such
machines, but will be silently be truncated when the module is read
from the `.pyc` instead.footnode.html#2020
There are functions that read/write files as well as functions
operating on strings.
The module defines these functions:
---
node35.html node27.html node33.html node1.html node221.html
guido@cnri.reston.va.us


3.8 Built-in Module imp

node36.html node27.html node34.html node1.html node221.html
---
# 3.8 Built-in Module `imp`
This module provides an interface to the mechanisms used to implement
the `import` statement. It defines the following constants and
functions:
The following constants with integer values, defined in the module,
are used to indicate the search result of `imp.find_module`.
---
- 3.8.1 Examples (node36.html#SECTION00481000000000000000)
---
node36.html node27.html node34.html node1.html node221.html
guido@cnri.reston.va.us


3.8.1 Examples

node37.html node35.html node35.html node1.html node221.html
---
## 3.8.1 Examples
The following function emulates the default import statement:
```text
import imp
import sys

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

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

# See if it's a built-in module.
m = imp.init_builtin(name)
if m:
return m

# See if it's a frozen module.
m = imp.init_frozen(name)
if m:
return m

# Search the default path (i.e. sys.path).
fp, pathname, (suffix, mode, type) = imp.find_module(name)

# See what we got.
try:
if type == imp.C_EXTENSION:
return imp.load_dynamic(name, pathname)
if type == imp.PY_SOURCE:
return imp.load_source(name, pathname, fp)
if type == imp.PY_COMPILED:
return imp.load_compiled(name, pathname, fp)

# Shouldn't get here at all.
raise ImportError, '%s: unknown module type (%d)' % (name, type)
finally:
# Since we may exit via an exception, close fp explicitly.
fp.close()
```
---
guido@cnri.reston.va.us


3.9 Built-in Module parser

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


3.9.1 Creating AST Objects

node39.html node37.html node37.html node1.html node221.html
---
## 3.9.1 Creating AST Objects
AST objects may be created from source code or from a parse tree.
When creating an AST object from source, different functions are used
to create the `'eval'` and `'exec'` forms.
---
node39.html node37.html node37.html node1.html node221.html
guido@cnri.reston.va.us


3.9.2 Converting AST Objects

node40.html node37.html node38.html node1.html node221.html
---
## 3.9.2 Converting AST Objects
AST objects, regardless of the input used to create them, may be
converted to parse trees represented as list- or tuple- trees, or may
be compiled into executable code objects. Parse trees may be
extracted with or without line numbering information.
---
node40.html node37.html node38.html node1.html node221.html
guido@cnri.reston.va.us


2.1 Built-in Types

node5.html node3.html node3.html node1.html node221.html
---
# 2.1 Built-in Types
The following sections describe the standard types that are built into
the interpreter. These are the numeric types, sequence types, and
several others, including types themselves. There is no explicit
Boolean type; use integers instead.
Some operations are supported by several object types; in particular,
all objects can be compared, tested for truth value, and converted to
a string (with the ``...`` notation). The latter conversion is
implicitly used when an object is written by the `print` statement.
---
- 2.1.1 Truth Value Testing (node5.html#SECTION00311000000000000000)
2.1.2 Boolean Operations (node6.html#SECTION00312000000000000000)
2.1.3 Comparisons (node7.html#SECTION00313000000000000000)
2.1.4 Numeric Types (node8.html#SECTION00314000000000000000)
- Bit-string Operations on Integer Types (node9.html#SECTION00314100000000000000)
2.1.5 Sequence Types (node10.html#SECTION00315000000000000000)
- More String Operations (node11.html#SECTION00315100000000000000)
Mutable Sequence Types (node12.html#SECTION00315200000000000000)
2.1.6 Mapping Types (node13.html#SECTION00316000000000000000)
2.1.7 Other Built-in Types (node14.html#SECTION00317000000000000000)
- Modules (node15.html#SECTION00317100000000000000)
Classes and Class Instances (node16.html#SECTION00317200000000000000)
Functions (node17.html#SECTION00317300000000000000)
Methods (node18.html#SECTION00317400000000000000)
Code Objects (node19.html#SECTION00317500000000000000)
Type Objects (node20.html#SECTION00317600000000000000)
The Null Object (node21.html#SECTION00317700000000000000)
File Objects (node22.html#SECTION00317800000000000000)
Internal Objects (node23.html#SECTION00317900000000000000)
2.1.8 Special Attributes (node24.html#SECTION00318000000000000000)
---
guido@cnri.reston.va.us


3.9.3 Queries on AST Objects

node41.html node37.html node39.html node1.html node221.html
---
## 3.9.3 Queries on AST Objects
Two functions are provided which allow an application to determine if
an AST was create as an expression or a suite. Neither of these
functions can be used to determine if an AST was created from source
code via `expr()` or `suite()` or from a parse tree via
`sequence2ast()`.
---
guido@cnri.reston.va.us


3.9.4 Exceptions and Error Handling

node42.html node37.html node40.html node1.html node221.html
---
## 3.9.4 Exceptions and Error Handling
The parser module defines a single exception, but may also pass other
built-in exceptions from other portions of the Python runtime
environment. See each function for information about the exceptions
it can raise.
Note that the functions `compileast()`, `expr()`, and
`suite()` may throw exceptions which are normally thrown by the
parsing and compilation process. These include the built in
exceptions `MemoryError`, `OverflowError`,
`SyntaxError`, and `SystemError`. In these cases, these
exceptions carry all the meaning normally associated with them. Refer
to the descriptions of each function for detailed information.
---
guido@cnri.reston.va.us


3.9.5 AST Objects

node43.html node37.html node41.html node1.html node221.html
---
## 3.9.5 AST Objects
AST objects returned by `expr()`, `suite()`, and
`sequence2ast()` have no methods of their own.
Some of the functions defined which accept an AST object as their
first argument may change to object methods in the future. The type
of these objects is available as `ASTType` in the module.
Ordered and equality comparisons are supported between AST objects.
---
guido@cnri.reston.va.us


3.9.6 Examples

node44.html node37.html node42.html node1.html node221.html
---
## 3.9.6 Examples
The parser modules allows operations to be performed on the parse tree
of Python source code before the bytecode is generated, and provides
for inspection of the parse tree for information gathering purposes.
Two examples are presented. The simple example demonstrates emulation
of the `compile()` built-in function and the complex example
shows the use of a parse tree for information discovery.
---
- Emulation of `compile()` (node44.html#SECTION00496100000000000000)
Information Discovery (node45.html#SECTION00496200000000000000)
---
guido@cnri.reston.va.us


Emulation of compile()

node45.html node43.html node43.html node1.html node221.html
---
### 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 equivelent to the code
```text
>>> code = compile('a + 5', 'eval')
>>> a = 5
>>> eval(code)
10
```
The equivelent 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 = parser.compileast(ast)
>>> 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)
code = parser.compileast(ast)
return ast, code

def load_expression(source_string):
ast = parser.expr(source_string)
code = parser.compileast(ast)
return ast, code
```
---
guido@cnri.reston.va.us


Information Discovery

node46.html node43.html node44.html node1.html node221.html
---
### 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 = parser.ast2tuple(ast)
>>> 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` and `token` 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 equivelence 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 paralels 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):
source = open(fileName).read()
import os
basename = os.path.basename(os.path.splitext(fileName)[0])
import parser
ast = parser.suite(source)
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
```
This provides an easy-to-use interface to the documentation of a
module. If information is required which is not extracted by the code
of this example, the code may be extended at clearly defined points to
provide additional capabilities.
---
node46.html node43.html node44.html node1.html node221.html
guido@cnri.reston.va.us


3.10 Built-in Module __builtin__

node47.html node27.html node45.html node1.html node221.html
---
# 3.10 Built-in Module `__builtin__`
This module provides direct access to all `built-in' identifiers of
Python; e.g. `__builtin__.open` is the full name for the built-in
function `open`. See the section on Built-in Functions in the
previous chapter.
---
guido@cnri.reston.va.us


3.11 Built-in Module __main__

node48.html node27.html node46.html node1.html node221.html
---
# 3.11 Built-in Module `__main__`
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes -- commands read either from
standard input or from a script file.
---
guido@cnri.reston.va.us


4 String Services

node49.html lib.html node47.html node1.html node221.html
---
# 4 String Services
The modules described in this chapter provide a wide range of string
manipulation operations. Here's an overview:
---
- 4.1 Standard Module `string` (node49.html#SECTION00510000000000000000)
4.2 Built-in Module `regex` (node50.html#SECTION00520000000000000000)
- 4.2.1 Regular Expressions (node51.html#SECTION00521000000000000000)
4.2.2 Module Contents (node52.html#SECTION00522000000000000000)
4.3 Standard Module `regsub` (node53.html#SECTION00530000000000000000)
4.4 Built-in Module `struct` (node54.html#SECTION00540000000000000000)
---
guido@cnri.reston.va.us


4.1 Standard Module string

node50.html node48.html node48.html node1.html node221.html
---
# 4.1 Standard Module `string`
This module defines some constants useful for checking character
classes and some useful string functions. See the modules
`regex` and `regsub` for string functions based on regular
expressions.
The constants defined in this module are are:
The functions defined in this module are:
This module is implemented in Python. Much of its functionality has
been reimplemented in the built-in module `strop`. However, you
should never import the latter module directly. When
`string` discovers that `strop` exists, it transparently
replaces parts of itself with the implementation from `strop`.
After initialization, there is no overhead in using
`string` instead of `strop`.
---
node50.html node48.html node48.html node1.html node221.html
guido@cnri.reston.va.us


2.1.1 Truth Value Testing

node6.html node4.html node4.html node1.html node221.html
---
## 2.1.1 Truth Value Testing
Any object can be tested for truth value, for use in an `if` or
`while` condition or as operand of the Boolean operations below.
The following values are considered false:
- `None`
zero of any numeric type, e.g., `0`, `0L`, `0.0`.any empty sequence, e.g., `''`, `()`, `[]`.any empty mapping, e.g., `{}`.instances of user-defined classes, if the class defines a
`__nonzero__()` or `__len__()` method, when that
method returns zero.
All other values are considered true -- so objects of many types are
always true.
Operations and built-in functions that have a Boolean result always
return `0` for false and `1` for true, unless otherwise
stated. (Important exception: the Boolean operations `or' and
`and' always return one of their operands.)
---
guido@cnri.reston.va.us


4.2 Built-in Module regex

node51.html node48.html node49.html node1.html node221.html
---
# 4.2 Built-in Module `regex`
This module provides regular expression matching operations similar to
those found in Emacs. It is always available.
By default the patterns are Emacs-style regular expressions
(with one exception). There is
a way to change the syntax to match that of several well-known
Unix utilities. The exception is that Emacs' `\s'
pattern is not supported, since the original implementation references
the Emacs syntax tables.
This module is 8-bit clean: both patterns and strings may contain null
bytes and characters whose high bit is set.
Please note: There is a little-known fact about Python string
literals which means that you don't usually have to worry about
doubling backslashes, even though they are used to escape special
characters in string literals as well as in regular expressions. This
is because Python doesn't remove backslashes from string literals if
they are followed by an unrecognized escape character.
However, if you want to include a literal backslash in a
regular expression represented as a string literal, you have to
quadruple it. E.g. to extract LaTeX `\section{
...}' headers from a document, you can use this pattern:
`'\\\\section{\(.*\)}'`. Another exception:
the escape sequece `\b' is significant in string literals
(where it means the ASCII bell character) as well as in Emacs regular
expressions (where it stands for a word boundary), so in order to
search for a word boundary, you should use the pattern `'\\b'`.
Similarly, a backslash followed by a digit 0-7 should be doubled to
avoid interpretation as an octal escape.
---
- 4.2.1 Regular Expressions (node51.html#SECTION00521000000000000000)
4.2.2 Module Contents (node52.html#SECTION00522000000000000000)
---
guido@cnri.reston.va.us


4.2.1 Regular Expressions

node52.html node50.html node50.html node1.html node221.html
---
## 4.2.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:
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 are indicated.
---
node52.html node50.html node50.html node1.html node221.html
guido@cnri.reston.va.us


4.2.2 Module Contents

node53.html node50.html node51.html node1.html node221.html
---
## 4.2.2 Module Contents
The module defines these functions, and an exception:
,
Compiled regular expression objects support these methods:
,
Compiled regular expressions support these data attributes:
---
node53.html node50.html node51.html node1.html node221.html
guido@cnri.reston.va.us


4.3 Standard Module regsub

node54.html node48.html node52.html node1.html node221.html
---
# 4.3 Standard Module `regsub`
This module defines a number of functions useful for working with
regular expressions (see built-in module `regex`).
Warning: these functions are not thread-safe.
---
guido@cnri.reston.va.us


4.4 Built-in Module struct

node55.html node48.html node53.html node1.html node221.html
---
# 4.4 Built-in Module `struct`
This module performs conversions between Python values and C
structs represented as Python strings. It uses format strings
(explained below) as compact descriptions of the lay-out of the C
structs and the intended conversion to/from Python values.
See also built-in module `array`.
The module defines the following exception and functions:
Format characters have the following meaning; the conversion between C
and Python values should be obvious given their types:
A format character may be preceded by an integral repeat count; e.g.\
the format string `'4h'` means exactly the same as `'hhhh'`.
C numbers are represented in the machine's native format and byte
order, and properly aligned by skipping pad bytes if necessary
(according to the rules used by the C compiler).
Examples (all on a big-endian machine):
```text
pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'
unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)
calcsize('hhl') == 8
```
Hint: to align the end of a structure to the alignment requirement of
a particular type, end the format with the code for that type with a
repeat count of zero, e.g. the format `'llh0l'` specifies two
pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
(More format characters are planned, e.g. `'s'` for character
arrays, upper case for unsigned variants, and a way to specify the
byte order, which is useful for [de]constructing network packets and
reading/writing portable binary file formats like TIFF and AIFF.)
---
node55.html node48.html node53.html node1.html node221.html
guido@cnri.reston.va.us


5 Miscellaneous Services

node56.html lib.html node54.html node1.html node221.html
---
# 5 Miscellaneous Services
The modules described in this chapter provide miscellaneous services
that are available in all Python versions. Here's an overview:
---
- 5.1 Built-in Module `math` (node56.html#SECTION00610000000000000000)
5.2 Standard Module `rand` (node57.html#SECTION00620000000000000000)
5.3 Standard Module `whrandom` (node58.html#SECTION00630000000000000000)
5.4 Built-in Module `array` (node59.html#SECTION00640000000000000000)
---
guido@cnri.reston.va.us


5.1 Built-in Module math

node57.html node55.html node55.html node1.html node221.html
---
# 5.1 Built-in Module `math`
This module is always available.
It provides access to the mathematical functions defined by the C
standard.
They are:
,
,
`acos( x )`,
`asin( x )`,
`atan( x )`,
`atan2( x, y )`,
`ceil( x )`,
`cos( x )`,
`cosh( x )`,
`exp( x )`,
`fabs( x )`,
`floor( x )`,
`fmod( x, y )`,
`frexp( x )`,
`hypot( x, y )`,
`ldexp( x, y )`,
`log( x )`,
`log10( x )`,
`modf( x )`,
`pow( x, y )`,
`sin( x )`,
`sinh( x )`,
`sqrt( x )`,
`tan( x )`,
`tanh( x )`.
,
Note that `frexp` and `modf` have a different call/return
pattern than their C equivalents: they take a single argument and
return a pair of values, rather than returning their second return
value through an `output parameter' (there is no such thing in Python).
The module also defines two mathematical constants:
,
,
`pi` and `e`.
,
---
guido@cnri.reston.va.us


5.2 Standard Module rand

node58.html node55.html node56.html node1.html node221.html
---
# 5.2 Standard Module `rand`
This module implements a pseudo-random number
generator with an interface similar to `rand()` in C. It defines
the following functions:
---
guido@cnri.reston.va.us


5.3 Standard Module whrandom

node59.html node55.html node57.html node1.html node221.html
---
# 5.3 Standard Module `whrandom`
This module implements a Wichmann-Hill pseudo-random number generator.
It defines the following functions:
---
guido@cnri.reston.va.us


5.4 Built-in Module array

node60.html node55.html node58.html node1.html node221.html
---
# 5.4 Built-in Module `array`
This module defines a new object type which can efficiently represent
an array of basic values: characters, integers, floating point
numbers. Arrays are sequence types and behave very much like lists,
except that the type of objects stored in them is constrained. The
type is specified at object creation time by using a type code,
which is a single character. The following type codes are defined:
The actual representation of values is determined by the machine
architecture (strictly speaking, by the C implementation). The actual
size can be accessed through the itemsize attribute.
See also built-in module `struct`.
The module defines the following function:
Array objects support the following data items and methods:
When an array object is printed or converted to a string, it is
represented as `array( typecode , initializer )`. The
initializer is omitted if the array is empty, otherwise it is a
string if the typecode is `'c'`, otherwise it is a list of
numbers. The string is guaranteed to be able to be converted back to
an array with the same type and value using reverse quotes
(````). Examples:
```text
array('l')
array('c', 'hello world')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
```
---
node60.html node55.html node58.html node1.html node221.html
guido@cnri.reston.va.us


2.1.2 Boolean Operations

node7.html node4.html node5.html node1.html node221.html
---
## 2.1.2 Boolean Operations
These are the Boolean operations, ordered by ascending priority:
,
Notes:
---
guido@cnri.reston.va.us


6 Generic Operating System Services

node61.html lib.html node59.html node1.html node221.html
---
# 6 Generic Operating System Services
The modules described in this chapter provide interfaces to operating
system features that are available on (almost) all operating systems,
such as files and a clock. The interfaces are generally modelled
after the Unix or C interfaces but they are available on most other
systems as well. Here's an overview:
---
- 6.1 Standard Module `os` (node61.html#SECTION00710000000000000000)
6.2 Built-in Module `time` (node62.html#SECTION00720000000000000000)
6.3 Standard Module `getopt` (node63.html#SECTION00730000000000000000)
6.4 Standard Module `tempfile` (node64.html#SECTION00740000000000000000)
6.5 Standard Module `errno` (node65.html#SECTION00750000000000000000)
---
guido@cnri.reston.va.us


6.1 Standard Module os

node62.html node60.html node60.html node1.html node221.html
---
# 6.1 Standard Module `os`
This module provides a more portable way of using operating system
(OS) dependent functionality than importing an OS dependent built-in
module like `posix`.
When the optional built-in module `posix` is available, this
module exports the same functions and data as `posix`; otherwise,
it searches for an OS dependent built-in module like `mac` and
exports the same functions and data as found there. The design of all
Python's built-in OS dependent modules is such that as long as the same
functionality is available, it uses the same interface; e.g., the
function `os.stat( file )` returns stat info about a file in a
format compatible with the POSIX interface.
Extensions peculiar to a particular OS are also available through the
`os` module, but using them is of course a threat to portability!
Note that after the first time `os` is imported, there is no
performance penalty in using functions from `os` instead of
directly from the OS dependent built-in module, so there should be
no reason not to use `os`!
In addition to whatever the correct OS dependent module exports, the
following variables and functions are always exported by `os`:
(The functions `os.execv()` and `execve()` are not
documented here, since they are implemented by the OS dependent
module. If the OS dependent module doesn't define either of these,
the functions that rely on it will raise an exception. They are
documented in the section on module `posix`, together with all
other functions that `os` imports from the OS dependent module.)
---
node62.html node60.html node60.html node1.html node221.html
guido@cnri.reston.va.us


6.2 Built-in Module time

node63.html node60.html node61.html node1.html node221.html
---
# 6.2 Built-in Module `time`
This module provides various time-related functions.
It is always available.
An explanation of some terminology and conventions is in order.
- The ``epoch'' is the point where the time starts. On January 1st of that
year, at 0 hours, the ``time since the epoch'' is zero. For UNIX, the
epoch is 1970. To find out what the epoch is, look at `gmtime(0)`.UTC is Coordinated Universal Time (formerly known as Greenwich Mean
Time). The acronym UTC is not a mistake but a compromise between
English and French.DST is Daylight Saving Time, an adjustment of the timezone by
(usually) one hour during part of the year. DST rules are magic
(determined by local law) and can change from year to year. The C
library has a table containing the local rules (often it is read from
a system file for flexibility) and is the only source of True Wisdom
in this respect.The precision of the various real-time functions may be less than
suggested by the units in which their value or argument is expressed.
E.g. on most UNIX systems, the clock ``ticks'' only 50 or 100 times a
second, and on the Mac, times are only accurate to whole seconds.The time tuple as returned by `gmtime()` and `localtime()`,
or as accpted by `mktime()` is a tuple of 9
integers: year (e.g. 1993), month (1-12), day (1-31), hour
(0-23), minute (0-59), second (0-59), weekday (0-6, monday is 0),
Julian day (1-366) and daylight savings flag (-1, 0 or 1).
Note that unlike the C structure, the month value is a range of 1-12, not
0-11. A year value of < 100 will typically be silently converted to
1900 + year value. A -1 argument as daylight savings flag, passed to
`mktime()` will usually result in the correct daylight savings
state to be filled in.
The module defines the following functions and data items:
---
node63.html node60.html node61.html node1.html node221.html
guido@cnri.reston.va.us


6.3 Standard Module getopt

node64.html node60.html node62.html node1.html node221.html
---
# 6.3 Standard Module `getopt`
This module helps scripts to parse the command line arguments in
`sys.argv`.
It supports the same conventions as the Unix
`getopt()`
function (including the special meanings of arguments of the form
`-' and `-'). Long options similar to those supported by
GNU software may be used as well via an optional third argument.
It defines the function
`getopt.getopt(args, options [, long_options])`
and the exception
`getopt.error`.
The first argument to
`getopt()`
is the argument list passed to the script with its first element
chopped off (i.e.,
`sys.argv[1:]`).
The second argument is the string of option letters that the
script wants to recognize, with options that require an argument
followed by a colon (i.e., the same format that Unix
`getopt()`
uses).
The third option, if specified, is a list of strings with the names of
the long options which should be supported. The leading `'-'`
characters should not be included in the option name. Options which
require an argument should be followed by an equal sign (`'='`).
The return value consists of two elements: the first is a list of
option-and-value pairs; the second is the list of program arguments
left after the option list was stripped (this is a trailing slice of the
first argument).
Each option-and-value pair returned has the option as its first element,
prefixed with a hyphen (e.g.,
`'-x'`),
and the option argument as its second element, or an empty string if the
option has no argument.
The options occur in the list in the same order in which they were
found, thus allowing multiple occurrences. Long and short options may
be mixed.
An example using only Unix style options:
```text
>>> import getopt, string
>>> args = string.split('-a -b -cfoo -d bar a1 a2')
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
>>>
```
Using long option names is equally easy:
```text
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = string.split(s)
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']
>>>
```
The exception
`getopt.error = 'getopt.error'`
is raised when an unrecognized option is found in the argument list or
when an option requiring an argument is given none.
The argument to the exception is a string indicating the cause of the
error. For long options, an argument given to an option which does
not require one will also cause this exception to be raised.
---
node64.html node60.html node62.html node1.html node221.html
guido@cnri.reston.va.us


6.4 Standard Module tempfile

node65.html node60.html node63.html node1.html node221.html
---
# 6.4 Standard Module `tempfile`
This module generates temporary file names. It is not Unix specific,
but it may require some help on non-Unix systems.
Note: the modules does not create temporary files, nor does it
automatically remove them when the current process exits or dies.
The module defines a single user-callable function:
The module uses two global variables that tell it how to construct a
temporary name. The caller may assign values to them; by default they
are initialized at the first call to `mktemp()`.
Warning: if a Unix process uses `mktemp()`, then calls
`fork()` and both parent and child continue to use
`mktemp()`, the processes will generate conflicting temporary
names. To resolve this, the child process should assign `None`
to `template`, to force recomputing the default on the next call
to `mktemp()`.
---
guido@cnri.reston.va.us


6.5 Standard Module errno

node66.html node60.html node64.html node1.html node221.html
---
# 6.5 Standard Module `errno`
This module makes available standard errno system symbols.
The value of each symbol is the corresponding integer value.
The names and descriptions are borrowed from linux/include/errno.h,
which should be pretty all-inclusive. Of the following list, symbols
that are not used on the current platform are not defined by the
module.
Symbols available can include:
---
node66.html node60.html node64.html node1.html node221.html
guido@cnri.reston.va.us


7 Optional Operating System Services

node67.html lib.html node65.html node1.html node221.html
---
# 7 Optional Operating System Services
The modules described in this chapter provide interfaces to operating
system features that are available on selected operating systems only.
The interfaces are generally modelled after the Unix or C
interfaces but they are available on some other systems as well
(e.g. Windows or NT). Here's an overview:
---
- 7.1 Built-in Module `signal` (node67.html#SECTION00810000000000000000)
7.2 Built-in Module `socket` (node68.html#SECTION00820000000000000000)
- 7.2.1 Socket Objects (node69.html#SECTION00821000000000000000)
7.2.2 Example (node70.html#SECTION00822000000000000000)
7.3 Built-in Module `select` (node71.html#SECTION00830000000000000000)
7.4 Built-in Module `thread` (node72.html#SECTION00840000000000000000)
---
guido@cnri.reston.va.us


7.1 Built-in Module signal

node68.html node66.html node66.html node1.html node221.html
---
# 7.1 Built-in Module `signal`
This module provides mechanisms to use signal handlers in Python.
Some general rules for working with signals handlers:
- A handler for a particular signal, once set, remains installed until
it is explicitly reset (i.e. Python emulates the BSD style interface
regardless of the underlying implementation), with the exception of
the handler for `SIGCHLD`, which follows the underlying
implementation.There is no way to ``block'' signals temporarily from critical
sections (since this is not supported by all Unix flavors).Although Python signal handlers are called asynchronously as far as
the Python user is concerned, they can only occur between the
``atomic'' instructions of the Python interpreter. This means that
signals arriving during long calculations implemented purely in C
(e.g. regular expression matches on large bodies of text) may be
delayed for an arbitrary amount of time.When a signal arrives during an I/O operation, it is possible that the
I/O operation raises an exception after the signal handler returns.
This is dependent on the underlying Unix system's semantics regarding
interrupted system calls.Because the C signal handler always returns, it makes little sense to
catch synchronous errors like `SIGFPE` or `SIGSEGV`.Python installs a small number of signal handlers by default:
`SIGPIPE` is ignored (so write errors on pipes and sockets can be
reported as ordinary Python exceptions), `SIGINT` is translated
into a `KeyboardInterrupt` exception, and `SIGTERM` is
caught so that necessary cleanup (especially `sys.exitfunc`) can
be performed before actually terminating. All of these can be
overridden.Some care must be taken if both signals and threads are used in the
same program. The fundamental thing to remember in using signals and
threads simultaneously is: always perform `signal()` operations
in the main thread of execution. Any thread can perform an
`alarm()`, `getsignal()`, or `pause()`; only the main
thread can set a new signal handler, and the main thread will be the
only one to receive signals (this is enforced by the Python signal
module, even if the underlying thread implementation supports sending
signals to individual threads). This means that signals can't be used
as a means of interthread communication. Use locks instead.
The variables defined in the signal module are:
The signal module defines the following functions:
---
node68.html node66.html node66.html node1.html node221.html
guido@cnri.reston.va.us