n | .. % THIS FILE IS AUTO-GENERATED! DO NOT EDIT! |
| .. % (Your changes will be lost the next time it is generated.) |
| |
| |
| :mod:`optparse` --- More powerful command line option parser |
| ============================================================ |
| |
| .. module:: optparse |
| :synopsis: More convenient, flexible, and powerful command-line parsing library. |
| .. moduleauthor:: Greg Ward <gward@python.net> |
| |
| |
| .. versionadded:: 2.3 |
| |
| .. sectionauthor:: Greg Ward <gward@python.net> |
| |
| |
| ``optparse`` is a more convenient, flexible, and powerful library for parsing |
n | command-line options than ``getopt``. ``optparse`` uses a more declarative |
n | command-line options than the old :mod:`getopt` module. ``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. ``optparse`` allows users |
| to specify options in the conventional GNU/POSIX syntax, and additionally |
| generates usage and help messages for you. |
n | |
| .. % An intro blurb used only when generating LaTeX docs for the Python |
| .. % manual (based on README.txt). |
| |
| Here's an example of using ``optparse`` in a simple script:: |
| |
| from optparse import OptionParser |
| [...] |
| parser = OptionParser() |
| parser.add_option("-f", "--file", dest="filename", |
| help="write report to FILE", metavar="FILE") |
| (``sys.argv[0]`` is the name of the program being executed). Unix shells also |
| use the term "word". |
| |
| 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:]``". |
| |
n | option |
n | 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`. |
| |
| Some other option syntaxes that the world has seen include: |
| |
n | * a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same |
n | * a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same |
| as multiple options merged into a single argument) |
| |
n | * a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically |
n | * a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically |
| equivalent to the previous syntax, but they aren't usually seen in the same |
| program) |
| |
n | * a plus sign followed by a single letter, or a few letters, or a word, e.g. |
n | * a plus sign followed by a single letter, or a few letters, or a word, e.g. |
| ``"+f"``, ``"+rgb"`` |
| |
n | * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, |
n | * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, |
| ``"/file"`` |
| |
| 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. |
| |
| option argument |
| |
| (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: |
| |
n | * ``options``, an object containing values for all of your options---e.g. if |
n | * ``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 |
| filename supplied by the user, or ``None`` if the user did not supply that |
| option |
| |
n | * ``args``, the list of positional arguments leftover after parsing options |
n | * ``args``, the list of positional arguments leftover after parsing options |
| |
| This tutorial section only covers the four most important option attributes: |
| :attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of |
| these, :attr:`action` is the most fundamental. |
| |
| |
| .. _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 |
n | :ref:`optparse-extending-optparse`, Extending :mod:`optparse`. Most actions tell |
n | :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``. |
| |
| If you don't specify an option action, :mod:`optparse` defaults to ``store``. |
| |
| |
| .. _optparse-store-action: |
| |
| .. _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:`help` value for each option, and optionally a short usage |
n | message for your whole program. Here's an OptionParser populated with user- |
n | message for your whole program. Here's an OptionParser populated with |
| friendly (documented) options:: |
| 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", |
n | action="store_false", dest="verbose", |
n | action="store_false", dest="verbose", |
| help="be vewwy quiet (I'm hunting wabbits)") |
| parser.add_option("-f", "--filename", |
| metavar="FILE", help="write output to FILE"), |
| parser.add_option("-m", "--mode", |
| default="intermediate", |
| help="interaction mode: novice, intermediate, " |
| "or expert [default: %default]") |
| |
n | If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the command- |
n | If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the |
| line, or if you just call :meth:`parser.print_help`, it prints the following to |
| command-line, or if you just call :meth:`parser.print_help`, it prints the |
| standard output:: |
| following to standard output:: |
| |
| 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 |
| 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: |
| |
n | * the script defines its own usage message:: |
n | * 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. |
| |
| If you don't supply a usage string, :mod:`optparse` uses a bland but sensible |
n | default: "``usage: %prog [options]"``, which is fine if your script doesn't take |
n | default: ``"usage: %prog [options]"``, which is fine if your script doesn't take |
| any positional arguments. |
| |
n | * every option defines a help string, and doesn't worry about line- |
n | * every option defines a help string, and doesn't worry about line-wrapping--- |
| wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help |
| :mod:`optparse` takes care of wrapping lines and making the help output look |
| output look good. |
| good. |
| |
n | * options that take a value indicate this fact in their automatically- |
n | * options that take a value indicate this fact in their automatically-generated |
| generated help message, e.g. for the "mode" option:: |
| 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 :option:`-m`/:option:`--mode`. By default, |
| :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 :option:`--filename` option explicitly sets ``metavar="FILE"``, resulting in |
| -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. |
| |
n | .. versionadded:: 2.4 |
| * 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``. |
| |
n | 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. |
| |
| Continuing with the parser defined above, adding an |
| :class:`OptionGroup` to a parser is easy:: |
| |
| group = OptionGroup(parser, "Dangerous Options", |
| "Caution: use these options at your own risk. " |
| "It is believed that some of them bite.") |
| group.add_option("-g", action="store_true", help="Group option.") |
| parser.add_option_group(group) |
| |
| This would result in the following help output:: |
| |
| usage: [options] arg1 arg2 |
| |
| options: |
| -h, --help show this help message and exit |
| -v, --verbose make lots of noise [default] |
| -q, --quiet be vewwy quiet (I'm hunting wabbits) |
| -fFILE, --file=FILE write output to FILE |
| -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate' |
| [default], 'expert' |
| |
| Dangerous Options: |
| Caution: use of these options is at your own risk. It is believed that |
| some of them bite. |
| -g Group option. |
| |
| .. _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`` |
| -f foo.txt -p 1 -3.5 4 -fbar.txt |
| |
| :mod:`optparse` will set :: |
| |
| options.f = "foo.txt" |
| options.point = (1.0, -3.5, 4.0) |
| options.f = "bar.txt" |
| |
n | * ``store_const`` [required: ``const``; relevant: :attr:`dest`] |
n | * ``store_const`` [required: ``const``; relevant: :attr:`dest`] |
| |
| The value ``const`` is stored in :attr:`dest`. |
| |
| 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 :: |
| |
| options.verbose = 2 |
| |
n | * ``store_true`` [relevant: :attr:`dest`] |
n | * ``store_true`` [relevant: :attr:`dest`] |
| |
| A special case of ``store_const`` that stores a true value to :attr:`dest`. |
| |
n | * ``store_false`` [relevant: :attr:`dest`] |
n | * ``store_false`` [relevant: :attr:`dest`] |
| |
| Like ``store_true``, but stores a false value. |
| |
| Example:: |
| |
| parser.add_option("--clobber", action="store_true", dest="clobber") |
| parser.add_option("--no-clobber", action="store_false", dest="clobber") |
| |
n | * ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] |
n | * ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] |
| |
| 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 |
| is automatically created when :mod:`optparse` first encounters this option on |
| the command-line. If ``nargs`` > 1, multiple arguments are consumed, and a |
| tuple of length ``nargs`` is appended to :attr:`dest`. |
| |
| The defaults for :attr:`type` and :attr:`dest` are the same as for the ``store`` |
| .. _optparse-option-attributes: |
| |
| Option attributes |
| ^^^^^^^^^^^^^^^^^ |
| |
| The following option attributes may be passed as keyword arguments to |
| ``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, |
n | :mod:`optparse` raises OptionError. |
n | :mod:`optparse` raises :exc:`OptionError`. |
| |
n | * :attr:`action` (default: ``"store"``) |
n | * :attr:`action` (default: ``"store"``) |
| |
| Determines :mod:`optparse`'s behaviour when this option is seen on the command |
| line; the available options are documented above. |
| |
n | * :attr:`type` (default: ``"string"``) |
n | * :attr:`type` (default: ``"string"``) |
| |
| The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the |
| available option types are documented below. |
| |
n | * :attr:`dest` (default: derived from option strings) |
n | * :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. |
| |
n | * ``default`` (deprecated) |
n | * ``default`` (deprecated) |
| |
| The value to use for this option's destination if the option is not seen on the |
| command line. Deprecated; use ``parser.set_defaults()`` instead. |
| |
n | * ``nargs`` (default: 1) |
n | * ``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`. |
| |
n | * ``const`` |
n | * ``const`` |
| |
| For actions that store a constant value, the constant value to store. |
| |
n | * ``choices`` |
n | * ``choices`` |
| |
| For options of type ``"choice"``, the list of strings the user may choose from. |
| |
n | * ``callback`` |
n | * ``callback`` |
| |
n | For options with action ``"callback"``, the callable to call when this option is |
n | For options with action ``"callback"``, the callable to call when this option |
| seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail |
| is seen. See section :ref:`optparse-option-callbacks` for detail on the |
| on the arguments passed to ``callable``. |
| arguments passed to ``callable``. |
| |
n | * ``callback_args``, ``callback_kwargs`` |
n | * ``callback_args``, ``callback_kwargs`` |
| |
| Additional positional and keyword arguments to pass to ``callback`` after the |
| four standard callback arguments. |
| |
n | * :attr:`help` |
n | * :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``. |
| |
n | * ``metavar`` (default: derived from option strings) |
n | * ``metavar`` (default: derived from option strings) |
| |
| Stand-in for the option argument(s) to use when printing help text. See section |
n | :ref:`optparse-tutorial`, the tutorial for an example. |
n | :ref:`optparse-tutorial` for an example. |
| |
| |
| .. _optparse-standard-option-types: |
| |
| Standard option types |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``, |
| ``choice``, ``float`` and ``complex``. If you need to add new option types, see |
n | section :ref:`optparse-extending-optparse`, Extending :mod:`optparse`. |
n | section :ref:`optparse-extending-optparse`. |
| |
| Arguments to string options are not checked or converted in any way: the text on |
| the command line is stored in the destination (or passed to the callback) as-is. |
| |
| Integer arguments (type ``int`` or ``long``) are parsed as follows: |
| |
n | * if the number starts with ``0x``, it is parsed as a hexadecimal number |
n | * if the number starts with ``0x``, it is parsed as a hexadecimal number |
| |
n | * if the number starts with ``0``, it is parsed as an octal number |
n | * if the number starts with ``0``, it is parsed as an octal number |
| |
n | * if the number starts with ``0b``, is is parsed as a binary number |
n | * if the number starts with ``0b``, it is parsed as a binary number |
| |
n | * otherwise, the number is parsed as a decimal number |
n | * otherwise, the number is parsed as a decimal number |
| |
| |
| The conversion is done by calling either ``int()`` or ``long()`` with the |
| appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`, |
| although with a more useful error message. |
| |
| ``float`` and ``complex`` option arguments are converted directly with |
| ``float()`` and ``complex()``, with similar error-handling. |
| |
| ``choice`` options are a subtype of ``string`` options. The ``choices`` option |
| attribute (a sequence of strings) defines the set of allowed option arguments. |
| ``optparse.check_choice()`` compares user-supplied option arguments against this |
n | master list and raises OptionValueError if an invalid string is given. |
n | master list and raises :exc:`OptionValueError` if an invalid string is given. |
| |
| |
| .. _optparse-parsing-arguments: |
| |
| Parsing arguments |
| ^^^^^^^^^^^^^^^^^ |
| |
| The whole point of creating and populating an OptionParser is to call its |
| :meth:`parse_args` method:: |
| |
n | (options, args) = parser.parse_args(args=None, options=None) |
n | (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:]``) |
| |
n | ``options`` |
n | ``values`` |
| object to store option arguments in (default: a new instance of optparse.Values) |
| |
| and the return values are |
| |
| ``options`` |
| the same object that was passed in as ``options``, or the optparse.Values |
| instance created by :mod:`optparse` |
| |
| traditional Unix exit status for command-line errors). |
| |
| |
| .. _optparse-querying-manipulating-option-parser: |
| |
| Querying and manipulating your option parser |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
n | The default behavior of the option parser can be customized slightly, |
| Sometimes, it's useful to poke around your option parser and see what's there. |
| and you can also poke around your option parser and see what's there. |
| OptionParser provides a couple of methods to help you out: |
| OptionParser provides several methods to help you out: |
| |
n | ``has_option(opt_str)`` |
n | ``disable_interspersed_args()`` |
| Return true if the OptionParser has an option with option string ``opt_str`` |
| Set parsing to stop on the first non-option. Use this if you have a |
| (e.g., ``"-q"`` or ``"--verbose"``). |
| 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. |
| |
| ``enable_interspersed_args()`` |
| Set parsing to not stop on the first non-option, allowing |
| interspersing switches with command arguments. For example, |
| ``"-s arg1 --long arg2"`` would return ``["arg1", "arg2"]`` |
| as the command arguments and ``-s, --long`` as options. |
| This is the default behavior. |
| |
| ``get_option(opt_str)`` |
| Returns the Option instance with the option string ``opt_str``, or ``None`` if |
| no options have that option string. |
| |
n | ``has_option(opt_str)`` |
| Return true if the OptionParser has an option with option string ``opt_str`` |
| (e.g., ``"-q"`` or ``"--verbose"``). |
| |
| ``remove_option(opt_str)`` |
n | If the OptionParser has an option corresponding to ``opt_str``, that option is |
n | 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 |
n | this OptionParser, raises ValueError. |
n | this :class:`OptionParser`, raises :exc:`ValueError`. |
| |
| |
| .. _optparse-conflicts-between-options: |
| |
| Conflicts between options |
| ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If you're not careful, it's easy to define options with conflicting option |
| |
| .. _optparse-other-methods: |
| |
| Other methods |
| ^^^^^^^^^^^^^ |
| |
| OptionParser supports several other public methods: |
| |
n | * ``set_usage(usage)`` |
n | * ``set_usage(usage)`` |
| |
| Set the usage string according to the rules described above for the ``usage`` |
| constructor keyword argument. Passing ``None`` sets the default usage string; |
| use ``SUPPRESS_USAGE`` to suppress a usage message. |
| |
n | * ``enable_interspersed_args()``, ``disable_interspersed_args()`` |
n | * ``enable_interspersed_args()``, ``disable_interspersed_args()`` |
| |
| Enable/disable positional arguments interspersed with options, similar to GNU |
| getopt (enabled by default). 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 ``disable_interspersed_args()``. This restores |
| traditional Unix syntax, where option parsing stops with the first non-option |
| argument. |
| |
n | * ``set_defaults(dest=value, ...)`` |
n | * ``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", |
| 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") |
| |
n | .. % $Id: reference.txt 519 2006-06-11 14:39:11Z gward $ |
| |
| |
| .. _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: |
| |
n | * define the option itself using the ``callback`` action |
n | * define the option itself using the ``callback`` action |
| |
n | * write the callback; this is a function (or method) that takes at least four |
n | * 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 |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| is a dictionary of arbitrary keyword arguments supplied via ``callback_kwargs``. |
| |
| |
| .. _optparse-raising-errors-in-callback: |
| |
| Raising errors in a callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
n | The callback function should raise OptionValueError if there are any problems |
n | 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. |
| |
| |
| .. _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): |
n | parser.saw_foo = True |
n | parser.values.saw_foo = True |
| |
| parser.add_option("--foo", action="callback", callback=record_foo_seen) |
| |
| Of course, you could do that with the ``store_true`` action. |
| |
| |
| .. _optparse-callback-example-2: |
| |
| |
| 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: |
| |
n | * either ``"--"`` or ``"-"`` can be option arguments |
n | * either ``"--"`` or ``"-"`` can be option arguments |
| |
n | * bare ``"--"`` (if not the argument to some option): halt command-line |
n | * bare ``"--"`` (if not the argument to some option): halt command-line |
| processing and discard the ``"--"`` |
| |
n | * bare ``"-"`` (if not the argument to some option): halt command-line |
n | * bare ``"-"`` (if not the argument to some option): halt command-line |
| processing but keep the ``"-"`` (append it to ``parser.largs``) |
| |
| 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:: |
| |
n | def vararg_callback(option, opt_str, value, parser): |
n | def vararg_callback(option, opt_str, value, parser): |
| assert value is None |
| assert value is None |
| done = 0 |
| value = [] |
| value = [] |
| |
| def floatable(str): |
| try: |
| float(str) |
| return True |
| except ValueError: |
| return False |
| |
| rargs = parser.rargs |
| for arg in parser.rargs: |
| while rargs: |
| # stop on --foo like options |
| arg = rargs[0] |
| |
| # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f", |
| # etc. Note that this also stops on "-3" or "-3.0", so if |
| # your option takes numeric values, you will need to handle |
| # this. |
| if ((arg[:2] == "--" and len(arg) > 2) or |
| if arg[:2] == "--" and len(arg) > 2: |
| (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")): |
| break |
| break |
| else: |
| # 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) |
| value.append(arg) |
| del rargs[0] |
| |
n | del parser.rargs[:len(value)] |
| setattr(parser.values, option.dest, value) |
| |
| [...] |
n | parser.add_option("-c", "--callback", |
n | parser.add_option("-c", "--callback", dest="vararg_attr", |
| action="callback", callback=varargs) |
| action="callback", callback=vararg_callback) |
| |
| The main weakness with this particular implementation is that negative numbers |
| in the arguments following ``"-c"`` will be interpreted as further options |
| (probably causing an error), rather than as arguments to ``"-c"``. Fixing this |
| is left as an exercise for the reader. |
| |
| .. % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $ |
| |
| |
| .. _optparse-extending-optparse: |
| |
| Extending :mod:`optparse` |
| ------------------------- |
| |
| Since the two major controlling factors in how :mod:`optparse` interprets |
| :attr:`TYPE_CHECKER` is a dictionary mapping type names to type-checking |
| functions. A type-checking function has the following signature:: |
| |
| def check_mytype(option, opt, value) |
| |
| 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 |
n | object of the hypothetical type ``mytype``. The value returned by a type- |
n | object of the hypothetical type ``mytype``. The value returned by a |
| checking function will wind up in the OptionValues instance returned by |
| 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. |
| |
n | Your type-checking function should raise OptionValueError if it encounters any |
n | Your type-checking function should raise :exc:`OptionValueError` if it encounters any |
| problems. OptionValueError takes a single string argument, which is passed as- |
| problems. :exc:`OptionValueError` takes a single string argument, which is passed |
| is to OptionParser's :meth:`error` method, which in turn prepends the program |
| 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 |
| than it used to be, because :mod:`optparse` 1.3 added built-in support for |
| complex numbers, but never mind.) |
| |
| lvalue = value.split(",") |
| values.ensure_value(dest, []).extend(lvalue) |
| else: |
| Option.take_action( |
| self, action, dest, opt, value, values, parser) |
| |
| Features of note: |
| |
n | * ``extend`` both expects a value on the command-line and stores that value |
n | * ``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` |
| |
n | * to ensure that :mod:`optparse` assigns the default type of ``string`` to |
n | * to ensure that :mod:`optparse` assigns the default type of ``string`` to |
| ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as |
| well |
| |
n | * :meth:`MyOption.take_action` implements just this one new action, and passes |
n | * :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 |
| |
n | * ``values`` is an instance of the optparse_parser.Values class, which |
n | * ``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 :: |
| |
| 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 |
| :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 |
| getting it right when it's needed. |
t | |
| .. % $Id: extending.txt 517 2006-06-10 16:18:11Z gward $ |
| |