1:mod:`optparse` --- Parser for command line options 2=================================================== 3 4.. module:: optparse 5 :synopsis: Command-line option parsing library. 6 :deprecated: 7 8.. moduleauthor:: Greg Ward <gward@python.net> 9.. sectionauthor:: Greg Ward <gward@python.net> 10 11**Source code:** :source:`Lib/optparse.py` 12 13.. deprecated:: 3.2 14 The :mod:`optparse` module is deprecated and will not be developed further; 15 development will continue with the :mod:`argparse` module. 16 17-------------- 18 19:mod:`optparse` is a more convenient, flexible, and powerful library for parsing 20command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a 21more declarative style of command-line parsing: you create an instance of 22:class:`OptionParser`, populate it with options, and parse the command 23line. :mod:`optparse` allows users to specify options in the conventional 24GNU/POSIX syntax, and additionally generates usage and help messages for you. 25 26Here's an example of using :mod:`optparse` in a simple script:: 27 28 from optparse import OptionParser 29 ... 30 parser = OptionParser() 31 parser.add_option("-f", "--file", dest="filename", 32 help="write report to FILE", metavar="FILE") 33 parser.add_option("-q", "--quiet", 34 action="store_false", dest="verbose", default=True, 35 help="don't print status messages to stdout") 36 37 (options, args) = parser.parse_args() 38 39With these few lines of code, users of your script can now do the "usual thing" 40on the command-line, for example:: 41 42 <yourscript> --file=outfile -q 43 44As it parses the command line, :mod:`optparse` sets attributes of the 45``options`` object returned by :meth:`parse_args` based on user-supplied 46command-line values. When :meth:`parse_args` returns from parsing this command 47line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be 48``False``. :mod:`optparse` supports both long and short options, allows short 49options to be merged together, and allows options to be associated with their 50arguments in a variety of ways. Thus, the following command lines are all 51equivalent to the above example:: 52 53 <yourscript> -f outfile --quiet 54 <yourscript> --quiet --file outfile 55 <yourscript> -q -foutfile 56 <yourscript> -qfoutfile 57 58Additionally, users can run one of the following :: 59 60 <yourscript> -h 61 <yourscript> --help 62 63and :mod:`optparse` will print out a brief summary of your script's options: 64 65.. code-block:: text 66 67 Usage: <yourscript> [options] 68 69 Options: 70 -h, --help show this help message and exit 71 -f FILE, --file=FILE write report to FILE 72 -q, --quiet don't print status messages to stdout 73 74where the value of *yourscript* is determined at runtime (normally from 75``sys.argv[0]``). 76 77 78.. _optparse-background: 79 80Background 81---------- 82 83:mod:`optparse` was explicitly designed to encourage the creation of programs 84with straightforward, conventional command-line interfaces. To that end, it 85supports only the most common command-line syntax and semantics conventionally 86used under Unix. If you are unfamiliar with these conventions, read this 87section to acquaint yourself with them. 88 89 90.. _optparse-terminology: 91 92Terminology 93^^^^^^^^^^^ 94 95argument 96 a string entered on the command-line, and passed by the shell to ``execl()`` 97 or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]`` 98 (``sys.argv[0]`` is the name of the program being executed). Unix shells 99 also use the term "word". 100 101 It is occasionally desirable to substitute an argument list other than 102 ``sys.argv[1:]``, so you should read "argument" as "an element of 103 ``sys.argv[1:]``, or of some other list provided as a substitute for 104 ``sys.argv[1:]``". 105 106option 107 an argument used to supply extra information to guide or customize the 108 execution of a program. There are many different syntaxes for options; the 109 traditional Unix syntax is a hyphen ("-") followed by a single letter, 110 e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple 111 options to be merged into a single argument, e.g. ``-x -F`` is equivalent 112 to ``-xF``. The GNU project introduced ``--`` followed by a series of 113 hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the 114 only two option syntaxes provided by :mod:`optparse`. 115 116 Some other option syntaxes that the world has seen include: 117 118 * a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same 119 as multiple options merged into a single argument) 120 121 * a hyphen followed by a whole word, e.g. ``-file`` (this is technically 122 equivalent to the previous syntax, but they aren't usually seen in the same 123 program) 124 125 * a plus sign followed by a single letter, or a few letters, or a word, e.g. 126 ``+f``, ``+rgb`` 127 128 * a slash followed by a letter, or a few letters, or a word, e.g. ``/f``, 129 ``/file`` 130 131 These option syntaxes are not supported by :mod:`optparse`, and they never 132 will be. This is deliberate: the first three are non-standard on any 133 environment, and the last only makes sense if you're exclusively targeting 134 VMS, MS-DOS, and/or Windows. 135 136option argument 137 an argument that follows an option, is closely associated with that option, 138 and is consumed from the argument list when that option is. With 139 :mod:`optparse`, option arguments may either be in a separate argument from 140 their option: 141 142 .. code-block:: text 143 144 -f foo 145 --file foo 146 147 or included in the same argument: 148 149 .. code-block:: text 150 151 -ffoo 152 --file=foo 153 154 Typically, a given option either takes an argument or it doesn't. Lots of 155 people want an "optional option arguments" feature, meaning that some options 156 will take an argument if they see it, and won't if they don't. This is 157 somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes 158 an optional argument and ``-b`` is another option entirely, how do we 159 interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not 160 support this feature. 161 162positional argument 163 something leftover in the argument list after options have been parsed, i.e. 164 after options and their arguments have been parsed and removed from the 165 argument list. 166 167required option 168 an option that must be supplied on the command-line; note that the phrase 169 "required option" is self-contradictory in English. :mod:`optparse` doesn't 170 prevent you from implementing required options, but doesn't give you much 171 help at it either. 172 173For example, consider this hypothetical command-line:: 174 175 prog -v --report report.txt foo bar 176 177``-v`` and ``--report`` are both options. Assuming that ``--report`` 178takes one argument, ``report.txt`` is an option argument. ``foo`` and 179``bar`` are positional arguments. 180 181 182.. _optparse-what-options-for: 183 184What are options for? 185^^^^^^^^^^^^^^^^^^^^^ 186 187Options are used to provide extra information to tune or customize the execution 188of a program. In case it wasn't clear, options are usually *optional*. A 189program should be able to run just fine with no options whatsoever. (Pick a 190random program from the Unix or GNU toolsets. Can it run without any options at 191all and still make sense? The main exceptions are ``find``, ``tar``, and 192``dd``\ ---all of which are mutant oddballs that have been rightly criticized 193for their non-standard syntax and confusing interfaces.) 194 195Lots of people want their programs to have "required options". Think about it. 196If it's required, then it's *not optional*! If there is a piece of information 197that your program absolutely requires in order to run successfully, that's what 198positional arguments are for. 199 200As an example of good command-line interface design, consider the humble ``cp`` 201utility, for copying files. It doesn't make much sense to try to copy files 202without supplying a destination and at least one source. Hence, ``cp`` fails if 203you run it with no arguments. However, it has a flexible, useful syntax that 204does not require any options at all:: 205 206 cp SOURCE DEST 207 cp SOURCE ... DEST-DIR 208 209You can get pretty far with just that. Most ``cp`` implementations provide a 210bunch of options to tweak exactly how the files are copied: you can preserve 211mode and modification time, avoid following symlinks, ask before clobbering 212existing files, etc. But none of this distracts from the core mission of 213``cp``, which is to copy either one file to another, or several files to another 214directory. 215 216 217.. _optparse-what-positional-arguments-for: 218 219What are positional arguments for? 220^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 221 222Positional arguments are for those pieces of information that your program 223absolutely, positively requires to run. 224 225A good user interface should have as few absolute requirements as possible. If 226your program requires 17 distinct pieces of information in order to run 227successfully, it doesn't much matter *how* you get that information from the 228user---most people will give up and walk away before they successfully run the 229program. This applies whether the user interface is a command-line, a 230configuration file, or a GUI: if you make that many demands on your users, most 231of them will simply give up. 232 233In short, try to minimize the amount of information that users are absolutely 234required to supply---use sensible defaults whenever possible. Of course, you 235also want to make your programs reasonably flexible. That's what options are 236for. Again, it doesn't matter if they are entries in a config file, widgets in 237the "Preferences" dialog of a GUI, or command-line options---the more options 238you implement, the more flexible your program is, and the more complicated its 239implementation becomes. Too much flexibility has drawbacks as well, of course; 240too many options can overwhelm users and make your code much harder to maintain. 241 242 243.. _optparse-tutorial: 244 245Tutorial 246-------- 247 248While :mod:`optparse` is quite flexible and powerful, it's also straightforward 249to use in most cases. This section covers the code patterns that are common to 250any :mod:`optparse`\ -based program. 251 252First, you need to import the OptionParser class; then, early in the main 253program, create an OptionParser instance:: 254 255 from optparse import OptionParser 256 ... 257 parser = OptionParser() 258 259Then you can start defining options. The basic syntax is:: 260 261 parser.add_option(opt_str, ..., 262 attr=value, ...) 263 264Each option has one or more option strings, such as ``-f`` or ``--file``, 265and several option attributes that tell :mod:`optparse` what to expect and what 266to do when it encounters that option on the command line. 267 268Typically, each option will have one short option string and one long option 269string, e.g.:: 270 271 parser.add_option("-f", "--file", ...) 272 273You're free to define as many short option strings and as many long option 274strings as you like (including zero), as long as there is at least one option 275string overall. 276 277The option strings passed to :meth:`OptionParser.add_option` are effectively 278labels for the 279option defined by that call. For brevity, we will frequently refer to 280*encountering an option* on the command line; in reality, :mod:`optparse` 281encounters *option strings* and looks up options from them. 282 283Once all of your options are defined, instruct :mod:`optparse` to parse your 284program's command line:: 285 286 (options, args) = parser.parse_args() 287 288(If you like, you can pass a custom argument list to :meth:`parse_args`, but 289that's rarely necessary: by default it uses ``sys.argv[1:]``.) 290 291:meth:`parse_args` returns two values: 292 293* ``options``, an object containing values for all of your options---e.g. if 294 ``--file`` takes a single string argument, then ``options.file`` will be the 295 filename supplied by the user, or ``None`` if the user did not supply that 296 option 297 298* ``args``, the list of positional arguments leftover after parsing options 299 300This tutorial section only covers the four most important option attributes: 301:attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest` 302(destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the 303most fundamental. 304 305 306.. _optparse-understanding-option-actions: 307 308Understanding option actions 309^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 310 311Actions tell :mod:`optparse` what to do when it encounters an option on the 312command line. There is a fixed set of actions hard-coded into :mod:`optparse`; 313adding new actions is an advanced topic covered in section 314:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store 315a value in some variable---for example, take a string from the command line and 316store it in an attribute of ``options``. 317 318If you don't specify an option action, :mod:`optparse` defaults to ``store``. 319 320 321.. _optparse-store-action: 322 323The store action 324^^^^^^^^^^^^^^^^ 325 326The most common option action is ``store``, which tells :mod:`optparse` to take 327the next argument (or the remainder of the current argument), ensure that it is 328of the correct type, and store it to your chosen destination. 329 330For example:: 331 332 parser.add_option("-f", "--file", 333 action="store", type="string", dest="filename") 334 335Now let's make up a fake command line and ask :mod:`optparse` to parse it:: 336 337 args = ["-f", "foo.txt"] 338 (options, args) = parser.parse_args(args) 339 340When :mod:`optparse` sees the option string ``-f``, it consumes the next 341argument, ``foo.txt``, and stores it in ``options.filename``. So, after this 342call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``. 343 344Some other option types supported by :mod:`optparse` are ``int`` and ``float``. 345Here's an option that expects an integer argument:: 346 347 parser.add_option("-n", type="int", dest="num") 348 349Note that this option has no long option string, which is perfectly acceptable. 350Also, there's no explicit action, since the default is ``store``. 351 352Let's parse another fake command-line. This time, we'll jam the option argument 353right up against the option: since ``-n42`` (one argument) is equivalent to 354``-n 42`` (two arguments), the code :: 355 356 (options, args) = parser.parse_args(["-n42"]) 357 print(options.num) 358 359will print ``42``. 360 361If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with 362the fact that the default action is ``store``, that means our first example can 363be a lot shorter:: 364 365 parser.add_option("-f", "--file", dest="filename") 366 367If you don't supply a destination, :mod:`optparse` figures out a sensible 368default from the option strings: if the first long option string is 369``--foo-bar``, then the default destination is ``foo_bar``. If there are no 370long option strings, :mod:`optparse` looks at the first short option string: the 371default destination for ``-f`` is ``f``. 372 373:mod:`optparse` also includes the built-in ``complex`` type. Adding 374types is covered in section :ref:`optparse-extending-optparse`. 375 376 377.. _optparse-handling-boolean-options: 378 379Handling boolean (flag) options 380^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 381 382Flag options---set a variable to true or false when a particular option is 383seen---are quite common. :mod:`optparse` supports them with two separate actions, 384``store_true`` and ``store_false``. For example, you might have a ``verbose`` 385flag that is turned on with ``-v`` and off with ``-q``:: 386 387 parser.add_option("-v", action="store_true", dest="verbose") 388 parser.add_option("-q", action="store_false", dest="verbose") 389 390Here we have two different options with the same destination, which is perfectly 391OK. (It just means you have to be a bit careful when setting default 392values---see below.) 393 394When :mod:`optparse` encounters ``-v`` on the command line, it sets 395``options.verbose`` to ``True``; when it encounters ``-q``, 396``options.verbose`` is set to ``False``. 397 398 399.. _optparse-other-actions: 400 401Other actions 402^^^^^^^^^^^^^ 403 404Some other actions supported by :mod:`optparse` are: 405 406``"store_const"`` 407 store a constant value 408 409``"append"`` 410 append this option's argument to a list 411 412``"count"`` 413 increment a counter by one 414 415``"callback"`` 416 call a specified function 417 418These are covered in section :ref:`optparse-reference-guide`, 419and section :ref:`optparse-option-callbacks`. 420 421 422.. _optparse-default-values: 423 424Default values 425^^^^^^^^^^^^^^ 426 427All of the above examples involve setting some variable (the "destination") when 428certain command-line options are seen. What happens if those options are never 429seen? Since we didn't supply any defaults, they are all set to ``None``. This 430is usually fine, but sometimes you want more control. :mod:`optparse` lets you 431supply a default value for each destination, which is assigned before the 432command line is parsed. 433 434First, consider the verbose/quiet example. If we want :mod:`optparse` to set 435``verbose`` to ``True`` unless ``-q`` is seen, then we can do this:: 436 437 parser.add_option("-v", action="store_true", dest="verbose", default=True) 438 parser.add_option("-q", action="store_false", dest="verbose") 439 440Since default values apply to the *destination* rather than to any particular 441option, and these two options happen to have the same destination, this is 442exactly equivalent:: 443 444 parser.add_option("-v", action="store_true", dest="verbose") 445 parser.add_option("-q", action="store_false", dest="verbose", default=True) 446 447Consider this:: 448 449 parser.add_option("-v", action="store_true", dest="verbose", default=False) 450 parser.add_option("-q", action="store_false", dest="verbose", default=True) 451 452Again, the default value for ``verbose`` will be ``True``: the last default 453value supplied for any particular destination is the one that counts. 454 455A clearer way to specify default values is the :meth:`set_defaults` method of 456OptionParser, which you can call at any time before calling :meth:`parse_args`:: 457 458 parser.set_defaults(verbose=True) 459 parser.add_option(...) 460 (options, args) = parser.parse_args() 461 462As before, the last value specified for a given option destination is the one 463that counts. For clarity, try to use one method or the other of setting default 464values, not both. 465 466 467.. _optparse-generating-help: 468 469Generating help 470^^^^^^^^^^^^^^^ 471 472:mod:`optparse`'s ability to generate help and usage text automatically is 473useful for creating user-friendly command-line interfaces. All you have to do 474is supply a :attr:`~Option.help` value for each option, and optionally a short 475usage message for your whole program. Here's an OptionParser populated with 476user-friendly (documented) options:: 477 478 usage = "usage: %prog [options] arg1 arg2" 479 parser = OptionParser(usage=usage) 480 parser.add_option("-v", "--verbose", 481 action="store_true", dest="verbose", default=True, 482 help="make lots of noise [default]") 483 parser.add_option("-q", "--quiet", 484 action="store_false", dest="verbose", 485 help="be vewwy quiet (I'm hunting wabbits)") 486 parser.add_option("-f", "--filename", 487 metavar="FILE", help="write output to FILE") 488 parser.add_option("-m", "--mode", 489 default="intermediate", 490 help="interaction mode: novice, intermediate, " 491 "or expert [default: %default]") 492 493If :mod:`optparse` encounters either ``-h`` or ``--help`` on the 494command-line, or if you just call :meth:`parser.print_help`, it prints the 495following to standard output: 496 497.. code-block:: text 498 499 Usage: <yourscript> [options] arg1 arg2 500 501 Options: 502 -h, --help show this help message and exit 503 -v, --verbose make lots of noise [default] 504 -q, --quiet be vewwy quiet (I'm hunting wabbits) 505 -f FILE, --filename=FILE 506 write output to FILE 507 -m MODE, --mode=MODE interaction mode: novice, intermediate, or 508 expert [default: intermediate] 509 510(If the help output is triggered by a help option, :mod:`optparse` exits after 511printing the help text.) 512 513There's a lot going on here to help :mod:`optparse` generate the best possible 514help message: 515 516* the script defines its own usage message:: 517 518 usage = "usage: %prog [options] arg1 arg2" 519 520 :mod:`optparse` expands ``%prog`` in the usage string to the name of the 521 current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string 522 is then printed before the detailed option help. 523 524 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible 525 default: ``"Usage: %prog [options]"``, which is fine if your script doesn't 526 take any positional arguments. 527 528* every option defines a help string, and doesn't worry about 529 line-wrapping---\ :mod:`optparse` takes care of wrapping lines and making 530 the help output look good. 531 532* options that take a value indicate this fact in their automatically-generated 533 help message, e.g. for the "mode" option:: 534 535 -m MODE, --mode=MODE 536 537 Here, "MODE" is called the meta-variable: it stands for the argument that the 538 user is expected to supply to ``-m``/``--mode``. By default, 539 :mod:`optparse` converts the destination variable name to uppercase and uses 540 that for the meta-variable. Sometimes, that's not what you want---for 541 example, the ``--filename`` option explicitly sets ``metavar="FILE"``, 542 resulting in this automatically-generated option description:: 543 544 -f FILE, --filename=FILE 545 546 This is important for more than just saving space, though: the manually 547 written help text uses the meta-variable ``FILE`` to clue the user in that 548 there's a connection between the semi-formal syntax ``-f FILE`` and the informal 549 semantic description "write output to FILE". This is a simple but effective 550 way to make your help text a lot clearer and more useful for end users. 551 552* options that have a default value can include ``%default`` in the help 553 string---\ :mod:`optparse` will replace it with :func:`str` of the option's 554 default value. If an option has no default value (or the default value is 555 ``None``), ``%default`` expands to ``none``. 556 557Grouping Options 558++++++++++++++++ 559 560When dealing with many options, it is convenient to group these options for 561better help output. An :class:`OptionParser` can contain several option groups, 562each of which can contain several options. 563 564An option group is obtained using the class :class:`OptionGroup`: 565 566.. class:: OptionGroup(parser, title, description=None) 567 568 where 569 570 * parser is the :class:`OptionParser` instance the group will be inserted in 571 to 572 * title is the group title 573 * description, optional, is a long description of the group 574 575:class:`OptionGroup` inherits from :class:`OptionContainer` (like 576:class:`OptionParser`) and so the :meth:`add_option` method can be used to add 577an option to the group. 578 579Once all the options are declared, using the :class:`OptionParser` method 580:meth:`add_option_group` the group is added to the previously defined parser. 581 582Continuing with the parser defined in the previous section, adding an 583:class:`OptionGroup` to a parser is easy:: 584 585 group = OptionGroup(parser, "Dangerous Options", 586 "Caution: use these options at your own risk. " 587 "It is believed that some of them bite.") 588 group.add_option("-g", action="store_true", help="Group option.") 589 parser.add_option_group(group) 590 591This would result in the following help output: 592 593.. code-block:: text 594 595 Usage: <yourscript> [options] arg1 arg2 596 597 Options: 598 -h, --help show this help message and exit 599 -v, --verbose make lots of noise [default] 600 -q, --quiet be vewwy quiet (I'm hunting wabbits) 601 -f FILE, --filename=FILE 602 write output to FILE 603 -m MODE, --mode=MODE interaction mode: novice, intermediate, or 604 expert [default: intermediate] 605 606 Dangerous Options: 607 Caution: use these options at your own risk. It is believed that some 608 of them bite. 609 610 -g Group option. 611 612A bit more complete example might involve using more than one group: still 613extending the previous example:: 614 615 group = OptionGroup(parser, "Dangerous Options", 616 "Caution: use these options at your own risk. " 617 "It is believed that some of them bite.") 618 group.add_option("-g", action="store_true", help="Group option.") 619 parser.add_option_group(group) 620 621 group = OptionGroup(parser, "Debug Options") 622 group.add_option("-d", "--debug", action="store_true", 623 help="Print debug information") 624 group.add_option("-s", "--sql", action="store_true", 625 help="Print all SQL statements executed") 626 group.add_option("-e", action="store_true", help="Print every action done") 627 parser.add_option_group(group) 628 629that results in the following output: 630 631.. code-block:: text 632 633 Usage: <yourscript> [options] arg1 arg2 634 635 Options: 636 -h, --help show this help message and exit 637 -v, --verbose make lots of noise [default] 638 -q, --quiet be vewwy quiet (I'm hunting wabbits) 639 -f FILE, --filename=FILE 640 write output to FILE 641 -m MODE, --mode=MODE interaction mode: novice, intermediate, or expert 642 [default: intermediate] 643 644 Dangerous Options: 645 Caution: use these options at your own risk. It is believed that some 646 of them bite. 647 648 -g Group option. 649 650 Debug Options: 651 -d, --debug Print debug information 652 -s, --sql Print all SQL statements executed 653 -e Print every action done 654 655Another interesting method, in particular when working programmatically with 656option groups is: 657 658.. method:: OptionParser.get_option_group(opt_str) 659 660 Return the :class:`OptionGroup` to which the short or long option 661 string *opt_str* (e.g. ``'-o'`` or ``'--option'``) belongs. If 662 there's no such :class:`OptionGroup`, return ``None``. 663 664.. _optparse-printing-version-string: 665 666Printing a version string 667^^^^^^^^^^^^^^^^^^^^^^^^^ 668 669Similar to the brief usage string, :mod:`optparse` can also print a version 670string for your program. You have to supply the string as the ``version`` 671argument to OptionParser:: 672 673 parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") 674 675``%prog`` is expanded just like it is in ``usage``. Apart from that, 676``version`` can contain anything you like. When you supply it, :mod:`optparse` 677automatically adds a ``--version`` option to your parser. If it encounters 678this option on the command line, it expands your ``version`` string (by 679replacing ``%prog``), prints it to stdout, and exits. 680 681For example, if your script is called ``/usr/bin/foo``: 682 683.. code-block:: shell-session 684 685 $ /usr/bin/foo --version 686 foo 1.0 687 688The following two methods can be used to print and get the ``version`` string: 689 690.. method:: OptionParser.print_version(file=None) 691 692 Print the version message for the current program (``self.version``) to 693 *file* (default stdout). As with :meth:`print_usage`, any occurrence 694 of ``%prog`` in ``self.version`` is replaced with the name of the current 695 program. Does nothing if ``self.version`` is empty or undefined. 696 697.. method:: OptionParser.get_version() 698 699 Same as :meth:`print_version` but returns the version string instead of 700 printing it. 701 702 703.. _optparse-how-optparse-handles-errors: 704 705How :mod:`optparse` handles errors 706^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 707 708There are two broad classes of errors that :mod:`optparse` has to worry about: 709programmer errors and user errors. Programmer errors are usually erroneous 710calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown 711option attributes, missing option attributes, etc. These are dealt with in the 712usual way: raise an exception (either :exc:`optparse.OptionError` or 713:exc:`TypeError`) and let the program crash. 714 715Handling user errors is much more important, since they are guaranteed to happen 716no matter how stable your code is. :mod:`optparse` can automatically detect 717some user errors, such as bad option arguments (passing ``-n 4x`` where 718``-n`` takes an integer argument), missing arguments (``-n`` at the end 719of the command line, where ``-n`` takes an argument of any type). Also, 720you can call :func:`OptionParser.error` to signal an application-defined error 721condition:: 722 723 (options, args) = parser.parse_args() 724 ... 725 if options.a and options.b: 726 parser.error("options -a and -b are mutually exclusive") 727 728In either case, :mod:`optparse` handles the error the same way: it prints the 729program's usage message and an error message to standard error and exits with 730error status 2. 731 732Consider the first example above, where the user passes ``4x`` to an option 733that takes an integer: 734 735.. code-block:: shell-session 736 737 $ /usr/bin/foo -n 4x 738 Usage: foo [options] 739 740 foo: error: option -n: invalid integer value: '4x' 741 742Or, where the user fails to pass a value at all: 743 744.. code-block:: shell-session 745 746 $ /usr/bin/foo -n 747 Usage: foo [options] 748 749 foo: error: -n option requires an argument 750 751:mod:`optparse`\ -generated error messages take care always to mention the 752option involved in the error; be sure to do the same when calling 753:func:`OptionParser.error` from your application code. 754 755If :mod:`optparse`'s default error-handling behaviour does not suit your needs, 756you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit` 757and/or :meth:`~OptionParser.error` methods. 758 759 760.. _optparse-putting-it-all-together: 761 762Putting it all together 763^^^^^^^^^^^^^^^^^^^^^^^ 764 765Here's what :mod:`optparse`\ -based scripts usually look like:: 766 767 from optparse import OptionParser 768 ... 769 def main(): 770 usage = "usage: %prog [options] arg" 771 parser = OptionParser(usage) 772 parser.add_option("-f", "--file", dest="filename", 773 help="read data from FILENAME") 774 parser.add_option("-v", "--verbose", 775 action="store_true", dest="verbose") 776 parser.add_option("-q", "--quiet", 777 action="store_false", dest="verbose") 778 ... 779 (options, args) = parser.parse_args() 780 if len(args) != 1: 781 parser.error("incorrect number of arguments") 782 if options.verbose: 783 print("reading %s..." % options.filename) 784 ... 785 786 if __name__ == "__main__": 787 main() 788 789 790.. _optparse-reference-guide: 791 792Reference Guide 793--------------- 794 795 796.. _optparse-creating-parser: 797 798Creating the parser 799^^^^^^^^^^^^^^^^^^^ 800 801The first step in using :mod:`optparse` is to create an OptionParser instance. 802 803.. class:: OptionParser(...) 804 805 The OptionParser constructor has no required arguments, but a number of 806 optional keyword arguments. You should always pass them as keyword 807 arguments, i.e. do not rely on the order in which the arguments are declared. 808 809 ``usage`` (default: ``"%prog [options]"``) 810 The usage summary to print when your program is run incorrectly or with a 811 help option. When :mod:`optparse` prints the usage string, it expands 812 ``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you 813 passed that keyword argument). To suppress a usage message, pass the 814 special value :data:`optparse.SUPPRESS_USAGE`. 815 816 ``option_list`` (default: ``[]``) 817 A list of Option objects to populate the parser with. The options in 818 ``option_list`` are added after any options in ``standard_option_list`` (a 819 class attribute that may be set by OptionParser subclasses), but before 820 any version or help options. Deprecated; use :meth:`add_option` after 821 creating the parser instead. 822 823 ``option_class`` (default: optparse.Option) 824 Class to use when adding options to the parser in :meth:`add_option`. 825 826 ``version`` (default: ``None``) 827 A version string to print when the user supplies a version option. If you 828 supply a true value for ``version``, :mod:`optparse` automatically adds a 829 version option with the single option string ``--version``. The 830 substring ``%prog`` is expanded the same as for ``usage``. 831 832 ``conflict_handler`` (default: ``"error"``) 833 Specifies what to do when options with conflicting option strings are 834 added to the parser; see section 835 :ref:`optparse-conflicts-between-options`. 836 837 ``description`` (default: ``None``) 838 A paragraph of text giving a brief overview of your program. 839 :mod:`optparse` reformats this paragraph to fit the current terminal width 840 and prints it when the user requests help (after ``usage``, but before the 841 list of options). 842 843 ``formatter`` (default: a new :class:`IndentedHelpFormatter`) 844 An instance of optparse.HelpFormatter that will be used for printing help 845 text. :mod:`optparse` provides two concrete classes for this purpose: 846 IndentedHelpFormatter and TitledHelpFormatter. 847 848 ``add_help_option`` (default: ``True``) 849 If true, :mod:`optparse` will add a help option (with option strings ``-h`` 850 and ``--help``) to the parser. 851 852 ``prog`` 853 The string to use when expanding ``%prog`` in ``usage`` and ``version`` 854 instead of ``os.path.basename(sys.argv[0])``. 855 856 ``epilog`` (default: ``None``) 857 A paragraph of help text to print after the option help. 858 859.. _optparse-populating-parser: 860 861Populating the parser 862^^^^^^^^^^^^^^^^^^^^^ 863 864There are several ways to populate the parser with options. The preferred way 865is by using :meth:`OptionParser.add_option`, as shown in section 866:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways: 867 868* pass it an Option instance (as returned by :func:`make_option`) 869 870* pass it any combination of positional and keyword arguments that are 871 acceptable to :func:`make_option` (i.e., to the Option constructor), and it 872 will create the Option instance for you 873 874The other alternative is to pass a list of pre-constructed Option instances to 875the OptionParser constructor, as in:: 876 877 option_list = [ 878 make_option("-f", "--filename", 879 action="store", type="string", dest="filename"), 880 make_option("-q", "--quiet", 881 action="store_false", dest="verbose"), 882 ] 883 parser = OptionParser(option_list=option_list) 884 885(:func:`make_option` is a factory function for creating Option instances; 886currently it is an alias for the Option constructor. A future version of 887:mod:`optparse` may split Option into several classes, and :func:`make_option` 888will pick the right class to instantiate. Do not instantiate Option directly.) 889 890 891.. _optparse-defining-options: 892 893Defining options 894^^^^^^^^^^^^^^^^ 895 896Each Option instance represents a set of synonymous command-line option strings, 897e.g. ``-f`` and ``--file``. You can specify any number of short or 898long option strings, but you must specify at least one overall option string. 899 900The canonical way to create an :class:`Option` instance is with the 901:meth:`add_option` method of :class:`OptionParser`. 902 903.. method:: OptionParser.add_option(option) 904 OptionParser.add_option(*opt_str, attr=value, ...) 905 906 To define an option with only a short option string:: 907 908 parser.add_option("-f", attr=value, ...) 909 910 And to define an option with only a long option string:: 911 912 parser.add_option("--foo", attr=value, ...) 913 914 The keyword arguments define attributes of the new Option object. The most 915 important option attribute is :attr:`~Option.action`, and it largely 916 determines which other attributes are relevant or required. If you pass 917 irrelevant option attributes, or fail to pass required ones, :mod:`optparse` 918 raises an :exc:`OptionError` exception explaining your mistake. 919 920 An option's *action* determines what :mod:`optparse` does when it encounters 921 this option on the command-line. The standard option actions hard-coded into 922 :mod:`optparse` are: 923 924 ``"store"`` 925 store this option's argument (default) 926 927 ``"store_const"`` 928 store a constant value 929 930 ``"store_true"`` 931 store ``True`` 932 933 ``"store_false"`` 934 store ``False`` 935 936 ``"append"`` 937 append this option's argument to a list 938 939 ``"append_const"`` 940 append a constant value to a list 941 942 ``"count"`` 943 increment a counter by one 944 945 ``"callback"`` 946 call a specified function 947 948 ``"help"`` 949 print a usage message including all options and the documentation for them 950 951 (If you don't supply an action, the default is ``"store"``. For this action, 952 you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option 953 attributes; see :ref:`optparse-standard-option-actions`.) 954 955As you can see, most actions involve storing or updating a value somewhere. 956:mod:`optparse` always creates a special object for this, conventionally called 957``options`` (it happens to be an instance of :class:`optparse.Values`). Option 958arguments (and various other values) are stored as attributes of this object, 959according to the :attr:`~Option.dest` (destination) option attribute. 960 961For example, when you call :: 962 963 parser.parse_args() 964 965one of the first things :mod:`optparse` does is create the ``options`` object:: 966 967 options = Values() 968 969If one of the options in this parser is defined with :: 970 971 parser.add_option("-f", "--file", action="store", type="string", dest="filename") 972 973and the command-line being parsed includes any of the following:: 974 975 -ffoo 976 -f foo 977 --file=foo 978 --file foo 979 980then :mod:`optparse`, on seeing this option, will do the equivalent of :: 981 982 options.filename = "foo" 983 984The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost 985as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only 986one that makes sense for *all* options. 987 988 989.. _optparse-option-attributes: 990 991Option attributes 992^^^^^^^^^^^^^^^^^ 993 994The following option attributes may be passed as keyword arguments to 995:meth:`OptionParser.add_option`. If you pass an option attribute that is not 996relevant to a particular option, or fail to pass a required option attribute, 997:mod:`optparse` raises :exc:`OptionError`. 998 999.. attribute:: Option.action 1000 1001 (default: ``"store"``) 1002 1003 Determines :mod:`optparse`'s behaviour when this option is seen on the 1004 command line; the available options are documented :ref:`here 1005 <optparse-standard-option-actions>`. 1006 1007.. attribute:: Option.type 1008 1009 (default: ``"string"``) 1010 1011 The argument type expected by this option (e.g., ``"string"`` or ``"int"``); 1012 the available option types are documented :ref:`here 1013 <optparse-standard-option-types>`. 1014 1015.. attribute:: Option.dest 1016 1017 (default: derived from option strings) 1018 1019 If the option's action implies writing or modifying a value somewhere, this 1020 tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an 1021 attribute of the ``options`` object that :mod:`optparse` builds as it parses 1022 the command line. 1023 1024.. attribute:: Option.default 1025 1026 The value to use for this option's destination if the option is not seen on 1027 the command line. See also :meth:`OptionParser.set_defaults`. 1028 1029.. attribute:: Option.nargs 1030 1031 (default: 1) 1032 1033 How many arguments of type :attr:`~Option.type` should be consumed when this 1034 option is seen. If > 1, :mod:`optparse` will store a tuple of values to 1035 :attr:`~Option.dest`. 1036 1037.. attribute:: Option.const 1038 1039 For actions that store a constant value, the constant value to store. 1040 1041.. attribute:: Option.choices 1042 1043 For options of type ``"choice"``, the list of strings the user may choose 1044 from. 1045 1046.. attribute:: Option.callback 1047 1048 For options with action ``"callback"``, the callable to call when this option 1049 is seen. See section :ref:`optparse-option-callbacks` for detail on the 1050 arguments passed to the callable. 1051 1052.. attribute:: Option.callback_args 1053 Option.callback_kwargs 1054 1055 Additional positional and keyword arguments to pass to ``callback`` after the 1056 four standard callback arguments. 1057 1058.. attribute:: Option.help 1059 1060 Help text to print for this option when listing all available options after 1061 the user supplies a :attr:`~Option.help` option (such as ``--help``). If 1062 no help text is supplied, the option will be listed without help text. To 1063 hide this option, use the special value :data:`optparse.SUPPRESS_HELP`. 1064 1065.. attribute:: Option.metavar 1066 1067 (default: derived from option strings) 1068 1069 Stand-in for the option argument(s) to use when printing help text. See 1070 section :ref:`optparse-tutorial` for an example. 1071 1072 1073.. _optparse-standard-option-actions: 1074 1075Standard option actions 1076^^^^^^^^^^^^^^^^^^^^^^^ 1077 1078The various option actions all have slightly different requirements and effects. 1079Most actions have several relevant option attributes which you may specify to 1080guide :mod:`optparse`'s behaviour; a few have required attributes, which you 1081must specify for any option using that action. 1082 1083* ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`, 1084 :attr:`~Option.nargs`, :attr:`~Option.choices`] 1085 1086 The option must be followed by an argument, which is converted to a value 1087 according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If 1088 :attr:`~Option.nargs` > 1, multiple arguments will be consumed from the 1089 command line; all will be converted according to :attr:`~Option.type` and 1090 stored to :attr:`~Option.dest` as a tuple. See the 1091 :ref:`optparse-standard-option-types` section. 1092 1093 If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type 1094 defaults to ``"choice"``. 1095 1096 If :attr:`~Option.type` is not supplied, it defaults to ``"string"``. 1097 1098 If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination 1099 from the first long option string (e.g., ``--foo-bar`` implies 1100 ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a 1101 destination from the first short option string (e.g., ``-f`` implies ``f``). 1102 1103 Example:: 1104 1105 parser.add_option("-f") 1106 parser.add_option("-p", type="float", nargs=3, dest="point") 1107 1108 As it parses the command line :: 1109 1110 -f foo.txt -p 1 -3.5 4 -fbar.txt 1111 1112 :mod:`optparse` will set :: 1113 1114 options.f = "foo.txt" 1115 options.point = (1.0, -3.5, 4.0) 1116 options.f = "bar.txt" 1117 1118* ``"store_const"`` [required: :attr:`~Option.const`; relevant: 1119 :attr:`~Option.dest`] 1120 1121 The value :attr:`~Option.const` is stored in :attr:`~Option.dest`. 1122 1123 Example:: 1124 1125 parser.add_option("-q", "--quiet", 1126 action="store_const", const=0, dest="verbose") 1127 parser.add_option("-v", "--verbose", 1128 action="store_const", const=1, dest="verbose") 1129 parser.add_option("--noisy", 1130 action="store_const", const=2, dest="verbose") 1131 1132 If ``--noisy`` is seen, :mod:`optparse` will set :: 1133 1134 options.verbose = 2 1135 1136* ``"store_true"`` [relevant: :attr:`~Option.dest`] 1137 1138 A special case of ``"store_const"`` that stores ``True`` to 1139 :attr:`~Option.dest`. 1140 1141* ``"store_false"`` [relevant: :attr:`~Option.dest`] 1142 1143 Like ``"store_true"``, but stores ``False``. 1144 1145 Example:: 1146 1147 parser.add_option("--clobber", action="store_true", dest="clobber") 1148 parser.add_option("--no-clobber", action="store_false", dest="clobber") 1149 1150* ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`, 1151 :attr:`~Option.nargs`, :attr:`~Option.choices`] 1152 1153 The option must be followed by an argument, which is appended to the list in 1154 :attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is 1155 supplied, an empty list is automatically created when :mod:`optparse` first 1156 encounters this option on the command-line. If :attr:`~Option.nargs` > 1, 1157 multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs` 1158 is appended to :attr:`~Option.dest`. 1159 1160 The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as 1161 for the ``"store"`` action. 1162 1163 Example:: 1164 1165 parser.add_option("-t", "--tracks", action="append", type="int") 1166 1167 If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent 1168 of:: 1169 1170 options.tracks = [] 1171 options.tracks.append(int("3")) 1172 1173 If, a little later on, ``--tracks=4`` is seen, it does:: 1174 1175 options.tracks.append(int("4")) 1176 1177 The ``append`` action calls the ``append`` method on the current value of the 1178 option. This means that any default value specified must have an ``append`` 1179 method. It also means that if the default value is non-empty, the default 1180 elements will be present in the parsed value for the option, with any values 1181 from the command line appended after those default values:: 1182 1183 >>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults']) 1184 >>> opts, args = parser.parse_args(['--files', 'overrides.mypkg']) 1185 >>> opts.files 1186 ['~/.mypkg/defaults', 'overrides.mypkg'] 1187 1188* ``"append_const"`` [required: :attr:`~Option.const`; relevant: 1189 :attr:`~Option.dest`] 1190 1191 Like ``"store_const"``, but the value :attr:`~Option.const` is appended to 1192 :attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to 1193 ``None``, and an empty list is automatically created the first time the option 1194 is encountered. 1195 1196* ``"count"`` [relevant: :attr:`~Option.dest`] 1197 1198 Increment the integer stored at :attr:`~Option.dest`. If no default value is 1199 supplied, :attr:`~Option.dest` is set to zero before being incremented the 1200 first time. 1201 1202 Example:: 1203 1204 parser.add_option("-v", action="count", dest="verbosity") 1205 1206 The first time ``-v`` is seen on the command line, :mod:`optparse` does the 1207 equivalent of:: 1208 1209 options.verbosity = 0 1210 options.verbosity += 1 1211 1212 Every subsequent occurrence of ``-v`` results in :: 1213 1214 options.verbosity += 1 1215 1216* ``"callback"`` [required: :attr:`~Option.callback`; relevant: 1217 :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`, 1218 :attr:`~Option.callback_kwargs`] 1219 1220 Call the function specified by :attr:`~Option.callback`, which is called as :: 1221 1222 func(option, opt_str, value, parser, *args, **kwargs) 1223 1224 See section :ref:`optparse-option-callbacks` for more detail. 1225 1226* ``"help"`` 1227 1228 Prints a complete help message for all the options in the current option 1229 parser. The help message is constructed from the ``usage`` string passed to 1230 OptionParser's constructor and the :attr:`~Option.help` string passed to every 1231 option. 1232 1233 If no :attr:`~Option.help` string is supplied for an option, it will still be 1234 listed in the help message. To omit an option entirely, use the special value 1235 :data:`optparse.SUPPRESS_HELP`. 1236 1237 :mod:`optparse` automatically adds a :attr:`~Option.help` option to all 1238 OptionParsers, so you do not normally need to create one. 1239 1240 Example:: 1241 1242 from optparse import OptionParser, SUPPRESS_HELP 1243 1244 # usually, a help option is added automatically, but that can 1245 # be suppressed using the add_help_option argument 1246 parser = OptionParser(add_help_option=False) 1247 1248 parser.add_option("-h", "--help", action="help") 1249 parser.add_option("-v", action="store_true", dest="verbose", 1250 help="Be moderately verbose") 1251 parser.add_option("--file", dest="filename", 1252 help="Input file to read data from") 1253 parser.add_option("--secret", help=SUPPRESS_HELP) 1254 1255 If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line, 1256 it will print something like the following help message to stdout (assuming 1257 ``sys.argv[0]`` is ``"foo.py"``): 1258 1259 .. code-block:: text 1260 1261 Usage: foo.py [options] 1262 1263 Options: 1264 -h, --help Show this help message and exit 1265 -v Be moderately verbose 1266 --file=FILENAME Input file to read data from 1267 1268 After printing the help message, :mod:`optparse` terminates your process with 1269 ``sys.exit(0)``. 1270 1271* ``"version"`` 1272 1273 Prints the version number supplied to the OptionParser to stdout and exits. 1274 The version number is actually formatted and printed by the 1275 ``print_version()`` method of OptionParser. Generally only relevant if the 1276 ``version`` argument is supplied to the OptionParser constructor. As with 1277 :attr:`~Option.help` options, you will rarely create ``version`` options, 1278 since :mod:`optparse` automatically adds them when needed. 1279 1280 1281.. _optparse-standard-option-types: 1282 1283Standard option types 1284^^^^^^^^^^^^^^^^^^^^^ 1285 1286:mod:`optparse` has five built-in option types: ``"string"``, ``"int"``, 1287``"choice"``, ``"float"`` and ``"complex"``. If you need to add new 1288option types, see section :ref:`optparse-extending-optparse`. 1289 1290Arguments to string options are not checked or converted in any way: the text on 1291the command line is stored in the destination (or passed to the callback) as-is. 1292 1293Integer arguments (type ``"int"``) are parsed as follows: 1294 1295* if the number starts with ``0x``, it is parsed as a hexadecimal number 1296 1297* if the number starts with ``0``, it is parsed as an octal number 1298 1299* if the number starts with ``0b``, it is parsed as a binary number 1300 1301* otherwise, the number is parsed as a decimal number 1302 1303 1304The conversion is done by calling :func:`int` with the appropriate base (2, 8, 130510, or 16). If this fails, so will :mod:`optparse`, although with a more useful 1306error message. 1307 1308``"float"`` and ``"complex"`` option arguments are converted directly with 1309:func:`float` and :func:`complex`, with similar error-handling. 1310 1311``"choice"`` options are a subtype of ``"string"`` options. The 1312:attr:`~Option.choices` option attribute (a sequence of strings) defines the 1313set of allowed option arguments. :func:`optparse.check_choice` compares 1314user-supplied option arguments against this master list and raises 1315:exc:`OptionValueError` if an invalid string is given. 1316 1317 1318.. _optparse-parsing-arguments: 1319 1320Parsing arguments 1321^^^^^^^^^^^^^^^^^ 1322 1323The whole point of creating and populating an OptionParser is to call its 1324:meth:`parse_args` method:: 1325 1326 (options, args) = parser.parse_args(args=None, values=None) 1327 1328where the input parameters are 1329 1330``args`` 1331 the list of arguments to process (default: ``sys.argv[1:]``) 1332 1333``values`` 1334 an :class:`optparse.Values` object to store option arguments in (default: a 1335 new instance of :class:`Values`) -- if you give an existing object, the 1336 option defaults will not be initialized on it 1337 1338and the return values are 1339 1340``options`` 1341 the same object that was passed in as ``values``, or the optparse.Values 1342 instance created by :mod:`optparse` 1343 1344``args`` 1345 the leftover positional arguments after all options have been processed 1346 1347The most common usage is to supply neither keyword argument. If you supply 1348``values``, it will be modified with repeated :func:`setattr` calls (roughly one 1349for every option argument stored to an option destination) and returned by 1350:meth:`parse_args`. 1351 1352If :meth:`parse_args` encounters any errors in the argument list, it calls the 1353OptionParser's :meth:`error` method with an appropriate end-user error message. 1354This ultimately terminates your process with an exit status of 2 (the 1355traditional Unix exit status for command-line errors). 1356 1357 1358.. _optparse-querying-manipulating-option-parser: 1359 1360Querying and manipulating your option parser 1361^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1362 1363The default behavior of the option parser can be customized slightly, and you 1364can also poke around your option parser and see what's there. OptionParser 1365provides several methods to help you out: 1366 1367.. method:: OptionParser.disable_interspersed_args() 1368 1369 Set parsing to stop on the first non-option. For example, if ``-a`` and 1370 ``-b`` are both simple options that take no arguments, :mod:`optparse` 1371 normally accepts this syntax:: 1372 1373 prog -a arg1 -b arg2 1374 1375 and treats it as equivalent to :: 1376 1377 prog -a -b arg1 arg2 1378 1379 To disable this feature, call :meth:`disable_interspersed_args`. This 1380 restores traditional Unix syntax, where option parsing stops with the first 1381 non-option argument. 1382 1383 Use this if you have a command processor which runs another command which has 1384 options of its own and you want to make sure these options don't get 1385 confused. For example, each command might have a different set of options. 1386 1387.. method:: OptionParser.enable_interspersed_args() 1388 1389 Set parsing to not stop on the first non-option, allowing interspersing 1390 switches with command arguments. This is the default behavior. 1391 1392.. method:: OptionParser.get_option(opt_str) 1393 1394 Returns the Option instance with the option string *opt_str*, or ``None`` if 1395 no options have that option string. 1396 1397.. method:: OptionParser.has_option(opt_str) 1398 1399 Return ``True`` if the OptionParser has an option with option string *opt_str* 1400 (e.g., ``-q`` or ``--verbose``). 1401 1402.. method:: OptionParser.remove_option(opt_str) 1403 1404 If the :class:`OptionParser` has an option corresponding to *opt_str*, that 1405 option is removed. If that option provided any other option strings, all of 1406 those option strings become invalid. If *opt_str* does not occur in any 1407 option belonging to this :class:`OptionParser`, raises :exc:`ValueError`. 1408 1409 1410.. _optparse-conflicts-between-options: 1411 1412Conflicts between options 1413^^^^^^^^^^^^^^^^^^^^^^^^^ 1414 1415If you're not careful, it's easy to define options with conflicting option 1416strings:: 1417 1418 parser.add_option("-n", "--dry-run", ...) 1419 ... 1420 parser.add_option("-n", "--noisy", ...) 1421 1422(This is particularly true if you've defined your own OptionParser subclass with 1423some standard options.) 1424 1425Every time you add an option, :mod:`optparse` checks for conflicts with existing 1426options. If it finds any, it invokes the current conflict-handling mechanism. 1427You can set the conflict-handling mechanism either in the constructor:: 1428 1429 parser = OptionParser(..., conflict_handler=handler) 1430 1431or with a separate call:: 1432 1433 parser.set_conflict_handler(handler) 1434 1435The available conflict handlers are: 1436 1437 ``"error"`` (default) 1438 assume option conflicts are a programming error and raise 1439 :exc:`OptionConflictError` 1440 1441 ``"resolve"`` 1442 resolve option conflicts intelligently (see below) 1443 1444 1445As an example, let's define an :class:`OptionParser` that resolves conflicts 1446intelligently and add conflicting options to it:: 1447 1448 parser = OptionParser(conflict_handler="resolve") 1449 parser.add_option("-n", "--dry-run", ..., help="do no harm") 1450 parser.add_option("-n", "--noisy", ..., help="be noisy") 1451 1452At this point, :mod:`optparse` detects that a previously-added option is already 1453using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``, 1454it resolves the situation by removing ``-n`` from the earlier option's list of 1455option strings. Now ``--dry-run`` is the only way for the user to activate 1456that option. If the user asks for help, the help message will reflect that:: 1457 1458 Options: 1459 --dry-run do no harm 1460 ... 1461 -n, --noisy be noisy 1462 1463It's possible to whittle away the option strings for a previously-added option 1464until there are none left, and the user has no way of invoking that option from 1465the command-line. In that case, :mod:`optparse` removes that option completely, 1466so it doesn't show up in help text or anywhere else. Carrying on with our 1467existing OptionParser:: 1468 1469 parser.add_option("--dry-run", ..., help="new dry-run option") 1470 1471At this point, the original ``-n``/``--dry-run`` option is no longer 1472accessible, so :mod:`optparse` removes it, leaving this help text:: 1473 1474 Options: 1475 ... 1476 -n, --noisy be noisy 1477 --dry-run new dry-run option 1478 1479 1480.. _optparse-cleanup: 1481 1482Cleanup 1483^^^^^^^ 1484 1485OptionParser instances have several cyclic references. This should not be a 1486problem for Python's garbage collector, but you may wish to break the cyclic 1487references explicitly by calling :meth:`~OptionParser.destroy` on your 1488OptionParser once you are done with it. This is particularly useful in 1489long-running applications where large object graphs are reachable from your 1490OptionParser. 1491 1492 1493.. _optparse-other-methods: 1494 1495Other methods 1496^^^^^^^^^^^^^ 1497 1498OptionParser supports several other public methods: 1499 1500.. method:: OptionParser.set_usage(usage) 1501 1502 Set the usage string according to the rules described above for the ``usage`` 1503 constructor keyword argument. Passing ``None`` sets the default usage 1504 string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message. 1505 1506.. method:: OptionParser.print_usage(file=None) 1507 1508 Print the usage message for the current program (``self.usage``) to *file* 1509 (default stdout). Any occurrence of the string ``%prog`` in ``self.usage`` 1510 is replaced with the name of the current program. Does nothing if 1511 ``self.usage`` is empty or not defined. 1512 1513.. method:: OptionParser.get_usage() 1514 1515 Same as :meth:`print_usage` but returns the usage string instead of 1516 printing it. 1517 1518.. method:: OptionParser.set_defaults(dest=value, ...) 1519 1520 Set default values for several option destinations at once. Using 1521 :meth:`set_defaults` is the preferred way to set default values for options, 1522 since multiple options can share the same destination. For example, if 1523 several "mode" options all set the same destination, any one of them can set 1524 the default, and the last one wins:: 1525 1526 parser.add_option("--advanced", action="store_const", 1527 dest="mode", const="advanced", 1528 default="novice") # overridden below 1529 parser.add_option("--novice", action="store_const", 1530 dest="mode", const="novice", 1531 default="advanced") # overrides above setting 1532 1533 To avoid this confusion, use :meth:`set_defaults`:: 1534 1535 parser.set_defaults(mode="advanced") 1536 parser.add_option("--advanced", action="store_const", 1537 dest="mode", const="advanced") 1538 parser.add_option("--novice", action="store_const", 1539 dest="mode", const="novice") 1540 1541 1542.. _optparse-option-callbacks: 1543 1544Option Callbacks 1545---------------- 1546 1547When :mod:`optparse`'s built-in actions and types aren't quite enough for your 1548needs, you have two choices: extend :mod:`optparse` or define a callback option. 1549Extending :mod:`optparse` is more general, but overkill for a lot of simple 1550cases. Quite often a simple callback is all you need. 1551 1552There are two steps to defining a callback option: 1553 1554* define the option itself using the ``"callback"`` action 1555 1556* write the callback; this is a function (or method) that takes at least four 1557 arguments, as described below 1558 1559 1560.. _optparse-defining-callback-option: 1561 1562Defining a callback option 1563^^^^^^^^^^^^^^^^^^^^^^^^^^ 1564 1565As always, the easiest way to define a callback option is by using the 1566:meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the 1567only option attribute you must specify is ``callback``, the function to call:: 1568 1569 parser.add_option("-c", action="callback", callback=my_callback) 1570 1571``callback`` is a function (or other callable object), so you must have already 1572defined ``my_callback()`` when you create this callback option. In this simple 1573case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments, 1574which usually means that the option takes no arguments---the mere presence of 1575``-c`` on the command-line is all it needs to know. In some 1576circumstances, though, you might want your callback to consume an arbitrary 1577number of command-line arguments. This is where writing callbacks gets tricky; 1578it's covered later in this section. 1579 1580:mod:`optparse` always passes four particular arguments to your callback, and it 1581will only pass additional arguments if you specify them via 1582:attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the 1583minimal callback function signature is:: 1584 1585 def my_callback(option, opt, value, parser): 1586 1587The four arguments to a callback are described below. 1588 1589There are several other option attributes that you can supply when you define a 1590callback option: 1591 1592:attr:`~Option.type` 1593 has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it 1594 instructs :mod:`optparse` to consume one argument and convert it to 1595 :attr:`~Option.type`. Rather than storing the converted value(s) anywhere, 1596 though, :mod:`optparse` passes it to your callback function. 1597 1598:attr:`~Option.nargs` 1599 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will 1600 consume :attr:`~Option.nargs` arguments, each of which must be convertible to 1601 :attr:`~Option.type`. It then passes a tuple of converted values to your 1602 callback. 1603 1604:attr:`~Option.callback_args` 1605 a tuple of extra positional arguments to pass to the callback 1606 1607:attr:`~Option.callback_kwargs` 1608 a dictionary of extra keyword arguments to pass to the callback 1609 1610 1611.. _optparse-how-callbacks-called: 1612 1613How callbacks are called 1614^^^^^^^^^^^^^^^^^^^^^^^^ 1615 1616All callbacks are called as follows:: 1617 1618 func(option, opt_str, value, parser, *args, **kwargs) 1619 1620where 1621 1622``option`` 1623 is the Option instance that's calling the callback 1624 1625``opt_str`` 1626 is the option string seen on the command-line that's triggering the callback. 1627 (If an abbreviated long option was used, ``opt_str`` will be the full, 1628 canonical option string---e.g. if the user puts ``--foo`` on the 1629 command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be 1630 ``"--foobar"``.) 1631 1632``value`` 1633 is the argument to this option seen on the command-line. :mod:`optparse` will 1634 only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be 1635 the type implied by the option's type. If :attr:`~Option.type` for this option is 1636 ``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs` 1637 > 1, ``value`` will be a tuple of values of the appropriate type. 1638 1639``parser`` 1640 is the OptionParser instance driving the whole thing, mainly useful because 1641 you can access some other interesting data through its instance attributes: 1642 1643 ``parser.largs`` 1644 the current list of leftover arguments, ie. arguments that have been 1645 consumed but are neither options nor option arguments. Feel free to modify 1646 ``parser.largs``, e.g. by adding more arguments to it. (This list will 1647 become ``args``, the second return value of :meth:`parse_args`.) 1648 1649 ``parser.rargs`` 1650 the current list of remaining arguments, ie. with ``opt_str`` and 1651 ``value`` (if applicable) removed, and only the arguments following them 1652 still there. Feel free to modify ``parser.rargs``, e.g. by consuming more 1653 arguments. 1654 1655 ``parser.values`` 1656 the object where option values are by default stored (an instance of 1657 optparse.OptionValues). This lets callbacks use the same mechanism as the 1658 rest of :mod:`optparse` for storing option values; you don't need to mess 1659 around with globals or closures. You can also access or modify the 1660 value(s) of any options already encountered on the command-line. 1661 1662``args`` 1663 is a tuple of arbitrary positional arguments supplied via the 1664 :attr:`~Option.callback_args` option attribute. 1665 1666``kwargs`` 1667 is a dictionary of arbitrary keyword arguments supplied via 1668 :attr:`~Option.callback_kwargs`. 1669 1670 1671.. _optparse-raising-errors-in-callback: 1672 1673Raising errors in a callback 1674^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1675 1676The callback function should raise :exc:`OptionValueError` if there are any 1677problems with the option or its argument(s). :mod:`optparse` catches this and 1678terminates the program, printing the error message you supply to stderr. Your 1679message should be clear, concise, accurate, and mention the option at fault. 1680Otherwise, the user will have a hard time figuring out what they did wrong. 1681 1682 1683.. _optparse-callback-example-1: 1684 1685Callback example 1: trivial callback 1686^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1687 1688Here's an example of a callback option that takes no arguments, and simply 1689records that the option was seen:: 1690 1691 def record_foo_seen(option, opt_str, value, parser): 1692 parser.values.saw_foo = True 1693 1694 parser.add_option("--foo", action="callback", callback=record_foo_seen) 1695 1696Of course, you could do that with the ``"store_true"`` action. 1697 1698 1699.. _optparse-callback-example-2: 1700 1701Callback example 2: check option order 1702^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1703 1704Here's a slightly more interesting example: record the fact that ``-a`` is 1705seen, but blow up if it comes after ``-b`` in the command-line. :: 1706 1707 def check_order(option, opt_str, value, parser): 1708 if parser.values.b: 1709 raise OptionValueError("can't use -a after -b") 1710 parser.values.a = 1 1711 ... 1712 parser.add_option("-a", action="callback", callback=check_order) 1713 parser.add_option("-b", action="store_true", dest="b") 1714 1715 1716.. _optparse-callback-example-3: 1717 1718Callback example 3: check option order (generalized) 1719^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1720 1721If you want to re-use this callback for several similar options (set a flag, but 1722blow up if ``-b`` has already been seen), it needs a bit of work: the error 1723message and the flag that it sets must be generalized. :: 1724 1725 def check_order(option, opt_str, value, parser): 1726 if parser.values.b: 1727 raise OptionValueError("can't use %s after -b" % opt_str) 1728 setattr(parser.values, option.dest, 1) 1729 ... 1730 parser.add_option("-a", action="callback", callback=check_order, dest='a') 1731 parser.add_option("-b", action="store_true", dest="b") 1732 parser.add_option("-c", action="callback", callback=check_order, dest='c') 1733 1734 1735.. _optparse-callback-example-4: 1736 1737Callback example 4: check arbitrary condition 1738^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1739 1740Of course, you could put any condition in there---you're not limited to checking 1741the values of already-defined options. For example, if you have options that 1742should not be called when the moon is full, all you have to do is this:: 1743 1744 def check_moon(option, opt_str, value, parser): 1745 if is_moon_full(): 1746 raise OptionValueError("%s option invalid when moon is full" 1747 % opt_str) 1748 setattr(parser.values, option.dest, 1) 1749 ... 1750 parser.add_option("--foo", 1751 action="callback", callback=check_moon, dest="foo") 1752 1753(The definition of ``is_moon_full()`` is left as an exercise for the reader.) 1754 1755 1756.. _optparse-callback-example-5: 1757 1758Callback example 5: fixed arguments 1759^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1760 1761Things get slightly more interesting when you define callback options that take 1762a fixed number of arguments. Specifying that a callback option takes arguments 1763is similar to defining a ``"store"`` or ``"append"`` option: if you define 1764:attr:`~Option.type`, then the option takes one argument that must be 1765convertible to that type; if you further define :attr:`~Option.nargs`, then the 1766option takes :attr:`~Option.nargs` arguments. 1767 1768Here's an example that just emulates the standard ``"store"`` action:: 1769 1770 def store_value(option, opt_str, value, parser): 1771 setattr(parser.values, option.dest, value) 1772 ... 1773 parser.add_option("--foo", 1774 action="callback", callback=store_value, 1775 type="int", nargs=3, dest="foo") 1776 1777Note that :mod:`optparse` takes care of consuming 3 arguments and converting 1778them to integers for you; all you have to do is store them. (Or whatever; 1779obviously you don't need a callback for this example.) 1780 1781 1782.. _optparse-callback-example-6: 1783 1784Callback example 6: variable arguments 1785^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1786 1787Things get hairy when you want an option to take a variable number of arguments. 1788For this case, you must write a callback, as :mod:`optparse` doesn't provide any 1789built-in capabilities for it. And you have to deal with certain intricacies of 1790conventional Unix command-line parsing that :mod:`optparse` normally handles for 1791you. In particular, callbacks should implement the conventional rules for bare 1792``--`` and ``-`` arguments: 1793 1794* either ``--`` or ``-`` can be option arguments 1795 1796* bare ``--`` (if not the argument to some option): halt command-line 1797 processing and discard the ``--`` 1798 1799* bare ``-`` (if not the argument to some option): halt command-line 1800 processing but keep the ``-`` (append it to ``parser.largs``) 1801 1802If you want an option that takes a variable number of arguments, there are 1803several subtle, tricky issues to worry about. The exact implementation you 1804choose will be based on which trade-offs you're willing to make for your 1805application (which is why :mod:`optparse` doesn't support this sort of thing 1806directly). 1807 1808Nevertheless, here's a stab at a callback for an option with variable 1809arguments:: 1810 1811 def vararg_callback(option, opt_str, value, parser): 1812 assert value is None 1813 value = [] 1814 1815 def floatable(str): 1816 try: 1817 float(str) 1818 return True 1819 except ValueError: 1820 return False 1821 1822 for arg in parser.rargs: 1823 # stop on --foo like options 1824 if arg[:2] == "--" and len(arg) > 2: 1825 break 1826 # stop on -a, but not on -3 or -3.0 1827 if arg[:1] == "-" and len(arg) > 1 and not floatable(arg): 1828 break 1829 value.append(arg) 1830 1831 del parser.rargs[:len(value)] 1832 setattr(parser.values, option.dest, value) 1833 1834 ... 1835 parser.add_option("-c", "--callback", dest="vararg_attr", 1836 action="callback", callback=vararg_callback) 1837 1838 1839.. _optparse-extending-optparse: 1840 1841Extending :mod:`optparse` 1842------------------------- 1843 1844Since the two major controlling factors in how :mod:`optparse` interprets 1845command-line options are the action and type of each option, the most likely 1846direction of extension is to add new actions and new types. 1847 1848 1849.. _optparse-adding-new-types: 1850 1851Adding new types 1852^^^^^^^^^^^^^^^^ 1853 1854To add new types, you need to define your own subclass of :mod:`optparse`'s 1855:class:`Option` class. This class has a couple of attributes that define 1856:mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`. 1857 1858.. attribute:: Option.TYPES 1859 1860 A tuple of type names; in your subclass, simply define a new tuple 1861 :attr:`TYPES` that builds on the standard one. 1862 1863.. attribute:: Option.TYPE_CHECKER 1864 1865 A dictionary mapping type names to type-checking functions. A type-checking 1866 function has the following signature:: 1867 1868 def check_mytype(option, opt, value) 1869 1870 where ``option`` is an :class:`Option` instance, ``opt`` is an option string 1871 (e.g., ``-f``), and ``value`` is the string from the command line that must 1872 be checked and converted to your desired type. ``check_mytype()`` should 1873 return an object of the hypothetical type ``mytype``. The value returned by 1874 a type-checking function will wind up in the OptionValues instance returned 1875 by :meth:`OptionParser.parse_args`, or be passed to a callback as the 1876 ``value`` parameter. 1877 1878 Your type-checking function should raise :exc:`OptionValueError` if it 1879 encounters any problems. :exc:`OptionValueError` takes a single string 1880 argument, which is passed as-is to :class:`OptionParser`'s :meth:`error` 1881 method, which in turn prepends the program name and the string ``"error:"`` 1882 and prints everything to stderr before terminating the process. 1883 1884Here's a silly example that demonstrates adding a ``"complex"`` option type to 1885parse Python-style complex numbers on the command line. (This is even sillier 1886than it used to be, because :mod:`optparse` 1.3 added built-in support for 1887complex numbers, but never mind.) 1888 1889First, the necessary imports:: 1890 1891 from copy import copy 1892 from optparse import Option, OptionValueError 1893 1894You need to define your type-checker first, since it's referred to later (in the 1895:attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass):: 1896 1897 def check_complex(option, opt, value): 1898 try: 1899 return complex(value) 1900 except ValueError: 1901 raise OptionValueError( 1902 "option %s: invalid complex value: %r" % (opt, value)) 1903 1904Finally, the Option subclass:: 1905 1906 class MyOption (Option): 1907 TYPES = Option.TYPES + ("complex",) 1908 TYPE_CHECKER = copy(Option.TYPE_CHECKER) 1909 TYPE_CHECKER["complex"] = check_complex 1910 1911(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end 1912up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s 1913Option class. This being Python, nothing stops you from doing that except good 1914manners and common sense.) 1915 1916That's it! Now you can write a script that uses the new option type just like 1917any other :mod:`optparse`\ -based script, except you have to instruct your 1918OptionParser to use MyOption instead of Option:: 1919 1920 parser = OptionParser(option_class=MyOption) 1921 parser.add_option("-c", type="complex") 1922 1923Alternately, you can build your own option list and pass it to OptionParser; if 1924you don't use :meth:`add_option` in the above way, you don't need to tell 1925OptionParser which option class to use:: 1926 1927 option_list = [MyOption("-c", action="store", type="complex", dest="c")] 1928 parser = OptionParser(option_list=option_list) 1929 1930 1931.. _optparse-adding-new-actions: 1932 1933Adding new actions 1934^^^^^^^^^^^^^^^^^^ 1935 1936Adding new actions is a bit trickier, because you have to understand that 1937:mod:`optparse` has a couple of classifications for actions: 1938 1939"store" actions 1940 actions that result in :mod:`optparse` storing a value to an attribute of the 1941 current OptionValues instance; these options require a :attr:`~Option.dest` 1942 attribute to be supplied to the Option constructor. 1943 1944"typed" actions 1945 actions that take a value from the command line and expect it to be of a 1946 certain type; or rather, a string that can be converted to a certain type. 1947 These options require a :attr:`~Option.type` attribute to the Option 1948 constructor. 1949 1950These are overlapping sets: some default "store" actions are ``"store"``, 1951``"store_const"``, ``"append"``, and ``"count"``, while the default "typed" 1952actions are ``"store"``, ``"append"``, and ``"callback"``. 1953 1954When you add an action, you need to categorize it by listing it in at least one 1955of the following class attributes of Option (all are lists of strings): 1956 1957.. attribute:: Option.ACTIONS 1958 1959 All actions must be listed in ACTIONS. 1960 1961.. attribute:: Option.STORE_ACTIONS 1962 1963 "store" actions are additionally listed here. 1964 1965.. attribute:: Option.TYPED_ACTIONS 1966 1967 "typed" actions are additionally listed here. 1968 1969.. attribute:: Option.ALWAYS_TYPED_ACTIONS 1970 1971 Actions that always take a type (i.e. whose options always take a value) are 1972 additionally listed here. The only effect of this is that :mod:`optparse` 1973 assigns the default type, ``"string"``, to options with no explicit type 1974 whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`. 1975 1976In order to actually implement your new action, you must override Option's 1977:meth:`take_action` method and add a case that recognizes your action. 1978 1979For example, let's add an ``"extend"`` action. This is similar to the standard 1980``"append"`` action, but instead of taking a single value from the command-line 1981and appending it to an existing list, ``"extend"`` will take multiple values in 1982a single comma-delimited string, and extend an existing list with them. That 1983is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command 1984line :: 1985 1986 --names=foo,bar --names blah --names ding,dong 1987 1988would result in a list :: 1989 1990 ["foo", "bar", "blah", "ding", "dong"] 1991 1992Again we define a subclass of Option:: 1993 1994 class MyOption(Option): 1995 1996 ACTIONS = Option.ACTIONS + ("extend",) 1997 STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",) 1998 TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",) 1999 ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",) 2000 2001 def take_action(self, action, dest, opt, value, values, parser): 2002 if action == "extend": 2003 lvalue = value.split(",") 2004 values.ensure_value(dest, []).extend(lvalue) 2005 else: 2006 Option.take_action( 2007 self, action, dest, opt, value, values, parser) 2008 2009Features of note: 2010 2011* ``"extend"`` both expects a value on the command-line and stores that value 2012 somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and 2013 :attr:`~Option.TYPED_ACTIONS`. 2014 2015* to ensure that :mod:`optparse` assigns the default type of ``"string"`` to 2016 ``"extend"`` actions, we put the ``"extend"`` action in 2017 :attr:`~Option.ALWAYS_TYPED_ACTIONS` as well. 2018 2019* :meth:`MyOption.take_action` implements just this one new action, and passes 2020 control back to :meth:`Option.take_action` for the standard :mod:`optparse` 2021 actions. 2022 2023* ``values`` is an instance of the optparse_parser.Values class, which provides 2024 the very useful :meth:`ensure_value` method. :meth:`ensure_value` is 2025 essentially :func:`getattr` with a safety valve; it is called as :: 2026 2027 values.ensure_value(attr, value) 2028 2029 If the ``attr`` attribute of ``values`` doesn't exist or is ``None``, then 2030 ensure_value() first sets it to ``value``, and then returns 'value. This is 2031 very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all 2032 of which accumulate data in a variable and expect that variable to be of a 2033 certain type (a list for the first two, an integer for the latter). Using 2034 :meth:`ensure_value` means that scripts using your action don't have to worry 2035 about setting a default value for the option destinations in question; they 2036 can just leave the default as ``None`` and :meth:`ensure_value` will take care of 2037 getting it right when it's needed. 2038