Skip to content

C
cpython
Commit 17c2b4e7 authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

Merged revisions 74868,74877-74878 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74868 | georg.brandl | 2009-09-17 12:23:02 +0200 (Do, 17 Sep 2009) | 2 lines

  String values should be shown with quotes, to avoid confusion with constants.
........
  r74877 | georg.brandl | 2009-09-17 18:26:06 +0200 (Do, 17 Sep 2009) | 1 line

  Remove duplicate doc of enable/disable_interspersed_args.
........
  r74878 | georg.brandl | 2009-09-17 19:14:04 +0200 (Do, 17 Sep 2009) | 1 line

  Make the optparse doc style a bit more standard: use standard description units for attrs/methods/etc., and use the correct referencing roles.
........
parent 5db61f90
Hide whitespace changes
Inline Side-by-side
Showing with 519 additions and 471 deletions
Doc/library/optparse.rst
View file @ 17c2b4e7
...@@ -7,14 +7,14 @@ ...@@ -7,14 +7,14 @@
.. sectionauthor:: Greg Ward <gward@python.net> .. sectionauthor:: Greg Ward <gward@python.net>
``optparse`` is a more convenient, flexible, and powerful library for parsing :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
command-line options than the old :mod:`getopt` module. ``optparse`` uses a more declarative command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
style of command-line parsing: you create an instance of :class:`OptionParser`, more declarative style of command-line parsing: you create an instance of
populate it with options, and parse the command line. ``optparse`` allows users :class:`OptionParser`, populate it with options, and parse the command
to specify options in the conventional GNU/POSIX syntax, and additionally line. :mod:`optparse` allows users to specify options in the conventional
generates usage and help messages for you. GNU/POSIX syntax, and additionally generates usage and help messages for you.
Here's an example of using ``optparse`` in a simple script:: Here's an example of using :mod:`optparse` in a simple script::
from optparse import OptionParser from optparse import OptionParser
[...] [...]
...@@ -32,11 +32,11 @@ on the command-line, for example:: ...@@ -32,11 +32,11 @@ on the command-line, for example::
<yourscript> --file=outfile -q <yourscript> --file=outfile -q
As it parses the command line, ``optparse`` sets attributes of the ``options`` As it parses the command line, :mod:`optparse` sets attributes of the
object returned by :meth:`parse_args` based on user-supplied command-line ``options`` object returned by :meth:`parse_args` based on user-supplied
values. When :meth:`parse_args` returns from parsing this command line, command-line values. When :meth:`parse_args` returns from parsing this command
``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
``False``. ``optparse`` supports both long and short options, allows short ``False``. :mod:`optparse` supports both long and short options, allows short
options to be merged together, and allows options to be associated with their 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 arguments in a variety of ways. Thus, the following command lines are all
equivalent to the above example:: equivalent to the above example::
...@@ -51,7 +51,7 @@ Additionally, users can run one of :: ...@@ -51,7 +51,7 @@ Additionally, users can run one of ::
<yourscript> -h <yourscript> -h
<yourscript> --help <yourscript> --help
and ``optparse`` will print out a brief summary of your script's options:: and :mod:`optparse` will print out a brief summary of your script's options::
usage: <yourscript> [options] usage: <yourscript> [options]
...@@ -82,10 +82,10 @@ Terminology ...@@ -82,10 +82,10 @@ Terminology
^^^^^^^^^^^ ^^^^^^^^^^^
argument argument
a string entered on the command-line, and passed by the shell to ``execl()`` or a string entered on the command-line, and passed by the shell to ``execl()``
``execv()``. In Python, arguments are elements of ``sys.argv[1:]`` 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 (``sys.argv[0]`` is the name of the program being executed). Unix shells
use the term "word". also use the term "word".
It is occasionally desirable to substitute an argument list other than 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:]``, so you should read "argument" as "an element of
...@@ -93,14 +93,14 @@ argument ...@@ -93,14 +93,14 @@ argument
``sys.argv[1:]``". ``sys.argv[1:]``".
option option
an argument used to supply extra information to guide or customize the execution an argument used to supply extra information to guide or customize the
of a program. There are many different syntaxes for options; the traditional execution of a program. There are many different syntaxes for options; the
Unix syntax is a hyphen ("-") followed by a single letter, e.g. ``"-x"`` or traditional Unix syntax is a hyphen ("-") followed by a single letter,
``"-F"``. Also, traditional Unix syntax allows multiple options to be merged e.g. ``"-x"`` or ``"-F"``. Also, traditional Unix syntax allows multiple
into a single argument, e.g. ``"-x -F"`` is equivalent to ``"-xF"``. The GNU options to be merged into a single argument, e.g. ``"-x -F"`` is equivalent
project introduced ``"--"`` followed by a series of hyphen-separated words, e.g. to ``"-xF"``. The GNU project introduced ``"--"`` followed by a series of
``"--file"`` or ``"--dry-run"``. These are the only two option syntaxes hyphen-separated words, e.g. ``"--file"`` or ``"--dry-run"``. These are the
provided by :mod:`optparse`. only two option syntaxes provided by :mod:`optparse`.
Some other option syntaxes that the world has seen include: Some other option syntaxes that the world has seen include:
...@@ -117,15 +117,16 @@ option ...@@ -117,15 +117,16 @@ option
* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
``"/file"`` ``"/file"``
These option syntaxes are not supported by :mod:`optparse`, and they never will These option syntaxes are not supported by :mod:`optparse`, and they never
be. This is deliberate: the first three are non-standard on any environment, will be. This is deliberate: the first three are non-standard on any
and the last only makes sense if you're exclusively targeting VMS, MS-DOS, environment, and the last only makes sense if you're exclusively targeting
and/or Windows. VMS, MS-DOS, and/or Windows.
option argument option argument
an argument that follows an option, is closely associated with that option, and an argument that follows an option, is closely associated with that option,
is consumed from the argument list when that option is. With :mod:`optparse`, and is consumed from the argument list when that option is. With
option arguments may either be in a separate argument from their option:: :mod:`optparse`, option arguments may either be in a separate argument from
their option::
-f foo -f foo
--file foo --file foo
...@@ -135,25 +136,26 @@ option argument ...@@ -135,25 +136,26 @@ option argument
-ffoo -ffoo
--file=foo --file=foo
Typically, a given option either takes an argument or it doesn't. Lots of people Typically, a given option either takes an argument or it doesn't. Lots of
want an "optional option arguments" feature, meaning that some options will take people want an "optional option arguments" feature, meaning that some options
an argument if they see it, and won't if they don't. This is somewhat will take an argument if they see it, and won't if they don't. This is
controversial, because it makes parsing ambiguous: if ``"-a"`` takes an optional somewhat controversial, because it makes parsing ambiguous: if ``"-a"`` takes
argument and ``"-b"`` is another option entirely, how do we interpret ``"-ab"``? an optional argument and ``"-b"`` is another option entirely, how do we
Because of this ambiguity, :mod:`optparse` does not support this feature. interpret ``"-ab"``? Because of this ambiguity, :mod:`optparse` does not
support this feature.
positional argument positional argument
something leftover in the argument list after options have been parsed, i.e. 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 after options and their arguments have been parsed and removed from the
list. argument list.
required option required option
an option that must be supplied on the command-line; note that the phrase 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 "required option" is self-contradictory in English. :mod:`optparse` doesn't
prevent you from implementing required options, but doesn't give you much help prevent you from implementing required options, but doesn't give you much
at it either. See ``examples/required_1.py`` and ``examples/required_2.py`` in help at it either. See ``examples/required_1.py`` and
the :mod:`optparse` source distribution for two ways to implement required ``examples/required_2.py`` in the :mod:`optparse` source distribution for two
options with :mod:`optparse`. ways to implement required options with :mod:`optparse`.
For example, consider this hypothetical command-line:: For example, consider this hypothetical command-line::
...@@ -282,8 +284,9 @@ that's rarely necessary: by default it uses ``sys.argv[1:]``.) ...@@ -282,8 +284,9 @@ that's rarely necessary: by default it uses ``sys.argv[1:]``.)
* ``args``, the list of positional arguments leftover after parsing options * ``args``, the list of positional arguments leftover after parsing options
This tutorial section only covers the four most important option attributes: This tutorial section only covers the four most important option attributes:
:attr:`action`, :attr:`!type`, :attr:`dest` (destination), and :attr:`help`. Of :attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
these, :attr:`action` is the most fundamental. (destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
most fundamental.
.. _optparse-understanding-option-actions: .. _optparse-understanding-option-actions:
...@@ -294,9 +297,9 @@ Understanding option actions ...@@ -294,9 +297,9 @@ Understanding option actions
Actions tell :mod:`optparse` what to do when it encounters an option on the 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`; command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
adding new actions is an advanced topic covered in section adding new actions is an advanced topic covered in section
:ref:`optparse-extending-optparse`. Most actions tell :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
:mod:`optparse` to store a value in some variable---for example, take a string a value in some variable---for example, take a string from the command line and
from the command line and store it in an attribute of ``options``. store it in an attribute of ``options``.
If you don't specify an option action, :mod:`optparse` defaults to ``store``. If you don't specify an option action, :mod:`optparse` defaults to ``store``.
...@@ -334,7 +337,7 @@ Also, there's no explicit action, since the default is ``store``. ...@@ -334,7 +337,7 @@ 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 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 right up against the option: since ``"-n42"`` (one argument) is equivalent to
``"-n 42"`` (two arguments), the code :: ``"-n 42"`` (two arguments), the code ::
(options, args) = parser.parse_args(["-n42"]) (options, args) = parser.parse_args(["-n42"])
print(options.num) print(options.num)
...@@ -386,16 +389,16 @@ Other actions ...@@ -386,16 +389,16 @@ Other actions
Some other actions supported by :mod:`optparse` are: Some other actions supported by :mod:`optparse` are:
``store_const`` ``"store_const"``
store a constant value store a constant value
``append`` ``"append"``
append this option's argument to a list append this option's argument to a list
``count`` ``"count"``
increment a counter by one increment a counter by one
``callback`` ``"callback"``
call a specified function call a specified function
These are covered in section :ref:`optparse-reference-guide`, Reference Guide These are covered in section :ref:`optparse-reference-guide`, Reference Guide
...@@ -454,8 +457,8 @@ Generating help ...@@ -454,8 +457,8 @@ Generating help
:mod:`optparse`'s ability to generate help and usage text automatically is :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 useful for creating user-friendly command-line interfaces. All you have to do
is supply a :attr:`help` value for each option, and optionally a short usage is supply a :attr:`~Option.help` value for each option, and optionally a short
message for your whole program. Here's an OptionParser populated with usage message for your whole program. Here's an OptionParser populated with
user-friendly (documented) options:: user-friendly (documented) options::
usage = "usage: %prog [options] arg1 arg2" usage = "usage: %prog [options] arg1 arg2"
...@@ -499,12 +502,12 @@ help message: ...@@ -499,12 +502,12 @@ help message:
usage = "usage: %prog [options] arg1 arg2" usage = "usage: %prog [options] arg1 arg2"
:mod:`optparse` expands ``"%prog"`` in the usage string to the name of the :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 current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
then printed before the detailed option help. is then printed before the detailed option help.
If you don't supply a usage string, :mod:`optparse` uses a bland but sensible 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 default: ``"usage: %prog [options]"``, which is fine if your script doesn't
any positional arguments. take any positional arguments.
* every option defines a help string, and doesn't worry about line-wrapping--- * 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 :mod:`optparse` takes care of wrapping lines and making the help output look
...@@ -518,29 +521,29 @@ help message: ...@@ -518,29 +521,29 @@ help message:
Here, "MODE" is called the meta-variable: it stands for the argument that the Here, "MODE" is called the meta-variable: it stands for the argument that the
user is expected to supply to :option:`-m`/:option:`--mode`. By default, user is expected to supply to :option:`-m`/:option:`--mode`. By default,
:mod:`optparse` converts the destination variable name to uppercase and uses :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, that for the meta-variable. Sometimes, that's not what you want---for
the :option:`--filename` option explicitly sets ``metavar="FILE"``, resulting in example, the :option:`--filename` option explicitly sets ``metavar="FILE"``,
this automatically-generated option description:: resulting in this automatically-generated option description::
-f FILE, --filename=FILE -f FILE, --filename=FILE
This is important for more than just saving space, though: the manually written This is important for more than just saving space, though: the manually
help text uses the meta-variable "FILE" to clue the user in that there's a written help text uses the meta-variable "FILE" to clue the user in that
connection between the semi-formal syntax "-f FILE" and the informal semantic there's a connection between the semi-formal syntax "-f FILE" and the informal
description "write output to FILE". This is a simple but effective way to make semantic description "write output to FILE". This is a simple but effective
your help text a lot clearer and more useful for end users. way to make your help text a lot clearer and more useful for end users.
* options that have a default value can include ``%default`` in the help * 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 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 default value. If an option has no default value (or the default value is
``None``), ``%default`` expands to ``none``. ``None``), ``%default`` expands to ``none``.
When dealing with many options, it is convenient to group these When dealing with many options, it is convenient to group these options for
options for better help output. An :class:`OptionParser` can contain better help output. An :class:`OptionParser` can contain several option groups,
several option groups, each of which can contain several options. each of which can contain several options.
Continuing with the parser defined above, adding an Continuing with the parser defined above, adding an :class:`OptionGroup` to a
:class:`OptionGroup` to a parser is easy:: parser is easy::
group = OptionGroup(parser, "Dangerous Options", group = OptionGroup(parser, "Dangerous Options",
"Caution: use these options at your own risk. " "Caution: use these options at your own risk. "
...@@ -595,17 +598,17 @@ How :mod:`optparse` handles errors ...@@ -595,17 +598,17 @@ How :mod:`optparse` handles errors
There are two broad classes of errors that :mod:`optparse` has to worry about: There are two broad classes of errors that :mod:`optparse` has to worry about:
programmer errors and user errors. Programmer errors are usually erroneous programmer errors and user errors. Programmer errors are usually erroneous
calls to ``parser.add_option()``, e.g. invalid option strings, unknown option calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
attributes, missing option attributes, etc. These are dealt with in the usual option attributes, missing option attributes, etc. These are dealt with in the
way: raise an exception (either ``optparse.OptionError`` or :exc:`TypeError`) and usual way: raise an exception (either :exc:`optparse.OptionError` or
let the program crash. :exc:`TypeError`) and let the program crash.
Handling user errors is much more important, since they are guaranteed to happen 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 no matter how stable your code is. :mod:`optparse` can automatically detect
some user errors, such as bad option arguments (passing ``"-n 4x"`` where some user errors, such as bad option arguments (passing ``"-n 4x"`` where
:option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end :option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
of the command line, where :option:`-n` takes an argument of any type). Also, of the command line, where :option:`-n` takes an argument of any type). Also,
you can call ``parser.error()`` to signal an application-defined error you can call :func:`OptionParser.error` to signal an application-defined error
condition:: condition::
(options, args) = parser.parse_args() (options, args) = parser.parse_args()
...@@ -634,7 +637,7 @@ Or, where the user fails to pass a value at all:: ...@@ -634,7 +637,7 @@ Or, where the user fails to pass a value at all::
:mod:`optparse`\ -generated error messages take care always to mention the :mod:`optparse`\ -generated error messages take care always to mention the
option involved in the error; be sure to do the same when calling option involved in the error; be sure to do the same when calling
``parser.error()`` from your application code. :func:`OptionParser.error` from your application code.
If :mod:`optparse`'s default error-handling behaviour does not suit your needs, 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` you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
...@@ -682,49 +685,51 @@ Reference Guide ...@@ -682,49 +685,51 @@ Reference Guide
Creating the parser Creating the parser
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The first step in using :mod:`optparse` is to create an OptionParser instance:: The first step in using :mod:`optparse` is to create an OptionParser instance.
parser = OptionParser(...) .. class:: OptionParser(...)
The OptionParser constructor has no required arguments, but a number of optional The OptionParser constructor has no required arguments, but a number of
keyword arguments. You should always pass them as keyword arguments, i.e. do optional keyword arguments. You should always pass them as keyword
not rely on the order in which the arguments are declared. arguments, i.e. do not rely on the order in which the arguments are declared.
``usage`` (default: ``"%prog [options]"``) ``usage`` (default: ``"%prog [options]"``)
The usage summary to print when your program is run incorrectly or with a help The usage summary to print when your program is run incorrectly or with a
option. When :mod:`optparse` prints the usage string, it expands ``%prog`` to help option. When :mod:`optparse` prints the usage string, it expands
``os.path.basename(sys.argv[0])`` (or to ``prog`` if you passed that keyword ``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
argument). To suppress a usage message, pass the special value passed that keyword argument). To suppress a usage message, pass the
``optparse.SUPPRESS_USAGE``. special value :data:`optparse.SUPPRESS_USAGE`.
``option_list`` (default: ``[]``) ``option_list`` (default: ``[]``)
A list of Option objects to populate the parser with. The options in 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 ``option_list`` are added after any options in ``standard_option_list`` (a
attribute that may be set by OptionParser subclasses), but before any version or class attribute that may be set by OptionParser subclasses), but before
help options. Deprecated; use :meth:`add_option` after creating the parser any version or help options. Deprecated; use :meth:`add_option` after
instead. creating the parser instead.
``option_class`` (default: optparse.Option) ``option_class`` (default: optparse.Option)
Class to use when adding options to the parser in :meth:`add_option`. Class to use when adding options to the parser in :meth:`add_option`.
``version`` (default: ``None``) ``version`` (default: ``None``)
A version string to print when the user supplies a version option. If you supply A version string to print when the user supplies a version option. If you
a true value for ``version``, :mod:`optparse` automatically adds a version supply a true value for ``version``, :mod:`optparse` automatically adds a
option with the single option string ``"--version"``. The substring ``"%prog"`` version option with the single option string ``"--version"``. The
is expanded the same as for ``usage``. substring ``"%prog"`` is expanded the same as for ``usage``.
``conflict_handler`` (default: ``"error"``) ``conflict_handler`` (default: ``"error"``)
Specifies what to do when options with conflicting option strings are added to Specifies what to do when options with conflicting option strings are
the parser; see section :ref:`optparse-conflicts-between-options`. added to the parser; see section
:ref:`optparse-conflicts-between-options`.
``description`` (default: ``None``) ``description`` (default: ``None``)
A paragraph of text giving a brief overview of your program. :mod:`optparse` A paragraph of text giving a brief overview of your program.
reformats this paragraph to fit the current terminal width and prints it when :mod:`optparse` reformats this paragraph to fit the current terminal width
the user requests help (after ``usage``, but before the list of options). and prints it when the user requests help (after ``usage``, but before the
list of options).
``formatter`` (default: a new IndentedHelpFormatter)
An instance of optparse.HelpFormatter that will be used for printing help text. ``formatter`` (default: a new :class:`IndentedHelpFormatter`)
:mod:`optparse` provides two concrete classes for this purpose: An instance of optparse.HelpFormatter that will be used for printing help
text. :mod:`optparse` provides two concrete classes for this purpose:
IndentedHelpFormatter and TitledHelpFormatter. IndentedHelpFormatter and TitledHelpFormatter.
``add_help_option`` (default: ``True``) ``add_help_option`` (default: ``True``)
...@@ -743,14 +748,14 @@ Populating the parser ...@@ -743,14 +748,14 @@ Populating the parser
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
There are several ways to populate the parser with options. The preferred way There are several ways to populate the parser with options. The preferred way
is by using ``OptionParser.add_option()``, as shown in section is by using :meth:`OptionParser.add_option`, as shown in section
:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways: :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 an Option instance (as returned by :func:`make_option`)
* pass it any combination of positional and keyword arguments that are * 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 acceptable to :func:`make_option` (i.e., to the Option constructor), and it
create the Option instance for you will create the Option instance for you
The other alternative is to pass a list of pre-constructed Option instances to The other alternative is to pass a list of pre-constructed Option instances to
the OptionParser constructor, as in:: the OptionParser constructor, as in::
...@@ -778,66 +783,67 @@ Each Option instance represents a set of synonymous command-line option strings, ...@@ -778,66 +783,67 @@ Each Option instance represents a set of synonymous command-line option strings,
e.g. :option:`-f` and :option:`--file`. You can specify any number of short or e.g. :option:`-f` and :option:`--file`. You can specify any number of short or
long option strings, but you must specify at least one overall option string. long option strings, but you must specify at least one overall option string.
The canonical way to create an Option instance is with the :meth:`add_option` The canonical way to create an :class:`Option` instance is with the
method of :class:`OptionParser`:: :meth:`add_option` method of :class:`OptionParser`.
parser.add_option(opt_str[, ...], attr=value, ...) .. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...)
To define an option with only a short option string:: To define an option with only a short option string::
parser.add_option("-f", attr=value, ...) parser.add_option("-f", attr=value, ...)
And to define an option with only a long option string:: And to define an option with only a long option string::
parser.add_option("--foo", attr=value, ...) parser.add_option("--foo", attr=value, ...)
The keyword arguments define attributes of the new Option object. The most The keyword arguments define attributes of the new Option object. The most
important option attribute is :attr:`action`, and it largely determines which important option attribute is :attr:`~Option.action`, and it largely
other attributes are relevant or required. If you pass irrelevant option determines which other attributes are relevant or required. If you pass
attributes, or fail to pass required ones, :mod:`optparse` raises an irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
:exc:`OptionError` exception explaining your mistake. raises an :exc:`OptionError` exception explaining your mistake.
An option's *action* determines what :mod:`optparse` does when it encounters 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 this option on the command-line. The standard option actions hard-coded into
:mod:`optparse` are: :mod:`optparse` are:
``store`` ``"store"``
store this option's argument (default) store this option's argument (default)
``store_const`` ``"store_const"``
store a constant value store a constant value
``store_true`` ``"store_true"``
store a true value store a true value
``store_false`` ``"store_false"``
store a false value store a false value
``append`` ``"append"``
append this option's argument to a list append this option's argument to a list
``append_const`` ``"append_const"``
append a constant value to a list append a constant value to a list
``count`` ``"count"``
increment a counter by one increment a counter by one
``callback`` ``"callback"``
call a specified function call a specified function
:attr:`help` ``"help"``
print a usage message including all options and the documentation for them print a usage message including all options and the documentation for them
(If you don't supply an action, the default is ``store``. For this action, you (If you don't supply an action, the default is ``"store"``. For this action,
may also supply :attr:`!type` and :attr:`dest` option attributes; see below.) you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
attributes; see :ref:`optparse-standard-option-actions`.)
As you can see, most actions involve storing or updating a value somewhere. As you can see, most actions involve storing or updating a value somewhere.
:mod:`optparse` always creates a special object for this, conventionally called :mod:`optparse` always creates a special object for this, conventionally called
``options`` (it happens to be an instance of ``optparse.Values``). Option ``options`` (it happens to be an instance of :class:`optparse.Values`). Option
arguments (and various other values) are stored as attributes of this object, arguments (and various other values) are stored as attributes of this object,
according to the :attr:`dest` (destination) option attribute. according to the :attr:`~Option.dest` (destination) option attribute.
For example, when you call :: For example, when you call ::
parser.parse_args() parser.parse_args()
...@@ -845,7 +851,7 @@ one of the first things :mod:`optparse` does is create the ``options`` object:: ...@@ -845,7 +851,7 @@ one of the first things :mod:`optparse` does is create the ``options`` object::
options = Values() options = Values()
If one of the options in this parser is defined with :: If one of the options in this parser is defined with ::
parser.add_option("-f", "--file", action="store", type="string", dest="filename") parser.add_option("-f", "--file", action="store", type="string", dest="filename")
...@@ -856,13 +862,97 @@ and the command-line being parsed includes any of the following:: ...@@ -856,13 +862,97 @@ and the command-line being parsed includes any of the following::
--file=foo --file=foo
--file foo --file foo
then :mod:`optparse`, on seeing this option, will do the equivalent of :: then :mod:`optparse`, on seeing this option, will do the equivalent of ::
options.filename = "foo" options.filename = "foo"
The :attr:`!type` and :attr:`dest` option attributes are almost as important as The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
:attr:`action`, but :attr:`action` is the only one that makes sense for *all* as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
options. 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.
.. _optparse-standard-option-actions: .. _optparse-standard-option-actions:
...@@ -875,42 +965,45 @@ Most actions have several relevant option attributes which you may specify to ...@@ -875,42 +965,45 @@ Most actions have several relevant option attributes which you may specify to
guide :mod:`optparse`'s behaviour; a few have required attributes, which you guide :mod:`optparse`'s behaviour; a few have required attributes, which you
must specify for any option using that action. must specify for any option using that action.
* ``store`` [relevant: :attr:`!type`, :attr:`dest`, ``nargs``, ``choices``] * ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
:attr:`~Option.nargs`, :attr:`~Option.choices`]
The option must be followed by an argument, which is converted to a value The option must be followed by an argument, which is converted to a value
according to :attr:`!type` and stored in :attr:`dest`. If ``nargs`` > 1, according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
multiple arguments will be consumed from the command line; all will be converted :attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
according to :attr:`!type` and stored to :attr:`dest` as a tuple. See the command line; all will be converted according to :attr:`~Option.type` and
"Option types" section below. stored to :attr:`~Option.dest` as a tuple. See the
:ref:`optparse-standard-option-types` section.
If ``choices`` is supplied (a list or tuple of strings), the type defaults to If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
``choice``. defaults to ``"choice"``.
If :attr:`!type` is not supplied, it defaults to ``string``. If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
If :attr:`dest` is not supplied, :mod:`optparse` derives a destination from the If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
first long option string (e.g., ``"--foo-bar"`` implies ``foo_bar``). If there from the first long option string (e.g., ``"--foo-bar"`` implies
are no long option strings, :mod:`optparse` derives a destination from the first ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
short option string (e.g., ``"-f"`` implies ``f``). destination from the first short option string (e.g., ``"-f"`` implies ``f``).
Example:: Example::
parser.add_option("-f") parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point") parser.add_option("-p", type="float", nargs=3, dest="point")
As it parses the command line :: As it parses the command line ::
-f foo.txt -p 1 -3.5 4 -fbar.txt -f foo.txt -p 1 -3.5 4 -fbar.txt
:mod:`optparse` will set :: :mod:`optparse` will set ::
options.f = "foo.txt" options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0) options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt" options.f = "bar.txt"
* ``store_const`` [required: ``const``; relevant: :attr:`dest`] * ``"store_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]
The value ``const`` is stored in :attr:`dest`. The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
Example:: Example::
...@@ -925,29 +1018,32 @@ must specify for any option using that action. ...@@ -925,29 +1018,32 @@ must specify for any option using that action.
options.verbose = 2 options.verbose = 2
* ``store_true`` [relevant: :attr:`dest`] * ``"store_true"`` [relevant: :attr:`~Option.dest`]
A special case of ``store_const`` that stores a true value to :attr:`dest`. A special case of ``"store_const"`` that stores a true value to
:attr:`~Option.dest`.
* ``store_false`` [relevant: :attr:`dest`] * ``"store_false"`` [relevant: :attr:`~Option.dest`]
Like ``store_true``, but stores a false value. Like ``"store_true"``, but stores a false value.
Example:: Example::
parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber")
* ``append`` [relevant: :attr:`!type`, :attr:`dest`, ``nargs``, ``choices``] * ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
:attr:`~Option.nargs`, :attr:`~Option.choices`]
The option must be followed by an argument, which is appended to the list in The option must be followed by an argument, which is appended to the list in
:attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list :attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
is automatically created when :mod:`optparse` first encounters this option on supplied, an empty list is automatically created when :mod:`optparse` first
the command-line. If ``nargs`` > 1, multiple arguments are consumed, and a encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
tuple of length ``nargs`` is appended to :attr:`dest`. multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
is appended to :attr:`~Option.dest`.
The defaults for :attr:`!type` and :attr:`dest` are the same as for the ``store`` The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
action. for the ``"store"`` action.
Example:: Example::
...@@ -963,16 +1059,19 @@ must specify for any option using that action. ...@@ -963,16 +1059,19 @@ must specify for any option using that action.
options.tracks.append(int("4")) options.tracks.append(int("4"))
* ``append_const`` [required: ``const``; relevant: :attr:`dest`] * ``"append_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]
Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
with ``append``, :attr:`dest` defaults to ``None``, and an empty list is :attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
automatically created the first time the option is encountered. ``None``, and an empty list is automatically created the first time the option
is encountered.
* ``count`` [relevant: :attr:`dest`] * ``"count"`` [relevant: :attr:`~Option.dest`]
Increment the integer stored at :attr:`dest`. If no default value is supplied, Increment the integer stored at :attr:`~Option.dest`. If no default value is
:attr:`dest` is set to zero before being incremented the first time. supplied, :attr:`~Option.dest` is set to zero before being incremented the
first time.
Example:: Example::
...@@ -988,27 +1087,29 @@ must specify for any option using that action. ...@@ -988,27 +1087,29 @@ must specify for any option using that action.
options.verbosity += 1 options.verbosity += 1
* ``callback`` [required: ``callback``; relevant: :attr:`!type`, ``nargs``, * ``"callback"`` [required: :attr:`~Option.callback`; relevant:
``callback_args``, ``callback_kwargs``] :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
:attr:`~Option.callback_kwargs`]
Call the function specified by ``callback``, which is called as :: Call the function specified by :attr:`~Option.callback`, which is called as ::
func(option, opt_str, value, parser, *args, **kwargs) func(option, opt_str, value, parser, *args, **kwargs)
See section :ref:`optparse-option-callbacks` for more detail. See section :ref:`optparse-option-callbacks` for more detail.
* :attr:`help` * ``"help"``
Prints a complete help message for all the options in the current option parser. Prints a complete help message for all the options in the current option
The help message is constructed from the ``usage`` string passed to parser. The help message is constructed from the ``usage`` string passed to
OptionParser's constructor and the :attr:`help` string passed to every option. OptionParser's constructor and the :attr:`~Option.help` string passed to every
option.
If no :attr:`help` string is supplied for an option, it will still be listed in If no :attr:`~Option.help` string is supplied for an option, it will still be
the help message. To omit an option entirely, use the special value listed in the help message. To omit an option entirely, use the special value
``optparse.SUPPRESS_HELP``. :data:`optparse.SUPPRESS_HELP`.
:mod:`optparse` automatically adds a :attr:`help` option to all OptionParsers, :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
so you do not normally need to create one. OptionParsers, so you do not normally need to create one.
Example:: Example::
...@@ -1025,8 +1126,8 @@ must specify for any option using that action. ...@@ -1025,8 +1126,8 @@ must specify for any option using that action.
help="Input file to read data from") help="Input file to read data from")
parser.add_option("--secret", help=SUPPRESS_HELP) parser.add_option("--secret", help=SUPPRESS_HELP)
If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line, it If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line,
will print something like the following help message to stdout (assuming it will print something like the following help message to stdout (assuming
``sys.argv[0]`` is ``"foo.py"``):: ``sys.argv[0]`` is ``"foo.py"``)::
usage: foo.py [options] usage: foo.py [options]
...@@ -1039,82 +1140,14 @@ must specify for any option using that action. ...@@ -1039,82 +1140,14 @@ must specify for any option using that action.
After printing the help message, :mod:`optparse` terminates your process with After printing the help message, :mod:`optparse` terminates your process with
``sys.exit(0)``. ``sys.exit(0)``.
* ``version`` * ``"version"``
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:`help` options, you
will rarely create ``version`` options, since :mod:`optparse` automatically adds
them when needed.
.. _optparse-option-attributes: Prints the version number supplied to the OptionParser to stdout and exits.
The version number is actually formatted and printed by the
Option attributes ``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,
The following option attributes may be passed as keyword arguments to since :mod:`optparse` automatically adds them when needed.
``parser.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`.
* :attr:`action` (default: ``"store"``)
Determines :mod:`optparse`'s behaviour when this option is seen on the command
line; the available options are documented above.
* :attr:`!type` (default: ``"string"``)
The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the
available option types are documented below.
* :attr:`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:`dest` names an attribute of the
``options`` object that :mod:`optparse` builds as it parses the command line.
* ``default``
The value to use for this option's destination if the option is not seen on the
command line. See also ``parser.set_defaults()``.
* ``nargs`` (default: 1)
How many arguments of type :attr:`!type` should be consumed when this option is
seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`.
* ``const``
For actions that store a constant value, the constant value to store.
* ``choices``
For options of type ``"choice"``, the list of strings the user may choose from.
* ``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 ``callable``.
* ``callback_args``, ``callback_kwargs``
Additional positional and keyword arguments to pass to ``callback`` after the
four standard callback arguments.
* :attr:`help`
Help text to print for this option when listing all available options after the
user supplies a :attr:`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 ``SUPPRESS_HELP``.
* ``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.
.. _optparse-standard-option-types: .. _optparse-standard-option-types:
...@@ -1122,14 +1155,14 @@ to a particular option, or fail to pass a required option attribute, ...@@ -1122,14 +1155,14 @@ to a particular option, or fail to pass a required option attribute,
Standard option types Standard option types
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
:mod:`optparse` has five built-in option types: ``string``, ``int``, :mod:`optparse` has five built-in option types: ``"string"``, ``"int"``,
``choice``, ``float`` and ``complex``. If you need to add new option types, see ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
section :ref:`optparse-extending-optparse`. option types, see section :ref:`optparse-extending-optparse`.
Arguments to string options are not checked or converted in any way: the text on 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. the command line is stored in the destination (or passed to the callback) as-is.
Integer arguments (type ``int``) are parsed as follows: Integer arguments (type ``"int"``) are parsed as follows:
* if the number starts with ``0x``, it is parsed as a hexadecimal number * if the number starts with ``0x``, it is parsed as a hexadecimal number
...@@ -1140,17 +1173,18 @@ Integer arguments (type ``int``) are parsed as follows: ...@@ -1140,17 +1173,18 @@ Integer arguments (type ``int``) are parsed as follows:
* otherwise, the number is parsed as a decimal number * otherwise, the number is parsed as a decimal number
The conversion is done by calling ``int()`` with the appropriate base (2, 8, 10, The conversion is done by calling :func:`int` with the appropriate base (2, 8,
or 16). If this fails, so will :mod:`optparse`, although with a more useful 10, or 16). If this fails, so will :mod:`optparse`, although with a more useful
error message. error message.
``float`` and ``complex`` option arguments are converted directly with ``"float"`` and ``"complex"`` option arguments are converted directly with
``float()`` and ``complex()``, with similar error-handling. :func:`float` and :func:`complex`, with similar error-handling.
``choice`` options are a subtype of ``string`` options. The ``choices`` option ``"choice"`` options are a subtype of ``"string"`` options. The
attribute (a sequence of strings) defines the set of allowed option arguments. :attr:`~Option.choices`` option attribute (a sequence of strings) defines the
``optparse.check_choice()`` compares user-supplied option arguments against this set of allowed option arguments. :func:`optparse.check_choice` compares
master list and raises :exc:`OptionValueError` if an invalid string is given. user-supplied option arguments against this master list and raises
:exc:`OptionValueError` if an invalid string is given.
.. _optparse-parsing-arguments: .. _optparse-parsing-arguments:
...@@ -1182,7 +1216,7 @@ and the return values are ...@@ -1182,7 +1216,7 @@ and the return values are
the leftover positional arguments after all options have been processed the leftover positional arguments after all options have been processed
The most common usage is to supply neither keyword argument. If you supply The most common usage is to supply neither keyword argument. If you supply
``values``, it will be modified with repeated ``setattr()`` calls (roughly one ``values``, it will be modified with repeated :func:`setattr` calls (roughly one
for every option argument stored to an option destination) and returned by for every option argument stored to an option destination) and returned by
:meth:`parse_args`. :meth:`parse_args`.
...@@ -1197,37 +1231,51 @@ traditional Unix exit status for command-line errors). ...@@ -1197,37 +1231,51 @@ traditional Unix exit status for command-line errors).
Querying and manipulating your option parser Querying and manipulating your option parser
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default behavior of the option parser can be customized slightly, The default behavior of the option parser can be customized slightly, and you
and you can also poke around your option parser and see what's there. can also poke around your option parser and see what's there. OptionParser
OptionParser provides several methods to help you out: provides several methods to help you out:
``disable_interspersed_args()`` .. method:: OptionParser.disable_interspersed_args()
Set parsing to stop on the first non-option. Use this if you have a
command processor which runs another command which has options of Set parsing to stop on the first non-option. For example, if ``"-a"`` and
its own and you want to make sure these options don't get ``"-b"`` are both simple options that take no arguments, :mod:`optparse`
confused. For example, each command might have a different normally accepts this syntax::
set of options.
prog -a arg1 -b arg2
``enable_interspersed_args()``
Set parsing to not stop on the first non-option, allowing and treats it as equivalent to ::
interspersing switches with command arguments. For example,
``"-s arg1 --long arg2"`` would return ``["arg1", "arg2"]`` prog -a -b arg1 arg2
as the command arguments and ``-s, --long`` as options.
This is the default behavior. To disable this feature, call :meth:`disable_interspersed_args`. This
restores traditional Unix syntax, where option parsing stops with the first
``get_option(opt_str)`` non-option argument.
Returns the Option instance with the option string ``opt_str``, or ``None`` if
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
no options have that option string. no options have that option string.
``has_option(opt_str)`` .. method:: OptionParser.has_option(opt_str)
Return true if the OptionParser has an option with option string ``opt_str``
Return true if the OptionParser has an option with option string *opt_str*
(e.g., ``"-q"`` or ``"--verbose"``). (e.g., ``"-q"`` or ``"--verbose"``).
``remove_option(opt_str)`` .. 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 If the :class:`OptionParser` has an option corresponding to *opt_str*, that
strings become invalid. If ``opt_str`` does not occur in any option belonging to option is removed. If that option provided any other option strings, all of
this :class:`OptionParser`, raises :exc:`ValueError`. those option strings become invalid. If *opt_str* does not occur in any
option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
.. _optparse-conflicts-between-options: .. _optparse-conflicts-between-options:
...@@ -1257,10 +1305,11 @@ or with a separate call:: ...@@ -1257,10 +1305,11 @@ or with a separate call::
The available conflict handlers are: The available conflict handlers are:
``error`` (default) ``"error"`` (default)
assume option conflicts are a programming error and raise :exc:`OptionConflictError` assume option conflicts are a programming error and raise
:exc:`OptionConflictError`
``resolve`` ``"resolve"``
resolve option conflicts intelligently (see below) resolve option conflicts intelligently (see below)
...@@ -1306,9 +1355,10 @@ Cleanup ...@@ -1306,9 +1355,10 @@ Cleanup
OptionParser instances have several cyclic references. This should not be a 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 problem for Python's garbage collector, but you may wish to break the cyclic
references explicitly by calling ``destroy()`` on your OptionParser once you are references explicitly by calling :meth:`~OptionParser.destroy` on your
done with it. This is particularly useful in long-running applications where OptionParser once you are done with it. This is particularly useful in
large object graphs are reachable from your OptionParser. long-running applications where large object graphs are reachable from your
OptionParser.
.. _optparse-other-methods: .. _optparse-other-methods:
...@@ -1318,51 +1368,34 @@ Other methods ...@@ -1318,51 +1368,34 @@ Other methods
OptionParser supports several other public methods: OptionParser supports several other public methods:
* ``set_usage(usage)`` .. method:: OptionParser.set_usage(usage)
Set the usage string according to the rules described above for the ``usage`` Set the usage string according to the rules described above for the ``usage``
constructor keyword argument. Passing ``None`` sets the default usage string; constructor keyword argument. Passing ``None`` sets the default usage
use ``SUPPRESS_USAGE`` to suppress a usage message. string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
* ``enable_interspersed_args()``, ``disable_interspersed_args()`` .. method:: OptionParser.set_defaults(dest=value, ...)
Enable/disable positional arguments interspersed with options, similar to GNU Set default values for several option destinations at once. Using
getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both :meth:`set_defaults` is the preferred way to set default values for options,
simple options that take no arguments, :mod:`optparse` normally accepts this since multiple options can share the same destination. For example, if
syntax:: several "mode" options all set the same destination, any one of them can set
the default, and the last one wins::
prog -a arg1 -b arg2 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
and treats it as equivalent to :: To avoid this confusion, use :meth:`set_defaults`::
prog -a -b arg1 arg2 parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
To disable this feature, call ``disable_interspersed_args()``. This restores dest="mode", const="advanced")
traditional Unix syntax, where option parsing stops with the first non-option parser.add_option("--novice", action="store_const",
argument. dest="mode", const="novice")
* ``set_defaults(dest=value, ...)``
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::
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
To avoid this confusion, use :meth:`set_defaults`::
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")
.. _optparse-option-callbacks: .. _optparse-option-callbacks:
...@@ -1377,7 +1410,7 @@ cases. Quite often a simple callback is all you need. ...@@ -1377,7 +1410,7 @@ cases. Quite often a simple callback is all you need.
There are two steps to defining a callback option: There are two steps to defining a callback option:
* define the option itself using the ``callback`` action * define the option itself using the ``"callback"`` action
* write the callback; this is a function (or method) that takes at least four * write the callback; this is a function (or method) that takes at least four
arguments, as described below arguments, as described below
...@@ -1389,8 +1422,8 @@ Defining a callback option ...@@ -1389,8 +1422,8 @@ Defining a callback option
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
As always, the easiest way to define a callback option is by using the As always, the easiest way to define a callback option is by using the
``parser.add_option()`` method. Apart from :attr:`action`, the only option :meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
attribute you must specify is ``callback``, the function to call:: only option attribute you must specify is ``callback``, the function to call::
parser.add_option("-c", action="callback", callback=my_callback) parser.add_option("-c", action="callback", callback=my_callback)
...@@ -1404,8 +1437,9 @@ number of command-line arguments. This is where writing callbacks gets tricky; ...@@ -1404,8 +1437,9 @@ number of command-line arguments. This is where writing callbacks gets tricky;
it's covered later in this section. it's covered later in this section.
:mod:`optparse` always passes four particular arguments to your callback, and it :mod:`optparse` always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via ``callback_args`` will only pass additional arguments if you specify them via
and ``callback_kwargs``. Thus, the minimal callback function signature is:: :attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
minimal callback function signature is::
def my_callback(option, opt, value, parser): def my_callback(option, opt, value, parser):
...@@ -1414,21 +1448,22 @@ The four arguments to a callback are described below. ...@@ -1414,21 +1448,22 @@ The four arguments to a callback are described below.
There are several other option attributes that you can supply when you define a There are several other option attributes that you can supply when you define a
callback option: callback option:
:attr:`!type` :attr:`~Option.type`
has its usual meaning: as with the ``store`` or ``append`` actions, it instructs has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
:mod:`optparse` to consume one argument and convert it to :attr:`!type`. Rather instructs :mod:`optparse` to consume one argument and convert it to
than storing the converted value(s) anywhere, though, :mod:`optparse` passes it :attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
to your callback function. though, :mod:`optparse` passes it to your callback function.
``nargs`` :attr:`~Option.nargs`
also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
consume ``nargs`` arguments, each of which must be convertible to :attr:`!type`. consume :attr:`~Option.nargs` arguments, each of which must be convertible to
It then passes a tuple of converted values to your callback. :attr:`~Option.type`. It then passes a tuple of converted values to your
callback.
``callback_args`` :attr:`~Option.callback_args`
a tuple of extra positional arguments to pass to the callback a tuple of extra positional arguments to pass to the callback
``callback_kwargs`` :attr:`~Option.callback_kwargs`
a dictionary of extra keyword arguments to pass to the callback a dictionary of extra keyword arguments to pass to the callback
...@@ -1448,45 +1483,48 @@ where ...@@ -1448,45 +1483,48 @@ where
``opt_str`` ``opt_str``
is the option string seen on the command-line that's triggering the callback. 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 (If an abbreviated long option was used, ``opt_str`` will be the full,
option string---e.g. if the user puts ``"--foo"`` on the command-line as an canonical option string---e.g. if the user puts ``"--foo"`` on the
abbreviation for ``"--foobar"``, then ``opt_str`` will be ``"--foobar"``.) command-line as an abbreviation for ``"--foobar"``, then ``opt_str`` will be
``"--foobar"``.)
``value`` ``value``
is the argument to this option seen on the command-line. :mod:`optparse` will is the argument to this option seen on the command-line. :mod:`optparse` will
only expect an argument if :attr:`!type` is set; the type of ``value`` will be 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:`!type` for this option is 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 ``nargs`` ``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
> 1, ``value`` will be a tuple of values of the appropriate type. > 1, ``value`` will be a tuple of values of the appropriate type.
``parser`` ``parser``
is the OptionParser instance driving the whole thing, mainly useful because you is the OptionParser instance driving the whole thing, mainly useful because
can access some other interesting data through its instance attributes: you can access some other interesting data through its instance attributes:
``parser.largs`` ``parser.largs``
the current list of leftover arguments, ie. arguments that have been consumed the current list of leftover arguments, ie. arguments that have been
but are neither options nor option arguments. Feel free to modify 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 ``parser.largs``, e.g. by adding more arguments to it. (This list will
``args``, the second return value of :meth:`parse_args`.) become ``args``, the second return value of :meth:`parse_args`.)
``parser.rargs`` ``parser.rargs``
the current list of remaining arguments, ie. with ``opt_str`` and ``value`` (if the current list of remaining arguments, ie. with ``opt_str`` and
applicable) removed, and only the arguments following them still there. Feel ``value`` (if applicable) removed, and only the arguments following them
free to modify ``parser.rargs``, e.g. by consuming more arguments. still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
arguments.
``parser.values`` ``parser.values``
the object where option values are by default stored (an instance of the object where option values are by default stored (an instance of
optparse.OptionValues). This lets callbacks use the same mechanism as the rest optparse.OptionValues). This lets callbacks use the same mechanism as the
of :mod:`optparse` for storing option values; you don't need to mess around with rest of :mod:`optparse` for storing option values; you don't need to mess
globals or closures. You can also access or modify the value(s) of any options around with globals or closures. You can also access or modify the
already encountered on the command-line. value(s) of any options already encountered on the command-line.
``args`` ``args``
is a tuple of arbitrary positional arguments supplied via the ``callback_args`` is a tuple of arbitrary positional arguments supplied via the
option attribute. :attr:`~Option.callback_args` option attribute.
``kwargs`` ``kwargs``
is a dictionary of arbitrary keyword arguments supplied via ``callback_kwargs``. is a dictionary of arbitrary keyword arguments supplied via
:attr:`~Option.callback_kwargs`.
.. _optparse-raising-errors-in-callback: .. _optparse-raising-errors-in-callback:
...@@ -1494,11 +1532,11 @@ where ...@@ -1494,11 +1532,11 @@ where
Raising errors in a callback Raising errors in a callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The callback function should raise :exc:`OptionValueError` if there are any problems The callback function should raise :exc:`OptionValueError` if there are any
with the option or its argument(s). :mod:`optparse` catches this and terminates problems with the option or its argument(s). :mod:`optparse` catches this and
the program, printing the error message you supply to stderr. Your message terminates the program, printing the error message you supply to stderr. Your
should be clear, concise, accurate, and mention the option at fault. Otherwise, message should be clear, concise, accurate, and mention the option at fault.
the user will have a hard time figuring out what he did wrong. Otherwise, the user will have a hard time figuring out what he did wrong.
.. _optparse-callback-example-1: .. _optparse-callback-example-1:
...@@ -1514,7 +1552,7 @@ records that the option was seen:: ...@@ -1514,7 +1552,7 @@ records that the option was seen::
parser.add_option("--foo", action="callback", callback=record_foo_seen) parser.add_option("--foo", action="callback", callback=record_foo_seen)
Of course, you could do that with the ``store_true`` action. Of course, you could do that with the ``"store_true"`` action.
.. _optparse-callback-example-2: .. _optparse-callback-example-2:
...@@ -1581,12 +1619,12 @@ Callback example 5: fixed arguments ...@@ -1581,12 +1619,12 @@ Callback example 5: fixed arguments
Things get slightly more interesting when you define callback options that take Things get slightly more interesting when you define callback options that take
a fixed number of arguments. Specifying that a callback option takes arguments a fixed number of arguments. Specifying that a callback option takes arguments
is similar to defining a ``store`` or ``append`` option: if you define is similar to defining a ``"store"`` or ``"append"`` option: if you define
:attr:`!type`, then the option takes one argument that must be convertible to :attr:`~Option.type`, then the option takes one argument that must be
that type; if you further define ``nargs``, then the option takes ``nargs`` convertible to that type; if you further define :attr:`~Option.nargs`, then the
arguments. option takes :attr:`~Option.nargs` arguments.
Here's an example that just emulates the standard ``store`` action:: Here's an example that just emulates the standard ``"store"`` action::
def store_value(option, opt_str, value, parser): def store_value(option, opt_str, value, parser):
setattr(parser.values, option.dest, value) setattr(parser.values, option.dest, value)
...@@ -1673,32 +1711,36 @@ Adding new types ...@@ -1673,32 +1711,36 @@ Adding new types
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
To add new types, you need to define your own subclass of :mod:`optparse`'s To add new types, you need to define your own subclass of :mod:`optparse`'s
Option class. This class has a couple of attributes that define :class:`Option` class. This class has a couple of attributes that define
:mod:`optparse`'s types: :attr:`TYPES` and :attr:`TYPE_CHECKER`. :mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
:attr:`TYPES` is a tuple of type names; in your subclass, simply define a new .. attribute:: Option.TYPES
tuple :attr:`TYPES` that builds on the standard one.
:attr:`TYPE_CHECKER` is a dictionary mapping type names to type-checking A tuple of type names; in your subclass, simply define a new tuple
functions. A type-checking function has the following signature:: :attr:`TYPES` that builds on the standard one.
def check_mytype(option, opt, value) .. attribute:: Option.TYPE_CHECKER
where ``option`` is an :class:`Option` instance, ``opt`` is an option string A dictionary mapping type names to type-checking functions. A type-checking
(e.g., ``"-f"``), and ``value`` is the string from the command line that must be function has the following signature::
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 def check_mytype(option, opt, value)
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 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
parse Python-style complex numbers on the command line. (This is even sillier 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 than it used to be, because :mod:`optparse` 1.3 added built-in support for
complex numbers, but never mind.) complex numbers, but never mind.)
...@@ -1709,7 +1751,7 @@ First, the necessary imports:: ...@@ -1709,7 +1751,7 @@ First, the necessary imports::
from optparse import Option, OptionValueError from optparse import Option, OptionValueError
You need to define your type-checker first, since it's referred to later (in the You need to define your type-checker first, since it's referred to later (in the
:attr:`TYPE_CHECKER` class attribute of your Option subclass):: :attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
def check_complex(option, opt, value): def check_complex(option, opt, value):
try: try:
...@@ -1726,9 +1768,9 @@ Finally, the Option subclass:: ...@@ -1726,9 +1768,9 @@ Finally, the Option subclass::
TYPE_CHECKER["complex"] = check_complex TYPE_CHECKER["complex"] = check_complex
(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end (If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
up modifying the :attr:`TYPE_CHECKER` attribute of :mod:`optparse`'s Option up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
class. This being Python, nothing stops you from doing that except good manners Option class. This being Python, nothing stops you from doing that except good
and common sense.) manners and common sense.)
That's it! Now you can write a script that uses the new option type just like 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 any other :mod:`optparse`\ -based script, except you have to instruct your
...@@ -1755,45 +1797,50 @@ Adding new actions is a bit trickier, because you have to understand that ...@@ -1755,45 +1797,50 @@ Adding new actions is a bit trickier, because you have to understand that
"store" actions "store" actions
actions that result in :mod:`optparse` storing a value to an attribute of the actions that result in :mod:`optparse` storing a value to an attribute of the
current OptionValues instance; these options require a :attr:`dest` attribute to current OptionValues instance; these options require a :attr:`~Option.dest`
be supplied to the Option constructor attribute to be supplied to the Option constructor.
"typed" actions "typed" actions
actions that take a value from the command line and expect it to be of a certain actions that take a value from the command line and expect it to be of a
type; or rather, a string that can be converted to a certain type. These certain type; or rather, a string that can be converted to a certain type.
options require a :attr:`!type` attribute to the Option constructor. These options require a :attr:`~Option.type` attribute to the Option
constructor.
These are overlapping sets: some default "store" actions are ``store``, These are overlapping sets: some default "store" actions are ``"store"``,
``store_const``, ``append``, and ``count``, while the default "typed" actions ``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
are ``store``, ``append``, and ``callback``. actions are ``"store"``, ``"append"``, and ``"callback"``.
When you add an action, you need to categorize it by listing it in at least one 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): of the following class attributes of Option (all are lists of strings):
:attr:`ACTIONS` .. attribute:: Option.ACTIONS
all actions must be listed in ACTIONS
All actions must be listed in ACTIONS.
.. attribute:: Option.STORE_ACTIONS
"store" actions are additionally listed here.
.. attribute:: Option.TYPED_ACTIONS
:attr:`STORE_ACTIONS` "typed" actions are additionally listed here.
"store" actions are additionally listed here
:attr:`TYPED_ACTIONS` .. attribute:: Option.ALWAYS_TYPED_ACTIONS
"typed" actions are additionally listed here
``ALWAYS_TYPED_ACTIONS`` Actions that always take a type (i.e. whose options always take a value) are
actions that always take a type (i.e. whose options always take a value) are
additionally listed here. The only effect of this is that :mod:`optparse` additionally listed here. The only effect of this is that :mod:`optparse`
assigns the default type, ``string``, to options with no explicit type whose assigns the default type, ``"string"``, to options with no explicit type
action is listed in ``ALWAYS_TYPED_ACTIONS``. whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
In order to actually implement your new action, you must override Option's 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. :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 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 ``"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 and appending it to an existing list, ``"extend"`` will take multiple values in
single comma-delimited string, and extend an existing list with them. That is, a single comma-delimited string, and extend an existing list with them. That
if ``"--names"`` is an ``extend`` option of type ``string``, the command line is, if ``"--names"`` is an ``"extend"`` option of type ``"string"``, the command
:: line ::
--names=foo,bar --names blah --names ding,dong --names=foo,bar --names blah --names ding,dong
...@@ -1820,29 +1867,30 @@ Again we define a subclass of Option:: ...@@ -1820,29 +1867,30 @@ Again we define a subclass of Option::
Features of note: Features of note:
* ``extend`` both expects a value on the command-line and stores that value * ``"extend"`` both expects a value on the command-line and stores that value
somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS` somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
:attr:`~Option.TYPED_ACTIONS`.
* to ensure that :mod:`optparse` assigns the default type of ``string`` to * to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as ``"extend"`` actions, we put the ``"extend"`` action in
well :attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
* :meth:`MyOption.take_action` implements just this one new action, and passes * :meth:`MyOption.take_action` implements just this one new action, and passes
control back to :meth:`Option.take_action` for the standard :mod:`optparse` control back to :meth:`Option.take_action` for the standard :mod:`optparse`
actions actions.
* ``values`` is an instance of the optparse_parser.Values class, which * ``values`` is an instance of the optparse_parser.Values class, which provides
provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
essentially :func:`getattr` with a safety valve; it is called as :: essentially :func:`getattr` with a safety valve; it is called as ::
values.ensure_value(attr, value) values.ensure_value(attr, value)
If the ``attr`` attribute of ``values`` doesn't exist or is None, then 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 ensure_value() first sets it to ``value``, and then returns 'value. This is
handy for actions like ``extend``, ``append``, and ``count``, all of which very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
accumulate data in a variable and expect that variable to be of a certain type of which accumulate data in a variable and expect that variable to be of a
(a list for the first two, an integer for the latter). Using certain type (a list for the first two, an integer for the latter). Using
:meth:`ensure_value` means that scripts using your action don't have to worry :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 about setting a default value for the option destinations in question; they
just leave the default as None and :meth:`ensure_value` will take care of can just leave the default as None and :meth:`ensure_value` will take care of
getting it right when it's needed. getting it right when it's needed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7