1 :mod:`optparse` --- More powerful command line option parser

     2 ============================================================

     3 

     4 .. module:: optparse

     5    :synopsis: More convenient, flexible, and powerful command-line parsing library.

     6 .. moduleauthor:: Greg Ward <gward@python.net>

     7 

     8 

     9 .. versionadded:: 2.3

    10 

    11 .. sectionauthor:: Greg Ward <gward@python.net>

    12 

    13 

    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.

    20 

    21 Here's an example of using ``optparse`` in a simple script::

    22 

    23    from optparse import OptionParser

    24    [...]

    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")

    31 

    32    (options, args) = parser.parse_args()

    33 

    34 With these few lines of code, users of your script can now do the "usual thing"

    35 on the command-line, for example::

    36 

    37    <yourscript> --file=outfile -q

    38 

    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::

    47 

    48    <yourscript> -f outfile --quiet

    49    <yourscript> --quiet --file outfile

    50    <yourscript> -q -foutfile

    51    <yourscript> -qfoutfile

    52 

    53 Additionally, users can run one of  ::

    54 

    55    <yourscript> -h

    56    <yourscript> --help

    57 

    58 and ``optparse`` will print out a brief summary of your script's options::

    59 

    60    usage: <yourscript> [options]

    61 

    62    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

    66 

    67 where the value of *yourscript* is determined at runtime (normally from

    68 ``sys.argv[0]``).

    69 

    70 

    71 .. _optparse-background:

    72 

    73 Background

    74 ----------

    75 

    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.

    81 

    82 

    83 .. _optparse-terminology:

    84 

    85 Terminology

    86 ^^^^^^^^^^^

    87 

    88 argument

    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

    92    use the term "word".

    93 

    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

    97    ``sys.argv[1:]``".

    98 

    99 option

   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`.

   108 

   109    Some other option syntaxes that the world has seen include:

   110 

   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)

   113 

   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

   116      program)

   117 

   118    * a plus sign followed by a single letter, or a few letters, or a word, e.g.

   119      ``"+f"``, ``"+rgb"``

   120 

   121    * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,

   122      ``"/file"``

   123 

   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,

   127    and/or Windows.

   128 

   129 option argument

   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::

   133 

   134       -f foo

   135       --file foo

   136 

   137    or included in the same argument::

   138 

   139       -ffoo

   140       --file=foo

   141 

   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.

   148 

   149 positional argument

   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

   152    list.

   153 

   154 required option

   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`.

   161 

   162 For example, consider this hypothetical command-line::

   163 

   164    prog -v --report /tmp/report.txt foo bar

   165 

   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.

   169 

   170 

   171 .. _optparse-what-options-for:

   172 

   173 What are options for?

   174 ^^^^^^^^^^^^^^^^^^^^^

   175 

   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.)

   183 

   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.

   188 

   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::

   194 

   195    cp SOURCE DEST

   196    cp SOURCE ... DEST-DIR

   197 

   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

   203 directory.

   204 

   205 

   206 .. _optparse-what-positional-arguments-for:

   207 

   208 What are positional arguments for?

   209 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   210 

   211 Positional arguments are for those pieces of information that your program

   212 absolutely, positively requires to run.

   213 

   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.

   221 

   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.

   230 

   231 

   232 .. _optparse-tutorial:

   233 

   234 Tutorial

   235 --------

   236 

   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.

   240 

   241 First, you need to import the OptionParser class; then, early in the main

   242 program, create an OptionParser instance::

   243 

   244    from optparse import OptionParser

   245    [...]

   246    parser = OptionParser()

   247 

   248 Then you can start defining options.  The basic syntax is::

   249 

   250    parser.add_option(opt_str, ...,

   251                      attr=value, ...)

   252 

   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.

   256 

   257 Typically, each option will have one short option string and one long option

   258 string, e.g.::

   259 

   260    parser.add_option("-f", "--file", ...)

   261 

   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

   264 string overall.

   265 

   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.

   270 

   271 Once all of your options are defined, instruct :mod:`optparse` to parse your

   272 program's command line::

   273 

   274    (options, args) = parser.parse_args()

   275 

   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:]``.)

   278 

   279 :meth:`parse_args` returns two values:

   280 

   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

   284   option

   285 

   286 * ``args``, the list of positional arguments leftover after parsing options

   287 

   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.

   291 

   292 

   293 .. _optparse-understanding-option-actions:

   294 

   295 Understanding option actions

   296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   297 

   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``.

   304 

   305 If you don't specify an option action, :mod:`optparse` defaults to ``store``.

   306 

   307 

   308 .. _optparse-store-action:

   309 

   310 The store action

   311 ^^^^^^^^^^^^^^^^

   312 

   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.

   316 

   317 For example::

   318 

   319    parser.add_option("-f", "--file",

   320                      action="store", type="string", dest="filename")

   321 

   322 Now let's make up a fake command line and ask :mod:`optparse` to parse it::

   323 

   324    args = ["-f", "foo.txt"]

   325    (options, args) = parser.parse_args(args)

   326 

   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"``.

   330 

   331 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.

   332 Here's an option that expects an integer argument::

   333 

   334    parser.add_option("-n", type="int", dest="num")

   335 

   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``.

   338 

   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  ::

   342 

   343    (options, args) = parser.parse_args(["-n42"])

   344    print options.num

   345 

   346 will print ``"42"``.

   347 

   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

   350 be a lot shorter::

   351 

   352    parser.add_option("-f", "--file", dest="filename")

   353 

   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``.

   359 

   360 :mod:`optparse` also includes built-in ``long`` and ``complex`` types.  Adding

   361 types is covered in section :ref:`optparse-extending-optparse`.

   362 

   363 

   364 .. _optparse-handling-boolean-options:

   365 

   366 Handling boolean (flag) options

   367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   368 

   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"``::

   373 

   374    parser.add_option("-v", action="store_true", dest="verbose")

   375    parser.add_option("-q", action="store_false", dest="verbose")

   376 

   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---

   379 see below.)

   380 

   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``.

   384 

   385 

   386 .. _optparse-other-actions:

   387 

   388 Other actions

   389 ^^^^^^^^^^^^^

   390 

   391 Some other actions supported by :mod:`optparse` are:

   392 

   393 ``store_const``

   394    store a constant value

   395 

   396 ``append``

   397    append this option's argument to a list

   398 

   399 ``count``

   400    increment a counter by one

   401 

   402 ``callback``

   403    call a specified function

   404 

   405 These are covered in section :ref:`optparse-reference-guide`, Reference Guide

   406 and section :ref:`optparse-option-callbacks`.

   407 

   408 

   409 .. _optparse-default-values:

   410 

   411 Default values

   412 ^^^^^^^^^^^^^^

   413 

   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.

   420 

   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::

   423 

   424    parser.add_option("-v", action="store_true", dest="verbose", default=True)

   425    parser.add_option("-q", action="store_false", dest="verbose")

   426 

   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

   429 exactly equivalent::

   430 

   431    parser.add_option("-v", action="store_true", dest="verbose")

   432    parser.add_option("-q", action="store_false", dest="verbose", default=True)

   433 

   434 Consider this::

   435 

   436    parser.add_option("-v", action="store_true", dest="verbose", default=False)

   437    parser.add_option("-q", action="store_false", dest="verbose", default=True)

   438 

   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.

   441 

   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`::

   444 

   445    parser.set_defaults(verbose=True)

   446    parser.add_option(...)

   447    (options, args) = parser.parse_args()

   448 

   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

   451 values, not both.

   452 

   453 

   454 .. _optparse-generating-help:

   455 

   456 Generating help

   457 ^^^^^^^^^^^^^^^

   458 

   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::

   464 

   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]")

   479 

   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::

   483 

   484    usage: <yourscript> [options] arg1 arg2

   485 

   486    options:

   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

   491                            write output to FILE

   492      -m MODE, --mode=MODE  interaction mode: novice, intermediate, or

   493                            expert [default: intermediate]

   494 

   495 (If the help output is triggered by a help option, :mod:`optparse` exits after

   496 printing the help text.)

   497 

   498 There's a lot going on here to help :mod:`optparse` generate the best possible

   499 help message:

   500 

   501 * the script defines its own usage message::

   502 

   503      usage = "usage: %prog [options] arg1 arg2"

   504 

   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.

   508 

   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.

   512 

   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

   515   good.

   516 

   517 * options that take a value indicate this fact in their automatically-generated

   518   help message, e.g. for the "mode" option::

   519 

   520      -m MODE, --mode=MODE

   521 

   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::

   528 

   529      -f FILE, --filename=FILE

   530 

   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.

   536 

   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``.

   542 

   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.

   546 

   547 Continuing with the parser defined above, adding an

   548 :class:`OptionGroup` to a parser is easy::

   549 

   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)

   555 

   556 This would result in the following help output::

   557 

   558     usage:  [options] arg1 arg2

   559 

   560     options:

   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'

   566 			   [default], 'expert'

   567 

   568       Dangerous Options:

   569 	Caution: use of these options is at your own risk.  It is believed that

   570 	some of them bite.

   571 	-g                 Group option.

   572 

   573 .. _optparse-printing-version-string:

   574 

   575 Printing a version string

   576 ^^^^^^^^^^^^^^^^^^^^^^^^^

   577 

   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::

   581 

   582    parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

   583 

   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.

   589 

   590 For example, if your script is called ``/usr/bin/foo``::

   591 

   592    $ /usr/bin/foo --version

   593    foo 1.0

   594 

   595 

   596 .. _optparse-how-optparse-handles-errors:

   597 

   598 How :mod:`optparse` handles errors

   599 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   600 

   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.

   607 

   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

   614 condition::

   615 

   616    (options, args) = parser.parse_args()

   617    [...]

   618    if options.a and options.b:

   619        parser.error("options -a and -b are mutually exclusive")

   620 

   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

   623 error status 2.

   624 

   625 Consider the first example above, where the user passes ``"4x"`` to an option

   626 that takes an integer::

   627 

   628    $ /usr/bin/foo -n 4x

   629    usage: foo [options]

   630 

   631    foo: error: option -n: invalid integer value: '4x'

   632 

   633 Or, where the user fails to pass a value at all::

   634 

   635    $ /usr/bin/foo -n

   636    usage: foo [options]

   637 

   638    foo: error: -n option requires an argument

   639 

   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.

   643 

   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.

   647 

   648 

   649 .. _optparse-putting-it-all-together:

   650 

   651 Putting it all together

   652 ^^^^^^^^^^^^^^^^^^^^^^^

   653 

   654 Here's what :mod:`optparse`\ -based scripts usually look like::

   655 

   656    from optparse import OptionParser

   657    [...]

   658    def main():

   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")

   667        [...]

   668        (options, args) = parser.parse_args()

   669        if len(args) != 1:

   670            parser.error("incorrect number of arguments")

   671        if options.verbose:

   672            print "reading %s..." % options.filename

   673        [...]

   674 

   675    if __name__ == "__main__":

   676        main()

   677 

   678 

   679 .. _optparse-reference-guide:

   680 

   681 Reference Guide

   682 ---------------

   683 

   684 

   685 .. _optparse-creating-parser:

   686 

   687 Creating the parser

   688 ^^^^^^^^^^^^^^^^^^^

   689 

   690 The first step in using :mod:`optparse` is to create an OptionParser instance::

   691 

   692    parser = OptionParser(...)

   693 

   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.

   697 

   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``.

   704 

   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

   710       instead.

   711 

   712    ``option_class`` (default: optparse.Option)

   713       Class to use when adding options to the parser in :meth:`add_option`.

   714 

   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``.

   720 

   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`.

   724 

   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).

   729 

   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.

   734 

   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.

   738 

   739    ``prog``

   740       The string to use when expanding ``"%prog"`` in ``usage`` and ``version``

   741       instead of ``os.path.basename(sys.argv[0])``.

   742 

   743 

   744 

   745 .. _optparse-populating-parser:

   746 

   747 Populating the parser

   748 ^^^^^^^^^^^^^^^^^^^^^

   749 

   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:

   753 

   754 * pass it an Option instance (as returned by :func:`make_option`)

   755 

   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

   759 

   760 The other alternative is to pass a list of pre-constructed Option instances to

   761 the OptionParser constructor, as in::

   762 

   763    option_list = [

   764        make_option("-f", "--filename",

   765                    action="store", type="string", dest="filename"),

   766        make_option("-q", "--quiet",

   767                    action="store_false", dest="verbose"),

   768        ]

   769    parser = OptionParser(option_list=option_list)

   770 

   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.)

   775 

   776 

   777 .. _optparse-defining-options:

   778 

   779 Defining options

   780 ^^^^^^^^^^^^^^^^

   781 

   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.

   785 

   786 The canonical way to create an Option instance is with the :meth:`add_option`

   787 method of :class:`OptionParser`::

   788 

   789    parser.add_option(opt_str[, ...], attr=value, ...)

   790 

   791 To define an option with only a short option string::

   792 

   793    parser.add_option("-f", attr=value, ...)

   794 

   795 And to define an option with only a long option string::

   796 

   797    parser.add_option("--foo", attr=value, ...)

   798 

   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.

   804 

   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

   807 :mod:`optparse` are:

   808 

   809 ``store``

   810    store this option's argument (default)

   811 

   812 ``store_const``

   813    store a constant value

   814 

   815 ``store_true``

   816    store a true value

   817 

   818 ``store_false``

   819    store a false value

   820 

   821 ``append``

   822    append this option's argument to a list

   823 

   824 ``append_const``

   825    append a constant value to a list

   826 

   827 ``count``

   828    increment a counter by one

   829 

   830 ``callback``

   831    call a specified function

   832 

   833 :attr:`help`

   834    print a usage message including all options and the documentation for them

   835 

   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.)

   838 

   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.

   844 

   845 For example, when you call  ::

   846 

   847    parser.parse_args()

   848 

   849 one of the first things :mod:`optparse` does is create the ``options`` object::

   850 

   851    options = Values()

   852 

   853 If one of the options in this parser is defined with  ::

   854 

   855    parser.add_option("-f", "--file", action="store", type="string", dest="filename")

   856 

   857 and the command-line being parsed includes any of the following::

   858 

   859    -ffoo

   860    -f foo

   861    --file=foo

   862    --file foo

   863 

   864 then :mod:`optparse`, on seeing this option, will do the equivalent of  ::

   865 

   866    options.filename = "foo"

   867 

   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*

   870 options.

   871 

   872 

   873 .. _optparse-standard-option-actions:

   874 

   875 Standard option actions

   876 ^^^^^^^^^^^^^^^^^^^^^^^

   877 

   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.

   882 

   883 * ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]

   884 

   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.

   890 

   891   If ``choices`` is supplied (a list or tuple of strings), the type defaults to

   892   ``choice``.

   893 

   894   If :attr:`type` is not supplied, it defaults to ``string``.

   895 

   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``).

   900 

   901   Example::

   902 

   903      parser.add_option("-f")

   904      parser.add_option("-p", type="float", nargs=3, dest="point")

   905 

   906   As it parses the command line  ::

   907 

   908      -f foo.txt -p 1 -3.5 4 -fbar.txt

   909 

   910   :mod:`optparse` will set  ::

   911 

   912      options.f = "foo.txt"

   913      options.point = (1.0, -3.5, 4.0)

   914      options.f = "bar.txt"

   915 

   916 * ``store_const`` [required: ``const``; relevant: :attr:`dest`]

   917 

   918   The value ``const`` is stored in :attr:`dest`.

   919 

   920   Example::

   921 

   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")

   928 

   929   If ``"--noisy"`` is seen, :mod:`optparse` will set  ::

   930 

   931      options.verbose = 2

   932 

   933 * ``store_true`` [relevant: :attr:`dest`]

   934 

   935   A special case of ``store_const`` that stores a true value to :attr:`dest`.

   936 

   937 * ``store_false`` [relevant: :attr:`dest`]

   938 

   939   Like ``store_true``, but stores a false value.

   940 

   941   Example::

   942 

   943      parser.add_option("--clobber", action="store_true", dest="clobber")

   944      parser.add_option("--no-clobber", action="store_false", dest="clobber")

   945 

   946 * ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]

   947 

   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`.

   953 

   954   The defaults for :attr:`type` and :attr:`dest` are the same as for the ``store``

   955   action.

   956 

   957   Example::

   958 

   959      parser.add_option("-t", "--tracks", action="append", type="int")

   960 

   961   If ``"-t3"`` is seen on the command-line, :mod:`optparse` does the equivalent

   962   of::

   963 

   964      options.tracks = []

   965      options.tracks.append(int("3"))

   966 

   967   If, a little later on, ``"--tracks=4"`` is seen, it does::

   968 

   969      options.tracks.append(int("4"))

   970 

   971 * ``append_const`` [required: ``const``; relevant: :attr:`dest`]

   972 

   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.

   976 

   977 * ``count`` [relevant: :attr:`dest`]

   978 

   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.

   981 

   982   Example::

   983 

   984      parser.add_option("-v", action="count", dest="verbosity")

   985 

   986   The first time ``"-v"`` is seen on the command line, :mod:`optparse` does the

   987   equivalent of::

   988 

   989      options.verbosity = 0

   990      options.verbosity += 1

   991 

   992   Every subsequent occurrence of ``"-v"`` results in  ::

   993 

   994      options.verbosity += 1

   995 

   996 * ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``,

   997   ``callback_args``, ``callback_kwargs``]

   998 

   999   Call the function specified by ``callback``, which is called as  ::

  1000 

  1001      func(option, opt_str, value, parser, *args, **kwargs)

  1002 

  1003   See section :ref:`optparse-option-callbacks` for more detail.

  1004 

  1005 * :attr:`help`

  1006 

  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.

  1010 

  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``.

  1014 

  1015   :mod:`optparse` automatically adds a :attr:`help` option to all OptionParsers,

  1016   so you do not normally need to create one.

  1017 

  1018   Example::

  1019 

  1020      from optparse import OptionParser, SUPPRESS_HELP

  1021 

  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)

  1029 

  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"``)::

  1033 

  1034      usage: foo.py [options]

  1035 

  1036      options:

  1037        -h, --help        Show this help message and exit

  1038        -v                Be moderately verbose

  1039        --file=FILENAME   Input file to read data from

  1040 

  1041   After printing the help message, :mod:`optparse` terminates your process with

  1042   ``sys.exit(0)``.

  1043 

  1044 * ``version``

  1045 

  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

  1051   them when needed.

  1052 

  1053 

  1054 .. _optparse-option-attributes:

  1055 

  1056 Option attributes

  1057 ^^^^^^^^^^^^^^^^^

  1058 

  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`.

  1063 

  1064 * :attr:`action` (default: ``"store"``)

  1065 

  1066   Determines :mod:`optparse`'s behaviour when this option is seen on the command

  1067   line; the available options are documented above.

  1068 

  1069 * :attr:`type` (default: ``"string"``)

  1070 

  1071   The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the

  1072   available option types are documented below.

  1073 

  1074 * :attr:`dest` (default: derived from option strings)

  1075 

  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.

  1079 

  1080 * ``default`` (deprecated)

  1081 

  1082   The value to use for this option's destination if the option is not seen on the

  1083   command line.  Deprecated; use ``parser.set_defaults()`` instead.

  1084 

  1085 * ``nargs`` (default: 1)

  1086 

  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`.

  1089 

  1090 * ``const``

  1091 

  1092   For actions that store a constant value, the constant value to store.

  1093 

  1094 * ``choices``

  1095 

  1096   For options of type ``"choice"``, the list of strings the user may choose from.

  1097 

  1098 * ``callback``

  1099 

  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``.

  1103 

  1104 * ``callback_args``, ``callback_kwargs``

  1105 

  1106   Additional positional and keyword arguments to pass to ``callback`` after the

  1107   four standard callback arguments.

  1108 

  1109 * :attr:`help`

  1110 

  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``.

  1115 

  1116 * ``metavar`` (default: derived from option strings)

  1117 

  1118   Stand-in for the option argument(s) to use when printing help text. See section

  1119   :ref:`optparse-tutorial` for an example.

  1120 

  1121 

  1122 .. _optparse-standard-option-types:

  1123 

  1124 Standard option types

  1125 ^^^^^^^^^^^^^^^^^^^^^

  1126 

  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`.

  1130 

  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.

  1133 

  1134 Integer arguments (type ``int`` or ``long``) are parsed as follows:

  1135