1
:mod:`optparse` --- More powerful command line option parser
2
============================================================
5
:synopsis: More convenient, flexible, and powerful command-line parsing library.
6
.. moduleauthor:: Greg Ward <gward@python.net>
7
.. sectionauthor:: Greg Ward <gward@python.net>
10
``optparse`` is a more convenient, flexible, and powerful library for parsing
11
command-line options than the old :mod:`getopt` module. ``optparse`` uses a more declarative
12
style of command-line parsing: you create an instance of :class:`OptionParser`,
13
populate it with options, and parse the command line. ``optparse`` allows users
14
to specify options in the conventional GNU/POSIX syntax, and additionally
15
generates usage and help messages for you.
17
Here's an example of using ``optparse`` in a simple script::
19
from optparse import OptionParser
21
parser = OptionParser()
22
parser.add_option("-f", "--file", dest="filename",
23
help="write report to FILE", metavar="FILE")
24
parser.add_option("-q", "--quiet",
25
action="store_false", dest="verbose", default=True,
26
help="don't print status messages to stdout")
28
(options, args) = parser.parse_args()
30
With these few lines of code, users of your script can now do the "usual thing"
31
on the command-line, for example::
33
<yourscript> --file=outfile -q
35
As it parses the command line, ``optparse`` sets attributes of the ``options``
36
object returned by :meth:`parse_args` based on user-supplied command-line
37
values. When :meth:`parse_args` returns from parsing this command line,
38
``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
39
``False``. ``optparse`` supports both long and short options, allows short
40
options to be merged together, and allows options to be associated with their
41
arguments in a variety of ways. Thus, the following command lines are all
42
equivalent to the above example::
44
<yourscript> -f outfile --quiet
45
<yourscript> --quiet --file outfile
46
<yourscript> -q -foutfile
47
<yourscript> -qfoutfile
49
Additionally, users can run one of ::
54
and ``optparse`` will print out a brief summary of your script's options::
56
usage: <yourscript> [options]
59
-h, --help show this help message and exit
60
-f FILE, --file=FILE write report to FILE
61
-q, --quiet don't print status messages to stdout
63
where the value of *yourscript* is determined at runtime (normally from
67
.. _optparse-background:
72
:mod:`optparse` was explicitly designed to encourage the creation of programs
73
with straightforward, conventional command-line interfaces. To that end, it
74
supports only the most common command-line syntax and semantics conventionally
75
used under Unix. If you are unfamiliar with these conventions, read this
76
section to acquaint yourself with them.
79
.. _optparse-terminology:
85
a string entered on the command-line, and passed by the shell to ``execl()`` or
86
``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
87
(``sys.argv[0]`` is the name of the program being executed). Unix shells also
90
It is occasionally desirable to substitute an argument list other than
91
``sys.argv[1:]``, so you should read "argument" as "an element of
92
``sys.argv[1:]``, or of some other list provided as a substitute for
96
an argument used to supply extra information to guide or customize the execution
97
of a program. There are many different syntaxes for options; the traditional
98
Unix syntax is a hyphen ("-") followed by a single letter, e.g. ``"-x"`` or
99
``"-F"``. Also, traditional Unix syntax allows multiple options to be merged
100
into a single argument, e.g. ``"-x -F"`` is equivalent to ``"-xF"``. The GNU
101
project introduced ``"--"`` followed by a series of hyphen-separated words, e.g.
102
``"--file"`` or ``"--dry-run"``. These are the only two option syntaxes
103
provided by :mod:`optparse`.
105
Some other option syntaxes that the world has seen include:
107
* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same
108
as multiple options merged into a single argument)
110
* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically
111
equivalent to the previous syntax, but they aren't usually seen in the same
114
* a plus sign followed by a single letter, or a few letters, or a word, e.g.
117
* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
120
These option syntaxes are not supported by :mod:`optparse`, and they never will
121
be. This is deliberate: the first three are non-standard on any environment,
122
and the last only makes sense if you're exclusively targeting VMS, MS-DOS,
126
an argument that follows an option, is closely associated with that option, and
127
is consumed from the argument list when that option is. With :mod:`optparse`,
128
option arguments may either be in a separate argument from their option::
133
or included in the same argument::
138
Typically, a given option either takes an argument or it doesn't. Lots of people
139
want an "optional option arguments" feature, meaning that some options will take
140
an argument if they see it, and won't if they don't. This is somewhat
141
controversial, because it makes parsing ambiguous: if ``"-a"`` takes an optional
142
argument and ``"-b"`` is another option entirely, how do we interpret ``"-ab"``?
143
Because of this ambiguity, :mod:`optparse` does not support this feature.
146
something leftover in the argument list after options have been parsed, i.e.
147
after options and their arguments have been parsed and removed from the argument
151
an option that must be supplied on the command-line; note that the phrase
152
"required option" is self-contradictory in English. :mod:`optparse` doesn't
153
prevent you from implementing required options, but doesn't give you much help
154
at it either. See ``examples/required_1.py`` and ``examples/required_2.py`` in
155
the :mod:`optparse` source distribution for two ways to implement required
156
options with :mod:`optparse`.
158
For example, consider this hypothetical command-line::
160
prog -v --report /tmp/report.txt foo bar
162
``"-v"`` and ``"--report"`` are both options. Assuming that :option:`--report`
163
takes one argument, ``"/tmp/report.txt"`` is an option argument. ``"foo"`` and
164
``"bar"`` are positional arguments.
167
.. _optparse-what-options-for:
169
What are options for?
170
^^^^^^^^^^^^^^^^^^^^^
172
Options are used to provide extra information to tune or customize the execution
173
of a program. In case it wasn't clear, options are usually *optional*. A
174
program should be able to run just fine with no options whatsoever. (Pick a
175
random program from the Unix or GNU toolsets. Can it run without any options at
176
all and still make sense? The main exceptions are ``find``, ``tar``, and
177
``dd``\ ---all of which are mutant oddballs that have been rightly criticized
178
for their non-standard syntax and confusing interfaces.)
180
Lots of people want their programs to have "required options". Think about it.
181
If it's required, then it's *not optional*! If there is a piece of information
182
that your program absolutely requires in order to run successfully, that's what
183
positional arguments are for.
185
As an example of good command-line interface design, consider the humble ``cp``
186
utility, for copying files. It doesn't make much sense to try to copy files
187
without supplying a destination and at least one source. Hence, ``cp`` fails if
188
you run it with no arguments. However, it has a flexible, useful syntax that
189
does not require any options at all::
192
cp SOURCE ... DEST-DIR
194
You can get pretty far with just that. Most ``cp`` implementations provide a
195
bunch of options to tweak exactly how the files are copied: you can preserve
196
mode and modification time, avoid following symlinks, ask before clobbering
197
existing files, etc. But none of this distracts from the core mission of
198
``cp``, which is to copy either one file to another, or several files to another
202
.. _optparse-what-positional-arguments-for:
204
What are positional arguments for?
205
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
207
Positional arguments are for those pieces of information that your program
208
absolutely, positively requires to run.
210
A good user interface should have as few absolute requirements as possible. If
211
your program requires 17 distinct pieces of information in order to run
212
successfully, it doesn't much matter *how* you get that information from the
213
user---most people will give up and walk away before they successfully run the
214
program. This applies whether the user interface is a command-line, a
215
configuration file, or a GUI: if you make that many demands on your users, most
216
of them will simply give up.
218
In short, try to minimize the amount of information that users are absolutely
219
required to supply---use sensible defaults whenever possible. Of course, you
220
also want to make your programs reasonably flexible. That's what options are
221
for. Again, it doesn't matter if they are entries in a config file, widgets in
222
the "Preferences" dialog of a GUI, or command-line options---the more options
223
you implement, the more flexible your program is, and the more complicated its
224
implementation becomes. Too much flexibility has drawbacks as well, of course;
225
too many options can overwhelm users and make your code much harder to maintain.
228
.. _optparse-tutorial:
233
While :mod:`optparse` is quite flexible and powerful, it's also straightforward
234
to use in most cases. This section covers the code patterns that are common to
235
any :mod:`optparse`\ -based program.
237
First, you need to import the OptionParser class; then, early in the main
238
program, create an OptionParser instance::
240
from optparse import OptionParser
242
parser = OptionParser()
244
Then you can start defining options. The basic syntax is::
246
parser.add_option(opt_str, ...,
249
Each option has one or more option strings, such as ``"-f"`` or ``"--file"``,
250
and several option attributes that tell :mod:`optparse` what to expect and what
251
to do when it encounters that option on the command line.
253
Typically, each option will have one short option string and one long option
256
parser.add_option("-f", "--file", ...)
258
You're free to define as many short option strings and as many long option
259
strings as you like (including zero), as long as there is at least one option
262
The option strings passed to :meth:`add_option` are effectively labels for the
263
option defined by that call. For brevity, we will frequently refer to
264
*encountering an option* on the command line; in reality, :mod:`optparse`
265
encounters *option strings* and looks up options from them.
267
Once all of your options are defined, instruct :mod:`optparse` to parse your
268
program's command line::
270
(options, args) = parser.parse_args()
272
(If you like, you can pass a custom argument list to :meth:`parse_args`, but
273
that's rarely necessary: by default it uses ``sys.argv[1:]``.)
275
:meth:`parse_args` returns two values:
277
* ``options``, an object containing values for all of your options---e.g. if
278
``"--file"`` takes a single string argument, then ``options.file`` will be the
279
filename supplied by the user, or ``None`` if the user did not supply that
282
* ``args``, the list of positional arguments leftover after parsing options
284
This tutorial section only covers the four most important option attributes:
285
:attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of
286
these, :attr:`action` is the most fundamental.
289
.. _optparse-understanding-option-actions:
291
Understanding option actions
292
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
294
Actions tell :mod:`optparse` what to do when it encounters an option on the
295
command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
296
adding new actions is an advanced topic covered in section
297
:ref:`optparse-extending-optparse`. Most actions tell
298
:mod:`optparse` to store a value in some variable---for example, take a string
299
from the command line and store it in an attribute of ``options``.
301
If you don't specify an option action, :mod:`optparse` defaults to ``store``.
304
.. _optparse-store-action:
309
The most common option action is ``store``, which tells :mod:`optparse` to take
310
the next argument (or the remainder of the current argument), ensure that it is
311
of the correct type, and store it to your chosen destination.
315
parser.add_option("-f", "--file",
316
action="store", type="string", dest="filename")
318
Now let's make up a fake command line and ask :mod:`optparse` to parse it::
320
args = ["-f", "foo.txt"]
321
(options, args) = parser.parse_args(args)
323
When :mod:`optparse` sees the option string ``"-f"``, it consumes the next
324
argument, ``"foo.txt"``, and stores it in ``options.filename``. So, after this
325
call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
327
Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
328
Here's an option that expects an integer argument::
330
parser.add_option("-n", type="int", dest="num")
332
Note that this option has no long option string, which is perfectly acceptable.
333
Also, there's no explicit action, since the default is ``store``.
335
Let's parse another fake command-line. This time, we'll jam the option argument
336
right up against the option: since ``"-n42"`` (one argument) is equivalent to
337
``"-n 42"`` (two arguments), the code ::
339
(options, args) = parser.parse_args(["-n42"])
344
If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
345
the fact that the default action is ``store``, that means our first example can
348
parser.add_option("-f", "--file", dest="filename")
350
If you don't supply a destination, :mod:`optparse` figures out a sensible
351
default from the option strings: if the first long option string is
352
``"--foo-bar"``, then the default destination is ``foo_bar``. If there are no
353
long option strings, :mod:`optparse` looks at the first short option string: the
354
default destination for ``"-f"`` is ``f``.
356
:mod:`optparse` also includes the built-in ``complex`` type. Adding
357
types is covered in section :ref:`optparse-extending-optparse`.
360
.. _optparse-handling-boolean-options:
362
Handling boolean (flag) options
363
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
365
Flag options---set a variable to true or false when a particular option is seen
366
---are quite common. :mod:`optparse` supports them with two separate actions,
367
``store_true`` and ``store_false``. For example, you might have a ``verbose``
368
flag that is turned on with ``"-v"`` and off with ``"-q"``::
370
parser.add_option("-v", action="store_true", dest="verbose")
371
parser.add_option("-q", action="store_false", dest="verbose")
373
Here we have two different options with the same destination, which is perfectly
374
OK. (It just means you have to be a bit careful when setting default values---
377
When :mod:`optparse` encounters ``"-v"`` on the command line, it sets
378
``options.verbose`` to ``True``; when it encounters ``"-q"``,
379
``options.verbose`` is set to ``False``.
382
.. _optparse-other-actions:
387
Some other actions supported by :mod:`optparse` are:
390
store a constant value
393
append this option's argument to a list
396
increment a counter by one
399
call a specified function
401
These are covered in section :ref:`optparse-reference-guide`, Reference Guide
402
and section :ref:`optparse-option-callbacks`.
405
.. _optparse-default-values:
410
All of the above examples involve setting some variable (the "destination") when
411
certain command-line options are seen. What happens if those options are never
412
seen? Since we didn't supply any defaults, they are all set to ``None``. This
413
is usually fine, but sometimes you want more control. :mod:`optparse` lets you
414
supply a default value for each destination, which is assigned before the
415
command line is parsed.
417
First, consider the verbose/quiet example. If we want :mod:`optparse` to set
418
``verbose`` to ``True`` unless ``"-q"`` is seen, then we can do this::
420
parser.add_option("-v", action="store_true", dest="verbose", default=True)
421
parser.add_option("-q", action="store_false", dest="verbose")
423
Since default values apply to the *destination* rather than to any particular
424
option, and these two options happen to have the same destination, this is
427
parser.add_option("-v", action="store_true", dest="verbose")
428
parser.add_option("-q", action="store_false", dest="verbose", default=True)
432
parser.add_option("-v", action="store_true", dest="verbose", default=False)
433
parser.add_option("-q", action="store_false", dest="verbose", default=True)
435
Again, the default value for ``verbose`` will be ``True``: the last default
436
value supplied for any particular destination is the one that counts.
438
A clearer way to specify default values is the :meth:`set_defaults` method of
439
OptionParser, which you can call at any time before calling :meth:`parse_args`::
441
parser.set_defaults(verbose=True)
442
parser.add_option(...)
443
(options, args) = parser.parse_args()
445
As before, the last value specified for a given option destination is the one
446
that counts. For clarity, try to use one method or the other of setting default
450
.. _optparse-generating-help:
455
:mod:`optparse`'s ability to generate help and usage text automatically is
456
useful for creating user-friendly command-line interfaces. All you have to do
457
is supply a :attr:`help` value for each option, and optionally a short usage
458
message for your whole program. Here's an OptionParser populated with
459
user-friendly (documented) options::
461
usage = "usage: %prog [options] arg1 arg2"
462
parser = OptionParser(usage=usage)
463
parser.add_option("-v", "--verbose",
464
action="store_true", dest="verbose", default=True,
465
help="make lots of noise [default]")
466
parser.add_option("-q", "--quiet",
467
action="store_false", dest="verbose",
468
help="be vewwy quiet (I'm hunting wabbits)")
469
parser.add_option("-f", "--filename",
470
metavar="FILE", help="write output to FILE"),
471
parser.add_option("-m", "--mode",
472
default="intermediate",
473
help="interaction mode: novice, intermediate, "
474
"or expert [default: %default]")
476
If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the
477
command-line, or if you just call :meth:`parser.print_help`, it prints the
478
following to standard output::
480
usage: <yourscript> [options] arg1 arg2
483
-h, --help show this help message and exit
484
-v, --verbose make lots of noise [default]
485
-q, --quiet be vewwy quiet (I'm hunting wabbits)
486
-f FILE, --filename=FILE
488
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
489
expert [default: intermediate]
491
(If the help output is triggered by a help option, :mod:`optparse` exits after
492
printing the help text.)
494
There's a lot going on here to help :mod:`optparse` generate the best possible
497
* the script defines its own usage message::
499
usage = "usage: %prog [options] arg1 arg2"
501
:mod:`optparse` expands ``"%prog"`` in the usage string to the name of the
502
current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string is
503
then printed before the detailed option help.
505
If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
506
default: ``"usage: %prog [options]"``, which is fine if your script doesn't take
507
any positional arguments.
509
* every option defines a help string, and doesn't worry about line-wrapping---
510
:mod:`optparse` takes care of wrapping lines and making the help output look
513
* options that take a value indicate this fact in their automatically-generated
514
help message, e.g. for the "mode" option::
518
Here, "MODE" is called the meta-variable: it stands for the argument that the
519
user is expected to supply to :option:`-m`/:option:`--mode`. By default,
520
:mod:`optparse` converts the destination variable name to uppercase and uses
521
that for the meta-variable. Sometimes, that's not what you want---for example,
522
the :option:`--filename` option explicitly sets ``metavar="FILE"``, resulting in
523
this automatically-generated option description::
525
-f FILE, --filename=FILE
527
This is important for more than just saving space, though: the manually written
528
help text uses the meta-variable "FILE" to clue the user in that there's a
529
connection between the semi-formal syntax "-f FILE" and the informal semantic
530
description "write output to FILE". This is a simple but effective way to make
531
your help text a lot clearer and more useful for end users.
533
* options that have a default value can include ``%default`` in the help
534
string---\ :mod:`optparse` will replace it with :func:`str` of the option's
535
default value. If an option has no default value (or the default value is
536
``None``), ``%default`` expands to ``none``.
538
When dealing with many options, it is convenient to group these
539
options for better help output. An :class:`OptionParser` can contain
540
several option groups, each of which can contain several options.
542
Continuing with the parser defined above, adding an
543
:class:`OptionGroup` to a parser is easy::
545
group = OptionGroup(parser, "Dangerous Options",
546
"Caution: use these options at your own risk. "
547
"It is believed that some of them bite.")
548
group.add_option("-g", action="store_true", help="Group option.")
549
parser.add_option_group(group)
551
This would result in the following help output::
553
usage: [options] arg1 arg2
556
-h, --help show this help message and exit
557
-v, --verbose make lots of noise [default]
558
-q, --quiet be vewwy quiet (I'm hunting wabbits)
559
-fFILE, --file=FILE write output to FILE
560
-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
564
Caution: use of these options is at your own risk. It is believed that
568
.. _optparse-printing-version-string:
570
Printing a version string
571
^^^^^^^^^^^^^^^^^^^^^^^^^
573
Similar to the brief usage string, :mod:`optparse` can also print a version
574
string for your program. You have to supply the string as the ``version``
575
argument to OptionParser::
577
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
579
``"%prog"`` is expanded just like it is in ``usage``. Apart from that,
580
``version`` can contain anything you like. When you supply it, :mod:`optparse`
581
automatically adds a ``"--version"`` option to your parser. If it encounters
582
this option on the command line, it expands your ``version`` string (by
583
replacing ``"%prog"``), prints it to stdout, and exits.
585
For example, if your script is called ``/usr/bin/foo``::
587
$ /usr/bin/foo --version
591
.. _optparse-how-optparse-handles-errors:
593
How :mod:`optparse` handles errors
594
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
596
There are two broad classes of errors that :mod:`optparse` has to worry about:
597
programmer errors and user errors. Programmer errors are usually erroneous
598
calls to ``parser.add_option()``, e.g. invalid option strings, unknown option
599
attributes, missing option attributes, etc. These are dealt with in the usual
600
way: raise an exception (either ``optparse.OptionError`` or :exc:`TypeError`) and
601
let the program crash.
603
Handling user errors is much more important, since they are guaranteed to happen
604
no matter how stable your code is. :mod:`optparse` can automatically detect
605
some user errors, such as bad option arguments (passing ``"-n 4x"`` where
606
:option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
607
of the command line, where :option:`-n` takes an argument of any type). Also,
608
you can call ``parser.error()`` to signal an application-defined error
611
(options, args) = parser.parse_args()
613
if options.a and options.b:
614
parser.error("options -a and -b are mutually exclusive")
616
In either case, :mod:`optparse` handles the error the same way: it prints the
617
program's usage message and an error message to standard error and exits with
620
Consider the first example above, where the user passes ``"4x"`` to an option
621
that takes an integer::
626
foo: error: option -n: invalid integer value: '4x'
628
Or, where the user fails to pass a value at all::
633
foo: error: -n option requires an argument
635
:mod:`optparse`\ -generated error messages take care always to mention the
636
option involved in the error; be sure to do the same when calling
637
``parser.error()`` from your application code.
639
If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
640
you'll need to subclass OptionParser and override its :meth:`exit` and/or
641
:meth:`error` methods.
644
.. _optparse-putting-it-all-together:
646
Putting it all together
647
^^^^^^^^^^^^^^^^^^^^^^^
649
Here's what :mod:`optparse`\ -based scripts usually look like::
651
from optparse import OptionParser
654
usage = "usage: %prog [options] arg"
655
parser = OptionParser(usage)
656
parser.add_option("-f", "--file", dest="filename",
657
help="read data from FILENAME")
658
parser.add_option("-v", "--verbose",
659
action="store_true", dest="verbose")
660
parser.add_option("-q", "--quiet",
661
action="store_false", dest="verbose")
663
(options, args) = parser.parse_args()
665
parser.error("incorrect number of arguments")
667
print("reading %s..." % options.filename)
670
if __name__ == "__main__":
674
.. _optparse-reference-guide:
680
.. _optparse-creating-parser:
685
The first step in using :mod:`optparse` is to create an OptionParser instance::
687
parser = OptionParser(...)
689
The OptionParser constructor has no required arguments, but a number of optional
690
keyword arguments. You should always pass them as keyword arguments, i.e. do
691
not rely on the order in which the arguments are declared.
693
``usage`` (default: ``"%prog [options]"``)
694
The usage summary to print when your program is run incorrectly or with a help
695
option. When :mod:`optparse` prints the usage string, it expands ``%prog`` to
696
``os.path.basename(sys.argv[0])`` (or to ``prog`` if you passed that keyword
697
argument). To suppress a usage message, pass the special value
698
``optparse.SUPPRESS_USAGE``.
700
``option_list`` (default: ``[]``)
701
A list of Option objects to populate the parser with. The options in
702
``option_list`` are added after any options in ``standard_option_list`` (a class
703
attribute that may be set by OptionParser subclasses), but before any version or
704
help options. Deprecated; use :meth:`add_option` after creating the parser
707
``option_class`` (default: optparse.Option)
708
Class to use when adding options to the parser in :meth:`add_option`.
710
``version`` (default: ``None``)
711
A version string to print when the user supplies a version option. If you supply
712
a true value for ``version``, :mod:`optparse` automatically adds a version
713
option with the single option string ``"--version"``. The substring ``"%prog"``
714
is expanded the same as for ``usage``.
716
``conflict_handler`` (default: ``"error"``)
717
Specifies what to do when options with conflicting option strings are added to
718
the parser; see section :ref:`optparse-conflicts-between-options`.
720
``description`` (default: ``None``)
721
A paragraph of text giving a brief overview of your program. :mod:`optparse`
722
reformats this paragraph to fit the current terminal width and prints it when
723
the user requests help (after ``usage``, but before the list of options).
725
``formatter`` (default: a new IndentedHelpFormatter)
726
An instance of optparse.HelpFormatter that will be used for printing help text.
727
:mod:`optparse` provides two concrete classes for this purpose:
728
IndentedHelpFormatter and TitledHelpFormatter.
730
``add_help_option`` (default: ``True``)
731
If true, :mod:`optparse` will add a help option (with option strings ``"-h"``
732
and ``"--help"``) to the parser.
735
The string to use when expanding ``"%prog"`` in ``usage`` and ``version``
736
instead of ``os.path.basename(sys.argv[0])``.
740
.. _optparse-populating-parser:
742
Populating the parser
743
^^^^^^^^^^^^^^^^^^^^^
745
There are several ways to populate the parser with options. The preferred way
746
is by using ``OptionParser.add_option()``, as shown in section
747
:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
749
* pass it an Option instance (as returned by :func:`make_option`)
751
* pass it any combination of positional and keyword arguments that are
752
acceptable to :func:`make_option` (i.e., to the Option constructor), and it will
753
create the Option instance for you
755
The other alternative is to pass a list of pre-constructed Option instances to
756
the OptionParser constructor, as in::
759
make_option("-f", "--filename",
760
action="store", type="string", dest="filename"),
761
make_option("-q", "--quiet",
762
action="store_false", dest="verbose"),
764
parser = OptionParser(option_list=option_list)
766
(:func:`make_option` is a factory function for creating Option instances;
767
currently it is an alias for the Option constructor. A future version of
768
:mod:`optparse` may split Option into several classes, and :func:`make_option`
769
will pick the right class to instantiate. Do not instantiate Option directly.)
772
.. _optparse-defining-options:
777
Each Option instance represents a set of synonymous command-line option strings,
778
e.g. :option:`-f` and :option:`--file`. You can specify any number of short or
779
long option strings, but you must specify at least one overall option string.
781
The canonical way to create an Option instance is with the :meth:`add_option`
782
method of :class:`OptionParser`::
784
parser.add_option(opt_str[, ...], attr=value, ...)
786
To define an option with only a short option string::
788
parser.add_option("-f", attr=value, ...)
790
And to define an option with only a long option string::
792
parser.add_option("--foo", attr=value, ...)
794
The keyword arguments define attributes of the new Option object. The most
795
important option attribute is :attr:`action`, and it largely determines which
796
other attributes are relevant or required. If you pass irrelevant option
797
attributes, or fail to pass required ones, :mod:`optparse` raises an
798
:exc:`OptionError` exception explaining your mistake.
800
An option's *action* determines what :mod:`optparse` does when it encounters
801
this option on the command-line. The standard option actions hard-coded into
805
store this option's argument (default)
808
store a constant value
817
append this option's argument to a list
820
append a constant value to a list
823
increment a counter by one
826
call a specified function
829
print a usage message including all options and the documentation for them
831
(If you don't supply an action, the default is ``store``. For this action, you
832
may also supply :attr:`type` and :attr:`dest` option attributes; see below.)
834
As you can see, most actions involve storing or updating a value somewhere.
835
:mod:`optparse` always creates a special object for this, conventionally called
836
``options`` (it happens to be an instance of ``optparse.Values``). Option
837
arguments (and various other values) are stored as attributes of this object,
838
according to the :attr:`dest` (destination) option attribute.
840
For example, when you call ::
844
one of the first things :mod:`optparse` does is create the ``options`` object::
848
If one of the options in this parser is defined with ::
850
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
852
and the command-line being parsed includes any of the following::
859
then :mod:`optparse`, on seeing this option, will do the equivalent of ::
861
options.filename = "foo"
863
The :attr:`type` and :attr:`dest` option attributes are almost as important as
864
:attr:`action`, but :attr:`action` is the only one that makes sense for *all*
868
.. _optparse-standard-option-actions:
870
Standard option actions
871
^^^^^^^^^^^^^^^^^^^^^^^
873
The various option actions all have slightly different requirements and effects.
874
Most actions have several relevant option attributes which you may specify to
875
guide :mod:`optparse`'s behaviour; a few have required attributes, which you
876
must specify for any option using that action.
878
* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
880
The option must be followed by an argument, which is converted to a value
881
according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1,
882
multiple arguments will be consumed from the command line; all will be converted
883
according to :attr:`type` and stored to :attr:`dest` as a tuple. See the
884
"Option types" section below.
886
If ``choices`` is supplied (a list or tuple of strings), the type defaults to
889
If :attr:`type` is not supplied, it defaults to ``string``.
891
If :attr:`dest` is not supplied, :mod:`optparse` derives a destination from the
892
first long option string (e.g., ``"--foo-bar"`` implies ``foo_bar``). If there
893
are no long option strings, :mod:`optparse` derives a destination from the first
894
short option string (e.g., ``"-f"`` implies ``f``).
898
parser.add_option("-f")
899
parser.add_option("-p", type="float", nargs=3, dest="point")
901
As it parses the command line ::
903
-f foo.txt -p 1 -3.5 4 -fbar.txt
905
:mod:`optparse` will set ::
907
options.f = "foo.txt"
908
options.point = (1.0, -3.5, 4.0)
909
options.f = "bar.txt"
911
* ``store_const`` [required: ``const``; relevant: :attr:`dest`]
913
The value ``const`` is stored in :attr:`dest`.
917
parser.add_option("-q", "--quiet",
918
action="store_const", const=0, dest="verbose")
919
parser.add_option("-v", "--verbose",
920
action="store_const", const=1, dest="verbose")
921
parser.add_option("--noisy",
922
action="store_const", const=2, dest="verbose")
924
If ``"--noisy"`` is seen, :mod:`optparse` will set ::
928
* ``store_true`` [relevant: :attr:`dest`]
930
A special case of ``store_const`` that stores a true value to :attr:`dest`.
932
* ``store_false`` [relevant: :attr:`dest`]
934
Like ``store_true``, but stores a false value.
938
parser.add_option("--clobber", action="store_true", dest="clobber")
939
parser.add_option("--no-clobber", action="store_false", dest="clobber")
941
* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
943
The option must be followed by an argument, which is appended to the list in
944
:attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list
945
is automatically created when :mod:`optparse` first encounters this option on
946
the command-line. If ``nargs`` > 1, multiple arguments are consumed, and a
947
tuple of length ``nargs`` is appended to :attr:`dest`.
949
The defaults for :attr:`type` and :attr:`dest` are the same as for the ``store``
954
parser.add_option("-t", "--tracks", action="append", type="int")
956
If ``"-t3"`` is seen on the command-line, :mod:`optparse` does the equivalent
960
options.tracks.append(int("3"))
962
If, a little later on, ``"--tracks=4"`` is seen, it does::
964
options.tracks.append(int("4"))
966
* ``append_const`` [required: ``const``; relevant: :attr:`dest`]
968
Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as
969
with ``append``, :attr:`dest` defaults to ``None``, and an empty list is
970
automatically created the first time the option is encountered.
972
* ``count`` [relevant: :attr:`dest`]
974
Increment the integer stored at :attr:`dest`. If no default value is supplied,
975
:attr:`dest` is set to zero before being incremented the first time.
979
parser.add_option("-v", action="count", dest="verbosity")
981
The first time ``"-v"`` is seen on the command line, :mod:`optparse` does the
984
options.verbosity = 0
985
options.verbosity += 1
987
Every subsequent occurrence of ``"-v"`` results in ::
989
options.verbosity += 1
991
* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``,
992
``callback_args``, ``callback_kwargs``]
994
Call the function specified by ``callback``, which is called as ::
996
func(option, opt_str, value, parser, *args, **kwargs)
998
See section :ref:`optparse-option-callbacks` for more detail.
1002
Prints a complete help message for all the options in the current option parser.
1003
The help message is constructed from the ``usage`` string passed to
1004
OptionParser's constructor and the :attr:`help` string passed to every option.
1006
If no :attr:`help` string is supplied for an option, it will still be listed in
1007
the help message. To omit an option entirely, use the special value
1008
``optparse.SUPPRESS_HELP``.
1010
:mod:`optparse` automatically adds a :attr:`help` option to all OptionParsers,
1011
so you do not normally need to create one.
1015
from optparse import OptionParser, SUPPRESS_HELP
1017
parser = OptionParser()
1018
parser.add_option("-h", "--help", action="help"),
1019
parser.add_option("-v", action="store_true", dest="verbose",
1020
help="Be moderately verbose")
1021
parser.add_option("--file", dest="filename",
1022
help="Input file to read data from"),
1023
parser.add_option("--secret", help=SUPPRESS_HELP)
1025
If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line, it
1026
will print something like the following help message to stdout (assuming
1027
``sys.argv[0]`` is ``"foo.py"``)::
1029
usage: foo.py [options]
1032
-h, --help Show this help message and exit
1033
-v Be moderately verbose
1034
--file=FILENAME Input file to read data from
1036
After printing the help message, :mod:`optparse` terminates your process with
1041
Prints the version number supplied to the OptionParser to stdout and exits. The
1042
version number is actually formatted and printed by the ``print_version()``
1043
method of OptionParser. Generally only relevant if the ``version`` argument is
1044
supplied to the OptionParser constructor. As with :attr:`help` options, you
1045
will rarely create ``version`` options, since :mod:`optparse` automatically adds
1049
.. _optparse-option-attributes:
1054
The following option attributes may be passed as keyword arguments to
1055
``parser.add_option()``. If you pass an option attribute that is not relevant
1056
to a particular option, or fail to pass a required option attribute,
1057
:mod:`optparse` raises :exc:`OptionError`.
1059
* :attr:`action` (default: ``"store"``)
1061
Determines :mod:`optparse`'s behaviour when this option is seen on the command
1062
line; the available options are documented above.
1064
* :attr:`type` (default: ``"string"``)
1066
The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the
1067
available option types are documented below.
1069
* :attr:`dest` (default: derived from option strings)
1071
If the option's action implies writing or modifying a value somewhere, this
1072
tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the
1073
``options`` object that :mod:`optparse` builds as it parses the command line.
1075
* ``default`` (deprecated)
1077
The value to use for this option's destination if the option is not seen on the
1078
command line. Deprecated; use ``parser.set_defaults()`` instead.
1080
* ``nargs`` (default: 1)
1082
How many arguments of type :attr:`type` should be consumed when this option is
1083
seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`.
1087
For actions that store a constant value, the constant value to store.
1091
For options of type ``"choice"``, the list of strings the user may choose from.
1095
For options with action ``"callback"``, the callable to call when this option
1096
is seen. See section :ref:`optparse-option-callbacks` for detail on the
1097
arguments passed to ``callable``.
1099
* ``callback_args``, ``callback_kwargs``
1101
Additional positional and keyword arguments to pass to ``callback`` after the
1102
four standard callback arguments.
1106
Help text to print for this option when listing all available options after the
1107
user supplies a :attr:`help` option (such as ``"--help"``). If no help text is
1108
supplied, the option will be listed without help text. To hide this option, use
1109
the special value ``SUPPRESS_HELP``.
1111
* ``metavar`` (default: derived from option strings)
1113
Stand-in for the option argument(s) to use when printing help text. See section
1114
:ref:`optparse-tutorial` for an example.
1117
.. _optparse-standard-option-types:
1119
Standard option types
1120
^^^^^^^^^^^^^^^^^^^^^
1122
:mod:`optparse` has five built-in option types: ``string``, ``int``,
1123
``choice``, ``float`` and ``complex``. If you need to add new option types, see
1124
section :ref:`optparse-extending-optparse`.
1126
Arguments to string options are not checked or converted in any way: the text on
1127
the command line is stored in the destination (or passed to the callback) as-is.
1129
Integer arguments (type ``int``) are parsed as follows:
1131
* if the number starts with ``0x``, it is parsed as a hexadecimal number
1133
* if the number starts with ``0``, it is parsed as an octal number
1135
* if the number starts with ``0b``, it is parsed as a binary number
1137
* otherwise, the number is parsed as a decimal number
1140
The conversion is done by calling ``int()`` with the appropriate base (2, 8, 10,
1141
or 16). If this fails, so will :mod:`optparse`, although with a more useful
1144
``float`` and ``complex`` option arguments are converted directly with
1145
``float()`` and ``complex()``, with similar error-handling.
1147
``choice`` options are a subtype of ``string`` options. The ``choices`` option
1148
attribute (a sequence of strings) defines the set of allowed option arguments.
1149
``optparse.check_choice()`` compares user-supplied option arguments against this
1150
master list and raises :exc:`OptionValueError` if an invalid string is given.
1153
.. _optparse-parsing-arguments:
1158
The whole point of creating and populating an OptionParser is to call its
1159
:meth:`parse_args` method::
1161
(options, args) = parser.parse_args(args=None, values=None)
1163
where the input parameters are
1166
the list of arguments to process (default: ``sys.argv[1:]``)
1169
object to store option arguments in (default: a new instance of optparse.Values)
1171
and the return values are
1174
the same object that was passed in as ``options``, or the optparse.Values
1175
instance created by :mod:`optparse`
1178
the leftover positional arguments after all options have been processed
1180
The most common usage is to supply neither keyword argument. If you supply
1181
``options``, it will be modified with repeated ``setattr()`` calls (roughly one
1182
for every option argument stored to an option destination) and returned by
1185
If :meth:`parse_args` encounters any errors in the argument list, it calls the
1186
OptionParser's :meth:`error` method with an appropriate end-user error message.
1187
This ultimately terminates your process with an exit status of 2 (the
1188
traditional Unix exit status for command-line errors).
1191
.. _optparse-querying-manipulating-option-parser:
1193
Querying and manipulating your option parser
1194
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1196
The default behavior of the option parser can be customized slightly,
1197
and you can also poke around your option parser and see what's there.
1198
OptionParser provides several methods to help you out:
1200
``disable_interspersed_args()``
1201
Set parsing to stop on the first non-option. Use this if you have a
1202
command processor which runs another command which has options of
1203
its own and you want to make sure these options don't get
1204
confused. For example, each command might have a different
1207
``enable_interspersed_args()``
1208
Set parsing to not stop on the first non-option, allowing
1209
interspersing switches with command arguments. For example,
1210
``"-s arg1 --long arg2"`` would return ``["arg1", "arg2"]``
1211
as the command arguments and ``-s, --long`` as options.
1212
This is the default behavior.
1214
``get_option(opt_str)``
1215
Returns the Option instance with the option string ``opt_str``, or ``None`` if
1216
no options have that option string.
1218
``has_option(opt_str)``
1219
Return true if the OptionParser has an option with option string ``opt_str``
1220
(e.g., ``"-q"`` or ``"--verbose"``).
1222
``remove_option(opt_str)``
1223
If the :class:`OptionParser` has an option corresponding to ``opt_str``, that option is
1224
removed. If that option provided any other option strings, all of those option
1225
strings become invalid. If ``opt_str`` does not occur in any option belonging to
1226
this :class:`OptionParser`, raises :exc:`ValueError`.
1229
.. _optparse-conflicts-between-options:
1231
Conflicts between options
1232
^^^^^^^^^^^^^^^^^^^^^^^^^
1234
If you're not careful, it's easy to define options with conflicting option
1237
parser.add_option("-n", "--dry-run", ...)
1239
parser.add_option("-n", "--noisy", ...)
1241
(This is particularly true if you've defined your own OptionParser subclass with
1242
some standard options.)
1244
Every time you add an option, :mod:`optparse` checks for conflicts with existing
1245
options. If it finds any, it invokes the current conflict-handling mechanism.
1246
You can set the conflict-handling mechanism either in the constructor::
1248
parser = OptionParser(..., conflict_handler=handler)
1250
or with a separate call::
1252
parser.set_conflict_handler(handler)
1254
The available conflict handlers are:
1257
assume option conflicts are a programming error and raise :exc:`OptionConflictError`
1260
resolve option conflicts intelligently (see below)
1263
As an example, let's define an :class:`OptionParser` that resolves conflicts
1264
intelligently and add conflicting options to it::
1266
parser = OptionParser(conflict_handler="resolve")
1267
parser.add_option("-n", "--dry-run", ..., help="do no harm")
1268
parser.add_option("-n", "--noisy", ..., help="be noisy")
1270
At this point, :mod:`optparse` detects that a previously-added option is already
1271
using the ``"-n"`` option string. Since ``conflict_handler`` is ``"resolve"``,
1272
it resolves the situation by removing ``"-n"`` from the earlier option's list of
1273
option strings. Now ``"--dry-run"`` is the only way for the user to activate
1274
that option. If the user asks for help, the help message will reflect that::
1277
--dry-run do no harm
1279
-n, --noisy be noisy
1281
It's possible to whittle away the option strings for a previously-added option
1282
until there are none left, and the user has no way of invoking that option from
1283
the command-line. In that case, :mod:`optparse` removes that option completely,
1284
so it doesn't show up in help text or anywhere else. Carrying on with our
1285
existing OptionParser::
1287
parser.add_option("--dry-run", ..., help="new dry-run option")
1289
At this point, the original :option:`-n/--dry-run` option is no longer
1290
accessible, so :mod:`optparse` removes it, leaving this help text::
1294
-n, --noisy be noisy
1295
--dry-run new dry-run option
1298
.. _optparse-cleanup:
1303
OptionParser instances have several cyclic references. This should not be a
1304
problem for Python's garbage collector, but you may wish to break the cyclic
1305
references explicitly by calling ``destroy()`` on your OptionParser once you are
1306
done with it. This is particularly useful in long-running applications where
1307
large object graphs are reachable from your OptionParser.
1310
.. _optparse-other-methods:
1315
OptionParser supports several other public methods:
1317
* ``set_usage(usage)``
1319
Set the usage string according to the rules described above for the ``usage``
1320
constructor keyword argument. Passing ``None`` sets the default usage string;
1321
use ``SUPPRESS_USAGE`` to suppress a usage message.
1323
* ``enable_interspersed_args()``, ``disable_interspersed_args()``
1325
Enable/disable positional arguments interspersed with options, similar to GNU
1326
getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both
1327
simple options that take no arguments, :mod:`optparse` normally accepts this
1330
prog -a arg1 -b arg2
1332
and treats it as equivalent to ::
1334
prog -a -b arg1 arg2
1336
To disable this feature, call ``disable_interspersed_args()``. This restores
1337
traditional Unix syntax, where option parsing stops with the first non-option
1340
* ``set_defaults(dest=value, ...)``
1342
Set default values for several option destinations at once. Using
1343
:meth:`set_defaults` is the preferred way to set default values for options,
1344
since multiple options can share the same destination. For example, if several
1345
"mode" options all set the same destination, any one of them can set the
1346
default, and the last one wins::
1348
parser.add_option("--advanced", action="store_const",
1349
dest="mode", const="advanced",
1350
default="novice") # overridden below
1351
parser.add_option("--novice", action="store_const",
1352
dest="mode", const="novice",
1353
default="advanced") # overrides above setting
1355
To avoid this confusion, use :meth:`set_defaults`::
1357
parser.set_defaults(mode="advanced")
1358
parser.add_option("--advanced", action="store_const",
1359
dest="mode", const="advanced")
1360
parser.add_option("--novice", action="store_const",
1361
dest="mode", const="novice")
1364
.. _optparse-option-callbacks:
1369
When :mod:`optparse`'s built-in actions and types aren't quite enough for your
1370
needs, you have two choices: extend :mod:`optparse` or define a callback option.
1371
Extending :mod:`optparse` is more general, but overkill for a lot of simple
1372
cases. Quite often a simple callback is all you need.
1374
There are two steps to defining a callback option:
1376
* define the option itself using the ``callback`` action
1378
* write the callback; this is a function (or method) that takes at least four
1379
arguments, as described below
1382
.. _optparse-defining-callback-option:
1384
Defining a callback option
1385
^^^^^^^^^^^^^^^^^^^^^^^^^^
1387
As always, the easiest way to define a callback option is by using the
1388
``parser.add_option()`` method. Apart from :attr:`action`, the only option
1389
attribute you must specify is ``callback``, the function to call::
1391
parser.add_option("-c", action="callback", callback=my_callback)
1393
``callback`` is a function (or other callable object), so you must have already
1394
defined ``my_callback()`` when you create this callback option. In this simple
1395
case, :mod:`optparse` doesn't even know if :option:`-c` takes any arguments,
1396
which usually means that the option takes no arguments---the mere presence of
1397
:option:`-c` on the command-line is all it needs to know. In some
1398
circumstances, though, you might want your callback to consume an arbitrary
1399
number of command-line arguments. This is where writing callbacks gets tricky;
1400
it's covered later in this section.
1402
:mod:`optparse` always passes four particular arguments to your callback, and it
1403
will only pass additional arguments if you specify them via ``callback_args``
1404
and ``callback_kwargs``. Thus, the minimal callback function signature is::
1406
def my_callback(option, opt, value, parser):
1408
The four arguments to a callback are described below.
1410
There are several other option attributes that you can supply when you define a
1414
has its usual meaning: as with the ``store`` or ``append`` actions, it instructs
1415
:mod:`optparse` to consume one argument and convert it to :attr:`type`. Rather
1416
than storing the converted value(s) anywhere, though, :mod:`optparse` passes it
1417
to your callback function.
1420
also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
1421
consume ``nargs`` arguments, each of which must be convertible to :attr:`type`.
1422
It then passes a tuple of converted values to your callback.
1425
a tuple of extra positional arguments to pass to the callback
1428
a dictionary of extra keyword arguments to pass to the callback
1431
.. _optparse-how-callbacks-called:
1433
How callbacks are called
1434
^^^^^^^^^^^^^^^^^^^^^^^^
1436
All callbacks are called as follows::
1438
func(option, opt_str, value, parser, *args, **kwargs)
1443
is the Option instance that's calling the callback
1446
is the option string seen on the command-line that's triggering the callback.
1447
(If an abbreviated long option was used, ``opt_str`` will be the full, canonical
1448
option string---e.g. if the user puts ``"--foo"`` on the command-line as an
1449
abbreviation for ``"--foobar"``, then ``opt_str`` will be ``"--foobar"``.)
1452
is the argument to this option seen on the command-line. :mod:`optparse` will
1453
only expect an argument if :attr:`type` is set; the type of ``value`` will be
1454
the type implied by the option's type. If :attr:`type` for this option is
1455
``None`` (no argument expected), then ``value`` will be ``None``. If ``nargs``
1456
> 1, ``value`` will be a tuple of values of the appropriate type.
1459
is the OptionParser instance driving the whole thing, mainly useful because you
1460
can access some other interesting data through its instance attributes:
1463
the current list of leftover arguments, ie. arguments that have been consumed
1464
but are neither options nor option arguments. Feel free to modify
1465
``parser.largs``, e.g. by adding more arguments to it. (This list will become
1466
``args``, the second return value of :meth:`parse_args`.)
1469
the current list of remaining arguments, ie. with ``opt_str`` and ``value`` (if
1470
applicable) removed, and only the arguments following them still there. Feel
1471
free to modify ``parser.rargs``, e.g. by consuming more arguments.
1474
the object where option values are by default stored (an instance of
1475
optparse.OptionValues). This lets callbacks use the same mechanism as the rest
1476
of :mod:`optparse` for storing option values; you don't need to mess around with
1477
globals or closures. You can also access or modify the value(s) of any options
1478
already encountered on the command-line.
1481
is a tuple of arbitrary positional arguments supplied via the ``callback_args``
1485
is a dictionary of arbitrary keyword arguments supplied via ``callback_kwargs``.
1488
.. _optparse-raising-errors-in-callback:
1490
Raising errors in a callback
1491
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1493
The callback function should raise :exc:`OptionValueError` if there are any problems
1494
with the option or its argument(s). :mod:`optparse` catches this and terminates
1495
the program, printing the error message you supply to stderr. Your message
1496
should be clear, concise, accurate, and mention the option at fault. Otherwise,
1497
the user will have a hard time figuring out what he did wrong.
1500
.. _optparse-callback-example-1:
1502
Callback example 1: trivial callback
1503
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1505
Here's an example of a callback option that takes no arguments, and simply
1506
records that the option was seen::
1508
def record_foo_seen(option, opt_str, value, parser):
1509
parser.values.saw_foo = True
1511
parser.add_option("--foo", action="callback", callback=record_foo_seen)
1513
Of course, you could do that with the ``store_true`` action.
1516
.. _optparse-callback-example-2:
1518
Callback example 2: check option order
1519
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1521
Here's a slightly more interesting example: record the fact that ``"-a"`` is
1522
seen, but blow up if it comes after ``"-b"`` in the command-line. ::
1524
def check_order(option, opt_str, value, parser):
1526
raise OptionValueError("can't use -a after -b")
1529
parser.add_option("-a", action="callback", callback=check_order)
1530
parser.add_option("-b", action="store_true", dest="b")
1533
.. _optparse-callback-example-3:
1535
Callback example 3: check option order (generalized)
1536
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1538
If you want to re-use this callback for several similar options (set a flag, but
1539
blow up if ``"-b"`` has already been seen), it needs a bit of work: the error
1540
message and the flag that it sets must be generalized. ::
1542
def check_order(option, opt_str, value, parser):
1544
raise OptionValueError("can't use %s after -b" % opt_str)
1545
setattr(parser.values, option.dest, 1)
1547
parser.add_option("-a", action="callback", callback=check_order, dest='a')
1548
parser.add_option("-b", action="store_true", dest="b")
1549
parser.add_option("-c", action="callback", callback=check_order, dest='c')
1552
.. _optparse-callback-example-4:
1554
Callback example 4: check arbitrary condition
1555
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1557
Of course, you could put any condition in there---you're not limited to checking
1558
the values of already-defined options. For example, if you have options that
1559
should not be called when the moon is full, all you have to do is this::
1561
def check_moon(option, opt_str, value, parser):
1563
raise OptionValueError("%s option invalid when moon is full"
1565
setattr(parser.values, option.dest, 1)
1567
parser.add_option("--foo",
1568
action="callback", callback=check_moon, dest="foo")
1570
(The definition of ``is_moon_full()`` is left as an exercise for the reader.)
1573
.. _optparse-callback-example-5:
1575
Callback example 5: fixed arguments
1576
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1578
Things get slightly more interesting when you define callback options that take
1579
a fixed number of arguments. Specifying that a callback option takes arguments
1580
is similar to defining a ``store`` or ``append`` option: if you define
1581
:attr:`type`, then the option takes one argument that must be convertible to
1582
that type; if you further define ``nargs``, then the option takes ``nargs``
1585
Here's an example that just emulates the standard ``store`` action::
1587
def store_value(option, opt_str, value, parser):
1588
setattr(parser.values, option.dest, value)
1590
parser.add_option("--foo",
1591
action="callback", callback=store_value,
1592
type="int", nargs=3, dest="foo")
1594
Note that :mod:`optparse` takes care of consuming 3 arguments and converting
1595
them to integers for you; all you have to do is store them. (Or whatever;
1596
obviously you don't need a callback for this example.)
1599
.. _optparse-callback-example-6:
1601
Callback example 6: variable arguments
1602
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1604
Things get hairy when you want an option to take a variable number of arguments.
1605
For this case, you must write a callback, as :mod:`optparse` doesn't provide any
1606
built-in capabilities for it. And you have to deal with certain intricacies of
1607
conventional Unix command-line parsing that :mod:`optparse` normally handles for
1608
you. In particular, callbacks should implement the conventional rules for bare
1609
``"--"`` and ``"-"`` arguments:
1611
* either ``"--"`` or ``"-"`` can be option arguments
1613
* bare ``"--"`` (if not the argument to some option): halt command-line
1614
processing and discard the ``"--"``
1616
* bare ``"-"`` (if not the argument to some option): halt command-line
1617
processing but keep the ``"-"`` (append it to ``parser.largs``)
1619
If you want an option that takes a variable number of arguments, there are
1620
several subtle, tricky issues to worry about. The exact implementation you
1621
choose will be based on which trade-offs you're willing to make for your
1622
application (which is why :mod:`optparse` doesn't support this sort of thing
1625
Nevertheless, here's a stab at a callback for an option with variable
1628
def vararg_callback(option, opt_str, value, parser):
1629
assert value is None
1639
for arg in parser.rargs:
1640
# stop on --foo like options
1641
if arg[:2] == "--" and len(arg) > 2:
1643
# stop on -a, but not on -3 or -3.0
1644
if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
1648
del parser.rargs[:len(value)]
1649
setattr(parser.values, option.dest, value)
1652
parser.add_option("-c", "--callback", dest="vararg_attr",
1653
action="callback", callback=vararg_callback)
1656
.. _optparse-extending-optparse:
1658
Extending :mod:`optparse`
1659
-------------------------
1661
Since the two major controlling factors in how :mod:`optparse` interprets
1662
command-line options are the action and type of each option, the most likely
1663
direction of extension is to add new actions and new types.
1666
.. _optparse-adding-new-types:
1671
To add new types, you need to define your own subclass of :mod:`optparse`'s
1672
Option class. This class has a couple of attributes that define
1673
:mod:`optparse`'s types: :attr:`TYPES` and :attr:`TYPE_CHECKER`.
1675
:attr:`TYPES` is a tuple of type names; in your subclass, simply define a new
1676
tuple :attr:`TYPES` that builds on the standard one.
1678
:attr:`TYPE_CHECKER` is a dictionary mapping type names to type-checking
1679
functions. A type-checking function has the following signature::
1681
def check_mytype(option, opt, value)
1683
where ``option`` is an :class:`Option` instance, ``opt`` is an option string
1684
(e.g., ``"-f"``), and ``value`` is the string from the command line that must be
1685
checked and converted to your desired type. ``check_mytype()`` should return an
1686
object of the hypothetical type ``mytype``. The value returned by a
1687
type-checking function will wind up in the OptionValues instance returned by
1688
:meth:`OptionParser.parse_args`, or be passed to a callback as the ``value``
1691
Your type-checking function should raise :exc:`OptionValueError` if it encounters any
1692
problems. :exc:`OptionValueError` takes a single string argument, which is passed
1693
as-is to :class:`OptionParser`'s :meth:`error` method, which in turn prepends the program
1694
name and the string ``"error:"`` and prints everything to stderr before
1695
terminating the process.
1697
Here's a silly example that demonstrates adding a ``complex`` option type to
1698
parse Python-style complex numbers on the command line. (This is even sillier
1699
than it used to be, because :mod:`optparse` 1.3 added built-in support for
1700
complex numbers, but never mind.)
1702
First, the necessary imports::
1704
from copy import copy
1705
from optparse import Option, OptionValueError
1707
You need to define your type-checker first, since it's referred to later (in the
1708
:attr:`TYPE_CHECKER` class attribute of your Option subclass)::
1710
def check_complex(option, opt, value):
1712
return complex(value)
1714
raise OptionValueError(
1715
"option %s: invalid complex value: %r" % (opt, value))
1717
Finally, the Option subclass::
1719
class MyOption (Option):
1720
TYPES = Option.TYPES + ("complex",)
1721
TYPE_CHECKER = copy(Option.TYPE_CHECKER)
1722
TYPE_CHECKER["complex"] = check_complex
1724
(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
1725
up modifying the :attr:`TYPE_CHECKER` attribute of :mod:`optparse`'s Option
1726
class. This being Python, nothing stops you from doing that except good manners
1729
That's it! Now you can write a script that uses the new option type just like
1730
any other :mod:`optparse`\ -based script, except you have to instruct your
1731
OptionParser to use MyOption instead of Option::
1733
parser = OptionParser(option_class=MyOption)
1734
parser.add_option("-c", type="complex")
1736
Alternately, you can build your own option list and pass it to OptionParser; if
1737
you don't use :meth:`add_option` in the above way, you don't need to tell
1738
OptionParser which option class to use::
1740
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
1741
parser = OptionParser(option_list=option_list)
1744
.. _optparse-adding-new-actions:
1749
Adding new actions is a bit trickier, because you have to understand that
1750
:mod:`optparse` has a couple of classifications for actions:
1753
actions that result in :mod:`optparse` storing a value to an attribute of the
1754
current OptionValues instance; these options require a :attr:`dest` attribute to
1755
be supplied to the Option constructor
1758
actions that take a value from the command line and expect it to be of a certain
1759
type; or rather, a string that can be converted to a certain type. These
1760
options require a :attr:`type` attribute to the Option constructor.
1762
These are overlapping sets: some default "store" actions are ``store``,
1763
``store_const``, ``append``, and ``count``, while the default "typed" actions
1764
are ``store``, ``append``, and ``callback``.
1766
When you add an action, you need to categorize it by listing it in at least one
1767
of the following class attributes of Option (all are lists of strings):
1770
all actions must be listed in ACTIONS
1772
:attr:`STORE_ACTIONS`
1773
"store" actions are additionally listed here
1775
:attr:`TYPED_ACTIONS`
1776
"typed" actions are additionally listed here
1778
``ALWAYS_TYPED_ACTIONS``
1779
actions that always take a type (i.e. whose options always take a value) are
1780
additionally listed here. The only effect of this is that :mod:`optparse`
1781
assigns the default type, ``string``, to options with no explicit type whose
1782
action is listed in ``ALWAYS_TYPED_ACTIONS``.
1784
In order to actually implement your new action, you must override Option's
1785
:meth:`take_action` method and add a case that recognizes your action.
1787
For example, let's add an ``extend`` action. This is similar to the standard
1788
``append`` action, but instead of taking a single value from the command-line
1789
and appending it to an existing list, ``extend`` will take multiple values in a
1790
single comma-delimited string, and extend an existing list with them. That is,
1791
if ``"--names"`` is an ``extend`` option of type ``string``, the command line
1794
--names=foo,bar --names blah --names ding,dong
1796
would result in a list ::
1798
["foo", "bar", "blah", "ding", "dong"]
1800
Again we define a subclass of Option::
1802
class MyOption (Option):
1804
ACTIONS = Option.ACTIONS + ("extend",)
1805
STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
1806
TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
1807
ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
1809
def take_action(self, action, dest, opt, value, values, parser):
1810
if action == "extend":
1811
lvalue = value.split(",")
1812
values.ensure_value(dest, []).extend(lvalue)
1815
self, action, dest, opt, value, values, parser)
1819
* ``extend`` both expects a value on the command-line and stores that value
1820
somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS`
1822
* to ensure that :mod:`optparse` assigns the default type of ``string`` to
1823
``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as
1826
* :meth:`MyOption.take_action` implements just this one new action, and passes
1827
control back to :meth:`Option.take_action` for the standard :mod:`optparse`
1830
* ``values`` is an instance of the optparse_parser.Values class, which
1831
provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
1832
essentially :func:`getattr` with a safety valve; it is called as ::
1834
values.ensure_value(attr, value)
1836
If the ``attr`` attribute of ``values`` doesn't exist or is None, then
1837
ensure_value() first sets it to ``value``, and then returns 'value. This is very
1838
handy for actions like ``extend``, ``append``, and ``count``, all of which
1839
accumulate data in a variable and expect that variable to be of a certain type
1840
(a list for the first two, an integer for the latter). Using
1841
:meth:`ensure_value` means that scripts using your action don't have to worry
1842
about setting a default value for the option destinations in question; they can
1843
just leave the default as None and :meth:`ensure_value` will take care of
1844
getting it right when it's needed.
added
removed
Doc/library/optparse.rst
