cpython/Doc/library/optparse.rst

2038 lines
75 KiB
ReStructuredText
Raw Normal View History

:mod:`optparse` --- Parser for command line options
===================================================
2007-08-15 11:28:22 -03:00
.. module:: optparse
:synopsis: Command-line option parsing library.
:deprecated:
2007-08-15 11:28:22 -03:00
.. moduleauthor:: Greg Ward <gward@python.net>
.. sectionauthor:: Greg Ward <gward@python.net>
**Source code:** :source:`Lib/optparse.py`
.. deprecated:: 3.2
The :mod:`optparse` module is deprecated and will not be developed further;
development will continue with the :mod:`argparse` module.
2011-01-27 16:38:46 -04:00
--------------
:mod:`optparse` is a more convenient, flexible, and powerful library for parsing
command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
more declarative style of command-line parsing: you create an instance of
:class:`OptionParser`, populate it with options, and parse the command
line. :mod:`optparse` allows users to specify options in the conventional
GNU/POSIX syntax, and additionally generates usage and help messages for you.
2007-08-15 11:28:22 -03:00
Here's an example of using :mod:`optparse` in a simple script::
2007-08-15 11:28:22 -03:00
from optparse import OptionParser
...
2007-08-15 11:28:22 -03:00
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose", default=True,
help="don't print status messages to stdout")
(options, args) = parser.parse_args()
With these few lines of code, users of your script can now do the "usual thing"
on the command-line, for example::
<yourscript> --file=outfile -q
As it parses the command line, :mod:`optparse` sets attributes of the
``options`` object returned by :meth:`parse_args` based on user-supplied
command-line values. When :meth:`parse_args` returns from parsing this command
line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
``False``. :mod:`optparse` supports both long and short options, allows short
2007-08-15 11:28:22 -03:00
options to be merged together, and allows options to be associated with their
arguments in a variety of ways. Thus, the following command lines are all
equivalent to the above example::
<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile
Additionally, users can run one of ::
<yourscript> -h
<yourscript> --help
and :mod:`optparse` will print out a brief summary of your script's options:
.. code-block:: text
2007-08-15 11:28:22 -03:00
Usage: <yourscript> [options]
2007-08-15 11:28:22 -03:00
Options:
2007-08-15 11:28:22 -03:00
-h, --help show this help message and exit
-f FILE, --file=FILE write report to FILE
-q, --quiet don't print status messages to stdout
where the value of *yourscript* is determined at runtime (normally from
``sys.argv[0]``).
.. _optparse-background:
Background
----------
:mod:`optparse` was explicitly designed to encourage the creation of programs
with straightforward, conventional command-line interfaces. To that end, it
supports only the most common command-line syntax and semantics conventionally
used under Unix. If you are unfamiliar with these conventions, read this
section to acquaint yourself with them.
.. _optparse-terminology:
Terminology
^^^^^^^^^^^
argument
a string entered on the command-line, and passed by the shell to ``execl()``
or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
(``sys.argv[0]`` is the name of the program being executed). Unix shells
also use the term "word".
2007-08-15 11:28:22 -03:00
It is occasionally desirable to substitute an argument list other than
``sys.argv[1:]``, so you should read "argument" as "an element of
``sys.argv[1:]``, or of some other list provided as a substitute for
``sys.argv[1:]``".
Merged revisions 66141,66145,66150,66180,66211,66217,66219,66226,66231,66244,66246,66249-66250,66264,66268,66272,66294,66306 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r66141 | gregory.p.smith | 2008-09-02 00:29:51 -0500 (Tue, 02 Sep 2008) | 3 lines Issue #3678: Correctly pass LDFLAGS and LDLAST to the linker on shared library targets in the Makefile. ........ r66145 | marc-andre.lemburg | 2008-09-02 05:32:34 -0500 (Tue, 02 Sep 2008) | 5 lines Add quotes around the file name to avoid issues with spaces. Closes #3719. ........ r66150 | marc-andre.lemburg | 2008-09-02 07:11:19 -0500 (Tue, 02 Sep 2008) | 3 lines Add news item for #3719. ........ r66180 | vinay.sajip | 2008-09-03 04:20:05 -0500 (Wed, 03 Sep 2008) | 1 line Issue #3726: Allowed spaces in separators in logging configuration files. ........ r66211 | vinay.sajip | 2008-09-04 02:31:21 -0500 (Thu, 04 Sep 2008) | 1 line Issue #3772: Fixed regression problem in StreamHandler.emit(). ........ r66217 | andrew.kuchling | 2008-09-04 08:26:24 -0500 (Thu, 04 Sep 2008) | 1 line #3671: various corrections and markup fixes noted by Kent Johnson ........ r66219 | hirokazu.yamamoto | 2008-09-04 09:25:30 -0500 (Thu, 04 Sep 2008) | 1 line Added NEWS ........ r66226 | benjamin.peterson | 2008-09-04 18:31:27 -0500 (Thu, 04 Sep 2008) | 1 line flesh out the documentation on using 2to3 ........ r66231 | andrew.kuchling | 2008-09-05 10:15:56 -0500 (Fri, 05 Sep 2008) | 1 line #3671: Typo fix ........ r66244 | jesse.noller | 2008-09-05 20:20:11 -0500 (Fri, 05 Sep 2008) | 2 lines Fix typo in multiprocessing doc, cancel_join_thread was missing _thread ........ r66246 | benjamin.peterson | 2008-09-05 22:00:00 -0500 (Fri, 05 Sep 2008) | 1 line actually tell the name of the flag to use ........ r66249 | andrew.kuchling | 2008-09-06 07:50:05 -0500 (Sat, 06 Sep 2008) | 1 line Various corrections ........ r66250 | andrew.kuchling | 2008-09-06 08:04:02 -0500 (Sat, 06 Sep 2008) | 1 line #3040: include 'dest' argument in example; trim some trailing whitespace ........ r66264 | benjamin.peterson | 2008-09-06 14:42:39 -0500 (Sat, 06 Sep 2008) | 1 line docs are pretty good about new-style classes these days ........ r66268 | andrew.kuchling | 2008-09-06 15:28:01 -0500 (Sat, 06 Sep 2008) | 1 line #3669 from Robert Lehmann: simplify use of iterator in example ........ r66272 | andrew.kuchling | 2008-09-06 16:26:02 -0500 (Sat, 06 Sep 2008) | 1 line #1317: describe the does_esmtp, ehlo_resp, esmtp_features, and helo_resp attributes ........ r66294 | georg.brandl | 2008-09-07 12:00:17 -0500 (Sun, 07 Sep 2008) | 2 lines Add a new howto about Python and the web, by Marek Kubica. ........ r66306 | mark.summerfield | 2008-09-08 09:45:37 -0500 (Mon, 08 Sep 2008) | 3 lines Added xrefs to each other. ........
2008-09-08 20:05:23 -03:00
option
an argument used to supply extra information to guide or customize the
execution of a program. There are many different syntaxes for options; the
traditional Unix syntax is a hyphen ("-") followed by a single letter,
e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple
options to be merged into a single argument, e.g. ``-x -F`` is equivalent
to ``-xF``. The GNU project introduced ``--`` followed by a series of
hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
only two option syntaxes provided by :mod:`optparse`.
2007-08-15 11:28:22 -03:00
Some other option syntaxes that the world has seen include:
* a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same
2007-08-15 11:28:22 -03:00
as multiple options merged into a single argument)
* a hyphen followed by a whole word, e.g. ``-file`` (this is technically
2007-08-15 11:28:22 -03:00
equivalent to the previous syntax, but they aren't usually seen in the same
program)
* a plus sign followed by a single letter, or a few letters, or a word, e.g.
``+f``, ``+rgb``
2007-08-15 11:28:22 -03:00
* a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
``/file``
2007-08-15 11:28:22 -03:00
These option syntaxes are not supported by :mod:`optparse`, and they never
will be. This is deliberate: the first three are non-standard on any
environment, and the last only makes sense if you're exclusively targeting
VMS, MS-DOS, and/or Windows.
2007-08-15 11:28:22 -03:00
option argument
an argument that follows an option, is closely associated with that option,
and is consumed from the argument list when that option is. With
:mod:`optparse`, option arguments may either be in a separate argument from
their option:
.. code-block:: text
2007-08-15 11:28:22 -03:00
-f foo
--file foo
or included in the same argument:
.. code-block:: text
2007-08-15 11:28:22 -03:00
-ffoo
--file=foo
Typically, a given option either takes an argument or it doesn't. Lots of
people want an "optional option arguments" feature, meaning that some options
will take an argument if they see it, and won't if they don't. This is
somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
an optional argument and ``-b`` is another option entirely, how do we
interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
support this feature.
2007-08-15 11:28:22 -03:00
positional argument
something leftover in the argument list after options have been parsed, i.e.
after options and their arguments have been parsed and removed from the
argument list.
2007-08-15 11:28:22 -03:00
required option
an option that must be supplied on the command-line; note that the phrase
"required option" is self-contradictory in English. :mod:`optparse` doesn't
prevent you from implementing required options, but doesn't give you much
Merged revisions 76847,76851,76869,76882,76891-76892,76924,77007,77070,77092,77096,77120,77126,77155 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76847 | benjamin.peterson | 2009-12-14 21:25:27 -0600 (Mon, 14 Dec 2009) | 1 line adverb ........ r76851 | benjamin.peterson | 2009-12-15 21:28:52 -0600 (Tue, 15 Dec 2009) | 1 line remove lib2to3 resource ........ r76869 | vinay.sajip | 2009-12-17 08:52:00 -0600 (Thu, 17 Dec 2009) | 1 line Issue #7529: logging: Minor correction to documentation. ........ r76882 | georg.brandl | 2009-12-19 11:30:28 -0600 (Sat, 19 Dec 2009) | 1 line #7527: use standard versionadded tags. ........ r76891 | georg.brandl | 2009-12-19 12:16:31 -0600 (Sat, 19 Dec 2009) | 1 line #7479: add note about function availability on Unices. ........ r76892 | georg.brandl | 2009-12-19 12:20:18 -0600 (Sat, 19 Dec 2009) | 1 line #7480: remove tautology. ........ r76924 | georg.brandl | 2009-12-20 08:28:05 -0600 (Sun, 20 Dec 2009) | 1 line Small indentation fix. ........ r77007 | gregory.p.smith | 2009-12-23 03:31:11 -0600 (Wed, 23 Dec 2009) | 3 lines Fix possible integer overflow in lchown and fchown functions. For issue1747858. ........ r77070 | amaury.forgeotdarc | 2009-12-27 14:06:44 -0600 (Sun, 27 Dec 2009) | 2 lines Fix a typo in comment ........ r77092 | georg.brandl | 2009-12-28 02:48:24 -0600 (Mon, 28 Dec 2009) | 1 line #7404: remove reference to non-existing example files. ........ r77096 | benjamin.peterson | 2009-12-28 14:51:17 -0600 (Mon, 28 Dec 2009) | 1 line document new fix_callable behavior ........ r77120 | georg.brandl | 2009-12-29 15:09:17 -0600 (Tue, 29 Dec 2009) | 1 line #7595: fix typo in argument default constant. ........ r77126 | amaury.forgeotdarc | 2009-12-29 17:06:17 -0600 (Tue, 29 Dec 2009) | 2 lines #7579: Add docstrings to the msvcrt module ........ r77155 | georg.brandl | 2009-12-30 13:03:00 -0600 (Wed, 30 Dec 2009) | 1 line We only support Windows NT derivatives now. ........
2009-12-30 23:11:23 -04:00
help at it either.
2007-08-15 11:28:22 -03:00
For example, consider this hypothetical command-line::
prog -v --report report.txt foo bar
2007-08-15 11:28:22 -03:00
``-v`` and ``--report`` are both options. Assuming that ``--report``
takes one argument, ``report.txt`` is an option argument. ``foo`` and
``bar`` are positional arguments.
2007-08-15 11:28:22 -03:00
.. _optparse-what-options-for:
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 are usually *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 main exceptions 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.
As an example of good command-line interface design, 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 require any options at all::
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 either one file to another, or several files to another
directory.
.. _optparse-what-positional-arguments-for:
What are positional arguments for?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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, or a GUI: if you make that many demands on your users, most
of them will simply 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, widgets 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. Too much flexibility has drawbacks as well, of course;
too many options can overwhelm users and make your code much harder to maintain.
.. _optparse-tutorial:
Tutorial
--------
While :mod:`optparse` is quite flexible and powerful, it's also straightforward
to use in most cases. This section covers the code patterns that are common to
any :mod:`optparse`\ -based program.
First, you need to import the OptionParser class; then, early in the main
program, create an OptionParser instance::
from optparse import OptionParser
...
2007-08-15 11:28:22 -03:00
parser = OptionParser()
Then you can start defining options. The basic syntax is::
parser.add_option(opt_str, ...,
attr=value, ...)
Each option has one or more option strings, such as ``-f`` or ``--file``,
2007-08-15 11:28:22 -03:00
and several option attributes that tell :mod:`optparse` what to expect and what
to do when it encounters that option on the command line.
Typically, each option will have one short option string and one long option
string, e.g.::
parser.add_option("-f", "--file", ...)
You're free to define as many short option strings and as many long option
strings as you like (including zero), as long as there is at least one option
string overall.
The option strings passed to :meth:`OptionParser.add_option` are effectively
labels for the
2007-08-15 11:28:22 -03:00
option defined by that call. For brevity, we will frequently refer to
*encountering an option* on the command line; in reality, :mod:`optparse`
encounters *option strings* and looks up options from them.
Once all of your options are defined, instruct :mod:`optparse` to parse your
program's command line::
(options, args) = parser.parse_args()
(If you like, you can pass a custom argument list to :meth:`parse_args`, but
that's rarely necessary: by default it uses ``sys.argv[1:]``.)
:meth:`parse_args` returns two values:
* ``options``, an object containing values for all of your options---e.g. if
``--file`` takes a single string argument, then ``options.file`` will be the
2007-08-15 11:28:22 -03:00
filename supplied by the user, or ``None`` if the user did not supply that
option
* ``args``, the list of positional arguments leftover after parsing options
This tutorial section only covers the four most important option attributes:
:attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
(destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
most fundamental.
2007-08-15 11:28:22 -03:00
.. _optparse-understanding-option-actions:
Understanding option actions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Actions tell :mod:`optparse` what to do when it encounters an option on the
command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
adding new actions is an advanced topic covered in section
:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
a value in some variable---for example, take a string from the command line and
store it in an attribute of ``options``.
2007-08-15 11:28:22 -03:00
If you don't specify an option action, :mod:`optparse` defaults to ``store``.
.. _optparse-store-action:
The store action
^^^^^^^^^^^^^^^^
The most common option action is ``store``, which tells :mod:`optparse` to 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::
parser.add_option("-f", "--file",
action="store", type="string", dest="filename")
Now let's make up a fake command line and ask :mod:`optparse` to parse it::
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
When :mod:`optparse` sees the option string ``-f``, it consumes the next
argument, ``foo.txt``, and stores it in ``options.filename``. So, after this
2007-08-15 11:28:22 -03:00
call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
Here's an option that expects an integer argument::
parser.add_option("-n", type="int", dest="num")
Note that this option has no long option string, which is perfectly acceptable.
Also, there's no explicit action, since the default is ``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), the code ::
2007-08-15 11:28:22 -03:00
(options, args) = parser.parse_args(["-n42"])
print(options.num)
2007-08-15 11:28:22 -03:00
will print ``42``.
2007-08-15 11:28:22 -03:00
If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
the fact that the default action is ``store``, that means our first example can
be a lot shorter::
parser.add_option("-f", "--file", dest="filename")
If you don't supply a destination, :mod:`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
2007-08-15 11:28:22 -03:00
long option strings, :mod:`optparse` looks at the first short option string: the
default destination for ``-f`` is ``f``.
2007-08-15 11:28:22 -03:00
:mod:`optparse` also includes the built-in ``complex`` type. Adding
2007-08-15 11:28:22 -03:00
types is covered in section :ref:`optparse-extending-optparse`.
.. _optparse-handling-boolean-options:
Handling boolean (flag) options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flag options---set a variable to true or false when a particular option is seen
---are quite common. :mod:`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``::
2007-08-15 11:28:22 -03:00
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 :mod:`optparse` encounters ``-v`` on the command line, it sets
``options.verbose`` to ``True``; when it encounters ``-q``,
2007-08-15 11:28:22 -03:00
``options.verbose`` is set to ``False``.
.. _optparse-other-actions:
Other actions
^^^^^^^^^^^^^
Some other actions supported by :mod:`optparse` are:
``"store_const"``
2007-08-15 11:28:22 -03:00
store a constant value
``"append"``
2007-08-15 11:28:22 -03:00
append this option's argument to a list
``"count"``
2007-08-15 11:28:22 -03:00
increment a counter by one
``"callback"``
2007-08-15 11:28:22 -03:00
call a specified function
These are covered in section :ref:`optparse-reference-guide`, Reference Guide
and section :ref:`optparse-option-callbacks`.
.. _optparse-default-values:
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``. This
is usually fine, but sometimes you want more control. :mod:`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 :mod:`optparse` to set
``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
2007-08-15 11:28:22 -03:00
parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")
Since default values apply to the *destination* rather than to any particular
option, and these two options happen to have the same destination, this is
exactly equivalent::
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)
Consider this::
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.
A clearer way to specify default values is the :meth:`set_defaults` method of
OptionParser, which you can call at any time before calling :meth:`parse_args`::
parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()
As before, the last value specified for a given option destination is the one
that counts. For clarity, try to use one method or the other of setting default
values, not both.
.. _optparse-generating-help:
Generating help
^^^^^^^^^^^^^^^
:mod:`optparse`'s ability to generate help and usage text automatically is
useful for creating user-friendly command-line interfaces. All you have to do
is supply a :attr:`~Option.help` value for each option, and optionally a short
usage message for your whole program. Here's an OptionParser populated with
2007-08-15 11:28:22 -03:00
user-friendly (documented) options::
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",
Merged revisions 66141,66145,66150,66180,66211,66217,66219,66226,66231,66244,66246,66249-66250,66264,66268,66272,66294,66306 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r66141 | gregory.p.smith | 2008-09-02 00:29:51 -0500 (Tue, 02 Sep 2008) | 3 lines Issue #3678: Correctly pass LDFLAGS and LDLAST to the linker on shared library targets in the Makefile. ........ r66145 | marc-andre.lemburg | 2008-09-02 05:32:34 -0500 (Tue, 02 Sep 2008) | 5 lines Add quotes around the file name to avoid issues with spaces. Closes #3719. ........ r66150 | marc-andre.lemburg | 2008-09-02 07:11:19 -0500 (Tue, 02 Sep 2008) | 3 lines Add news item for #3719. ........ r66180 | vinay.sajip | 2008-09-03 04:20:05 -0500 (Wed, 03 Sep 2008) | 1 line Issue #3726: Allowed spaces in separators in logging configuration files. ........ r66211 | vinay.sajip | 2008-09-04 02:31:21 -0500 (Thu, 04 Sep 2008) | 1 line Issue #3772: Fixed regression problem in StreamHandler.emit(). ........ r66217 | andrew.kuchling | 2008-09-04 08:26:24 -0500 (Thu, 04 Sep 2008) | 1 line #3671: various corrections and markup fixes noted by Kent Johnson ........ r66219 | hirokazu.yamamoto | 2008-09-04 09:25:30 -0500 (Thu, 04 Sep 2008) | 1 line Added NEWS ........ r66226 | benjamin.peterson | 2008-09-04 18:31:27 -0500 (Thu, 04 Sep 2008) | 1 line flesh out the documentation on using 2to3 ........ r66231 | andrew.kuchling | 2008-09-05 10:15:56 -0500 (Fri, 05 Sep 2008) | 1 line #3671: Typo fix ........ r66244 | jesse.noller | 2008-09-05 20:20:11 -0500 (Fri, 05 Sep 2008) | 2 lines Fix typo in multiprocessing doc, cancel_join_thread was missing _thread ........ r66246 | benjamin.peterson | 2008-09-05 22:00:00 -0500 (Fri, 05 Sep 2008) | 1 line actually tell the name of the flag to use ........ r66249 | andrew.kuchling | 2008-09-06 07:50:05 -0500 (Sat, 06 Sep 2008) | 1 line Various corrections ........ r66250 | andrew.kuchling | 2008-09-06 08:04:02 -0500 (Sat, 06 Sep 2008) | 1 line #3040: include 'dest' argument in example; trim some trailing whitespace ........ r66264 | benjamin.peterson | 2008-09-06 14:42:39 -0500 (Sat, 06 Sep 2008) | 1 line docs are pretty good about new-style classes these days ........ r66268 | andrew.kuchling | 2008-09-06 15:28:01 -0500 (Sat, 06 Sep 2008) | 1 line #3669 from Robert Lehmann: simplify use of iterator in example ........ r66272 | andrew.kuchling | 2008-09-06 16:26:02 -0500 (Sat, 06 Sep 2008) | 1 line #1317: describe the does_esmtp, ehlo_resp, esmtp_features, and helo_resp attributes ........ r66294 | georg.brandl | 2008-09-07 12:00:17 -0500 (Sun, 07 Sep 2008) | 2 lines Add a new howto about Python and the web, by Marek Kubica. ........ r66306 | mark.summerfield | 2008-09-08 09:45:37 -0500 (Mon, 08 Sep 2008) | 3 lines Added xrefs to each other. ........
2008-09-08 20:05:23 -03:00
action="store_false", dest="verbose",
2007-08-15 11:28:22 -03:00
help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
metavar="FILE", help="write output to FILE")
2007-08-15 11:28:22 -03:00
parser.add_option("-m", "--mode",
default="intermediate",
help="interaction mode: novice, intermediate, "
"or expert [default: %default]")
If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
2007-08-15 11:28:22 -03:00
command-line, or if you just call :meth:`parser.print_help`, it prints the
following to standard output:
.. code-block:: text
2007-08-15 11:28:22 -03:00
Usage: <yourscript> [options] arg1 arg2
2007-08-15 11:28:22 -03:00
Options:
2007-08-15 11:28:22 -03:00
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
(If the help output is triggered by a help option, :mod:`optparse` exits after
printing the help text.)
There's a lot going on here to help :mod:`optparse` generate the best possible
help message:
* the script defines its own usage message::
usage = "usage: %prog [options] arg1 arg2"
:mod:`optparse` expands ``%prog`` in the usage string to the name of the
current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
is then printed before the detailed option help.
2007-08-15 11:28:22 -03:00
If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
default: ``"Usage: %prog [options]"``, which is fine if your script doesn't
take any positional arguments.
2007-08-15 11:28:22 -03:00
* every option defines a help string, and doesn't worry about line-wrapping---
:mod:`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::
-m MODE, --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,
2007-08-15 11:28:22 -03:00
:mod:`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::
2007-08-15 11:28:22 -03:00
-f FILE, --filename=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 semi-formal syntax ``-f FILE`` 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.
2007-08-15 11:28:22 -03:00
* options that have a default value can include ``%default`` in the help
string---\ :mod:`optparse` will replace it with :func:`str` of the option's
default value. If an option has no default value (or the default value is
``None``), ``%default`` expands to ``none``.
Grouping Options
++++++++++++++++
When dealing with many options, it is convenient to group these options for
better help output. An :class:`OptionParser` can contain several option groups,
each of which can contain several options.
Merged revisions 60094-60123 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk *** NOTE *** I haven't merged the files in Doc/c-api/. I got too many conflicts. Georg, please split them manually. ........ r60095 | andrew.kuchling | 2008-01-19 21:12:04 +0100 (Sat, 19 Jan 2008) | 2 lines Bug 1277: make Maildir use the user-provided factory instead of hard-wiring MaildirMessage. 2.5.2 bugfix candidate. ........ r60097 | georg.brandl | 2008-01-19 21:22:13 +0100 (Sat, 19 Jan 2008) | 4 lines #1663329: add os.closerange() to close a range of fds, ignoring errors, and use this in subprocess to speed up subprocess creation in close_fds mode. Patch by Mike Klaas. ........ r60099 | georg.brandl | 2008-01-19 21:40:24 +0100 (Sat, 19 Jan 2008) | 2 lines #1411695: clarify behavior of xml.sax.utils.[un]escape. ........ r60101 | andrew.kuchling | 2008-01-19 21:47:59 +0100 (Sat, 19 Jan 2008) | 7 lines Patch #1019808 from Federico Schwindt: Return correct socket error when a default timeout has been set, by using getsockopt() to get the error condition (instead of trying another connect() call, which seems to be a Linuxism). 2.5 bugfix candidate, assuming no one reports any problems with this change. ........ r60102 | gregory.p.smith | 2008-01-19 21:49:02 +0100 (Sat, 19 Jan 2008) | 3 lines fix comment typos, use not arg instead of arg == "", add test coverage for inside of the final if needquotes: within subprocess.list2cmdline(). ........ r60103 | georg.brandl | 2008-01-19 21:53:07 +0100 (Sat, 19 Jan 2008) | 2 lines #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. ........ r60104 | gregory.p.smith | 2008-01-19 21:57:59 +0100 (Sat, 19 Jan 2008) | 6 lines Fixes issue1336 - a race condition could occur when forking if the gc kicked in during the critical section. solution: disable gc during that section. Patch contributed by jpa and updated by me to cover the race condition still existing what therve from twistedmatrix pointed out (already seen and fixed in twisted's own subprocess code). ........ r60105 | gregory.p.smith | 2008-01-19 22:00:37 +0100 (Sat, 19 Jan 2008) | 2 lines note about r60104 ........ r60106 | andrew.kuchling | 2008-01-19 22:00:38 +0100 (Sat, 19 Jan 2008) | 1 line Bug 1296: restore text describing OptionGroup ........ r60109 | georg.brandl | 2008-01-19 23:08:21 +0100 (Sat, 19 Jan 2008) | 2 lines Split the monstrous C API manual files in smaller parts. ........ r60110 | georg.brandl | 2008-01-19 23:14:27 +0100 (Sat, 19 Jan 2008) | 2 lines Missed one big file to split up. ........ r60111 | gregory.p.smith | 2008-01-19 23:23:56 +0100 (Sat, 19 Jan 2008) | 12 lines Undo an unnecessary else: and indentation that r60104 added. try: ... except: ... raise else: ... the else: is unecessary due to the blind except: with a raise. ........ r60115 | gregory.p.smith | 2008-01-19 23:49:37 +0100 (Sat, 19 Jan 2008) | 3 lines Fix issue 1300: Quote command line arguments that contain a '|' character in subprocess.list2cmdline (windows). ........ r60116 | gregory.p.smith | 2008-01-20 00:10:52 +0100 (Sun, 20 Jan 2008) | 3 lines Fixes/Accepts Patch for issue1189216 - Work properly with archives that have file headers past the 2**31 byte boundary. ........ r60119 | andrew.kuchling | 2008-01-20 01:00:38 +0100 (Sun, 20 Jan 2008) | 3 lines Patch #1048820 from Stefan Wehr: add insert-mode editing to Textbox. Fix an off-by-one error I noticed. ........ r60120 | andrew.kuchling | 2008-01-20 01:12:19 +0100 (Sun, 20 Jan 2008) | 1 line Add an interactive test script for exercising curses ........ r60121 | gregory.p.smith | 2008-01-20 02:21:03 +0100 (Sun, 20 Jan 2008) | 7 lines Fix zipfile decryption. The check for validity only worked on one type of encrypted zip files. Files using extended local headers needed to compare the check byte against different values. (according to reading the infozip unzip crypt.c source code) Fixes issue1003. ........ r60122 | gregory.p.smith | 2008-01-20 02:26:04 +0100 (Sun, 20 Jan 2008) | 2 lines note for r60121 ........ r60123 | gregory.p.smith | 2008-01-20 02:32:00 +0100 (Sun, 20 Jan 2008) | 4 lines Document that zipfile decryption is insanely slow and fix a typo and blatant lie in a docstring (it is not useful for security regardless of how you spell it). ........
2008-01-20 05:06:41 -04:00
An option group is obtained using the class :class:`OptionGroup`:
.. class:: OptionGroup(parser, title, description=None)
where
* parser is the :class:`OptionParser` instance the group will be insterted in
to
* title is the group title
* description, optional, is a long description of the group
:class:`OptionGroup` inherits from :class:`OptionContainer` (like
:class:`OptionParser`) and so the :meth:`add_option` method can be used to add
an option to the group.
Once all the options are declared, using the :class:`OptionParser` method
:meth:`add_option_group` the group is added to the previously defined parser.
Continuing with the parser defined in the previous section, adding an
:class:`OptionGroup` to a parser is easy::
Merged revisions 60094-60123 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk *** NOTE *** I haven't merged the files in Doc/c-api/. I got too many conflicts. Georg, please split them manually. ........ r60095 | andrew.kuchling | 2008-01-19 21:12:04 +0100 (Sat, 19 Jan 2008) | 2 lines Bug 1277: make Maildir use the user-provided factory instead of hard-wiring MaildirMessage. 2.5.2 bugfix candidate. ........ r60097 | georg.brandl | 2008-01-19 21:22:13 +0100 (Sat, 19 Jan 2008) | 4 lines #1663329: add os.closerange() to close a range of fds, ignoring errors, and use this in subprocess to speed up subprocess creation in close_fds mode. Patch by Mike Klaas. ........ r60099 | georg.brandl | 2008-01-19 21:40:24 +0100 (Sat, 19 Jan 2008) | 2 lines #1411695: clarify behavior of xml.sax.utils.[un]escape. ........ r60101 | andrew.kuchling | 2008-01-19 21:47:59 +0100 (Sat, 19 Jan 2008) | 7 lines Patch #1019808 from Federico Schwindt: Return correct socket error when a default timeout has been set, by using getsockopt() to get the error condition (instead of trying another connect() call, which seems to be a Linuxism). 2.5 bugfix candidate, assuming no one reports any problems with this change. ........ r60102 | gregory.p.smith | 2008-01-19 21:49:02 +0100 (Sat, 19 Jan 2008) | 3 lines fix comment typos, use not arg instead of arg == "", add test coverage for inside of the final if needquotes: within subprocess.list2cmdline(). ........ r60103 | georg.brandl | 2008-01-19 21:53:07 +0100 (Sat, 19 Jan 2008) | 2 lines #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. ........ r60104 | gregory.p.smith | 2008-01-19 21:57:59 +0100 (Sat, 19 Jan 2008) | 6 lines Fixes issue1336 - a race condition could occur when forking if the gc kicked in during the critical section. solution: disable gc during that section. Patch contributed by jpa and updated by me to cover the race condition still existing what therve from twistedmatrix pointed out (already seen and fixed in twisted's own subprocess code). ........ r60105 | gregory.p.smith | 2008-01-19 22:00:37 +0100 (Sat, 19 Jan 2008) | 2 lines note about r60104 ........ r60106 | andrew.kuchling | 2008-01-19 22:00:38 +0100 (Sat, 19 Jan 2008) | 1 line Bug 1296: restore text describing OptionGroup ........ r60109 | georg.brandl | 2008-01-19 23:08:21 +0100 (Sat, 19 Jan 2008) | 2 lines Split the monstrous C API manual files in smaller parts. ........ r60110 | georg.brandl | 2008-01-19 23:14:27 +0100 (Sat, 19 Jan 2008) | 2 lines Missed one big file to split up. ........ r60111 | gregory.p.smith | 2008-01-19 23:23:56 +0100 (Sat, 19 Jan 2008) | 12 lines Undo an unnecessary else: and indentation that r60104 added. try: ... except: ... raise else: ... the else: is unecessary due to the blind except: with a raise. ........ r60115 | gregory.p.smith | 2008-01-19 23:49:37 +0100 (Sat, 19 Jan 2008) | 3 lines Fix issue 1300: Quote command line arguments that contain a '|' character in subprocess.list2cmdline (windows). ........ r60116 | gregory.p.smith | 2008-01-20 00:10:52 +0100 (Sun, 20 Jan 2008) | 3 lines Fixes/Accepts Patch for issue1189216 - Work properly with archives that have file headers past the 2**31 byte boundary. ........ r60119 | andrew.kuchling | 2008-01-20 01:00:38 +0100 (Sun, 20 Jan 2008) | 3 lines Patch #1048820 from Stefan Wehr: add insert-mode editing to Textbox. Fix an off-by-one error I noticed. ........ r60120 | andrew.kuchling | 2008-01-20 01:12:19 +0100 (Sun, 20 Jan 2008) | 1 line Add an interactive test script for exercising curses ........ r60121 | gregory.p.smith | 2008-01-20 02:21:03 +0100 (Sun, 20 Jan 2008) | 7 lines Fix zipfile decryption. The check for validity only worked on one type of encrypted zip files. Files using extended local headers needed to compare the check byte against different values. (according to reading the infozip unzip crypt.c source code) Fixes issue1003. ........ r60122 | gregory.p.smith | 2008-01-20 02:26:04 +0100 (Sun, 20 Jan 2008) | 2 lines note for r60121 ........ r60123 | gregory.p.smith | 2008-01-20 02:32:00 +0100 (Sun, 20 Jan 2008) | 4 lines Document that zipfile decryption is insanely slow and fix a typo and blatant lie in a docstring (it is not useful for security regardless of how you spell it). ........
2008-01-20 05:06:41 -04:00
group = OptionGroup(parser, "Dangerous Options",
"Caution: use these options at your own risk. "
"It is believed that some of them bite.")
Merged revisions 60094-60123 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk *** NOTE *** I haven't merged the files in Doc/c-api/. I got too many conflicts. Georg, please split them manually. ........ r60095 | andrew.kuchling | 2008-01-19 21:12:04 +0100 (Sat, 19 Jan 2008) | 2 lines Bug 1277: make Maildir use the user-provided factory instead of hard-wiring MaildirMessage. 2.5.2 bugfix candidate. ........ r60097 | georg.brandl | 2008-01-19 21:22:13 +0100 (Sat, 19 Jan 2008) | 4 lines #1663329: add os.closerange() to close a range of fds, ignoring errors, and use this in subprocess to speed up subprocess creation in close_fds mode. Patch by Mike Klaas. ........ r60099 | georg.brandl | 2008-01-19 21:40:24 +0100 (Sat, 19 Jan 2008) | 2 lines #1411695: clarify behavior of xml.sax.utils.[un]escape. ........ r60101 | andrew.kuchling | 2008-01-19 21:47:59 +0100 (Sat, 19 Jan 2008) | 7 lines Patch #1019808 from Federico Schwindt: Return correct socket error when a default timeout has been set, by using getsockopt() to get the error condition (instead of trying another connect() call, which seems to be a Linuxism). 2.5 bugfix candidate, assuming no one reports any problems with this change. ........ r60102 | gregory.p.smith | 2008-01-19 21:49:02 +0100 (Sat, 19 Jan 2008) | 3 lines fix comment typos, use not arg instead of arg == "", add test coverage for inside of the final if needquotes: within subprocess.list2cmdline(). ........ r60103 | georg.brandl | 2008-01-19 21:53:07 +0100 (Sat, 19 Jan 2008) | 2 lines #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. ........ r60104 | gregory.p.smith | 2008-01-19 21:57:59 +0100 (Sat, 19 Jan 2008) | 6 lines Fixes issue1336 - a race condition could occur when forking if the gc kicked in during the critical section. solution: disable gc during that section. Patch contributed by jpa and updated by me to cover the race condition still existing what therve from twistedmatrix pointed out (already seen and fixed in twisted's own subprocess code). ........ r60105 | gregory.p.smith | 2008-01-19 22:00:37 +0100 (Sat, 19 Jan 2008) | 2 lines note about r60104 ........ r60106 | andrew.kuchling | 2008-01-19 22:00:38 +0100 (Sat, 19 Jan 2008) | 1 line Bug 1296: restore text describing OptionGroup ........ r60109 | georg.brandl | 2008-01-19 23:08:21 +0100 (Sat, 19 Jan 2008) | 2 lines Split the monstrous C API manual files in smaller parts. ........ r60110 | georg.brandl | 2008-01-19 23:14:27 +0100 (Sat, 19 Jan 2008) | 2 lines Missed one big file to split up. ........ r60111 | gregory.p.smith | 2008-01-19 23:23:56 +0100 (Sat, 19 Jan 2008) | 12 lines Undo an unnecessary else: and indentation that r60104 added. try: ... except: ... raise else: ... the else: is unecessary due to the blind except: with a raise. ........ r60115 | gregory.p.smith | 2008-01-19 23:49:37 +0100 (Sat, 19 Jan 2008) | 3 lines Fix issue 1300: Quote command line arguments that contain a '|' character in subprocess.list2cmdline (windows). ........ r60116 | gregory.p.smith | 2008-01-20 00:10:52 +0100 (Sun, 20 Jan 2008) | 3 lines Fixes/Accepts Patch for issue1189216 - Work properly with archives that have file headers past the 2**31 byte boundary. ........ r60119 | andrew.kuchling | 2008-01-20 01:00:38 +0100 (Sun, 20 Jan 2008) | 3 lines Patch #1048820 from Stefan Wehr: add insert-mode editing to Textbox. Fix an off-by-one error I noticed. ........ r60120 | andrew.kuchling | 2008-01-20 01:12:19 +0100 (Sun, 20 Jan 2008) | 1 line Add an interactive test script for exercising curses ........ r60121 | gregory.p.smith | 2008-01-20 02:21:03 +0100 (Sun, 20 Jan 2008) | 7 lines Fix zipfile decryption. The check for validity only worked on one type of encrypted zip files. Files using extended local headers needed to compare the check byte against different values. (according to reading the infozip unzip crypt.c source code) Fixes issue1003. ........ r60122 | gregory.p.smith | 2008-01-20 02:26:04 +0100 (Sun, 20 Jan 2008) | 2 lines note for r60121 ........ r60123 | gregory.p.smith | 2008-01-20 02:32:00 +0100 (Sun, 20 Jan 2008) | 4 lines Document that zipfile decryption is insanely slow and fix a typo and blatant lie in a docstring (it is not useful for security regardless of how you spell it). ........
2008-01-20 05:06:41 -04:00
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
This would result in the following help output:
.. code-block:: text
Merged revisions 60094-60123 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk *** NOTE *** I haven't merged the files in Doc/c-api/. I got too many conflicts. Georg, please split them manually. ........ r60095 | andrew.kuchling | 2008-01-19 21:12:04 +0100 (Sat, 19 Jan 2008) | 2 lines Bug 1277: make Maildir use the user-provided factory instead of hard-wiring MaildirMessage. 2.5.2 bugfix candidate. ........ r60097 | georg.brandl | 2008-01-19 21:22:13 +0100 (Sat, 19 Jan 2008) | 4 lines #1663329: add os.closerange() to close a range of fds, ignoring errors, and use this in subprocess to speed up subprocess creation in close_fds mode. Patch by Mike Klaas. ........ r60099 | georg.brandl | 2008-01-19 21:40:24 +0100 (Sat, 19 Jan 2008) | 2 lines #1411695: clarify behavior of xml.sax.utils.[un]escape. ........ r60101 | andrew.kuchling | 2008-01-19 21:47:59 +0100 (Sat, 19 Jan 2008) | 7 lines Patch #1019808 from Federico Schwindt: Return correct socket error when a default timeout has been set, by using getsockopt() to get the error condition (instead of trying another connect() call, which seems to be a Linuxism). 2.5 bugfix candidate, assuming no one reports any problems with this change. ........ r60102 | gregory.p.smith | 2008-01-19 21:49:02 +0100 (Sat, 19 Jan 2008) | 3 lines fix comment typos, use not arg instead of arg == "", add test coverage for inside of the final if needquotes: within subprocess.list2cmdline(). ........ r60103 | georg.brandl | 2008-01-19 21:53:07 +0100 (Sat, 19 Jan 2008) | 2 lines #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. ........ r60104 | gregory.p.smith | 2008-01-19 21:57:59 +0100 (Sat, 19 Jan 2008) | 6 lines Fixes issue1336 - a race condition could occur when forking if the gc kicked in during the critical section. solution: disable gc during that section. Patch contributed by jpa and updated by me to cover the race condition still existing what therve from twistedmatrix pointed out (already seen and fixed in twisted's own subprocess code). ........ r60105 | gregory.p.smith | 2008-01-19 22:00:37 +0100 (Sat, 19 Jan 2008) | 2 lines note about r60104 ........ r60106 | andrew.kuchling | 2008-01-19 22:00:38 +0100 (Sat, 19 Jan 2008) | 1 line Bug 1296: restore text describing OptionGroup ........ r60109 | georg.brandl | 2008-01-19 23:08:21 +0100 (Sat, 19 Jan 2008) | 2 lines Split the monstrous C API manual files in smaller parts. ........ r60110 | georg.brandl | 2008-01-19 23:14:27 +0100 (Sat, 19 Jan 2008) | 2 lines Missed one big file to split up. ........ r60111 | gregory.p.smith | 2008-01-19 23:23:56 +0100 (Sat, 19 Jan 2008) | 12 lines Undo an unnecessary else: and indentation that r60104 added. try: ... except: ... raise else: ... the else: is unecessary due to the blind except: with a raise. ........ r60115 | gregory.p.smith | 2008-01-19 23:49:37 +0100 (Sat, 19 Jan 2008) | 3 lines Fix issue 1300: Quote command line arguments that contain a '|' character in subprocess.list2cmdline (windows). ........ r60116 | gregory.p.smith | 2008-01-20 00:10:52 +0100 (Sun, 20 Jan 2008) | 3 lines Fixes/Accepts Patch for issue1189216 - Work properly with archives that have file headers past the 2**31 byte boundary. ........ r60119 | andrew.kuchling | 2008-01-20 01:00:38 +0100 (Sun, 20 Jan 2008) | 3 lines Patch #1048820 from Stefan Wehr: add insert-mode editing to Textbox. Fix an off-by-one error I noticed. ........ r60120 | andrew.kuchling | 2008-01-20 01:12:19 +0100 (Sun, 20 Jan 2008) | 1 line Add an interactive test script for exercising curses ........ r60121 | gregory.p.smith | 2008-01-20 02:21:03 +0100 (Sun, 20 Jan 2008) | 7 lines Fix zipfile decryption. The check for validity only worked on one type of encrypted zip files. Files using extended local headers needed to compare the check byte against different values. (according to reading the infozip unzip crypt.c source code) Fixes issue1003. ........ r60122 | gregory.p.smith | 2008-01-20 02:26:04 +0100 (Sun, 20 Jan 2008) | 2 lines note for r60121 ........ r60123 | gregory.p.smith | 2008-01-20 02:32:00 +0100 (Sun, 20 Jan 2008) | 4 lines Document that zipfile decryption is insanely slow and fix a typo and blatant lie in a docstring (it is not useful for security regardless of how you spell it). ........
2008-01-20 05:06:41 -04:00
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)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
2011-11-16 00:02:21 -04:00
A bit more complete example might involve using more than one group: still
extending the previous example::
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)
group = OptionGroup(parser, "Debug Options")
group.add_option("-d", "--debug", action="store_true",
help="Print debug information")
group.add_option("-s", "--sql", action="store_true",
help="Print all SQL statements executed")
group.add_option("-e", action="store_true", help="Print every action done")
parser.add_option_group(group)
that results in the following output:
.. code-block:: 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)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
[default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
Debug Options:
-d, --debug Print debug information
-s, --sql Print all SQL statements executed
-e Print every action done
Another interesting method, in particular when working programmatically with
option groups is:
Merged revisions 60094-60123 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk *** NOTE *** I haven't merged the files in Doc/c-api/. I got too many conflicts. Georg, please split them manually. ........ r60095 | andrew.kuchling | 2008-01-19 21:12:04 +0100 (Sat, 19 Jan 2008) | 2 lines Bug 1277: make Maildir use the user-provided factory instead of hard-wiring MaildirMessage. 2.5.2 bugfix candidate. ........ r60097 | georg.brandl | 2008-01-19 21:22:13 +0100 (Sat, 19 Jan 2008) | 4 lines #1663329: add os.closerange() to close a range of fds, ignoring errors, and use this in subprocess to speed up subprocess creation in close_fds mode. Patch by Mike Klaas. ........ r60099 | georg.brandl | 2008-01-19 21:40:24 +0100 (Sat, 19 Jan 2008) | 2 lines #1411695: clarify behavior of xml.sax.utils.[un]escape. ........ r60101 | andrew.kuchling | 2008-01-19 21:47:59 +0100 (Sat, 19 Jan 2008) | 7 lines Patch #1019808 from Federico Schwindt: Return correct socket error when a default timeout has been set, by using getsockopt() to get the error condition (instead of trying another connect() call, which seems to be a Linuxism). 2.5 bugfix candidate, assuming no one reports any problems with this change. ........ r60102 | gregory.p.smith | 2008-01-19 21:49:02 +0100 (Sat, 19 Jan 2008) | 3 lines fix comment typos, use not arg instead of arg == "", add test coverage for inside of the final if needquotes: within subprocess.list2cmdline(). ........ r60103 | georg.brandl | 2008-01-19 21:53:07 +0100 (Sat, 19 Jan 2008) | 2 lines #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. ........ r60104 | gregory.p.smith | 2008-01-19 21:57:59 +0100 (Sat, 19 Jan 2008) | 6 lines Fixes issue1336 - a race condition could occur when forking if the gc kicked in during the critical section. solution: disable gc during that section. Patch contributed by jpa and updated by me to cover the race condition still existing what therve from twistedmatrix pointed out (already seen and fixed in twisted's own subprocess code). ........ r60105 | gregory.p.smith | 2008-01-19 22:00:37 +0100 (Sat, 19 Jan 2008) | 2 lines note about r60104 ........ r60106 | andrew.kuchling | 2008-01-19 22:00:38 +0100 (Sat, 19 Jan 2008) | 1 line Bug 1296: restore text describing OptionGroup ........ r60109 | georg.brandl | 2008-01-19 23:08:21 +0100 (Sat, 19 Jan 2008) | 2 lines Split the monstrous C API manual files in smaller parts. ........ r60110 | georg.brandl | 2008-01-19 23:14:27 +0100 (Sat, 19 Jan 2008) | 2 lines Missed one big file to split up. ........ r60111 | gregory.p.smith | 2008-01-19 23:23:56 +0100 (Sat, 19 Jan 2008) | 12 lines Undo an unnecessary else: and indentation that r60104 added. try: ... except: ... raise else: ... the else: is unecessary due to the blind except: with a raise. ........ r60115 | gregory.p.smith | 2008-01-19 23:49:37 +0100 (Sat, 19 Jan 2008) | 3 lines Fix issue 1300: Quote command line arguments that contain a '|' character in subprocess.list2cmdline (windows). ........ r60116 | gregory.p.smith | 2008-01-20 00:10:52 +0100 (Sun, 20 Jan 2008) | 3 lines Fixes/Accepts Patch for issue1189216 - Work properly with archives that have file headers past the 2**31 byte boundary. ........ r60119 | andrew.kuchling | 2008-01-20 01:00:38 +0100 (Sun, 20 Jan 2008) | 3 lines Patch #1048820 from Stefan Wehr: add insert-mode editing to Textbox. Fix an off-by-one error I noticed. ........ r60120 | andrew.kuchling | 2008-01-20 01:12:19 +0100 (Sun, 20 Jan 2008) | 1 line Add an interactive test script for exercising curses ........ r60121 | gregory.p.smith | 2008-01-20 02:21:03 +0100 (Sun, 20 Jan 2008) | 7 lines Fix zipfile decryption. The check for validity only worked on one type of encrypted zip files. Files using extended local headers needed to compare the check byte against different values. (according to reading the infozip unzip crypt.c source code) Fixes issue1003. ........ r60122 | gregory.p.smith | 2008-01-20 02:26:04 +0100 (Sun, 20 Jan 2008) | 2 lines note for r60121 ........ r60123 | gregory.p.smith | 2008-01-20 02:32:00 +0100 (Sun, 20 Jan 2008) | 4 lines Document that zipfile decryption is insanely slow and fix a typo and blatant lie in a docstring (it is not useful for security regardless of how you spell it). ........
2008-01-20 05:06:41 -04:00
.. method:: OptionParser.get_option_group(opt_str)
Merged revisions 60094-60123 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk *** NOTE *** I haven't merged the files in Doc/c-api/. I got too many conflicts. Georg, please split them manually. ........ r60095 | andrew.kuchling | 2008-01-19 21:12:04 +0100 (Sat, 19 Jan 2008) | 2 lines Bug 1277: make Maildir use the user-provided factory instead of hard-wiring MaildirMessage. 2.5.2 bugfix candidate. ........ r60097 | georg.brandl | 2008-01-19 21:22:13 +0100 (Sat, 19 Jan 2008) | 4 lines #1663329: add os.closerange() to close a range of fds, ignoring errors, and use this in subprocess to speed up subprocess creation in close_fds mode. Patch by Mike Klaas. ........ r60099 | georg.brandl | 2008-01-19 21:40:24 +0100 (Sat, 19 Jan 2008) | 2 lines #1411695: clarify behavior of xml.sax.utils.[un]escape. ........ r60101 | andrew.kuchling | 2008-01-19 21:47:59 +0100 (Sat, 19 Jan 2008) | 7 lines Patch #1019808 from Federico Schwindt: Return correct socket error when a default timeout has been set, by using getsockopt() to get the error condition (instead of trying another connect() call, which seems to be a Linuxism). 2.5 bugfix candidate, assuming no one reports any problems with this change. ........ r60102 | gregory.p.smith | 2008-01-19 21:49:02 +0100 (Sat, 19 Jan 2008) | 3 lines fix comment typos, use not arg instead of arg == "", add test coverage for inside of the final if needquotes: within subprocess.list2cmdline(). ........ r60103 | georg.brandl | 2008-01-19 21:53:07 +0100 (Sat, 19 Jan 2008) | 2 lines #1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods. ........ r60104 | gregory.p.smith | 2008-01-19 21:57:59 +0100 (Sat, 19 Jan 2008) | 6 lines Fixes issue1336 - a race condition could occur when forking if the gc kicked in during the critical section. solution: disable gc during that section. Patch contributed by jpa and updated by me to cover the race condition still existing what therve from twistedmatrix pointed out (already seen and fixed in twisted's own subprocess code). ........ r60105 | gregory.p.smith | 2008-01-19 22:00:37 +0100 (Sat, 19 Jan 2008) | 2 lines note about r60104 ........ r60106 | andrew.kuchling | 2008-01-19 22:00:38 +0100 (Sat, 19 Jan 2008) | 1 line Bug 1296: restore text describing OptionGroup ........ r60109 | georg.brandl | 2008-01-19 23:08:21 +0100 (Sat, 19 Jan 2008) | 2 lines Split the monstrous C API manual files in smaller parts. ........ r60110 | georg.brandl | 2008-01-19 23:14:27 +0100 (Sat, 19 Jan 2008) | 2 lines Missed one big file to split up. ........ r60111 | gregory.p.smith | 2008-01-19 23:23:56 +0100 (Sat, 19 Jan 2008) | 12 lines Undo an unnecessary else: and indentation that r60104 added. try: ... except: ... raise else: ... the else: is unecessary due to the blind except: with a raise. ........ r60115 | gregory.p.smith | 2008-01-19 23:49:37 +0100 (Sat, 19 Jan 2008) | 3 lines Fix issue 1300: Quote command line arguments that contain a '|' character in subprocess.list2cmdline (windows). ........ r60116 | gregory.p.smith | 2008-01-20 00:10:52 +0100 (Sun, 20 Jan 2008) | 3 lines Fixes/Accepts Patch for issue1189216 - Work properly with archives that have file headers past the 2**31 byte boundary. ........ r60119 | andrew.kuchling | 2008-01-20 01:00:38 +0100 (Sun, 20 Jan 2008) | 3 lines Patch #1048820 from Stefan Wehr: add insert-mode editing to Textbox. Fix an off-by-one error I noticed. ........ r60120 | andrew.kuchling | 2008-01-20 01:12:19 +0100 (Sun, 20 Jan 2008) | 1 line Add an interactive test script for exercising curses ........ r60121 | gregory.p.smith | 2008-01-20 02:21:03 +0100 (Sun, 20 Jan 2008) | 7 lines Fix zipfile decryption. The check for validity only worked on one type of encrypted zip files. Files using extended local headers needed to compare the check byte against different values. (according to reading the infozip unzip crypt.c source code) Fixes issue1003. ........ r60122 | gregory.p.smith | 2008-01-20 02:26:04 +0100 (Sun, 20 Jan 2008) | 2 lines note for r60121 ........ r60123 | gregory.p.smith | 2008-01-20 02:32:00 +0100 (Sun, 20 Jan 2008) | 4 lines Document that zipfile decryption is insanely slow and fix a typo and blatant lie in a docstring (it is not useful for security regardless of how you spell it). ........
2008-01-20 05:06:41 -04:00
Return the :class:`OptionGroup` to which the short or long option
string *opt_str* (e.g. ``'-o'`` or ``'--option'``) belongs. If
there's no such :class:`OptionGroup`, return ``None``.
2007-08-15 11:28:22 -03:00
.. _optparse-printing-version-string:
Printing a version string
^^^^^^^^^^^^^^^^^^^^^^^^^
Similar to the brief usage string, :mod:`optparse` can also print a version
string for your program. You have to supply the string as the ``version``
argument to OptionParser::
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
``%prog`` is expanded just like it is in ``usage``. Apart from that,
2007-08-15 11:28:22 -03:00
``version`` can contain anything you like. When you supply it, :mod:`optparse`
automatically adds a ``--version`` option to your parser. If it encounters
2007-08-15 11:28:22 -03:00
this option on the command line, it expands your ``version`` string (by
replacing ``%prog``), prints it to stdout, and exits.
2007-08-15 11:28:22 -03:00
For example, if your script is called ``/usr/bin/foo``:
.. code-block:: shell-session
2007-08-15 11:28:22 -03:00
$ /usr/bin/foo --version
foo 1.0
The following two methods can be used to print and get the ``version`` string:
.. method:: OptionParser.print_version(file=None)
Print the version message for the current program (``self.version``) to
*file* (default stdout). As with :meth:`print_usage`, any occurrence
of ``%prog`` in ``self.version`` is replaced with the name of the current
program. Does nothing if ``self.version`` is empty or undefined.
.. method:: OptionParser.get_version()
Same as :meth:`print_version` but returns the version string instead of
printing it.
2007-08-15 11:28:22 -03:00
.. _optparse-how-optparse-handles-errors:
How :mod:`optparse` handles errors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two broad classes of errors that :mod:`optparse` has to worry about:
programmer errors and user errors. Programmer errors are usually erroneous
calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
option attributes, missing option attributes, etc. These are dealt with in the
usual way: raise an exception (either :exc:`optparse.OptionError` or
:exc:`TypeError`) and let the program crash.
2007-08-15 11:28:22 -03:00
Handling user errors is much more important, since they are guaranteed to happen
no matter how stable your code is. :mod:`optparse` can automatically detect
some user errors, such as bad option arguments (passing ``-n 4x`` where
``-n`` takes an integer argument), missing arguments (``-n`` at the end
of the command line, where ``-n`` takes an argument of any type). Also,
you can call :func:`OptionParser.error` to signal an application-defined error
2007-08-15 11:28:22 -03:00
condition::
(options, args) = parser.parse_args()
...
2007-08-15 11:28:22 -03:00
if options.a and options.b:
parser.error("options -a and -b are mutually exclusive")
In either case, :mod:`optparse` handles the error the same way: it prints the
program's usage message and an error message to standard error and exits with
error status 2.
Consider the first example above, where the user passes ``4x`` to an option
that takes an integer:
.. code-block:: shell-session
2007-08-15 11:28:22 -03:00
$ /usr/bin/foo -n 4x
Usage: foo [options]
2007-08-15 11:28:22 -03:00
foo: error: option -n: invalid integer value: '4x'
Or, where the user fails to pass a value at all:
.. code-block:: shell-session
2007-08-15 11:28:22 -03:00
$ /usr/bin/foo -n
Usage: foo [options]
2007-08-15 11:28:22 -03:00
foo: error: -n option requires an argument
:mod:`optparse`\ -generated error messages take care always to mention the
option involved in the error; be sure to do the same when calling
:func:`OptionParser.error` from your application code.
2007-08-15 11:28:22 -03:00
Merged revisions 64119,64147,64150,64165,64219-64221,64229-64230,64233,64235,64253,64278,64280,64301,64303,64320,64328,64338-64339 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r64119 | andrew.kuchling | 2008-06-11 14:53:14 +0200 (mer., 11 juin 2008) | 1 line Note PEP 371 section ........ r64147 | benjamin.peterson | 2008-06-11 22:04:30 +0200 (mer., 11 juin 2008) | 2 lines update ACKS and NEWs for multiprocessing ........ r64150 | georg.brandl | 2008-06-11 22:28:06 +0200 (mer., 11 juin 2008) | 2 lines Can we agree to put dots at entry ends? Thanks. ........ r64165 | armin.rigo | 2008-06-12 11:50:58 +0200 (jeu., 12 juin 2008) | 3 lines Sounds obvious, but I didn't even realize that you can put non-string keys in type dictionaries without using this locals() hack. ........ r64219 | neal.norwitz | 2008-06-13 08:00:46 +0200 (ven., 13 juin 2008) | 1 line Check for memory alloc failure ........ r64220 | neal.norwitz | 2008-06-13 08:02:26 +0200 (ven., 13 juin 2008) | 3 lines Fix some memory dealloc problems when exceptions occur. It caused: "Fatal Python error: UNREF invalid object" in the DoubleTest. ........ r64221 | neal.norwitz | 2008-06-13 08:03:25 +0200 (ven., 13 juin 2008) | 3 lines Fix typo in method name. The LT class implemented less than. The LE class should implement less than or equal to (as the code does). ........ r64229 | georg.brandl | 2008-06-13 15:26:54 +0200 (ven., 13 juin 2008) | 2 lines Clarification. ........ r64230 | robert.schuppenies | 2008-06-13 15:29:37 +0200 (ven., 13 juin 2008) | 2 lines Fixed: sys.getsizeof does not take the actual length of the tuples into account. ........ r64233 | benjamin.peterson | 2008-06-13 17:11:50 +0200 (ven., 13 juin 2008) | 2 lines platform.uname now tries to fill empty values even when os.uname is present ........ r64235 | benjamin.peterson | 2008-06-13 17:41:09 +0200 (ven., 13 juin 2008) | 1 line set svn:ignore on multiprocessing ........ r64253 | andrew.kuchling | 2008-06-13 21:38:18 +0200 (ven., 13 juin 2008) | 1 line Typo fixes ........ r64278 | martin.v.loewis | 2008-06-14 16:24:47 +0200 (sam., 14 juin 2008) | 2 lines Disable UAC by default. ........ r64280 | gregory.p.smith | 2008-06-14 19:34:09 +0200 (sam., 14 juin 2008) | 3 lines silence the test when it is skipped on some platforms. should fix a buildbot. ........ r64301 | georg.brandl | 2008-06-15 21:54:36 +0200 (dim., 15 juin 2008) | 2 lines Forward-port new test from r64300. ........ r64303 | raymond.hettinger | 2008-06-16 03:42:40 +0200 (lun., 16 juin 2008) | 1 line Issue 3116: fix quadratic behavior in marshal.dumps(). ........ r64320 | georg.brandl | 2008-06-16 23:00:47 +0200 (lun., 16 juin 2008) | 2 lines Add Jesse Noller to the developers list. ........ r64328 | georg.brandl | 2008-06-17 11:01:35 +0200 (mar., 17 juin 2008) | 2 lines Split the HTML index. ........ r64338 | vinay.sajip | 2008-06-17 13:02:14 +0200 (mar., 17 juin 2008) | 1 line Bug #3126: StreamHandler and FileHandler check before calling "flush" and "close" that the stream object has these, using hasattr (thanks to bobf for the patch). ........ r64339 | vinay.sajip | 2008-06-17 13:04:02 +0200 (mar., 17 juin 2008) | 1 line Updated with fix for #3126. ........
2008-06-17 18:11:29 -03:00
If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
and/or :meth:`~OptionParser.error` methods.
2007-08-15 11:28:22 -03:00
.. _optparse-putting-it-all-together:
Putting it all together
^^^^^^^^^^^^^^^^^^^^^^^
Here's what :mod:`optparse`\ -based scripts usually look like::
from optparse import OptionParser
...
2007-08-15 11:28:22 -03:00
def main():
usage = "usage: %prog [options] arg"
parser = OptionParser(usage)
parser.add_option("-f", "--file", 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")
...
2007-08-15 11:28:22 -03:00
(options, args) = parser.parse_args()
if len(args) != 1:
parser.error("incorrect number of arguments")
if options.verbose:
print("reading %s..." % options.filename)
...
2007-08-15 11:28:22 -03:00
if __name__ == "__main__":
main()
.. _optparse-reference-guide:
Reference Guide
---------------
.. _optparse-creating-parser:
Creating the parser
^^^^^^^^^^^^^^^^^^^
The first step in using :mod:`optparse` is to create an OptionParser instance.
2007-08-15 11:28:22 -03:00
.. class:: OptionParser(...)
2007-08-15 11:28:22 -03:00
The OptionParser constructor has no required arguments, but a number of
optional keyword arguments. You should always pass them as keyword
arguments, i.e. do not rely on the order in which the arguments are declared.
2007-08-15 11:28:22 -03:00
``usage`` (default: ``"%prog [options]"``)
The usage summary to print when your program is run incorrectly or with a
help option. When :mod:`optparse` prints the usage string, it expands
``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
passed that keyword argument). To suppress a usage message, pass the
special value :data:`optparse.SUPPRESS_USAGE`.
2007-08-15 11:28:22 -03:00
``option_list`` (default: ``[]``)
A list of Option objects to populate the parser with. The options in
``option_list`` are added after any options in ``standard_option_list`` (a
class attribute that may be set by OptionParser subclasses), but before
any version or help options. Deprecated; use :meth:`add_option` after
creating the parser instead.
2007-08-15 11:28:22 -03:00
``option_class`` (default: optparse.Option)
Class to use when adding options to the parser in :meth:`add_option`.
``version`` (default: ``None``)
A version string to print when the user supplies a version option. If you
supply a true value for ``version``, :mod:`optparse` automatically adds a
version option with the single option string ``--version``. The
substring ``%prog`` is expanded the same as for ``usage``.
2007-08-15 11:28:22 -03:00
``conflict_handler`` (default: ``"error"``)
Specifies what to do when options with conflicting option strings are
added to the parser; see section
:ref:`optparse-conflicts-between-options`.
2007-08-15 11:28:22 -03:00
``description`` (default: ``None``)
A paragraph of text giving a brief overview of your program.
:mod:`optparse` reformats this paragraph to fit the current terminal width
and prints it when the user requests help (after ``usage``, but before the
list of options).
``formatter`` (default: a new :class:`IndentedHelpFormatter`)
An instance of optparse.HelpFormatter that will be used for printing help
text. :mod:`optparse` provides two concrete classes for this purpose:
2007-08-15 11:28:22 -03:00
IndentedHelpFormatter and TitledHelpFormatter.
``add_help_option`` (default: ``True``)
If true, :mod:`optparse` will add a help option (with option strings ``-h``
and ``--help``) to the parser.
2007-08-15 11:28:22 -03:00
``prog``
The string to use when expanding ``%prog`` in ``usage`` and ``version``
2007-08-15 11:28:22 -03:00
instead of ``os.path.basename(sys.argv[0])``.
``epilog`` (default: ``None``)
A paragraph of help text to print after the option help.
2007-08-15 11:28:22 -03:00
.. _optparse-populating-parser:
Populating the parser
^^^^^^^^^^^^^^^^^^^^^
There are several ways to populate the parser with options. The preferred way
is by using :meth:`OptionParser.add_option`, as shown in section
2007-08-15 11:28:22 -03:00
:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
* pass it an Option instance (as returned by :func:`make_option`)
* pass it any combination of positional and keyword arguments that are
acceptable to :func:`make_option` (i.e., to the Option constructor), and it
will create the Option instance for you
2007-08-15 11:28:22 -03:00
The other alternative is to pass a list of pre-constructed Option instances to
the OptionParser constructor, as in::
option_list = [
make_option("-f", "--filename",
action="store", type="string", dest="filename"),
make_option("-q", "--quiet",
action="store_false", dest="verbose"),
]
parser = OptionParser(option_list=option_list)
(:func:`make_option` is a factory function for creating Option instances;
currently it is an alias for the Option constructor. A future version of
:mod:`optparse` may split Option into several classes, and :func:`make_option`
will pick the right class to instantiate. Do not instantiate Option directly.)
.. _optparse-defining-options:
Defining options
^^^^^^^^^^^^^^^^
Each Option instance represents a set of synonymous command-line option strings,
e.g. ``-f`` and ``--file``. You can specify any number of short or
2007-08-15 11:28:22 -03:00
long option strings, but you must specify at least one overall option string.
The canonical way to create an :class:`Option` instance is with the
:meth:`add_option` method of :class:`OptionParser`.
2007-08-15 11:28:22 -03:00
.. method:: OptionParser.add_option(option)
OptionParser.add_option(*opt_str, attr=value, ...)
2007-08-15 11:28:22 -03:00
To define an option with only a short option string::
2007-08-15 11:28:22 -03:00
parser.add_option("-f", attr=value, ...)
2007-08-15 11:28:22 -03:00
And to define an option with only a long option string::
2007-08-15 11:28:22 -03:00
parser.add_option("--foo", attr=value, ...)
2007-08-15 11:28:22 -03:00
The keyword arguments define attributes of the new Option object. The most
important option attribute is :attr:`~Option.action`, and it largely
determines which other attributes are relevant or required. If you pass
irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
raises an :exc:`OptionError` exception explaining your mistake.
2007-08-15 11:28:22 -03:00
An option's *action* determines what :mod:`optparse` does when it encounters
this option on the command-line. The standard option actions hard-coded into
:mod:`optparse` are:
2007-08-15 11:28:22 -03:00
``"store"``
store this option's argument (default)
2007-08-15 11:28:22 -03:00
``"store_const"``
store a constant value
2007-08-15 11:28:22 -03:00
``"store_true"``
store a true value
2007-08-15 11:28:22 -03:00
``"store_false"``
store a false value
2007-08-15 11:28:22 -03:00
``"append"``
append this option's argument to a list
2007-08-15 11:28:22 -03:00
``"append_const"``
append a constant value to a list
2007-08-15 11:28:22 -03:00
``"count"``
increment a counter by one
2007-08-15 11:28:22 -03:00
``"callback"``
call a specified function
2007-08-15 11:28:22 -03:00
``"help"``
print a usage message including all options and the documentation for them
2007-08-15 11:28:22 -03:00
(If you don't supply an action, the default is ``"store"``. For this action,
you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
attributes; see :ref:`optparse-standard-option-actions`.)
2007-08-15 11:28:22 -03:00
As you can see, most actions involve storing or updating a value somewhere.
:mod:`optparse` always creates a special object for this, conventionally called
``options`` (it happens to be an instance of :class:`optparse.Values`). Option
2007-08-15 11:28:22 -03:00
arguments (and various other values) are stored as attributes of this object,
according to the :attr:`~Option.dest` (destination) option attribute.
2007-08-15 11:28:22 -03:00
For example, when you call ::
2007-08-15 11:28:22 -03:00
parser.parse_args()
one of the first things :mod:`optparse` does is create the ``options`` object::
options = Values()
If one of the options in this parser is defined with ::
2007-08-15 11:28:22 -03:00
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
and the command-line being parsed includes any of the following::
-ffoo
-f foo
--file=foo
--file foo
then :mod:`optparse`, on seeing this option, will do the equivalent of ::
2007-08-15 11:28:22 -03:00
options.filename = "foo"
The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
one that makes sense for *all* options.
.. _optparse-option-attributes:
Option attributes
^^^^^^^^^^^^^^^^^
The following option attributes may be passed as keyword arguments to
:meth:`OptionParser.add_option`. If you pass an option attribute that is not
relevant to a particular option, or fail to pass a required option attribute,
:mod:`optparse` raises :exc:`OptionError`.
.. attribute:: Option.action
(default: ``"store"``)
Determines :mod:`optparse`'s behaviour when this option is seen on the
command line; the available options are documented :ref:`here
<optparse-standard-option-actions>`.
.. attribute:: Option.type
(default: ``"string"``)
The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
the available option types are documented :ref:`here
<optparse-standard-option-types>`.
.. attribute:: Option.dest
(default: derived from option strings)
If the option's action implies writing or modifying a value somewhere, this
tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
attribute of the ``options`` object that :mod:`optparse` builds as it parses
the command line.
.. attribute:: Option.default
The value to use for this option's destination if the option is not seen on
the command line. See also :meth:`OptionParser.set_defaults`.
.. attribute:: Option.nargs
(default: 1)
How many arguments of type :attr:`~Option.type` should be consumed when this
option is seen. If > 1, :mod:`optparse` will store a tuple of values to
:attr:`~Option.dest`.
.. attribute:: Option.const
For actions that store a constant value, the constant value to store.
.. attribute:: Option.choices
For options of type ``"choice"``, the list of strings the user may choose
from.
.. attribute:: Option.callback
For options with action ``"callback"``, the callable to call when this option
is seen. See section :ref:`optparse-option-callbacks` for detail on the
arguments passed to the callable.
.. attribute:: Option.callback_args
Option.callback_kwargs
Additional positional and keyword arguments to pass to ``callback`` after the
four standard callback arguments.
.. attribute:: Option.help
Help text to print for this option when listing all available options after
the user supplies a :attr:`~Option.help` option (such as ``--help``). If
no help text is supplied, the option will be listed without help text. To
hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
.. attribute:: Option.metavar
(default: derived from option strings)
Stand-in for the option argument(s) to use when printing help text. See
section :ref:`optparse-tutorial` for an example.
2007-08-15 11:28:22 -03:00
.. _optparse-standard-option-actions:
Standard option actions
^^^^^^^^^^^^^^^^^^^^^^^
The various option actions all have slightly different requirements and effects.
Most actions have several relevant option attributes which you may specify to
guide :mod:`optparse`'s behaviour; a few have required attributes, which you
must specify for any option using that action.
* ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
:attr:`~Option.nargs`, :attr:`~Option.choices`]
2007-08-15 11:28:22 -03:00
The option must be followed by an argument, which is converted to a value
according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
:attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
command line; all will be converted according to :attr:`~Option.type` and
stored to :attr:`~Option.dest` as a tuple. See the
:ref:`optparse-standard-option-types` section.
2007-08-15 11:28:22 -03:00
If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
defaults to ``"choice"``.
2007-08-15 11:28:22 -03:00
If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
2007-08-15 11:28:22 -03:00
If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
from the first long option string (e.g., ``--foo-bar`` implies
``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
destination from the first short option string (e.g., ``-f`` implies ``f``).
2007-08-15 11:28:22 -03:00
Example::
parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")
As it parses the command line ::
2007-08-15 11:28:22 -03:00
-f foo.txt -p 1 -3.5 4 -fbar.txt
:mod:`optparse` will set ::
2007-08-15 11:28:22 -03:00
options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"
* ``"store_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]
2007-08-15 11:28:22 -03:00
The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
2007-08-15 11:28:22 -03:00
Example::
parser.add_option("-q", "--quiet",
action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
action="store_const", const=2, dest="verbose")
If ``--noisy`` is seen, :mod:`optparse` will set ::
2007-08-15 11:28:22 -03:00
options.verbose = 2
* ``"store_true"`` [relevant: :attr:`~Option.dest`]
2007-08-15 11:28:22 -03:00
A special case of ``"store_const"`` that stores a true value to
:attr:`~Option.dest`.
2007-08-15 11:28:22 -03:00
* ``"store_false"`` [relevant: :attr:`~Option.dest`]
2007-08-15 11:28:22 -03:00
Like ``"store_true"``, but stores a false value.
2007-08-15 11:28:22 -03:00
Example::
parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")
* ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
:attr:`~Option.nargs`, :attr:`~Option.choices`]
2007-08-15 11:28:22 -03:00
The option must be followed by an argument, which is appended to the list in
:attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
supplied, an empty list is automatically created when :mod:`optparse` first
encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
is appended to :attr:`~Option.dest`.
2007-08-15 11:28:22 -03:00
The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
for the ``"store"`` action.
2007-08-15 11:28:22 -03:00
Example::
parser.add_option("-t", "--tracks", action="append", type="int")
If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
2007-08-15 11:28:22 -03:00
of::
options.tracks = []
options.tracks.append(int("3"))
If, a little later on, ``--tracks=4`` is seen, it does::
2007-08-15 11:28:22 -03:00
options.tracks.append(int("4"))
The ``append`` action calls the ``append`` method on the current value of the
option. This means that any default value specified must have an ``append``
method. It also means that if the default value is non-empty, the default
elements will be present in the parsed value for the option, with any values
from the command line appended after those default values::
>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']
* ``"append_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]
2007-08-15 11:28:22 -03:00
Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
:attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
``None``, and an empty list is automatically created the first time the option
is encountered.
2007-08-15 11:28:22 -03:00
* ``"count"`` [relevant: :attr:`~Option.dest`]
2007-08-15 11:28:22 -03:00
Increment the integer stored at :attr:`~Option.dest`. If no default value is
supplied, :attr:`~Option.dest` is set to zero before being incremented the
first time.
2007-08-15 11:28:22 -03:00
Example::
parser.add_option("-v", action="count", dest="verbosity")
The first time ``-v`` is seen on the command line, :mod:`optparse` does the
2007-08-15 11:28:22 -03:00
equivalent of::
options.verbosity = 0
options.verbosity += 1
Every subsequent occurrence of ``-v`` results in ::
2007-08-15 11:28:22 -03:00
options.verbosity += 1
* ``"callback"`` [required: :attr:`~Option.callback`; relevant:
:attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
:attr:`~Option.callback_kwargs`]
2007-08-15 11:28:22 -03:00
Call the function specified by :attr:`~Option.callback`, which is called as ::
2007-08-15 11:28:22 -03:00
func(option, opt_str, value, parser, *args, **kwargs)
See section :ref:`optparse-option-callbacks` for more detail.
* ``"help"``
2007-08-15 11:28:22 -03:00
Prints a complete help message for all the options in the current option
parser. The help message is constructed from the ``usage`` string passed to
OptionParser's constructor and the :attr:`~Option.help` string passed to every
option.
2007-08-15 11:28:22 -03:00
If no :attr:`~Option.help` string is supplied for an option, it will still be
listed in the help message. To omit an option entirely, use the special value
:data:`optparse.SUPPRESS_HELP`.
2007-08-15 11:28:22 -03:00
:mod:`optparse` automatically adds a :attr:`~Option.help` option to all
OptionParsers, so you do not normally need to create one.
2007-08-15 11:28:22 -03:00
Example::
from optparse import OptionParser, SUPPRESS_HELP
# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
parser = OptionParser(add_help_option=False)
parser.add_option("-h", "--help", action="help")
2007-08-15 11:28:22 -03:00
parser.add_option("-v", action="store_true", dest="verbose",
help="Be moderately verbose")
parser.add_option("--file", dest="filename",
help="Input file to read data from")
2007-08-15 11:28:22 -03:00
parser.add_option("--secret", help=SUPPRESS_HELP)
If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
it will print something like the following help message to stdout (assuming
``sys.argv[0]`` is ``"foo.py"``):
.. code-block:: text
2007-08-15 11:28:22 -03:00
Usage: foo.py [options]
2007-08-15 11:28:22 -03:00
Options:
2007-08-15 11:28:22 -03:00
-h, --help Show this help message and exit
-v Be moderately verbose
--file=FILENAME Input file to read data from
After printing the help message, :mod:`optparse` terminates your process with
``sys.exit(0)``.
* ``"version"``
2007-08-15 11:28:22 -03:00
Prints the version number supplied to the OptionParser to stdout and exits.
The version number is actually formatted and printed by the
``print_version()`` method of OptionParser. Generally only relevant if the
``version`` argument is supplied to the OptionParser constructor. As with
:attr:`~Option.help` options, you will rarely create ``version`` options,
since :mod:`optparse` automatically adds them when needed.
2007-08-15 11:28:22 -03:00
.. _optparse-standard-option-types:
Standard option types
^^^^^^^^^^^^^^^^^^^^^
:mod:`optparse` has five built-in option types: ``"string"``, ``"int"``,
``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
option types, see section :ref:`optparse-extending-optparse`.
2007-08-15 11:28:22 -03:00
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 (type ``"int"``) are parsed as follows:
2007-08-15 11:28:22 -03:00
* if the number starts with ``0x``, it is parsed as a hexadecimal number
* if the number starts with ``0``, it is parsed as an octal number
#1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Merged revisions 58221-58741 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r58221 | georg.brandl | 2007-09-20 10:57:59 -0700 (Thu, 20 Sep 2007) | 2 lines Patch #1181: add os.environ.clear() method. ........ r58225 | sean.reifschneider | 2007-09-20 23:33:28 -0700 (Thu, 20 Sep 2007) | 3 lines Issue1704287: "make install" fails unless you do "make" first. Make oldsharedmods and sharedmods in "libinstall". ........ r58232 | guido.van.rossum | 2007-09-22 13:18:03 -0700 (Sat, 22 Sep 2007) | 4 lines Patch # 188 by Philip Jenvey. Make tell() mark CRLF as a newline. With unit test. ........ r58242 | georg.brandl | 2007-09-24 10:55:47 -0700 (Mon, 24 Sep 2007) | 2 lines Fix typo and double word. ........ r58245 | georg.brandl | 2007-09-24 10:59:28 -0700 (Mon, 24 Sep 2007) | 2 lines #1196: document default radix for int(). ........ r58247 | georg.brandl | 2007-09-24 11:08:24 -0700 (Mon, 24 Sep 2007) | 2 lines #1177: accept 2xx responses for https too, not only http. ........ r58249 | andrew.kuchling | 2007-09-24 16:45:51 -0700 (Mon, 24 Sep 2007) | 1 line Remove stray odd character; grammar fix ........ r58250 | andrew.kuchling | 2007-09-24 16:46:28 -0700 (Mon, 24 Sep 2007) | 1 line Typo fix ........ r58251 | andrew.kuchling | 2007-09-24 17:09:42 -0700 (Mon, 24 Sep 2007) | 1 line Add various items ........ r58268 | vinay.sajip | 2007-09-26 22:34:45 -0700 (Wed, 26 Sep 2007) | 1 line Change to flush and close logic to fix #1760556. ........ r58269 | vinay.sajip | 2007-09-26 22:38:51 -0700 (Wed, 26 Sep 2007) | 1 line Change to basicConfig() to fix #1021. ........ r58270 | georg.brandl | 2007-09-26 23:26:58 -0700 (Wed, 26 Sep 2007) | 2 lines #1208: document match object's boolean value. ........ r58271 | vinay.sajip | 2007-09-26 23:56:13 -0700 (Wed, 26 Sep 2007) | 1 line Minor date change. ........ r58272 | vinay.sajip | 2007-09-27 00:35:10 -0700 (Thu, 27 Sep 2007) | 1 line Change to LogRecord.__init__() to fix #1206. Note that archaic use of type(x) == types.DictType is because of keeping 1.5.2 compatibility. While this is much less relevant these days, there probably needs to be a separate commit for removing all archaic constructs at the same time. ........ r58288 | brett.cannon | 2007-09-30 12:45:10 -0700 (Sun, 30 Sep 2007) | 9 lines tuple.__repr__ did not consider a reference loop as it is not possible from Python code; but it is possible from C. object.__str__ had the issue of not expecting a type to doing something within it's tp_str implementation that could trigger an infinite recursion, but it could in C code.. Both found thanks to BaseException and how it handles its repr. Closes issue #1686386. Thanks to Thomas Herve for taking an initial stab at coming up with a solution. ........ r58289 | brett.cannon | 2007-09-30 13:37:19 -0700 (Sun, 30 Sep 2007) | 3 lines Fix error introduced by r58288; if a tuple is length 0 return its repr and don't worry about any self-referring tuples. ........ r58294 | facundo.batista | 2007-10-02 10:01:24 -0700 (Tue, 02 Oct 2007) | 11 lines Made the various is_* operations return booleans. This was discussed with Cawlishaw by mail, and he basically confirmed that to these is_* operations, there's no need to return Decimal(0) and Decimal(1) if the language supports the False and True booleans. Also added a few tests for the these functions in extra.decTest, since they are mostly untested (apart from the doctests). Thanks Mark Dickinson ........ r58295 | facundo.batista | 2007-10-02 11:21:18 -0700 (Tue, 02 Oct 2007) | 4 lines Added a class to store the digits of log(10), so that they can be made available when necessary without recomputing. Thanks Mark Dickinson ........ r58299 | mark.summerfield | 2007-10-03 01:53:21 -0700 (Wed, 03 Oct 2007) | 4 lines Added note in footnote about string comparisons about unicodedata.normalize(). ........ r58304 | raymond.hettinger | 2007-10-03 14:18:11 -0700 (Wed, 03 Oct 2007) | 1 line enumerate() is no longer bounded to using sequences shorter than LONG_MAX. The possibility of overflow was sending some newsgroup posters into a tizzy. ........ r58305 | raymond.hettinger | 2007-10-03 17:20:27 -0700 (Wed, 03 Oct 2007) | 1 line itertools.count() no longer limited to sys.maxint. ........ r58306 | kurt.kaiser | 2007-10-03 18:49:54 -0700 (Wed, 03 Oct 2007) | 3 lines Assume that the user knows when he wants to end the line; don't insert something he didn't select or complete. ........ r58307 | kurt.kaiser | 2007-10-03 19:07:50 -0700 (Wed, 03 Oct 2007) | 2 lines Remove unused theme that was causing a fault in p3k. ........ r58308 | kurt.kaiser | 2007-10-03 19:09:17 -0700 (Wed, 03 Oct 2007) | 2 lines Clean up EditorWindow close. ........ r58309 | kurt.kaiser | 2007-10-03 19:53:07 -0700 (Wed, 03 Oct 2007) | 7 lines textView cleanup. Patch 1718043 Tal Einat. M idlelib/EditorWindow.py M idlelib/aboutDialog.py M idlelib/textView.py M idlelib/NEWS.txt ........ r58310 | kurt.kaiser | 2007-10-03 20:11:12 -0700 (Wed, 03 Oct 2007) | 3 lines configDialog cleanup. Patch 1730217 Tal Einat. ........ r58311 | neal.norwitz | 2007-10-03 23:00:48 -0700 (Wed, 03 Oct 2007) | 4 lines Coverity #151: Remove deadcode. All this code already exists above starting at line 653. ........ r58325 | fred.drake | 2007-10-04 19:46:12 -0700 (Thu, 04 Oct 2007) | 1 line wrap lines to <80 characters before fixing errors ........ r58326 | raymond.hettinger | 2007-10-04 19:47:07 -0700 (Thu, 04 Oct 2007) | 6 lines Add __asdict__() to NamedTuple and refine the docs. Add maxlen support to deque() and fixup docs. Partially fix __reduce__(). The None as a third arg was no longer supported. Still needs work on __reduce__() to handle recursive inputs. ........ r58327 | fred.drake | 2007-10-04 19:48:32 -0700 (Thu, 04 Oct 2007) | 3 lines move descriptions of ac_(in|out)_buffer_size to the right place http://bugs.python.org/issue1053 ........ r58329 | neal.norwitz | 2007-10-04 20:39:17 -0700 (Thu, 04 Oct 2007) | 3 lines dict could be NULL, so we need to XDECREF. Fix a compiler warning about passing a PyTypeObject* instead of PyObject*. ........ r58330 | neal.norwitz | 2007-10-04 20:41:19 -0700 (Thu, 04 Oct 2007) | 2 lines Fix Coverity #158: Check the correct variable. ........ r58332 | neal.norwitz | 2007-10-04 22:01:38 -0700 (Thu, 04 Oct 2007) | 7 lines Fix Coverity #159. This code was broken if save() returned a negative number since i contained a boolean value and then we compared i < 0 which should never be true. Will backport (assuming it's necessary) ........ r58334 | neal.norwitz | 2007-10-04 22:29:17 -0700 (Thu, 04 Oct 2007) | 1 line Add a note about fixing some more warnings found by Coverity. ........ r58338 | raymond.hettinger | 2007-10-05 12:07:31 -0700 (Fri, 05 Oct 2007) | 1 line Restore BEGIN/END THREADS macros which were squashed in the previous checkin ........ r58343 | gregory.p.smith | 2007-10-06 00:48:10 -0700 (Sat, 06 Oct 2007) | 3 lines Stab in the dark attempt to fix the test_bsddb3 failure on sparc and S-390 ubuntu buildbots. ........ r58344 | gregory.p.smith | 2007-10-06 00:51:59 -0700 (Sat, 06 Oct 2007) | 2 lines Allows BerkeleyDB 4.6.x >= 4.6.21 for the bsddb module. ........ r58348 | gregory.p.smith | 2007-10-06 08:47:37 -0700 (Sat, 06 Oct 2007) | 3 lines Use the host the author likely meant in the first place. pop.gmail.com is reliable. gmail.org is someones personal domain. ........ r58351 | neal.norwitz | 2007-10-06 12:16:28 -0700 (Sat, 06 Oct 2007) | 3 lines Ensure that this test will pass even if another test left an unwritable TESTFN. Also use the safe unlink in test_support instead of rolling our own here. ........ r58368 | georg.brandl | 2007-10-08 00:50:24 -0700 (Mon, 08 Oct 2007) | 3 lines #1123: fix the docs for the str.split(None, sep) case. Also expand a few other methods' docs, which had more info in the deprecated string module docs. ........ r58369 | georg.brandl | 2007-10-08 01:06:05 -0700 (Mon, 08 Oct 2007) | 2 lines Update docstring of sched, also remove an unused assignment. ........ r58370 | raymond.hettinger | 2007-10-08 02:14:28 -0700 (Mon, 08 Oct 2007) | 5 lines Add comments to NamedTuple code. Let the field spec be either a string or a non-string sequence (suggested by Martin Blais with use cases). Improve the error message in the case of a SyntaxError (caused by a duplicate field name). ........ r58371 | raymond.hettinger | 2007-10-08 02:56:29 -0700 (Mon, 08 Oct 2007) | 1 line Missed a line in the docs ........ r58372 | raymond.hettinger | 2007-10-08 03:11:51 -0700 (Mon, 08 Oct 2007) | 1 line Better variable names ........ r58376 | georg.brandl | 2007-10-08 07:12:47 -0700 (Mon, 08 Oct 2007) | 3 lines #1199: docs for tp_as_{number,sequence,mapping}, by Amaury Forgeot d'Arc. No need to merge this to py3k! ........ r58380 | raymond.hettinger | 2007-10-08 14:26:58 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58381 | andrew.kuchling | 2007-10-08 16:23:03 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58382 | raymond.hettinger | 2007-10-08 18:36:23 -0700 (Mon, 08 Oct 2007) | 1 line Make the error messages more specific ........ r58384 | gregory.p.smith | 2007-10-08 23:02:21 -0700 (Mon, 08 Oct 2007) | 10 lines Splits Modules/_bsddb.c up into bsddb.h and _bsddb.c and adds a C API object available as bsddb.db.api. This is based on the patch submitted by Duncan Grisby here: http://sourceforge.net/tracker/index.php?func=detail&aid=1551895&group_id=13900&atid=313900 See this thread for additional info: http://sourceforge.net/mailarchive/forum.php?thread_name=E1GAVDK-0002rk-Iw%40apasphere.com&forum_name=pybsddb-users It also cleans up the code a little by removing some ifdef/endifs for python prior to 2.1 and for unsupported Berkeley DB <= 3.2. ........ r58385 | gregory.p.smith | 2007-10-08 23:50:43 -0700 (Mon, 08 Oct 2007) | 5 lines Fix a double free when positioning a database cursor to a non-existant string key (and probably a few other situations with string keys). This was reported with a patch as pybsddb sourceforge bug 1708868 by jjjhhhlll at gmail. ........ r58386 | gregory.p.smith | 2007-10-09 00:19:11 -0700 (Tue, 09 Oct 2007) | 3 lines Use the highest cPickle protocol in bsddb.dbshelve. This comes from sourceforge pybsddb patch 1551443 by w_barnes. ........ r58394 | gregory.p.smith | 2007-10-09 11:26:02 -0700 (Tue, 09 Oct 2007) | 2 lines remove another sleepycat reference ........ r58396 | kurt.kaiser | 2007-10-09 12:31:30 -0700 (Tue, 09 Oct 2007) | 3 lines Allow interrupt only when executing user code in subprocess Patch 1225 Tal Einat modified from IDLE-Spoon. ........ r58399 | brett.cannon | 2007-10-09 17:07:50 -0700 (Tue, 09 Oct 2007) | 5 lines Remove file-level typedefs that were inconsistently used throughout the file. Just move over to the public API names. Closes issue1238. ........ r58401 | raymond.hettinger | 2007-10-09 17:26:46 -0700 (Tue, 09 Oct 2007) | 1 line Accept Jim Jewett's api suggestion to use None instead of -1 to indicate unbounded deques. ........ r58403 | kurt.kaiser | 2007-10-09 17:55:40 -0700 (Tue, 09 Oct 2007) | 2 lines Allow cursor color change w/o restart. Patch 1725576 Tal Einat. ........ r58404 | kurt.kaiser | 2007-10-09 18:06:47 -0700 (Tue, 09 Oct 2007) | 2 lines show paste if > 80 columns. Patch 1659326 Tal Einat. ........ r58415 | thomas.heller | 2007-10-11 12:51:32 -0700 (Thu, 11 Oct 2007) | 5 lines On OS X, use os.uname() instead of gestalt.sysv(...) to get the operating system version. This allows to use ctypes when Python was configured with --disable-toolbox-glue. ........ r58419 | neal.norwitz | 2007-10-11 20:01:01 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warning about not being able to create an existing directory. ........ r58420 | neal.norwitz | 2007-10-11 20:01:30 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warnings on a bunch of platforms by using a proper prototype. ........ r58421 | neal.norwitz | 2007-10-11 20:01:54 -0700 (Thu, 11 Oct 2007) | 4 lines Get rid of compiler warning about retval being used (returned) without being initialized. (gcc warning and Coverity 202) ........ r58422 | neal.norwitz | 2007-10-11 20:03:23 -0700 (Thu, 11 Oct 2007) | 1 line Fix Coverity 168: Close the file before returning (exiting). ........ r58423 | neal.norwitz | 2007-10-11 20:04:18 -0700 (Thu, 11 Oct 2007) | 4 lines Fix Coverity 180: Don't overallocate. We don't need structs, but pointers. Also fix a memory leak. ........ r58424 | neal.norwitz | 2007-10-11 20:05:19 -0700 (Thu, 11 Oct 2007) | 5 lines Fix Coverity 185-186: If the passed in FILE is NULL, uninitialized memory would be accessed. Will backport. ........ r58425 | neal.norwitz | 2007-10-11 20:52:34 -0700 (Thu, 11 Oct 2007) | 1 line Get this module to compile with bsddb versions prior to 4.3 ........ r58430 | martin.v.loewis | 2007-10-12 01:56:52 -0700 (Fri, 12 Oct 2007) | 3 lines Bug #1216: Restore support for Visual Studio 2002. Will backport to 2.5. ........ r58433 | raymond.hettinger | 2007-10-12 10:53:11 -0700 (Fri, 12 Oct 2007) | 1 line Fix test of count.__repr__() to ignore the 'L' if the count is a long ........ r58434 | gregory.p.smith | 2007-10-12 11:44:06 -0700 (Fri, 12 Oct 2007) | 4 lines Fixes http://bugs.python.org/issue1233 - bsddb.dbshelve.DBShelf.append was useless due to inverted logic. Also adds a test case for RECNO dbs to test_dbshelve. ........ r58445 | georg.brandl | 2007-10-13 06:20:03 -0700 (Sat, 13 Oct 2007) | 2 lines Fix email example. ........ r58450 | gregory.p.smith | 2007-10-13 16:02:05 -0700 (Sat, 13 Oct 2007) | 2 lines Fix an uncollectable reference leak in bsddb.db.DBShelf.append ........ r58453 | neal.norwitz | 2007-10-13 17:18:40 -0700 (Sat, 13 Oct 2007) | 8 lines Let the O/S supply a port if none of the default ports can be used. This should make the tests more robust at the expense of allowing tests to be sloppier by not requiring them to cleanup after themselves. (It will legitamitely help when running two test suites simultaneously or if another process is already using one of the predefined ports.) Also simplifies (slightLy) the exception handling elsewhere. ........ r58459 | neal.norwitz | 2007-10-14 11:30:21 -0700 (Sun, 14 Oct 2007) | 2 lines Don't raise a string exception, they don't work anymore. ........ r58460 | neal.norwitz | 2007-10-14 11:40:37 -0700 (Sun, 14 Oct 2007) | 1 line Use unittest for assertions ........ r58468 | armin.rigo | 2007-10-15 00:48:35 -0700 (Mon, 15 Oct 2007) | 2 lines test_bigbits was not testing what it seemed to. ........ r58471 | guido.van.rossum | 2007-10-15 08:54:11 -0700 (Mon, 15 Oct 2007) | 3 lines Change a PyErr_Print() into a PyErr_Clear(), per discussion in issue 1031213. ........ r58500 | raymond.hettinger | 2007-10-16 12:18:30 -0700 (Tue, 16 Oct 2007) | 1 line Improve error messages ........ r58506 | raymond.hettinger | 2007-10-16 14:28:32 -0700 (Tue, 16 Oct 2007) | 1 line More docs, error messages, and tests ........ r58507 | andrew.kuchling | 2007-10-16 15:58:03 -0700 (Tue, 16 Oct 2007) | 1 line Add items ........ r58508 | brett.cannon | 2007-10-16 16:24:06 -0700 (Tue, 16 Oct 2007) | 3 lines Remove ``:const:`` notation on None in parameter list. Since the markup is not rendered for parameters it just showed up as ``:const:`None` `` in the output. ........ r58509 | brett.cannon | 2007-10-16 16:26:45 -0700 (Tue, 16 Oct 2007) | 3 lines Re-order some functions whose parameters differ between PyObject and const char * so that they are next to each other. ........ r58522 | armin.rigo | 2007-10-17 11:46:37 -0700 (Wed, 17 Oct 2007) | 5 lines Fix the overflow checking of list_repeat. Introduce overflow checking into list_inplace_repeat. Backport candidate, possibly. ........ r58530 | facundo.batista | 2007-10-17 20:16:03 -0700 (Wed, 17 Oct 2007) | 7 lines Issue #1580738. When HTTPConnection reads the whole stream with read(), it closes itself. When the stream is read in several calls to read(n), it should behave in the same way if HTTPConnection knows where the end of the stream is (through self.length). Added a test case for this behaviour. ........ r58531 | facundo.batista | 2007-10-17 20:44:48 -0700 (Wed, 17 Oct 2007) | 3 lines Issue 1289, just a typo. ........ r58532 | gregory.p.smith | 2007-10-18 00:56:54 -0700 (Thu, 18 Oct 2007) | 4 lines cleanup test_dbtables to use mkdtemp. cleanup dbtables to pass txn as a keyword argument whenever possible to avoid bugs and confusion. (dbtables.py line 447 self.db.get using txn as a non-keyword was an actual bug due to this) ........ r58533 | gregory.p.smith | 2007-10-18 01:34:20 -0700 (Thu, 18 Oct 2007) | 4 lines Fix a weird bug in dbtables: if it chose a random rowid string that contained NULL bytes it would cause the database all sorts of problems in the future leading to very strange random failures and corrupt dbtables.bsdTableDb dbs. ........ r58534 | gregory.p.smith | 2007-10-18 09:32:02 -0700 (Thu, 18 Oct 2007) | 3 lines A cleaner fix than the one committed last night. Generate random rowids that do not contain null bytes. ........ r58537 | gregory.p.smith | 2007-10-18 10:17:57 -0700 (Thu, 18 Oct 2007) | 2 lines mention bsddb fixes. ........ r58538 | raymond.hettinger | 2007-10-18 14:13:06 -0700 (Thu, 18 Oct 2007) | 1 line Remove useless warning ........ r58539 | gregory.p.smith | 2007-10-19 00:31:20 -0700 (Fri, 19 Oct 2007) | 2 lines squelch the warning that this test is supposed to trigger. ........ r58542 | georg.brandl | 2007-10-19 05:32:39 -0700 (Fri, 19 Oct 2007) | 2 lines Clarify wording for apply(). ........ r58544 | mark.summerfield | 2007-10-19 05:48:17 -0700 (Fri, 19 Oct 2007) | 3 lines Added a cross-ref to each other. ........ r58545 | georg.brandl | 2007-10-19 10:38:49 -0700 (Fri, 19 Oct 2007) | 2 lines #1284: "S" means "seen", not unread. ........ r58548 | thomas.heller | 2007-10-19 11:11:41 -0700 (Fri, 19 Oct 2007) | 4 lines Fix ctypes on 32-bit systems when Python is configured --with-system-ffi. See also https://bugs.launchpad.net/bugs/72505. Ported from release25-maint branch. ........ r58550 | facundo.batista | 2007-10-19 12:25:57 -0700 (Fri, 19 Oct 2007) | 8 lines The constructor from tuple was way too permissive: it allowed bad coefficient numbers, floats in the sign, and other details that generated directly the wrong number in the best case, or triggered misfunctionality in the alorithms. Test cases added for these issues. Thanks Mark Dickinson. ........ r58559 | georg.brandl | 2007-10-20 06:22:53 -0700 (Sat, 20 Oct 2007) | 2 lines Fix code being interpreted as a target. ........ r58561 | georg.brandl | 2007-10-20 06:36:24 -0700 (Sat, 20 Oct 2007) | 2 lines Document new "cmdoption" directive. ........ r58562 | georg.brandl | 2007-10-20 08:21:22 -0700 (Sat, 20 Oct 2007) | 2 lines Make a path more Unix-standardy. ........ r58564 | georg.brandl | 2007-10-20 10:51:39 -0700 (Sat, 20 Oct 2007) | 2 lines Document new directive "envvar". ........ r58567 | georg.brandl | 2007-10-20 11:08:14 -0700 (Sat, 20 Oct 2007) | 6 lines * Add new toplevel chapter, "Using Python." (how to install, configure and setup python on different platforms -- at least in theory.) * Move the Python on Mac docs in that chapter. * Add a new chapter about the command line invocation, by stargaming. ........ r58568 | georg.brandl | 2007-10-20 11:33:20 -0700 (Sat, 20 Oct 2007) | 2 lines Change title, for now. ........ r58569 | georg.brandl | 2007-10-20 11:39:25 -0700 (Sat, 20 Oct 2007) | 2 lines Add entry to ACKS. ........ r58570 | georg.brandl | 2007-10-20 12:05:45 -0700 (Sat, 20 Oct 2007) | 2 lines Clarify -E docs. ........ r58571 | georg.brandl | 2007-10-20 12:08:36 -0700 (Sat, 20 Oct 2007) | 2 lines Even more clarification. ........ r58572 | andrew.kuchling | 2007-10-20 12:25:37 -0700 (Sat, 20 Oct 2007) | 1 line Fix protocol name ........ r58573 | andrew.kuchling | 2007-10-20 12:35:18 -0700 (Sat, 20 Oct 2007) | 1 line Various items ........ r58574 | andrew.kuchling | 2007-10-20 12:39:35 -0700 (Sat, 20 Oct 2007) | 1 line Use correct header line ........ r58576 | armin.rigo | 2007-10-21 02:14:15 -0700 (Sun, 21 Oct 2007) | 3 lines Add a crasher for the long-standing issue with closing a file while another thread uses it. ........ r58577 | georg.brandl | 2007-10-21 03:01:56 -0700 (Sun, 21 Oct 2007) | 2 lines Remove duplicate crasher. ........ r58578 | georg.brandl | 2007-10-21 03:24:20 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "byte code" to "bytecode". Also sprinkle :term: markup for it. ........ r58579 | georg.brandl | 2007-10-21 03:32:54 -0700 (Sun, 21 Oct 2007) | 2 lines Add markup to new function descriptions. ........ r58580 | georg.brandl | 2007-10-21 03:45:46 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for descriptors. ........ r58581 | georg.brandl | 2007-10-21 03:46:24 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "file-descriptor" to "file descriptor". ........ r58582 | georg.brandl | 2007-10-21 03:52:38 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term: for generators. ........ r58583 | georg.brandl | 2007-10-21 05:10:28 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for iterator. ........ r58584 | georg.brandl | 2007-10-21 05:15:05 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for "new-style class". ........ r58588 | neal.norwitz | 2007-10-21 21:47:54 -0700 (Sun, 21 Oct 2007) | 1 line Add Chris Monson so he can edit PEPs. ........ r58594 | guido.van.rossum | 2007-10-22 09:27:19 -0700 (Mon, 22 Oct 2007) | 4 lines Issue #1307, patch by Derek Shockey. When "MAIL" is received without args, an exception happens instead of sending a 501 syntax error response. ........ r58598 | travis.oliphant | 2007-10-22 19:40:56 -0700 (Mon, 22 Oct 2007) | 1 line Add phuang patch from Issue 708374 which adds offset parameter to mmap module. ........ r58601 | neal.norwitz | 2007-10-22 22:44:27 -0700 (Mon, 22 Oct 2007) | 2 lines Bug #1313, fix typo (wrong variable name) in example. ........ r58609 | georg.brandl | 2007-10-23 11:21:35 -0700 (Tue, 23 Oct 2007) | 2 lines Update Pygments version from externals. ........ r58618 | guido.van.rossum | 2007-10-23 12:25:41 -0700 (Tue, 23 Oct 2007) | 3 lines Issue 1307 by Derek Shockey, fox the same bug for RCPT. Neal: please backport! ........ r58620 | raymond.hettinger | 2007-10-23 13:37:41 -0700 (Tue, 23 Oct 2007) | 1 line Shorter name for namedtuple() ........ r58621 | andrew.kuchling | 2007-10-23 13:55:47 -0700 (Tue, 23 Oct 2007) | 1 line Update name ........ r58622 | raymond.hettinger | 2007-10-23 14:23:07 -0700 (Tue, 23 Oct 2007) | 1 line Fixup news entry ........ r58623 | raymond.hettinger | 2007-10-23 18:28:33 -0700 (Tue, 23 Oct 2007) | 1 line Optimize sum() for integer and float inputs. ........ r58624 | raymond.hettinger | 2007-10-23 19:05:51 -0700 (Tue, 23 Oct 2007) | 1 line Fixup error return and add support for intermixed ints and floats/ ........ r58628 | vinay.sajip | 2007-10-24 03:47:06 -0700 (Wed, 24 Oct 2007) | 1 line Bug #1321: Fixed logic error in TimedRotatingFileHandler.__init__() ........ r58641 | facundo.batista | 2007-10-24 12:11:08 -0700 (Wed, 24 Oct 2007) | 4 lines Issue 1290. CharacterData.__repr__ was constructing a string in response that keeped having a non-ascii character. ........ r58643 | thomas.heller | 2007-10-24 12:50:45 -0700 (Wed, 24 Oct 2007) | 1 line Added unittest for calling a function with paramflags (backport from py3k branch). ........ r58645 | matthias.klose | 2007-10-24 13:00:44 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*. ........ r58651 | georg.brandl | 2007-10-24 14:40:38 -0700 (Wed, 24 Oct 2007) | 2 lines Bug #1287: make os.environ.pop() work as expected. ........ r58652 | raymond.hettinger | 2007-10-24 19:26:58 -0700 (Wed, 24 Oct 2007) | 1 line Missing DECREFs ........ r58653 | matthias.klose | 2007-10-24 23:37:24 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*, pass --with-system-ffi to CONFIG_ARGS ........ r58655 | thomas.heller | 2007-10-25 12:47:32 -0700 (Thu, 25 Oct 2007) | 2 lines ffi_type_longdouble may be already #defined. See issue 1324. ........ r58656 | kurt.kaiser | 2007-10-25 15:43:45 -0700 (Thu, 25 Oct 2007) | 3 lines Correct an ancient bug in an unused path by removing that path: register() is now idempotent. ........ r58660 | kurt.kaiser | 2007-10-25 17:10:09 -0700 (Thu, 25 Oct 2007) | 4 lines 1. Add comments to provide top-level documentation. 2. Refactor to use more descriptive names. 3. Enhance tests in main(). ........ r58675 | georg.brandl | 2007-10-26 11:30:41 -0700 (Fri, 26 Oct 2007) | 2 lines Fix new pop() method on os.environ on ignorecase-platforms. ........ r58696 | neal.norwitz | 2007-10-27 15:32:21 -0700 (Sat, 27 Oct 2007) | 1 line Update URL for Pygments. 0.8.1 is no longer available ........ r58697 | hyeshik.chang | 2007-10-28 04:19:02 -0700 (Sun, 28 Oct 2007) | 3 lines - Add support for FreeBSD 8 which is recently forked from FreeBSD 7. - Regenerate IN module for most recent maintenance tree of FreeBSD 6 and 7. ........ r58698 | hyeshik.chang | 2007-10-28 05:38:09 -0700 (Sun, 28 Oct 2007) | 2 lines Enable platform-specific tweaks for FreeBSD 8 (exactly same to FreeBSD 7's yet) ........ r58700 | kurt.kaiser | 2007-10-28 12:03:59 -0700 (Sun, 28 Oct 2007) | 2 lines Add confirmation dialog before printing. Patch 1717170 Tal Einat. ........ r58706 | guido.van.rossum | 2007-10-29 13:52:45 -0700 (Mon, 29 Oct 2007) | 3 lines Patch 1353 by Jacob Winther. Add mp4 mapping to mimetypes.py. ........ r58709 | guido.van.rossum | 2007-10-29 15:15:05 -0700 (Mon, 29 Oct 2007) | 6 lines Backport fixes for the code that decodes octal escapes (and for PyString also hex escapes) -- this was reaching beyond the end of the input string buffer, even though it is not supposed to be \0-terminated. This has no visible effect but is clearly the correct thing to do. (In 3.0 it had a visible effect after removing ob_sstate from PyString.) ........ r58710 | kurt.kaiser | 2007-10-29 19:38:54 -0700 (Mon, 29 Oct 2007) | 7 lines check in Tal Einat's update to tabpage.py Patch 1612746 M configDialog.py M NEWS.txt AM tabbedpages.py ........ r58715 | georg.brandl | 2007-10-30 10:51:18 -0700 (Tue, 30 Oct 2007) | 2 lines Use correct markup. ........ r58716 | georg.brandl | 2007-10-30 10:57:12 -0700 (Tue, 30 Oct 2007) | 2 lines Make example about hiding None return values at the prompt clearer. ........ r58728 | neal.norwitz | 2007-10-30 23:33:20 -0700 (Tue, 30 Oct 2007) | 1 line Fix some compiler warnings for signed comparisons on Unix and Windows. ........ r58731 | martin.v.loewis | 2007-10-31 10:19:33 -0700 (Wed, 31 Oct 2007) | 2 lines Adding Christian Heimes. ........ r58737 | raymond.hettinger | 2007-10-31 14:57:58 -0700 (Wed, 31 Oct 2007) | 1 line Clarify the reasons why pickle is almost always better than marshal ........ r58739 | raymond.hettinger | 2007-10-31 15:15:49 -0700 (Wed, 31 Oct 2007) | 1 line Sets are marshalable. ........
2007-11-01 17:32:30 -03:00
* if the number starts with ``0b``, it is parsed as a binary number
2007-08-15 11:28:22 -03:00
* otherwise, the number is parsed as a decimal number
The conversion is done by calling :func:`int` with the appropriate base (2, 8,
10, or 16). If this fails, so will :mod:`optparse`, although with a more useful
error message.
2007-08-15 11:28:22 -03:00
``"float"`` and ``"complex"`` option arguments are converted directly with
:func:`float` and :func:`complex`, with similar error-handling.
2007-08-15 11:28:22 -03:00
``"choice"`` options are a subtype of ``"string"`` options. The
2010-10-06 07:26:05 -03:00
:attr:`~Option.choices` option attribute (a sequence of strings) defines the
set of allowed option arguments. :func:`optparse.check_choice` compares
user-supplied option arguments against this master list and raises
:exc:`OptionValueError` if an invalid string is given.
2007-08-15 11:28:22 -03:00
.. _optparse-parsing-arguments:
Parsing arguments
^^^^^^^^^^^^^^^^^
The whole point of creating and populating an OptionParser is to call its
:meth:`parse_args` method::
(options, args) = parser.parse_args(args=None, values=None)
where the input parameters are
``args``
the list of arguments to process (default: ``sys.argv[1:]``)
``values``
an :class:`optparse.Values` object to store option arguments in (default: a
new instance of :class:`Values`) -- if you give an existing object, the
option defaults will not be initialized on it
2007-08-15 11:28:22 -03:00
and the return values are
``options``
Merged revisions 74542,74544-74548,74550,74554-74555,74578,74588,74590,74603,74616-74618,74621 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74542 | georg.brandl | 2009-08-23 23:28:56 +0200 (So, 23 Aug 2009) | 1 line Restore alphabetic order. ........ r74544 | georg.brandl | 2009-08-24 19:12:30 +0200 (Mo, 24 Aug 2009) | 1 line #6775: fix python.org URLs in README. ........ r74545 | georg.brandl | 2009-08-24 19:14:29 +0200 (Mo, 24 Aug 2009) | 1 line #6772: mention utf-8 as utf8 alias. ........ r74546 | georg.brandl | 2009-08-24 19:20:40 +0200 (Mo, 24 Aug 2009) | 1 line #6725: spell "namespace" consistently. ........ r74547 | georg.brandl | 2009-08-24 19:22:05 +0200 (Mo, 24 Aug 2009) | 1 line #6718: fix example. ........ r74548 | georg.brandl | 2009-08-24 19:24:27 +0200 (Mo, 24 Aug 2009) | 1 line #6677: mention "deleting" as an alias for removing files. ........ r74550 | georg.brandl | 2009-08-24 19:48:40 +0200 (Mo, 24 Aug 2009) | 1 line #6677: note that rmdir only removes empty directories. ........ r74554 | georg.brandl | 2009-08-27 20:59:02 +0200 (Do, 27 Aug 2009) | 1 line Typo fix. ........ r74555 | georg.brandl | 2009-08-27 21:02:43 +0200 (Do, 27 Aug 2009) | 1 line #6787: reference fix. ........ r74578 | tarek.ziade | 2009-08-29 15:33:21 +0200 (Sa, 29 Aug 2009) | 1 line fixed #6801: symmetric_difference_update also accepts pipe ........ r74588 | georg.brandl | 2009-08-30 10:35:01 +0200 (So, 30 Aug 2009) | 1 line #6803: fix old name. ........ r74590 | georg.brandl | 2009-08-30 13:51:53 +0200 (So, 30 Aug 2009) | 1 line #6801: fix copy-paste oversight. ........ r74603 | georg.brandl | 2009-08-31 08:38:29 +0200 (Mo, 31 Aug 2009) | 1 line other -> others where multiple arguments are accepted. ........ r74616 | georg.brandl | 2009-09-01 09:46:26 +0200 (Di, 01 Sep 2009) | 1 line #6808: clarification. ........ r74617 | georg.brandl | 2009-09-01 09:53:37 +0200 (Di, 01 Sep 2009) | 1 line #6765: hint that log(x, base) is not very sophisticated. ........ r74618 | georg.brandl | 2009-09-01 10:00:47 +0200 (Di, 01 Sep 2009) | 1 line #6810: add a link to the section about frame objects instead of just a description where to find it. ........ r74621 | georg.brandl | 2009-09-01 10:06:03 +0200 (Di, 01 Sep 2009) | 1 line #6638: fix wrong parameter name and markup a class. ........
2009-09-01 05:11:14 -03:00
the same object that was passed in as ``values``, or the optparse.Values
2007-08-15 11:28:22 -03:00
instance created by :mod:`optparse`
``args``
the leftover positional arguments after all options have been processed
The most common usage is to supply neither keyword argument. If you supply
``values``, it will be modified with repeated :func:`setattr` calls (roughly one
2007-08-15 11:28:22 -03:00
for every option argument stored to an option destination) and returned by
:meth:`parse_args`.
If :meth:`parse_args` encounters any errors in the argument list, it calls the
OptionParser's :meth:`error` method with an appropriate end-user error message.
This ultimately terminates your process with an exit status of 2 (the
traditional Unix exit status for command-line errors).
.. _optparse-querying-manipulating-option-parser:
Querying and manipulating your option parser
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default behavior of the option parser can be customized slightly, and you
can also poke around your option parser and see what's there. OptionParser
provides several methods to help you out:
.. method:: OptionParser.disable_interspersed_args()
Set parsing to stop on the first non-option. For example, if ``-a`` and
``-b`` are both simple options that take no arguments, :mod:`optparse`
normally accepts this syntax::
prog -a arg1 -b arg2
and treats it as equivalent to ::
prog -a -b arg1 arg2
To disable this feature, call :meth:`disable_interspersed_args`. This
restores traditional Unix syntax, where option parsing stops with the first
non-option argument.
Use this if you have a command processor which runs another command which has
options of its own and you want to make sure these options don't get
confused. For example, each command might have a different set of options.
.. method:: OptionParser.enable_interspersed_args()
Set parsing to not stop on the first non-option, allowing interspersing
switches with command arguments. This is the default behavior.
.. method:: OptionParser.get_option(opt_str)
Returns the Option instance with the option string *opt_str*, or ``None`` if
2007-08-15 11:28:22 -03:00
no options have that option string.
.. method:: OptionParser.has_option(opt_str)
Return true if the OptionParser has an option with option string *opt_str*
(e.g., ``-q`` or ``--verbose``).
Devil merge! Merged revisions 66561,66564,66580,66610,66614,66618,66624-66625,66628-66629,66643,66645,66660-66665 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r66561 | benjamin.peterson | 2008-09-22 17:13:29 -0500 (Mon, 22 Sep 2008) | 1 line clean up docs for platform's linux_distribution and dist functions ........ r66564 | benjamin.peterson | 2008-09-23 08:32:46 -0500 (Tue, 23 Sep 2008) | 1 line mention how to override boolean evaluation ........ r66580 | georg.brandl | 2008-09-24 04:47:55 -0500 (Wed, 24 Sep 2008) | 2 lines Indentation normalization. ........ r66610 | andrew.kuchling | 2008-09-24 12:27:55 -0500 (Wed, 24 Sep 2008) | 1 line Improve wording ........ r66614 | benjamin.peterson | 2008-09-24 17:11:59 -0500 (Wed, 24 Sep 2008) | 4 lines #3950 fix missing scale factors in turtle.py reviewers: Georg, Benjamin ........ r66618 | benjamin.peterson | 2008-09-25 15:35:45 -0500 (Thu, 25 Sep 2008) | 1 line add a NEWs entry for r66614 ........ r66624 | raymond.hettinger | 2008-09-25 18:31:52 -0500 (Thu, 25 Sep 2008) | 1 line Fix namedtuple bug reported by Glenn Linderman. Template did not form correctly if the field names were input in Unicode. ........ r66625 | benjamin.peterson | 2008-09-25 21:58:36 -0500 (Thu, 25 Sep 2008) | 1 line add the beginnings of a C-API 2 -> 3 porting guide ........ r66628 | benjamin.peterson | 2008-09-26 15:52:06 -0500 (Fri, 26 Sep 2008) | 1 line add an 'other options' section ........ r66629 | georg.brandl | 2008-09-26 16:15:21 -0500 (Fri, 26 Sep 2008) | 2 lines typos. ........ r66643 | andrew.kuchling | 2008-09-27 09:12:33 -0500 (Sat, 27 Sep 2008) | 1 line Add a last bunch of items ........ r66645 | benjamin.peterson | 2008-09-27 11:23:55 -0500 (Sat, 27 Sep 2008) | 1 line 2to3's api should be considered unstable ........ r66660 | andrew.kuchling | 2008-09-27 17:54:08 -0500 (Sat, 27 Sep 2008) | 1 line #3510: future-proof text ........ r66661 | benjamin.peterson | 2008-09-27 18:28:43 -0500 (Sat, 27 Sep 2008) | 1 line clarify a few things ........ r66662 | andrew.kuchling | 2008-09-27 19:15:27 -0500 (Sat, 27 Sep 2008) | 1 line #1579477: mention necessity to flush output before exec'ing ........ r66663 | andrew.kuchling | 2008-09-27 20:08:47 -0500 (Sat, 27 Sep 2008) | 1 line #1415508: Document two functions ........ r66664 | benjamin.peterson | 2008-09-27 20:51:36 -0500 (Sat, 27 Sep 2008) | 1 line better grammar ........ r66665 | benjamin.peterson | 2008-09-27 20:53:29 -0500 (Sat, 27 Sep 2008) | 1 line note the 2to3 -d could be useful for other refactoring ........
2008-09-27 23:06:32 -03:00
.. method:: OptionParser.remove_option(opt_str)
If the :class:`OptionParser` has an option corresponding to *opt_str*, that
option is removed. If that option provided any other option strings, all of
those option strings become invalid. If *opt_str* does not occur in any
option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
2007-08-15 11:28:22 -03:00
.. _optparse-conflicts-between-options:
Conflicts between options
^^^^^^^^^^^^^^^^^^^^^^^^^
If you're not careful, it's easy to define options with conflicting option
strings::
parser.add_option("-n", "--dry-run", ...)
...
2007-08-15 11:28:22 -03:00
parser.add_option("-n", "--noisy", ...)
(This is particularly true if you've defined your own OptionParser subclass with
some standard options.)
Every time you add an option, :mod:`optparse` checks for conflicts with existing
options. If it finds any, it invokes the current conflict-handling mechanism.
You can set the conflict-handling mechanism either in the constructor::
parser = OptionParser(..., conflict_handler=handler)
or with a separate call::
parser.set_conflict_handler(handler)
The available conflict handlers are:
``"error"`` (default)
assume option conflicts are a programming error and raise
:exc:`OptionConflictError`
2007-08-15 11:28:22 -03:00
``"resolve"``
2007-08-15 11:28:22 -03:00
resolve option conflicts intelligently (see below)
As an example, let's define an :class:`OptionParser` that resolves conflicts
2007-08-15 11:28:22 -03:00
intelligently and add conflicting options to it::
parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
At this point, :mod:`optparse` detects that a previously-added option is already
using the ``-n`` option string. Since ``conflict_handler`` is ``"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
2007-08-15 11:28:22 -03:00
that option. If the user asks for help, the help message will reflect that::
Options:
2007-08-15 11:28:22 -03:00
--dry-run do no harm
...
2007-08-15 11:28:22 -03:00
-n, --noisy be noisy
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, :mod:`optparse` removes that option completely,
so it doesn't show up in help text or anywhere else. Carrying on with our
existing OptionParser::
parser.add_option("--dry-run", ..., help="new dry-run option")
At this point, the original ``-n``/``--dry-run`` option is no longer
2007-08-15 11:28:22 -03:00
accessible, so :mod:`optparse` removes it, leaving this help text::
Options:
...
2007-08-15 11:28:22 -03:00
-n, --noisy be noisy
--dry-run new dry-run option
.. _optparse-cleanup:
Cleanup
^^^^^^^
OptionParser instances have several cyclic references. This should not be a
problem for Python's garbage collector, but you may wish to break the cyclic
references explicitly by calling :meth:`~OptionParser.destroy` on your
OptionParser once you are done with it. This is particularly useful in
long-running applications where large object graphs are reachable from your
OptionParser.
2007-08-15 11:28:22 -03:00
.. _optparse-other-methods:
Other methods
^^^^^^^^^^^^^
OptionParser supports several other public methods:
.. method:: OptionParser.set_usage(usage)
2007-08-15 11:28:22 -03:00
Set the usage string according to the rules described above for the ``usage``
constructor keyword argument. Passing ``None`` sets the default usage
string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
2007-08-15 11:28:22 -03:00
.. method:: OptionParser.print_usage(file=None)
Print the usage message for the current program (``self.usage``) to *file*
(default stdout). Any occurrence of the string ``%prog`` in ``self.usage``
is replaced with the name of the current program. Does nothing if
``self.usage`` is empty or not defined.
.. method:: OptionParser.get_usage()
Same as :meth:`print_usage` but returns the usage string instead of
printing it.
.. method:: OptionParser.set_defaults(dest=value, ...)
2007-08-15 11:28:22 -03:00
Set default values for several option destinations at once. Using
:meth:`set_defaults` is the preferred way to set default values for options,
since multiple options can share the same destination. For example, if
several "mode" options all set the same destination, any one of them can set
the default, and the last one wins::
2007-08-15 11:28:22 -03:00
parser.add_option("--advanced", action="store_const",
dest="mode", const="advanced",
default="novice") # overridden below
parser.add_option("--novice", action="store_const",
dest="mode", const="novice",
default="advanced") # overrides above setting
2007-08-15 11:28:22 -03:00
To avoid this confusion, use :meth:`set_defaults`::
2007-08-15 11:28:22 -03:00
parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
dest="mode", const="novice")
2007-08-15 11:28:22 -03:00
.. _optparse-option-callbacks:
Option Callbacks
----------------
When :mod:`optparse`'s built-in actions and types aren't quite enough for your
needs, you have two choices: extend :mod:`optparse` or define a callback option.
Extending :mod:`optparse` is more general, but overkill for a lot of simple
cases. Quite often a simple callback is all you need.
There are two steps to defining a callback option:
* define the option itself using the ``"callback"`` action
2007-08-15 11:28:22 -03:00
* write the callback; this is a function (or method) that takes at least four
arguments, as described below
.. _optparse-defining-callback-option:
Defining a callback option
^^^^^^^^^^^^^^^^^^^^^^^^^^
As always, the easiest way to define a callback option is by using the
:meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
only option attribute you must specify is ``callback``, the function to call::
2007-08-15 11:28:22 -03:00
parser.add_option("-c", action="callback", callback=my_callback)
``callback`` is a function (or other callable object), so you must have already
defined ``my_callback()`` when you create this callback option. In this simple
case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
2007-08-15 11:28:22 -03:00
which usually means that the option takes no arguments---the mere presence of
``-c`` on the command-line is all it needs to know. In some
2007-08-15 11:28:22 -03:00
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 section.
:mod:`optparse` always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via
:attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
minimal callback function signature is::
2007-08-15 11:28:22 -03:00
def my_callback(option, opt, value, parser):
The four arguments to a callback are described below.
There are several other option attributes that you can supply when you define a
callback option:
:attr:`~Option.type`
has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
instructs :mod:`optparse` to consume one argument and convert it to
:attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
though, :mod:`optparse` passes it to your callback function.
2007-08-15 11:28:22 -03:00
:attr:`~Option.nargs`
2007-08-15 11:28:22 -03:00
also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
consume :attr:`~Option.nargs` arguments, each of which must be convertible to
:attr:`~Option.type`. It then passes a tuple of converted values to your
callback.
2007-08-15 11:28:22 -03:00
:attr:`~Option.callback_args`
2007-08-15 11:28:22 -03:00
a tuple of extra positional arguments to pass to the callback
:attr:`~Option.callback_kwargs`
2007-08-15 11:28:22 -03:00
a dictionary of extra keyword arguments to pass to the callback
.. _optparse-how-callbacks-called:
How callbacks are called
^^^^^^^^^^^^^^^^^^^^^^^^
All callbacks are called as follows::
func(option, opt_str, value, parser, *args, **kwargs)
where
``option``
is the Option instance that's calling the callback
``opt_str``
is the option string seen on the command-line that's triggering the callback.
(If an abbreviated long option was used, ``opt_str`` will be the full,
canonical option string---e.g. if the user puts ``--foo`` on the
command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
``"--foobar"``.)
2007-08-15 11:28:22 -03:00
``value``
is the argument to this option seen on the command-line. :mod:`optparse` will
only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
the type implied by the option's type. If :attr:`~Option.type` for this option is
``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
2007-08-15 11:28:22 -03:00
> 1, ``value`` will be a tuple of values of the appropriate type.
``parser``
is the OptionParser instance driving the whole thing, mainly useful because
you can access some other interesting data through its instance attributes:
2007-08-15 11:28:22 -03:00
``parser.largs``
the current list of leftover arguments, ie. arguments that have been
consumed but are neither options nor option arguments. Feel free to modify
``parser.largs``, e.g. by adding more arguments to it. (This list will
become ``args``, the second return value of :meth:`parse_args`.)
2007-08-15 11:28:22 -03:00
``parser.rargs``
the current list of remaining arguments, ie. with ``opt_str`` and
``value`` (if applicable) removed, and only the arguments following them
still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
arguments.
2007-08-15 11:28:22 -03:00
``parser.values``
the object where option values are by default stored (an instance of
optparse.OptionValues). This lets callbacks use the same mechanism as the
rest of :mod:`optparse` for storing option values; you don't need to mess
around with globals or closures. You can also access or modify the
value(s) of any options already encountered on the command-line.
2007-08-15 11:28:22 -03:00
``args``
is a tuple of arbitrary positional arguments supplied via the
:attr:`~Option.callback_args` option attribute.
2007-08-15 11:28:22 -03:00
``kwargs``
is a dictionary of arbitrary keyword arguments supplied via
:attr:`~Option.callback_kwargs`.
2007-08-15 11:28:22 -03:00
.. _optparse-raising-errors-in-callback:
Raising errors in a callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The callback function should raise :exc:`OptionValueError` if there are any
problems with the option or its argument(s). :mod:`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.
2007-08-15 11:28:22 -03:00
.. _optparse-callback-example-1:
Callback example 1: trivial callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here's an example of a callback option that takes no arguments, and simply
records that the option was seen::
def record_foo_seen(option, opt_str, value, parser):
Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r69129 | benjamin.peterson | 2009-01-30 19:42:55 -0600 (Fri, 30 Jan 2009) | 1 line check the errno in bad fd cases ........ r69130 | andrew.kuchling | 2009-01-30 20:50:09 -0600 (Fri, 30 Jan 2009) | 1 line Add a section ........ r69131 | andrew.kuchling | 2009-01-30 21:26:02 -0600 (Fri, 30 Jan 2009) | 1 line Text edits and markup fixes ........ r69139 | mark.dickinson | 2009-01-31 10:44:04 -0600 (Sat, 31 Jan 2009) | 2 lines Add an extra test for long <-> float hash equivalence. ........ r69140 | benjamin.peterson | 2009-01-31 10:52:03 -0600 (Sat, 31 Jan 2009) | 1 line PyErr_BadInternalCall() raises a SystemError, not TypeError #5112 ........ r69143 | benjamin.peterson | 2009-01-31 15:00:10 -0600 (Sat, 31 Jan 2009) | 1 line I believe the intention here was to avoid a global lookup ........ r69154 | benjamin.peterson | 2009-01-31 16:33:02 -0600 (Sat, 31 Jan 2009) | 1 line fix indentation in comment ........ r69155 | david.goodger | 2009-01-31 16:53:46 -0600 (Sat, 31 Jan 2009) | 1 line markup fix ........ r69156 | gregory.p.smith | 2009-01-31 16:57:30 -0600 (Sat, 31 Jan 2009) | 4 lines - Issue #5104: The socket module now raises OverflowError when 16-bit port and protocol numbers are supplied outside the allowed 0-65536 range on bind() and getservbyport(). ........ r69157 | benjamin.peterson | 2009-01-31 17:43:25 -0600 (Sat, 31 Jan 2009) | 1 line add explanatory comment ........ r69158 | benjamin.peterson | 2009-01-31 17:54:38 -0600 (Sat, 31 Jan 2009) | 1 line more flags which only work for function blocks ........ r69159 | gregory.p.smith | 2009-01-31 18:16:01 -0600 (Sat, 31 Jan 2009) | 2 lines Update doc wording as suggested in issue4903. ........ r69169 | guilherme.polo | 2009-01-31 20:56:16 -0600 (Sat, 31 Jan 2009) | 3 lines Restore Tkinter.Tk._loadtk so this test doesn't fail for problems related to ttk. ........ r69288 | georg.brandl | 2009-02-05 04:30:57 -0600 (Thu, 05 Feb 2009) | 1 line #5153: fix typo in example. ........ r69289 | georg.brandl | 2009-02-05 04:37:07 -0600 (Thu, 05 Feb 2009) | 1 line #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. ........ r69293 | georg.brandl | 2009-02-05 04:59:28 -0600 (Thu, 05 Feb 2009) | 1 line #5059: fix example. ........ r69297 | georg.brandl | 2009-02-05 05:32:18 -0600 (Thu, 05 Feb 2009) | 1 line #5015: document PythonHome API functions. ........ r69298 | georg.brandl | 2009-02-05 05:33:21 -0600 (Thu, 05 Feb 2009) | 1 line #4827: fix callback example. ........ r69299 | georg.brandl | 2009-02-05 05:35:28 -0600 (Thu, 05 Feb 2009) | 1 line #4820: use correct module for ctypes.util. ........ r69300 | georg.brandl | 2009-02-05 05:38:23 -0600 (Thu, 05 Feb 2009) | 1 line #4563: disable alpha and roman lists, fixes wrong formatting of contributor list. ........ r69301 | georg.brandl | 2009-02-05 05:40:35 -0600 (Thu, 05 Feb 2009) | 1 line #5031: fix Thread.daemon property docs. ........ r69348 | benjamin.peterson | 2009-02-05 19:47:31 -0600 (Thu, 05 Feb 2009) | 1 line fix download link ........
2009-02-05 22:40:07 -04:00
parser.values.saw_foo = True
2007-08-15 11:28:22 -03:00
parser.add_option("--foo", action="callback", callback=record_foo_seen)
Of course, you could do that with the ``"store_true"`` action.
2007-08-15 11:28:22 -03:00
.. _optparse-callback-example-2:
Callback example 2: check option order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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. ::
2007-08-15 11:28:22 -03:00
def check_order(option, opt_str, value, parser):
if parser.values.b:
raise OptionValueError("can't use -a after -b")
parser.values.a = 1
...
2007-08-15 11:28:22 -03:00
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
.. _optparse-callback-example-3:
Callback example 3: check option order (generalized)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to re-use 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
2007-08-15 11:28:22 -03:00
message and the flag that it sets must be generalized. ::
def check_order(option, opt_str, value, parser):
if parser.values.b:
raise OptionValueError("can't use %s after -b" % opt_str)
setattr(parser.values, option.dest, 1)
...
2007-08-15 11:28:22 -03:00
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')
.. _optparse-callback-example-4:
Callback example 4: check arbitrary condition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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::
def check_moon(option, opt_str, value, parser):
if is_moon_full():
raise OptionValueError("%s option invalid when moon is full"
% opt_str)
setattr(parser.values, option.dest, 1)
...
2007-08-15 11:28:22 -03:00
parser.add_option("--foo",
action="callback", callback=check_moon, dest="foo")
(The definition of ``is_moon_full()`` is left as an exercise for the reader.)
.. _optparse-callback-example-5:
Callback example 5: 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
:attr:`~Option.type`, then the option takes one argument that must be
convertible to that type; if you further define :attr:`~Option.nargs`, then the
option takes :attr:`~Option.nargs` arguments.
2007-08-15 11:28:22 -03:00
Here's an example that just emulates the standard ``"store"`` action::
2007-08-15 11:28:22 -03:00
def store_value(option, opt_str, value, parser):
setattr(parser.values, option.dest, value)
...
2007-08-15 11:28:22 -03:00
parser.add_option("--foo",
action="callback", callback=store_value,
type="int", nargs=3, dest="foo")
Note that :mod:`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.)
.. _optparse-callback-example-6:
Callback example 6: variable arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Things get hairy when you want an option to take a variable number of arguments.
For this case, you must write a callback, as :mod:`optparse` doesn't provide any
built-in capabilities for it. And you have to deal with certain intricacies of
conventional Unix command-line parsing that :mod:`optparse` normally handles for
you. In particular, callbacks should implement the conventional rules for bare
``--`` and ``-`` arguments:
2007-08-15 11:28:22 -03:00
* either ``--`` or ``-`` can be option arguments
2007-08-15 11:28:22 -03:00
* bare ``--`` (if not the argument to some option): halt command-line
processing and discard the ``--``
2007-08-15 11:28:22 -03:00
* bare ``-`` (if not the argument to some option): halt command-line
processing but keep the ``-`` (append it to ``parser.largs``)
2007-08-15 11:28:22 -03:00
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 :mod:`optparse` doesn't support this sort of thing
directly).
Nevertheless, here's a stab at a callback for an option with variable
arguments::
Merged revisions 67654,67676-67677,67681,67692,67725,67761,67784-67785,67787-67788,67802,67848-67850,67862-67864,67880,67882 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67654 | georg.brandl | 2008-12-07 16:42:09 -0600 (Sun, 07 Dec 2008) | 2 lines #4457: rewrite __import__() documentation. ........ r67676 | benjamin.peterson | 2008-12-08 20:03:03 -0600 (Mon, 08 Dec 2008) | 1 line specify how things are copied ........ r67677 | benjamin.peterson | 2008-12-08 20:05:11 -0600 (Mon, 08 Dec 2008) | 1 line revert unrelated change to installer script ........ r67681 | jeremy.hylton | 2008-12-09 15:03:10 -0600 (Tue, 09 Dec 2008) | 2 lines Add simple unittests for Request ........ r67692 | amaury.forgeotdarc | 2008-12-10 18:03:42 -0600 (Wed, 10 Dec 2008) | 2 lines #1030250: correctly pass the dry_run option to the mkpath() function. ........ r67725 | benjamin.peterson | 2008-12-12 22:02:20 -0600 (Fri, 12 Dec 2008) | 1 line fix incorrect example ........ r67761 | benjamin.peterson | 2008-12-14 11:26:04 -0600 (Sun, 14 Dec 2008) | 1 line fix missing bracket ........ r67784 | georg.brandl | 2008-12-15 02:33:58 -0600 (Mon, 15 Dec 2008) | 2 lines #4446: document "platforms" argument for setup(). ........ r67785 | georg.brandl | 2008-12-15 02:36:11 -0600 (Mon, 15 Dec 2008) | 2 lines #4611: fix typo. ........ r67787 | georg.brandl | 2008-12-15 02:58:59 -0600 (Mon, 15 Dec 2008) | 2 lines #4578: fix has_key() usage in compiler package. ........ r67788 | georg.brandl | 2008-12-15 03:07:39 -0600 (Mon, 15 Dec 2008) | 2 lines #4568: remove limitation in varargs callback example. ........ r67802 | amaury.forgeotdarc | 2008-12-15 16:29:14 -0600 (Mon, 15 Dec 2008) | 4 lines #3632: the "pyo" macro from gdbinit can now run when the GIL is released. Patch by haypo. ........ r67848 | benjamin.peterson | 2008-12-18 20:28:56 -0600 (Thu, 18 Dec 2008) | 1 line fix typo ........ r67849 | benjamin.peterson | 2008-12-18 20:31:35 -0600 (Thu, 18 Dec 2008) | 1 line _call_method -> _callmethod and _get_value to _getvalue ........ r67850 | raymond.hettinger | 2008-12-19 03:06:07 -0600 (Fri, 19 Dec 2008) | 9 lines Fix-up and clean-up docs for int.bit_length(). * Replace dramatic footnote with in-line comment about possible round-off errors in logarithms of large numbers. * Add comments to the pure python code equivalent. * replace floor() with int() in the mathematical equivalent so the type is correct (should be an int, not a float). * add abs() to the mathematical equivalent so that it matches the previous line that it is supposed to be equivalent to. * make one combined example with a negative input. ........ r67862 | benjamin.peterson | 2008-12-19 20:48:02 -0600 (Fri, 19 Dec 2008) | 1 line copy sentence from docstring ........ r67863 | benjamin.peterson | 2008-12-19 20:51:26 -0600 (Fri, 19 Dec 2008) | 1 line add headings ........ r67864 | benjamin.peterson | 2008-12-19 20:57:19 -0600 (Fri, 19 Dec 2008) | 1 line beef up docstring ........ r67880 | benjamin.peterson | 2008-12-20 16:49:24 -0600 (Sat, 20 Dec 2008) | 1 line remove redundant sentence ........ r67882 | benjamin.peterson | 2008-12-20 16:59:49 -0600 (Sat, 20 Dec 2008) | 1 line add some recent releases to the list ........
2008-12-20 20:06:59 -04:00
def vararg_callback(option, opt_str, value, parser):
assert value is None
value = []
def floatable(str):
try:
float(str)
return True
except ValueError:
return False
for arg in parser.rargs:
# stop on --foo like options
if arg[:2] == "--" and len(arg) > 2:
break
# stop on -a, but not on -3 or -3.0
if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
break
value.append(arg)
del parser.rargs[:len(value)]
Merged revisions 69129-69131,69139-69140,69143,69154-69159,69169,69288-69289,69293,69297-69301,69348 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r69129 | benjamin.peterson | 2009-01-30 19:42:55 -0600 (Fri, 30 Jan 2009) | 1 line check the errno in bad fd cases ........ r69130 | andrew.kuchling | 2009-01-30 20:50:09 -0600 (Fri, 30 Jan 2009) | 1 line Add a section ........ r69131 | andrew.kuchling | 2009-01-30 21:26:02 -0600 (Fri, 30 Jan 2009) | 1 line Text edits and markup fixes ........ r69139 | mark.dickinson | 2009-01-31 10:44:04 -0600 (Sat, 31 Jan 2009) | 2 lines Add an extra test for long <-> float hash equivalence. ........ r69140 | benjamin.peterson | 2009-01-31 10:52:03 -0600 (Sat, 31 Jan 2009) | 1 line PyErr_BadInternalCall() raises a SystemError, not TypeError #5112 ........ r69143 | benjamin.peterson | 2009-01-31 15:00:10 -0600 (Sat, 31 Jan 2009) | 1 line I believe the intention here was to avoid a global lookup ........ r69154 | benjamin.peterson | 2009-01-31 16:33:02 -0600 (Sat, 31 Jan 2009) | 1 line fix indentation in comment ........ r69155 | david.goodger | 2009-01-31 16:53:46 -0600 (Sat, 31 Jan 2009) | 1 line markup fix ........ r69156 | gregory.p.smith | 2009-01-31 16:57:30 -0600 (Sat, 31 Jan 2009) | 4 lines - Issue #5104: The socket module now raises OverflowError when 16-bit port and protocol numbers are supplied outside the allowed 0-65536 range on bind() and getservbyport(). ........ r69157 | benjamin.peterson | 2009-01-31 17:43:25 -0600 (Sat, 31 Jan 2009) | 1 line add explanatory comment ........ r69158 | benjamin.peterson | 2009-01-31 17:54:38 -0600 (Sat, 31 Jan 2009) | 1 line more flags which only work for function blocks ........ r69159 | gregory.p.smith | 2009-01-31 18:16:01 -0600 (Sat, 31 Jan 2009) | 2 lines Update doc wording as suggested in issue4903. ........ r69169 | guilherme.polo | 2009-01-31 20:56:16 -0600 (Sat, 31 Jan 2009) | 3 lines Restore Tkinter.Tk._loadtk so this test doesn't fail for problems related to ttk. ........ r69288 | georg.brandl | 2009-02-05 04:30:57 -0600 (Thu, 05 Feb 2009) | 1 line #5153: fix typo in example. ........ r69289 | georg.brandl | 2009-02-05 04:37:07 -0600 (Thu, 05 Feb 2009) | 1 line #5144: document that PySys_SetArgv prepends the script directory (or the empty string) to sys.path. ........ r69293 | georg.brandl | 2009-02-05 04:59:28 -0600 (Thu, 05 Feb 2009) | 1 line #5059: fix example. ........ r69297 | georg.brandl | 2009-02-05 05:32:18 -0600 (Thu, 05 Feb 2009) | 1 line #5015: document PythonHome API functions. ........ r69298 | georg.brandl | 2009-02-05 05:33:21 -0600 (Thu, 05 Feb 2009) | 1 line #4827: fix callback example. ........ r69299 | georg.brandl | 2009-02-05 05:35:28 -0600 (Thu, 05 Feb 2009) | 1 line #4820: use correct module for ctypes.util. ........ r69300 | georg.brandl | 2009-02-05 05:38:23 -0600 (Thu, 05 Feb 2009) | 1 line #4563: disable alpha and roman lists, fixes wrong formatting of contributor list. ........ r69301 | georg.brandl | 2009-02-05 05:40:35 -0600 (Thu, 05 Feb 2009) | 1 line #5031: fix Thread.daemon property docs. ........ r69348 | benjamin.peterson | 2009-02-05 19:47:31 -0600 (Thu, 05 Feb 2009) | 1 line fix download link ........
2009-02-05 22:40:07 -04:00
setattr(parser.values, option.dest, value)
2007-08-15 11:28:22 -03:00
...
parser.add_option("-c", "--callback", dest="vararg_attr",
action="callback", callback=vararg_callback)
2007-08-15 11:28:22 -03:00
.. _optparse-extending-optparse:
Extending :mod:`optparse`
-------------------------
Since the two major controlling factors in how :mod:`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.
.. _optparse-adding-new-types:
Adding new types
^^^^^^^^^^^^^^^^
To add new types, you need to define your own subclass of :mod:`optparse`'s
:class:`Option` class. This class has a couple of attributes that define
:mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
2007-08-15 11:28:22 -03:00
.. attribute:: Option.TYPES
2007-08-15 11:28:22 -03:00
A tuple of type names; in your subclass, simply define a new tuple
:attr:`TYPES` that builds on the standard one.
2007-08-15 11:28:22 -03:00
.. attribute:: Option.TYPE_CHECKER
2007-08-15 11:28:22 -03:00
A dictionary mapping type names to type-checking functions. A type-checking
function has the following signature::
2007-08-15 11:28:22 -03:00
def check_mytype(option, opt, value)
2007-08-15 11:28:22 -03:00
where ``option`` is an :class:`Option` instance, ``opt`` is an option string
(e.g., ``-f``), and ``value`` is the string from the command line that must
be checked and converted to your desired type. ``check_mytype()`` should
return an object of the hypothetical type ``mytype``. The value returned by
a type-checking function will wind up in the OptionValues instance returned
by :meth:`OptionParser.parse_args`, or be passed to a callback as the
``value`` parameter.
Your type-checking function should raise :exc:`OptionValueError` if it
encounters any problems. :exc:`OptionValueError` takes a single string
argument, which is passed as-is to :class:`OptionParser`'s :meth:`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
2007-08-15 11:28:22 -03:00
parse Python-style complex numbers on the command line. (This is even sillier
than it used to be, because :mod:`optparse` 1.3 added built-in support for
complex numbers, but never mind.)
First, the necessary imports::
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
:attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
2007-08-15 11:28:22 -03:00
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::
class MyOption (Option):
TYPES = Option.TYPES + ("complex",)
TYPE_CHECKER = copy(Option.TYPE_CHECKER)
TYPE_CHECKER["complex"] = check_complex
(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
Option class. This being Python, nothing stops you from doing that except good
manners and common sense.)
2007-08-15 11:28:22 -03:00
That's it! Now you can write a script that uses the new option type just like
any other :mod:`optparse`\ -based script, except you have to instruct your
OptionParser to use MyOption instead of Option::
parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")
Alternately, you can build your own option list and pass it to OptionParser; if
you don't use :meth:`add_option` in the above way, you don't need to tell
OptionParser which option class to use::
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
.. _optparse-adding-new-actions:
Adding new actions
^^^^^^^^^^^^^^^^^^
Adding new actions is a bit trickier, because you have to understand that
:mod:`optparse` has a couple of classifications for actions:
"store" actions
actions that result in :mod:`optparse` storing a value to an attribute of the
current OptionValues instance; these options require a :attr:`~Option.dest`
attribute to be supplied to the Option constructor.
2007-08-15 11:28:22 -03:00
"typed" actions
actions that take a value from the command line and expect it to be of a
certain type; or rather, a string that can be converted to a certain type.
These options require a :attr:`~Option.type` attribute to the Option
constructor.
2007-08-15 11:28:22 -03:00
These are overlapping sets: some default "store" actions are ``"store"``,
``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
actions are ``"store"``, ``"append"``, and ``"callback"``.
2007-08-15 11:28:22 -03:00
When you add an action, you need to categorize it by listing it in at least one
of the following class attributes of Option (all are lists of strings):
.. attribute:: Option.ACTIONS
All actions must be listed in ACTIONS.
.. attribute:: Option.STORE_ACTIONS
"store" actions are additionally listed here.
.. attribute:: Option.TYPED_ACTIONS
2007-08-15 11:28:22 -03:00
"typed" actions are additionally listed here.
2007-08-15 11:28:22 -03:00
.. attribute:: Option.ALWAYS_TYPED_ACTIONS
2007-08-15 11:28:22 -03:00
Actions that always take a type (i.e. whose options always take a value) are
2007-08-15 11:28:22 -03:00
additionally listed here. The only effect of this is that :mod:`optparse`
assigns the default type, ``"string"``, to options with no explicit type
whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
2007-08-15 11:28:22 -03:00
In order to actually implement your new action, you must override Option's
:meth:`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 ::
2007-08-15 11:28:22 -03:00
--names=foo,bar --names blah --names ding,dong
would result in a list ::
["foo", "bar", "blah", "ding", "dong"]
Again we define a subclass of Option::
class MyOption(Option):
2007-08-15 11:28:22 -03:00
ACTIONS = Option.ACTIONS + ("extend",)
STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
ALWAYS_TYPED_ACTIONS = Option.ALWAYS_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 :attr:`~Option.STORE_ACTIONS` and
:attr:`~Option.TYPED_ACTIONS`.
2007-08-15 11:28:22 -03:00
* to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
``"extend"`` actions, we put the ``"extend"`` action in
:attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
2007-08-15 11:28:22 -03:00
* :meth:`MyOption.take_action` implements just this one new action, and passes
control back to :meth:`Option.take_action` for the standard :mod:`optparse`
actions.
2007-08-15 11:28:22 -03:00
* ``values`` is an instance of the optparse_parser.Values class, which provides
the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
essentially :func:`getattr` with a safety valve; it is called as ::
2007-08-15 11:28:22 -03:00
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
2007-08-15 11:28:22 -03:00
:meth:`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 :meth:`ensure_value` will take care of
2007-08-15 11:28:22 -03:00
getting it right when it's needed.