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 ``optparse`` is a more convenient, flexible, and powerful library for parsing
15 command-line options than the old :mod:`getopt` module. ``optparse`` uses a more declarative
16 style of command-line parsing: you create an instance of :class:`OptionParser`,
17 populate it with options, and parse the command line. ``optparse`` allows users
18 to specify options in the conventional GNU/POSIX syntax, and additionally
19 generates usage and help messages for you.
21 Here's an example of using ``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, ``optparse`` sets attributes of the ``options``
40 object returned by :meth:`parse_args` based on user-supplied command-line
41 values. When :meth:`parse_args` returns from parsing this command line,
42 ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
43 ``False``. ``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 ``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()`` or
90 ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
91 (``sys.argv[0]`` is the name of the program being executed). Unix shells also
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 execution
101 of a program. There are many different syntaxes for options; the traditional
102 Unix syntax is a hyphen ("-") followed by a single letter, e.g. ``"-x"`` or
103 ``"-F"``. Also, traditional Unix syntax allows multiple options to be merged
104 into a single argument, e.g. ``"-x -F"`` is equivalent to ``"-xF"``. The GNU
105 project introduced ``"--"`` followed by a series of hyphen-separated words, e.g.
106 ``"--file"`` or ``"--dry-run"``. These are the only two option syntaxes
107 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 will
125 be. This is deliberate: the first three are non-standard on any environment,
126 and the last only makes sense if you're exclusively targeting VMS, MS-DOS,
130 an argument that follows an option, is closely associated with that option, and
131 is consumed from the argument list when that option is. With :mod:`optparse`,
132 option arguments may either be in a separate argument from their option::
137 or included in the same argument::
142 Typically, a given option either takes an argument or it doesn't. Lots of people
143 want an "optional option arguments" feature, meaning that some options will take
144 an argument if they see it, and won't if they don't. This is somewhat
145 controversial, because it makes parsing ambiguous: if ``"-a"`` takes an optional
146 argument and ``"-b"`` is another option entirely, how do we interpret ``"-ab"``?
147 Because of this ambiguity, :mod:`optparse` does not support this feature.
150 something leftover in the argument list after options have been parsed, i.e.
151 after options and their arguments have been parsed and removed from the argument
155 an option that must be supplied on the command-line; note that the phrase
156 "required option" is self-contradictory in English. :mod:`optparse` doesn't
157 prevent you from implementing required options, but doesn't give you much help
158 at it either. See ``examples/required_1.py`` and ``examples/required_2.py`` in
159 the :mod:`optparse` source distribution for two ways to implement required
160 options with :mod:`optparse`.
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:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of
290 these, :attr:`action` is the most fundamental.
293 .. _optparse-understanding-option-actions:
295 Understanding option actions
296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
298 Actions tell :mod:`optparse` what to do when it encounters an option on the
299 command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
300 adding new actions is an advanced topic covered in section
301 :ref:`optparse-extending-optparse`. Most actions tell
302 :mod:`optparse` to store a value in some variable---for example, take a string
303 from the command line and store it in an attribute of ``options``.
305 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
308 .. _optparse-store-action:
313 The most common option action is ``store``, which tells :mod:`optparse` to take
314 the next argument (or the remainder of the current argument), ensure that it is
315 of the correct type, and store it to your chosen destination.
319 parser.add_option("-f", "--file",
320 action="store", type="string", dest="filename")
322 Now let's make up a fake command line and ask :mod:`optparse` to parse it::
324 args = ["-f", "foo.txt"]
325 (options, args) = parser.parse_args(args)
327 When :mod:`optparse` sees the option string ``"-f"``, it consumes the next
328 argument, ``"foo.txt"``, and stores it in ``options.filename``. So, after this
329 call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
331 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
332 Here's an option that expects an integer argument::
334 parser.add_option("-n", type="int", dest="num")
336 Note that this option has no long option string, which is perfectly acceptable.
337 Also, there's no explicit action, since the default is ``store``.
339 Let's parse another fake command-line. This time, we'll jam the option argument
340 right up against the option: since ``"-n42"`` (one argument) is equivalent to
341 ``"-n 42"`` (two arguments), the code ::
343 (options, args) = parser.parse_args(["-n42"])
348 If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
349 the fact that the default action is ``store``, that means our first example can
352 parser.add_option("-f", "--file", dest="filename")
354 If you don't supply a destination, :mod:`optparse` figures out a sensible
355 default from the option strings: if the first long option string is
356 ``"--foo-bar"``, then the default destination is ``foo_bar``. If there are no
357 long option strings, :mod:`optparse` looks at the first short option string: the
358 default destination for ``"-f"`` is ``f``.
360 :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding
361 types is covered in section :ref:`optparse-extending-optparse`.
364 .. _optparse-handling-boolean-options:
366 Handling boolean (flag) options
367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
369 Flag options---set a variable to true or false when a particular option is seen
370 ---are quite common. :mod:`optparse` supports them with two separate actions,
371 ``store_true`` and ``store_false``. For example, you might have a ``verbose``
372 flag that is turned on with ``"-v"`` and off with ``"-q"``::
374 parser.add_option("-v", action="store_true", dest="verbose")
375 parser.add_option("-q", action="store_false", dest="verbose")
377 Here we have two different options with the same destination, which is perfectly
378 OK. (It just means you have to be a bit careful when setting default values---
381 When :mod:`optparse` encounters ``"-v"`` on the command line, it sets
382 ``options.verbose`` to ``True``; when it encounters ``"-q"``,
383 ``options.verbose`` is set to ``False``.
386 .. _optparse-other-actions:
391 Some other actions supported by :mod:`optparse` are:
394 store a constant value
397 append this option's argument to a list
400 increment a counter by one
403 call a specified function
405 These are covered in section :ref:`optparse-reference-guide`, Reference Guide
406 and section :ref:`optparse-option-callbacks`.
409 .. _optparse-default-values:
414 All of the above examples involve setting some variable (the "destination") when
415 certain command-line options are seen. What happens if those options are never
416 seen? Since we didn't supply any defaults, they are all set to ``None``. This
417 is usually fine, but sometimes you want more control. :mod:`optparse` lets you
418 supply a default value for each destination, which is assigned before the
419 command line is parsed.
421 First, consider the verbose/quiet example. If we want :mod:`optparse` to set
422 ``verbose`` to ``True`` unless ``"-q"`` is seen, then we can do this::
424 parser.add_option("-v", action="store_true", dest="verbose", default=True)
425 parser.add_option("-q", action="store_false", dest="verbose")
427 Since default values apply to the *destination* rather than to any particular
428 option, and these two options happen to have the same destination, this is
431 parser.add_option("-v", action="store_true", dest="verbose")
432 parser.add_option("-q", action="store_false", dest="verbose", default=True)
436 parser.add_option("-v", action="store_true", dest="verbose", default=False)
437 parser.add_option("-q", action="store_false", dest="verbose", default=True)
439 Again, the default value for ``verbose`` will be ``True``: the last default
440 value supplied for any particular destination is the one that counts.
442 A clearer way to specify default values is the :meth:`set_defaults` method of
443 OptionParser, which you can call at any time before calling :meth:`parse_args`::
445 parser.set_defaults(verbose=True)
446 parser.add_option(...)
447 (options, args) = parser.parse_args()
449 As before, the last value specified for a given option destination is the one
450 that counts. For clarity, try to use one method or the other of setting default
454 .. _optparse-generating-help:
459 :mod:`optparse`'s ability to generate help and usage text automatically is
460 useful for creating user-friendly command-line interfaces. All you have to do
461 is supply a :attr:`help` value for each option, and optionally a short usage
462 message for your whole program. Here's an OptionParser populated with
463 user-friendly (documented) options::
465 usage = "usage: %prog [options] arg1 arg2"
466 parser = OptionParser(usage=usage)
467 parser.add_option("-v", "--verbose",
468 action="store_true", dest="verbose", default=True,
469 help="make lots of noise [default]")
470 parser.add_option("-q", "--quiet",
471 action="store_false", dest="verbose",
472 help="be vewwy quiet (I'm hunting wabbits)")
473 parser.add_option("-f", "--filename",
474 metavar="FILE", help="write output to FILE"),
475 parser.add_option("-m", "--mode",
476 default="intermediate",
477 help="interaction mode: novice, intermediate, "
478 "or expert [default: %default]")
480 If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the
481 command-line, or if you just call :meth:`parser.print_help`, it prints the
482 following to standard output::
484 usage: <yourscript> [options] arg1 arg2
487 -h, --help show this help message and exit
488 -v, --verbose make lots of noise [default]
489 -q, --quiet be vewwy quiet (I'm hunting wabbits)
490 -f FILE, --filename=FILE
492 -m MODE, --mode=MODE interaction mode: novice, intermediate, or
493 expert [default: intermediate]
495 (If the help output is triggered by a help option, :mod:`optparse` exits after
496 printing the help text.)
498 There's a lot going on here to help :mod:`optparse` generate the best possible
501 * the script defines its own usage message::
503 usage = "usage: %prog [options] arg1 arg2"
505 :mod:`optparse` expands ``"%prog"`` in the usage string to the name of the
506 current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string is
507 then printed before the detailed option help.
509 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
510 default: ``"usage: %prog [options]"``, which is fine if your script doesn't take
511 any positional arguments.
513 * every option defines a help string, and doesn't worry about line-wrapping---
514 :mod:`optparse` takes care of wrapping lines and making the help output look
517 * options that take a value indicate this fact in their automatically-generated
518 help message, e.g. for the "mode" option::
522 Here, "MODE" is called the meta-variable: it stands for the argument that the
523 user is expected to supply to :option:`-m`/:option:`--mode`. By default,
524 :mod:`optparse` converts the destination variable name to uppercase and uses
525 that for the meta-variable. Sometimes, that's not what you want---for example,
526 the :option:`--filename` option explicitly sets ``metavar="FILE"``, resulting in
527 this automatically-generated option description::
529 -f FILE, --filename=FILE
531 This is important for more than just saving space, though: the manually written
532 help text uses the meta-variable "FILE" to clue the user in that there's a
533 connection between the semi-formal syntax "-f FILE" and the informal semantic
534 description "write output to FILE". This is a simple but effective way to make
535 your help text a lot clearer and more useful for end users.
537 .. versionadded:: 2.4
538 Options that have a default value can include ``%default`` in the help
539 string---\ :mod:`optparse` will replace it with :func:`str` of the option's
540 default value. If an option has no default value (or the default value is
541 ``None``), ``%default`` expands to ``none``.
543 When dealing with many options, it is convenient to group these
544 options for better help output. An :class:`OptionParser` can contain
545 several option groups, each of which can contain several options.
547 Continuing with the parser defined above, adding an
548 :class:`OptionGroup` to a parser is easy::
550 group = OptionGroup(parser, "Dangerous Options",
551 "Caution: use these options at your own risk. "
552 "It is believed that some of them bite.")
553 group.add_option("-g", action="store_true", help="Group option.")
554 parser.add_option_group(group)
556 This would result in the following help output::
558 usage: [options] arg1 arg2
561 -h, --help show this help message and exit
562 -v, --verbose make lots of noise [default]
563 -q, --quiet be vewwy quiet (I'm hunting wabbits)
564 -fFILE, --file=FILE write output to FILE
565 -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'
569 Caution: use of these options is at your own risk. It is believed that
573 .. _optparse-printing-version-string:
575 Printing a version string
576 ^^^^^^^^^^^^^^^^^^^^^^^^^
578 Similar to the brief usage string, :mod:`optparse` can also print a version
579 string for your program. You have to supply the string as the ``version``
580 argument to OptionParser::
582 parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
584 ``"%prog"`` is expanded just like it is in ``usage``. Apart from that,
585 ``version`` can contain anything you like. When you supply it, :mod:`optparse`
586 automatically adds a ``"--version"`` option to your parser. If it encounters
587 this option on the command line, it expands your ``version`` string (by
588 replacing ``"%prog"``), prints it to stdout, and exits.
590 For example, if your script is called ``/usr/bin/foo``::
592 $ /usr/bin/foo --version
596 .. _optparse-how-optparse-handles-errors:
598 How :mod:`optparse` handles errors
599 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
601 There are two broad classes of errors that :mod:`optparse` has to worry about:
602 programmer errors and user errors. Programmer errors are usually erroneous
603 calls to ``parser.add_option()``, e.g. invalid option strings, unknown option
604 attributes, missing option attributes, etc. These are dealt with in the usual
605 way: raise an exception (either ``optparse.OptionError`` or :exc:`TypeError`) and
606 let the program crash.
608 Handling user errors is much more important, since they are guaranteed to happen
609 no matter how stable your code is. :mod:`optparse` can automatically detect
610 some user errors, such as bad option arguments (passing ``"-n 4x"`` where
611 :option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
612 of the command line, where :option:`-n` takes an argument of any type). Also,
613 you can call ``parser.error()`` to signal an application-defined error
616 (options, args) = parser.parse_args()
618 if options.a and options.b:
619 parser.error("options -a and -b are mutually exclusive")
621 In either case, :mod:`optparse` handles the error the same way: it prints the
622 program's usage message and an error message to standard error and exits with
625 Consider the first example above, where the user passes ``"4x"`` to an option
626 that takes an integer::
631 foo: error: option -n: invalid integer value: '4x'
633 Or, where the user fails to pass a value at all::
638 foo: error: -n option requires an argument
640 :mod:`optparse`\ -generated error messages take care always to mention the
641 option involved in the error; be sure to do the same when calling
642 ``parser.error()`` from your application code.
644 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
645 you'll need to subclass OptionParser and override its :meth:`exit` and/or
646 :meth:`error` methods.
649 .. _optparse-putting-it-all-together:
651 Putting it all together
652 ^^^^^^^^^^^^^^^^^^^^^^^
654 Here's what :mod:`optparse`\ -based scripts usually look like::
656 from optparse import OptionParser
659 usage = "usage: %prog [options] arg"
660 parser = OptionParser(usage)
661 parser.add_option("-f", "--file", dest="filename",
662 help="read data from FILENAME")
663 parser.add_option("-v", "--verbose",
664 action="store_true", dest="verbose")
665 parser.add_option("-q", "--quiet",
666 action="store_false", dest="verbose")
668 (options, args) = parser.parse_args()
670 parser.error("incorrect number of arguments")
672 print "reading %s..." % options.filename
675 if __name__ == "__main__":
679 .. _optparse-reference-guide:
685 .. _optparse-creating-parser:
690 The first step in using :mod:`optparse` is to create an OptionParser instance::
692 parser = OptionParser(...)
694 The OptionParser constructor has no required arguments, but a number of optional
695 keyword arguments. You should always pass them as keyword arguments, i.e. do
696 not rely on the order in which the arguments are declared.
698 ``usage`` (default: ``"%prog [options]"``)
699 The usage summary to print when your program is run incorrectly or with a help
700 option. When :mod:`optparse` prints the usage string, it expands ``%prog`` to
701 ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you passed that keyword
702 argument). To suppress a usage message, pass the special value
703 ``optparse.SUPPRESS_USAGE``.
705 ``option_list`` (default: ``[]``)
706 A list of Option objects to populate the parser with. The options in
707 ``option_list`` are added after any options in ``standard_option_list`` (a class
708 attribute that may be set by OptionParser subclasses), but before any version or
709 help options. Deprecated; use :meth:`add_option` after creating the parser
712 ``option_class`` (default: optparse.Option)
713 Class to use when adding options to the parser in :meth:`add_option`.
715 ``version`` (default: ``None``)
716 A version string to print when the user supplies a version option. If you supply
717 a true value for ``version``, :mod:`optparse` automatically adds a version
718 option with the single option string ``"--version"``. The substring ``"%prog"``
719 is expanded the same as for ``usage``.
721 ``conflict_handler`` (default: ``"error"``)
722 Specifies what to do when options with conflicting option strings are added to
723 the parser; see section :ref:`optparse-conflicts-between-options`.
725 ``description`` (default: ``None``)
726 A paragraph of text giving a brief overview of your program. :mod:`optparse`
727 reformats this paragraph to fit the current terminal width and prints it when
728 the user requests help (after ``usage``, but before the list of options).
730 ``formatter`` (default: a new IndentedHelpFormatter)
731 An instance of optparse.HelpFormatter that will be used for printing help text.
732 :mod:`optparse` provides two concrete classes for this purpose:
733 IndentedHelpFormatter and TitledHelpFormatter.
735 ``add_help_option`` (default: ``True``)
736 If true, :mod:`optparse` will add a help option (with option strings ``"-h"``
737 and ``"--help"``) to the parser.
740 The string to use when expanding ``"%prog"`` in ``usage`` and ``version``
741 instead of ``os.path.basename(sys.argv[0])``.
745 .. _optparse-populating-parser:
747 Populating the parser
748 ^^^^^^^^^^^^^^^^^^^^^
750 There are several ways to populate the parser with options. The preferred way
751 is by using ``OptionParser.add_option()``, as shown in section
752 :ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
754 * pass it an Option instance (as returned by :func:`make_option`)
756 * pass it any combination of positional and keyword arguments that are
757 acceptable to :func:`make_option` (i.e., to the Option constructor), and it will
758 create the Option instance for you
760 The other alternative is to pass a list of pre-constructed Option instances to
761 the OptionParser constructor, as in::
764 make_option("-f", "--filename",
765 action="store", type="string", dest="filename"),
766 make_option("-q", "--quiet",
767 action="store_false", dest="verbose"),
769 parser = OptionParser(option_list=option_list)
771 (:func:`make_option` is a factory function for creating Option instances;
772 currently it is an alias for the Option constructor. A future version of
773 :mod:`optparse` may split Option into several classes, and :func:`make_option`
774 will pick the right class to instantiate. Do not instantiate Option directly.)
777 .. _optparse-defining-options:
782 Each Option instance represents a set of synonymous command-line option strings,
783 e.g. :option:`-f` and :option:`--file`. You can specify any number of short or
784 long option strings, but you must specify at least one overall option string.
786 The canonical way to create an Option instance is with the :meth:`add_option`
787 method of :class:`OptionParser`::
789 parser.add_option(opt_str[, ...], attr=value, ...)
791 To define an option with only a short option string::
793 parser.add_option("-f", attr=value, ...)
795 And to define an option with only a long option string::
797 parser.add_option("--foo", attr=value, ...)
799 The keyword arguments define attributes of the new Option object. The most
800 important option attribute is :attr:`action`, and it largely determines which
801 other attributes are relevant or required. If you pass irrelevant option
802 attributes, or fail to pass required ones, :mod:`optparse` raises an
803 :exc:`OptionError` exception explaining your mistake.
805 An option's *action* determines what :mod:`optparse` does when it encounters
806 this option on the command-line. The standard option actions hard-coded into
810 store this option's argument (default)
813 store a constant value
822 append this option's argument to a list
825 append a constant value to a list
828 increment a counter by one
831 call a specified function
834 print a usage message including all options and the documentation for them
836 (If you don't supply an action, the default is ``store``. For this action, you
837 may also supply :attr:`type` and :attr:`dest` option attributes; see below.)
839 As you can see, most actions involve storing or updating a value somewhere.
840 :mod:`optparse` always creates a special object for this, conventionally called
841 ``options`` (it happens to be an instance of ``optparse.Values``). Option
842 arguments (and various other values) are stored as attributes of this object,
843 according to the :attr:`dest` (destination) option attribute.
845 For example, when you call ::
849 one of the first things :mod:`optparse` does is create the ``options`` object::
853 If one of the options in this parser is defined with ::
855 parser.add_option("-f", "--file", action="store", type="string", dest="filename")
857 and the command-line being parsed includes any of the following::
864 then :mod:`optparse`, on seeing this option, will do the equivalent of ::
866 options.filename = "foo"
868 The :attr:`type` and :attr:`dest` option attributes are almost as important as
869 :attr:`action`, but :attr:`action` is the only one that makes sense for *all*
873 .. _optparse-standard-option-actions:
875 Standard option actions
876 ^^^^^^^^^^^^^^^^^^^^^^^
878 The various option actions all have slightly different requirements and effects.
879 Most actions have several relevant option attributes which you may specify to
880 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
881 must specify for any option using that action.
883 * ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
885 The option must be followed by an argument, which is converted to a value
886 according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1,
887 multiple arguments will be consumed from the command line; all will be converted
888 according to :attr:`type` and stored to :attr:`dest` as a tuple. See the
889 "Option types" section below.
891 If ``choices`` is supplied (a list or tuple of strings), the type defaults to
894 If :attr:`type` is not supplied, it defaults to ``string``.
896 If :attr:`dest` is not supplied, :mod:`optparse` derives a destination from the
897 first long option string (e.g., ``"--foo-bar"`` implies ``foo_bar``). If there
898 are no long option strings, :mod:`optparse` derives a destination from the first
899 short option string (e.g., ``"-f"`` implies ``f``).
903 parser.add_option("-f")
904 parser.add_option("-p", type="float", nargs=3, dest="point")
906 As it parses the command line ::
908 -f foo.txt -p 1 -3.5 4 -fbar.txt
910 :mod:`optparse` will set ::
912 options.f = "foo.txt"
913 options.point = (1.0, -3.5, 4.0)
914 options.f = "bar.txt"
916 * ``store_const`` [required: ``const``; relevant: :attr:`dest`]
918 The value ``const`` is stored in :attr:`dest`.
922 parser.add_option("-q", "--quiet",
923 action="store_const", const=0, dest="verbose")
924 parser.add_option("-v", "--verbose",
925 action="store_const", const=1, dest="verbose")
926 parser.add_option("--noisy",
927 action="store_const", const=2, dest="verbose")
929 If ``"--noisy"`` is seen, :mod:`optparse` will set ::
933 * ``store_true`` [relevant: :attr:`dest`]
935 A special case of ``store_const`` that stores a true value to :attr:`dest`.
937 * ``store_false`` [relevant: :attr:`dest`]
939 Like ``store_true``, but stores a false value.
943 parser.add_option("--clobber", action="store_true", dest="clobber")
944 parser.add_option("--no-clobber", action="store_false", dest="clobber")
946 * ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
948 The option must be followed by an argument, which is appended to the list in
949 :attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list
950 is automatically created when :mod:`optparse` first encounters this option on
951 the command-line. If ``nargs`` > 1, multiple arguments are consumed, and a
952 tuple of length ``nargs`` is appended to :attr:`dest`.
954 The defaults for :attr:`type` and :attr:`dest` are the same as for the ``store``
959 parser.add_option("-t", "--tracks", action="append", type="int")
961 If ``"-t3"`` is seen on the command-line, :mod:`optparse` does the equivalent
965 options.tracks.append(int("3"))
967 If, a little later on, ``"--tracks=4"`` is seen, it does::
969 options.tracks.append(int("4"))
971 * ``append_const`` [required: ``const``; relevant: :attr:`dest`]
973 Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as
974 with ``append``, :attr:`dest` defaults to ``None``, and an empty list is
975 automatically created the first time the option is encountered.
977 * ``count`` [relevant: :attr:`dest`]
979 Increment the integer stored at :attr:`dest`. If no default value is supplied,
980 :attr:`dest` is set to zero before being incremented the first time.
984 parser.add_option("-v", action="count", dest="verbosity")
986 The first time ``"-v"`` is seen on the command line, :mod:`optparse` does the
989 options.verbosity = 0
990 options.verbosity += 1
992 Every subsequent occurrence of ``"-v"`` results in ::
994 options.verbosity += 1
996 * ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``,
997 ``callback_args``, ``callback_kwargs``]
999 Call the function specified by ``callback``, which is called as ::
1001 func(option, opt_str, value, parser, *args, **kwargs)
1003 See section :ref:`optparse-option-callbacks` for more detail.
1007 Prints a complete help message for all the options in the current option parser.
1008 The help message is constructed from the ``usage`` string passed to
1009 OptionParser's constructor and the :attr:`help` string passed to every option.
1011 If no :attr:`help` string is supplied for an option, it will still be listed in
1012 the help message. To omit an option entirely, use the special value
1013 ``optparse.SUPPRESS_HELP``.
1015 :mod:`optparse` automatically adds a :attr:`help` option to all OptionParsers,
1016 so you do not normally need to create one.
1020 from optparse import OptionParser, SUPPRESS_HELP
1022 parser = OptionParser()
1023 parser.add_option("-h", "--help", action="help"),
1024 parser.add_option("-v", action="store_true", dest="verbose",
1025 help="Be moderately verbose")
1026 parser.add_option("--file", dest="filename",
1027 help="Input file to read data from"),
1028 parser.add_option("--secret", help=SUPPRESS_HELP)
1030 If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line, it
1031 will print something like the following help message to stdout (assuming
1032 ``sys.argv[0]`` is ``"foo.py"``)::
1034 usage: foo.py [options]
1037 -h, --help Show this help message and exit
1038 -v Be moderately verbose
1039 --file=FILENAME Input file to read data from
1041 After printing the help message, :mod:`optparse` terminates your process with
1046 Prints the version number supplied to the OptionParser to stdout and exits. The
1047 version number is actually formatted and printed by the ``print_version()``
1048 method of OptionParser. Generally only relevant if the ``version`` argument is
1049 supplied to the OptionParser constructor. As with :attr:`help` options, you
1050 will rarely create ``version`` options, since :mod:`optparse` automatically adds
1054 .. _optparse-option-attributes:
1059 The following option attributes may be passed as keyword arguments to
1060 ``parser.add_option()``. If you pass an option attribute that is not relevant
1061 to a particular option, or fail to pass a required option attribute,
1062 :mod:`optparse` raises :exc:`OptionError`.
1064 * :attr:`action` (default: ``"store"``)
1066 Determines :mod:`optparse`'s behaviour when this option is seen on the command
1067 line; the available options are documented above.
1069 * :attr:`type` (default: ``"string"``)
1071 The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the
1072 available option types are documented below.
1074 * :attr:`dest` (default: derived from option strings)
1076 If the option's action implies writing or modifying a value somewhere, this
1077 tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the
1078 ``options`` object that :mod:`optparse` builds as it parses the command line.
1082 The value to use for this option's destination if the option is not seen on the
1083 command line. See also ``parser.set_defaults()``.
1085 * ``nargs`` (default: 1)
1087 How many arguments of type :attr:`type` should be consumed when this option is
1088 seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`.
1092 For actions that store a constant value, the constant value to store.
1096 For options of type ``"choice"``, the list of strings the user may choose from.
1100 For options with action ``"callback"``, the callable to call when this option
1101 is seen. See section :ref:`optparse-option-callbacks` for detail on the
1102 arguments passed to ``callable``.
1104 * ``callback_args``, ``callback_kwargs``
1106 Additional positional and keyword arguments to pass to ``callback`` after the
1107 four standard callback arguments.
1111 Help text to print for this option when listing all available options after the
1112 user supplies a :attr:`help` option (such as ``"--help"``). If no help text is
1113 supplied, the option will be listed without help text. To hide this option, use
1114 the special value ``SUPPRESS_HELP``.
1116 * ``metavar`` (default: derived from option strings)
1118 Stand-in for the option argument(s) to use when printing help text. See section
1119 :ref:`optparse-tutorial` for an example.
1122 .. _optparse-standard-option-types:
1124 Standard option types
1125 ^^^^^^^^^^^^^^^^^^^^^
1127 :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``,
1128 ``choice``, ``float`` and ``complex``. If you need to add new option types, see
1129 section :ref:`optparse-extending-optparse`.
1131 Arguments to string options are not checked or converted in any way: the text on
1132 the command line is stored in the destination (or passed to the callback) as-is.
1134 Integer arguments (type ``int`` or ``long``) are parsed as follows:
1136 * if the number starts with ``0x``, it is parsed as a hexadecimal number
1138 * if the number starts with ``0``, it is parsed as an octal number
1140 * if the number starts with ``0b``, it is parsed as a binary number
1142 * otherwise, the number is parsed as a decimal number
1145 The conversion is done by calling either ``int()`` or ``long()`` with the
1146 appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`,
1147 although with a more useful error message.
1149 ``float`` and ``complex`` option arguments are converted directly with
1150 ``float()`` and ``complex()``, with similar error-handling.
1152 ``choice`` options are a subtype of ``string`` options. The ``choices`` option
1153 attribute (a sequence of strings) defines the set of allowed option arguments.
1154 ``optparse.check_choice()`` compares user-supplied option arguments against this
1155 master list and raises :exc:`OptionValueError` if an invalid string is given.
1158 .. _optparse-parsing-arguments:
1163 The whole point of creating and populating an OptionParser is to call its
1164 :meth:`parse_args` method::
1166 (options, args) = parser.parse_args(args=None, values=None)
1168 where the input parameters are
1171 the list of arguments to process (default: ``sys.argv[1:]``)
1174 object to store option arguments in (default: a new instance of optparse.Values)
1176 and the return values are
1179 the same object that was passed in as ``options``, or the optparse.Values
1180 instance created by :mod:`optparse`
1183 the leftover positional arguments after all options have been processed
1185 The most common usage is to supply neither keyword argument. If you supply
1186 ``options``, it will be modified with repeated ``setattr()`` calls (roughly one
1187 for every option argument stored to an option destination) and returned by
1190 If :meth:`parse_args` encounters any errors in the argument list, it calls the
1191 OptionParser's :meth:`error` method with an appropriate end-user error message.
1192 This ultimately terminates your process with an exit status of 2 (the
1193 traditional Unix exit status for command-line errors).
1196 .. _optparse-querying-manipulating-option-parser:
1198 Querying and manipulating your option parser
1199 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1201 The default behavior of the option parser can be customized slightly,
1202 and you can also poke around your option parser and see what's there.
1203 OptionParser provides several methods to help you out:
1205 ``disable_interspersed_args()``
1206 Set parsing to stop on the first non-option. Use this if you have a
1207 command processor which runs another command which has options of
1208 its own and you want to make sure these options don't get
1209 confused. For example, each command might have a different
1212 ``enable_interspersed_args()``
1213 Set parsing to not stop on the first non-option, allowing
1214 interspersing switches with command arguments. For example,
1215 ``"-s arg1 --long arg2"`` would return ``["arg1", "arg2"]``
1216 as the command arguments and ``-s, --long`` as options.
1217 This is the default behavior.
1219 ``get_option(opt_str)``
1220 Returns the Option instance with the option string ``opt_str``, or ``None`` if
1221 no options have that option string.
1223 ``has_option(opt_str)``
1224 Return true if the OptionParser has an option with option string ``opt_str``
1225 (e.g., ``"-q"`` or ``"--verbose"``).
1227 ``remove_option(opt_str)``
1228 If the :class:`OptionParser` has an option corresponding to ``opt_str``, that option is
1229 removed. If that option provided any other option strings, all of those option
1230 strings become invalid. If ``opt_str`` does not occur in any option belonging to
1231 this :class:`OptionParser`, raises :exc:`ValueError`.
1234 .. _optparse-conflicts-between-options:
1236 Conflicts between options
1237 ^^^^^^^^^^^^^^^^^^^^^^^^^
1239 If you're not careful, it's easy to define options with conflicting option
1242 parser.add_option("-n", "--dry-run", ...)
1244 parser.add_option("-n", "--noisy", ...)
1246 (This is particularly true if you've defined your own OptionParser subclass with
1247 some standard options.)
1249 Every time you add an option, :mod:`optparse` checks for conflicts with existing
1250 options. If it finds any, it invokes the current conflict-handling mechanism.
1251 You can set the conflict-handling mechanism either in the constructor::
1253 parser = OptionParser(..., conflict_handler=handler)
1255 or with a separate call::
1257 parser.set_conflict_handler(handler)
1259 The available conflict handlers are:
1262 assume option conflicts are a programming error and raise :exc:`OptionConflictError`
1265 resolve option conflicts intelligently (see below)
1268 As an example, let's define an :class:`OptionParser` that resolves conflicts
1269 intelligently and add conflicting options to it::
1271 parser = OptionParser(conflict_handler="resolve")
1272 parser.add_option("-n", "--dry-run", ..., help="do no harm")
1273 parser.add_option("-n", "--noisy", ..., help="be noisy")
1275 At this point, :mod:`optparse` detects that a previously-added option is already
1276 using the ``"-n"`` option string. Since ``conflict_handler`` is ``"resolve"``,
1277 it resolves the situation by removing ``"-n"`` from the earlier option's list of
1278 option strings. Now ``"--dry-run"`` is the only way for the user to activate
1279 that option. If the user asks for help, the help message will reflect that::
1282 --dry-run do no harm
1284 -n, --noisy be noisy
1286 It's possible to whittle away the option strings for a previously-added option
1287 until there are none left, and the user has no way of invoking that option from
1288 the command-line. In that case, :mod:`optparse` removes that option completely,
1289 so it doesn't show up in help text or anywhere else. Carrying on with our
1290 existing OptionParser::
1292 parser.add_option("--dry-run", ..., help="new dry-run option")
1294 At this point, the original :option:`-n/--dry-run` option is no longer
1295 accessible, so :mod:`optparse` removes it, leaving this help text::
1299 -n, --noisy be noisy
1300 --dry-run new dry-run option
1303 .. _optparse-cleanup:
1308 OptionParser instances have several cyclic references. This should not be a
1309 problem for Python's garbage collector, but you may wish to break the cyclic
1310 references explicitly by calling ``destroy()`` on your OptionParser once you are
1311 done with it. This is particularly useful in long-running applications where
1312 large object graphs are reachable from your OptionParser.
1315 .. _optparse-other-methods:
1320 OptionParser supports several other public methods:
1322 * ``set_usage(usage)``
1324 Set the usage string according to the rules described above for the ``usage``
1325 constructor keyword argument. Passing ``None`` sets the default usage string;
1326 use ``SUPPRESS_USAGE`` to suppress a usage message.
1328 * ``enable_interspersed_args()``, ``disable_interspersed_args()``
1330 Enable/disable positional arguments interspersed with options, similar to GNU
1331 getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both
1332 simple options that take no arguments, :mod:`optparse` normally accepts this
1335 prog -a arg1 -b arg2
1337 and treats it as equivalent to ::
1339 prog -a -b arg1 arg2
1341 To disable this feature, call ``disable_interspersed_args()``. This restores
1342 traditional Unix syntax, where option parsing stops with the first non-option
1345 * ``set_defaults(dest=value, ...)``
1347 Set default values for several option destinations at once. Using
1348 :meth:`set_defaults` is the preferred way to set default values for options,
1349 since multiple options can share the same destination. For example, if several
1350 "mode" options all set the same destination, any one of them can set the
1351 default, and the last one wins::
1353 parser.add_option("--advanced", action="store_const",
1354 dest="mode", const="advanced",
1355 default="novice") # overridden below
1356 parser.add_option("--novice", action="store_const",
1357 dest="mode", const="novice",
1358 default="advanced") # overrides above setting
1360 To avoid this confusion, use :meth:`set_defaults`::
1362 parser.set_defaults(mode="advanced")
1363 parser.add_option("--advanced", action="store_const",
1364 dest="mode", const="advanced")
1365 parser.add_option("--novice", action="store_const",
1366 dest="mode", const="novice")
1369 .. _optparse-option-callbacks:
1374 When :mod:`optparse`'s built-in actions and types aren't quite enough for your
1375 needs, you have two choices: extend :mod:`optparse` or define a callback option.
1376 Extending :mod:`optparse` is more general, but overkill for a lot of simple
1377 cases. Quite often a simple callback is all you need.
1379 There are two steps to defining a callback option:
1381 * define the option itself using the ``callback`` action
1383 * write the callback; this is a function (or method) that takes at least four
1384 arguments, as described below
1387 .. _optparse-defining-callback-option:
1389 Defining a callback option
1390 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1392 As always, the easiest way to define a callback option is by using the
1393 ``parser.add_option()`` method. Apart from :attr:`action`, the only option
1394 attribute you must specify is ``callback``, the function to call::
1396 parser.add_option("-c", action="callback", callback=my_callback)
1398 ``callback`` is a function (or other callable object), so you must have already
1399 defined ``my_callback()`` when you create this callback option. In this simple
1400 case, :mod:`optparse` doesn't even know if :option:`-c` takes any arguments,
1401 which usually means that the option takes no arguments---the mere presence of
1402 :option:`-c` on the command-line is all it needs to know. In some
1403 circumstances, though, you might want your callback to consume an arbitrary
1404 number of command-line arguments. This is where writing callbacks gets tricky;
1405 it's covered later in this section.
1407 :mod:`optparse` always passes four particular arguments to your callback, and it
1408 will only pass additional arguments if you specify them via ``callback_args``
1409 and ``callback_kwargs``. Thus, the minimal callback function signature is::
1411 def my_callback(option, opt, value, parser):
1413 The four arguments to a callback are described below.
1415 There are several other option attributes that you can supply when you define a
1419 has its usual meaning: as with the ``store`` or ``append`` actions, it instructs
1420 :mod:`optparse` to consume one argument and convert it to :attr:`type`. Rather
1421 than storing the converted value(s) anywhere, though, :mod:`optparse` passes it
1422 to your callback function.
1425 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
1426 consume ``nargs`` arguments, each of which must be convertible to :attr:`type`.
1427 It then passes a tuple of converted values to your callback.
1430 a tuple of extra positional arguments to pass to the callback
1433 a dictionary of extra keyword arguments to pass to the callback
1436 .. _optparse-how-callbacks-called:
1438 How callbacks are called
1439 ^^^^^^^^^^^^^^^^^^^^^^^^
1441 All callbacks are called as follows::
1443 func(option, opt_str, value, parser, *args, **kwargs)
1448 is the Option instance that's calling the callback
1451 is the option string seen on the command-line that's triggering the callback.
1452 (If an abbreviated long option was used, ``opt_str`` will be the full, canonical
1453 option string---e.g. if the user puts ``"--foo"`` on the command-line as an
1454 abbreviation for ``"--foobar"``, then ``opt_str`` will be ``"--foobar"``.)
1457 is the argument to this option seen on the command-line. :mod:`optparse` will
1458 only expect an argument if :attr:`type` is set; the type of ``value`` will be
1459 the type implied by the option's type. If :attr:`type` for this option is
1460 ``None`` (no argument expected), then ``value`` will be ``None``. If ``nargs``
1461 > 1, ``value`` will be a tuple of values of the appropriate type.
1464 is the OptionParser instance driving the whole thing, mainly useful because you
1465 can access some other interesting data through its instance attributes:
1468 the current list of leftover arguments, ie. arguments that have been consumed
1469 but are neither options nor option arguments. Feel free to modify
1470 ``parser.largs``, e.g. by adding more arguments to it. (This list will become
1471 ``args``, the second return value of :meth:`parse_args`.)
1474 the current list of remaining arguments, ie. with ``opt_str`` and ``value`` (if
1475 applicable) removed, and only the arguments following them still there. Feel
1476 free to modify ``parser.rargs``, e.g. by consuming more arguments.
1479 the object where option values are by default stored (an instance of
1480 optparse.OptionValues). This lets callbacks use the same mechanism as the rest
1481 of :mod:`optparse` for storing option values; you don't need to mess around with
1482 globals or closures. You can also access or modify the value(s) of any options
1483 already encountered on the command-line.
1486 is a tuple of arbitrary positional arguments supplied via the ``callback_args``
1490 is a dictionary of arbitrary keyword arguments supplied via ``callback_kwargs``.
1493 .. _optparse-raising-errors-in-callback:
1495 Raising errors in a callback
1496 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1498 The callback function should raise :exc:`OptionValueError` if there are any problems
1499 with the option or its argument(s). :mod:`optparse` catches this and terminates
1500 the program, printing the error message you supply to stderr. Your message
1501 should be clear, concise, accurate, and mention the option at fault. Otherwise,
1502 the user will have a hard time figuring out what he did wrong.
1505 .. _optparse-callback-example-1:
1507 Callback example 1: trivial callback
1508 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1510 Here's an example of a callback option that takes no arguments, and simply
1511 records that the option was seen::
1513 def record_foo_seen(option, opt_str, value, parser):
1514 parser.values.saw_foo = True
1516 parser.add_option("--foo", action="callback", callback=record_foo_seen)
1518 Of course, you could do that with the ``store_true`` action.
1521 .. _optparse-callback-example-2:
1523 Callback example 2: check option order
1524 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1526 Here's a slightly more interesting example: record the fact that ``"-a"`` is
1527 seen, but blow up if it comes after ``"-b"`` in the command-line. ::
1529 def check_order(option, opt_str, value, parser):
1531 raise OptionValueError("can't use -a after -b")
1534 parser.add_option("-a", action="callback", callback=check_order)
1535 parser.add_option("-b", action="store_true", dest="b")
1538 .. _optparse-callback-example-3:
1540 Callback example 3: check option order (generalized)
1541 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1543 If you want to re-use this callback for several similar options (set a flag, but
1544 blow up if ``"-b"`` has already been seen), it needs a bit of work: the error
1545 message and the flag that it sets must be generalized. ::
1547 def check_order(option, opt_str, value, parser):
1549 raise OptionValueError("can't use %s after -b" % opt_str)
1550 setattr(parser.values, option.dest, 1)
1552 parser.add_option("-a", action="callback", callback=check_order, dest='a')
1553 parser.add_option("-b", action="store_true", dest="b")
1554 parser.add_option("-c", action="callback", callback=check_order, dest='c')
1557 .. _optparse-callback-example-4:
1559 Callback example 4: check arbitrary condition
1560 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1562 Of course, you could put any condition in there---you're not limited to checking
1563 the values of already-defined options. For example, if you have options that
1564 should not be called when the moon is full, all you have to do is this::
1566 def check_moon(option, opt_str, value, parser):
1568 raise OptionValueError("%s option invalid when moon is full"
1570 setattr(parser.values, option.dest, 1)
1572 parser.add_option("--foo",
1573 action="callback", callback=check_moon, dest="foo")
1575 (The definition of ``is_moon_full()`` is left as an exercise for the reader.)
1578 .. _optparse-callback-example-5:
1580 Callback example 5: fixed arguments
1581 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1583 Things get slightly more interesting when you define callback options that take
1584 a fixed number of arguments. Specifying that a callback option takes arguments
1585 is similar to defining a ``store`` or ``append`` option: if you define
1586 :attr:`type`, then the option takes one argument that must be convertible to
1587 that type; if you further define ``nargs``, then the option takes ``nargs``
1590 Here's an example that just emulates the standard ``store`` action::
1592 def store_value(option, opt_str, value, parser):
1593 setattr(parser.values, option.dest, value)
1595 parser.add_option("--foo",
1596 action="callback", callback=store_value,
1597 type="int", nargs=3, dest="foo")
1599 Note that :mod:`optparse` takes care of consuming 3 arguments and converting
1600 them to integers for you; all you have to do is store them. (Or whatever;
1601 obviously you don't need a callback for this example.)
1604 .. _optparse-callback-example-6:
1606 Callback example 6: variable arguments
1607 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1609 Things get hairy when you want an option to take a variable number of arguments.
1610 For this case, you must write a callback, as :mod:`optparse` doesn't provide any
1611 built-in capabilities for it. And you have to deal with certain intricacies of
1612 conventional Unix command-line parsing that :mod:`optparse` normally handles for
1613 you. In particular, callbacks should implement the conventional rules for bare
1614 ``"--"`` and ``"-"`` arguments:
1616 * either ``"--"`` or ``"-"`` can be option arguments
1618 * bare ``"--"`` (if not the argument to some option): halt command-line
1619 processing and discard the ``"--"``
1621 * bare ``"-"`` (if not the argument to some option): halt command-line
1622 processing but keep the ``"-"`` (append it to ``parser.largs``)
1624 If you want an option that takes a variable number of arguments, there are
1625 several subtle, tricky issues to worry about. The exact implementation you
1626 choose will be based on which trade-offs you're willing to make for your
1627 application (which is why :mod:`optparse` doesn't support this sort of thing
1630 Nevertheless, here's a stab at a callback for an option with variable
1633 def vararg_callback(option, opt_str, value, parser):
1634 assert value is None
1644 for arg in parser.rargs:
1645 # stop on --foo like options
1646 if arg[:2] == "--" and len(arg) > 2:
1648 # stop on -a, but not on -3 or -3.0
1649 if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
1653 del parser.rargs[:len(value)]
1654 setattr(parser.values, option.dest, value)
1657 parser.add_option("-c", "--callback", dest="vararg_attr",
1658 action="callback", callback=vararg_callback)
1661 .. _optparse-extending-optparse:
1663 Extending :mod:`optparse`
1664 -------------------------
1666 Since the two major controlling factors in how :mod:`optparse` interprets
1667 command-line options are the action and type of each option, the most likely
1668 direction of extension is to add new actions and new types.
1671 .. _optparse-adding-new-types:
1676 To add new types, you need to define your own subclass of :mod:`optparse`'s
1677 Option class. This class has a couple of attributes that define
1678 :mod:`optparse`'s types: :attr:`TYPES` and :attr:`TYPE_CHECKER`.
1680 :attr:`TYPES` is a tuple of type names; in your subclass, simply define a new
1681 tuple :attr:`TYPES` that builds on the standard one.
1683 :attr:`TYPE_CHECKER` is a dictionary mapping type names to type-checking
1684 functions. A type-checking function has the following signature::
1686 def check_mytype(option, opt, value)
1688 where ``option`` is an :class:`Option` instance, ``opt`` is an option string
1689 (e.g., ``"-f"``), and ``value`` is the string from the command line that must be
1690 checked and converted to your desired type. ``check_mytype()`` should return an
1691 object of the hypothetical type ``mytype``. The value returned by a
1692 type-checking function will wind up in the OptionValues instance returned by
1693 :meth:`OptionParser.parse_args`, or be passed to a callback as the ``value``
1696 Your type-checking function should raise :exc:`OptionValueError` if it encounters any
1697 problems. :exc:`OptionValueError` takes a single string argument, which is passed
1698 as-is to :class:`OptionParser`'s :meth:`error` method, which in turn prepends the program
1699 name and the string ``"error:"`` and prints everything to stderr before
1700 terminating the process.
1702 Here's a silly example that demonstrates adding a ``complex`` option type to
1703 parse Python-style complex numbers on the command line. (This is even sillier
1704 than it used to be, because :mod:`optparse` 1.3 added built-in support for
1705 complex numbers, but never mind.)
1707 First, the necessary imports::
1709 from copy import copy
1710 from optparse import Option, OptionValueError
1712 You need to define your type-checker first, since it's referred to later (in the
1713 :attr:`TYPE_CHECKER` class attribute of your Option subclass)::
1715 def check_complex(option, opt, value):
1717 return complex(value)
1719 raise OptionValueError(
1720 "option %s: invalid complex value: %r" % (opt, value))
1722 Finally, the Option subclass::
1724 class MyOption (Option):
1725 TYPES = Option.TYPES + ("complex",)
1726 TYPE_CHECKER = copy(Option.TYPE_CHECKER)
1727 TYPE_CHECKER["complex"] = check_complex
1729 (If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
1730 up modifying the :attr:`TYPE_CHECKER` attribute of :mod:`optparse`'s Option
1731 class. This being Python, nothing stops you from doing that except good manners
1734 That's it! Now you can write a script that uses the new option type just like
1735 any other :mod:`optparse`\ -based script, except you have to instruct your
1736 OptionParser to use MyOption instead of Option::
1738 parser = OptionParser(option_class=MyOption)
1739 parser.add_option("-c", type="complex")
1741 Alternately, you can build your own option list and pass it to OptionParser; if
1742 you don't use :meth:`add_option` in the above way, you don't need to tell
1743 OptionParser which option class to use::
1745 option_list = [MyOption("-c", action="store", type="complex", dest="c")]
1746 parser = OptionParser(option_list=option_list)
1749 .. _optparse-adding-new-actions:
1754 Adding new actions is a bit trickier, because you have to understand that
1755 :mod:`optparse` has a couple of classifications for actions:
1758 actions that result in :mod:`optparse` storing a value to an attribute of the
1759 current OptionValues instance; these options require a :attr:`dest` attribute to
1760 be supplied to the Option constructor
1763 actions that take a value from the command line and expect it to be of a certain
1764 type; or rather, a string that can be converted to a certain type. These
1765 options require a :attr:`type` attribute to the Option constructor.
1767 These are overlapping sets: some default "store" actions are ``store``,
1768 ``store_const``, ``append``, and ``count``, while the default "typed" actions
1769 are ``store``, ``append``, and ``callback``.
1771 When you add an action, you need to categorize it by listing it in at least one
1772 of the following class attributes of Option (all are lists of strings):
1775 all actions must be listed in ACTIONS
1777 :attr:`STORE_ACTIONS`
1778 "store" actions are additionally listed here
1780 :attr:`TYPED_ACTIONS`
1781 "typed" actions are additionally listed here
1783 ``ALWAYS_TYPED_ACTIONS``
1784 actions that always take a type (i.e. whose options always take a value) are
1785 additionally listed here. The only effect of this is that :mod:`optparse`
1786 assigns the default type, ``string``, to options with no explicit type whose
1787 action is listed in ``ALWAYS_TYPED_ACTIONS``.
1789 In order to actually implement your new action, you must override Option's
1790 :meth:`take_action` method and add a case that recognizes your action.
1792 For example, let's add an ``extend`` action. This is similar to the standard
1793 ``append`` action, but instead of taking a single value from the command-line
1794 and appending it to an existing list, ``extend`` will take multiple values in a
1795 single comma-delimited string, and extend an existing list with them. That is,
1796 if ``"--names"`` is an ``extend`` option of type ``string``, the command line
1799 --names=foo,bar --names blah --names ding,dong
1801 would result in a list ::
1803 ["foo", "bar", "blah", "ding", "dong"]
1805 Again we define a subclass of Option::
1807 class MyOption (Option):
1809 ACTIONS = Option.ACTIONS + ("extend",)
1810 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
1811 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
1812 ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
1814 def take_action(self, action, dest, opt, value, values, parser):
1815 if action == "extend":
1816 lvalue = value.split(",")
1817 values.ensure_value(dest, []).extend(lvalue)
1820 self, action, dest, opt, value, values, parser)
1824 * ``extend`` both expects a value on the command-line and stores that value
1825 somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS`
1827 * to ensure that :mod:`optparse` assigns the default type of ``string`` to
1828 ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as
1831 * :meth:`MyOption.take_action` implements just this one new action, and passes
1832 control back to :meth:`Option.take_action` for the standard :mod:`optparse`
1835 * ``values`` is an instance of the optparse_parser.Values class, which
1836 provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
1837 essentially :func:`getattr` with a safety valve; it is called as ::
1839 values.ensure_value(attr, value)
1841 If the ``attr`` attribute of ``values`` doesn't exist or is None, then
1842 ensure_value() first sets it to ``value``, and then returns 'value. This is very
1843 handy for actions like ``extend``, ``append``, and ``count``, all of which
1844 accumulate data in a variable and expect that variable to be of a certain type
1845 (a list for the first two, an integer for the latter). Using
1846 :meth:`ensure_value` means that scripts using your action don't have to worry
1847 about setting a default value for the option destinations in question; they can
1848 just leave the default as None and :meth:`ensure_value` will take care of
1849 getting it right when it's needed.