1
:mod:`optparse` --- Parser for command line options
2
===================================================
5
:synopsis: Command-line option parsing library.
7
.. moduleauthor:: Greg Ward <gward@python.net>
8
.. sectionauthor:: Greg Ward <gward@python.net>
13
The :mod:`optparse` module is deprecated and will not be developed further;
14
development will continue with the :mod:`argparse` module.
16
**Source code:** :source:`Lib/optparse.py`
20
:mod:`optparse` is a more convenient, flexible, and powerful library for parsing
21
command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
22
more declarative style of command-line parsing: you create an instance of
23
:class:`OptionParser`, populate it with options, and parse the command
24
line. :mod:`optparse` allows users to specify options in the conventional
25
GNU/POSIX syntax, and additionally generates usage and help messages for you.
27
Here's an example of using :mod:`optparse` in a simple script::
29
from optparse import OptionParser
31
parser = OptionParser()
32
parser.add_option("-f", "--file", dest="filename",
33
help="write report to FILE", metavar="FILE")
34
parser.add_option("-q", "--quiet",
35
action="store_false", dest="verbose", default=True,
36
help="don't print status messages to stdout")
38
(options, args) = parser.parse_args()
40
With these few lines of code, users of your script can now do the "usual thing"
41
on the command-line, for example::
43
<yourscript> --file=outfile -q
45
As it parses the command line, :mod:`optparse` sets attributes of the
46
``options`` object returned by :meth:`parse_args` based on user-supplied
47
command-line values. When :meth:`parse_args` returns from parsing this command
48
line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
49
``False``. :mod:`optparse` supports both long and short options, allows short
50
options to be merged together, and allows options to be associated with their
51
arguments in a variety of ways. Thus, the following command lines are all
52
equivalent to the above example::
54
<yourscript> -f outfile --quiet
55
<yourscript> --quiet --file outfile
56
<yourscript> -q -foutfile
57
<yourscript> -qfoutfile
59
Additionally, users can run one of ::
64
and :mod:`optparse` will print out a brief summary of your script's options:
68
Usage: <yourscript> [options]
71
-h, --help show this help message and exit
72
-f FILE, --file=FILE write report to FILE
73
-q, --quiet don't print status messages to stdout
75
where the value of *yourscript* is determined at runtime (normally from
79
.. _optparse-background:
84
:mod:`optparse` was explicitly designed to encourage the creation of programs
85
with straightforward, conventional command-line interfaces. To that end, it
86
supports only the most common command-line syntax and semantics conventionally
87
used under Unix. If you are unfamiliar with these conventions, read this
88
section to acquaint yourself with them.
91
.. _optparse-terminology:
97
a string entered on the command-line, and passed by the shell to ``execl()``
98
or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
99
(``sys.argv[0]`` is the name of the program being executed). Unix shells
100
also use the term "word".
102
It is occasionally desirable to substitute an argument list other than
103
``sys.argv[1:]``, so you should read "argument" as "an element of
104
``sys.argv[1:]``, or of some other list provided as a substitute for
108
an argument used to supply extra information to guide or customize the
109
execution of a program. There are many different syntaxes for options; the
110
traditional Unix syntax is a hyphen ("-") followed by a single letter,
111
e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple
112
options to be merged into a single argument, e.g. ``-x -F`` is equivalent
113
to ``-xF``. The GNU project introduced ``--`` followed by a series of
114
hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
115
only two option syntaxes provided by :mod:`optparse`.
117
Some other option syntaxes that the world has seen include:
119
* a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same
120
as multiple options merged into a single argument)
122
* a hyphen followed by a whole word, e.g. ``-file`` (this is technically
123
equivalent to the previous syntax, but they aren't usually seen in the same
126
* a plus sign followed by a single letter, or a few letters, or a word, e.g.
129
* a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
132
These option syntaxes are not supported by :mod:`optparse`, and they never
133
will be. This is deliberate: the first three are non-standard on any
134
environment, and the last only makes sense if you're exclusively targeting
135
VMS, MS-DOS, and/or Windows.
138
an argument that follows an option, is closely associated with that option,
139
and is consumed from the argument list when that option is. With
140
:mod:`optparse`, option arguments may either be in a separate argument from
148
or included in the same argument:
155
Typically, a given option either takes an argument or it doesn't. Lots of
156
people want an "optional option arguments" feature, meaning that some options
157
will take an argument if they see it, and won't if they don't. This is
158
somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
159
an optional argument and ``-b`` is another option entirely, how do we
160
interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
161
support this feature.
164
something leftover in the argument list after options have been parsed, i.e.
165
after options and their arguments have been parsed and removed from the
169
an option that must be supplied on the command-line; note that the phrase
170
"required option" is self-contradictory in English. :mod:`optparse` doesn't
171
prevent you from implementing required options, but doesn't give you much
174
For example, consider this hypothetical command-line::
176
prog -v --report report.txt foo bar
178
``-v`` and ``--report`` are both options. Assuming that ``--report``
179
takes one argument, ``report.txt`` is an option argument. ``foo`` and
180
``bar`` are positional arguments.
183
.. _optparse-what-options-for:
185
What are options for?
186
^^^^^^^^^^^^^^^^^^^^^
188
Options are used to provide extra information to tune or customize the execution
189
of a program. In case it wasn't clear, options are usually *optional*. A
190
program should be able to run just fine with no options whatsoever. (Pick a
191
random program from the Unix or GNU toolsets. Can it run without any options at
192
all and still make sense? The main exceptions are ``find``, ``tar``, and
193
``dd``\ ---all of which are mutant oddballs that have been rightly criticized
194
for their non-standard syntax and confusing interfaces.)
196
Lots of people want their programs to have "required options". Think about it.
197
If it's required, then it's *not optional*! If there is a piece of information
198
that your program absolutely requires in order to run successfully, that's what
199
positional arguments are for.
201
As an example of good command-line interface design, consider the humble ``cp``
202
utility, for copying files. It doesn't make much sense to try to copy files
203
without supplying a destination and at least one source. Hence, ``cp`` fails if
204
you run it with no arguments. However, it has a flexible, useful syntax that
205
does not require any options at all::
208
cp SOURCE ... DEST-DIR
210
You can get pretty far with just that. Most ``cp`` implementations provide a
211
bunch of options to tweak exactly how the files are copied: you can preserve
212
mode and modification time, avoid following symlinks, ask before clobbering
213
existing files, etc. But none of this distracts from the core mission of
214
``cp``, which is to copy either one file to another, or several files to another
218
.. _optparse-what-positional-arguments-for:
220
What are positional arguments for?
221
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
223
Positional arguments are for those pieces of information that your program
224
absolutely, positively requires to run.
226
A good user interface should have as few absolute requirements as possible. If
227
your program requires 17 distinct pieces of information in order to run
228
successfully, it doesn't much matter *how* you get that information from the
229
user---most people will give up and walk away before they successfully run the
230
program. This applies whether the user interface is a command-line, a
231
configuration file, or a GUI: if you make that many demands on your users, most
232
of them will simply give up.
234
In short, try to minimize the amount of information that users are absolutely
235
required to supply---use sensible defaults whenever possible. Of course, you
236
also want to make your programs reasonably flexible. That's what options are
237
for. Again, it doesn't matter if they are entries in a config file, widgets in
238
the "Preferences" dialog of a GUI, or command-line options---the more options
239
you implement, the more flexible your program is, and the more complicated its
240
implementation becomes. Too much flexibility has drawbacks as well, of course;
241
too many options can overwhelm users and make your code much harder to maintain.
244
.. _optparse-tutorial:
249
While :mod:`optparse` is quite flexible and powerful, it's also straightforward
250
to use in most cases. This section covers the code patterns that are common to
251
any :mod:`optparse`\ -based program.
253
First, you need to import the OptionParser class; then, early in the main
254
program, create an OptionParser instance::
256
from optparse import OptionParser
258
parser = OptionParser()
260
Then you can start defining options. The basic syntax is::
262
parser.add_option(opt_str, ...,
265
Each option has one or more option strings, such as ``-f`` or ``--file``,
266
and several option attributes that tell :mod:`optparse` what to expect and what
267
to do when it encounters that option on the command line.
269
Typically, each option will have one short option string and one long option
272
parser.add_option("-f", "--file", ...)
274
You're free to define as many short option strings and as many long option
275
strings as you like (including zero), as long as there is at least one option
278
The option strings passed to :meth:`OptionParser.add_option` are effectively
280
option defined by that call. For brevity, we will frequently refer to
281
*encountering an option* on the command line; in reality, :mod:`optparse`
282
encounters *option strings* and looks up options from them.
284
Once all of your options are defined, instruct :mod:`optparse` to parse your
285
program's command line::
287
(options, args) = parser.parse_args()
289
(If you like, you can pass a custom argument list to :meth:`parse_args`, but
290
that's rarely necessary: by default it uses ``sys.argv[1:]``.)
292
:meth:`parse_args` returns two values:
294
* ``options``, an object containing values for all of your options---e.g. if
295
``--file`` takes a single string argument, then ``options.file`` will be the
296
filename supplied by the user, or ``None`` if the user did not supply that
299
* ``args``, the list of positional arguments leftover after parsing options
301
This tutorial section only covers the four most important option attributes:
302
:attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
303
(destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
307
.. _optparse-understanding-option-actions:
309
Understanding option actions
310
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
312
Actions tell :mod:`optparse` what to do when it encounters an option on the
313
command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
314
adding new actions is an advanced topic covered in section
315
:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
316
a value in some variable---for example, take a string from the command line and
317
store it in an attribute of ``options``.
319
If you don't specify an option action, :mod:`optparse` defaults to ``store``.
322
.. _optparse-store-action:
327
The most common option action is ``store``, which tells :mod:`optparse` to take
328
the next argument (or the remainder of the current argument), ensure that it is
329
of the correct type, and store it to your chosen destination.
333
parser.add_option("-f", "--file",
334
action="store", type="string", dest="filename")
336
Now let's make up a fake command line and ask :mod:`optparse` to parse it::
338
args = ["-f", "foo.txt"]
339
(options, args) = parser.parse_args(args)
341
When :mod:`optparse` sees the option string ``-f``, it consumes the next
342
argument, ``foo.txt``, and stores it in ``options.filename``. So, after this
343
call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
345
Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
346
Here's an option that expects an integer argument::
348
parser.add_option("-n", type="int", dest="num")
350
Note that this option has no long option string, which is perfectly acceptable.
351
Also, there's no explicit action, since the default is ``store``.
353
Let's parse another fake command-line. This time, we'll jam the option argument
354
right up against the option: since ``-n42`` (one argument) is equivalent to
355
``-n 42`` (two arguments), the code ::
357
(options, args) = parser.parse_args(["-n42"])
362
If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
363
the fact that the default action is ``store``, that means our first example can
366
parser.add_option("-f", "--file", dest="filename")
368
If you don't supply a destination, :mod:`optparse` figures out a sensible
369
default from the option strings: if the first long option string is
370
``--foo-bar``, then the default destination is ``foo_bar``. If there are no
371
long option strings, :mod:`optparse` looks at the first short option string: the
372
default destination for ``-f`` is ``f``.
374
:mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding
375
types is covered in section :ref:`optparse-extending-optparse`.
378
.. _optparse-handling-boolean-options:
380
Handling boolean (flag) options
381
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383
Flag options---set a variable to true or false when a particular option is seen
384
---are quite common. :mod:`optparse` supports them with two separate actions,
385
``store_true`` and ``store_false``. For example, you might have a ``verbose``
386
flag that is turned on with ``-v`` and off with ``-q``::
388
parser.add_option("-v", action="store_true", dest="verbose")
389
parser.add_option("-q", action="store_false", dest="verbose")
391
Here we have two different options with the same destination, which is perfectly
392
OK. (It just means you have to be a bit careful when setting default values---
395
When :mod:`optparse` encounters ``-v`` on the command line, it sets
396
``options.verbose`` to ``True``; when it encounters ``-q``,
397
``options.verbose`` is set to ``False``.
400
.. _optparse-other-actions:
405
Some other actions supported by :mod:`optparse` are:
408
store a constant value
411
append this option's argument to a list
414
increment a counter by one
417
call a specified function
419
These are covered in section :ref:`optparse-reference-guide`, Reference Guide
420
and section :ref:`optparse-option-callbacks`.
423
.. _optparse-default-values:
428
All of the above examples involve setting some variable (the "destination") when
429
certain command-line options are seen. What happens if those options are never
430
seen? Since we didn't supply any defaults, they are all set to ``None``. This
431
is usually fine, but sometimes you want more control. :mod:`optparse` lets you
432
supply a default value for each destination, which is assigned before the
433
command line is parsed.
435
First, consider the verbose/quiet example. If we want :mod:`optparse` to set
436
``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
438
parser.add_option("-v", action="store_true", dest="verbose", default=True)
439
parser.add_option("-q", action="store_false", dest="verbose")
441
Since default values apply to the *destination* rather than to any particular
442
option, and these two options happen to have the same destination, this is
445
parser.add_option("-v", action="store_true", dest="verbose")
446
parser.add_option("-q", action="store_false", dest="verbose", default=True)
450
parser.add_option("-v", action="store_true", dest="verbose", default=False)
451
parser.add_option("-q", action="store_false", dest="verbose", default=True)
453
Again, the default value for ``verbose`` will be ``True``: the last default
454
value supplied for any particular destination is the one that counts.
456
A clearer way to specify default values is the :meth:`set_defaults` method of
457
OptionParser, which you can call at any time before calling :meth:`parse_args`::
459
parser.set_defaults(verbose=True)
460
parser.add_option(...)
461
(options, args) = parser.parse_args()
463
As before, the last value specified for a given option destination is the one
464
that counts. For clarity, try to use one method or the other of setting default
468
.. _optparse-generating-help:
473
:mod:`optparse`'s ability to generate help and usage text automatically is
474
useful for creating user-friendly command-line interfaces. All you have to do
475
is supply a :attr:`~Option.help` value for each option, and optionally a short
476
usage message for your whole program. Here's an OptionParser populated with
477
user-friendly (documented) options::
479
usage = "usage: %prog [options] arg1 arg2"
480
parser = OptionParser(usage=usage)
481
parser.add_option("-v", "--verbose",
482
action="store_true", dest="verbose", default=True,
483
help="make lots of noise [default]")
484
parser.add_option("-q", "--quiet",
485
action="store_false", dest="verbose",
486
help="be vewwy quiet (I'm hunting wabbits)")
487
parser.add_option("-f", "--filename",
488
metavar="FILE", help="write output to FILE")
489
parser.add_option("-m", "--mode",
490
default="intermediate",
491
help="interaction mode: novice, intermediate, "
492
"or expert [default: %default]")
494
If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
495
command-line, or if you just call :meth:`parser.print_help`, it prints the
496
following to standard output:
500
Usage: <yourscript> [options] arg1 arg2
503
-h, --help show this help message and exit
504
-v, --verbose make lots of noise [default]
505
-q, --quiet be vewwy quiet (I'm hunting wabbits)
506
-f FILE, --filename=FILE
508
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
509
expert [default: intermediate]
511
(If the help output is triggered by a help option, :mod:`optparse` exits after
512
printing the help text.)
514
There's a lot going on here to help :mod:`optparse` generate the best possible
517
* the script defines its own usage message::
519
usage = "usage: %prog [options] arg1 arg2"
521
:mod:`optparse` expands ``%prog`` in the usage string to the name of the
522
current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
523
is then printed before the detailed option help.
525
If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
526
default: ``"Usage: %prog [options]"``, which is fine if your script doesn't
527
take any positional arguments.
529
* every option defines a help string, and doesn't worry about line-wrapping---
530
:mod:`optparse` takes care of wrapping lines and making the help output look
533
* options that take a value indicate this fact in their automatically-generated
534
help message, e.g. for the "mode" option::
538
Here, "MODE" is called the meta-variable: it stands for the argument that the
539
user is expected to supply to ``-m``/``--mode``. By default,
540
:mod:`optparse` converts the destination variable name to uppercase and uses
541
that for the meta-variable. Sometimes, that's not what you want---for
542
example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
543
resulting in this automatically-generated option description::
545
-f FILE, --filename=FILE
547
This is important for more than just saving space, though: the manually
548
written help text uses the meta-variable ``FILE`` to clue the user in that
549
there's a connection between the semi-formal syntax ``-f FILE`` and the informal
550
semantic description "write output to FILE". This is a simple but effective
551
way to make your help text a lot clearer and more useful for end users.
553
.. versionadded:: 2.4
554
Options that have a default value can include ``%default`` in the help
555
string---\ :mod:`optparse` will replace it with :func:`str` of the option's
556
default value. If an option has no default value (or the default value is
557
``None``), ``%default`` expands to ``none``.
562
When dealing with many options, it is convenient to group these options for
563
better help output. An :class:`OptionParser` can contain several option groups,
564
each of which can contain several options.
566
An option group is obtained using the class :class:`OptionGroup`:
568
.. class:: OptionGroup(parser, title, description=None)
572
* parser is the :class:`OptionParser` instance the group will be insterted in
574
* title is the group title
575
* description, optional, is a long description of the group
577
:class:`OptionGroup` inherits from :class:`OptionContainer` (like
578
:class:`OptionParser`) and so the :meth:`add_option` method can be used to add
579
an option to the group.
581
Once all the options are declared, using the :class:`OptionParser` method
582
:meth:`add_option_group` the group is added to the previously defined parser.
584
Continuing with the parser defined in the previous section, adding an
585
:class:`OptionGroup` to a parser is easy::
587
group = OptionGroup(parser, "Dangerous Options",
588
"Caution: use these options at your own risk. "
589
"It is believed that some of them bite.")
590
group.add_option("-g", action="store_true", help="Group option.")
591
parser.add_option_group(group)
593
This would result in the following help output:
597
Usage: <yourscript> [options] arg1 arg2
600
-h, --help show this help message and exit
601
-v, --verbose make lots of noise [default]
602
-q, --quiet be vewwy quiet (I'm hunting wabbits)
603
-f FILE, --filename=FILE
605
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
606
expert [default: intermediate]
609
Caution: use these options at your own risk. It is believed that some
614
A bit more complete example might involve using more than one group: still
615
extending the previous example::
617
group = OptionGroup(parser, "Dangerous Options",
618
"Caution: use these options at your own risk. "
619
"It is believed that some of them bite.")
620
group.add_option("-g", action="store_true", help="Group option.")
621
parser.add_option_group(group)
623
group = OptionGroup(parser, "Debug Options")
624
group.add_option("-d", "--debug", action="store_true",
625
help="Print debug information")
626
group.add_option("-s", "--sql", action="store_true",
627
help="Print all SQL statements executed")
628
group.add_option("-e", action="store_true", help="Print every action done")
629
parser.add_option_group(group)
631
that results in the following output:
635
Usage: <yourscript> [options] arg1 arg2
638
-h, --help show this help message and exit
639
-v, --verbose make lots of noise [default]
640
-q, --quiet be vewwy quiet (I'm hunting wabbits)
641
-f FILE, --filename=FILE
643
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
644
[default: intermediate]
647
Caution: use these options at your own risk. It is believed that some
653
-d, --debug Print debug information
654
-s, --sql Print all SQL statements executed
655
-e Print every action done
657
Another interesting method, in particular when working programmatically with
660
.. method:: OptionParser.get_option_group(opt_str)
662
Return the :class:`OptionGroup` to which the short or long option
663
string *opt_str* (e.g. ``'-o'`` or ``'--option'``) belongs. If
664
there's no such :class:`OptionGroup`, return ``None``.
666
.. _optparse-printing-version-string:
668
Printing a version string
669
^^^^^^^^^^^^^^^^^^^^^^^^^
671
Similar to the brief usage string, :mod:`optparse` can also print a version
672
string for your program. You have to supply the string as the ``version``
673
argument to OptionParser::
675
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
677
``%prog`` is expanded just like it is in ``usage``. Apart from that,
678
``version`` can contain anything you like. When you supply it, :mod:`optparse`
679
automatically adds a ``--version`` option to your parser. If it encounters
680
this option on the command line, it expands your ``version`` string (by
681
replacing ``%prog``), prints it to stdout, and exits.
683
For example, if your script is called ``/usr/bin/foo``::
685
$ /usr/bin/foo --version
688
The following two methods can be used to print and get the ``version`` string:
690
.. method:: OptionParser.print_version(file=None)
692
Print the version message for the current program (``self.version``) to
693
*file* (default stdout). As with :meth:`print_usage`, any occurrence
694
of ``%prog`` in ``self.version`` is replaced with the name of the current
695
program. Does nothing if ``self.version`` is empty or undefined.
697
.. method:: OptionParser.get_version()
699
Same as :meth:`print_version` but returns the version string instead of
703
.. _optparse-how-optparse-handles-errors:
705
How :mod:`optparse` handles errors
706
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
708
There are two broad classes of errors that :mod:`optparse` has to worry about:
709
programmer errors and user errors. Programmer errors are usually erroneous
710
calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
711
option attributes, missing option attributes, etc. These are dealt with in the
712
usual way: raise an exception (either :exc:`optparse.OptionError` or
713
:exc:`TypeError`) and let the program crash.
715
Handling user errors is much more important, since they are guaranteed to happen
716
no matter how stable your code is. :mod:`optparse` can automatically detect
717
some user errors, such as bad option arguments (passing ``-n 4x`` where
718
``-n`` takes an integer argument), missing arguments (``-n`` at the end
719
of the command line, where ``-n`` takes an argument of any type). Also,
720
you can call :func:`OptionParser.error` to signal an application-defined error
723
(options, args) = parser.parse_args()
725
if options.a and options.b:
726
parser.error("options -a and -b are mutually exclusive")
728
In either case, :mod:`optparse` handles the error the same way: it prints the
729
program's usage message and an error message to standard error and exits with
732
Consider the first example above, where the user passes ``4x`` to an option
733
that takes an integer::
738
foo: error: option -n: invalid integer value: '4x'
740
Or, where the user fails to pass a value at all::
745
foo: error: -n option requires an argument
747
:mod:`optparse`\ -generated error messages take care always to mention the
748
option involved in the error; be sure to do the same when calling
749
:func:`OptionParser.error` from your application code.
751
If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
752
you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
753
and/or :meth:`~OptionParser.error` methods.
756
.. _optparse-putting-it-all-together:
758
Putting it all together
759
^^^^^^^^^^^^^^^^^^^^^^^
761
Here's what :mod:`optparse`\ -based scripts usually look like::
763
from optparse import OptionParser
766
usage = "usage: %prog [options] arg"
767
parser = OptionParser(usage)
768
parser.add_option("-f", "--file", dest="filename",
769
help="read data from FILENAME")
770
parser.add_option("-v", "--verbose",
771
action="store_true", dest="verbose")
772
parser.add_option("-q", "--quiet",
773
action="store_false", dest="verbose")
775
(options, args) = parser.parse_args()
777
parser.error("incorrect number of arguments")
779
print "reading %s..." % options.filename
782
if __name__ == "__main__":
786
.. _optparse-reference-guide:
792
.. _optparse-creating-parser:
797
The first step in using :mod:`optparse` is to create an OptionParser instance.
799
.. class:: OptionParser(...)
801
The OptionParser constructor has no required arguments, but a number of
802
optional keyword arguments. You should always pass them as keyword
803
arguments, i.e. do not rely on the order in which the arguments are declared.
805
``usage`` (default: ``"%prog [options]"``)
806
The usage summary to print when your program is run incorrectly or with a
807
help option. When :mod:`optparse` prints the usage string, it expands
808
``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
809
passed that keyword argument). To suppress a usage message, pass the
810
special value :data:`optparse.SUPPRESS_USAGE`.
812
``option_list`` (default: ``[]``)
813
A list of Option objects to populate the parser with. The options in
814
``option_list`` are added after any options in ``standard_option_list`` (a
815
class attribute that may be set by OptionParser subclasses), but before
816
any version or help options. Deprecated; use :meth:`add_option` after
817
creating the parser instead.
819
``option_class`` (default: optparse.Option)
820
Class to use when adding options to the parser in :meth:`add_option`.
822
``version`` (default: ``None``)
823
A version string to print when the user supplies a version option. If you
824
supply a true value for ``version``, :mod:`optparse` automatically adds a
825
version option with the single option string ``--version``. The
826
substring ``%prog`` is expanded the same as for ``usage``.
828
``conflict_handler`` (default: ``"error"``)
829
Specifies what to do when options with conflicting option strings are
830
added to the parser; see section
831
:ref:`optparse-conflicts-between-options`.
833
``description`` (default: ``None``)
834
A paragraph of text giving a brief overview of your program.
835
:mod:`optparse` reformats this paragraph to fit the current terminal width
836
and prints it when the user requests help (after ``usage``, but before the
839
``formatter`` (default: a new :class:`IndentedHelpFormatter`)
840
An instance of optparse.HelpFormatter that will be used for printing help
841
text. :mod:`optparse` provides two concrete classes for this purpose:
842
IndentedHelpFormatter and TitledHelpFormatter.
844
``add_help_option`` (default: ``True``)
845
If true, :mod:`optparse` will add a help option (with option strings ``-h``
846
and ``--help``) to the parser.
849
The string to use when expanding ``%prog`` in ``usage`` and ``version``
850
instead of ``os.path.basename(sys.argv[0])``.
852
``epilog`` (default: ``None``)
853
A paragraph of help text to print after the option help.
855
.. _optparse-populating-parser:
857
Populating the parser
858
^^^^^^^^^^^^^^^^^^^^^
860
There are several ways to populate the parser with options. The preferred way
861
is by using :meth:`OptionParser.add_option`, as shown in section
862
:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
864
* pass it an Option instance (as returned by :func:`make_option`)
866
* pass it any combination of positional and keyword arguments that are
867
acceptable to :func:`make_option` (i.e., to the Option constructor), and it
868
will create the Option instance for you
870
The other alternative is to pass a list of pre-constructed Option instances to
871
the OptionParser constructor, as in::
874
make_option("-f", "--filename",
875
action="store", type="string", dest="filename"),
876
make_option("-q", "--quiet",
877
action="store_false", dest="verbose"),
879
parser = OptionParser(option_list=option_list)
881
(:func:`make_option` is a factory function for creating Option instances;
882
currently it is an alias for the Option constructor. A future version of
883
:mod:`optparse` may split Option into several classes, and :func:`make_option`
884
will pick the right class to instantiate. Do not instantiate Option directly.)
887
.. _optparse-defining-options:
892
Each Option instance represents a set of synonymous command-line option strings,
893
e.g. ``-f`` and ``--file``. You can specify any number of short or
894
long option strings, but you must specify at least one overall option string.
896
The canonical way to create an :class:`Option` instance is with the
897
:meth:`add_option` method of :class:`OptionParser`.
899
.. method:: OptionParser.add_option(option)
900
OptionParser.add_option(*opt_str, attr=value, ...)
902
To define an option with only a short option string::
904
parser.add_option("-f", attr=value, ...)
906
And to define an option with only a long option string::
908
parser.add_option("--foo", attr=value, ...)
910
The keyword arguments define attributes of the new Option object. The most
911
important option attribute is :attr:`~Option.action`, and it largely
912
determines which other attributes are relevant or required. If you pass
913
irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
914
raises an :exc:`OptionError` exception explaining your mistake.
916
An option's *action* determines what :mod:`optparse` does when it encounters
917
this option on the command-line. The standard option actions hard-coded into
921
store this option's argument (default)
924
store a constant value
933
append this option's argument to a list
936
append a constant value to a list
939
increment a counter by one
942
call a specified function
945
print a usage message including all options and the documentation for them
947
(If you don't supply an action, the default is ``"store"``. For this action,
948
you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
949
attributes; see :ref:`optparse-standard-option-actions`.)
951
As you can see, most actions involve storing or updating a value somewhere.
952
:mod:`optparse` always creates a special object for this, conventionally called
953
``options`` (it happens to be an instance of :class:`optparse.Values`). Option
954
arguments (and various other values) are stored as attributes of this object,
955
according to the :attr:`~Option.dest` (destination) option attribute.
957
For example, when you call ::
961
one of the first things :mod:`optparse` does is create the ``options`` object::
965
If one of the options in this parser is defined with ::
967
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
969
and the command-line being parsed includes any of the following::
976
then :mod:`optparse`, on seeing this option, will do the equivalent of ::
978
options.filename = "foo"
980
The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
981
as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
982
one that makes sense for *all* options.
985
.. _optparse-option-attributes:
990
The following option attributes may be passed as keyword arguments to
991
:meth:`OptionParser.add_option`. If you pass an option attribute that is not
992
relevant to a particular option, or fail to pass a required option attribute,
993
:mod:`optparse` raises :exc:`OptionError`.
995
.. attribute:: Option.action
997
(default: ``"store"``)
999
Determines :mod:`optparse`'s behaviour when this option is seen on the
1000
command line; the available options are documented :ref:`here
1001
<optparse-standard-option-actions>`.
1003
.. attribute:: Option.type
1005
(default: ``"string"``)
1007
The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
1008
the available option types are documented :ref:`here
1009
<optparse-standard-option-types>`.
1011
.. attribute:: Option.dest
1013
(default: derived from option strings)
1015
If the option's action implies writing or modifying a value somewhere, this
1016
tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
1017
attribute of the ``options`` object that :mod:`optparse` builds as it parses
1020
.. attribute:: Option.default
1022
The value to use for this option's destination if the option is not seen on
1023
the command line. See also :meth:`OptionParser.set_defaults`.
1025
.. attribute:: Option.nargs
1029
How many arguments of type :attr:`~Option.type` should be consumed when this
1030
option is seen. If > 1, :mod:`optparse` will store a tuple of values to
1031
:attr:`~Option.dest`.
1033
.. attribute:: Option.const
1035
For actions that store a constant value, the constant value to store.
1037
.. attribute:: Option.choices
1039
For options of type ``"choice"``, the list of strings the user may choose
1042
.. attribute:: Option.callback
1044
For options with action ``"callback"``, the callable to call when this option
1045
is seen. See section :ref:`optparse-option-callbacks` for detail on the
1046
arguments passed to the callable.
1048
.. attribute:: Option.callback_args
1049
Option.callback_kwargs
1051
Additional positional and keyword arguments to pass to ``callback`` after the
1052
four standard callback arguments.
1054
.. attribute:: Option.help
1056
Help text to print for this option when listing all available options after
1057
the user supplies a :attr:`~Option.help` option (such as ``--help``). If
1058
no help text is supplied, the option will be listed without help text. To
1059
hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
1061
.. attribute:: Option.metavar
1063
(default: derived from option strings)
1065
Stand-in for the option argument(s) to use when printing help text. See
1066
section :ref:`optparse-tutorial` for an example.
1069
.. _optparse-standard-option-actions:
1071
Standard option actions
1072
^^^^^^^^^^^^^^^^^^^^^^^
1074
The various option actions all have slightly different requirements and effects.
1075
Most actions have several relevant option attributes which you may specify to
1076
guide :mod:`optparse`'s behaviour; a few have required attributes, which you
1077
must specify for any option using that action.
1079
* ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
1080
:attr:`~Option.nargs`, :attr:`~Option.choices`]
1082
The option must be followed by an argument, which is converted to a value
1083
according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
1084
:attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
1085
command line; all will be converted according to :attr:`~Option.type` and
1086
stored to :attr:`~Option.dest` as a tuple. See the
1087
:ref:`optparse-standard-option-types` section.
1089
If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
1090
defaults to ``"choice"``.
1092
If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
1094
If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
1095
from the first long option string (e.g., ``--foo-bar`` implies
1096
``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
1097
destination from the first short option string (e.g., ``-f`` implies ``f``).
1101
parser.add_option("-f")
1102
parser.add_option("-p", type="float", nargs=3, dest="point")
1104
As it parses the command line ::
1106
-f foo.txt -p 1 -3.5 4 -fbar.txt
1108
:mod:`optparse` will set ::
1110
options.f = "foo.txt"
1111
options.point = (1.0, -3.5, 4.0)
1112
options.f = "bar.txt"
1114
* ``"store_const"`` [required: :attr:`~Option.const`; relevant:
1115
:attr:`~Option.dest`]
1117
The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
1121
parser.add_option("-q", "--quiet",
1122
action="store_const", const=0, dest="verbose")
1123
parser.add_option("-v", "--verbose",
1124
action="store_const", const=1, dest="verbose")
1125
parser.add_option("--noisy",
1126
action="store_const", const=2, dest="verbose")
1128
If ``--noisy`` is seen, :mod:`optparse` will set ::
1132
* ``"store_true"`` [relevant: :attr:`~Option.dest`]
1134
A special case of ``"store_const"`` that stores a true value to
1135
:attr:`~Option.dest`.
1137
* ``"store_false"`` [relevant: :attr:`~Option.dest`]
1139
Like ``"store_true"``, but stores a false value.
1143
parser.add_option("--clobber", action="store_true", dest="clobber")
1144
parser.add_option("--no-clobber", action="store_false", dest="clobber")
1146
* ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
1147
:attr:`~Option.nargs`, :attr:`~Option.choices`]
1149
The option must be followed by an argument, which is appended to the list in
1150
:attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
1151
supplied, an empty list is automatically created when :mod:`optparse` first
1152
encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
1153
multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
1154
is appended to :attr:`~Option.dest`.
1156
The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
1157
for the ``"store"`` action.
1161
parser.add_option("-t", "--tracks", action="append", type="int")
1163
If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
1167
options.tracks.append(int("3"))
1169
If, a little later on, ``--tracks=4`` is seen, it does::
1171
options.tracks.append(int("4"))
1173
The ``append`` action calls the ``append`` method on the current value of the
1174
option. This means that any default value specified must have an ``append``
1175
method. It also means that if the default value is non-empty, the default
1176
elements will be present in the parsed value for the option, with any values
1177
from the command line appended after those default values::
1179
>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
1180
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
1182
['~/.mypkg/defaults', 'overrides.mypkg']
1184
* ``"append_const"`` [required: :attr:`~Option.const`; relevant:
1185
:attr:`~Option.dest`]
1187
Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
1188
:attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
1189
``None``, and an empty list is automatically created the first time the option
1192
* ``"count"`` [relevant: :attr:`~Option.dest`]
1194
Increment the integer stored at :attr:`~Option.dest`. If no default value is
1195
supplied, :attr:`~Option.dest` is set to zero before being incremented the
1200
parser.add_option("-v", action="count", dest="verbosity")
1202
The first time ``-v`` is seen on the command line, :mod:`optparse` does the
1205
options.verbosity = 0
1206
options.verbosity += 1
1208
Every subsequent occurrence of ``-v`` results in ::
1210
options.verbosity += 1
1212
* ``"callback"`` [required: :attr:`~Option.callback`; relevant:
1213
:attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
1214
:attr:`~Option.callback_kwargs`]
1216
Call the function specified by :attr:`~Option.callback`, which is called as ::
1218
func(option, opt_str, value, parser, *args, **kwargs)
1220
See section :ref:`optparse-option-callbacks` for more detail.
1224
Prints a complete help message for all the options in the current option
1225
parser. The help message is constructed from the ``usage`` string passed to
1226
OptionParser's constructor and the :attr:`~Option.help` string passed to every
1229
If no :attr:`~Option.help` string is supplied for an option, it will still be
1230
listed in the help message. To omit an option entirely, use the special value
1231
:data:`optparse.SUPPRESS_HELP`.
1233
:mod:`optparse` automatically adds a :attr:`~Option.help` option to all
1234
OptionParsers, so you do not normally need to create one.
1238
from optparse import OptionParser, SUPPRESS_HELP
1240
# usually, a help option is added automatically, but that can
1241
# be suppressed using the add_help_option argument
1242
parser = OptionParser(add_help_option=False)
1244
parser.add_option("-h", "--help", action="help")
1245
parser.add_option("-v", action="store_true", dest="verbose",
1246
help="Be moderately verbose")
1247
parser.add_option("--file", dest="filename",
1248
help="Input file to read data from")
1249
parser.add_option("--secret", help=SUPPRESS_HELP)
1251
If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
1252
it will print something like the following help message to stdout (assuming
1253
``sys.argv[0]`` is ``"foo.py"``):
1255
.. code-block:: text
1257
Usage: foo.py [options]
1260
-h, --help Show this help message and exit
1261
-v Be moderately verbose
1262
--file=FILENAME Input file to read data from
1264
After printing the help message, :mod:`optparse` terminates your process with
1269
Prints the version number supplied to the OptionParser to stdout and exits.
1270
The version number is actually formatted and printed by the
1271
``print_version()`` method of OptionParser. Generally only relevant if the
1272
``version`` argument is supplied to the OptionParser constructor. As with
1273
:attr:`~Option.help` options, you will rarely create ``version`` options,
1274
since :mod:`optparse` automatically adds them when needed.
1277
.. _optparse-standard-option-types:
1279
Standard option types
1280
^^^^^^^^^^^^^^^^^^^^^
1282
:mod:`optparse` has six built-in option types: ``"string"``, ``"int"``,
1283
``"long"``, ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
1284
option types, see section :ref:`optparse-extending-optparse`.
1286
Arguments to string options are not checked or converted in any way: the text on
1287
the command line is stored in the destination (or passed to the callback) as-is.
1289
Integer arguments (type ``"int"`` or ``"long"``) are parsed as follows:
1291
* if the number starts with ``0x``, it is parsed as a hexadecimal number
1293
* if the number starts with ``0``, it is parsed as an octal number
1295
* if the number starts with ``0b``, it is parsed as a binary number
1297
* otherwise, the number is parsed as a decimal number
1300
The conversion is done by calling either :func:`int` or :func:`long` with the
1301
appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`,
1302
although with a more useful error message.
1304
``"float"`` and ``"complex"`` option arguments are converted directly with
1305
:func:`float` and :func:`complex`, with similar error-handling.
1307
``"choice"`` options are a subtype of ``"string"`` options. The
1308
:attr:`~Option.choices` option attribute (a sequence of strings) defines the
1309
set of allowed option arguments. :func:`optparse.check_choice` compares
1310
user-supplied option arguments against this master list and raises
1311
:exc:`OptionValueError` if an invalid string is given.
1314
.. _optparse-parsing-arguments:
1319
The whole point of creating and populating an OptionParser is to call its
1320
:meth:`parse_args` method::
1322
(options, args) = parser.parse_args(args=None, values=None)
1324
where the input parameters are
1327
the list of arguments to process (default: ``sys.argv[1:]``)
1330
a :class:`optparse.Values` object to store option arguments in (default: a
1331
new instance of :class:`Values`) -- if you give an existing object, the
1332
option defaults will not be initialized on it
1334
and the return values are
1337
the same object that was passed in as ``values``, or the optparse.Values
1338
instance created by :mod:`optparse`
1341
the leftover positional arguments after all options have been processed
1343
The most common usage is to supply neither keyword argument. If you supply
1344
``values``, it will be modified with repeated :func:`setattr` calls (roughly one
1345
for every option argument stored to an option destination) and returned by
1348
If :meth:`parse_args` encounters any errors in the argument list, it calls the
1349
OptionParser's :meth:`error` method with an appropriate end-user error message.
1350
This ultimately terminates your process with an exit status of 2 (the
1351
traditional Unix exit status for command-line errors).
1354
.. _optparse-querying-manipulating-option-parser:
1356
Querying and manipulating your option parser
1357
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1359
The default behavior of the option parser can be customized slightly, and you
1360
can also poke around your option parser and see what's there. OptionParser
1361
provides several methods to help you out:
1363
.. method:: OptionParser.disable_interspersed_args()
1365
Set parsing to stop on the first non-option. For example, if ``-a`` and
1366
``-b`` are both simple options that take no arguments, :mod:`optparse`
1367
normally accepts this syntax::
1369
prog -a arg1 -b arg2
1371
and treats it as equivalent to ::
1373
prog -a -b arg1 arg2
1375
To disable this feature, call :meth:`disable_interspersed_args`. This
1376
restores traditional Unix syntax, where option parsing stops with the first
1377
non-option argument.
1379
Use this if you have a command processor which runs another command which has
1380
options of its own and you want to make sure these options don't get
1381
confused. For example, each command might have a different set of options.
1383
.. method:: OptionParser.enable_interspersed_args()
1385
Set parsing to not stop on the first non-option, allowing interspersing
1386
switches with command arguments. This is the default behavior.
1388
.. method:: OptionParser.get_option(opt_str)
1390
Returns the Option instance with the option string *opt_str*, or ``None`` if
1391
no options have that option string.
1393
.. method:: OptionParser.has_option(opt_str)
1395
Return true if the OptionParser has an option with option string *opt_str*
1396
(e.g., ``-q`` or ``--verbose``).
1398
.. method:: OptionParser.remove_option(opt_str)
1400
If the :class:`OptionParser` has an option corresponding to *opt_str*, that
1401
option is removed. If that option provided any other option strings, all of
1402
those option strings become invalid. If *opt_str* does not occur in any
1403
option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
1406
.. _optparse-conflicts-between-options:
1408
Conflicts between options
1409
^^^^^^^^^^^^^^^^^^^^^^^^^
1411
If you're not careful, it's easy to define options with conflicting option
1414
parser.add_option("-n", "--dry-run", ...)
1416
parser.add_option("-n", "--noisy", ...)
1418
(This is particularly true if you've defined your own OptionParser subclass with
1419
some standard options.)
1421
Every time you add an option, :mod:`optparse` checks for conflicts with existing
1422
options. If it finds any, it invokes the current conflict-handling mechanism.
1423
You can set the conflict-handling mechanism either in the constructor::
1425
parser = OptionParser(..., conflict_handler=handler)
1427
or with a separate call::
1429
parser.set_conflict_handler(handler)
1431
The available conflict handlers are:
1433
``"error"`` (default)
1434
assume option conflicts are a programming error and raise
1435
:exc:`OptionConflictError`
1438
resolve option conflicts intelligently (see below)
1441
As an example, let's define an :class:`OptionParser` that resolves conflicts
1442
intelligently and add conflicting options to it::
1444
parser = OptionParser(conflict_handler="resolve")
1445
parser.add_option("-n", "--dry-run", ..., help="do no harm")
1446
parser.add_option("-n", "--noisy", ..., help="be noisy")
1448
At this point, :mod:`optparse` detects that a previously-added option is already
1449
using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``,
1450
it resolves the situation by removing ``-n`` from the earlier option's list of
1451
option strings. Now ``--dry-run`` is the only way for the user to activate
1452
that option. If the user asks for help, the help message will reflect that::
1455
--dry-run do no harm
1457
-n, --noisy be noisy
1459
It's possible to whittle away the option strings for a previously-added option
1460
until there are none left, and the user has no way of invoking that option from
1461
the command-line. In that case, :mod:`optparse` removes that option completely,
1462
so it doesn't show up in help text or anywhere else. Carrying on with our
1463
existing OptionParser::
1465
parser.add_option("--dry-run", ..., help="new dry-run option")
1467
At this point, the original ``-n``/``--dry-run`` option is no longer
1468
accessible, so :mod:`optparse` removes it, leaving this help text::
1472
-n, --noisy be noisy
1473
--dry-run new dry-run option
1476
.. _optparse-cleanup:
1481
OptionParser instances have several cyclic references. This should not be a
1482
problem for Python's garbage collector, but you may wish to break the cyclic
1483
references explicitly by calling :meth:`~OptionParser.destroy` on your
1484
OptionParser once you are done with it. This is particularly useful in
1485
long-running applications where large object graphs are reachable from your
1489
.. _optparse-other-methods:
1494
OptionParser supports several other public methods:
1496
.. method:: OptionParser.set_usage(usage)
1498
Set the usage string according to the rules described above for the ``usage``
1499
constructor keyword argument. Passing ``None`` sets the default usage
1500
string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
1502
.. method:: OptionParser.print_usage(file=None)
1504
Print the usage message for the current program (``self.usage``) to *file*
1505
(default stdout). Any occurrence of the string ``%prog`` in ``self.usage``
1506
is replaced with the name of the current program. Does nothing if
1507
``self.usage`` is empty or not defined.
1509
.. method:: OptionParser.get_usage()
1511
Same as :meth:`print_usage` but returns the usage string instead of
1514
.. method:: OptionParser.set_defaults(dest=value, ...)
1516
Set default values for several option destinations at once. Using
1517
:meth:`set_defaults` is the preferred way to set default values for options,
1518
since multiple options can share the same destination. For example, if
1519
several "mode" options all set the same destination, any one of them can set
1520
the default, and the last one wins::
1522
parser.add_option("--advanced", action="store_const",
1523
dest="mode", const="advanced",
1524
default="novice") # overridden below
1525
parser.add_option("--novice", action="store_const",
1526
dest="mode", const="novice",
1527
default="advanced") # overrides above setting
1529
To avoid this confusion, use :meth:`set_defaults`::
1531
parser.set_defaults(mode="advanced")
1532
parser.add_option("--advanced", action="store_const",
1533
dest="mode", const="advanced")
1534
parser.add_option("--novice", action="store_const",
1535
dest="mode", const="novice")
1538
.. _optparse-option-callbacks:
1543
When :mod:`optparse`'s built-in actions and types aren't quite enough for your
1544
needs, you have two choices: extend :mod:`optparse` or define a callback option.
1545
Extending :mod:`optparse` is more general, but overkill for a lot of simple
1546
cases. Quite often a simple callback is all you need.
1548
There are two steps to defining a callback option:
1550
* define the option itself using the ``"callback"`` action
1552
* write the callback; this is a function (or method) that takes at least four
1553
arguments, as described below
1556
.. _optparse-defining-callback-option:
1558
Defining a callback option
1559
^^^^^^^^^^^^^^^^^^^^^^^^^^
1561
As always, the easiest way to define a callback option is by using the
1562
:meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
1563
only option attribute you must specify is ``callback``, the function to call::
1565
parser.add_option("-c", action="callback", callback=my_callback)
1567
``callback`` is a function (or other callable object), so you must have already
1568
defined ``my_callback()`` when you create this callback option. In this simple
1569
case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
1570
which usually means that the option takes no arguments---the mere presence of
1571
``-c`` on the command-line is all it needs to know. In some
1572
circumstances, though, you might want your callback to consume an arbitrary
1573
number of command-line arguments. This is where writing callbacks gets tricky;
1574
it's covered later in this section.
1576
:mod:`optparse` always passes four particular arguments to your callback, and it
1577
will only pass additional arguments if you specify them via
1578
:attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
1579
minimal callback function signature is::
1581
def my_callback(option, opt, value, parser):
1583
The four arguments to a callback are described below.
1585
There are several other option attributes that you can supply when you define a
1588
:attr:`~Option.type`
1589
has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
1590
instructs :mod:`optparse` to consume one argument and convert it to
1591
:attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
1592
though, :mod:`optparse` passes it to your callback function.
1594
:attr:`~Option.nargs`
1595
also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
1596
consume :attr:`~Option.nargs` arguments, each of which must be convertible to
1597
:attr:`~Option.type`. It then passes a tuple of converted values to your
1600
:attr:`~Option.callback_args`
1601
a tuple of extra positional arguments to pass to the callback
1603
:attr:`~Option.callback_kwargs`
1604
a dictionary of extra keyword arguments to pass to the callback
1607
.. _optparse-how-callbacks-called:
1609
How callbacks are called
1610
^^^^^^^^^^^^^^^^^^^^^^^^
1612
All callbacks are called as follows::
1614
func(option, opt_str, value, parser, *args, **kwargs)
1619
is the Option instance that's calling the callback
1622
is the option string seen on the command-line that's triggering the callback.
1623
(If an abbreviated long option was used, ``opt_str`` will be the full,
1624
canonical option string---e.g. if the user puts ``--foo`` on the
1625
command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
1629
is the argument to this option seen on the command-line. :mod:`optparse` will
1630
only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
1631
the type implied by the option's type. If :attr:`~Option.type` for this option is
1632
``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
1633
> 1, ``value`` will be a tuple of values of the appropriate type.
1636
is the OptionParser instance driving the whole thing, mainly useful because
1637
you can access some other interesting data through its instance attributes:
1640
the current list of leftover arguments, ie. arguments that have been
1641
consumed but are neither options nor option arguments. Feel free to modify
1642
``parser.largs``, e.g. by adding more arguments to it. (This list will
1643
become ``args``, the second return value of :meth:`parse_args`.)
1646
the current list of remaining arguments, ie. with ``opt_str`` and
1647
``value`` (if applicable) removed, and only the arguments following them
1648
still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
1652
the object where option values are by default stored (an instance of
1653
optparse.OptionValues). This lets callbacks use the same mechanism as the
1654
rest of :mod:`optparse` for storing option values; you don't need to mess
1655
around with globals or closures. You can also access or modify the
1656
value(s) of any options already encountered on the command-line.
1659
is a tuple of arbitrary positional arguments supplied via the
1660
:attr:`~Option.callback_args` option attribute.
1663
is a dictionary of arbitrary keyword arguments supplied via
1664
:attr:`~Option.callback_kwargs`.
1667
.. _optparse-raising-errors-in-callback:
1669
Raising errors in a callback
1670
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1672
The callback function should raise :exc:`OptionValueError` if there are any
1673
problems with the option or its argument(s). :mod:`optparse` catches this and
1674
terminates the program, printing the error message you supply to stderr. Your
1675
message should be clear, concise, accurate, and mention the option at fault.
1676
Otherwise, the user will have a hard time figuring out what he did wrong.
1679
.. _optparse-callback-example-1:
1681
Callback example 1: trivial callback
1682
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1684
Here's an example of a callback option that takes no arguments, and simply
1685
records that the option was seen::
1687
def record_foo_seen(option, opt_str, value, parser):
1688
parser.values.saw_foo = True
1690
parser.add_option("--foo", action="callback", callback=record_foo_seen)
1692
Of course, you could do that with the ``"store_true"`` action.
1695
.. _optparse-callback-example-2:
1697
Callback example 2: check option order
1698
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1700
Here's a slightly more interesting example: record the fact that ``-a`` is
1701
seen, but blow up if it comes after ``-b`` in the command-line. ::
1703
def check_order(option, opt_str, value, parser):
1705
raise OptionValueError("can't use -a after -b")
1708
parser.add_option("-a", action="callback", callback=check_order)
1709
parser.add_option("-b", action="store_true", dest="b")
1712
.. _optparse-callback-example-3:
1714
Callback example 3: check option order (generalized)
1715
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1717
If you want to re-use this callback for several similar options (set a flag, but
1718
blow up if ``-b`` has already been seen), it needs a bit of work: the error
1719
message and the flag that it sets must be generalized. ::
1721
def check_order(option, opt_str, value, parser):
1723
raise OptionValueError("can't use %s after -b" % opt_str)
1724
setattr(parser.values, option.dest, 1)
1726
parser.add_option("-a", action="callback", callback=check_order, dest='a')
1727
parser.add_option("-b", action="store_true", dest="b")
1728
parser.add_option("-c", action="callback", callback=check_order, dest='c')
1731
.. _optparse-callback-example-4:
1733
Callback example 4: check arbitrary condition
1734
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1736
Of course, you could put any condition in there---you're not limited to checking
1737
the values of already-defined options. For example, if you have options that
1738
should not be called when the moon is full, all you have to do is this::
1740
def check_moon(option, opt_str, value, parser):
1742
raise OptionValueError("%s option invalid when moon is full"
1744
setattr(parser.values, option.dest, 1)
1746
parser.add_option("--foo",
1747
action="callback", callback=check_moon, dest="foo")
1749
(The definition of ``is_moon_full()`` is left as an exercise for the reader.)
1752
.. _optparse-callback-example-5:
1754
Callback example 5: fixed arguments
1755
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1757
Things get slightly more interesting when you define callback options that take
1758
a fixed number of arguments. Specifying that a callback option takes arguments
1759
is similar to defining a ``"store"`` or ``"append"`` option: if you define
1760
:attr:`~Option.type`, then the option takes one argument that must be
1761
convertible to that type; if you further define :attr:`~Option.nargs`, then the
1762
option takes :attr:`~Option.nargs` arguments.
1764
Here's an example that just emulates the standard ``"store"`` action::
1766
def store_value(option, opt_str, value, parser):
1767
setattr(parser.values, option.dest, value)
1769
parser.add_option("--foo",
1770
action="callback", callback=store_value,
1771
type="int", nargs=3, dest="foo")
1773
Note that :mod:`optparse` takes care of consuming 3 arguments and converting
1774
them to integers for you; all you have to do is store them. (Or whatever;
1775
obviously you don't need a callback for this example.)
1778
.. _optparse-callback-example-6:
1780
Callback example 6: variable arguments
1781
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1783
Things get hairy when you want an option to take a variable number of arguments.
1784
For this case, you must write a callback, as :mod:`optparse` doesn't provide any
1785
built-in capabilities for it. And you have to deal with certain intricacies of
1786
conventional Unix command-line parsing that :mod:`optparse` normally handles for
1787
you. In particular, callbacks should implement the conventional rules for bare
1788
``--`` and ``-`` arguments:
1790
* either ``--`` or ``-`` can be option arguments
1792
* bare ``--`` (if not the argument to some option): halt command-line
1793
processing and discard the ``--``
1795
* bare ``-`` (if not the argument to some option): halt command-line
1796
processing but keep the ``-`` (append it to ``parser.largs``)
1798
If you want an option that takes a variable number of arguments, there are
1799
several subtle, tricky issues to worry about. The exact implementation you
1800
choose will be based on which trade-offs you're willing to make for your
1801
application (which is why :mod:`optparse` doesn't support this sort of thing
1804
Nevertheless, here's a stab at a callback for an option with variable
1807
def vararg_callback(option, opt_str, value, parser):
1808
assert value is None
1818
for arg in parser.rargs:
1819
# stop on --foo like options
1820
if arg[:2] == "--" and len(arg) > 2:
1822
# stop on -a, but not on -3 or -3.0
1823
if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
1827
del parser.rargs[:len(value)]
1828
setattr(parser.values, option.dest, value)
1831
parser.add_option("-c", "--callback", dest="vararg_attr",
1832
action="callback", callback=vararg_callback)
1835
.. _optparse-extending-optparse:
1837
Extending :mod:`optparse`
1838
-------------------------
1840
Since the two major controlling factors in how :mod:`optparse` interprets
1841
command-line options are the action and type of each option, the most likely
1842
direction of extension is to add new actions and new types.
1845
.. _optparse-adding-new-types:
1850
To add new types, you need to define your own subclass of :mod:`optparse`'s
1851
:class:`Option` class. This class has a couple of attributes that define
1852
:mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
1854
.. attribute:: Option.TYPES
1856
A tuple of type names; in your subclass, simply define a new tuple
1857
:attr:`TYPES` that builds on the standard one.
1859
.. attribute:: Option.TYPE_CHECKER
1861
A dictionary mapping type names to type-checking functions. A type-checking
1862
function has the following signature::
1864
def check_mytype(option, opt, value)
1866
where ``option`` is an :class:`Option` instance, ``opt`` is an option string
1867
(e.g., ``-f``), and ``value`` is the string from the command line that must
1868
be checked and converted to your desired type. ``check_mytype()`` should
1869
return an object of the hypothetical type ``mytype``. The value returned by
1870
a type-checking function will wind up in the OptionValues instance returned
1871
by :meth:`OptionParser.parse_args`, or be passed to a callback as the
1872
``value`` parameter.
1874
Your type-checking function should raise :exc:`OptionValueError` if it
1875
encounters any problems. :exc:`OptionValueError` takes a single string
1876
argument, which is passed as-is to :class:`OptionParser`'s :meth:`error`
1877
method, which in turn prepends the program name and the string ``"error:"``
1878
and prints everything to stderr before terminating the process.
1880
Here's a silly example that demonstrates adding a ``"complex"`` option type to
1881
parse Python-style complex numbers on the command line. (This is even sillier
1882
than it used to be, because :mod:`optparse` 1.3 added built-in support for
1883
complex numbers, but never mind.)
1885
First, the necessary imports::
1887
from copy import copy
1888
from optparse import Option, OptionValueError
1890
You need to define your type-checker first, since it's referred to later (in the
1891
:attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
1893
def check_complex(option, opt, value):
1895
return complex(value)
1897
raise OptionValueError(
1898
"option %s: invalid complex value: %r" % (opt, value))
1900
Finally, the Option subclass::
1902
class MyOption (Option):
1903
TYPES = Option.TYPES + ("complex",)
1904
TYPE_CHECKER = copy(Option.TYPE_CHECKER)
1905
TYPE_CHECKER["complex"] = check_complex
1907
(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
1908
up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
1909
Option class. This being Python, nothing stops you from doing that except good
1910
manners and common sense.)
1912
That's it! Now you can write a script that uses the new option type just like
1913
any other :mod:`optparse`\ -based script, except you have to instruct your
1914
OptionParser to use MyOption instead of Option::
1916
parser = OptionParser(option_class=MyOption)
1917
parser.add_option("-c", type="complex")
1919
Alternately, you can build your own option list and pass it to OptionParser; if
1920
you don't use :meth:`add_option` in the above way, you don't need to tell
1921
OptionParser which option class to use::
1923
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
1924
parser = OptionParser(option_list=option_list)
1927
.. _optparse-adding-new-actions:
1932
Adding new actions is a bit trickier, because you have to understand that
1933
:mod:`optparse` has a couple of classifications for actions:
1936
actions that result in :mod:`optparse` storing a value to an attribute of the
1937
current OptionValues instance; these options require a :attr:`~Option.dest`
1938
attribute to be supplied to the Option constructor.
1941
actions that take a value from the command line and expect it to be of a
1942
certain type; or rather, a string that can be converted to a certain type.
1943
These options require a :attr:`~Option.type` attribute to the Option
1946
These are overlapping sets: some default "store" actions are ``"store"``,
1947
``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
1948
actions are ``"store"``, ``"append"``, and ``"callback"``.
1950
When you add an action, you need to categorize it by listing it in at least one
1951
of the following class attributes of Option (all are lists of strings):
1953
.. attribute:: Option.ACTIONS
1955
All actions must be listed in ACTIONS.
1957
.. attribute:: Option.STORE_ACTIONS
1959
"store" actions are additionally listed here.
1961
.. attribute:: Option.TYPED_ACTIONS
1963
"typed" actions are additionally listed here.
1965
.. attribute:: Option.ALWAYS_TYPED_ACTIONS
1967
Actions that always take a type (i.e. whose options always take a value) are
1968
additionally listed here. The only effect of this is that :mod:`optparse`
1969
assigns the default type, ``"string"``, to options with no explicit type
1970
whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
1972
In order to actually implement your new action, you must override Option's
1973
:meth:`take_action` method and add a case that recognizes your action.
1975
For example, let's add an ``"extend"`` action. This is similar to the standard
1976
``"append"`` action, but instead of taking a single value from the command-line
1977
and appending it to an existing list, ``"extend"`` will take multiple values in
1978
a single comma-delimited string, and extend an existing list with them. That
1979
is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command
1982
--names=foo,bar --names blah --names ding,dong
1984
would result in a list ::
1986
["foo", "bar", "blah", "ding", "dong"]
1988
Again we define a subclass of Option::
1990
class MyOption(Option):
1992
ACTIONS = Option.ACTIONS + ("extend",)
1993
STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
1994
TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
1995
ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
1997
def take_action(self, action, dest, opt, value, values, parser):
1998
if action == "extend":
1999
lvalue = value.split(",")
2000
values.ensure_value(dest, []).extend(lvalue)
2003
self, action, dest, opt, value, values, parser)
2007
* ``"extend"`` both expects a value on the command-line and stores that value
2008
somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
2009
:attr:`~Option.TYPED_ACTIONS`.
2011
* to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
2012
``"extend"`` actions, we put the ``"extend"`` action in
2013
:attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
2015
* :meth:`MyOption.take_action` implements just this one new action, and passes
2016
control back to :meth:`Option.take_action` for the standard :mod:`optparse`
2019
* ``values`` is an instance of the optparse_parser.Values class, which provides
2020
the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
2021
essentially :func:`getattr` with a safety valve; it is called as ::
2023
values.ensure_value(attr, value)
2025
If the ``attr`` attribute of ``values`` doesn't exist or is None, then
2026
ensure_value() first sets it to ``value``, and then returns 'value. This is
2027
very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
2028
of which accumulate data in a variable and expect that variable to be of a
2029
certain type (a list for the first two, an integer for the latter). Using
2030
:meth:`ensure_value` means that scripts using your action don't have to worry
2031
about setting a default value for the option destinations in question; they
2032
can just leave the default as None and :meth:`ensure_value` will take care of
2033
getting it right when it's needed.
added
removed
python-2.7.11-docs-html/_sources/library/optparse.txt
