16.1.2.2 A Simple Hello World Program

node502.html | node501.html | node504.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.2.2 A Simple Hello World Program
```text

from Tkinter import * 1
2
class Application(Frame): 3
def say_hi(self): 4
print "hi there, everyone!" 5
6
def createWidgets(self): 7
self.QUIT = Button(self) 8
self.QUIT["text"] = "QUIT" 9
self.QUIT["fg"] = "red" 10
self.QUIT["command"] = self.quit 11
12
self.QUIT.pack({"side": "left"}) 13
14
self.hi_there = Button(self) 15
self.hi_there["text"] = "Hello", 16
self.hi_there["command"] = self.say_hi 17
18
self.hi_there.pack({"side": "left"}) 19
20
21
def __init__(self, master=None): 22
Frame.__init__(self, master) 23
self.pack() 24
self.createWidgets() 25
26
app = Application() 27
app.mainloop() 28
```


16.1.3 A (Very) Quick Look at Tcl/Tk

node503.html | module-Tkinter.html | tkinter-basic-mapping.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.1.3 A (Very) Quick Look at Tcl/Tk
The class hierarchy looks complicated, but in actual practice,
application programmers almost always refer to the classes at the very
bottom of the hierarchy.
Notes:
- These classes are provided for the purposes of
organizing certain functions under one namespace. They aren't meant to
be instantiated independently.
- The Tk class is meant to be instantiated only once in
an application. Application programmers need not instantiate one
explicitly, the system creates one whenever any of the other classes
are instantiated.
- The Widget class is not meant to be instantiated, it
is meant only for subclassing to make ``real'' widgets (in C++, this
is called an `abstract class').
To make use of this reference material, there will be times when you
will need to know how to read short passages of Tk and how to identify
the various parts of a Tk command.
(See section 16.1.4 (tkinter-basic-mapping.html#tkinter-basic-mapping) for the
Tkinter (module-Tkinter.html) equivalents of what's below.)
Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are
just lists of tokens separated by spaces. A Tk widget is just its
class, the options that help configure it, and the
actions that make it do useful things.
To make a widget in Tk, the command is always of the form:
```text

classCommand newPathname options
```
classCommand: denotes which kind of widget to make (a button, a label, a menu...)
newPathname: is the new name for this widget. All names in Tk must be unique. To
help enforce this, widgets in Tk are named with pathnames, just
like files in a file system. The top level widget, the root,
is called `.` (period) and children are delimited by more
periods. For example, `.myApp.controlPanel.okButton` might be
the name of a widget.
options: configure the widget's appearance and in some cases, its
behavior. The options come in the form of a list of flags and values.
Flags are proceeded by a `-', like unix shell command flags, and
values are put in quotes if they are more than one word.
For example:
```text

button .fred -fg red -text "hi there"
^ ^ \_____________________/
| | |
class new options
command widget (-opt val -opt val ...)
```
Once created, the pathname to the widget becomes a new command. This
new widget command is the programmer's handle for getting the new
widget to perform some action. In C, you'd express this as
someAction(fred, someOptions), in C++, you would express this as
fred.someAction(someOptions), and in Tk, you say:
```text

.fred someAction someOptions
```
Note that the object name, `.fred`, starts with a dot.
As you'd expect, the legal values for someAction will depend on
the widget's class: `.fred disable` works if fred is a
button (fred gets greyed out), but does not work if fred is a label
(disabling of labels is not supported in Tk).
The legal values of someOptions is action dependent. Some
actions, like `disable`, require no arguments, others, like
a text-entry box's `delete` command, would need arguments
to specify what range of text to delete.


16.1.5 How Tk and Tkinter are Related

tkinter-basic-mapping.html | module-Tkinter.html | node507.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.1.5 How Tk and Tkinter are Related
Note:
This was derived from a graphical image; the image will be used
more directly in a subsequent version of this document.
From the top down:
Your App Here (Python): A Python application makes a Tkinter (module-Tkinter.html) call.
Tkinter (Python Module): This call (say, for example, creating a button widget), is
implemented in the Tkinter module, which is written in
Python. This Python function will parse the commands and the
arguments and convert them into a form that makes them look as if they
had come from a Tk script instead of a Python script.
tkinter (C): These commands and their arguments will be passed to a C function
in the tkinter - note the lowercase - extension module.
Tk Widgets (C and Tcl): This C function is able to make calls into other C modules,
including the C functions that make up the Tk library. Tk is
implemented in C and some Tcl. The Tcl part of the Tk widgets is used
to bind certain default behaviors to widgets, and is executed once at
the point where the Python Tkinter (module-Tkinter.html) module is
imported. (The user never sees this stage).
Tk (C): The Tk part of the Tk Widgets implement the final mapping to ...
Xlib (C): the Xlib library to draw graphics on the screen.


16.1.6 Handy Reference

node506.html | module-Tkinter.html | tkinter-setting-options.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.1.6 Handy Reference


16.1.6.2 The Packer

tkinter-setting-options.html | node507.html | node510.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.2 The Packer
The packer is one of Tk's geometry-management mechanisms. See also
the Packer class interface (classes/ClassPacker.html).
Geometry managers are used to specify the relative positioning of the
positioning of widgets within their container - their mutual
master. In contrast to the more cumbersome placer
(which is used less commonly, and we do not cover here), the packer
takes qualitative relationship specification - above, to
the left of, filling, etc - and works everything out to
determine the exact placement coordinates for you.
The size of any master widget is determined by the size of
the "slave widgets" inside. The packer is used to control where slave
widgets appear inside the master into which they are packed. You can
pack widgets into frames, and frames into other frames, in order to
achieve the kind of layout you desire. Additionally, the arrangement
is dynamically adjusted to accomodate incremental changes to the
configuration, once it is packed.
Note that widgets do not appear until they have had their geometry
specified with a geometry manager. It's a common early mistake to
leave out the geometry specification, and then be surprised when the
widget is created but nothing appears. A widget will appear only
after it has had, for example, the packer's pack() method
applied to it.
The pack() method can be called with keyword-option/value pairs that
control where the widget is to appear within its container, and how it
is to behave when the main application window is resized. Here are
some examples:
```text

fred.pack() # defaults to side = "top"
fred.pack(side = "left")
fred.pack(expand = 1)
```


16.1.6.3 Packer Options

node509.html | node507.html | node511.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.3 Packer Options
For more extensive information on the packer and the options that it
can take, see the man pages and page 183 of John Ousterhout's book.
anchor: Anchor type. Denotes where the packer is to place each slave in its
parcel.
expand: Boolean, `0` or `1`.
fill: Legal values: `'x'`, `'y'`, `'both'`, `'none'`.
ipadx and ipady: A distance - designating internal padding on each side of the slave
widget.
padx and pady: A distance - designating external padding on each side of the slave
widget.
side: Legal values are: `'left'`, `'right'`, `'top'`,
`'bottom'`.


16.1.6.4 Coupling Widget Variables

node510.html | node507.html | node512.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.4 Coupling Widget Variables
The current-value setting of some widgets (like text entry widgets)
can be connected directly to application variables by using special
options. These options are `variable`, `textvariable`,
`onvalue`, `offvalue`, and `value`. This
connection works both ways: if the variable changes for any reason,
the widget it's connected to will be updated to reflect the new value.
Unfortunately, in the current implementation of Tkinter (module-Tkinter.html) it is
not possible to hand over an arbitrary Python variable to a widget
through a `variable` or `textvariable` option. The only
kinds of variables for which this works are variables that are
subclassed from a class called Variable, defined in the
Tkinter (module-Tkinter.html) module.
There are many useful subclasses of Variable already defined:
StringVar, IntVar, DoubleVar, and
BooleanVar. To read the current value of such a variable,
call the get() method on
it, and to change its value you call the set() method. If
you follow this protocol, the widget will always track the value of
the variable, with no further intervention on your part.
For example:
```text

class App(Frame):
def __init__(self, master=None):
Frame.__init__(self, master)
self.pack()

self.entrythingy = Entry()
self.entrythingy.pack()

self.button.pack()
# here is the application variable
self.contents = StringVar()
# set it to some value
self.contents.set("this is a variable")
# tell the entry widget to watch this variable
self.entrythingy["textvariable"] = self.contents

# and here we get a callback when the user hits return.
# we will have the program print out the value of the
# application variable when the user hits return
self.entrythingy.bind('<Key-Return>',
self.print_contents)

def print_contents(self, event):
print "hi. contents of entry is now ---->", \
self.contents.get()
```


16.1.6.5 The Window Manager

node511.html | node507.html | node513.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.5 The Window Manager
In Tk, there is a utility command, `wm`, for interacting with the
window manager. Options to the `wm` command allow you to control
things like titles, placement, icon bitmaps, and the like. In
Tkinter (module-Tkinter.html), these commands have been implemented as methods
on the Wm class. Toplevel widgets are subclassed from the
Wm class, and so can call the Wm methods directly.
To get at the toplevel window that contains a given widget, you can
often just refer to the widget's master. Of course if the widget has
been packed inside of a frame, the master won't represent a toplevel
window. To get at the toplevel window that contains an arbitrary
widget, you can call the _root() method. This
method begins with an underscore to denote the fact that this function
is part of the implementation, and not an interface to Tk functionality.
Here are some examples of typical usage:
```text

import Tkinter
class App(Frame):
def __init__(self, master=None):
Frame.__init__(self, master)
self.pack()

# create the application
myapp = App()

#
# here are method calls to the window manager class
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# start the program
myapp.mainloop()
```


16.1.6.6 Tk Option Data Types

node512.html | node507.html | node514.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.6 Tk Option Data Types
anchor: Legal values are points of the compass: `"n"`,
`"ne"`, `"e"`, `"se"`, `"s"`,
`"sw"`, `"w"`, `"nw"`, and also
`"center"`.
bitmap: There are eight built-in, named bitmaps: `'error'`, `'gray25'`,
`'gray50'`, `'hourglass'`, `'info'`, `'questhead'`,
`'question'`, `'warning'`. To specify an X bitmap
filename, give the full path to the file, preceded with an `@`,
as in `"@/usr/contrib/bitmap/gumby.bit"`.
boolean: You can pass integers 0 or 1 or the stings `"yes"` or `"no"` .
callback: This is any Python function that takes no arguments. For example:
```text

def print_it():
print "hi there"
fred["command"] = print_it
```
color: Colors can be given as the names of X colors in the rgb.txt file,
or as strings representing RGB values in 4 bit: `"#RGB"`, 8
bit: `"#RRGGBB"`, 12 bit" `"#RRRGGGBBB"`, or 16 bit
`"#RRRRGGGGBBBB"` ranges, where R,G,B here represent any
legal hex digit. See page 160 of Ousterhout's book for details.
cursor: The standard X cursor names from cursorfont.h can be used,
without the `XC_` prefix. For example to get a hand cursor
(XC_hand2), use the string `"hand2"`. You can also
specify a bitmap and mask file of your own. See page 179 of
Ousterhout's book.
distance: Screen distances can be specified in either pixels or absolute
distances. Pixels are given as numbers and absolute distances as
strings, with the trailing character denoting units: `c`
for centimeters, `i` for inches, `m` for millimeters,
`p` for printer's points. For example, 3.5 inches is expressed
as `"3.5i"`.
font: Tk uses a list font name format, such as `{courier 10 bold}`.
Font sizes with positive numbers are measured in points;
sizes with negative numbers are measured in pixels.
geometry: This is a string of the form "widthxheight", where
width and height are measured in pixels for most widgets (in
characters for widgets displaying text). For example:
`fred["geometry"] = "200x100"`.
justify: Legal values are the strings: `"left"`,
`"center"`, `"right"`, and `"fill"`.
region: This is a string with four space-delimited elements, each of
which is a legal distance (see above). For example: `"2 3 4
5"` and `"3i 2i 4.5i 2i"` and `"3c 2c 4c 10.43c"`
are all legal regions.
relief: Determines what the border style of a widget will be. Legal
values are: `"raised"`, `"sunken"`,
`"flat"`, `"groove"`, and `"ridge"`.
scrollcommand: This is almost always the set() method of some scrollbar
widget, but can be any widget method that takes a single argument.
Refer to the file Demo/tkinter/matt/canvas-with-scrollbars.py
in the Python source distribution for an example.
wrap:: Must be one of: `"none"`, `"char"`, or `"word"`.


16.1.6.7 Bindings and Events

node513.html | node507.html | node515.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.7 Bindings and Events
The bind method from the widget command allows you to watch for
certain events and to have a callback function trigger when that event
type occurs. The form of the bind method is:
```text

def bind(self, sequence, func, add=''):
```
where:
sequence: is a string that denotes the target kind of event. (See the bind
man page and page 201 of John Ousterhout's book for details).
func: is a Python function, taking one argument, to be invoked when the
event occurs. An Event instance will be passed as the argument.
(Functions deployed this way are commonly known as callbacks.)
add: is optional, either "" or "+". Passing an empty string
denotes that this binding is to replace any other bindings that this
event is associated with. Preceeding with a "+" means that this
function is to be added to the list of functions bound to this event type.
For example:
```text

def turnRed(self, event):
event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turnRed)
```
Notice how the widget field of the event is being accesed in the
turnRed() callback. This field contains the widget that
caught the X event. The following table lists the other event fields
you can access, and how they are denoted in Tk, which can be useful
when referring to the Tk man pages.
```text

Tk Tkinter Event Field Tk Tkinter Event Field
-- ------------------- -- -------------------
%f focus %A char
%h height %E send_event
%k keycode %K keysym
%s state %N keysym_num
%t time %T type
%w width %W widget
%x x %X x_root
%y y %Y y_root
```


16.1.6.8 The index Parameter

node514.html | node507.html | module-Tix.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.1.6.8 The index Parameter
A number of widgets require``index'' parameters to be passed. These
are used to point at a specific place in a Text widget, or to
particular characters in an Entry widget, or to particular menu items
in a Menu widget.
Entry widget indexes (index, view index, etc.): Entry widgets have options that refer to character positions in the
text being displayed. You can use these Tkinter (module-Tkinter.html) functions
to access these special points in text widgets:
AtEnd(): refers to the last position in the text
AtInsert(): refers to the point where the text cursor is
AtSelFirst(): indicates the beginning point of the selected text
AtSelLast(): denotes the last point of the selected text and finally
At(x[, y]): refers to the character at pixel location x, y (with
y not used in the case of a text entry widget, which contains a
single line of text).
Text widget indexes: The index notation for Text widgets is very rich and is best described
in the Tk man pages.
Menu indexes (menu.invoke(), menu.entryconfig(), etc.): Some options and methods for menus manipulate specific menu entries.
Anytime a menu index is needed for an option or a parameter, you may
pass in:
- an integer which refers to the numeric position of the entry in
the widget, counted from the top, starting with 0;
- the string `'active'`, which refers to the menu position that is
currently under the cursor;
- the string `"last"` which refers to the last menu
item;
- An integer preceded by `@`, as in `@6`, where the integer is
interpreted as a y pixel coordinate in the menu's coordinate system;
- the string `"none"`, which indicates no menu entry at all, most
often used with menu.activate() to deactivate all entries, and
finally,
- a text string that is pattern matched against the label of the
menu entry, as scanned from the top of the menu to the bottom. Note
that this index type is considered after all the others, which means
that matches for menu items labelled `last`, `active`, or
`none` may be interpreted as the above literals, instead.


16.2.1 Using Tix

module-Tix.html | module-Tix.html | node518.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.2.1 Using Tix
To use Tix (module-Tix.html), you must have the Tix (module-Tix.html) widgets installed,
usually alongside your installation of the Tk widgets.
To test your installation, try the following:
```text

import Tix
root = Tix.Tk()
root.tk.eval('package require Tix')
```
If this fails, you have a Tk installation problem which must be
resolved before proceeding. Use the environment variable TIX_LIBRARY
to point to the installed Tix (module-Tix.html) library directory, and
make sure you have the dynamic object library (tix8183.dll or
libtix8183.so) in the same directory that contains your Tk
dynamic object library (tk8183.dll or libtk8183.so). The
directory with the dynamic object library should also have a file
called pkgIndex.tcl (case sensitive), which contains the line:
```text

package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
```


16.2.2 Tix Widgets

node517.html | module-Tix.html | node519.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.2.2 Tix Widgets
Tix (http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm)
introduces over 40 widget classes to the Tkinter (module-Tkinter.html)
repertoire. There is a demo of all the Tix (module-Tix.html) widgets in the
Demo/tix directory of the standard distribution.


16.2.2.1 Basic Widgets

node518.html | node518.html | node520.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.1 Basic Widgets


16.2.2.2 File Selectors

node519.html | node518.html | node521.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.2 File Selectors


16.2.2.3 Hierachical ListBox

node520.html | node518.html | node522.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.3 Hierachical ListBox


16.2.2.4 Tabular ListBox

node521.html | node518.html | node523.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.4 Tabular ListBox


16.2.2.5 Manager Widgets

node522.html | node518.html | node524.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.5 Manager Widgets


16.2.2.6 Image Types

node523.html | node518.html | node525.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.6 Image Types
The Tix (module-Tix.html) module adds:
- pixmap (http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm)
capabilities to all Tix (module-Tix.html) and Tkinter (module-Tkinter.html) widgets to
create color images from XPM files.
- Compound (http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.html)
image types can be used to create images that consists of multiple
horizontal lines; each line is composed of a series of items (texts,
bitmaps, images or spaces) arranged from left to right. For example, a
compound image can be used to display a bitmap and a text string
simutaneously in a Tk Button widget.


16.2.2.7 Miscellaneous Widgets

node524.html | node518.html | node526.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.7 Miscellaneous Widgets


16.2.2.8 Form Geometry Manager

node525.html | node518.html | node527.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.2.2.8 Form Geometry Manager
In addition, Tix (module-Tix.html) augments Tkinter (module-Tkinter.html) by providing:


16.2.3 Tix Commands

node526.html | module-Tix.html | module-ScrolledText.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.2.3 Tix Commands


16.5.1 Menus

idle.html | idle.html | node533.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.5.1 Menus


16.5.1.1 File menu

node532.html | node532.html | node534.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.1.1 File menu
New window: create a new editing window
Open...: open an existing file
Open module...: open an existing module (searches sys.path)
Class browser: show classes and methods in current file
Path browser: show sys.path directories, modules, classes and methods
Save: save current window to the associated file (unsaved
windows have a * before and after the window title)
Save As...: save current window to new file, which becomes
the associated file
Save Copy As...: save current window to different file
without changing the associated file
Close: close current window (asks to save if unsaved)
Exit: close all windows and quit IDLE (asks to save if unsaved)


16.5.1.2 Edit menu

node533.html | node532.html | node535.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.1.2 Edit menu
Undo: Undo last change to current window (max 1000 changes)
Redo: Redo last undone change to current window
Cut: Copy selection into system-wide clipboard; then delete selection
Copy: Copy selection into system-wide clipboard
Paste: Insert system-wide clipboard into window
Select All: Select the entire contents of the edit buffer
Find...: Open a search dialog box with many options
Find again: Repeat last search
Find selection: Search for the string in the selection
Find in Files...: Open a search dialog box for searching files
Replace...: Open a search-and-replace dialog box
Go to line: Ask for a line number and show that line
Indent region: Shift selected lines right 4 spaces
Dedent region: Shift selected lines left 4 spaces
Comment out region: Insert ## in front of selected lines
Uncomment region: Remove leading # or ## from selected lines
Tabify region: Turns leading stretches of spaces into tabs
Untabify region: Turn all tabs into the right number of spaces
Expand word: Expand the word you have typed to match another
word in the same buffer; repeat to get a different expansion
Format Paragraph: Reformat the current blank-line-separated paragraph
Import module: Import or reload the current module
Run script: Execute the current file in the __main__ namespace


16.5.1.3 Windows menu

node534.html | node532.html | node536.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.1.3 Windows menu
Zoom Height: toggles the window between normal size (24x80)
and maximum height.
The rest of this menu lists the names of all open windows; select one
to bring it to the foreground (deiconifying it if necessary).


node535.html | node532.html | node537.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.1.4 Debug menu (in the Python Shell window only)
Go to file/line: look around the insert point for a filename
and linenumber, open the file, and show the line.
Open stack viewer: show the stack traceback of the last exception
Debugger toggle: Run commands in the shell under the debugger
JIT Stack viewer toggle: Open stack viewer on traceback


16.5.2 Basic editing and navigation

node536.html | idle.html | node538.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.5.2 Basic editing and navigation
- Backspace deletes to the left; Del deletes to the right
- Arrow keys and Page Up/Page Down to move around
- Home/End go to begin/end of line
- C-Home/C-End go to begin/end of file
- Some Emacs bindings may also work, including C-B,
C-P, C-A, C-E, C-D, C-L


16.5.2.1 Automatic indentation

node537.html | node537.html | node539.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.2.1 Automatic indentation
After a block-opening statement, the next line is indented by 4 spaces
(in the Python Shell window by one tab). After certain keywords
(break, return etc.) the next line is dedented. In leading
indentation, Backspace deletes up to 4 spaces if they are there.
Tab inserts 1-4 spaces (in the Python Shell window one tab).
See also the indent/dedent region commands in the edit menu.


16.5.2.2 Python Shell window

node538.html | node537.html | node540.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.2.2 Python Shell window
- C-C interrupts executing command
- C-D sends end-of-file; closes window if typed at
a "»> " prompt
- Alt-p retrieves previous command matching what you have typed
- Alt-n retrieves next
- Return while on any previous command retrieves that command
- Alt-/ (Expand word) is also useful here


16.5.3 Syntax colors

node539.html | idle.html | node541.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.5.3 Syntax colors
The coloring is applied in a background ``thread,'' so you may
occasionally see uncolorized text. To change the color
scheme, edit the `[Colors]` section in config.txt.
Python syntax colors:: Keywords: orange
Strings: green
Comments: red
Definitions: blue
Shell colors:: Console output: brown
stdout: blue
stderr: dark green
stdin: black


16.5.3.1 Command line usage

node540.html | node540.html | other-gui-packages.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 16.5.3.1 Command line usage
```text

idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...

-c command run this command
-d enable debugger
-e edit mode; arguments are files to be edited
-s run $IDLESTARTUP or $PYTHONSTARTUP first
-t title set title of shell window
```
If there are arguments:
1. If -e is used, arguments are files opened for
editing and `sys.argv` reflects the arguments passed to
IDLE itself.
2. Otherwise, if -c is used, all arguments are
placed in `sys.argv[1:...]`, with `sys.argv[0]` set
to `'-c'`.
3. Otherwise, if neither -e nor -c is
used, the first argument is a script which is executed with
the remaining arguments in `sys.argv[1:...]` and
`sys.argv[0]` set to the script name. If the script name
is '-', no script is executed but an interactive Python
session is started; the arguments are still available in
`sys.argv`.


17.1.3 An example

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


18.1.1 Creating AST Objects

module-parser.html | module-parser.html | node552.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.1.1 Creating AST Objects
AST objects may be created from source code or from a parse tree.
When creating an AST object from source, different functions are used
to create the `'eval'` and `'exec'` forms.


18.1.2 Converting AST Objects

node551.html | module-parser.html | node553.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.1.2 Converting AST Objects
AST objects, regardless of the input used to create them, may be
converted to parse trees represented as list- or tuple- trees, or may
be compiled into executable code objects. Parse trees may be
extracted with or without line numbering information.


18.1.3 Queries on AST Objects

node552.html | module-parser.html | node554.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.1.3 Queries on AST Objects
Two functions are provided which allow an application to determine if
an AST was created as an expression or a suite. Neither of these
functions can be used to determine if an AST was created from source
code via expr() or suite() or from a parse tree
via sequence2ast().


18.1.4 Exceptions and Error Handling

node553.html | module-parser.html | node555.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.1.4 Exceptions and Error Handling
The parser module defines a single exception, but may also pass other
built-in exceptions from other portions of the Python runtime
environment. See each function for information about the exceptions
it can raise.
Note that the functions compileast(), expr(), and
suite() may throw exceptions which are normally thrown by the
parsing and compilation process. These include the built in
exceptions MemoryError, OverflowError,
SyntaxError, and SystemError. In these cases, these
exceptions carry all the meaning normally associated with them. Refer
to the descriptions of each function for detailed information.


18.1.5 AST Objects

node554.html | module-parser.html | node556.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.1.5 AST Objects
Ordered and equality comparisons are supported between AST objects.
Pickling of AST objects (using the pickle (module-pickle.html) module) is also
supported.
AST objects have the following methods:


18.1.6 Examples

node555.html | module-parser.html | node557.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 18.1.6 Examples
The parser modules allows operations to be performed on the parse tree
of Python source code before the bytecode is generated, and provides
for inspection of the parse tree for information gathering purposes.
Two examples are presented. The simple example demonstrates emulation
of the compile()built-in function and
the complex example shows the use of a parse tree for information
discovery.


18.1.6.1 Emulation of compile()

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

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

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

import parser

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

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


18.1.6.2 Information Discovery

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

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

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

from types import ListType, TupleType

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

import symbol
import token

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

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

class SuiteInfoBase:
_docstring = ''
_name = ''

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

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

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

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

def get_docs(fileName):
import os
import parser

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


19.2 Limitations

module-compiler.html | compiler.html | node574.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 19.2 Limitations
There are some problems with the error checking of the compiler
package. The interpreter detects syntax errors in two distinct
phases. One set of errors is detected by the interpreter's parser,
the other set by the compiler. The compiler package relies on the
interpreter's parser, so it get the first phases of error checking for
free. It implements the second phase itself, and that implement is
incomplete. For example, the compiler package does not raise an error
if a name appears more than once in an argument list:
`def f(x, x): ...`
A future version of the compiler should fix these problems.


19.3 Python Abstract Syntax

node573.html | compiler.html | module-compiler.ast.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 19.3 Python Abstract Syntax
The compiler.ast module defines an abstract syntax for
Python. In the abstract syntax tree, each node represents a syntactic
construct. The root of the tree is Module object.
The abstract syntax offers a higher level interface to parsed Python
source code. The parser (http://www.python.org/doc/current/lib/module-parser.html)
module and the compiler written in C for the Python interpreter use a
concrete syntax tree. The concrete syntax is tied closely to the
grammar description used for the Python parser. Instead of a single
node for a construct, there are often several levels of nested nodes
that are introduced by Python's precedence rules.
The abstract syntax tree is created by the
compiler.transformer module. The transformer relies on the
builtin Python parser to generate a concrete syntax tree. It
generates an abstract syntax tree from the concrete tree.
The transformer module was created by Greg
Steinand Bill Tuttfor an
experimental Python-to-C compiler. The current version contains a
number of modifications and improvements, but the basic form of the
abstract syntax and of the transformer are due to Stein and Tutt.


19.3.2 Assignment nodes

module-compiler.ast.html | node574.html | node577.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 19.3.2 Assignment nodes
There is a collection of nodes used to represent assignments. Each
assignment statement in the source code becomes a single
Assign node in the AST. The nodes attribute is a
list that contains a node for each assignment target. This is
necessary because assignment can be chained, e.g. `a = b = 2`.
Each Node in the list will be one of the following classes:
AssAttr, AssList, AssName, or
AssTuple.
Each target assignment node will describe the kind of object being
assigned to: AssName for a simple name, e.g. `a = 1`.
AssAttr for an attribute assigned, e.g. `a.x = 1`.
AssList and AssTuple for list and tuple expansion
respectively, e.g. `a, b, c = a_tuple`.
The target assignment nodes also have a flags attribute that
indicates whether the node is being used for assignment or in a delete
statement. The AssName is also used to represent a delete
statement, e.g. del x.
When an expression contains several attribute references, an
assignment or delete statement will contain only one AssAttr
node - for the final attribute reference. The other attribute
references will be represented as Getattr nodes in the
expr attribute of the AssAttr instance.


19.3.3 Examples

node576.html | node574.html | module-compiler.visitor.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 19.3.3 Examples
This section shows several simple examples of ASTs for Python source
code. The examples demonstrate how to use the parse()
function, what the repr of an AST looks like, and how to access
attributes of an AST node.
The first module defines a single function. Assume it is stored in
/tmp/doublelib.py.
```text

"""This is an example module.

This is the docstring.
"""

def double(x):
"Return twice the argument"
return x * 2
```
In the interactive interpreter session below, I have reformatted the
long AST reprs for readability. The AST reprs use unqualified class
names. If you want to create an instance from a repr, you must import
the class names from the compiler.ast module.
```text

>>> import compiler
>>> mod = compiler.parseFile("/tmp/doublelib.py")
>>> mod
Module('This is an example module.\n\nThis is the docstring.\n',
Stmt([Function('double', ['x'], [], 0, 'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> from compiler.ast import *
>>> Module('This is an example module.\n\nThis is the docstring.\n',
... Stmt([Function('double', ['x'], [], 0, 'Return twice the argument',
... Stmt([Return(Mul((Name('x'), Const(2))))]))]))
Module('This is an example module.\n\nThis is the docstring.\n',
Stmt([Function('double', ['x'], [], 0, 'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> mod.doc
'This is an example module.\n\nThis is the docstring.\n'
>>> for node in mod.node.nodes:
... print node
...
Function('double', ['x'], [], 0, 'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))
>>> func = mod.node.nodes[0]
>>> func.code
Stmt([Return(Mul((Name('x'), Const(2))))])
```


19.5 Bytecode Generation

module-compiler.visitor.html | compiler.html | sgi.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 19.5 Bytecode Generation
The code generator is a visitor that emits bytecodes. Each visit method
can call the emit() method to emit a new bytecode. The basic
code generator is specialized for modules, classes, and functions. An
assembler converts that emitted instructions to the low-level bytecode
format. It handles things like generator of constant lists of code
objects and calculation of jump offsets.


20.4.1 Functions Defined in Module fl

module-fl.html | module-fl.html | form-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 20.4.1 Functions Defined in Module fl
Module fl defines the following functions. For more
information about what they do, see the description of the equivalent
C function in the FORMS documentation:


module-pickle.html | module-pickle.html | node60.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.14.1 Relationship to other Python modules
The pickle module has an optimized cousin called the
cPickle module. As its name implies, cPickle is
written in C, so it can be up to 1000 times faster than
pickle. However it does not support subclassing of the
Pickler() and Unpickler() classes, because in
cPickle these are functions, not classes. Most applications
have no need for this functionality, and can benefit from the improved
performance of cPickle. Other than that, the interfaces of
the two modules are nearly identical; the common interface is
described in this manual and differences are pointed out where
necessary. In the following discussions, we use the term ``pickle''
to collectively describe the pickle and
cPickle modules.
The data streams the two modules produce are guaranteed to be
interchangeable.
Python has a more primitive serialization module called
marshal (module-marshal.html), but in general
pickle should always be the preferred way to serialize Python
objects. marshal exists primarily to support Python's
.pyc files.
The pickle module differs from marshal (module-marshal.html) several
significant ways:
- The pickle module keeps track of the objects it has
already serialized, so that later references to the same object
won't be serialized again. marshal doesn't do this.
This has implications both for recursive objects and object
sharing. Recursive objects are objects that contain references
to themselves. These are not handled by marshal, and in fact,
attempting to marshal recursive objects will crash your Python
interpreter. Object sharing happens when there are multiple
references to the same object in different places in the object
hierarchy being serialized. pickle stores such objects
only once, and ensures that all other references point to the
master copy. Shared objects remain shared, which can be very
important for mutable objects.
- marshal cannot be used to serialize user-defined
classes and their instances. pickle can save and
restore class instances transparently, however the class
definition must be importable and live in the same module as
when the object was stored.
- The marshal serialization format is not guaranteed to
be portable across Python versions. Because its primary job in
life is to support .pyc files, the Python implementers
reserve the right to change the serialization format in
non-backwards compatible ways should the need arise. The
pickle serialization format is guaranteed to be
backwards compatible across Python releases.
- The pickle module doesn't handle code objects, which
the marshal module does. This avoids the possibility
of smuggling Trojan horses into a program through the
pickle module3.3 (#foot6913).
Note that serialization is a more primitive notion than persistence;
although
pickle reads and writes file objects, it does not handle the
issue of naming persistent objects, nor the (even more complicated)
issue of concurrent access to persistent objects. The pickle
module can transform a complex object into a byte stream and it can
transform the byte stream into an object with the same internal
structure. Perhaps the most obvious thing to do with these byte
streams is to write them onto a file, but it is also conceivable to
send them across a network or store them in a database. The module
shelve (module-shelve.html) provides a simple interface
to pickle and unpickle objects on DBM-style database files.


3.14.2 Data stream format

node59.html | module-pickle.html | node61.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.14.2 Data stream format
The data format used by pickle is Python-specific. This has
the advantage that there are no restrictions imposed by external
standards such as XDR(which can't represent pointer sharing); however it means that
non-Python programs may not be able to reconstruct pickled Python
objects.
By default, the pickle data format uses a printable ASCII
representation. This is slightly more voluminous than a binary
representation. The big advantage of using printable ASCII (and of
some other characteristics of pickle's representation) is that
for debugging or recovery purposes it is possible for a human to read
the pickled file with a standard text editor.
A binary format, which is slightly more efficient, can be chosen by
specifying a true value for the bin argument to the
Pickler constructor or the dump() and dumps()
functions.


22. MS Windows Specific Services

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


3.14.3 Usage

node60.html | module-pickle.html | node62.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.14.3 Usage
To serialize an object hierarchy, you first create a pickler, then you
call the pickler's dump() method. To de-serialize a data
stream, you first create an unpickler, then you call the unpickler's
load() method. The pickle module provides the
following functions to make this process more convenient:
The pickle module also defines three exceptions:
The pickle module also exports two callables3.4 (#foot6918), Pickler and
Unpickler:
Pickler objects define one (or two) public methods:
It is possible to make multiple calls to the dump() method of
the same Pickler instance. These must then be matched to the
same number of calls to the load() method of the
corresponding Unpickler instance. If the same object is
pickled by multiple dump() calls, the load() will
all yield references to the same object3.5 (#foot6920).
Unpickler objects are defined as:
Unpickler objects have one (or two) public methods:


A.1 Frameworks

undoc.html | undoc.html | node614.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.1 Frameworks
Frameworks tend to be harder to document, but are well worth the
effort spent.
test: -- Regression testing framework. This is used for the Python
regression test, but is useful for other Python libraries as well.
This is a package rather than a single module.


A.2 Miscellaneous useful utilities

node613.html | undoc.html | node615.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.2 Miscellaneous useful utilities
Some of these are very old and/or not very robust; marked with ``hmm.''
bdb: -- A generic Python debugger base class (used by pdb).
ihooks: -- Import hook support (for rexec (module-rexec.html); may become obsolete).
smtpd: -- An SMTP daemon implementation which meets the minimum requirements
for RFC 821 (http://www.faqs.org/rfcs/rfc821.html) conformance.


A.3 Platform specific modules

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


A.4 Multimedia

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


A.6 SGI-specific Extension modules

obsolete-modules.html | undoc.html | reporting-bugs.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# A.6 SGI-specific Extension modules
The following are SGI specific, and may be out of touch with the
current version of reality.
cl: -- Interface to the SGI compression library.
sv: -- Interface to the ``simple video'' board on SGI Indigo
(obsolete hardware).


node61.html | module-pickle.html | pickle-protocol.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.14.4 What can be pickled and unpickled?
The following types can be pickled:
- `None`
- integers, long integers, floating point numbers, complex numbers
- normal and Unicode strings
- tuples, lists, and dictionaries containing only picklable objects
- functions defined at the top level of a module
- built-in functions defined at the top level of a module
- classes that are defined at the top level of a module
- instances of such classes whose __dict__ or
__setstate__() is picklable (see
section 3.14.5 (pickle-protocol.html#pickle-protocol) for details)
Attempts to pickle unpicklable objects will raise the
PicklingError exception; when this happens, an unspecified
number of bytes may have already been written to the underlying file.
Note that functions (built-in and user-defined) are pickled by ``fully
qualified'' name reference, not by value. This means that only the
function name is pickled, along with the name of module the function
is defined in. Neither the function's code, nor any of its function
attributes are pickled. Thus the defining module must be importable
in the unpickling environment, and the module must contain the named
object, otherwise an exception will be raised3.6 (#foot6921).
Similarly, classes are pickled by named reference, so the same
restrictions in the unpickling environment apply. Note that none of
the class's code or data is pickled, so in the following example the
class attribute `attr` is not restored in the unpickling
environment:
```text

class Foo:
attr = 'a class attr'

picklestring = pickle.dumps(Foo)
```
These restrictions are why picklable functions and classes must be
defined in the top level of a module.
Similarly, when class instances are pickled, their class's code and
data are not pickled along with them. Only the instance data are
pickled. This is done on purpose, so you can fix bugs in a class or
add methods to the class and still load objects that were created with
an earlier version of the class. If you plan to have long-lived
objects that will see many versions of a class, it may be worthwhile
to put a version number in the objects so that suitable conversions
can be made by the class's __setstate__() method.


C. History and License

reporting-bugs.html | lib.html | node621.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# C. History and License


C.1 History of the software

node620.html | node620.html | node622.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# C.1 History of the software
Python was created in the early 1990s by Guido van Rossum at Stichting
Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands
as a successor of a language called ABC. Guido remains Python's
principal author, although it includes many contributions from others.
In 1995, Guido continued his work on Python at the Corporation for
National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/)
in Reston, Virginia where he released several versions of the
software.
In May 2000, Guido and the Python core development team moved to
BeOpen.com to form the BeOpen PythonLabs team. In October of the same
year, the PythonLabs team moved to Zope Corporation (then Digital
Creations; see http://www.zope.com/). In 2001, the Python
Software Foundation (PSF, see http://www.python.org/psf/) was
formed, a non-profit organization created specifically to own
Python-related Intellectual Property. Digital Creations is a
sponsoring member of the PSF.
All Python releases are Open Source (see
http://www.opensource.org/ for the Open Source Definition).
Historically, most, but not all, Python releases have also been
GPL-compatible; the table below summarizes the various releases.
Note:
GPL-compatible doesn't mean that we're distributing
Python under the GPL. All Python licenses, unlike the GPL, let you
distribute a modified version without making your changes open source.
The GPL-compatible licenses make it possible to combine Python with
other software that is released under the GPL; the others don't.
Thanks to the many outside volunteers who have worked under Guido's
direction to make these releases possible.


node621.html | node620.html | modindex.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# C.2 Terms and conditions for accessing or otherwise using Python
PSF LICENSE AGREEMENT FOR PYTHON 2.2
1. This LICENSE AGREEMENT is between the Python Software Foundation
(``PSF''), and the Individual or Organization (``Licensee'') accessing
and otherwise using Python 2.2 software in source or binary
form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python
2.2 alone or in any derivative version, provided, however, that
PSF's License Agreement and PSF's notice of copyright, i.e.,
``Copyright © 2001 Python Software Foundation; All Rights
Reserved'' are retained in Python 2.2 alone or in any
derivative version prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 2.2 or any part thereof, and wants to
make the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 2.2.
4. PSF is making Python 2.2 available to Licensee on an ``AS IS''
basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.2 WILL
NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
2.2 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
2.2, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE
POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any
relationship of agency, partnership, or joint venture between PSF and
Licensee. This License Agreement does not grant permission to use PSF
trademarks or trade name in a trademark sense to endorse or promote
products or services of Licensee, or any third party.
8. By copying, installing or otherwise using Python 2.2, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an
office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
Individual or Organization (``Licensee'') accessing and otherwise
using this software in source or binary form and its associated
documentation (``the Software'').
2. Subject to the terms and conditions of this BeOpen Python License
Agreement, BeOpen hereby grants Licensee a non-exclusive,
royalty-free, world-wide license to reproduce, analyze, test, perform
and/or display publicly, prepare derivative works, distribute, and
otherwise use the Software alone or in any derivative version,
provided, however, that the BeOpen Python License is retained in the
Software, alone or in any derivative version prepared by Licensee.
3. BeOpen is making the Software available to Licensee on an ``AS IS''
basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
5. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
6. This License Agreement shall be governed by and interpreted in all
respects by the law of the State of California, excluding conflict of
law provisions. Nothing in this License Agreement shall be deemed to
create any relationship of agency, partnership, or joint venture
between BeOpen and Licensee. This License Agreement does not grant
permission to use BeOpen trademarks or trade names in a trademark
sense to endorse or promote products or services of Licensee, or any
third party. As an exception, the ``BeOpen Python'' logos available
at http://www.pythonlabs.com/logos.html may be used according to the
permissions granted on that web page.
7. By copying, installing or otherwise using the software, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
1. This LICENSE AGREEMENT is between the Corporation for National
Research Initiatives, having an office at 1895 Preston White Drive,
Reston, VA 20191 (``CNRI''), and the Individual or Organization
(``Licensee'') accessing and otherwise using Python 1.6.1 software in
source or binary form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, CNRI
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python 1.6.1
alone or in any derivative version, provided, however, that CNRI's
License Agreement and CNRI's notice of copyright, i.e., ``Copyright
© 1995-2001 Corporation for National Research Initiatives;
All Rights Reserved'' are retained in Python 1.6.1 alone or in any
derivative version prepared by Licensee. Alternately, in lieu of
CNRI's License Agreement, Licensee may substitute the following text
(omitting the quotes): ``Python 1.6.1 is made available subject to the
terms and conditions in CNRI's License Agreement. This Agreement
together with Python 1.6.1 may be located on the Internet using the
following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server
on the Internet using the following URL:
http://hdl.handle.net/1895.22/1013.''
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 1.6.1 or any part thereof, and wants to make
the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 1.6.1.
4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS''
basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. This License Agreement shall be governed by the federal
intellectual property law of the United States, including without
limitation the federal copyright law, and, to the extent such
U.S. federal law does not apply, by the law of the Commonwealth of
Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based
on Python 1.6.1 that incorporate non-separable material that was
previously distributed under the GNU General Public License (GPL), the
law of the Commonwealth of Virginia shall govern this License
Agreement only as to issues arising under or with respect to
Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this
License Agreement shall be deemed to create any relationship of
agency, partnership, or joint venture between CNRI and Licensee. This
License Agreement does not grant permission to use CNRI trademarks or
trade name in a trademark sense to endorse or promote products or
services of Licensee, or any third party.
8. By clicking on the ``ACCEPT'' button where indicated, or by copying,
installing or otherwise using Python 1.6.1, Licensee agrees to be
bound by the terms and conditions of this License Agreement.
ACCEPT
CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
Copyright © 1991 - 1995, Stichting Mathematisch Centrum
Amsterdam, The Netherlands. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.
STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


pickle-inst.html | pickle-protocol.html | node66.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 3.14.5.2 Pickling and unpickling extension types
When the Pickler encounters an object of a type it knows
nothing about -- such as an extension type -- it looks in two places
for a hint of how to pickle it. One alternative is for the object to
implement a __reduce__() method. If provided, at pickling
time __reduce__() will be called with no arguments, and it
must return either a string or a tuple.
If a string is returned, it names a global variable whose contents are
pickled as normal. When a tuple is returned, it must be of length two
or three, with the following semantics:
- A callable object, which in the unpickling environment must be
either a class, a callable registered as a ``safe constructor''
(see below), or it must have an attribute
__safe_for_unpickling__ with a true value. Otherwise,
an UnpicklingError will be raised in the unpickling
environment. Note that as usual, the callable itself is pickled
by name.
- A tuple of arguments for the callable object, or `None`.
- Optionally, the object's state, which will be passed to
the object's __setstate__() method as described in
section 3.14.5 (pickle-inst.html#pickle-inst). If the object has no
__setstate__() method, then, as above, the value must
be a dictionary and it will be added to the object's
__dict__.
Upon unpickling, the callable will be called (provided that it meets
the above criteria), passing in the tuple of arguments; it should
return the unpickled object. If the second item was `None`, then
instead of calling the callable directly, its __basicnew__()
method is called without arguments. It should also return the
unpickled object.
An alternative to implementing a __reduce__() method on the
object to be pickled, is to register the callable with the
copy_reg (module-copyreg.html) module. This module provides a way
for programs to register ``reduction functions'' and constructors for
user-defined types. Reduction functions have the same semantics and
interface as the __reduce__() method described above, except
that they are called with a single argument, the object to be pickled.
The registered constructor is deemed a ``safe constructor'' for purposes
of unpickling as described above.


node65.html | pickle-protocol.html | pickle-sec.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 3.14.5.3 Pickling and unpickling external objects
For the benefit of object persistence, the pickle module
supports the notion of a reference to an object outside the pickled
data stream. Such objects are referenced by a ``persistent id'',
which is just an arbitrary string of printable ASCII characters.
The resolution of such names is not defined by the pickle
module; it will delegate this resolution to user defined functions on
the pickler and unpickler3.9 (#foot6929).
To define external persistent id resolution, you need to set the
persistent_id attribute of the pickler object and the
persistent_load attribute of the unpickler object.
To pickle objects that have an external persistent id, the pickler
must have a custom persistent_id() method that takes an
object as an argument and returns either `None` or the persistent
id for that object. When `None` is returned, the pickler simply
pickles the object as normal. When a persistent id string is
returned, the pickler will pickle that string, along with a marker
so that the unpickler will recognize the string as a persistent id.
To unpickle external objects, the unpickler must have a custom
persistent_load() function that takes a persistent id
string and returns the referenced object.
Here's a silly example that might shed more light:
```text

import pickle
from cStringIO import StringIO

src = StringIO()
p = pickle.Pickler(src)

def persistent_id(obj):
if hasattr(obj, 'x'):
return 'the value %d' % obj.x
else:
return None

p.persistent_id = persistent_id

class Integer:
def __init__(self, x):
self.x = x
def __str__(self):
return 'My name is integer %d' % self.x

i = Integer(7)
print i
p.dump(i)

datastream = src.getvalue()
print repr(datastream)
dst = StringIO(datastream)

up = pickle.Unpickler(dst)

class FancyInteger(Integer):
def __str__(self):
return 'I am the integer %d' % self.x

def persistent_load(persid):
if persid.startswith('the value '):
value = int(persid.split()[2])
return FancyInteger(value)
else:
raise pickle.UnpicklingError, 'Invalid persistent id'

up.persistent_load = persistent_load

j = up.load()
print j
```
In the cPickle module, the unpickler's
persistent_load attribute can also be set to a Python
list, in which case, when the unpickler reaches a persistent id, the
persistent id string will simply be appended to this list. This
functionality exists so that a pickle data stream can be ``sniffed''
for object references without actually instantiating all the objects
in a pickle3.10 (#foot6824). Setting
persistent_load to a list is usually used in conjunction with
the noload() method on the Unpickler.


3.24.1 PrettyPrinter Objects

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


4.2.3 Module Contents

matching-searching.html | module-re.html | re-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 4.2.3 Module Contents
The module defines the following functions and constants, and an exception:


A.5 Obsolete

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


11.5.2 OpenerDirector Objects

request-objects.html | module-urllib2.html | base-handler-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 11.5.2 OpenerDirector Objects
OpenerDirector instances have the following methods:


3.10.1 Mapping Operators to Functions

module-operator.html | module-operator.html | module-inspect.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 3.10.1 Mapping Operators to Functions
This table shows how abstract operations correspond to operator
symbols in the Python syntax and the functions in the
operator (module-operator.html) module.


5.3.1 Organizing test code

module-unittest.html | module-unittest.html | legacy-unit-tests.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 5.3.1 Organizing test code
The basic building blocks of unit testing are test cases --
single scenarios that must be set up and checked for correctness. In
PyUnit, test cases are represented by instances of the
TestCase class in the unittest (module-unittest.html) module. To make
your own test cases you must write subclasses of TestCase, or
use FunctionTestCase.
An instance of a TestCase-derived class is an object that can
completely run a single test method, together with optional set-up
and tidy-up code.
The testing code of a TestCase instance should be entirely
self contained, such that it can be run either in isolation or in
arbitrary combination with any number of other test cases.
The simplest test case subclass will simply override the
runTest() method in order to perform specific testing code:
```text

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
def runTest(self):
widget = Widget("The widget")
self.failUnless(widget.size() == (50,50), 'incorrect default size')
```
Note that in order to test something, we use the one of the
assert*() or fail*() methods provided by the
TestCase base class. If the test fails when the test case
runs, an exception will be raised, and the testing framework will
identify the test case as a failure. Other exceptions that do
not arise from checks made through the assert*() and
fail*() methods are identified by the testing framework as
dfnerrors.
The way to run a test case will be described later. For now, note
that to construct an instance of such a test case, we call its
constructor without arguments:
```text

testCase = DefaultWidgetSizeTestCase()
```
Now, such test cases can be numerous, and their set-up can be
repetitive. In the above case, constructing a ``Widget'' in each of
100 Widget test case subclasses would mean unsightly duplication.
Luckily, we can factor out such set-up code by implementing a method
called setUp(), which the testing framework will
automatically call for us when we run the test:
```text

import unittest

class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget("The widget")

class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.failUnless(self.widget.size() == (50,50),
'incorrect default size')

class WidgetResizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.widget.resize(100,150)
self.failUnless(self.widget.size() == (100,150),
'wrong size after resize')
```
If the setUp() method raises an exception while the test is
running, the framework will consider the test to have suffered an
error, and the runTest() method will not be executed.
Similarly, we can provide a tearDown() method that tidies up
after the runTest() method has been run:
```text

import unittest

class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget("The widget")

def tearDown(self):
self.widget.dispose()
self.widget = None
```
If setUp() succeeded, the tearDown() method will be
run regardless of whether or not runTest() succeeded.
Such a working environment for the testing code is called a
fixture.
Often, many small test cases will use the same fixture. In this case,
we would end up subclassing SimpleWidgetTestCase into many
small one-method classes such as
DefaultWidgetSizeTestCase. This is time-consuming and
discouraging, so in the same vein as JUnit, PyUnit provides a simpler
mechanism:
```text

import unittest

class WidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget("The widget")

def tearDown(self):
self.widget.dispose()
self.widget = None

def testDefaultSize(self):
self.failUnless(self.widget.size() == (50,50),
'incorrect default size')

def testResize(self):
self.widget.resize(100,150)
self.failUnless(self.widget.size() == (100,150),
'wrong size after resize')
```
Here we have not provided a runTest() method, but have
instead provided two different test methods. Class instances will now
each run one of the test*() methods, with `self.widget`
created and destroyed separately for each instance. When creating an
instance we must specify the test method it is to run. We do this by
passing the method name in the constructor:
```text

defaultSizeTestCase = WidgetTestCase("testDefaultSize")
resizeTestCase = WidgetTestCase("testResize")
```
Test case instances are grouped together according to the features
they test. PyUnit provides a mechanism for this: the test
suite, represented by the class TestSuite in the
unittest (module-unittest.html) module:
```text

widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase("testDefaultSize"))
widgetTestSuite.addTest(WidgetTestCase("testResize"))
```
For the ease of running tests, as we will see later, it is a good
idea to provide in each test module a callable object that returns a
pre-built test suite:
```text

def suite():
suite = unittest.TestSuite()
suite.addTest(WidgetTestCase("testDefaultSize"))
suite.addTest(WidgetTestCase("testResize"))
return suite
```
or even:
```text

class WidgetTestSuite(unittest.TestSuite):
def __init__(self):
unittest.TestSuite.__init__(self,map(WidgetTestCase,
("testDefaultSize",
"testResize")))
```
(The latter is admittedly not for the faint-hearted!)
Since it is a common pattern to create a TestCase subclass
with many similarly named test functions, there is a convenience
function called makeSuite() provided in the
unittest (module-unittest.html) module that constructs a test suite that
comprises all of the test cases in a test case class:
```text

suite = unittest.makeSuite(WidgetTestCase,'test')
```
Note that when using the makeSuite() function, the order in
which the various test cases will be run by the test suite is the
order determined by sorting the test function names using the
cmp() built-in function.
Often it is desirable to group suites of test cases together, so as to
run tests for the whole system at once. This is easy, since
TestSuite instances can be added to a TestSuite just
as TestCase instances can be added to a TestSuite:
```text

suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite((suite1, suite2))
```
You can place the definitions of test cases and test suites in the
same modules as the code they are to test (e.g. widget.py),
but there are several advantages to placing the test code in a
separate module, such as widgettests.py:
- The test module can be run standalone from the command line.
- The test code can more easily be separated from shipped code.
- There is less temptation to change test code to fit the code.
it tests without a good reason.
- Test code should be modified much less frequently than the
code it tests.
- Tested code can be refactored more easily.
- Tests for modules written in C must be in separate modules
anyway, so why not be consistent?
- If the testing strategy changes, there is no need to change
the source code.


6.1.3 File Descriptor Operations

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


6.1.4 Files and Directories

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


6.1.2 File Object Creation

os-procinfo.html | module-os.html | os-fd-ops.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 6.1.2 File Object Creation
These functions create new file objects.
For each of these popen() variants, if bufsize is
specified, it specifies the buffer size for the I/O pipes.
mode, if provided, should be the string `'b'` or
`'t'`; on Windows this is needed to determine whether the file
objects should be opened in binary or text mode. The default value
for mode is `'t'`.
These methods do not make it possible to retrieve the return code from
the child processes. The only way to control the input and output
streams and also retrieve the return codes is to use the
Popen3 and Popen4 classes from the popen2 (module-popen2.html)
module; these are only available on Unix.
This functionality is also available in the popen2 (module-popen2.html) module
using functions of the same names, but the return values of those
functions have a different order.


6.1.6 Miscellaneous System Information

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


6.1.5 Process Management

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


6.1.1 Process Parameters

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


node541.html | tkinter.html | restricted.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
# 16.6 Other Graphical User Interface Packages
There are an number of extension widget sets to Tkinter (module-Tkinter.html).
Tk is not the only GUI for Python, but is however the
most commonly used one.


16.4.1 Pen and RawPen Objects

module-turtle.html | module-turtle.html | idle.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
## 16.4.1 Pen and RawPen Objects
Pen and RawPen objects have all the global functions
described above, except for demo() as methods, which
manipulate the given pen.
The only method which is more powerful as a method is
degrees().


3.14.7 Example

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

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

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

def __getstate__(self):
odict = self.__dict__.copy() # copy the dict since we change it
del odict['fh'] # remove filehandle entry
return odict

def __setstate__(self,dict):
fh = open(dict['file']) # reopen file
count = dict['lineno'] # read from file...
while count: # until line count is restored
fh.readline()
count = count - 1
self.__dict__.update(dict) # update attributes
self.fh = fh # save the file object
```
A sample usage might be something like this:
```text

>>> import TextReader
>>> obj = TextReader.TextReader("TextReader.py")
>>> obj.readline()
'1: #!/usr/local/bin/python'
>>> # (more invocations of obj.readline() here)
... obj.readline()
'7: class TextReader:'
>>> import pickle
>>> pickle.dump(obj,open('save.p','w'))
```
If you want to see that pickle (module-pickle.html) works across Python
processes, start another Python session, before continuing. What
follows can happen from either the same process or a new process.
```text

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


pickle-protocol.html | pickle-protocol.html | node65.html | Python Library Reference | contents.html | modindex.html | genindex.html
---
### 3.14.5.1 Pickling and unpickling normal class
instances
When a pickled class instance is unpickled, its __init__()
method is normally not invoked. If it is desirable that the
__init__() method be called on unpickling, a class can define
a method __getinitargs__(), which should return a
tuple containing the arguments to be passed to the class
constructor (i.e. __init__()). The
__getinitargs__() method is called at
pickle time; the tuple it returns is incorporated in the pickle for
the instance.
Classes can further influence how their instances are pickled; if the
class defines the method __getstate__(), it is called and the
return state is pickled as the contents for the instance, instead of
the contents of the instance's dictionary. If there is no
__getstate__() method, the instance's __dict__ is
pickled.
Upon unpickling, if the class also defines the method
__setstate__(), it is called with the unpickled
state3.7 (#foot6781). If there is no __setstate__() method, the
pickled object must be a dictionary and its items are assigned to the
new instance's dictionary. If a class defines both
__getstate__() and __setstate__(), the state object
needn't be a dictionary and these methods can do what they
want3.8 (#foot6928).