Lines Matching refs:optparse
1 :mod:`optparse` --- Parser for command line options
4 .. module:: optparse
13 The :mod:`optparse` module is deprecated and will not be developed further;
16 **Source code:** :source:`Lib/optparse.py`
20 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
21 command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
24 line. :mod:`optparse` allows users to specify options in the conventional
27 Here's an example of using :mod:`optparse` in a simple script::
29 from optparse import OptionParser
45 As it parses the command line, :mod:`optparse` sets attributes of the
49 ``False``. :mod:`optparse` supports both long and short options, allows short
64 and :mod:`optparse` will print out a brief summary of your script's options:
84 :mod:`optparse` was explicitly designed to encourage the creation of programs
115 only two option syntaxes provided by :mod:`optparse`.
132 These option syntaxes are not supported by :mod:`optparse`, and they never
140 :mod:`optparse`, option arguments may either be in a separate argument from
160 interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
170 "required option" is self-contradictory in English. :mod:`optparse` doesn't
249 While :mod:`optparse` is quite flexible and powerful, it's also straightforward
251 any :mod:`optparse`\ -based program.
256 from optparse import OptionParser
266 and several option attributes that tell :mod:`optparse` what to expect and what
281 *encountering an option* on the command line; in reality, :mod:`optparse`
284 Once all of your options are defined, instruct :mod:`optparse` to parse your
312 Actions tell :mod:`optparse` what to do when it encounters an option on the
313 command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
315 :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
319 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
327 The most common option action is ``store``, which tells :mod:`optparse` to take
336 Now let's make up a fake command line and ask :mod:`optparse` to parse it::
341 When :mod:`optparse` sees the option string ``-f``, it consumes the next
345 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
362 If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
368 If you don't supply a destination, :mod:`optparse` figures out a sensible
371 long option strings, :mod:`optparse` looks at the first short option string: the
374 :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding
375 types is covered in section :ref:`optparse-extending-optparse`.
384 ---are quite common. :mod:`optparse` supports them with two separate actions,
395 When :mod:`optparse` encounters ``-v`` on the command line, it sets
405 Some other actions supported by :mod:`optparse` are:
419 These are covered in section :ref:`optparse-reference-guide`, Reference Guide
420 and section :ref:`optparse-option-callbacks`.
431 is usually fine, but sometimes you want more control. :mod:`optparse` lets you
435 First, consider the verbose/quiet example. If we want :mod:`optparse` to set
473 :mod:`optparse`'s ability to generate help and usage text automatically is
494 If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
511 (If the help output is triggered by a help option, :mod:`optparse` exits after
514 There's a lot going on here to help :mod:`optparse` generate the best possible
521 :mod:`optparse` expands ``%prog`` in the usage string to the name of the
525 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
530 :mod:`optparse` takes care of wrapping lines and making the help output look
540 :mod:`optparse` converts the destination variable name to uppercase and uses
555 string---\ :mod:`optparse` will replace it with :func:`str` of the option's
671 Similar to the brief usage string, :mod:`optparse` can also print a version
678 ``version`` can contain anything you like. When you supply it, :mod:`optparse`
705 .. _optparse-how-optparse-handles-errors:
707 How :mod:`optparse` handles errors
710 There are two broad classes of errors that :mod:`optparse` has to worry about:
714 usual way: raise an exception (either :exc:`optparse.OptionError` or
718 no matter how stable your code is. :mod:`optparse` can automatically detect
730 In either case, :mod:`optparse` handles the error the same way: it prints the
753 :mod:`optparse`\ -generated error messages take care always to mention the
757 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
767 Here's what :mod:`optparse`\ -based scripts usually look like::
769 from optparse import OptionParser
803 The first step in using :mod:`optparse` is to create an OptionParser instance.
813 help option. When :mod:`optparse` prints the usage string, it expands
816 special value :data:`optparse.SUPPRESS_USAGE`.
825 ``option_class`` (default: optparse.Option)
830 supply a true value for ``version``, :mod:`optparse` automatically adds a
837 :ref:`optparse-conflicts-between-options`.
841 :mod:`optparse` reformats this paragraph to fit the current terminal width
846 An instance of optparse.HelpFormatter that will be used for printing help
847 text. :mod:`optparse` provides two concrete classes for this purpose:
851 If true, :mod:`optparse` will add a help option (with option strings ``-h``
868 :ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
889 :mod:`optparse` may split Option into several classes, and :func:`make_option`
919 irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
922 An option's *action* determines what :mod:`optparse` does when it encounters
924 :mod:`optparse` are:
955 attributes; see :ref:`optparse-standard-option-actions`.)
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
967 one of the first things :mod:`optparse` does is create the ``options`` object::
982 then :mod:`optparse`, on seeing this option, will do the equivalent of ::
999 :mod:`optparse` raises :exc:`OptionError`.
1005 Determines :mod:`optparse`'s behaviour when this option is seen on the
1007 <optparse-standard-option-actions>`.
1015 <optparse-standard-option-types>`.
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
1036 option is seen. If > 1, :mod:`optparse` will store a tuple of values to
1051 is seen. See section :ref:`optparse-option-callbacks` for detail on the
1065 hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
1072 section :ref:`optparse-tutorial` for an example.
1082 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
1093 :ref:`optparse-standard-option-types` section.
1100 If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
1102 ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
1114 :mod:`optparse` will set ::
1134 If ``--noisy`` is seen, :mod:`optparse` will set ::
1157 supplied, an empty list is automatically created when :mod:`optparse` first
1169 If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
1208 The first time ``-v`` is seen on the command line, :mod:`optparse` does the
1226 See section :ref:`optparse-option-callbacks` for more detail.
1237 :data:`optparse.SUPPRESS_HELP`.
1239 :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
1244 from optparse import OptionParser, SUPPRESS_HELP
1257 If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
1270 After printing the help message, :mod:`optparse` terminates your process with
1280 since :mod:`optparse` automatically adds them when needed.
1288 :mod:`optparse` has six built-in option types: ``"string"``, ``"int"``,
1290 option types, see section :ref:`optparse-extending-optparse`.
1307 appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`,
1315 set of allowed option arguments. :func:`optparse.check_choice` compares
1336 an :class:`optparse.Values` object to store option arguments in (default: a
1343 the same object that was passed in as ``values``, or the optparse.Values
1344 instance created by :mod:`optparse`
1372 ``-b`` are both simple options that take no arguments, :mod:`optparse`
1427 Every time you add an option, :mod:`optparse` checks for conflicts with existing
1454 At this point, :mod:`optparse` detects that a previously-added option is already
1467 the command-line. In that case, :mod:`optparse` removes that option completely,
1474 accessible, so :mod:`optparse` removes it, leaving this help text::
1506 string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
1549 When :mod:`optparse`'s built-in actions and types aren't quite enough for your
1550 needs, you have two choices: extend :mod:`optparse` or define a callback option.
1551 Extending :mod:`optparse` is more general, but overkill for a lot of simple
1575 case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
1582 :mod:`optparse` always passes four particular arguments to your callback, and it
1596 instructs :mod:`optparse` to consume one argument and convert it to
1598 though, :mod:`optparse` passes it to your callback function.
1601 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
1635 is the argument to this option seen on the command-line. :mod:`optparse` will
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
1679 problems with the option or its argument(s). :mod:`optparse` catches this and
1779 Note that :mod:`optparse` takes care of consuming 3 arguments and converting
1790 For this case, you must write a callback, as :mod:`optparse` doesn't provide any
1792 conventional Unix command-line parsing that :mod:`optparse` normally handles for
1807 application (which is why :mod:`optparse` doesn't support this sort of thing
1841 .. _optparse-extending-optparse:
1843 Extending :mod:`optparse`
1846 Since the two major controlling factors in how :mod:`optparse` interprets
1856 To add new types, you need to define your own subclass of :mod:`optparse`'s
1858 :mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
1888 than it used to be, because :mod:`optparse` 1.3 added built-in support for
1894 from optparse import Option, OptionValueError
1914 up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
1919 any other :mod:`optparse`\ -based script, except you have to instruct your
1939 :mod:`optparse` has a couple of classifications for actions:
1942 actions that result in :mod:`optparse` storing a value to an attribute of the
1974 additionally listed here. The only effect of this is that :mod:`optparse`
2017 * to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
2022 control back to :meth:`Option.take_action` for the standard :mod:`optparse`