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>
11 .. sectionauthor:: Greg Ward <gward@python.net>
14 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
15 command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
16 more declarative style of command-line parsing: you create an instance of
17 :class:`OptionParser`, populate it with options, and parse the command
18 line. :mod:`optparse` allows users to specify options in the conventional
19 GNU/POSIX syntax, and additionally generates usage and help messages for you.
21 Here's an example of using :mod:`optparse` in a simple script::
23 from optparse import OptionParser
25 parser = OptionParser()
26 parser.add_option("-f", "--file", dest="filename",
27 help="write report to FILE", metavar="FILE")
28 parser.add_option("-q", "--quiet",
29 action="store_false", dest="verbose", default=True,
30 help="don't print status messages to stdout")
32 (options, args) = parser.parse_args()
34 With these few lines of code, users of your script can now do the "usual thing"
35 on the command-line, for example::
37 <yourscript> --file=outfile -q
39 As it parses the command line, :mod:`optparse` sets attributes of the
40 ``options`` object returned by :meth:`parse_args` based on user-supplied
41 command-line values. When :meth:`parse_args` returns from parsing this command
42 line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
43 ``False``. :mod:`optparse` supports both long and short options, allows short
44 options to be merged together, and allows options to be associated with their
45 arguments in a variety of ways. Thus, the following command lines are all
46 equivalent to the above example::
48 <yourscript> -f outfile --quiet
49 <yourscript> --quiet --file outfile
50 <yourscript> -q -foutfile
51 <yourscript> -qfoutfile
53 Additionally, users can run one of ::
58 and :mod:`optparse` will print out a brief summary of your script's options::
60 usage: <yourscript> [options]
63 -h, --help show this help message and exit
64 -f FILE, --file=FILE write report to FILE
65 -q, --quiet don't print status messages to stdout
67 where the value of *yourscript* is determined at runtime (normally from
71 .. _optparse-background:
76 :mod:`optparse` was explicitly designed to encourage the creation of programs
77 with straightforward, conventional command-line interfaces. To that end, it
78 supports only the most common command-line syntax and semantics conventionally
79 used under Unix. If you are unfamiliar with these conventions, read this
80 section to acquaint yourself with them.
83 .. _optparse-terminology:
89 a string entered on the command-line, and passed by the shell to ``execl()``
90 or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
91 (``sys.argv[0]`` is the name of the program being executed). Unix shells
92 also use the term "word".
94 It is occasionally desirable to substitute an argument list other than
95 ``sys.argv[1:]``, so you should read "argument" as "an element of
96 ``sys.argv[1:]``, or of some other list provided as a substitute for
100 an argument used to supply extra information to guide or customize the
101 execution of a program. There are many different syntaxes for options; the
102 traditional Unix syntax is a hyphen ("-") followed by a single letter,
103 e.g. ``"-x"`` or ``"-F"``. Also, traditional Unix syntax allows multiple
104 options to be merged into a single argument, e.g. ``"-x -F"`` is equivalent
105 to ``"-xF"``. The GNU project introduced ``"--"`` followed by a series of
106 hyphen-separated words, e.g. ``"--file"`` or ``"--dry-run"``. These are the
107 only two option syntaxes provided by :mod:`optparse`.
109 Some other option syntaxes that the world has seen include:
111 * a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same
112 as multiple options merged into a single argument)
114 * a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically
115 equivalent to the previous syntax, but they aren't usually seen in the same
118 * a plus sign followed by a single letter, or a few letters, or a word, e.g.
121 * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
124 These option syntaxes are not supported by :mod:`optparse`, and they never
125 will be. This is deliberate: the first three are non-standard on any
126 environment, and the last only makes sense if you're exclusively targeting
127 VMS, MS-DOS, and/or Windows.
130 an argument that follows an option, is closely associated with that option,
131 and is consumed from the argument list when that option is. With
132 :mod:`optparse`, option arguments may either be in a separate argument from
138 or included in the same argument::
143 Typically, a given option either takes an argument or it doesn't. Lots of
144 people want an "optional option arguments" feature, meaning that some options
145 will take an argument if they see it, and won't if they don't. This is
146 somewhat controversial, because it makes parsing ambiguous: if ``"-a"`` takes
147 an optional argument and ``"-b"`` is another option entirely, how do we
148 interpret ``"-ab"``? Because of this ambiguity, :mod:`optparse` does not
149 support this feature.
152 something leftover in the argument list after options have been parsed, i.e.
153 after options and their arguments have been parsed and removed from the
157 an option that must be supplied on the command-line; note that the phrase
158 "required option" is self-contradictory in English. :mod:`optparse` doesn't
159 prevent you from implementing required options, but doesn't give you much
162 For example, consider this hypothetical command-line::
164 prog -v --report /tmp/report.txt foo bar
166 ``"-v"`` and ``"--report"`` are both options. Assuming that :option:`--report`
167 takes one argument, ``"/tmp/report.txt"`` is an option argument. ``"foo"`` and
168 ``"bar"`` are positional arguments.
171 .. _optparse-what-options-for:
173 What are options for?
174 ^^^^^^^^^^^^^^^^^^^^^
176 Options are used to provide extra information to tune or customize the execution
177 of a program. In case it wasn't clear, options are usually *optional*. A
178 program should be able to run just fine with no options whatsoever. (Pick a
179 random program from the Unix or GNU toolsets. Can it run without any options at
180 all and still make sense? The main exceptions are ``find``, ``tar``, and
181 ``dd``\ ---all of which are mutant oddballs that have been rightly criticized
182 for their non-standard syntax and confusing interfaces.)
184 Lots of people want their programs to have "required options". Think about it.
185 If it's required, then it's *not optional*! If there is a piece of information
186 that your program absolutely requires in order to run successfully, that's what
187 positional arguments are for.
189 As an example of good command-line interface design, consider the humble ``cp``
190 utility, for copying files. It doesn't make much sense to try to copy files
191 without supplying a destination and at least one source. Hence, ``cp`` fails if
192 you run it with no arguments. However, it has a flexible, useful syntax that
193 does not require any options at all::
196 cp SOURCE ... DEST-DIR
198 You can get pretty far with just that. Most ``cp`` implementations provide a
199 bunch of options to tweak exactly how the files are copied: you can preserve
200 mode and modification time, avoid following symlinks, ask before clobbering
201 existing files, etc. But none of this distracts from the core mission of
202 ``cp``, which is to copy either one file to another, or several files to another
206 .. _optparse-what-positional-arguments-for:
208 What are positional arguments for?
209 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
211 Positional arguments are for those pieces of information that your program
212 absolutely, positively requires to run.
214 A good user interface should have as few absolute requirements as possible. If
215 your program requires 17 distinct pieces of information in order to run
216 successfully, it doesn't much matter *how* you get that information from the
217 user---most people will give up and walk away before they successfully run the
218 program. This applies whether the user interface is a command-line, a
219 configuration file, or a GUI: if you make that many demands on your users, most
220 of them will simply give up.
222 In short, try to minimize the amount of information that users are absolutely
223 required to supply---use sensible defaults whenever possible. Of course, you
224 also want to make your programs reasonably flexible. That's what options are
225 for. Again, it doesn't matter if they are entries in a config file, widgets in
226 the "Preferences" dialog of a GUI, or command-line options---the more options
227 you implement, the more flexible your program is, and the more complicated its
228 implementation becomes. Too much flexibility has drawbacks as well, of course;
229 too many options can overwhelm users and make your code much harder to maintain.
232 .. _optparse-tutorial:
237 While :mod:`optparse` is quite flexible and powerful, it's also straightforward
238 to use in most cases. This section covers the code patterns that are common to
239 any :mod:`optparse`\ -based program.
241 First, you need to import the OptionParser class; then, early in the main
242 program, create an OptionParser instance::
244 from optparse import OptionParser
246 parser = OptionParser()
248 Then you can start defining options. The basic syntax is::
250 parser.add_option(opt_str, ...,
253 Each option has one or more option strings, such as ``"-f"`` or ``"--file"``,
254 and several option attributes that tell :mod:`optparse` what to expect and what
255 to do when it encounters that option on the command line.
257 Typically, each option will have one short option string and one long option
260 parser.add_option("-f", "--file", ...)
262 You're free to define as many short option strings and as many long option
263 strings as you like (including zero), as long as there is at least one option
266 The option strings passed to :meth:`add_option` are effectively labels for the
267 option defined by that call. For brevity, we will frequently refer to
268 *encountering an option* on the command line; in reality, :mod:`optparse`
269 encounters *option strings* and looks up options from them.
271 Once all of your options are defined, instruct :mod:`optparse` to parse your
272 program's command line::
274 (options, args) = parser.parse_args()
276 (If you like, you can pass a custom argument list to :meth:`parse_args`, but
277 that's rarely necessary: by default it uses ``sys.argv[1:]``.)
279 :meth:`parse_args` returns two values:
281 * ``options``, an object containing values for all of your options---e.g. if
282 ``"--file"`` takes a single string argument, then ``options.file`` will be the
283 filename supplied by the user, or ``None`` if the user did not supply that
286 * ``args``, the list of positional arguments leftover after parsing options
288 This tutorial section only covers the four most important option attributes:
289 :attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
290 (destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
294 .. _optparse-understanding-option-actions:
296 Understanding option actions
297 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
299 Actions tell :mod:`optparse` what to do when it encounters an option on the
300 command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
301 adding new actions is an advanced topic covered in section
302 :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
303 a value in some variable---for example, take a string from the command line and
304 store it in an attribute of ``options``.
306 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
309 .. _optparse-store-action:
314 The most common option action is ``store``, which tells :mod:`optparse` to take
315 the next argument (or the remainder of the current argument), ensure that it is
316 of the correct type, and store it to your chosen destination.
320 parser.add_option("-f", "--file",
321 action="store", type="string", dest="filename")
323 Now let's make up a fake command line and ask :mod:`optparse` to parse it::
325 args = ["-f", "foo.txt"]
326 (options, args) = parser.parse_args(args)
328 When :mod:`optparse` sees the option string ``"-f"``, it consumes the next
329 argument, ``"foo.txt"``, and stores it in ``options.filename``. So, after this
330 call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
332 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
333 Here's an option that expects an integer argument::
335 parser.add_option("-n", type="int", dest="num")
337 Note that this option has no long option string, which is perfectly acceptable.
338 Also, there's no explicit action, since the default is ``store``.
340 Let's parse another fake command-line. This time, we'll jam the option argument
341 right up against the option: since ``"-n42"`` (one argument) is equivalent to
342 ``"-n 42"`` (two arguments), the code ::
344 (options, args) = parser.parse_args(["-n42"])
349 If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
350 the fact that the default action is ``store``, that means our first example can
353 parser.add_option("-f", "--file", dest="filename")
355 If you don't supply a destination, :mod:`optparse` figures out a sensible
356 default from the option strings: if the first long option string is
357 ``"--foo-bar"``, then the default destination is ``foo_bar``. If there are no
358 long option strings, :mod:`optparse` looks at the first short option string: the
359 default destination for ``"-f"`` is ``f``.
361 :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding
362 types is covered in section :ref:`optparse-extending-optparse`.
365 .. _optparse-handling-boolean-options:
367 Handling boolean (flag) options
368 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
370 Flag options---set a variable to true or false when a particular option is seen
371 ---are quite common. :mod:`optparse` supports them with two separate actions,
372 ``store_true`` and ``store_false``. For example, you might have a ``verbose``
373 flag that is turned on with ``"-v"`` and off with ``"-q"``::
375 parser.add_option("-v", action="store_true", dest="verbose")
376 parser.add_option("-q", action="store_false", dest="verbose")
378 Here we have two different options with the same destination, which is perfectly
379 OK. (It just means you have to be a bit careful when setting default values---
382 When :mod:`optparse` encounters ``"-v"`` on the command line, it sets
383 ``options.verbose`` to ``True``; when it encounters ``"-q"``,
384 ``options.verbose`` is set to ``False``.
387 .. _optparse-other-actions:
392 Some other actions supported by :mod:`optparse` are:
395 store a constant value
398 append this option's argument to a list
401 increment a counter by one
404 call a specified function
406 These are covered in section :ref:`optparse-reference-guide`, Reference Guide
407 and section :ref:`optparse-option-callbacks`.
410 .. _optparse-default-values:
415 All of the above examples involve setting some variable (the "destination") when
416 certain command-line options are seen. What happens if those options are never
417 seen? Since we didn't supply any defaults, they are all set to ``None``. This
418 is usually fine, but sometimes you want more control. :mod:`optparse` lets you
419 supply a default value for each destination, which is assigned before the
420 command line is parsed.
422 First, consider the verbose/quiet example. If we want :mod:`optparse` to set
423 ``verbose`` to ``True`` unless ``"-q"`` is seen, then we can do this::
425 parser.add_option("-v", action="store_true", dest="verbose", default=True)
426 parser.add_option("-q", action="store_false", dest="verbose")
428 Since default values apply to the *destination* rather than to any particular
429 option, and these two options happen to have the same destination, this is
432 parser.add_option("-v", action="store_true", dest="verbose")
433 parser.add_option("-q", action="store_false", dest="verbose", default=True)
437 parser.add_option("-v", action="store_true", dest="verbose", default=False)
438 parser.add_option("-q", action="store_false", dest="verbose", default=True)
440 Again, the default value for ``verbose`` will be ``True``: the last default
441 value supplied for any particular destination is the one that counts.
443 A clearer way to specify default values is the :meth:`set_defaults` method of
444 OptionParser, which you can call at any time before calling :meth:`parse_args`::
446 parser.set_defaults(verbose=True)
447 parser.add_option(...)
448 (options, args) = parser.parse_args()
450 As before, the last value specified for a given option destination is the one
451 that counts. For clarity, try to use one method or the other of setting default
455 .. _optparse-generating-help:
460 :mod:`optparse`'s ability to generate help and usage text automatically is
461 useful for creating user-friendly command-line interfaces. All you have to do
462 is supply a :attr:`~Option.help` value for each option, and optionally a short
463 usage message for your whole program. Here's an OptionParser populated with
464 user-friendly (documented) options::
466 usage = "usage: %prog [options] arg1 arg2"
467 parser = OptionParser(usage=usage)
468 parser.add_option("-v", "--verbose",
469 action="store_true", dest="verbose", default=True,
470 help="make lots of noise [default]")
471 parser.add_option("-q", "--quiet",
472 action="store_false", dest="verbose",
473 help="be vewwy quiet (I'm hunting wabbits)")
474 parser.add_option("-f", "--filename",
475 metavar="FILE", help="write output to FILE")
476 parser.add_option("-m", "--mode",
477 default="intermediate",
478 help="interaction mode: novice, intermediate, "
479 "or expert [default: %default]")
481 If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the
482 command-line, or if you just call :meth:`parser.print_help`, it prints the
483 following to standard output::
485 usage: <yourscript> [options] arg1 arg2
488 -h, --help show this help message and exit
489 -v, --verbose make lots of noise [default]
490 -q, --quiet be vewwy quiet (I'm hunting wabbits)
491 -f FILE, --filename=FILE
493 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
494 expert [default: intermediate]
496 (If the help output is triggered by a help option, :mod:`optparse` exits after
497 printing the help text.)
499 There's a lot going on here to help :mod:`optparse` generate the best possible
502 * the script defines its own usage message::
504 usage = "usage: %prog [options] arg1 arg2"
506 :mod:`optparse` expands ``"%prog"`` in the usage string to the name of the
507 current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
508 is then printed before the detailed option help.
510 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
511 default: ``"usage: %prog [options]"``, which is fine if your script doesn't
512 take any positional arguments.
514 * every option defines a help string, and doesn't worry about line-wrapping---
515 :mod:`optparse` takes care of wrapping lines and making the help output look
518 * options that take a value indicate this fact in their automatically-generated
519 help message, e.g. for the "mode" option::
523 Here, "MODE" is called the meta-variable: it stands for the argument that the
524 user is expected to supply to :option:`-m`/:option:`--mode`. By default,
525 :mod:`optparse` converts the destination variable name to uppercase and uses
526 that for the meta-variable. Sometimes, that's not what you want---for
527 example, the :option:`--filename` option explicitly sets ``metavar="FILE"``,
528 resulting in this automatically-generated option description::
530 -f FILE, --filename=FILE
532 This is important for more than just saving space, though: the manually
533 written help text uses the meta-variable "FILE" to clue the user in that
534 there's a connection between the semi-formal syntax "-f FILE" and the informal
535 semantic description "write output to FILE". This is a simple but effective
536 way to make your help text a lot clearer and more useful for end users.
538 .. versionadded:: 2.4
539 Options that have a default value can include ``%default`` in the help
540 string---\ :mod:`optparse` will replace it with :func:`str` of the option's
541 default value. If an option has no default value (or the default value is
542 ``None``), ``%default`` expands to ``none``.
544 When dealing with many options, it is convenient to group these options for
545 better help output. An :class:`OptionParser` can contain several option groups,
546 each of which can contain several options.
548 Continuing with the parser defined above, adding an :class:`OptionGroup` to a
551 group = OptionGroup(parser, "Dangerous Options",
552 "Caution: use these options at your own risk. "
553 "It is believed that some of them bite.")
554 group.add_option("-g", action="store_true", help="Group option.")
555 parser.add_option_group(group)
557 This would result in the following help output::
559 usage: [options] arg1 arg2
562 -h, --help show this help message and exit
563 -v, --verbose make lots of noise [default]
564 -q, --quiet be vewwy quiet (I'm hunting wabbits)
565 -fFILE, --file=FILE write output to FILE
566 -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
570 Caution: use of these options is at your own risk. It is believed that
574 .. _optparse-printing-version-string:
576 Printing a version string
577 ^^^^^^^^^^^^^^^^^^^^^^^^^
579 Similar to the brief usage string, :mod:`optparse` can also print a version
580 string for your program. You have to supply the string as the ``version``
581 argument to OptionParser::
583 parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
585 ``"%prog"`` is expanded just like it is in ``usage``. Apart from that,
586 ``version`` can contain anything you like. When you supply it, :mod:`optparse`
587 automatically adds a ``"--version"`` option to your parser. If it encounters
588 this option on the command line, it expands your ``version`` string (by
589 replacing ``"%prog"``), prints it to stdout, and exits.
591 For example, if your script is called ``/usr/bin/foo``::
593 $ /usr/bin/foo --version
597 .. _optparse-how-optparse-handles-errors:
599 How :mod:`optparse` handles errors
600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
602 There are two broad classes of errors that :mod:`optparse` has to worry about:
603 programmer errors and user errors. Programmer errors are usually erroneous
604 calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
605 option attributes, missing option attributes, etc. These are dealt with in the
606 usual way: raise an exception (either :exc:`optparse.OptionError` or
607 :exc:`TypeError`) and let the program crash.
609 Handling user errors is much more important, since they are guaranteed to happen
610 no matter how stable your code is. :mod:`optparse` can automatically detect
611 some user errors, such as bad option arguments (passing ``"-n 4x"`` where
612 :option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
613 of the command line, where :option:`-n` takes an argument of any type). Also,
614 you can call :func:`OptionParser.error` to signal an application-defined error
617 (options, args) = parser.parse_args()
619 if options.a and options.b:
620 parser.error("options -a and -b are mutually exclusive")
622 In either case, :mod:`optparse` handles the error the same way: it prints the
623 program's usage message and an error message to standard error and exits with
626 Consider the first example above, where the user passes ``"4x"`` to an option
627 that takes an integer::
632 foo: error: option -n: invalid integer value: '4x'
634 Or, where the user fails to pass a value at all::
639 foo: error: -n option requires an argument
641 :mod:`optparse`\ -generated error messages take care always to mention the
642 option involved in the error; be sure to do the same when calling
643 :func:`OptionParser.error` from your application code.
645 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
646 you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
647 and/or :meth:`~OptionParser.error` methods.
650 .. _optparse-putting-it-all-together:
652 Putting it all together
653 ^^^^^^^^^^^^^^^^^^^^^^^
655 Here's what :mod:`optparse`\ -based scripts usually look like::
657 from optparse import OptionParser
660 usage = "usage: %prog [options] arg"
661 parser = OptionParser(usage)
662 parser.add_option("-f", "--file", dest="filename",
663 help="read data from FILENAME")
664 parser.add_option("-v", "--verbose",
665 action="store_true", dest="verbose")
666 parser.add_option("-q", "--quiet",
667 action="store_false", dest="verbose")
669 (options, args) = parser.parse_args()
671 parser.error("incorrect number of arguments")
673 print "reading %s..." % options.filename
676 if __name__ == "__main__":
680 .. _optparse-reference-guide:
686 .. _optparse-creating-parser:
691 The first step in using :mod:`optparse` is to create an OptionParser instance.
693 .. class:: OptionParser(...)
695 The OptionParser constructor has no required arguments, but a number of
696 optional keyword arguments. You should always pass them as keyword
697 arguments, i.e. do not rely on the order in which the arguments are declared.
699 ``usage`` (default: ``"%prog [options]"``)
700 The usage summary to print when your program is run incorrectly or with a
701 help option. When :mod:`optparse` prints the usage string, it expands
702 ``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
703 passed that keyword argument). To suppress a usage message, pass the
704 special value :data:`optparse.SUPPRESS_USAGE`.
706 ``option_list`` (default: ``[]``)
707 A list of Option objects to populate the parser with. The options in
708 ``option_list`` are added after any options in ``standard_option_list`` (a
709 class attribute that may be set by OptionParser subclasses), but before
710 any version or help options. Deprecated; use :meth:`add_option` after
711 creating the parser instead.
713 ``option_class`` (default: optparse.Option)
714 Class to use when adding options to the parser in :meth:`add_option`.
716 ``version`` (default: ``None``)
717 A version string to print when the user supplies a version option. If you
718 supply a true value for ``version``, :mod:`optparse` automatically adds a
719 version option with the single option string ``"--version"``. The
720 substring ``"%prog"`` is expanded the same as for ``usage``.
722 ``conflict_handler`` (default: ``"error"``)
723 Specifies what to do when options with conflicting option strings are
724 added to the parser; see section
725 :ref:`optparse-conflicts-between-options`.
727 ``description`` (default: ``None``)
728 A paragraph of text giving a brief overview of your program.
729 :mod:`optparse` reformats this paragraph to fit the current terminal width
730 and prints it when the user requests help (after ``usage``, but before the
733 ``formatter`` (default: a new :class:`IndentedHelpFormatter`)
734 An instance of optparse.HelpFormatter that will be used for printing help
735 text. :mod:`optparse` provides two concrete classes for this purpose:
736 IndentedHelpFormatter and TitledHelpFormatter.
738 ``add_help_option`` (default: ``True``)
739 If true, :mod:`optparse` will add a help option (with option strings ``"-h"``
740 and ``"--help"``) to the parser.
743 The string to use when expanding ``"%prog"`` in ``usage`` and ``version``
744 instead of ``os.path.basename(sys.argv[0])``.
748 .. _optparse-populating-parser:
750 Populating the parser
751 ^^^^^^^^^^^^^^^^^^^^^
753 There are several ways to populate the parser with options. The preferred way
754 is by using :meth:`OptionParser.add_option`, as shown in section
755 :ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
757 * pass it an Option instance (as returned by :func:`make_option`)
759 * pass it any combination of positional and keyword arguments that are
760 acceptable to :func:`make_option` (i.e., to the Option constructor), and it
761 will create the Option instance for you
763 The other alternative is to pass a list of pre-constructed Option instances to
764 the OptionParser constructor, as in::
767 make_option("-f", "--filename",
768 action="store", type="string", dest="filename"),
769 make_option("-q", "--quiet",
770 action="store_false", dest="verbose"),
772 parser = OptionParser(option_list=option_list)
774 (:func:`make_option` is a factory function for creating Option instances;
775 currently it is an alias for the Option constructor. A future version of
776 :mod:`optparse` may split Option into several classes, and :func:`make_option`
777 will pick the right class to instantiate. Do not instantiate Option directly.)
780 .. _optparse-defining-options:
785 Each Option instance represents a set of synonymous command-line option strings,
786 e.g. :option:`-f` and :option:`--file`. You can specify any number of short or
787 long option strings, but you must specify at least one overall option string.
789 The canonical way to create an :class:`Option` instance is with the
790 :meth:`add_option` method of :class:`OptionParser`.
792 .. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...)
794 To define an option with only a short option string::
796 parser.add_option("-f", attr=value, ...)
798 And to define an option with only a long option string::
800 parser.add_option("--foo", attr=value, ...)
802 The keyword arguments define attributes of the new Option object. The most
803 important option attribute is :attr:`~Option.action`, and it largely
804 determines which other attributes are relevant or required. If you pass
805 irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
806 raises an :exc:`OptionError` exception explaining your mistake.
808 An option's *action* determines what :mod:`optparse` does when it encounters
809 this option on the command-line. The standard option actions hard-coded into
813 store this option's argument (default)
816 store a constant value
825 append this option's argument to a list
828 append a constant value to a list
831 increment a counter by one
834 call a specified function
837 print a usage message including all options and the documentation for them
839 (If you don't supply an action, the default is ``"store"``. For this action,
840 you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
841 attributes; see :ref:`optparse-standard-option-actions`.)
843 As you can see, most actions involve storing or updating a value somewhere.
844 :mod:`optparse` always creates a special object for this, conventionally called
845 ``options`` (it happens to be an instance of :class:`optparse.Values`). Option
846 arguments (and various other values) are stored as attributes of this object,
847 according to the :attr:`~Option.dest` (destination) option attribute.
849 For example, when you call ::
853 one of the first things :mod:`optparse` does is create the ``options`` object::
857 If one of the options in this parser is defined with ::
859 parser.add_option("-f", "--file", action="store", type="string", dest="filename")
861 and the command-line being parsed includes any of the following::
868 then :mod:`optparse`, on seeing this option, will do the equivalent of ::
870 options.filename = "foo"
872 The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
873 as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
874 one that makes sense for *all* options.
877 .. _optparse-option-attributes:
882 The following option attributes may be passed as keyword arguments to
883 :meth:`OptionParser.add_option`. If you pass an option attribute that is not
884 relevant to a particular option, or fail to pass a required option attribute,
885 :mod:`optparse` raises :exc:`OptionError`.
887 .. attribute:: Option.action
889 (default: ``"store"``)
891 Determines :mod:`optparse`'s behaviour when this option is seen on the
892 command line; the available options are documented :ref:`here
893 <optparse-standard-option-actions>`.
895 .. attribute:: Option.type
897 (default: ``"string"``)
899 The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
900 the available option types are documented :ref:`here
901 <optparse-standard-option-types>`.
903 .. attribute:: Option.dest
905 (default: derived from option strings)
907 If the option's action implies writing or modifying a value somewhere, this
908 tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
909 attribute of the ``options`` object that :mod:`optparse` builds as it parses
912 .. attribute:: Option.default
914 The value to use for this option's destination if the option is not seen on
915 the command line. See also :meth:`OptionParser.set_defaults`.
917 .. attribute:: Option.nargs
921 How many arguments of type :attr:`~Option.type` should be consumed when this
922 option is seen. If > 1, :mod:`optparse` will store a tuple of values to
923 :attr:`~Option.dest`.
925 .. attribute:: Option.const
927 For actions that store a constant value, the constant value to store.
929 .. attribute:: Option.choices
931 For options of type ``"choice"``, the list of strings the user may choose
934 .. attribute:: Option.callback
936 For options with action ``"callback"``, the callable to call when this option
937 is seen. See section :ref:`optparse-option-callbacks` for detail on the
938 arguments passed to the callable.
940 .. attribute:: Option.callback_args
941 Option.callback_kwargs
943 Additional positional and keyword arguments to pass to ``callback`` after the
944 four standard callback arguments.
946 .. attribute:: Option.help
948 Help text to print for this option when listing all available options after
949 the user supplies a :attr:`~Option.help` option (such as ``"--help"``). If
950 no help text is supplied, the option will be listed without help text. To
951 hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
953 .. attribute:: Option.metavar
955 (default: derived from option strings)
957 Stand-in for the option argument(s) to use when printing help text. See
958 section :ref:`optparse-tutorial` for an example.
961 .. _optparse-standard-option-actions:
963 Standard option actions
964 ^^^^^^^^^^^^^^^^^^^^^^^
966 The various option actions all have slightly different requirements and effects.
967 Most actions have several relevant option attributes which you may specify to
968 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
969 must specify for any option using that action.
971 * ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
972 :attr:`~Option.nargs`, :attr:`~Option.choices`]
974 The option must be followed by an argument, which is converted to a value
975 according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
976 :attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
977 command line; all will be converted according to :attr:`~Option.type` and
978 stored to :attr:`~Option.dest` as a tuple. See the
979 :ref:`optparse-standard-option-types` section.
981 If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
982 defaults to ``"choice"``.
984 If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
986 If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
987 from the first long option string (e.g., ``"--foo-bar"`` implies
988 ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
989 destination from the first short option string (e.g., ``"-f"`` implies ``f``).
993 parser.add_option("-f")
994 parser.add_option("-p", type="float", nargs=3, dest="point")
996 As it parses the command line ::
998 -f foo.txt -p 1 -3.5 4 -fbar.txt
1000 :mod:`optparse` will set ::
1002 options.f = "foo.txt"
1003 options.point = (1.0, -3.5, 4.0)
1004 options.f = "bar.txt"
1006 * ``"store_const"`` [required: :attr:`~Option.const`; relevant:
1007 :attr:`~Option.dest`]
1009 The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
1013 parser.add_option("-q", "--quiet",
1014 action="store_const", const=0, dest="verbose")
1015 parser.add_option("-v", "--verbose",
1016 action="store_const", const=1, dest="verbose")
1017 parser.add_option("--noisy",
1018 action="store_const", const=2, dest="verbose")
1020 If ``"--noisy"`` is seen, :mod:`optparse` will set ::
1024 * ``"store_true"`` [relevant: :attr:`~Option.dest`]
1026 A special case of ``"store_const"`` that stores a true value to
1027 :attr:`~Option.dest`.
1029 * ``"store_false"`` [relevant: :attr:`~Option.dest`]
1031 Like ``"store_true"``, but stores a false value.
1035 parser.add_option("--clobber", action="store_true", dest="clobber")
1036 parser.add_option("--no-clobber", action="store_false", dest="clobber")
1038 * ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
1039 :attr:`~Option.nargs`, :attr:`~Option.choices`]
1041 The option must be followed by an argument, which is appended to the list in
1042 :attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
1043 supplied, an empty list is automatically created when :mod:`optparse` first
1044 encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
1045 multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
1046 is appended to :attr:`~Option.dest`.
1048 The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
1049 for the ``"store"`` action.
1053 parser.add_option("-t", "--tracks", action="append", type="int")
1055 If ``"-t3"`` is seen on the command-line, :mod:`optparse` does the equivalent
1059 options.tracks.append(int("3"))
1061 If, a little later on, ``"--tracks=4"`` is seen, it does::
1063 options.tracks.append(int("4"))
1065 * ``"append_const"`` [required: :attr:`~Option.const`; relevant:
1066 :attr:`~Option.dest`]
1068 Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
1069 :attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
1070 ``None``, and an empty list is automatically created the first time the option
1073 * ``"count"`` [relevant: :attr:`~Option.dest`]
1075 Increment the integer stored at :attr:`~Option.dest`. If no default value is
1076 supplied, :attr:`~Option.dest` is set to zero before being incremented the
1081 parser.add_option("-v", action="count", dest="verbosity")
1083 The first time ``"-v"`` is seen on the command line, :mod:`optparse` does the
1086 options.verbosity = 0
1087 options.verbosity += 1
1089 Every subsequent occurrence of ``"-v"`` results in ::
1091 options.verbosity += 1
1093 * ``"callback"`` [required: :attr:`~Option.callback`; relevant:
1094 :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
1095 :attr:`~Option.callback_kwargs`]
1097 Call the function specified by :attr:`~Option.callback`, which is called as ::
1099 func(option, opt_str, value, parser, *args, **kwargs)
1101 See section :ref:`optparse-option-callbacks` for more detail.
1105 Prints a complete help message for all the options in the current option
1106 parser. The help message is constructed from the ``usage`` string passed to
1107 OptionParser's constructor and the :attr:`~Option.help` string passed to every
1110 If no :attr:`~Option.help` string is supplied for an option, it will still be
1111 listed in the help message. To omit an option entirely, use the special value
1112 :data:`optparse.SUPPRESS_HELP`.
1114 :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
1115 OptionParsers, so you do not normally need to create one.
1119 from optparse import OptionParser, SUPPRESS_HELP
1121 # usually, a help option is added automatically, but that can
1122 # be suppressed using the add_help_option argument
1123 parser = OptionParser(add_help_option=False)
1125 parser.add_option("-h", "--help", action="help")
1126 parser.add_option("-v", action="store_true", dest="verbose",
1127 help="Be moderately verbose")
1128 parser.add_option("--file", dest="filename",
1129 help="Input file to read data from")
1130 parser.add_option("--secret", help=SUPPRESS_HELP)
1132 If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line,
1133 it will print something like the following help message to stdout (assuming
1134 ``sys.argv[0]`` is ``"foo.py"``)::
1136 usage: foo.py [options]
1139 -h, --help Show this help message and exit
1140 -v Be moderately verbose
1141 --file=FILENAME Input file to read data from
1143 After printing the help message, :mod:`optparse` terminates your process with
1148 Prints the version number supplied to the OptionParser to stdout and exits.
1149 The version number is actually formatted and printed by the
1150 ``print_version()`` method of OptionParser. Generally only relevant if the
1151 ``version`` argument is supplied to the OptionParser constructor. As with
1152 :attr:`~Option.help` options, you will rarely create ``version`` options,
1153 since :mod:`optparse` automatically adds them when needed.
1156 .. _optparse-standard-option-types:
1158 Standard option types
1159 ^^^^^^^^^^^^^^^^^^^^^
1161 :mod:`optparse` has six built-in option types: ``"string"``, ``"int"``,
1162 ``"long"``, ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
1163 option types, see section :ref:`optparse-extending-optparse`.
1165 Arguments to string options are not checked or converted in any way: the text on
1166 the command line is stored in the destination (or passed to the callback) as-is.
1168 Integer arguments (type ``"int"`` or ``"long"``) are parsed as follows:
1170 * if the number starts with ``0x``, it is parsed as a hexadecimal number
1172 * if the number starts with ``0``, it is parsed as an octal number
1174 * if the number starts with ``0b``, it is parsed as a binary number
1176 * otherwise, the number is parsed as a decimal number
1179 The conversion is done by calling either :func:`int` or :func:`long` with the
1180 appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`,
1181 although with a more useful error message.
1183 ``"float"`` and ``"complex"`` option arguments are converted directly with
1184 :func:`float` and :func:`complex`, with similar error-handling.
1186 ``"choice"`` options are a subtype of ``"string"`` options. The
1187 :attr:`~Option.choices`` option attribute (a sequence of strings) defines the
1188 set of allowed option arguments. :func:`optparse.check_choice` compares
1189 user-supplied option arguments against this master list and raises
1190 :exc:`OptionValueError` if an invalid string is given.
1193 .. _optparse-parsing-arguments:
1198 The whole point of creating and populating an OptionParser is to call its
1199 :meth:`parse_args` method::
1201 (options, args) = parser.parse_args(args=None, values=None)
1203 where the input parameters are
1206 the list of arguments to process (default: ``sys.argv[1:]``)
1209 object to store option arguments in (default: a new instance of
1210 :class:`optparse.Values`)
1212 and the return values are
1215 the same object that was passed in as ``values``, or the optparse.Values
1216 instance created by :mod:`optparse`
1219 the leftover positional arguments after all options have been processed
1221 The most common usage is to supply neither keyword argument. If you supply
1222 ``values``, it will be modified with repeated :func:`setattr` calls (roughly one
1223 for every option argument stored to an option destination) and returned by
1226 If :meth:`parse_args` encounters any errors in the argument list, it calls the
1227 OptionParser's :meth:`error` method with an appropriate end-user error message.
1228 This ultimately terminates your process with an exit status of 2 (the
1229 traditional Unix exit status for command-line errors).
1232 .. _optparse-querying-manipulating-option-parser:
1234 Querying and manipulating your option parser
1235 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1237 The default behavior of the option parser can be customized slightly, and you
1238 can also poke around your option parser and see what's there. OptionParser
1239 provides several methods to help you out:
1241 .. method:: OptionParser.disable_interspersed_args()
1243 Set parsing to stop on the first non-option. For example, if ``"-a"`` and
1244 ``"-b"`` are both simple options that take no arguments, :mod:`optparse`
1245 normally accepts this syntax::
1247 prog -a arg1 -b arg2
1249 and treats it as equivalent to ::
1251 prog -a -b arg1 arg2
1253 To disable this feature, call :meth:`disable_interspersed_args`. This
1254 restores traditional Unix syntax, where option parsing stops with the first
1255 non-option argument.
1257 Use this if you have a command processor which runs another command which has
1258 options of its own and you want to make sure these options don't get
1259 confused. For example, each command might have a different set of options.
1261 .. method:: OptionParser.enable_interspersed_args()
1263 Set parsing to not stop on the first non-option, allowing interspersing
1264 switches with command arguments. This is the default behavior.
1266 .. method:: OptionParser.get_option(opt_str)
1268 Returns the Option instance with the option string *opt_str*, or ``None`` if
1269 no options have that option string.
1271 .. method:: OptionParser.has_option(opt_str)
1273 Return true if the OptionParser has an option with option string *opt_str*
1274 (e.g., ``"-q"`` or ``"--verbose"``).
1276 .. method:: OptionParser.remove_option(opt_str)
1278 If the :class:`OptionParser` has an option corresponding to *opt_str*, that
1279 option is removed. If that option provided any other option strings, all of
1280 those option strings become invalid. If *opt_str* does not occur in any
1281 option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
1284 .. _optparse-conflicts-between-options:
1286 Conflicts between options
1287 ^^^^^^^^^^^^^^^^^^^^^^^^^
1289 If you're not careful, it's easy to define options with conflicting option
1292 parser.add_option("-n", "--dry-run", ...)
1294 parser.add_option("-n", "--noisy", ...)
1296 (This is particularly true if you've defined your own OptionParser subclass with
1297 some standard options.)
1299 Every time you add an option, :mod:`optparse` checks for conflicts with existing
1300 options. If it finds any, it invokes the current conflict-handling mechanism.
1301 You can set the conflict-handling mechanism either in the constructor::
1303 parser = OptionParser(..., conflict_handler=handler)
1305 or with a separate call::
1307 parser.set_conflict_handler(handler)
1309 The available conflict handlers are:
1311 ``"error"`` (default)
1312 assume option conflicts are a programming error and raise
1313 :exc:`OptionConflictError`
1316 resolve option conflicts intelligently (see below)
1319 As an example, let's define an :class:`OptionParser` that resolves conflicts
1320 intelligently and add conflicting options to it::
1322 parser = OptionParser(conflict_handler="resolve")
1323 parser.add_option("-n", "--dry-run", ..., help="do no harm")
1324 parser.add_option("-n", "--noisy", ..., help="be noisy")
1326 At this point, :mod:`optparse` detects that a previously-added option is already
1327 using the ``"-n"`` option string. Since ``conflict_handler`` is ``"resolve"``,
1328 it resolves the situation by removing ``"-n"`` from the earlier option's list of
1329 option strings. Now ``"--dry-run"`` is the only way for the user to activate
1330 that option. If the user asks for help, the help message will reflect that::
1333 --dry-run do no harm
1335 -n, --noisy be noisy
1337 It's possible to whittle away the option strings for a previously-added option
1338 until there are none left, and the user has no way of invoking that option from
1339 the command-line. In that case, :mod:`optparse` removes that option completely,
1340 so it doesn't show up in help text or anywhere else. Carrying on with our
1341 existing OptionParser::
1343 parser.add_option("--dry-run", ..., help="new dry-run option")
1345 At this point, the original :option:`-n/--dry-run` option is no longer
1346 accessible, so :mod:`optparse` removes it, leaving this help text::
1350 -n, --noisy be noisy
1351 --dry-run new dry-run option
1354 .. _optparse-cleanup:
1359 OptionParser instances have several cyclic references. This should not be a
1360 problem for Python's garbage collector, but you may wish to break the cyclic
1361 references explicitly by calling :meth:`~OptionParser.destroy` on your
1362 OptionParser once you are done with it. This is particularly useful in
1363 long-running applications where large object graphs are reachable from your
1367 .. _optparse-other-methods:
1372 OptionParser supports several other public methods:
1374 .. method:: OptionParser.set_usage(usage)
1376 Set the usage string according to the rules described above for the ``usage``
1377 constructor keyword argument. Passing ``None`` sets the default usage
1378 string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
1380 .. method:: OptionParser.set_defaults(dest=value, ...)
1382 Set default values for several option destinations at once. Using
1383 :meth:`set_defaults` is the preferred way to set default values for options,
1384 since multiple options can share the same destination. For example, if
1385 several "mode" options all set the same destination, any one of them can set
1386 the default, and the last one wins::
1388 parser.add_option("--advanced", action="store_const",
1389 dest="mode", const="advanced",
1390 default="novice") # overridden below
1391 parser.add_option("--novice", action="store_const",
1392 dest="mode", const="novice",
1393 default="advanced") # overrides above setting
1395 To avoid this confusion, use :meth:`set_defaults`::
1397 parser.set_defaults(mode="advanced")
1398 parser.add_option("--advanced", action="store_const",
1399 dest="mode", const="advanced")
1400 parser.add_option("--novice", action="store_const",
1401 dest="mode", const="novice")
1404 .. _optparse-option-callbacks:
1409 When :mod:`optparse`'s built-in actions and types aren't quite enough for your
1410 needs, you have two choices: extend :mod:`optparse` or define a callback option.
1411 Extending :mod:`optparse` is more general, but overkill for a lot of simple
1412 cases. Quite often a simple callback is all you need.
1414 There are two steps to defining a callback option:
1416 * define the option itself using the ``"callback"`` action
1418 * write the callback; this is a function (or method) that takes at least four
1419 arguments, as described below
1422 .. _optparse-defining-callback-option:
1424 Defining a callback option
1425 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1427 As always, the easiest way to define a callback option is by using the
1428 :meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
1429 only option attribute you must specify is ``callback``, the function to call::
1431 parser.add_option("-c", action="callback", callback=my_callback)
1433 ``callback`` is a function (or other callable object), so you must have already
1434 defined ``my_callback()`` when you create this callback option. In this simple
1435 case, :mod:`optparse` doesn't even know if :option:`-c` takes any arguments,
1436 which usually means that the option takes no arguments---the mere presence of
1437 :option:`-c` on the command-line is all it needs to know. In some
1438 circumstances, though, you might want your callback to consume an arbitrary
1439 number of command-line arguments. This is where writing callbacks gets tricky;
1440 it's covered later in this section.
1442 :mod:`optparse` always passes four particular arguments to your callback, and it
1443 will only pass additional arguments if you specify them via
1444 :attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
1445 minimal callback function signature is::
1447 def my_callback(option, opt, value, parser):
1449 The four arguments to a callback are described below.
1451 There are several other option attributes that you can supply when you define a
1454 :attr:`~Option.type`
1455 has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
1456 instructs :mod:`optparse` to consume one argument and convert it to
1457 :attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
1458 though, :mod:`optparse` passes it to your callback function.
1460 :attr:`~Option.nargs`
1461 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
1462 consume :attr:`~Option.nargs` arguments, each of which must be convertible to
1463 :attr:`~Option.type`. It then passes a tuple of converted values to your
1466 :attr:`~Option.callback_args`
1467 a tuple of extra positional arguments to pass to the callback
1469 :attr:`~Option.callback_kwargs`
1470 a dictionary of extra keyword arguments to pass to the callback
1473 .. _optparse-how-callbacks-called:
1475 How callbacks are called
1476 ^^^^^^^^^^^^^^^^^^^^^^^^
1478 All callbacks are called as follows::
1480 func(option, opt_str, value, parser, *args, **kwargs)
1485 is the Option instance that's calling the callback
1488 is the option string seen on the command-line that's triggering the callback.
1489 (If an abbreviated long option was used, ``opt_str`` will be the full,
1490 canonical option string---e.g. if the user puts ``"--foo"`` on the
1491 command-line as an abbreviation for ``"--foobar"``, then ``opt_str`` will be
1495 is the argument to this option seen on the command-line. :mod:`optparse` will
1496 only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
1497 the type implied by the option's type. If :attr:`~Option.type` for this option is
1498 ``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
1499 > 1, ``value`` will be a tuple of values of the appropriate type.
1502 is the OptionParser instance driving the whole thing, mainly useful because
1503 you can access some other interesting data through its instance attributes:
1506 the current list of leftover arguments, ie. arguments that have been
1507 consumed but are neither options nor option arguments. Feel free to modify
1508 ``parser.largs``, e.g. by adding more arguments to it. (This list will
1509 become ``args``, the second return value of :meth:`parse_args`.)
1512 the current list of remaining arguments, ie. with ``opt_str`` and
1513 ``value`` (if applicable) removed, and only the arguments following them
1514 still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
1518 the object where option values are by default stored (an instance of
1519 optparse.OptionValues). This lets callbacks use the same mechanism as the
1520 rest of :mod:`optparse` for storing option values; you don't need to mess
1521 around with globals or closures. You can also access or modify the
1522 value(s) of any options already encountered on the command-line.
1525 is a tuple of arbitrary positional arguments supplied via the
1526 :attr:`~Option.callback_args` option attribute.
1529 is a dictionary of arbitrary keyword arguments supplied via
1530 :attr:`~Option.callback_kwargs`.
1533 .. _optparse-raising-errors-in-callback:
1535 Raising errors in a callback
1536 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1538 The callback function should raise :exc:`OptionValueError` if there are any
1539 problems with the option or its argument(s). :mod:`optparse` catches this and
1540 terminates the program, printing the error message you supply to stderr. Your
1541 message should be clear, concise, accurate, and mention the option at fault.
1542 Otherwise, the user will have a hard time figuring out what he did wrong.
1545 .. _optparse-callback-example-1:
1547 Callback example 1: trivial callback
1548 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1550 Here's an example of a callback option that takes no arguments, and simply
1551 records that the option was seen::
1553 def record_foo_seen(option, opt_str, value, parser):
1554 parser.values.saw_foo = True
1556 parser.add_option("--foo", action="callback", callback=record_foo_seen)
1558 Of course, you could do that with the ``"store_true"`` action.
1561 .. _optparse-callback-example-2:
1563 Callback example 2: check option order
1564 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1566 Here's a slightly more interesting example: record the fact that ``"-a"`` is
1567 seen, but blow up if it comes after ``"-b"`` in the command-line. ::
1569 def check_order(option, opt_str, value, parser):
1571 raise OptionValueError("can't use -a after -b")
1574 parser.add_option("-a", action="callback", callback=check_order)
1575 parser.add_option("-b", action="store_true", dest="b")
1578 .. _optparse-callback-example-3:
1580 Callback example 3: check option order (generalized)
1581 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1583 If you want to re-use this callback for several similar options (set a flag, but
1584 blow up if ``"-b"`` has already been seen), it needs a bit of work: the error
1585 message and the flag that it sets must be generalized. ::
1587 def check_order(option, opt_str, value, parser):
1589 raise OptionValueError("can't use %s after -b" % opt_str)
1590 setattr(parser.values, option.dest, 1)
1592 parser.add_option("-a", action="callback", callback=check_order, dest='a')
1593 parser.add_option("-b", action="store_true", dest="b")
1594 parser.add_option("-c", action="callback", callback=check_order, dest='c')
1597 .. _optparse-callback-example-4:
1599 Callback example 4: check arbitrary condition
1600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1602 Of course, you could put any condition in there---you're not limited to checking
1603 the values of already-defined options. For example, if you have options that
1604 should not be called when the moon is full, all you have to do is this::
1606 def check_moon(option, opt_str, value, parser):
1608 raise OptionValueError("%s option invalid when moon is full"
1610 setattr(parser.values, option.dest, 1)
1612 parser.add_option("--foo",
1613 action="callback", callback=check_moon, dest="foo")
1615 (The definition of ``is_moon_full()`` is left as an exercise for the reader.)
1618 .. _optparse-callback-example-5:
1620 Callback example 5: fixed arguments
1621 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1623 Things get slightly more interesting when you define callback options that take
1624 a fixed number of arguments. Specifying that a callback option takes arguments
1625 is similar to defining a ``"store"`` or ``"append"`` option: if you define
1626 :attr:`~Option.type`, then the option takes one argument that must be
1627 convertible to that type; if you further define :attr:`~Option.nargs`, then the
1628 option takes :attr:`~Option.nargs` arguments.
1630 Here's an example that just emulates the standard ``"store"`` action::
1632 def store_value(option, opt_str, value, parser):
1633 setattr(parser.values, option.dest, value)
1635 parser.add_option("--foo",
1636 action="callback", callback=store_value,
1637 type="int", nargs=3, dest="foo")
1639 Note that :mod:`optparse` takes care of consuming 3 arguments and converting
1640 them to integers for you; all you have to do is store them. (Or whatever;
1641 obviously you don't need a callback for this example.)
1644 .. _optparse-callback-example-6:
1646 Callback example 6: variable arguments
1647 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1649 Things get hairy when you want an option to take a variable number of arguments.
1650 For this case, you must write a callback, as :mod:`optparse` doesn't provide any
1651 built-in capabilities for it. And you have to deal with certain intricacies of
1652 conventional Unix command-line parsing that :mod:`optparse` normally handles for
1653 you. In particular, callbacks should implement the conventional rules for bare
1654 ``"--"`` and ``"-"`` arguments:
1656 * either ``"--"`` or ``"-"`` can be option arguments
1658 * bare ``"--"`` (if not the argument to some option): halt command-line
1659 processing and discard the ``"--"``
1661 * bare ``"-"`` (if not the argument to some option): halt command-line
1662 processing but keep the ``"-"`` (append it to ``parser.largs``)
1664 If you want an option that takes a variable number of arguments, there are
1665 several subtle, tricky issues to worry about. The exact implementation you
1666 choose will be based on which trade-offs you're willing to make for your
1667 application (which is why :mod:`optparse` doesn't support this sort of thing
1670 Nevertheless, here's a stab at a callback for an option with variable
1673 def vararg_callback(option, opt_str, value, parser):
1674 assert value is None
1684 for arg in parser.rargs:
1685 # stop on --foo like options
1686 if arg[:2] == "--" and len(arg) > 2:
1688 # stop on -a, but not on -3 or -3.0
1689 if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
1693 del parser.rargs[:len(value)]
1694 setattr(parser.values, option.dest, value)
1697 parser.add_option("-c", "--callback", dest="vararg_attr",
1698 action="callback", callback=vararg_callback)
1701 .. _optparse-extending-optparse:
1703 Extending :mod:`optparse`
1704 -------------------------
1706 Since the two major controlling factors in how :mod:`optparse` interprets
1707 command-line options are the action and type of each option, the most likely
1708 direction of extension is to add new actions and new types.
1711 .. _optparse-adding-new-types:
1716 To add new types, you need to define your own subclass of :mod:`optparse`'s
1717 :class:`Option` class. This class has a couple of attributes that define
1718 :mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
1720 .. attribute:: Option.TYPES
1722 A tuple of type names; in your subclass, simply define a new tuple
1723 :attr:`TYPES` that builds on the standard one.
1725 .. attribute:: Option.TYPE_CHECKER
1727 A dictionary mapping type names to type-checking functions. A type-checking
1728 function has the following signature::
1730 def check_mytype(option, opt, value)
1732 where ``option`` is an :class:`Option` instance, ``opt`` is an option string
1733 (e.g., ``"-f"``), and ``value`` is the string from the command line that must
1734 be checked and converted to your desired type. ``check_mytype()`` should
1735 return an object of the hypothetical type ``mytype``. The value returned by
1736 a type-checking function will wind up in the OptionValues instance returned
1737 by :meth:`OptionParser.parse_args`, or be passed to a callback as the
1738 ``value`` parameter.
1740 Your type-checking function should raise :exc:`OptionValueError` if it
1741 encounters any problems. :exc:`OptionValueError` takes a single string
1742 argument, which is passed as-is to :class:`OptionParser`'s :meth:`error`
1743 method, which in turn prepends the program name and the string ``"error:"``
1744 and prints everything to stderr before terminating the process.
1746 Here's a silly example that demonstrates adding a ``"complex"`` option type to
1747 parse Python-style complex numbers on the command line. (This is even sillier
1748 than it used to be, because :mod:`optparse` 1.3 added built-in support for
1749 complex numbers, but never mind.)
1751 First, the necessary imports::
1753 from copy import copy
1754 from optparse import Option, OptionValueError
1756 You need to define your type-checker first, since it's referred to later (in the
1757 :attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
1759 def check_complex(option, opt, value):
1761 return complex(value)
1763 raise OptionValueError(
1764 "option %s: invalid complex value: %r" % (opt, value))
1766 Finally, the Option subclass::
1768 class MyOption (Option):
1769 TYPES = Option.TYPES + ("complex",)
1770 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
1771 TYPE_CHECKER["complex"] = check_complex
1773 (If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
1774 up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
1775 Option class. This being Python, nothing stops you from doing that except good
1776 manners and common sense.)
1778 That's it! Now you can write a script that uses the new option type just like
1779 any other :mod:`optparse`\ -based script, except you have to instruct your
1780 OptionParser to use MyOption instead of Option::
1782 parser = OptionParser(option_class=MyOption)
1783 parser.add_option("-c", type="complex")
1785 Alternately, you can build your own option list and pass it to OptionParser; if
1786 you don't use :meth:`add_option` in the above way, you don't need to tell
1787 OptionParser which option class to use::
1789 option_list = [MyOption("-c", action="store", type="complex", dest="c")]
1790 parser = OptionParser(option_list=option_list)
1793 .. _optparse-adding-new-actions:
1798 Adding new actions is a bit trickier, because you have to understand that
1799 :mod:`optparse` has a couple of classifications for actions:
1802 actions that result in :mod:`optparse` storing a value to an attribute of the
1803 current OptionValues instance; these options require a :attr:`~Option.dest`
1804 attribute to be supplied to the Option constructor.
1807 actions that take a value from the command line and expect it to be of a
1808 certain type; or rather, a string that can be converted to a certain type.
1809 These options require a :attr:`~Option.type` attribute to the Option
1812 These are overlapping sets: some default "store" actions are ``"store"``,
1813 ``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
1814 actions are ``"store"``, ``"append"``, and ``"callback"``.
1816 When you add an action, you need to categorize it by listing it in at least one
1817 of the following class attributes of Option (all are lists of strings):
1819 .. attribute:: Option.ACTIONS
1821 All actions must be listed in ACTIONS.
1823 .. attribute:: Option.STORE_ACTIONS
1825 "store" actions are additionally listed here.
1827 .. attribute:: Option.TYPED_ACTIONS
1829 "typed" actions are additionally listed here.
1831 .. attribute:: Option.ALWAYS_TYPED_ACTIONS
1833 Actions that always take a type (i.e. whose options always take a value) are
1834 additionally listed here. The only effect of this is that :mod:`optparse`
1835 assigns the default type, ``"string"``, to options with no explicit type
1836 whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
1838 In order to actually implement your new action, you must override Option's
1839 :meth:`take_action` method and add a case that recognizes your action.
1841 For example, let's add an ``"extend"`` action. This is similar to the standard
1842 ``"append"`` action, but instead of taking a single value from the command-line
1843 and appending it to an existing list, ``"extend"`` will take multiple values in
1844 a single comma-delimited string, and extend an existing list with them. That
1845 is, if ``"--names"`` is an ``"extend"`` option of type ``"string"``, the command
1848 --names=foo,bar --names blah --names ding,dong
1850 would result in a list ::
1852 ["foo", "bar", "blah", "ding", "dong"]
1854 Again we define a subclass of Option::
1856 class MyOption (Option):
1858 ACTIONS = Option.ACTIONS + ("extend",)
1859 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
1860 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
1861 ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
1863 def take_action(self, action, dest, opt, value, values, parser):
1864 if action == "extend":
1865 lvalue = value.split(",")
1866 values.ensure_value(dest, []).extend(lvalue)
1869 self, action, dest, opt, value, values, parser)
1873 * ``"extend"`` both expects a value on the command-line and stores that value
1874 somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
1875 :attr:`~Option.TYPED_ACTIONS`.
1877 * to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
1878 ``"extend"`` actions, we put the ``"extend"`` action in
1879 :attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
1881 * :meth:`MyOption.take_action` implements just this one new action, and passes
1882 control back to :meth:`Option.take_action` for the standard :mod:`optparse`
1885 * ``values`` is an instance of the optparse_parser.Values class, which provides
1886 the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
1887 essentially :func:`getattr` with a safety valve; it is called as ::
1889 values.ensure_value(attr, value)
1891 If the ``attr`` attribute of ``values`` doesn't exist or is None, then
1892 ensure_value() first sets it to ``value``, and then returns 'value. This is
1893 very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
1894 of which accumulate data in a variable and expect that variable to be of a
1895 certain type (a list for the first two, an integer for the latter). Using
1896 :meth:`ensure_value` means that scripts using your action don't have to worry
1897 about setting a default value for the option destinations in question; they
1898 can just leave the default as None and :meth:`ensure_value` will take care of
1899 getting it right when it's needed.