2.1.5 Sequence Types

node11.html node4.html node9.html node1.html node221.html
---
## 2.1.5 Sequence Types
There are three sequence types: strings, lists and tuples.
Strings literals are written in single or double quotes:
`'xyzzy'`, `"frobozz"`. See Chapter 2 of the Python
Reference Manual for more about string literals. Lists are
constructed with square brackets, separating items with commas:
`[a, b, c]`. Tuples are constructed by the comma operator (not
within square brackets), with or without enclosing parentheses, but an
empty tuple must have the enclosing parentheses, e.g.,
`a, b, c` or `()`. A single item tuple must have a trailing
comma, e.g., `(d,)`.
Sequence types support the following operations. The `in' and
`not,in' operations have the same priorities as the comparison
operations. The `+' and `*' operations have the same
priority as the corresponding numeric operations.footnode.html#385
This table lists the sequence operations sorted in ascending priority
(operations in the same box have the same priority). In the table,
s and t are sequences of the same type; n, i
and j are integers:
,
Notes:
---
- More String Operations (node11.html#SECTION00315100000000000000)
Mutable Sequence Types (node12.html#SECTION00315200000000000000)
---
guido@cnri.reston.va.us


10.8.1 OldProfile Class

node101.html node99.html node99.html node1.html node221.html
---
## 10.8.1 OldProfile Class
The following derived profiler simulates the old style profiler,
providing errant results on recursive functions. The reason for the
usefulness of this profiler is that it runs faster (i.e., less
overhead) than the old profiler. It still creates all the caller
stats, and is quite useful when there is no recursion in the
user's code. It is also a lot more accurate than the old profiler, as
it does not charge all its overhead time to the user's code.
```text
class OldProfile(Profile):

def trace_dispatch_exception(self, frame, t):
rt, rtt, rct, rfn, rframe, rcur = self.cur
if rcur and not rframe is frame:
return self.trace_dispatch_return(rframe, t)
return 0

def trace_dispatch_call(self, frame, t):
fn = `frame.f_code`

self.cur = (t, 0, 0, fn, frame, self.cur)
if self.timings.has_key(fn):
tt, ct, callers = self.timings[fn]
self.timings[fn] = tt, ct, callers
else:
self.timings[fn] = 0, 0, {}
return 1

def trace_dispatch_return(self, frame, t):
rt, rtt, rct, rfn, frame, rcur = self.cur
rtt = rtt + t
sft = rtt + rct

pt, ptt, pct, pfn, pframe, pcur = rcur
self.cur = pt, ptt+rt, pct+sft, pfn, pframe, pcur

tt, ct, callers = self.timings[rfn]
if callers.has_key(pfn):
callers[pfn] = callers[pfn] + 1
else:
callers[pfn] = 1
self.timings[rfn] = tt+rtt, ct + sft, callers

return 1

def snapshot_stats(self):
self.stats = {}
for func in self.timings.keys():
tt, ct, callers = self.timings[func]
nor_func = self.func_normalize(func)
nor_callers = {}
nc = 0
for func_caller in callers.keys():
nor_callers[self.func_normalize(func_caller)]=\
callers[func_caller]
nc = nc + callers[func_caller]
self.stats[nor_func] = nc, nc, tt, ct, nor_callers
```
---
guido@cnri.reston.va.us


10.8.2 HotProfile Class

node102.html node99.html node100.html node1.html node221.html
---
## 10.8.2 HotProfile Class
This profiler is the fastest derived profile example. It does not
calculate caller-callee relationships, and does not calculate
cumulative time under a function. It only calculates time spent in a
function, so it runs very quickly (re: very low overhead). In truth,
the basic profiler is so fast, that is probably not worth the savings
to give up the data, but this class still provides a nice example.
```text
class HotProfile(Profile):

def trace_dispatch_exception(self, frame, t):
rt, rtt, rfn, rframe, rcur = self.cur
if rcur and not rframe is frame:
return self.trace_dispatch_return(rframe, t)
return 0

def trace_dispatch_call(self, frame, t):
self.cur = (t, 0, frame, self.cur)
return 1

def trace_dispatch_return(self, frame, t):
rt, rtt, frame, rcur = self.cur

rfn = `frame.f_code`

pt, ptt, pframe, pcur = rcur
self.cur = pt, ptt+rt, pframe, pcur

if self.timings.has_key(rfn):
nc, tt = self.timings[rfn]
self.timings[rfn] = nc + 1, rt + rtt + tt
else:
self.timings[rfn] = 1, rt + rtt

return 1

def snapshot_stats(self):
self.stats = {}
for func in self.timings.keys():
nc, tt = self.timings[func]
nor_func = self.func_normalize(func)
self.stats[nor_func] = nc, nc, tt, 0, {}
```
---
guido@cnri.reston.va.us


11 Internet and WWW Services

node103.html lib.html node101.html node1.html node221.html
---
# 11 Internet and WWW Services
The modules described in this chapter provide various services to
World-Wide Web (WWW) clients and/or services, and a few modules
related to news and email. They are all implemented in Python. Some
of these modules require the presence of the system-dependent module
`sockets`, which is currently only fully supported on Unix and
Windows NT. Here is an overview:
---
- 11.1 Standard Module `cgi` (node103.html#SECTION001210000000000000000)
- 11.1.1 Introduction (node104.html#SECTION001211000000000000000)
11.1.2 Using the cgi module (node105.html#SECTION001212000000000000000)
11.1.3 Old classes (node106.html#SECTION001213000000000000000)
11.1.4 Functions (node107.html#SECTION001214000000000000000)
11.1.5 Caring about security (node108.html#SECTION001215000000000000000)
11.1.6 Installing your CGI script on a Unix system (node109.html#SECTION001216000000000000000)
11.1.7 Testing your CGI script (node110.html#SECTION001217000000000000000)
11.1.8 Debugging CGI scripts (node111.html#SECTION001218000000000000000)
11.1.9 Common problems and solutions (node112.html#SECTION001219000000000000000)
11.2 Standard Module `urllib` (node113.html#SECTION001220000000000000000)
11.3 Standard Module `httplib` (node114.html#SECTION001230000000000000000)
- 11.3.1 HTTP Objects (node115.html#SECTION001231000000000000000)
11.3.2 Example (node116.html#SECTION001232000000000000000)
11.4 Standard Module `ftplib` (node117.html#SECTION001240000000000000000)
- 11.4.1 FTP Objects (node118.html#SECTION001241000000000000000)
11.5 Standard Module `gopherlib` (node119.html#SECTION001250000000000000000)
11.6 Standard Module `nntplib` (node120.html#SECTION001260000000000000000)
- 11.6.1 NNTP Objects (node121.html#SECTION001261000000000000000)
11.7 Standard Module `urlparse` (node122.html#SECTION001270000000000000000)
11.8 Standard Module `sgmllib` (node123.html#SECTION001280000000000000000)
11.9 Standard Module `htmllib` (node124.html#SECTION001290000000000000000)
11.10 Standard Module `formatter` (node125.html#SECTION0012100000000000000000)
- 11.10.1 The Formatter Interface (node126.html#SECTION0012101000000000000000)
11.10.2 Formatter Implementations (node127.html#SECTION0012102000000000000000)
11.10.3 The Writer Interface (node128.html#SECTION0012103000000000000000)
11.10.4 Writer Implementations (node129.html#SECTION0012104000000000000000)
11.11 Standard Module `rfc822` (node130.html#SECTION0012110000000000000000)
- 11.11.1 Message Objects (node131.html#SECTION0012111000000000000000)
11.12 Standard Module `mimetools` (node132.html#SECTION0012120000000000000000)
- 11.12.1 Additional Methods of Message objects (node133.html#SECTION0012121000000000000000)
11.13 Standard module `binhex` (node134.html#SECTION0012130000000000000000)
- 11.13.1 notes (node135.html#SECTION0012131000000000000000)
11.14 Standard module `uu` (node136.html#SECTION0012140000000000000000)
11.15 Built-in Module `binascii` (node137.html#SECTION0012150000000000000000)
11.16 Standard module `xdrlib` (node138.html#SECTION0012160000000000000000)
- 11.16.1 Packer Objects (node139.html#SECTION0012161000000000000000)
11.16.2 Unpacker Objects (node140.html#SECTION0012162000000000000000)
11.16.3 Exceptions (node141.html#SECTION0012163000000000000000)
11.16.4 Supporting Floating Point Data (node142.html#SECTION0012164000000000000000)
---
guido@cnri.reston.va.us


11.1 Standard Module cgi

node104.html node102.html node102.html node1.html node221.html
---
# 11.1 Standard Module `cgi`
Support module for CGI (Common Gateway Interface) scripts.
This module defines a number of utilities for use by CGI scripts
written in Python.
---
- 11.1.1 Introduction (node104.html#SECTION001211000000000000000)
11.1.2 Using the cgi module (node105.html#SECTION001212000000000000000)
11.1.3 Old classes (node106.html#SECTION001213000000000000000)
11.1.4 Functions (node107.html#SECTION001214000000000000000)
11.1.5 Caring about security (node108.html#SECTION001215000000000000000)
11.1.6 Installing your CGI script on a Unix system (node109.html#SECTION001216000000000000000)
11.1.7 Testing your CGI script (node110.html#SECTION001217000000000000000)
11.1.8 Debugging CGI scripts (node111.html#SECTION001218000000000000000)
11.1.9 Common problems and solutions (node112.html#SECTION001219000000000000000)
---
guido@cnri.reston.va.us


11.1.1 Introduction

node105.html node103.html node103.html node1.html node221.html
---
## 11.1.1 Introduction
A CGI script is invoked by an HTTP server, usually to process user
input submitted through an HTML `<FORM>` or `<ISINPUT>` element.
Most often, CGI scripts live in the server's special `cgi-bin`
directory. The HTTP server places all sorts of information about the
request (such as the client's hostname, the requested URL, the query
string, and lots of other goodies) in the script's shell environment,
executes the script, and sends the script's output back to the client.
The script's input is connected to the client too, and sometimes the
form data is read this way; at other times the form data is passed via
the ``query string'' part of the URL. This module (`cgi.py`) is intended
to take care of the different cases and provide a simpler interface to
the Python script. It also provides a number of utilities that help
in debugging scripts, and the latest addition is support for file
uploads from a form (if your browser supports it - Grail 0.3 and
Netscape 2.0 do).
The output of a CGI script should consist of two sections, separated
by a blank line. The first section contains a number of headers,
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
```text
print "Content-type: text/html" # HTML is following
print # blank line, end of headers
```
The second section is usually HTML, which allows the client software
to display nicely formatted text with header, in-line images, etc.
Here's Python code that prints a simple piece of HTML:
```text
print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"
```
(It may not be fully legal HTML according to the letter of the
standard, but any browser will understand it.)
---
guido@cnri.reston.va.us


11.1.2 Using the cgi module

node106.html node103.html node104.html node1.html node221.html
---
## 11.1.2 Using the cgi module
Begin by writing `import cgi`. Don't use `from cgi import *` - the
module defines all sorts of names for its own use or for backward
compatibility that you don't want in your namespace.
It's best to use the `FieldStorage` class. The other classes define in this
module are provided mostly for backward compatibility. Instantiate it
exactly once, without arguments. This reads the form contents from
standard input or the environment (depending on the value of various
environment variables set according to the CGI standard). Since it may
consume standard input, it should be instantiated only once.
The `FieldStorage` instance can be accessed as if it were a Python
dictionary. For instance, the following code (which assumes that the
`Content-type` header and blank line have already been printed) checks that
the fields `name` and `addr` are both set to a non-empty string:
```text
form = cgi.FieldStorage()
form_ok = 0
if form.has_key("name") and form.has_key("addr"):
if form["name"].value != "" and form["addr"].value != "":
form_ok = 1
if not form_ok:
print "<H1>Error</H1>"
print "Please fill in the name and addr fields."
return
...further form processing here...
```
Here the fields, accessed through `form[key]`, are themselves instances
of `FieldStorage` (or `MiniFieldStorage`, depending on the form encoding).
If the submitted form data contains more than one field with the same
name, the object retrieved by `form[key]` is not a `(Mini)FieldStorage`
instance but a list of such instances. If you expect this possibility
(i.e., when your HTML form comtains multiple fields with the same
name), use the `type()` function to determine whether you have a single
instance or a list of instances. For example, here's code that
concatenates any number of username fields, separated by commas:
```text
username = form["username"]
if type(username) is type([]):
# Multiple username fields specified
usernames = ""
for item in username:
if usernames:
# Next item -- insert comma
usernames = usernames + "," + item.value
else:
# First item -- don't insert comma
usernames = item.value
else:
# Single username field specified
usernames = username.value
```
If a field represents an uploaded file, the value attribute reads the
entire file in memory as a string. This may not be what you want. You can
test for an uploaded file by testing either the filename attribute or the
file attribute. You can then read the data at leasure from the file
attribute:
```text
fileitem = form["userfile"]
if fileitem.file:
# It's an uploaded file; count lines
linecount = 0
while 1:
line = fileitem.file.readline()
if not line: break
linecount = linecount + 1
```
The file upload draft standard entertains the possibility of uploading
multiple files from one field (using a recursive `multipart/*`
encoding). When this occurs, the item will be a dictionary-like
FieldStorage item. This can be determined by testing its type
attribute, which should have the value `multipart/form-data` (or
perhaps another string beginning with `multipart/` It this case, it
can be iterated over recursively just like the top-level form object.
When a form is submitted in the ``old'' format (as the query string or as a
single data part of type `application/x-www-form-urlencoded`), the items
will actually be instances of the class `MiniFieldStorage`. In this case,
the list, file and filename attributes are always `None`.
---
node106.html node103.html node104.html node1.html node221.html
guido@cnri.reston.va.us


11.1.3 Old classes

node107.html node103.html node105.html node1.html node221.html
---
## 11.1.3 Old classes
These classes, present in earlier versions of the `cgi` module, are still
supported for backward compatibility. New applications should use the
FieldStorage class.
`SvFormContentDict`: single value form content as dictionary; assumes each
field name occurs in the form only once.
`FormContentDict`: multiple value form content as dictionary (the form
items are lists of values). Useful if your form contains multiple
fields with the same name.
Other classes (`FormContent`, `InterpFormContentDict`) are present for
backwards compatibility with really old applications only. If you still
use these and would be inconvenienced when they disappeared from a next
version of this module, drop me a note.
---
guido@cnri.reston.va.us


11.1.4 Functions

node108.html node103.html node106.html node1.html node221.html
---
## 11.1.4 Functions
These are useful if you want more control, or if you want to employ
some of the algorithms implemented in this module in other
circumstances.
---
node108.html node103.html node106.html node1.html node221.html
guido@cnri.reston.va.us


11.1.5 Caring about security

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


node110.html node103.html node108.html node1.html node221.html
---
## 11.1.6 Installing your CGI script on a Unix system
Read the documentation for your HTTP server and check with your local
system administrator to find the directory where CGI scripts should be
installed; usually this is in a directory `cgi-bin` in the server tree.
Make sure that your script is readable and executable by ``others''; the
Unix file mode should be 755 (use `chmod 755 filename`). Make sure
that the first line of the script contains `#!` starting in column 1
followed by the pathname of the Python interpreter, for instance:
```text
#!/usr/local/bin/python
```
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
readable or writable, respectively, by ``others'' - their mode should
be 644 for readable and 666 for writable. This is because, for
security reasons, the HTTP server executes your script as user
``nobody'', without any special privileges. It can only read (write,
execute) files that everybody can read (write, execute). The current
directory at execution time is also different (it is usually the
server's cgi-bin directory) and the set of environment variables is
also different from what you get at login. in particular, don't count
on the shell's search path for executables (`$PATH`) or the Python
module search path (`$PYTHONPATH`) to be set to anything interesting.
If you need to load modules from a directory which is not on Python's
default module search path, you can change the path in your script,
before importing other modules, e.g.:
```text
import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
```
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).
---
guido@cnri.reston.va.us


More String Operations

node12.html node10.html node10.html node1.html node221.html
---
### More String Operations
String objects have one unique built-in operation: the `%`
operator (modulo) with a string left argument interprets this string
as a C sprintf format string to be applied to the right argument, and
returns the string resulting from this formatting operation.
The right argument should be a tuple with one item for each argument
required by the format string; if the string requires a single
argument, the right argument may also be a single non-tuple object.footnode.html#491
The following format characters are understood:
%, c, s, i, d, u, o, x, X, e, E, f, g, G.
Width and precision may be a * to specify that an integer argument
specifies the actual width or precision. The flag characters -, +,
blank, # and 0 are understood. The size specifiers h, l or L may be
present but are ignored. The `%s` conversion takes any Python
object and converts it to a string using `str()` before
formatting it. The ANSI features `%p` and `%n`
are not supported. Since Python strings have an explicit length,
`%s` conversions don't assume that `'\0'` is the end of
the string.
For safety reasons, floating point precisions are clipped to 50;
`%f` conversions for numbers whose absolute value is over 1e25
are replaced by `%g` conversions.footnode.html#500
All other errors raise exceptions.
If the right argument is a dictionary (or any kind of mapping), then
the formats in the string must have a parenthesized key into that
dictionary inserted immediately after the `%` character, and
each format formats the corresponding entry from the mapping. E.g.
```text
>>> count = 2
>>> language = 'Python'
>>> print '%(language)s has %(count)03d quote types.' % vars()
Python has 002 quote types.
>>>
```
In this case no * specifiers may occur in a format (since they
require a sequential parameter list).
Additional string operations are defined in standard module
`string` and in built-in module `regex`.
---
guido@cnri.reston.va.us


11.1.7 Testing your CGI script

node111.html node103.html node109.html node1.html node221.html
---
## 11.1.7 Testing your CGI script
Unfortunately, a CGI script will generally not run when you try it
from the command line, and a script that works perfectly from the
command line may fail mysteriously when run from the server. There's
one reason why you should still test your script from the command
line: if it contains a syntax error, the python interpreter won't
execute it at all, and the HTTP server will most likely send a cryptic
error to the client.
Assuming your script has no syntax errors, yet it does not work, you
have no choice but to read the next section:
---
guido@cnri.reston.va.us


11.1.8 Debugging CGI scripts

node112.html node103.html node110.html node1.html node221.html
---
## 11.1.8 Debugging CGI scripts
First of all, check for trivial installation errors - reading the
section above on installing your CGI script carefully can save you a
lot of time. If you wonder whether you have understood the
installation procedure correctly, try installing a copy of this module
file (`cgi.py`) as a CGI script. When invoked as a script, the file
will dump its environment and the contents of the form in HTML form.
Give it the right mode etc, and send it a request. If it's installed
in the standard `cgi-bin` directory, it should be possible to send it a
request by entering a URL into your browser of the form:
```text
http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
```
If this gives an error of type 404, the server cannot find the script
- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
you should fix before trying to go any further. If you get a nicely
formatted listing of the environment and form content (in this
example, the fields should be listed as ``addr'' with value ``At Home''
and ``name'' with value ``Joe Blow''), the `cgi.py` script has been
installed correctly. If you follow the same procedure for your own
script, you should now be able to debug it.
The next step could be to call the `cgi` module's test() function from
your script: replace its main code with the single statement
```text
cgi.test()
```
This should produce the same results as those gotten from installing
the `cgi.py` file itself.
When an ordinary Python script raises an unhandled exception
(e.g. because of a typo in a module name, a file that can't be opened,
etc.), the Python interpreter prints a nice traceback and exits.
While the Python interpreter will still do this when your CGI script
raises an exception, most likely the traceback will end up in one of
the HTTP server's log file, or be discarded altogether.
Fortunately, once you have managed to get your script to execute
*some* code, it is easy to catch exceptions and cause a traceback to
be printed. The `test()` function below in this module is an example.
Here are the rules:
1. Import the traceback module (before entering the
try-except!)Make sure you finish printing the headers and the blank
line earlyAssign `sys.stderr` to `sys.stdout`Wrap all remaining code in a try-except statementIn the except clause, call `traceback.print_exc()`
For example:
```text
import sys
import traceback
print "Content-type: text/html"
print
sys.stderr = sys.stdout
try:
...your code here...
except:
print "\n\n<PRE>"
traceback.print_exc()
```
Notes: The assignment to `sys.stderr` is needed because the traceback
prints to `sys.stderr`. The `print " n n<PRE>"` statement is necessary to
disable the word wrapping in HTML.
If you suspect that there may be a problem in importing the traceback
module, you can use an even more robust approach (which only uses
built-in modules):
```text
import sys
sys.stderr = sys.stdout
print "Content-type: text/plain"
print
...your code here...
```
This relies on the Python interpreter to print the traceback. The
content type of the output is set to plain text, which disables all
HTML processing. If your script works, the raw HTML will be displayed
by your client. If it raises an exception, most likely after the
first two lines have been printed, a traceback will be displayed.
Because no HTML interpretation is going on, the traceback will
readable.
---
node112.html node103.html node110.html node1.html node221.html
guido@cnri.reston.va.us


11.1.9 Common problems and solutions

node113.html node103.html node111.html node1.html node221.html
---
## 11.1.9 Common problems and solutions
- Most HTTP servers buffer the output from CGI scripts until the
script is completed. This means that it is not possible to display a
progress report on the client's display while the script is running.Check the installation instructions above.Check the HTTP server's log files. (`tail -f logfile` in a separate
window may be useful!)Always check a script for syntax errors first, by doing something
like `python script.py`.When using any of the debugging techniques, don't forget to add
`import sys` to the top of the script.When invoking external programs, make sure they can be found.
Usually, this means using absolute path names - `$PATH` is usually not
set to a very useful value in a CGI script.When reading or writing external files, make sure they can be read
or written by every user on the system.Don't try to give a CGI script a set-uid mode. This doesn't work on
most systems, and is a security liability as well.
---
guido@cnri.reston.va.us


11.2 Standard Module urllib

node114.html node102.html node112.html node1.html node221.html
---
# 11.2 Standard Module `urllib`
This module provides a high-level interface for fetching data across
the World-Wide Web. In particular, the `urlopen` function is
similar to the built-in function `open`, but accepts URLs
(Universal Resource Locators) instead of filenames. Some restrictions
apply -- it can only open URLs for reading, and no seek operations
are available.
it defines the following public functions:
Restrictions:
- Currently, only the following protocols are supported: HTTP, (versions
0.9 and 1.0), Gopher (but not Gopher-+), FTP, and local files.
The caching feature of `urlretrieve()` has been disabled until I
find the time to hack proper processing of Expiration time headers.There should be a function to query whether a particular URL is in
the cache.For backward compatibility, if a URL appears to point to a local file
but the file can't be opened, the URL is re-interpreted using the FTP
protocol. This can sometimes cause confusing error messages.The `urlopen()` and `urlretrieve()` functions can cause
arbitrarily long delays while waiting for a network connection to be
set up. This means that it is difficult to build an interactive
web client using these functions without using threads.The data returned by `urlopen()` or `urlretrieve()` is the
raw data returned by the server. This may be binary data (e.g. an
image), plain text or (for example) HTML. The HTTP protocol provides
type information in the reply header, which can be inspected by
looking at the `Content-type` header. For the Gopher protocol,
type information is encoded in the URL; there is currently no easy way
to extract it. If the returned data is HTML, you can use the module
`htmllib` to parse it.
Although the `urllib` module contains (undocumented) routines to
parse and unparse URL strings, the recommended interface for URL
manipulation is in module `urlparse`.
---
node114.html node102.html node112.html node1.html node221.html
guido@cnri.reston.va.us


11.3 Standard Module httplib

node115.html node102.html node113.html node1.html node221.html
---
# 11.3 Standard Module `httplib`
This module defines a class which implements the client side of the
HTTP protocol. It is normally not used directly -- the module
`urllib` uses it to handle URLs that use HTTP.
The module defines one class, `HTTP`. An `HTTP` instance
represents one transaction with an HTTP server. It should be
instantiated passing it a host and optional port number. If no port
number is passed, the port is extracted from the host string if it has
the form `host:port`, else the default HTTP port (80) is used.
If no host is passed, no connection is made, and the `connect`
method should be used to connect to a server. For example, the
following calls all create instances that connect to the server at the
same host and port:
```text
>>> h1 = httplib.HTTP('www.cwi.nl')
>>> h2 = httplib.HTTP('www.cwi.nl:80')
>>> h3 = httplib.HTTP('www.cwi.nl', 80)
```
Once an `HTTP` instance has been connected to an HTTP server, it
should be used as follows:
---
- 11.3.1 HTTP Objects (node115.html#SECTION001231000000000000000)
11.3.2 Example (node116.html#SECTION001232000000000000000)
---
guido@cnri.reston.va.us


11.3.1 HTTP Objects

node116.html node114.html node114.html node1.html node221.html
---
## 11.3.1 HTTP Objects
`HTTP` instances have the following methods:
---
node116.html node114.html node114.html node1.html node221.html
guido@cnri.reston.va.us


11.3.2 Example

node117.html node114.html node115.html node1.html node221.html
---
## 11.3.2 Example
Here is an example session:
```text
>>> import httplib
>>> h = httplib.HTTP('www.cwi.nl')
>>> h.putrequest('GET', '/index.html')
>>> h.putheader('Accept', 'text/html')
>>> h.putheader('Accept', 'text/plain')
>>> h.endheaders()
>>> errcode, errmsg, headers = h.getreply()
>>> print errcode # Should be 200
>>> f = h.getfile()
>>> data f.read() # Get the raw HTML
>>> f.close()
>>>
```
---
guido@cnri.reston.va.us


11.4 Standard Module ftplib

node118.html node102.html node116.html node1.html node221.html
---
# 11.4 Standard Module `ftplib`
This module defines the class `FTP` and a few related items. The
`FTP` class implements the client side of the FTP protocol. You
can use this to write Python programs that perform a variety of
automated FTP jobs, such as mirroring other ftp servers. It is also
used by the module `urllib` to handle URLs that use FTP. For
more information on FTP (File Transfer Protocol), see Internet RFC
959.
Here's a sample session using the `ftplib` module:
```text
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
>>> ftp.login() # user anonymous, passwd user@hostname
>>> ftp.retrlines('LIST') # list directory contents
total 24418
drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
.
.
.
>>> ftp.quit()
```
The module defines the following items:
---
- 11.4.1 FTP Objects (node118.html#SECTION001241000000000000000)
---
guido@cnri.reston.va.us


11.4.1 FTP Objects

node119.html node117.html node117.html node1.html node221.html
---
## 11.4.1 FTP Objects
FTP instances have the following methods:
---
node119.html node117.html node117.html node1.html node221.html
guido@cnri.reston.va.us


11.5 Standard Module gopherlib

node120.html node102.html node118.html node1.html node221.html
---
# 11.5 Standard Module `gopherlib`
This module provides a minimal implementation of client side of the
the Gopher protocol. It is used by the module `urllib` to handle
URLs that use the Gopher protocol.
The module defines the following functions:
Note that the data returned by the Gopher server can be of any type,
depending on the first character of the selector string. If the data
is text (first character of the selector is `0'), lines are
terminated by CRLF, and the data is terminated by a line consisting of
a single `.', and a leading `.' should be stripped from
lines that begin with `..'. Directory listings (first charactger
of the selector is `1') are transferred using the same protocol.
---
guido@cnri.reston.va.us


Mutable Sequence Types

node13.html node10.html node11.html node1.html node221.html
---
### Mutable Sequence Types
List objects support additional operations that allow in-place
modification of the object.
These operations would be supported by other mutable sequence types
(when added to the language) as well.
Strings and tuples are immutable sequence types and such objects cannot
be modified once created.
The following operations are defined on mutable sequence types (where
x is an arbitrary object):
,
Notes:
---
guido@cnri.reston.va.us


11.6 Standard Module nntplib

node121.html node102.html node119.html node1.html node221.html
---
# 11.6 Standard Module `nntplib`
This module defines the class `NNTP` which implements the client
side of the NNTP protocol. It can be used to implement a news reader
or poster, or automated news processors. For more information on NNTP
(Network News Transfer Protocol), see Internet RFC 977.
Here are two small examples of how it can be used. To list some
statistics about a newsgroup and print the subjects of the last 10
articles:
```text
>>> s = NNTP('news.cwi.nl')
>>> resp, count, first, last, name = s.group('comp.lang.python')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
Group comp.lang.python has 59 articles, range 3742 to 3803
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
3792 Re: Removing elements from a list while iterating...
3793 Re: Who likes Info files?
3794 Emacs and doc strings
3795 a few questions about the Mac implementation
3796 Re: executable python scripts
3797 Re: executable python scripts
3798 Re: a few questions about the Mac implementation
3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
3802 Re: executable python scripts
3803 Re: POSIX wait and SIGCHLD
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
```
To post an article from a file (this assumes that the article has
valid headers):
```text
>>> s = NNTP('news.cwi.nl')
>>> f = open('/tmp/article')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
```
The module itself defines the following items:
---
- 11.6.1 NNTP Objects (node121.html#SECTION001261000000000000000)
---
guido@cnri.reston.va.us


11.6.1 NNTP Objects

node122.html node120.html node120.html node1.html node221.html
---
## 11.6.1 NNTP Objects
NNTP instances have the following methods. The response that is
returned as the first item in the return tuple of almost all methods
is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.
---
node122.html node120.html node120.html node1.html node221.html
guido@cnri.reston.va.us


11.7 Standard Module urlparse

node123.html node102.html node121.html node1.html node221.html
---
# 11.7 Standard Module `urlparse`
This module defines a standard interface to break URL strings up in
components (addessing scheme, network location, path etc.), to combine
the components back into a URL string, and to convert a ``relative
URL'' to an absolute URL given a ``base URL''.
The module has been designed to match the current Internet draft on
Relative Uniform Resource Locators (and discovered a bug in an earlier
draft!).
It defines the following functions:
---
node123.html node102.html node121.html node1.html node221.html
guido@cnri.reston.va.us


11.8 Standard Module sgmllib

node124.html node102.html node122.html node1.html node221.html
---
# 11.8 Standard Module `sgmllib`
This module defines a class `SGMLParser` which serves as the
basis for parsing text files formatted in SGML (Standard Generalized
Mark-up Language). In fact, it does not provide a full SGML parser
-- it only parses SGML insofar as it is used by HTML, and the module
only exists as a base for the `htmllib` module.
In particular, the parser is hardcoded to recognize the following
constructs:
- Opening and closing tags of the form
```< tag attr =" value " ...>`'' and
```</ tag >`'', respectively.Numeric character references of the form ```&# name ;`''.Entity references of the form ```& name ;`''.SGML comments of the form ```<!- text ->`''. Note that
spaces, tabs, and newlines are allowed between the trailing
```>`'' and the immediately preceeding ```-`''.

The `SGMLParser` class must be instantiated without arguments.
It has the following interface methods:

Apart from overriding or extending the methods listed above, derived
classes may also define methods of the following form to define
processing of specific tags. Tag names in the input stream are case
independent; the tag occurring in method names must be in lower
case:

Note that the parser maintains a stack of open elements for which no
end tag has been found yet. Only tags processed by
`start_ tag ()` are pushed on this stack. Definition of an
`end_ tag ()` method is optional for these tags. For tags
processed by `do_ tag ()` or by `unknown_tag()`, no
`end_ tag ()` method must be defined; if defined, it will not
be used. If both `start_ tag ()` and `do_ tag ()`
methods exist for a tag, the `start_ tag ()` method takes
precedence.

---

node124.html node102.html node122.html node1.html node221.html

Next: 11.9 Standard Module htmllib (node124.html)
Up: 11 Internet and WWW (node102.html)
Previous: 11.7 Standard Module urlparse (node122.html)

guido@cnri.reston.va.us


11.9 Standard Module htmllib

node125.html node102.html node123.html node1.html node221.html
---
# 11.9 Standard Module `htmllib`
This module defines a class which can serve as a base for parsing text
files formatted in the HyperText Mark-up Language (HTML). The class
is not directly concerned with I/O -- it must be provided with input
in string form via a method, and makes calls to methods of a
``formatter'' object in order to produce output. The
`HTMLParser` class is designed to be used as a base class for
other classes in order to add functionality, and allows most of its
methods to be extended or overridden. In turn, this class is derived
from and extends the `SGMLParser` class defined in module
`sgmllib`. Two implementations of formatter objects are
provided in the `formatter` module; refer to the documentation
for that module for information on the formatter interface.
The following is a summary of the interface defined by
`sgmllib.SGMLParser`:
- The interface to feed data to an instance is through the `feed()`
method, which takes a string argument. This can be called with as
little or as much text at a time as desired; `p.feed(a);
p.feed(b)` has the same effect as `p.feed(a+b)`. When the data
contains complete HTML tags, these are processed immediately;
incomplete elements are saved in a buffer. To force processing of all
unprocessed data, call the `close()` method.
For example, to parse the entire contents of a file, use:
```text
parser.feed(open('myfile.html').read())
parser.close()
```
The interface to define semantics for HTML tags is very simple: derive
a class and define methods called `start_ tag ()`,
`end_ tag ()`, or `do_ tag ()`. The parser will
call these at appropriate moments: `start_ tag` or
`do_ tag` is called when an opening tag of the form
`< tag ...>` is encountered; `end_ tag` is called
when a closing tag of the form `< tag >` is encountered. If
an opening tag requires a corresponding closing tag, like `<H1>`
... `</H1>`, the class should define the `start_ tag`
method; if a tag requires no closing tag, like `<P>`, the class
should define the `do_ tag` method.
The module defines a single class:
In addition to tag methods, the `HTMLParser` class provides some
additional methods and instance variables for use within tag methods.
---
node125.html node102.html node123.html node1.html node221.html
guido@cnri.reston.va.us


11.10 Standard Module formatter

node126.html node102.html node124.html node1.html node221.html
---
# 11.10 Standard Module `formatter`
This module supports two interface definitions, each with mulitple
implementations. The formatter interface is used by the
`HTMLParser` class of the `htmllib` module, and the
writer interface is required by the formatter interface.
Formatter objects transform an abstract flow of formatting events into
specific output events on writer objects. Formatters manage several
stack structures to allow various properties of a writer object to be
changed and restored; writers need not be able to handle relative
changes nor any sort of ``change back'' operation. Specific writer
properties which may be controlled via formatter objects are
horizontal alignment, font, and left margin indentations. A mechanism
is provided which supports providing arbitrary, non-exclusive style
settings to a writer as well. Additional interfaces facilitate
formatting events which are not reversible, such as paragraph
separation.
Writer objects encapsulate device interfaces. Abstract devices, such
as file formats, are supported as well as physical devices. The
provided implementations all work with abstract devices. The
interface makes available mechanisms for setting the properties which
formatter objects manage and inserting data into the output.
---
- 11.10.1 The Formatter Interface (node126.html#SECTION0012101000000000000000)
11.10.2 Formatter Implementations (node127.html#SECTION0012102000000000000000)
11.10.3 The Writer Interface (node128.html#SECTION0012103000000000000000)
11.10.4 Writer Implementations (node129.html#SECTION0012104000000000000000)
---
guido@cnri.reston.va.us


11.10.1 The Formatter Interface

node127.html node125.html node125.html node1.html node221.html
---
## 11.10.1 The Formatter Interface
Interfaces to create formatters are dependent on the specific
formatter class being instantiated. The interfaces described below
are the required interfaces which all formatters must support once
initialized.
One data element is defined at the module level:
The following attributes are defined for formatter instance objects:
---
node127.html node125.html node125.html node1.html node221.html
guido@cnri.reston.va.us


11.10.2 Formatter Implementations

node128.html node125.html node126.html node1.html node221.html
---
## 11.10.2 Formatter Implementations
Two implementations of formatter objects are provided by this module.
Most applications may use one of these classes without modification or
subclassing.
---
guido@cnri.reston.va.us


11.10.3 The Writer Interface

node129.html node125.html node127.html node1.html node221.html
---
## 11.10.3 The Writer Interface
Interfaces to create writers are dependent on the specific writer
class being instantiated. The interfaces described below are the
required interfaces which all writers must support once initialized.
Note that while most applications can use the `AbstractFormatter`
class as a formatter, the writer must typically be provided by the
application.
---
node129.html node125.html node127.html node1.html node221.html
guido@cnri.reston.va.us


11.10.4 Writer Implementations

node130.html node125.html node128.html node1.html node221.html
---
## 11.10.4 Writer Implementations
Three implementations of the writer object interface are provided as
examples by this module. Most applications will need to derive new
writer classes from the `NullWriter` class.
---
guido@cnri.reston.va.us


2.1.6 Mapping Types

node14.html node4.html node12.html node1.html node221.html
---
## 2.1.6 Mapping Types
A mapping object maps values of one type (the key type) to
arbitrary objects. Mappings are mutable objects. There is currently
only one standard mapping type, the dictionary. A dictionary's keys are
almost arbitrary values. The only types of values not acceptable as
keys are values containing lists or dictionaries or other mutable
types that are compared by value rather than by object identity.
Numeric types used for keys obey the normal rules for numeric
comparison: if two numbers compare equal (e.g. 1 and 1.0) then they
can be used interchangeably to index the same dictionary entry.
Dictionaries are created by placing a comma-separated list of
`key :, value` pairs within braces, for example:
`{'jack':,4098, 'sjoerd':,4127}` or
`{4098:,'jack', 4127:,'sjoerd'}`.
The following operations are defined on mappings (where a is a
mapping, k is a key and x is an arbitrary object):
,
Notes:
---
guido@cnri.reston.va.us


11.11 Standard Module rfc822

node131.html node102.html node129.html node1.html node221.html
---
# 11.11 Standard Module `rfc822`
This module defines a class, `Message`, which represents a
collection of ``email headers'' as defined by the Internet standard
RFC 822. It is used in various contexts, usually to read such headers
from a file.
A `Message` instance is instantiated with an open file object as
parameter. Instantiation reads headers from the file up to a blank
line and stores them in the instance; after instantiation, the file is
positioned directly after the blank line that terminates the headers.
Input lines as read from the file may either be terminated by CR-LF or
by a single linefeed; a terminating CR-LF is replaced by a single
linefeed before the line is stored.
All header matching is done independent of upper or lower case;
e.g. `m['From']`, `m['from']` and `m['FROM']` all yield
the same result.
---
- 11.11.1 Message Objects (node131.html#SECTION0012111000000000000000)
---
guido@cnri.reston.va.us


11.11.1 Message Objects

node132.html node130.html node130.html node1.html node221.html
---
## 11.11.1 Message Objects
A `Message` instance has the following methods:
`Message` instances also support a read-only mapping interface.
In particular: `m[name]` is the same as `m.getheader(name)`;
and `len(m)`, `m.has_key(name)`, `m.keys()`,
`m.values()` and `m.items()` act as expected (and
consistently).
Finally, `Message` instances have two public instance variables:
---
node132.html node130.html node130.html node1.html node221.html
guido@cnri.reston.va.us


11.12 Standard Module mimetools

node133.html node102.html node131.html node1.html node221.html
---
# 11.12 Standard Module `mimetools`
This module defines a subclass of the class `rfc822.Message` and
a number of utility functions that are useful for the manipulation for
MIME style multipart or encoded message.
It defines the following items:
---
- 11.12.1 Additional Methods of Message objects (node133.html#SECTION0012121000000000000000)
---
guido@cnri.reston.va.us


node134.html node132.html node132.html node1.html node221.html
---
## 11.12.1 Additional Methods of Message objects
The `mimetools.Message` class defines the following methods in
addition to the `rfc822.Message` class:
---
guido@cnri.reston.va.us


11.13 Standard module binhex

node135.html node102.html node133.html node1.html node221.html
---
# 11.13 Standard module `binhex`
This module encodes and decodes files in binhex4 format, a format
allowing representation of Macintosh files in ASCII. On the macintosh,
both forks of a file and the finder information are encoded (or
decoded), on other platforms only the data fork is handled.
The `binhex` module defines the following functions:
---
- 11.13.1 notes (node135.html#SECTION0012131000000000000000)
---
guido@cnri.reston.va.us


11.13.1 notes

node136.html node134.html node134.html node1.html node221.html
---
## 11.13.1 notes
There is an alternative, more powerful interface to the coder and
decoder, see the source for details.
If you code or decode textfiles on non-Macintosh platforms they will
still use the macintosh newline convention (carriage-return as end of
line).
As of this writing, hexbin appears to not work in all cases.
---
guido@cnri.reston.va.us


11.14 Standard module uu

node137.html node102.html node135.html node1.html node221.html
---
# 11.14 Standard module `uu`
This module encodes and decodes files in uuencode format, allowing
arbitrary binary data to be transferred over ascii-only connections.
Whereever a file argument is expected, the methods accept either a
pathname (`'-'` for stdin/stdout) or a file-like object.
Normally you would pass filenames, but there is one case where you
have to open the file yourself: if you are on a non-unix platform and
your binary file is actually a textfile that you want encoded
unix-compatible you will have to open the file yourself as a textfile,
so newline conversion is performed.
This code was contributed by Lance Ellinghouse, and modified by Jack
Jansen.
The `uu` module defines the following functions:
---
guido@cnri.reston.va.us


11.15 Built-in Module binascii

node138.html node102.html node136.html node1.html node221.html
---
# 11.15 Built-in Module `binascii`
The binascii module contains a number of methods to convert between
binary and various ascii-encoded binary representations. Normally, you
will not use these modules directly but use wrapper modules like
uu or hexbin in stead, this module solely exists because
bit-manipuation of large amounts of data is slow in python.
The `binascii` module defines the following functions:
---
node138.html node102.html node136.html node1.html node221.html
guido@cnri.reston.va.us


11.16 Standard module xdrlib

node139.html node102.html node137.html node1.html node221.html
---
# 11.16 Standard module `xdrlib`
The `xdrlib` module supports the External Data Representation
Standard as described in RFC 1014, written by Sun Microsystems,
Inc. June 1987. It supports most of the data types described in the
RFC, although some, most notably `float` and `double` are
only supported on those operating systems that provide an XDR
library.
The `xdrlib` module defines two classes, one for packing
variables into XDR representation, and another for unpacking from XDR
representation. There are also two exception classes.
---
- 11.16.1 Packer Objects (node139.html#SECTION0012161000000000000000)
11.16.2 Unpacker Objects (node140.html#SECTION0012162000000000000000)
11.16.3 Exceptions (node141.html#SECTION0012163000000000000000)
11.16.4 Supporting Floating Point Data (node142.html#SECTION0012164000000000000000)
---
guido@cnri.reston.va.us


11.16.1 Packer Objects

node140.html node138.html node138.html node1.html node221.html
---
## 11.16.1 Packer Objects
`Packer` is the class for packing data into XDR representation.
The `Packer` class is instantiated with no arguments.
In general, you can pack any of the most common XDR data types by
calling the appropriate `pack_ type` method. Each method
takes a single argument, the value to pack. The following simple data
type packing methods are supported: `pack_uint`, `pack_int`,
`pack_enum`, `pack_bool`, `pack_uhyper`,
and `pack_hyper`.
The following methods pack floating point numbers, however they
require C library support. Without the optional C built-in module,
both of these methods will raise an `xdrlib.ConversionError`
exception. See the note at the end of this chapter for details.
The following methods support packing strings, bytes, and opaque data:
The following methods support packing arrays and lists:
---
node140.html node138.html node138.html node1.html node221.html
guido@cnri.reston.va.us


2.1.7 Other Built-in Types

node15.html node4.html node13.html node1.html node221.html
---
## 2.1.7 Other Built-in Types
The interpreter supports several other kinds of objects.
Most of these support only one or two operations.
---
- 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)
---
guido@cnri.reston.va.us


11.16.2 Unpacker Objects

node141.html node138.html node139.html node1.html node221.html
---
## 11.16.2 Unpacker Objects
`Unpacker` is the complementary class which unpacks XDR data
values from a string buffer, and has the following methods:
In addition, every data type that can be packed with a `Packer`,
can be unpacked with an `Unpacker`. Unpacking methods are of the
form `unpack_ type`, and take no arguments. They return the
unpacked object. The same caveats apply for `unpack_float` and
`unpack_double` as above.
In addition, the following methods unpack strings, bytes, and opaque
data:
The following methods support unpacking arrays and lists:
---
node141.html node138.html node139.html node1.html node221.html
guido@cnri.reston.va.us


11.16.3 Exceptions

node142.html node138.html node140.html node1.html node221.html
---
## 11.16.3 Exceptions
Exceptions in this module are coded as class instances:
Here is an example of how you would catch one of these exceptions:
```text
import xdrlib
p = xdrlib.Packer()
try:
p.pack_double(8.01)
except xdrlib.ConversionError, instance:
print 'packing the double failed:', instance.msg
```
---
guido@cnri.reston.va.us


11.16.4 Supporting Floating Point Data

node143.html node138.html node141.html node1.html node221.html
---
## 11.16.4 Supporting Floating Point Data
Packing and unpacking floating point data,
i.e. `Packer.pack_float`, `Packer.pack_double`,
`Unpacker.unpack_float`, and `Unpacker.unpack_double`, are
only supported with the helper built-in `_xdr` module, which
relies on your operating system having the appropriate XDR library
routines.
If you have built the Python interpeter with the `_xdr` module,
or have built the `_xdr` module as a shared library,
`xdrlib` will use these to pack and unpack floating point
numbers. Otherwise, using these routines will raise a
`ConversionError` exception.
See the Python installation instructions for details on building the
`_xdr` module.
---
guido@cnri.reston.va.us


12 Restricted Execution

node144.html lib.html node142.html node1.html node221.html
---
# 12 Restricted Execution
In general, Python programs have complete access to the underlying
operating system throug the various functions and classes, For
example, a Python program can open any file for reading and writing by
using the `open()` built-in function (provided the underlying OS
gives you permission!). This is exactly what you want for most
applications.
There exists a class of applications for which this ``openness'' is
inappropriate. Take Grail: a web browser that accepts ``applets'',
snippets of Python code, from anywhere on the Internet for execution
on the local system. This can be used to improve the user interface
of forms, for instance. Since the originator of the code is unknown,
it is obvious that it cannot be trusted with the full resources of the
local machine.
Restricted execution is the basic framework in Python that allows
for the segregation of trusted and untrusted code. It is based on the
notion that trusted Python code (a supervisor) can create a
``padded cell' (or environment) with limited permissions, and run the
untrusted code within this cell. The untrusted code cannot break out
of its cell, and can only interact with sensitive system resources
through interfaces defined and managed by the trusted code. The term
``restricted execution'' is favored over ``safe-Python''
since true safety is hard to define, and is determined by the way the
restricted environment is created. Note that the restricted
environments can be nested, with inner cells creating subcells of
lesser, but never greater, privilege.
An interesting aspect of Python's restricted execution model is that
the interfaces presented to untrusted code usually have the same names
as those presented to trusted code. Therefore no special interfaces
need to be learned to write code designed to run in a restricted
environment. And because the exact nature of the padded cell is
determined by the supervisor, different restrictions can be imposed,
depending on the application. For example, it might be deemed
``safe'' for untrusted code to read any file within a specified
directory, but never to write a file. In this case, the supervisor
may redefine the built-in
`open()` function so that it raises an exception whenever the
mode parameter is `'w'`. It might also perform a
`chroot()`-like operation on the filename parameter, such
that root is always relative to some safe ``sandbox'' area of the
filesystem. In this case, the untrusted code would still see an
built-in `open()` function in its environment, with the same
calling interface. The semantics would be identical too, with
`IOError`s being raised when the supervisor determined that an
unallowable parameter is being used.
The Python run-time determines whether a particular code block is
executing in restricted execution mode based on the identity of the
`__builtins__` object in its global variables: if this is (the
dictionary of) the standard `__builtin__` module, the code is
deemed to be unrestricted, else it is deemed to be restricted.
Python code executing in restricted mode faces a number of limitations
that are designed to prevent it from escaping from the padded cell.
For instance, the function object attribute `func_globals` and the
class and instance object attribute `__dict__` are unavailable.
Two modules provide the framework for setting up restricted execution
environments:
---
- 12.1 Standard Module `rexec` (node144.html#SECTION001310000000000000000)
- 12.1.1 An example (node145.html#SECTION001311000000000000000)
12.2 Standard Module `Bastion` (node146.html#SECTION001320000000000000000)
---
node144.html lib.html node142.html node1.html node221.html
guido@cnri.reston.va.us


12.1 Standard Module rexec

node145.html node143.html node143.html node1.html node221.html
---
# 12.1 Standard Module `rexec`
This module contains the `RExec` class, which supports
`r_exec()`, `r_eval()`, `r_execfile()`, and
`r_import()` methods, which are restricted versions of the standard
Python functions `exec()`, `eval()`, `execfile()`, and
the `import` statement.
Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you
can subclass `RExec` to add or remove capabilities as desired.
Note: The `RExec` class can prevent code from performing
unsafe operations like reading or writing disk files, or using TCP/IP
sockets. However, it does not protect against code using extremely
large amounts of memory or CPU time.
The RExec class has the following class attributes, which are used by the
`__init__` method. Changing them on an existing instance won't
have any effect; instead, create a subclass of `RExec` and assign
them new values in the class definition. Instances of the new class
will then use those new values. All these attributes are tuples of
strings.
RExec instances support the following methods:
Methods whose names begin with `s_` are similar to the functions
beginning with `r_`, but the code will be granted access to
restricted versions of the standard I/O streans `sys.stdin`,
`sys.stderr`, and `sys.stdout`.
`RExec` objects must also support various methods which will be
implicitly called by code executing in the restricted environment.
Overriding these methods in a subclass is used to change the policies
enforced by a restricted environment.
And their equivalents with access to restricted standard I/O streams:
---
- 12.1.1 An example (node145.html#SECTION001311000000000000000)
---
node145.html node143.html node143.html node1.html node221.html
guido@cnri.reston.va.us


12.1.1 An example

node146.html node144.html node144.html node1.html node221.html
---
## 12.1.1 An example
Let us say that we want a slightly more relaxed policy than the
standard RExec class. For example, if we're willing to allow files in
``/tmp`' to be written, we can subclass the `RExec` class:
```text
class TmpWriterRExec(rexec.RExec):
def r_open(self, file, mode='r', buf=-1):
if mode in ('r', 'rb'):
pass
elif mode in ('w', 'wb', 'a', 'ab'):
# check filename : must begin with /tmp/
if file[:5]!='/tmp/':
raise IOError, "can't write outside /tmp"
elif (string.find(file, '/../') >= 0 or
file[:3] == '../' or file[-3:] == '/..'):
raise IOError, "'..' in filename forbidden"
else: raise IOError, "Illegal open() mode"
return open(file, mode, buf)
```
Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be
able to open a file called ``/tmp/foo/../bar`'. To fix this, the
`r_open` method would have to simplify the filename to
``/tmp/bar`', which would require splitting apart the filename and
performing various operations on it. In cases where security is at
stake, it may be preferable to write simple code which is sometimes
overly restrictive, instead of more general code that is also more
complex and may harbor a subtle security hole.
---
guido@cnri.reston.va.us


12.2 Standard Module Bastion

node147.html node143.html node145.html node1.html node221.html
---
# 12.2 Standard Module `Bastion`
According to the dictionary, a bastion is ``a fortified area or
position'', or ``something that is considered a stronghold.'' It's a
suitable name for this module, which provides a way to forbid access
to certain attributes of an object. It must always be used with the
`rexec` module, in order to allow restricted-mode programs access
to certain safe attributes of an object, while denying access to
other, unsafe attributes.
---
guido@cnri.reston.va.us


13 Multimedia Services

node148.html lib.html node146.html node1.html node221.html
---
# 13 Multimedia Services
The modules described in this chapter implement various algorithms or
interfaces that are mainly useful for multimedia applications. They
are available at the discretion of the installation. Here's an overview:
---
- 13.1 Built-in Module `audioop` (node148.html#SECTION001410000000000000000)
13.2 Built-in Module `imageop` (node149.html#SECTION001420000000000000000)
13.3 Standard Module `aifc` (node150.html#SECTION001430000000000000000)
13.4 Built-in Module `jpeg` (node151.html#SECTION001440000000000000000)
13.5 Built-in Module `rgbimg` (node152.html#SECTION001450000000000000000)
13.6 Standard module `imghdr` (node153.html#SECTION001460000000000000000)
---
guido@cnri.reston.va.us


13.1 Built-in Module audioop

node149.html node147.html node147.html node1.html node221.html
---
# 13.1 Built-in Module `audioop`
The `audioop` module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples
8, 16 or 32 bits wide, stored in Python strings. This is the same
format as used by the `al` and `sunaudiodev` modules. All
scalar items are integers, unless specified otherwise.
A few of the more complicated operations only take 16-bit samples,
otherwise the sample size (in bytes) is always a parameter of the operation.
The module defines the following variables and functions:
Note that operations such as `mul` or `max` make no
distinction between mono and stereo fragments, i.e. all samples are
treated equal. If this is a problem the stereo fragment should be split
into two mono fragments first and recombined later. Here is an example
of how to do that:
```text
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
rsample = audioop.tomono(sample, width, 0, 1)
lsample = audioop.mul(sample, width, lfactor)
rsample = audioop.mul(sample, width, rfactor)
lsample = audioop.tostereo(lsample, width, 1, 0)
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
```
If you use the ADPCM coder to build network packets and you want your
protocol to be stateless (i.e. to be able to tolerate packet loss)
you should not only transmit the data but also the state. Note that
you should send the initial state (the one you passed to
`lin2adpcm`) along to the decoder, not the final state (as returned by
the coder). If you want to use `struct` to store the state in
binary you can code the first element (the predicted value) in 16 bits
and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders,
only against themselves. It could well be that I misinterpreted the
standards in which case they will not be interoperable with the
respective standards.
The `find...` routines might look a bit funny at first sight.
They are primarily meant to do echo cancellation. A reasonably
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
```text
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second
out_test = outputdata[pos*2:]
in_test = inputdata[pos*2:]
ipos, factor = audioop.findfit(in_test, out_test)
# Optional (for better cancellation):
# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
# out_test)
prefill = '\0'*(pos+ipos)*2
postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
return audioop.add(inputdata, outputdata, 2)
```
---
node149.html node147.html node147.html node1.html node221.html
guido@cnri.reston.va.us


13.2 Built-in Module imageop

node150.html node147.html node148.html node1.html node221.html
---
# 13.2 Built-in Module `imageop`
The `imageop` module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels
stored in Python strings. This is the same format as used
by `gl.lrectwrite` and the `imgfile` module.
The module defines the following variables and functions:
---
node150.html node147.html node148.html node1.html node221.html
guido@cnri.reston.va.us


Modules

node16.html node14.html node14.html node1.html node221.html
---
### Modules
The only special operation on a module is attribute access:
`m . name`, where m is a module and name accesses
a name defined in m's symbol table. Module attributes can be
assigned to. (Note that the `import` statement is not, strictly
spoken, an operation on a module object; `import foo` does not
require a module object named foo to exist, rather it requires
an (external) definition for a module named foo
somewhere.)
A special member of every module is `__dict__`.
This is the dictionary containing the module's symbol table.
Modifying this dictionary will actually change the module's symbol
table, but direct assignment to the `__dict__` attribute is not
possible (i.e., you can write `m .__dict__['a'] = 1`, which
defines `m .a` to be `1`, but you can't write `m .__dict__ = {}`.
Modules are written like this: `<module 'sys'>`.
---
guido@cnri.reston.va.us


13.3 Standard Module aifc

node151.html node147.html node149.html node1.html node221.html
---
# 13.3 Standard Module `aifc`
This module provides support for reading and writing AIFF and AIFF-C
files. AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file. AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
Audio files have a number of parameters that describe the audio data.
The sampling rate or frame rate is the number of times per second the
sound is sampled. The number of channels indicate if the audio is
mono, stereo, or quadro. Each frame consists of one sample per
channel. The sample size is the size in bytes of each sample. Thus a
frame consists of nchannels*samplesize bytes, and a
second's worth of audio consists of
nchannels*samplesize*framerate bytes.
For example, CD quality audio has a sample size of two bytes (16
bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second. This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes, i.e. 176,400 bytes.
Module `aifc` defines the following function:
Objects returned by `aifc.open()` when a file is opened for
reading have the following methods:
Objects returned by `aifc.open()` when a file is opened for
writing have all the above methods, except for `readframes` and
`setpos`. In addition the following methods exist. The
`get` methods can only be called after the corresponding
`set` methods have been called. Before the first
`writeframes` or `writeframesraw`, all parameters except for
the number of frames must be filled in.
---
node151.html node147.html node149.html node1.html node221.html
guido@cnri.reston.va.us


13.4 Built-in Module jpeg

node152.html node147.html node150.html node1.html node221.html
---
# 13.4 Built-in Module `jpeg`
The module `jpeg` provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group. JPEG is a (draft?)\
standard for compressing pictures. For details on jpeg or the
Independent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.
The `jpeg` module defines these functions:
Compress and uncompress raise the error `jpeg.error` in case of errors.
---
guido@cnri.reston.va.us


13.5 Built-in Module rgbimg

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


13.6 Standard module imghdr

node154.html node147.html node152.html node1.html node221.html
---
# 13.6 Standard module `imghdr`
The `imghdr` module determines the type of image contained in a
file or byte stream.
The `imghdr` module defines the following function:
The following image types are recognized, as listed below with the
return value from `what`:
You can extend the list of file types `imghdr` can recognize by
appending to this variable:
Example:
```text
>>> import imghdr
>>> imghdr.what('/tmp/bass.gif')
'gif'
```
---
guido@cnri.reston.va.us


14 Cryptographic Services

node155.html lib.html node153.html node1.html node221.html
---
# 14 Cryptographic Services
The modules described in this chapter implement various algorithms of
a cryptographic nature. They are available at the discretion of the
installation. Here's an overview:
Hardcore cypherpunks will probably find the cryptographic modules
written by Andrew Kuchling of further interest; the package adds
built-in modules for DES and IDEA encryption, provides a Python module
for reading and decrypting PGP files, and then some. These modules
are not distributed with Python but available separately. See the URL
``http://www.magnet.com/ amk/python/pct.html`' or send email to
``amk@magnet.com`' for more information.
---
- 14.1 Built-in Module `md5` (node155.html#SECTION001510000000000000000)
14.2 Built-in Module `mpz` (node156.html#SECTION001520000000000000000)
14.3 Built-in Module `rotor` (node157.html#SECTION001530000000000000000)
---
guido@cnri.reston.va.us


14.1 Built-in Module md5

node156.html node154.html node154.html node1.html node221.html
---
# 14.1 Built-in Module `md5`
This module implements the interface to RSA's MD5 message digest
algorithm (see also Internet RFC 1321). Its use is quite
straightforward: use the `md5.new()` to create an md5 object.
You can now feed this object with arbitrary strings using the
`update()` method, and at any point you can ask it for the
digest (a strong kind of 128-bit checksum,
a.k.a. ``fingerprint'') of the contatenation of the strings fed to it
so far using the `digest()` method.
For example, to obtain the digest of the string "Nobody inspects
the spammish repetition":
```text
>>> import md5
>>> m = md5.new()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
```
More condensed:
```text
>>> md5.new("Nobody inspects the spammish repetition").digest()
'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
```
An md5 object has the following methods:
---
guido@cnri.reston.va.us


14.2 Built-in Module mpz

node157.html node154.html node155.html node1.html node221.html
---
# 14.2 Built-in Module `mpz`
This is an optional module. It is only available when Python is
configured to include it, which requires that the GNU MP software is
installed.
This module implements the interface to part of the GNU MP library,
which defines arbitrary precision integer and rational number
arithmetic routines. Only the interfaces to the integer
(`mpz_...') routines are provided. If not stated
otherwise, the description in the GNU MP documentation can be applied.
In general, mpz-numbers can be used just like other standard
Python numbers, e.g. you can use the built-in operators like `+`,
`*`, etc., as well as the standard built-in functions like
`abs`, `int`, ..., `divmod`, `pow`.
Please note: the bitwise-xor operation has been implemented as
a bunch of ands, inverts and ors, because the library
lacks an `mpz_xor` function, and I didn't need one.
You create an mpz-number by calling the function called `mpz` (see
below for an exact description). An mpz-number is printed like this:
`mpz( value )`.
A number of extra functions are defined in this module. Non
mpz-arguments are converted to mpz-values first, and the functions
return mpz-numbers.
An mpz-number has one method:
---
node157.html node154.html node155.html node1.html node221.html
guido@cnri.reston.va.us


14.3 Built-in Module rotor

node158.html node154.html node156.html node1.html node221.html
---
# 14.3 Built-in Module `rotor`
This module implements a rotor-based encryption algorithm, contributed by
Lance Ellinghouse. The design is derived from the Enigma device, a machine
used during World War II to encipher messages. A rotor is simply a
permutation. For example, if the character `A' is the origin of the rotor,
then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
To encrypt, we choose several different rotors, and set the origins of the
rotors to known positions; their initial position is the ciphering key. To
encipher a character, we permute the original character by the first rotor,
and then apply the second rotor's permutation to the result. We continue
until we've applied all the rotors; the resulting character is our
ciphertext. We then change the origin of the final rotor by one position,
from `A' to `B'; if the final rotor has made a complete revolution, then we
rotate the next-to-last rotor by one position, and apply the same procedure
recursively. In other words, after enciphering one character, we advance
the rotors in the same fashion as a car's odometer. Decoding works in the
same way, except we reverse the permutations and apply them in the opposite
order.
The available functions in this module are:
Rotor objects have the following methods:
An example usage:
```text
>>> import rotor
>>> rt = rotor.newrotor('key', 12)
>>> rt.encrypt('bar')
'\2534\363'
>>> rt.encryptmore('bar')
'\357\375$'
>>> rt.encrypt('bar')
'\2534\363'
>>> rt.decrypt('\2534\363')
'bar'
>>> rt.decryptmore('\357\375$')
'bar'
>>> rt.decrypt('\357\375$')
'l(\315'
>>> del rt
```
The module's code is not an exact simulation of the original Enigma device;
it implements the rotor encryption scheme differently from the original. The
most important difference is that in the original Enigma, there were only 5
or 6 different rotors in existence, and they were applied twice to each
character; the cipher key was the order in which they were placed in the
machine. The Python rotor module uses the supplied key to initialize a
random number generator; the rotor permutations and their initial positions
are then randomly generated. The original device only enciphered the
letters of the alphabet, while this module can handle any 8-bit binary data;
it also produces binary output. This module can also operate with an
arbitrary number of rotors.
The original Enigma cipher was broken in 1944. The version implemented here is probably a good deal more difficult to crack
(especially if you use many rotors), but it won't be impossible for
a truly skilful and determined attacker to break the cipher. So if you want
to keep the NSA out of your files, this rotor cipher may well be unsafe, but
for discouraging casual snooping through your files, it will probably be
just fine, and may be somewhat safer than using the Unix ``crypt`'
command.
---
node158.html node154.html node156.html node1.html node221.html
guido@cnri.reston.va.us


15 Macintosh Specific Services

node159.html lib.html node157.html node1.html node221.html
---
# 15 Macintosh Specific Services
The modules in this chapter are available on the Apple Macintosh only.
Aside from the modules described here there are also interfaces to
various MacOS toolboxes, which are currently not extensively
described. The toolboxes for which modules exist are:
`AE` (Apple Events),
`Cm` (Component Manager),
`Ctl` (Control Manager),
`Dlg` (Dialog Manager),
`Evt` (Event Manager),
`Fm` (Font Manager),
`List` (List Manager),
`Menu` (Moenu Manager),
`Qd` (QuickDraw),
`Qt` (QuickTime),
`Res` (Resource Manager and Handles),
`Scrap` (Scrap Manager),
`Snd` (Sound Manager),
`TE` (TextEdit),
`Waste` (non-Apple TextEdit replacement) and
`Win` (Window Manager).
If applicable the module will define a number of Python objects for
the various structures declared by the toolbox, and operations will be
implemented as methods of the object. Other operations will be
implemented as functions in the module. Not all operations possible in
C will also be possible in Python (callbacks are often a problem), and
parameters will occasionally be different in Python (input and output
buffers, especially). All methods and functions have a `__doc__`
string describing their arguments and return values, and for
additional description you are referred to Inside Mac or similar
works.
---
- 15.1 Built-in Module `mac` (node159.html#SECTION001610000000000000000)
15.2 Standard Module `macpath` (node160.html#SECTION001620000000000000000)
15.3 Built-in Module `ctb` (node161.html#SECTION001630000000000000000)
- 15.3.1 connection object (node162.html#SECTION001631000000000000000)
15.4 Built-in Module `macconsole` (node163.html#SECTION001640000000000000000)
- 15.4.1 macconsole options object (node164.html#SECTION001641000000000000000)
15.4.2 console window object (node165.html#SECTION001642000000000000000)
15.5 Built-in Module `macdnr` (node166.html#SECTION001650000000000000000)
- 15.5.1 dnr result object (node167.html#SECTION001651000000000000000)
15.6 Built-in Module `macfs` (node168.html#SECTION001660000000000000000)
- 15.6.1 FSSpec objects (node169.html#SECTION001661000000000000000)
15.6.2 alias objects (node170.html#SECTION001662000000000000000)
15.6.3 FInfo objects (node171.html#SECTION001663000000000000000)
15.7 Built-in Module `MacOS` (node172.html#SECTION001670000000000000000)
15.8 Standard module `macostools` (node173.html#SECTION001680000000000000000)
15.9 Standard module `findertools` (node174.html#SECTION001690000000000000000)
15.10 Built-in Module `mactcp` (node175.html#SECTION0016100000000000000000)
- 15.10.1 TCP Stream Objects (node176.html#SECTION0016101000000000000000)
15.10.2 TCP Status Objects (node177.html#SECTION0016102000000000000000)
15.10.3 UDP Stream Objects (node178.html#SECTION0016103000000000000000)
15.11 Built-in Module `macspeech` (node179.html#SECTION0016110000000000000000)
- 15.11.1 voice objects (node180.html#SECTION0016111000000000000000)
15.11.2 speech channel objects (node181.html#SECTION0016112000000000000000)
15.12 Standard module `EasyDialogs` (node182.html#SECTION0016120000000000000000)
15.13 Standard module `FrameWork` (node183.html#SECTION0016130000000000000000)
- 15.13.1 Application objects (node184.html#SECTION0016131000000000000000)
15.13.2 Window Objects (node185.html#SECTION0016132000000000000000)
15.13.3 ControlsWindow Object (node186.html#SECTION0016133000000000000000)
15.13.4 ScrolledWindow Object (node187.html#SECTION0016134000000000000000)
15.13.5 DialogWindow Objects (node188.html#SECTION0016135000000000000000)
15.14 Standard module `MiniAEFrame` (node189.html#SECTION0016140000000000000000)
- 15.14.1 AEServer Objects (node190.html#SECTION0016141000000000000000)
---
guido@cnri.reston.va.us


15.1 Built-in Module mac

node160.html node158.html node158.html node1.html node221.html
---
# 15.1 Built-in Module `mac`
This module provides a subset of the operating system dependent
functionality provided by the optional built-in module `posix`.
It is best accessed through the more portable standard module
`os`.
The following functions are available in this module:
`chdir`,
`close`,
`dup`,
`fdopen`,
`getcwd`,
`lseek`,
`listdir`,
`mkdir`,
`open`,
`read`,
`rename`,
`rmdir`,
`stat`,
`sync`,
`unlink`,
`write`,
as well as the exception `error`. Note that the times returned by
`stat` are floating-point values, like all time values in
MacPython.
One additional function is available: `xstat`. This function
returns the same information as `stat`, but with three extra
values appended: the size of the resource fork of the file and its
4-char creator and type.
---
guido@cnri.reston.va.us


Classes and Class Instances

node17.html node14.html node15.html node1.html node221.html
---
### Classes and Class Instances
(See Chapters 3 and 7 of the Python Reference Manual for these.)
---
guido@cnri.reston.va.us


15.2 Standard Module macpath

node161.html node158.html node159.html node1.html node221.html
---
# 15.2 Standard Module `macpath`
This module provides a subset of the pathname manipulation functions
available from the optional standard module `posixpath`. It is
best accessed through the more portable standard module `os`, as
`os.path`.
The following functions are available in this module:
`normcase`,
`normpath`,
`isabs`,
`join`,
`split`,
`isdir`,
`isfile`,
`walk`,
`exists`.
For other functions available in `posixpath` dummy counterparts
are available.
---
guido@cnri.reston.va.us


15.3 Built-in Module ctb

node162.html node158.html node160.html node1.html node221.html
---
# 15.3 Built-in Module `ctb`
This module provides a partial interface to the Macintosh
Communications Toolbox. Currently, only Connection Manager tools are
supported. It may not be available in all Mac Python versions.
---
- 15.3.1 connection object (node162.html#SECTION001631000000000000000)
---
guido@cnri.reston.va.us


15.3.1 connection object

node163.html node161.html node161.html node1.html node221.html
---
## 15.3.1 connection object
For all connection methods that take a timeout argument, a value
of `-1` is indefinite, meaning that the command runs to completion.
---
node163.html node161.html node161.html node1.html node221.html
guido@cnri.reston.va.us


15.4 Built-in Module macconsole

node164.html node158.html node162.html node1.html node221.html
---
# 15.4 Built-in Module `macconsole`
This module is available on the Macintosh, provided Python has been
built using the Think C compiler. It provides an interface to the
Think console package, with which basic text windows can be created.
---
- 15.4.1 macconsole options object (node164.html#SECTION001641000000000000000)
15.4.2 console window object (node165.html#SECTION001642000000000000000)
---
guido@cnri.reston.va.us


15.4.1 macconsole options object

node165.html node163.html node163.html node1.html node221.html
---
## 15.4.1 macconsole options object
These options are examined when a window is created:
---
guido@cnri.reston.va.us


15.4.2 console window object

node166.html node163.html node164.html node1.html node221.html
---
## 15.4.2 console window object
---
guido@cnri.reston.va.us


15.5 Built-in Module macdnr

node167.html node158.html node165.html node1.html node221.html
---
# 15.5 Built-in Module `macdnr`
This module provides an interface to the Macintosh Domain Name
Resolver. It is usually used in conjunction with the mactcp
module, to map hostnames to IP-addresses. It may not be available in
all Mac Python versions.
The `macdnr` module defines the following functions:
---
- 15.5.1 dnr result object (node167.html#SECTION001651000000000000000)
---
guido@cnri.reston.va.us


15.5.1 dnr result object

node168.html node166.html node166.html node1.html node221.html
---
## 15.5.1 dnr result object
Since the DNR calls all execute asynchronously you do not get the
results back immediately. Instead, you get a dnr result object. You
can check this object to see whether the query is complete, and access
its attributes to obtain the information when it is.
Alternatively, you can also reference the result attributes directly,
this will result in an implicit wait for the query to complete.
The rtnCode and cname attributes are always available, the
others depend on the type of query (address, hinfo or mx).
The simplest way to use the module to convert names to dotted-decimal
strings, without worrying about idle time, etc:
```text
>>> def gethostname(name):
... import macdnr
... dnrr = macdnr.StrToAddr(name)
... return macdnr.AddrToStr(dnrr.ip0)
```
---
guido@cnri.reston.va.us


15.6 Built-in Module macfs

node169.html node158.html node167.html node1.html node221.html
---
# 15.6 Built-in Module `macfs`
This module provides access to macintosh FSSpec handling, the Alias
Manager, finder aliases and the Standard File package.
Whenever a function or method expects a file argument, this
argument can be one of three things: (1) a full or partial Macintosh
pathname, (2) an FSSpec object or (3) a 3-tuple `(wdRefNum,
parID, name)` as described in Inside Mac VI. A description of aliases
and the standard file package can also be found there.
---
- 15.6.1 FSSpec objects (node169.html#SECTION001661000000000000000)
15.6.2 alias objects (node170.html#SECTION001662000000000000000)
15.6.3 FInfo objects (node171.html#SECTION001663000000000000000)
---
node169.html node158.html node167.html node1.html node221.html
guido@cnri.reston.va.us


15.6.1 FSSpec objects

node170.html node168.html node168.html node1.html node221.html
---
## 15.6.1 FSSpec objects
---
guido@cnri.reston.va.us


Functions

node18.html node14.html node16.html node1.html node221.html
---
### Functions
Function objects are created by function definitions. The only
operation on a function object is to call it:
`func ( argument-list )`.
There are really two flavors of function objects: built-in functions
and user-defined functions. Both support the same operation (to call
the function), but the implementation is different, hence the
different object types.
The implementation adds two special read-only attributes:
`f .func_code` is a function's code object (see below) and
`f .func_globals` is the dictionary used as the function's
global name space (this is the same as `m .__dict__` where
m is the module in which the function f was defined).
---
guido@cnri.reston.va.us


15.6.2 alias objects

node171.html node168.html node169.html node1.html node221.html
---
## 15.6.2 alias objects
Note that it is currently not possible to directly manipulate a resource
as an alias object. Hence, after calling Update or after
Resolve indicates that the alias has changed the Python program
is responsible for getting the data from the alias object and
modifying the resource.
---
guido@cnri.reston.va.us


15.6.3 FInfo objects

node172.html node168.html node170.html node1.html node221.html
---
## 15.6.3 FInfo objects
See Inside Mac for a complete description of what the various fields
mean.
---
guido@cnri.reston.va.us


15.7 Built-in Module MacOS

node173.html node158.html node171.html node1.html node221.html
---
# 15.7 Built-in Module `MacOS`
This module provides access to MacOS specific functionality in the
python interpreter, such as how the interpreter eventloop functions
and the like. Use with care.
Note the capitalisation of the module name, this is a historical
artefact.
---
node173.html node158.html node171.html node1.html node221.html
guido@cnri.reston.va.us


15.8 Standard module macostools

node174.html node158.html node172.html node1.html node221.html
---
# 15.8 Standard module `macostools`
This module contains some convenience routines for file-manipulation
on the Macintosh.
The `macostools` module defines the following functions:
Note that the process of creating finder aliases is not specified in
the Apple documentation. Hence, aliases created with `mkalias`
could conceivably have incompatible behaviour in some cases.
---
guido@cnri.reston.va.us


15.9 Standard module findertools

node175.html node158.html node173.html node1.html node221.html
---
# 15.9 Standard module `findertools`
This module contains routines that give Python programs access to some
functionality provided by the finder. They are implemented as wrappers
around the AppleEvent interface to the finder.
All file and folder parameters can be specified either as full
pathnames or as `FSSpec` objects.
The `findertools` module defines the following functions:
---
guido@cnri.reston.va.us


15.10 Built-in Module mactcp

node176.html node158.html node174.html node1.html node221.html
---
# 15.10 Built-in Module `mactcp`
This module provides an interface to the Macintosh TCP/IP driver
MacTCP. There is an accompanying module `macdnr` which provides an
interface to the name-server (allowing you to translate hostnames to
ip-addresses), a module `MACTCPconst` which has symbolic names for
constants constants used by MacTCP. Since the builtin module
`socket` is also available on the mac it is usually easier to use
sockets in stead of the mac-specific MacTCP API.
A complete description of the MacTCP interface can be found in the
Apple MacTCP API documentation.
---
- 15.10.1 TCP Stream Objects (node176.html#SECTION0016101000000000000000)
15.10.2 TCP Status Objects (node177.html#SECTION0016102000000000000000)
15.10.3 UDP Stream Objects (node178.html#SECTION0016103000000000000000)
---
guido@cnri.reston.va.us


15.10.1 TCP Stream Objects

node177.html node175.html node175.html node1.html node221.html
---
## 15.10.1 TCP Stream Objects
---
node177.html node175.html node175.html node1.html node221.html
guido@cnri.reston.va.us


15.10.2 TCP Status Objects

node178.html node175.html node176.html node1.html node221.html
---
## 15.10.2 TCP Status Objects
This object has no methods, only some members holding information on
the connection. A complete description of all fields in this objects
can be found in the Apple documentation. The most interesting ones are:
---
guido@cnri.reston.va.us


15.10.3 UDP Stream Objects

node179.html node175.html node177.html node1.html node221.html
---
## 15.10.3 UDP Stream Objects
Note that, unlike the name suggests, there is nothing stream-like
about UDP.
---
guido@cnri.reston.va.us


15.11 Built-in Module macspeech

node180.html node158.html node178.html node1.html node221.html
---
# 15.11 Built-in Module `macspeech`
This module provides an interface to the Macintosh Speech Manager,
allowing you to let the Macintosh utter phrases. You need a version of
the speech manager extension (version 1 and 2 have been tested) in
your `Extensions` folder for this to work. The module does not
provide full access to all features of the Speech Manager yet. It may
not be available in all Mac Python versions.
---
- 15.11.1 voice objects (node180.html#SECTION0016111000000000000000)
15.11.2 speech channel objects (node181.html#SECTION0016112000000000000000)
---
guido@cnri.reston.va.us


Methods

node19.html node14.html node17.html node1.html node221.html
---
### Methods
Methods are functions that are called using the attribute notation.
There are two flavors: built-in methods (such as `append()` on
lists) and class instance methods. Built-in methods are described
with the types that support them.
The implementation adds two special read-only attributes to class
instance methods: `m .im_self` is the object whose method this
is, and `m .im_func` is the function implementing the method.
Calling `m ( arg-1 , arg-2 , ..., arg-n )` is completely equivalent to calling
`m .im_func( m .im_self, arg-1 , arg-2 ,
..., arg-n )`.
(See the Python Reference Manual for more info.)
---
guido@cnri.reston.va.us


15.11.1 voice objects

node181.html node179.html node179.html node1.html node221.html
---
## 15.11.1 voice objects
Voice objects contain the description of a voice. It is currently not
yet possible to access the parameters of a voice.
---
guido@cnri.reston.va.us


15.11.2 speech channel objects

node182.html node179.html node180.html node1.html node221.html
---
## 15.11.2 speech channel objects
A speech channel object allows you to speak strings with slightly more
control than `SpeakString()`, and allows you to use multiple
speakers at the same time. Please note that channel pitch and rate are
interrelated in some way, so that to make your Macintosh sing you will
have to adjust both.
---
guido@cnri.reston.va.us


15.12 Standard module EasyDialogs

node183.html node158.html node181.html node1.html node221.html
---
# 15.12 Standard module `EasyDialogs`
The `EasyDialogs` module contains some simple dialogs for
the Macintosh, modelled after the `stdwin` dialogs with similar
names.
The `EasyDialogs` module defines the following functions:
Note that `EasyDialogs` does not currently use the notification
manager. This means that displaying dialogs while the program is in
the background will lead to unexpected results and possibly
crashes. Also, all dialogs are modeless and hence expect to be at the
top of the stacking order. This is true when the dialogs are created,
but windows that pop-up later (like a console window) may also result
in crashes.
---
node183.html node158.html node181.html node1.html node221.html
guido@cnri.reston.va.us


15.13 Standard module FrameWork

node184.html node158.html node182.html node1.html node221.html
---
# 15.13 Standard module `FrameWork`
The `FrameWork` module contains classes that together provide a
framework for an interactive Macintosh application. The programmer
builds an application by creating subclasses that override various
methods of the bases classes, thereby implementing the functionality
wanted. Overriding functionality can often be done on various
different levels, i.e. to handle clicks in a single dialog window in a
non-standard way it is not necessary to override the complete event
handling.
The `FrameWork` is still very much work-in-progress, and the
documentation describes only the most important functionality, and not
in the most logical manner at that. Examine the source or the examples
for more details.
The `FrameWork` module defines the following functions:
---
- 15.13.1 Application objects (node184.html#SECTION0016131000000000000000)
15.13.2 Window Objects (node185.html#SECTION0016132000000000000000)
15.13.3 ControlsWindow Object (node186.html#SECTION0016133000000000000000)
15.13.4 ScrolledWindow Object (node187.html#SECTION0016134000000000000000)
15.13.5 DialogWindow Objects (node188.html#SECTION0016135000000000000000)
---
node184.html node158.html node182.html node1.html node221.html
guido@cnri.reston.va.us


15.13.1 Application objects

node185.html node183.html node183.html node1.html node221.html
---
## 15.13.1 Application objects
Application objects have the following methods, among others:
---
guido@cnri.reston.va.us


15.13.2 Window Objects

node186.html node183.html node184.html node1.html node221.html
---
## 15.13.2 Window Objects
Window objects have the following methods, among others:
---
guido@cnri.reston.va.us


15.13.3 ControlsWindow Object

node187.html node183.html node185.html node1.html node221.html
---
## 15.13.3 ControlsWindow Object
ControlsWindow objects have the following methods besides those of
`Window` objects:
---
guido@cnri.reston.va.us


15.13.4 ScrolledWindow Object

node188.html node183.html node186.html node1.html node221.html
---
## 15.13.4 ScrolledWindow Object
ScrolledWindow objects are ControlsWindow objects with the following
extra methods:
---
guido@cnri.reston.va.us


15.13.5 DialogWindow Objects

node189.html node183.html node187.html node1.html node221.html
---
## 15.13.5 DialogWindow Objects
DialogWindow objects have the following methods besides those of
`Window` objects:
---
guido@cnri.reston.va.us


15.14 Standard module MiniAEFrame

node190.html node158.html node188.html node1.html node221.html
---
# 15.14 Standard module `MiniAEFrame`
The module MiniAEFrame provides a framework for an application
that can function as an OSA server, i.e. receive and process
AppleEvents. It can be used in conjunction with FrameWork or
standalone.
This module is temporary, it will eventually be replaced by a module
that handles argument names better and possibly automates making your
application scriptable.
The MiniAEFrame module defines the following classes:
---
- 15.14.1 AEServer Objects (node190.html#SECTION0016141000000000000000)
---
guido@cnri.reston.va.us


Code Objects

node20.html node14.html node18.html node1.html node221.html
---
### Code Objects
Code objects are used by the implementation to represent
``pseudo-compiled'' executable Python code such as a function body.
They differ from function objects because they don't contain a
reference to their global execution environment. Code objects are
returned by the built-in `compile()` function and can be
extracted from function objects through their `func_code`
attribute.
A code object can be executed or evaluated by passing it (instead of a
source string) to the `exec` statement or the built-in
`eval()` function.
(See the Python Reference Manual for more info.)
---
guido@cnri.reston.va.us


15.14.1 AEServer Objects

node191.html node189.html node189.html node1.html node221.html
---
## 15.14.1 AEServer Objects
Note that there are some serious problems with the current
design. AppleEvents which have non-identifier 4-char designators for
arguments are not implementable, and it is not possible to return an
error to the originator. This will be addressed in a future release.
---
guido@cnri.reston.va.us


16 Standard Windowing Interface

node192.html lib.html node190.html node1.html node221.html
---
# 16 Standard Windowing Interface
The modules in this chapter are available only on those systems where
the STDWIN library is available. STDWIN runs on Unix under X11 and
on the Macintosh. See CWI report CS-R8817.
Warning: Using STDWIN is not recommended for new
applications. It has never been ported to Microsoft Windows or
Windows NT, and for X11 or the Macintosh it lacks important
functionality -- in particular, it has no tools for the construction
of dialogs. For most platforms, alternative, native solutions exist
(though none are currently documented in this manual): Tkinter for
Unix under X11, native Xt with Motif or Athena widgets for Unix
under X11, Win32 for Windows and Windows NT, and a collection of
native toolkit interfaces for the Macintosh.
---
- 16.1 Built-in Module `stdwin` (node192.html#SECTION001710000000000000000)
- 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)
16.2 Standard Module `stdwinevents` (node200.html#SECTION001720000000000000000)
16.3 Standard Module `rect` (node201.html#SECTION001730000000000000000)
---
guido@cnri.reston.va.us