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