node752.html | node751.html | modindex.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
C.1 History of the (node752.html)
Up:
C. History and License (node751.html)
Next:
Module Index (modindex.html)
---
# C.2 Terms and conditions for accessing or otherwise using Python
PSF LICENSE AGREEMENT FOR PYTHON 2.3
1. This LICENSE AGREEMENT is between the Python Software Foundation
(``PSF''), and the Individual or Organization (``Licensee'') accessing
and otherwise using Python 2.3 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.3 alone or in any derivative version, provided, however, that
PSF's License Agreement and PSF's notice of copyright, i.e.,
``Copyright © 2001-2003 Python Software Foundation; All
Rights Reserved'' are retained in Python 2.3 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.3 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.3.
4. PSF is making Python 2.3 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.3 WILL
NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
2.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
2.3, 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.3, 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.


3.25.1 PrettyPrinter Objects

module-pprint.html | module-pprint.html | module-repr.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.25 pprint (module-pprint.html)
Up:
3.25 pprint (module-pprint.html)
Next:
3.26 repr (module-repr.html)
---
## 3.25.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.
This method is provided as a hook to allow subclasses to modify the
way objects are converted to strings. The default implementation uses
the internals of the saferepr() implementation.


A.5 Obsolete

node747.html | undoc.html | node749.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
A.4 Multimedia (node747.html)
Up:
A. Undocumented Modules (undoc.html)
Next:
A.6 SGI-specific Extension modules (node749.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
Previous:
11.5.1 Request Objects (request-objects.html)
Up:
11.5 urllib2 (module-urllib2.html)
Next:
11.5.3 BaseHandler Objects (base-handler-objects.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
Previous:
3.10 operator (module-operator.html)
Up:
3.10 operator (module-operator.html)
Next:
3.11 inspect (module-inspect.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.


6.20.5.2 Adding new actions

optparse-adding-types.html | optparse-extending.html | optparse-extending-other-reasons.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.5.1 Adding new types (optparse-adding-types.html)
Up:
6.20.5 Extending optparse (optparse-extending.html)
Next:
6.20.5.3 Other reasons to (optparse-extending-other-reasons.html)
---
### 6.20.5.2 Adding new actions
Adding new actions is a bit trickier, because you have to understand
that optparse has a couple of classifications for actions:
Some default ``store'' actions are store, store_const,
append, and count. The default ``typed'' actions are
store, append, and callback.
When you add an action, you need to decide if it's a ``store'' action,
a ``typed'', neither, or both. Three class attributes of
Option (or your Option subclass) control this:
In order to actually implement your new action, you must override
Option's take_action() method and add a case that
recognizes your action.
For example, let's add an ``extend'' action. This is similar to the
standard ``append'' action, but instead of taking a single value from
the command-line and appending it to an existing list, ``extend'' will
take multiple values in a single comma-delimited string, and extend an
existing list with them. That is, if --names is an
``extend'' option of type string, the command line:
```text

--names=foo,bar --names blah --names ding,dong
```
would result in a list:
```text

["foo", "bar", "blah", "ding", "dong"]
```
Again we define a subclass of Option:
```text

class MyOption (Option):

ACTIONS = Option.ACTIONS + ("extend",)
STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)

def take_action (self, action, dest, opt, value, values, parser):
if action == "extend":
lvalue = value.split(",")
values.ensure_value(dest, []).extend(lvalue)
else:
Option.take_action(
self, action, dest, opt, value, values, parser)
```
Features of note:
- ``extend'' both expects a value on the command-line and stores that
value somewhere, so it goes in both STORE_ACTIONS and
TYPED_ACTIONS.
- MyOption.take_action() implements just this one new
action, and passes control back to Option.take_action() for
the standard optparse actions.
- values is an instance of the Values class, which
provides the very useful ensure_value()
method. ensure_value() is essentially getattr()
with a safety valve; it is called as:
```text

values.ensure_value(attr, value)
```
If the attr attribute of values doesn't exist or is
`None`, then ensure_value() first sets it to value, and
then returns value. This is very handy for actions like
``extend'', ``append'', and ``count'', all of which accumulate data in
a variable and expect that variable to be of a certain type (a list
for the first two, an integer for the latter). Using
ensure_value() means that scripts using your action don't
have to worry about setting a default value for the option
destinations in question; they can just leave the default as `None` and
ensure_value() will take care of getting it right when it's
needed.


6.20.5.1 Adding new types

optparse-extending.html | optparse-extending.html | optparse-adding-actions.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.5 Extending optparse (optparse-extending.html)
Up:
6.20.5 Extending optparse (optparse-extending.html)
Next:
6.20.5.2 Adding new actions (optparse-adding-actions.html)
---
### 6.20.5.1 Adding new types
To add new types, you need to define your own subclass of
optparse's Option class. This class has a couple of
attributes that define optparse's types: TYPES and
TYPE_CHECKER.
TYPES is a tuple of type names; in your subclass, simply
define a new tuple TYPES that builds on the standard one.
TYPE_CHECKER is a dictionary mapping type names to
type-checking functions. A type-checking function has the following
signature:
```text

def check_foo (option : Option, opt : string, value : string)
-> foo
```
You can name it whatever you like, and make it return any type you
like. The value returned by a type-checking function will wind up in
the OptionValues instance returned by
OptionParser.parse_args(), or be passed to callbacks as the
value parameter.
Your type-checking function should raise OptionValueError
if it encounters any problems. OptionValueError takes a
single string argument, which is passed as-is to
OptionParser's error() method, which in turn prepends
the program name and the string ``error:'' and prints everything to
stderr before terminating the process.
Here's a silly example that demonstrates adding a ``complex'' option
type to parse Python-style complex numbers on the command line. (This
is even sillier than it used to be, because optparse 1.3 adds
built-in support for complex numbers [purely for completeness], but
never mind.)
First, the necessary imports:
```text

from copy import copy
from optparse import Option, OptionValueError
```
You need to define your type-checker first, since it's referred to
later (in the TYPE_CHECKER class attribute of your
Option subclass):
```text

def check_complex (option, opt, value):
try:
return complex(value)
except ValueError:
raise OptionValueError(
"option %s: invalid complex value: %r" % (opt, value))
```
Finally, the Option subclass:
```text

class MyOption (Option):
TYPES = Option.TYPES + ("complex",)
TYPE_CHECKER = copy(Option.TYPE_CHECKER)
TYPE_CHECKER["complex"] = check_complex
```
(If we didn't make a copy() of
Option.TYPE_CHECKER, we would end up modifying the
TYPE_CHECKER attribute of optparse's Option class.
This being Python, nothing stops you from doing that except good
manners and common sense.)
That's it! Now you can write a script that uses the new option type
just like any other optparse-based script, except you have to
instruct your OptionParser to use MyOption instead of
Option:
```text

parser = OptionParser(option_class=MyOption)
parser.add_option("-c", action="store", type="complex", dest="c")
```
Alternately, you can build your own option list and pass it to
OptionParser; if you don't use add_option() in the
above way, you don't need to tell OptionParser which option
class to use:
```text

option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
```


6.20.3 Advanced Usage

optparse-basic-summary.html | module-optparse.html | optparse-creating-the-parser.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.7 Putting it all (optparse-basic-summary.html)
Up:
6.20 optparse (module-optparse.html)
Next:
6.20.3.1 Creating and populating (optparse-creating-the-parser.html)
---
## 6.20.3 Advanced Usage


6.20.2.7 Putting it all together

optparse-error-handling.html | optparse-basic-usage.html | optparse-advanced-usage.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.6 Error-handling (optparse-error-handling.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
---
### 6.20.2.7 Putting it all together
Here's what optparse-based scripts typically look like:
```text

from optparse import OptionParser
[...]
def main():
usage = "usage: \%prog [-f] [-v] [-q] firstarg secondarg"
parser = OptionParser(usage)
parser.add_option("-f", "--file", type="string", dest="filename",
help="read data from FILENAME")
parser.add_option("-v", "--verbose",
action="store_true", dest="verbose")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose")

(options, args) = parser.parse_args()
if len(args) != 1:
parser.error("incorrect number of arguments")

if options.verbose:
print "reading \%s..." \% options.filename
[... go to work ...]

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


6.20.2 Basic Usage

optparse-positional-arguments.html | module-optparse.html | optparse-store-action.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.1.3 What are positional (optparse-positional-arguments.html)
Up:
6.20 optparse (module-optparse.html)
Next:
6.20.2.1 The store action (optparse-store-action.html)
---
## 6.20.2 Basic Usage
While optparse is quite flexible and powerful, you don't have
to jump through hoops or read reams of documentation to get it working
in basic cases. This document aims to demonstrate some simple usage
patterns that will get you started using optparse in your
scripts.
To parse a command line with optparse, you must create an
OptionParser instance and populate it. Obviously, you'll have
to import the OptionParser classes in any script that uses
optparse:
```text

from optparse import OptionParser
```
Early on in the main program, create a parser:
```text

parser = OptionParser()
```
Then you can start populating the parser with options. Each option is
really a set of synonymous option strings; most commonly, you'll have
one short option string and one long option string --
e.g. -f and --file:
```text

parser.add_option("-f", "--file", ...)
```
The interesting stuff, of course, is what comes after the option
strings. For now, we'll only cover four of the things you can put
there: action, type, dest (destination), and
help.


6.20.4.3 Error handling

optparse-callbacks-called.html | optparse-callback-options.html | optparse-callback-examples.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.4.2 How callbacks are (optparse-callbacks-called.html)
Up:
6.20.4 Callback Options (optparse-callback-options.html)
Next:
6.20.4.4 Examples (optparse-callback-examples.html)
---
### 6.20.4.3 Error handling
The callback function should raise OptionValueError if
there are any problems with the option or its
argument(s). optparse catches this and terminates the
program, printing the error message you supply to stderr. Your
message should be clear, concise, accurate, and mention the option at
fault. Otherwise, the user will have a hard time figuring out what he
did wrong.


6.20.4.4 Examples

optparse-callback-error-handling.html | optparse-callback-options.html | optparse-extending.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.4.3 Error handling (optparse-callback-error-handling.html)
Up:
6.20.4 Callback Options (optparse-callback-options.html)
Next:
6.20.5 Extending optparse (optparse-extending.html)
---
### 6.20.4.4 Examples
Here's an example of a callback option that takes no arguments, and
simply records that the option was seen:
```text

def record_foo_seen (option, opt, value, parser):
parser.saw_foo = 1

parser.add_option("--foo", action="callback", callback=record_foo_seen)
```
Of course, you could do that with the ``store_true'' action. Here's a
slightly more interesting example: record the fact that
-a is seen, but blow up if it comes after -b
in the command-line.
```text

def check_order (option, opt, value, parser):
if parser.values.b:
raise OptionValueError("can't use -a after -b")
parser.values.a = 1
...
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
```
If you want to reuse this callback for several similar options (set a
flag, but blow up if -b has already been seen), it needs
a bit of work: the error message and the flag that it sets must be
generalized.
```text

def check_order (option, opt, value, parser):
if parser.values.b:
raise OptionValueError("can't use %s after -b" % opt)
setattr(parser.values, option.dest, 1)
...
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')
```
Of course, you could put any condition in there--you're not limited
to checking the values of already-defined options. For example, if
you have options that should not be called when the moon is full, all
you have to do is this:
```text

def check_moon (option, opt, value, parser):
if is_full_moon():
raise OptionValueError("%s option invalid when moon full" % opt)
setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
action="callback", callback=check_moon, dest="foo")
```
(The definition of `is_full_moon()` is left as an exercise for the
reader.)
Fixed arguments
Things get slightly more interesting when you define callback options
that take a fixed number of arguments. Specifying that a callback
option takes arguments is similar to defining a ``store'' or
``append'' option: if you define type, then the option takes one
argument that must be convertible to that type; if you further define
nargs, then the option takes that many arguments.
Here's an example that just emulates the standard ``store'' action:
```text

def store_value (option, opt, value, parser):
setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
action="callback", callback=store_value,
type="int", nargs=3, dest="foo")
```
Note that optparse takes care of consuming 3 arguments and
converting them to integers for you; all you have to do is store them.
(Or whatever: obviously you don't need a callback for this example.
Use your imagination!)
Variable arguments
Things get hairy when you want an option to take a variable number of
arguments. For this case, you have to write a callback;
optparse doesn't provide any built-in capabilities for it.
You have to deal with the full-blown syntax for conventional Unix
command-line parsing. (Previously, optparse took care of
this for you, but I got it wrong. It was fixed at the cost of making
this kind of callback more complex.) In particular, callbacks have to
worry about bare -- and - arguments; the
convention is:
- bare --, if not the argument to some option,
causes command-line processing to halt and the --
itself is lost.
- bare - similarly causes command-line processing to
halt, but the - itself is kept.
- either -- or - can be option
arguments.
If you want an option that takes a variable number of arguments, there
are several subtle, tricky issues to worry about. The exact
implementation you choose will be based on which trade-offs you're
willing to make for your application (which is why optparse
doesn't support this sort of thing directly).
Nevertheless, here's a stab at a callback for an option with variable
arguments:
```text

def varargs (option, opt, value, parser):
assert value is None
done = 0
value = []
rargs = parser.rargs
while rargs:
arg = rargs[0]

# Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
# etc. Note that this also stops on "-3" or "-3.0", so if
# your option takes numeric values, you will need to handle
# this.
if ((arg[:2] == "--" and len(arg) > 2) or
(arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
break
else:
value.append(arg)
del rargs[0]

setattr(parser.values, option.dest, value)

...
parser.add_option("-c", "--callback",
action="callback", callback=varargs)
```
The main weakness with this particular implementation is that negative
numbers in the arguments following -c will be interpreted
as further options, rather than as arguments to -c.
Fixing this is left as an exercise for the reader.


6.20.4 Callback Options

optparse-conflicts.html | module-optparse.html | optparse-defining-callback-option.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3.6 Conflicts between options (optparse-conflicts.html)
Up:
6.20 optparse (module-optparse.html)
Next:
6.20.4.1 Defining a callback (optparse-defining-callback-option.html)
---
## 6.20.4 Callback Options
If optparse's built-in actions and types just don't fit the
bill for you, but it's not worth extending optparse to define
your own actions or types, you'll probably need to define a callback
option. Defining callback options is quite easy; the tricky part is
writing a good callback (the function that is called when
optparse encounters the option on the command line).


6.20.4.2 How callbacks are called

optparse-defining-callback-option.html | optparse-callback-options.html | optparse-callback-error-handling.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.4.1 Defining a callback (optparse-defining-callback-option.html)
Up:
6.20.4 Callback Options (optparse-callback-options.html)
Next:
6.20.4.3 Error handling (optparse-callback-error-handling.html)
---
### 6.20.4.2 How callbacks are called
All callbacks are called as follows:
```text

func(option, opt, value, parser, *args, **kwargs)
```
where
Since args and kwargs are optional (they are only passed
if you supply callback_args and/or callback_kwargs when
you define your callback option), the minimal callback function is:
```text

def my_callback (option, opt, value, parser):
pass
```


6.20.3.6 Conflicts between options

optparse-querying-and-manipulating.html | optparse-advanced-usage.html | optparse-callback-options.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3.5 Querying and manipulating (optparse-querying-and-manipulating.html)
Up:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Next:
6.20.4 Callback Options (optparse-callback-options.html)
---
### 6.20.3.6 Conflicts between options
If you're not careful, it's easy to define conflicting options:
```text

parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)
```
(This is even easier to do if you've defined your own
OptionParser subclass with some standard options.)
On the assumption that this is usually a mistake, optparse
raises an exception (OptionConflictError) by default when
this happens. Since this is an easily-fixed programming error, you
shouldn't try to catch this exception--fix your mistake and get on
with life.
Sometimes, you want newer options to deliberately replace the option
strings used by older options. You can achieve this by calling:
```text

parser.set_conflict_handler("resolve")
```
which instructs optparse to resolve option conflicts
intelligently.
Here's how it works: every time you add an option, optparse
checks for conflicts with previously-added options. If it finds any,
it invokes the conflict-handling mechanism you specify either to the
OptionParser constructor:
```text

parser = OptionParser(..., conflict_handler="resolve")
```
or via the set_conflict_handler() method.
The default conflict-handling mechanism is `error`.
Here's an example: first, define an OptionParser set to
resolve conflicts intelligently:
```text

parser = OptionParser(conflict_handler="resolve")
```
Now add all of our options:
```text

parser.add_option("-n", "--dry-run", ..., help="original dry-run option")
...
parser.add_option("-n", "--noisy", ..., help="be noisy")
```
At this point, optparse detects that a previously-added option is already
using the -n option string. Since `conflict_handler
== "resolve"`, it resolves the situation by removing -n
from the earlier option's list of option strings. Now,
--dry-run is the only way for the user to activate that
option. If the user asks for help, the help message will reflect
that, e.g.:
```text

options:
--dry-run original dry-run option
...
-n, --noisy be noisy
```
Note that it's possible to whittle away the option strings for a
previously-added option until there are none left, and the user has no
way of invoking that option from the command-line. In that case,
optparse removes that option completely, so it doesn't show
up in help text or anywhere else. E.g. if we carry on with our
existing OptionParser:
```text

parser.add_option("--dry-run", ..., help="new dry-run option")
```
At this point, the first -n/--dry-run
option is no longer accessible, so optparse removes it. If
the user asks for help, they'll get something like this:
```text

options:
...
-n, --noisy be noisy
--dry-run new dry-run option
```


optparse-advanced-usage.html | optparse-advanced-usage.html | optparse-defining-options.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Up:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Next:
6.20.3.2 Defining options (optparse-defining-options.html)
---
### 6.20.3.1 Creating and populating the
parser
There are several ways to populate the parser with options. One way
is to pass a list of Options to the OptionParser
constructor:
```text

from optparse import OptionParser, make_option
[...]
parser = OptionParser(option_list=[
make_option("-f", "--filename",
action="store", type="string", dest="filename"),
make_option("-q", "--quiet",
action="store_false", dest="verbose")])
```
(make_option() is a factory function for generating
Option objects.)
For long option lists, it may be more convenient/readable to create the
list separately:
```text

option_list = [make_option("-f", "--filename",
action="store", type="string", dest="filename"),
[... more options ...]
make_option("-q", "--quiet",
action="store_false", dest="verbose")]
parser = OptionParser(option_list=option_list)
```
Or, you can use the add_option() method of
OptionParser to add options one-at-a-time:
```text

parser = OptionParser()
parser.add_option("-f", "--filename",
action="store", type="string", dest="filename")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose")
```
This method makes it easier to track down exceptions raised by the
Option constructor, which are common because of the complicated
interdependencies among the various keyword arguments. (If you get it
wrong, optparse raises OptionError.)
add_option() can be called in one of two ways:
- pass it an Option instance (as returned by make_option())
- pass it any combination of positional and keyword arguments that
are acceptable to make_option() (i.e., to the Option
constructor), and it will create the Option instance for you
(shown above).


6.20.4.1 Defining a callback option

optparse-callback-options.html | optparse-callback-options.html | optparse-callbacks-called.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.4 Callback Options (optparse-callback-options.html)
Up:
6.20.4 Callback Options (optparse-callback-options.html)
Next:
6.20.4.2 How callbacks are (optparse-callbacks-called.html)
---
### 6.20.4.1 Defining a callback option
As always, you can define a callback option either by directly
instantiating the Option class, or by using the
add_option() method of your OptionParser object. The
only option attribute you must specify is callback, the function
to call:
```text

parser.add_option("-c", callback=my_callback)
```
Note that you supply a function object here--so you must have
already defined a function my_callback() when you define
the callback option. In this simple case, optparse knows
nothing about the arguments the -c option expects to
take. Usually, this means that the option doesn't take any arguments
- the mere presence of -c on the command-line is all it
needs to know. In some circumstances, though, you might want your
callback to consume an arbitrary number of command-line arguments.
This is where writing callbacks gets tricky; it's covered later in
this document.
There are several other option attributes that you can supply when you
define an option attribute:


6.20.3.2 Defining options

optparse-creating-the-parser.html | optparse-advanced-usage.html | optparse-option-actions.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3.1 Creating and populating (optparse-creating-the-parser.html)
Up:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Next:
6.20.3.3 Option actions (optparse-option-actions.html)
---
### 6.20.3.2 Defining options
Each Option instance represents a set of synonymous
command-line options, i.e. options that have the same meaning and
effect, but different spellings. You can specify any number of short
or long option strings, but you must specify at least one option
string.
To define an option with only a short option string:
```text

make_option("-f", ...)
```
And to define an option with only a long option string:
```text

make_option("--foo", ...)
```
The ``...'' represents a set of keyword arguments that define attributes
of the Option object. The rules governing which keyword args
you must supply for a given Option are fairly complicated, but
you always have to supply some. If you get it wrong,
optparse raises an OptionError exception explaining
your mistake.
The most important attribute of an option is its action, i.e. what to do
when we encounter this option on the command-line. The possible actions
are:
(If you don't supply an action, the default is ``store''. For this
action, you may also supply type and dest keywords; see
below.)
As you can see, most actions involve storing or updating a value
somewhere. optparse always creates a particular object (an
instance of the Values class) specifically for this
purpose. Option arguments (and various other values) are stored as
attributes of this object, according to the dest (destination)
argument to make_option()/add_option().
For example, when you call:
```text

parser.parse_args()
```
one of the first things optparse does is create a
`values` object:
```text

values = Values()
```
If one of the options in this parser is defined with:
```text

make_option("-f", "--file", action="store", type="string", dest="filename")
```
and the command-line being parsed includes any of the following:
```text

-ffoo
-f foo
--file=foo
--file foo
```
then optparse, on seeing the -f or
--file option, will do the equivalent of this:
```text

values.filename = "foo"
```
Clearly, the type and dest arguments are almost
as important as action. action is the only attribute that
is meaningful for all options, though, so it is the most
important.


6.20.2.6 Error-handling

optparse-print-version.html | optparse-basic-usage.html | optparse-basic-summary.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.5 Print a version (optparse-print-version.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.2.7 Putting it all (optparse-basic-summary.html)
---
### 6.20.2.6 Error-handling
The one thing you need to know for basic usage is how
optparse behaves when it encounters an error on the
command-line--e.g. -n 4x where -n is an
integer-valued option. In this case, optparse prints your
usage message to stderr, followed by a useful and human-readable error
message. Then it terminates (calls sys.exit()) with a
non-zero exit status.
If you don't like this, subclass OptionParser and override the
error() method. See section 6.20.5 (optparse-extending.html#optparse-extending),
``Extending optparse.''


6.20.5.4 Examples

optparse-extending-other-reasons.html | optparse-extending.html | module-tempfile.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.5.3 Other reasons to (optparse-extending-other-reasons.html)
Up:
6.20.5 Extending optparse (optparse-extending.html)
Next:
6.21 tempfile (module-tempfile.html)
---
### 6.20.5.4 Examples
Here are a few examples of extending the optparse module.
First, let's change the option-parsing to be case-insensitive:
```text
from optparse import Option, OptionParser, _match_abbrev

# This case-insensitive option parser relies on having a
# case-insensitive dictionary type available. Here's one
# for Python 2.2. Note that a *real* case-insensitive
# dictionary type would also have to implement __new__(),
# update(), and setdefault() -- but that's not the point
# of this exercise.

class caseless_dict (dict):
def __setitem__ (self, key, value):
dict.__setitem__(self, key.lower(), value)

def __getitem__ (self, key):
return dict.__getitem__(self, key.lower())

def get (self, key, default=None):
return dict.get(self, key.lower())

def has_key (self, key):
return dict.has_key(self, key.lower())

class CaselessOptionParser (OptionParser):

def _create_option_list (self):
self.option_list = []
self._short_opt = caseless_dict()
self._long_opt = caseless_dict()
self._long_opts = []
self.defaults = {}

def _match_long_opt (self, opt):
return _match_abbrev(opt.lower(), self._long_opt.keys())

if __name__ == "__main__":
from optik.errors import OptionConflictError

# test 1: no options to start with
parser = CaselessOptionParser()
try:
parser.add_option("-H", dest="blah")
except OptionConflictError:
print "ok: got OptionConflictError for -H"
else:
print "not ok: no conflict between -h and -H"

parser.add_option("-f", "--file", dest="file")
#print `parser.get_option("-f")`
#print `parser.get_option("-F")`
#print `parser.get_option("--file")`
#print `parser.get_option("--fIlE")`
(options, args) = parser.parse_args(["--FiLe", "foo"])
assert options.file == "foo", options.file
print "ok: case insensitive long options work"

(options, args) = parser.parse_args(["-F", "bar"])
assert options.file == "bar", options.file
print "ok: case insensitive short options work"
```
Download as text (original file name: caseless.py). (caseless.txt)
And two ways of implementing ``required options'' with
optparse.
Version 1: Add a method to OptionParser which applications
must call after parsing arguments:
```text
import optparse

class OptionParser (optparse.OptionParser):

def check_required (self, opt):
option = self.get_option(opt)

# Assumes the option's 'default' is set to None!
if getattr(self.values, option.dest) is None:
self.error("%s option not supplied" % option)

parser = OptionParser()
parser.add_option("-v", action="count", dest="verbose")
parser.add_option("-f", "--file", default=None)
(options, args) = parser.parse_args()

print "verbose:", options.verbose
print "file:", options.file
parser.check_required("-f")
```
Download as text (original file name: required_1.py). (required_1.txt)
Version 2: Extend Option and add a required
attribute; extend OptionParser to ensure that required options
are present after parsing:


optparse-adding-actions.html | optparse-extending.html | optparse-extending-examples.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.5.2 Adding new actions (optparse-adding-actions.html)
Up:
6.20.5 Extending optparse (optparse-extending.html)
Next:
6.20.5.4 Examples (optparse-extending-examples.html)
---
### 6.20.5.3 Other reasons to extend optparse
Adding new types and new actions are the big, obvious reasons why you
might want to extend optparse. I can think of at least two
other areas to play with.
First, the simple one: OptionParser tries to be helpful by
calling sys.exit() when appropriate, i.e. when there's an
error on the command-line or when the user requests help. In the
former case, the traditional course of letting the script crash with a
traceback is unacceptable; it will make users think there's a bug in
your script when they make a command-line error. In the latter case,
there's generally not much point in carrying on after printing a help
message.
If this behaviour bothers you, it shouldn't be too hard to ``fix'' it.
You'll have to
1. subclass OptionParser and override the error() method
2. subclass Option and override the take_action() method--you'll
need to provide your own handling of the ``help'' action that
doesn't call sys.exit()
The second, much more complex, possibility is to override the
command-line syntax implemented by optparse. In this case,
you'd leave the whole machinery of option actions and types alone, but
rewrite the code that processes `sys.argv`. You'll need to
subclass OptionParser in any case; depending on how radical a
rewrite you want, you'll probably need to override one or all of
parse_args(), _process_long_opt(), and
_process_short_opts().
Both of these are left as an exercise for the reader. I have not
tried to implement either myself, since I'm quite happy with
optparse's default behaviour (naturally).
Happy hacking, and don't forget: Use the Source, Luke.


6.20.5 Extending optparse

optparse-callback-examples.html | module-optparse.html | optparse-adding-types.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.4.4 Examples (optparse-callback-examples.html)
Up:
6.20 optparse (module-optparse.html)
Next:
6.20.5.1 Adding new types (optparse-adding-types.html)
---
## 6.20.5 Extending optparse
Since the two major controlling factors in how optparse
interprets command-line options are the action and type of each
option, the most likely direction of extension is to add new actions
and new types.
Also, the examples section includes several demonstrations of
extending optparse in different ways: e.g. a case-insensitive
option parser, or two kinds of option parsers that implement
``required options''.


6.20.2.4 Generating help

optparse-setting-default-values.html | optparse-basic-usage.html | optparse-print-version.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.3 Setting default values (optparse-setting-default-values.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.2.5 Print a version (optparse-print-version.html)
---
### 6.20.2.4 Generating help
The last feature that you will use in every script is
optparse's ability to generate help messages. All you have
to do is supply a help argument when you add an option. Let's
create a new parser and populate it with user-friendly (documented)
options:
```text

usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
action="store_true", dest="verbose", default=True,
help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose",
help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--file", dest="filename",
metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
default="intermediate",
help="interaction mode: one of 'novice', "
"'intermediate' [default], 'expert'")
```
If optparse encounters either -h or
--help on the command-line, or if you just call
parser.print_help(), it prints the following to stdout:
```text

usage: <yourscript> [options] arg1 arg2

options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-fFILE, --file=FILE write output to FILE
-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
[default], 'expert'
```
There's a lot going on here to help optparse generate the
best possible help message:
- the script defines its own usage message:
```text

usage = "usage: %prog [options] arg1 arg2"
```
optparse expands "%prog" in the usage string to the name of the
current script, i.e. `os.path.basename(sys.argv[0])`. The
expanded string is then printed before the detailed option help.
If you don't supply a usage string, optparse uses a bland but
sensible default: `"usage: %prog [options]"`, which is fine if your
script doesn't take any positional arguments.
- every option defines a help string, and doesn't worry about
line-wrapping--optparse takes care of wrapping lines and
making the help output look good.
- options that take a value indicate this fact in their
automatically-generated help message, e.g. for the ``mode'' option:
```text

-mMODE, --mode=MODE
```
Here, ``MODE'' is called the meta-variable: it stands for the argument
that the user is expected to supply to
-m/--mode. By default, optparse
converts the destination variable name to uppercase and uses that for
the meta-variable. Sometimes, that's not what you want--for
example, the filename option explicitly sets
`metavar="FILE"`, resulting in this automatically-generated
option description:
```text

-fFILE, --file=FILE
```
This is important for more than just saving space, though: the
manually written help text uses the meta-variable ``FILE'', to clue
the user in that there's a connection between the formal syntax
``-fFILE'' and the informal semantic description ``write output to
FILE''. This is a simple but effective way to make your help text a
lot clearer and more useful for end users.
When dealing with many options, it is convenient to group these
options for better help output. An OptionParser can contain
several option groups, each of which can contain several options.
Continuing with the parser defined above, adding an
OptionGroup to a parser is easy:
```text

group = OptionGroup(parser, "Dangerous Options",
"Caution: use these options at your own risk. "
"It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
```
This would result in the following help output:
```text

usage: [options] arg1 arg2

options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-fFILE, --file=FILE write output to FILE
-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
[default], 'expert'

Dangerous Options:
Caution: use of these options is at your own risk. It is believed that
some of them bite.
-g Group option.
```


6.20.3.3 Option actions

optparse-defining-options.html | optparse-advanced-usage.html | optparse-option-types.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3.2 Defining options (optparse-defining-options.html)
Up:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Next:
6.20.3.4 Option types (optparse-option-types.html)
---
### 6.20.3.3 Option actions
The various option actions all have slightly different requirements
and effects. Except for the ``help'' action, you must supply at least
one other keyword argument when creating the Option; the exact
requirements for each action are listed here.


6.20.3.4 Option types

optparse-option-actions.html | optparse-advanced-usage.html | optparse-querying-and-manipulating.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3.3 Option actions (optparse-option-actions.html)
Up:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Next:
6.20.3.5 Querying and manipulating (optparse-querying-and-manipulating.html)
---
### 6.20.3.4 Option types
optparse supports six option types out of the box: string,
int, long, choice, float and complex.
(Of these, string, int, float, and choice are the most commonly used
--long and complex are there mainly for completeness.) It's easy to
add new option types by subclassing the Option class; see
section 6.20.5 (optparse-extending.html#optparse-extending), ``Extending optparse.''
Arguments to string options are not checked or converted in any way:
the text on the command line is stored in the destination (or passed
to the callback) as-is.
Integer arguments are passed to int() to convert them to
Python integers. If int() fails, so will
optparse, although with a more useful error message.
Internally, optparse raises OptionValueError in
optparse.check_builtin(); at a higher level (in
OptionParser), optparse catches this exception and
terminates your program with a useful error message.
Likewise, float arguments are passed to float() for
conversion, long arguments to long(), and complex arguments
to complex(). Apart from that, they are handled
identically to integer arguments.
Choice options are a subtype of string options. A master list or
tuple of choices (strings) must be passed to the option constructor
(make_option() or OptionParser.add_option()) as
the choices keyword argument. Choice option arguments are
compared against this master list in
optparse.check_choice(), and OptionValueError
is raised if an unknown string is given.


6.20.1.2 What are options for?

optparse-terminology.html | optparse-philosophy.html | optparse-positional-arguments.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.1.1 Terminology (optparse-terminology.html)
Up:
6.20.1 Philosophy (optparse-philosophy.html)
Next:
6.20.1.3 What are positional (optparse-positional-arguments.html)
---
### 6.20.1.2 What are options for?
Options are used to provide extra information to tune or customize the
execution of a program. In case it wasn't clear, options should be
optional. A program should be able to run just fine with no
options whatsoever. (Pick a random program from the Unix or GNU
toolsets. Can it run without any options at all and still make sense?
The only exceptions I can think of are find, tar,
and dd--all of which are mutant oddballs that have been
rightly criticized for their non-standard syntax and confusing
interfaces.)
Lots of people want their programs to have ``required options''.
Think about it. If it's required, then it's not optional! If
there is a piece of information that your program absolutely requires
in order to run successfully, that's what positional arguments are
for. (However, if you insist on adding ``required options'' to your
programs, look in ``Extending Examples''
(section 6.20.5 (optparse-extending-examples.html#optparse-extending-examples)) for two ways of
implementing them with optparse.)
Consider the humble cp utility, for copying files. It
doesn't make much sense to try to copy files without supplying a
destination and at least one source. Hence, cp fails if you
run it with no arguments. However, it has a flexible, useful syntax
that does not rely on options at all:
```text

$ cp SOURCE DEST
$ cp SOURCE ... DEST-DIR
```
You can get pretty far with just that. Most cp
implementations provide a bunch of options to tweak exactly how the
files are copied: you can preserve mode and modification time, avoid
following symlinks, ask before clobbering existing files, etc. But
none of this distracts from the core mission of cp, which is
to copy one file to another, or N files to another directory.


6.20.2.2 Other store_* actions

optparse-store-action.html | optparse-basic-usage.html | optparse-setting-default-values.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.1 The store action (optparse-store-action.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.2.3 Setting default values (optparse-setting-default-values.html)
---
### 6.20.2.2 Other store_* actions
Flag options--set a variable to true or false when a particular
option is seen--are quite common. optparse supports them
with two separate actions, ``store_true'' and ``store_false''. For
example, you might have a verbose flag that is turned on with
-v and off with -q:
```text

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
```
Here we have two different options with the same destination, which is
perfectly OK. (It just means you have to be a bit careful when setting
default values--see below.)
When optparse sees -v on the command line, it sets
`options.verbose` to `True`; when it sees -q, it
sets `options.verbose` to `False`.


6.20.1 Philosophy

module-optparse.html | module-optparse.html | optparse-terminology.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20 optparse (module-optparse.html)
Up:
6.20 optparse (module-optparse.html)
Next:
6.20.1.1 Terminology (optparse-terminology.html)
---
## 6.20.1 Philosophy
The purpose of optparse is to make it very easy to provide the
most standard, obvious, straightforward, and user-friendly user
interface for Unix command-line programs. The optparse
philosophy is heavily influenced by the Unix and GNU toolkits, and
this section is meant to explain that philosophy.


optparse-options.html | optparse-philosophy.html | optparse-basic-usage.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.1.2 What are options (optparse-options.html)
Up:
6.20.1 Philosophy (optparse-philosophy.html)
Next:
6.20.2 Basic Usage (optparse-basic-usage.html)
---
### 6.20.1.3 What are positional arguments for?
In case it wasn't clear from the above example: positional arguments
are for those pieces of information that your program absolutely,
positively requires to run.
A good user interface should have as few absolute requirements as
possible. If your program requires 17 distinct pieces of information in
order to run successfully, it doesn't much matter how you get that
information from the user--most people will give up and walk away
before they successfully run the program. This applies whether the user
interface is a command-line, a configuration file, a GUI, or whatever:
if you make that many demands on your users, most of them will just give
up.
In short, try to minimize the amount of information that users are
absolutely required to supply--use sensible defaults whenever
possible. Of course, you also want to make your programs reasonably
flexible. That's what options are for. Again, it doesn't matter if
they are entries in a config file, checkboxes in the ``Preferences''
dialog of a GUI, or command-line options--the more options you
implement, the more flexible your program is, and the more complicated
its implementation becomes. It's quite easy to overwhelm users (and
yourself!) with too much flexibility, so be careful there.


6.20.2.5 Print a version number

optparse-generating-help.html | optparse-basic-usage.html | optparse-error-handling.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.4 Generating help (optparse-generating-help.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.2.6 Error-handling (optparse-error-handling.html)
---
### 6.20.2.5 Print a version number
Similar to the brief usage string, optparse can also print a
version string for your program. You have to supply the string, as
the version argument to OptionParser:
```text

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
```
version can contain anything you like; `%prog` is expanded
in version just as with usage. When you supply it,
optparse automatically adds a --version option
to your parser. If it encounters this option on the command line, it
expands your version string (by replacing `%prog`), prints
it to stdout, and exits.
For example, if your script is called /usr/bin/foo, a user might do:
```text

$ /usr/bin/foo --version
foo 1.0
```


optparse-option-types.html | optparse-advanced-usage.html | optparse-conflicts.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.3.4 Option types (optparse-option-types.html)
Up:
6.20.3 Advanced Usage (optparse-advanced-usage.html)
Next:
6.20.3.6 Conflicts between options (optparse-conflicts.html)
---
### 6.20.3.5 Querying and manipulating your option parser
Sometimes, it's useful to poke around your option parser and see what's
there. OptionParser provides a couple of methods to help you out:


6.20.2.3 Setting default values

optparse-other-store-actions.html | optparse-basic-usage.html | optparse-generating-help.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2.2 Other store_* actions (optparse-other-store-actions.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.2.4 Generating help (optparse-generating-help.html)
---
### 6.20.2.3 Setting default values
All of the above examples involve setting some variable (the
``destination'') when certain command-line options are seen. What
happens if those options are never seen? Since we didn't supply any
defaults, they are all set to `None`. Sometimes, this is just fine (which
is why it's the default), but sometimes, you want more control. To
address that need, optparse lets you supply a default value for
each destination, which is assigned before the command-line is parsed.
First, consider the verbose/quiet example. If we want
optparse to set verbose to `True` unless
-q is seen, then we can do this:
```text

parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")
```
Oddly enough, this is exactly equivalent:
```text

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)
```
Those are equivalent because you're supplying a default value for the
option's destination, and these two options happen to have the same
destination (the verbose variable).
Consider this:
```text

parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)
```
Again, the default value for verbose will be `True`: the last
default value supplied for any particular destination is the one that
counts.


6.20.2.1 The store action

optparse-basic-usage.html | optparse-basic-usage.html | optparse-other-store-actions.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.2 Basic Usage (optparse-basic-usage.html)
Up:
6.20.2 Basic Usage (optparse-basic-usage.html)
Next:
6.20.2.2 Other store_* actions (optparse-other-store-actions.html)
---
### 6.20.2.1 The store action
The action tells optparse what to do when it sees one of the
option strings for this option on the command-line. For example, the
action store means: take the next argument (or the remainder of
the current argument), ensure that it is of the correct type, and
store it to your chosen destination.
For example, let's fill in the ``...'' of that last option:
```text

parser.add_option("-f", "--file",
action="store", type="string", dest="filename")
```
Now let's make up a fake command-line and ask optparse to
parse it:
```text

args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
```
(Note that if you don't pass an argument list to
parse_args(), it automatically uses `sys.argv[1:]`.)
When optparse sees the -f, it consumes the next
argument--`foo.txt`--and stores it in the filename
attribute of a special object. That object is the first return value
from parse_args(), so:
```text

print options.filename
```
will print `foo.txt`.
Other option types supported by optparse are `int` and
`float`. Here's an option that expects an integer argument:
```text

parser.add_option("-n", type="int", dest="num")
```
This example doesn't provide a long option, which is perfectly
acceptable. It also doesn't specify the action--it defaults to
``store''.
Let's parse another fake command-line. This time, we'll jam the option
argument right up against the option, since -n42 (one
argument) is equivalent to -n 42 (two arguments).
```text

(options, args) = parser.parse_args(["-n42"])
print options.num
```
This prints `42`.
Trying out the ``float'' type is left as an exercise for the reader.
If you don't specify a type, optparse assumes ``string''.
Combined with the fact that the default action is ``store'', that
means our first example can be a lot shorter:
```text

parser.add_option("-f", "--file", dest="filename")
```
If you don't supply a destination, optparse figures out a
sensible default from the option strings: if the first long option
string is --foo-bar, then the default destination is
foo_bar. If there are no long option strings,
optparse looks at the first short option: the default
destination for -f is f.
Adding types is fairly easy; please refer to
section 6.20.5 (optparse-adding-types.html#optparse-adding-types), ``Adding new types.''


6.20.1.1 Terminology

optparse-philosophy.html | optparse-philosophy.html | optparse-options.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.20.1 Philosophy (optparse-philosophy.html)
Up:
6.20.1 Philosophy (optparse-philosophy.html)
Next:
6.20.1.2 What are options (optparse-options.html)
---
### 6.20.1.1 Terminology
First, we need to establish some terminology.
For example, consider this hypothetical command-line:
```text

prog -v --report /tmp/report.txt foo bar
```
-v and --report are both options. Assuming
the --report option takes one argument,
`/tmp/report.txt` is an option argument. `foo` and `bar`
are positional arguments.


5.3.2 Organizing test code

minimal-example.html | module-unittest.html | legacy-unit-tests.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
5.3.1 Minimal example (minimal-example.html)
Up:
5.3 unittest (module-unittest.html)
Next:
5.3.3 Re-using old test (legacy-unit-tests.html)
---
## 5.3.2 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
Previous:
6.1.2 File Object Creation (os-newstreams.html)
Up:
6.1 os (module-os.html)
Next:
6.1.4 Files and Directories (os-file-dir.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
Previous:
6.1.3 File Descriptor Operations (os-fd-ops.html)
Up:
6.1 os (module-os.html)
Next:
6.1.5 Process Management (os-process.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
Previous:
6.1.1 Process Parameters (os-procinfo.html)
Up:
6.1 os (module-os.html)
Next:
6.1.3 File Descriptor Operations (os-fd-ops.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.
For a discussion of possible deadlock conditions related to the use
of these functions, see ``Flow Control
Issues (popen2-flow-control.html)''
(section 6.8.2 (popen2-flow-control.html#popen2-flow-control)).
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
Previous:
6.1.5 Process Management (os-process.html)
Up:
6.1 os (module-os.html)
Next:
6.2 os.path (module-os.path.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
Previous:
6.1.4 Files and Directories (os-file-dir.html)
Up:
6.1 os (module-os.html)
Next:
6.1.6 Miscellaneous System Information (os-path.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 exit codes are a defined, and can be used with
_exit(), although they are not required. These are
typically used for system programs written in Python, such as a
mail server's external command delivery program.
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
Previous:
6.1 os (module-os.html)
Up:
6.1 os (module-os.html)
Next:
6.1.2 File Object Creation (os-newstreams.html)
---
## 6.1.1 Process Parameters
These functions and data items provide information and operate on the
current process and user.


14.11.1 Audio Device Objects

module-ossaudiodev.html | module-ossaudiodev.html | mixer-device-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
14.11 ossaudiodev (module-ossaudiodev.html)
Up:
14.11 ossaudiodev (module-ossaudiodev.html)
Next:
14.11.2 Mixer Device Objects (mixer-device-objects.html)
---
## 14.11.1 Audio Device Objects
Before you can write to or read from an audio device, you must call
three methods in the correct order:
1. setfmt() to set the output format
2. channels() to set the number of channels
3. speed() to set the sample rate
Alternately, you can use the setparameters() method to set all
three audio parameters at once. This is more convenient, but may not be
as flexible in all cases.
The audio device objects returned by open() define the
following methods:
The following methods each map to exactly one
ioctl() system call. The correspondence is obvious: for
example, setfmt() corresponds to the `SNDCTL_DSP_SETFMT`
ioctl, and sync() to `SNDCTL_DSP_SYNC` (this can be useful
when consulting the OSS documentation). If the underlying
ioctl() fails, they all raise IOError.
The following convenience methods combine several ioctls, or one ioctl
and some simple calculations.


node672.html | tkinter.html | restricted.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
16.5.3.1 Command line usage (node672.html)
Up:
16. Graphical User Interfaces (tkinter.html)
Next:
17. Restricted Execution (restricted.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
Previous:
16.4 turtle (module-turtle.html)
Up:
16.4 turtle (module-turtle.html)
Next:
16.5 Idle (idle.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-sub.html | module-pickle.html | module-cPickle.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.14.6 Subclassing Unpicklers (pickle-sub.html)
Up:
3.14 pickle (module-pickle.html)
Next:
3.15 cPickle (module-cPickle.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 | node67.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.14.5 The pickle protocol (pickle-protocol.html)
Up:
3.14.5 The pickle protocol (pickle-protocol.html)
Next:
3.14.5.2 Pickling and unpickling (node67.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.6 (#foot8046). If there is no __setstate__() method, the
pickled state 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
want.3.7 (#foot8183)
Warning:
For new-style classes, if __getstate__() returns a false
value, the __setstate__() method will not be called.


3.14.5 The pickle protocol

node64.html | module-pickle.html | pickle-inst.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.14.4 What can be (node64.html)
Up:
3.14 pickle (module-pickle.html)
Next:
3.14.5.1 Pickling and unpickling (pickle-inst.html)
---
## 3.14.5 The pickle protocol
This section describes the ``pickling protocol'' that defines the
interface between the pickler/unpickler and the objects that are being
serialized. This protocol provides a standard way for you to define,
customize, and control how your objects are serialized and
de-serialized. The description in this section doesn't cover specific
customizations that you can employ to make the unpickling environment
slightly safer from untrusted pickle data streams; see section 3.14.6 (pickle-sub.html#pickle-sub)
for more details.


3.14.6 Subclassing Unpicklers

node68.html | module-pickle.html | pickle-example.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
3.14.5.3 Pickling and unpickling (node68.html)
Up:
3.14 pickle (module-pickle.html)
Next:
3.14.7 Example (pickle-example.html)
---
## 3.14.6 Subclassing Unpicklers
By default, unpickling will import any class that it finds in the
pickle data. You can control exactly what gets unpickled and what
gets called by customizing your unpickler. Unfortunately, exactly how
you do this is different depending on whether you're using
pickle or cPickle.3.10 (#foot8186).
In the pickle module, you need to derive a subclass from
Unpickler, overriding the load_global()
method. load_global() should read two lines from the pickle
data stream where the first line will the the name of the module
containing the class and the second line will be the name of the
instance's class. It then looks up the class, possibly importing the
module and digging out the attribute, then it appends what it finds to
the unpickler's stack. Later on, this class will be assigned to the
__class__ attribute of an empty class, as a way of magically
creating an instance without calling its class's __init__().
Your job (should you choose to accept it), would be to have
load_global() push onto the unpickler's stack, a known safe
version of any class you deem safe to unpickle. It is up to you to
produce such a class. Or you could raise an error if you want to
disallow all unpickling of instances. If this sounds like a hack,
you're right. Refer to the source code to make this work.
Things are a little cleaner with cPickle, but not by much.
To control what gets unpickled, you can set the unpickler's
find_global attribute to a function or `None`. If it is
`None` then any attempts to unpickle instances will raise an
UnpicklingError. If it is a function,
then it should accept a module name and a class name, and return the
corresponding class object. It is responsible for looking up the
class and performing any necessary imports, and it may raise an
error to prevent instances of the class from being unpickled.
The moral of the story is that you should be really careful about the
source of the strings your application unpickles.


20.3.1 Player Objects

module-cd.html | module-cd.html | cd-parser-objects.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
20.3 cd (module-cd.html)
Up:
20.3 cd (module-cd.html)
Next:
20.3.2 Parser Objects (cd-parser-objects.html)
---
## 20.3.1 Player Objects
Player objects (returned by open()) have the following
methods:


7.3.1 Polling Objects

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


11.9.2 POP3 Example

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

import getpass, poplib

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


11.9.1 POP3 Objects

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


6.8.2 Flow Control Issues

popen3-objects.html | module-popen2.html | module-datetime.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.8.1 Popen3 and Popen4 (popen3-objects.html)
Up:
6.8 popen2 (module-popen2.html)
Next:
6.9 datetime (module-datetime.html)
---
## 6.8.2 Flow Control Issues
Any time you are working with any form of inter-process communication,
control flow needs to be carefully thought out. This remains the case
with the file objects provided by this module (or the os (module-os.html)
module equivalents).
When reading output from a child process that writes a lot of data to
standard error while the parent is reading from the child's standard
output, a deadlock can occur. A similar situation can occur with other
combinations of reads and writes. The essential factors are that more
than _PC_PIPE_BUF bytes are being written by one process in
a blocking fashion, while the other process is reading from the other
process, also in a blocking fashion.
There are several ways to deal with this situation.
The simplest application change, in many cases, will be to follow this
model in the parent process:
```text

import popen2

r, w, e = popen2.popen3('python slave.py')
e.readlines()
r.readlines()
r.close()
e.close()
w.close()
```
with code like this in the child:
```text

import os
import sys

# note that each of these print statements
# writes a single long string

print >>sys.stderr, 400 * 'this is a test\n'
os.close(sys.stderr.fileno())
print >>sys.stdout, 400 * 'this is another test\n'
```
In particular, note that `sys.stderr` must be closed after
writing all data, or readlines() won't return. Also note
that os.close() must be used, as `sys.stderr.close()`
won't close `stderr` (otherwise assigning to `sys.stderr`
will silently close it, so no further errors can be printed).
Applications which need to support a more general approach should
integrate I/O over pipes with their select() loops, or use
separate threads to read each of the individual files provided by
whichever popen*() function or Popen* class was
used.


6.8.1 Popen3 and Popen4 Objects

module-popen2.html | module-popen2.html | popen2-flow-control.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
6.8 popen2 (module-popen2.html)
Up:
6.8 popen2 (module-popen2.html)
Next:
6.8.2 Flow Control Issues (popen2-flow-control.html)
---
## 6.8.1 Popen3 and Popen4 Objects
Instances of the Popen3 and Popen4 classes have the
following methods:
The following attributes are also available:


8.1.2 Module Contents

posix-large-files.html | module-posix.html | module-pwd.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
8.1.1 Large File Support (posix-large-files.html)
Up:
8.1 posix (module-posix.html)
Next:
8.2 pwd (module-pwd.html)
---
## 8.1.2 Module Contents
Module posix defines the following data item:


8.1.1 Large File Support

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

CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
./configure
```
On large-file-capable Linux systems, this might work:
```text

CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
./configure
```


10.7 Calibration

profile-limits.html | profile.html | node390.html | Python Library Reference | contents.html | modindex.html | genindex.html
Previous:
10.6 Limitations (profile-limits.html)
Up:
10. The Python Profiler (profile.html)
Next:
10.8 Extensions (node390.html)
---
# 10.7 Calibration
The profiler subtracts a constant from each
event handling time to compensate for the overhead of calling the time
function, and socking away the results. By default, the constant is 0.
The following procedure can
be used to obtain a better constant for a given platform (see discussion
in section Limitations above).
```text

import profile
pr = profile.Profile()
for i in range(5):
print pr.calibrate(10000)
```
The method executes the number of Python calls given by the argument,
directly and again under the profiler, measuring the time for both.
It then computes the hidden overhead per profiler event, and returns
that as a float. For example, on an 800 MHz Pentium running
Windows 2000, and using Python's time.clock() as the timer,
the magical number is about 12.5e-6.
The object of this exercise is to get a fairly consistent result.
If your computer is very fast, or your timer function has poor
resolution, you might have to pass 100000, or even 1000000, to get
consistent results.
When you have a consistent answer,
there are three ways you can use it:10.3 (#foot40211)
```text

import profile

# 1. Apply computed bias to all Profile instances created hereafter.
profile.Profile.bias = your_computed_bias

# 2. Apply computed bias to a specific Profile instance.
pr = profile.Profile()
pr.bias = your_computed_bias

# 3. Specify computed bias in instance constructor.
pr = profile.Profile(bias=your_computed_bias)
```
If you have a choice, you are better off choosing a smaller constant, and
then your results will ``less often'' show up as negative in profile
statistics.