Lines Matching refs:optparse
1 :mod:`optparse` --- Parser for command line options
4 .. module:: optparse
11 **Source code:** :source:`Lib/optparse.py`
14 The :mod:`optparse` module is deprecated and will not be developed further;
19 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
20 command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
23 line. :mod:`optparse` allows users to specify options in the conventional
26 Here's an example of using :mod:`optparse` in a simple script::
28 from optparse import OptionParser
44 As it parses the command line, :mod:`optparse` sets attributes of the
48 ``False``. :mod:`optparse` supports both long and short options, allows short
63 and :mod:`optparse` will print out a brief summary of your script's options:
83 :mod:`optparse` was explicitly designed to encourage the creation of programs
114 only two option syntaxes provided by :mod:`optparse`.
131 These option syntaxes are not supported by :mod:`optparse`, and they never
139 :mod:`optparse`, option arguments may either be in a separate argument from
159 interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
169 "required option" is self-contradictory in English. :mod:`optparse` doesn't
248 While :mod:`optparse` is quite flexible and powerful, it's also straightforward
250 any :mod:`optparse`\ -based program.
255 from optparse import OptionParser
265 and several option attributes that tell :mod:`optparse` what to expect and what
280 *encountering an option* on the command line; in reality, :mod:`optparse`
283 Once all of your options are defined, instruct :mod:`optparse` to parse your
311 Actions tell :mod:`optparse` what to do when it encounters an option on the
312 command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
314 :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
318 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
326 The most common option action is ``store``, which tells :mod:`optparse` to take
335 Now let's make up a fake command line and ask :mod:`optparse` to parse it::
340 When :mod:`optparse` sees the option string ``-f``, it consumes the next
344 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
361 If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
367 If you don't supply a destination, :mod:`optparse` figures out a sensible
370 long option strings, :mod:`optparse` looks at the first short option string: the
373 :mod:`optparse` also includes the built-in ``complex`` type. Adding
374 types is covered in section :ref:`optparse-extending-optparse`.
383 seen---are quite common. :mod:`optparse` supports them with two separate actions,
394 When :mod:`optparse` encounters ``-v`` on the command line, it sets
404 Some other actions supported by :mod:`optparse` are:
418 These are covered in section :ref:`optparse-reference-guide`,
419 and section :ref:`optparse-option-callbacks`.
430 is usually fine, but sometimes you want more control. :mod:`optparse` lets you
434 First, consider the verbose/quiet example. If we want :mod:`optparse` to set
472 :mod:`optparse`'s ability to generate help and usage text automatically is
493 If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
510 (If the help output is triggered by a help option, :mod:`optparse` exits after
513 There's a lot going on here to help :mod:`optparse` generate the best possible
520 :mod:`optparse` expands ``%prog`` in the usage string to the name of the
524 If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
529 line-wrapping---\ :mod:`optparse` takes care of wrapping lines and making
539 :mod:`optparse` converts the destination variable name to uppercase and uses
553 string---\ :mod:`optparse` will replace it with :func:`str` of the option's
669 Similar to the brief usage string, :mod:`optparse` can also print a version
676 ``version`` can contain anything you like. When you supply it, :mod:`optparse`
703 .. _optparse-how-optparse-handles-errors:
705 How :mod:`optparse` handles errors
708 There are two broad classes of errors that :mod:`optparse` has to worry about:
712 usual way: raise an exception (either :exc:`optparse.OptionError` or
716 no matter how stable your code is. :mod:`optparse` can automatically detect
728 In either case, :mod:`optparse` handles the error the same way: it prints the
751 :mod:`optparse`\ -generated error messages take care always to mention the
755 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
765 Here's what :mod:`optparse`\ -based scripts usually look like::
767 from optparse import OptionParser
801 The first step in using :mod:`optparse` is to create an OptionParser instance.
811 help option. When :mod:`optparse` prints the usage string, it expands
814 special value :data:`optparse.SUPPRESS_USAGE`.
823 ``option_class`` (default: optparse.Option)
828 supply a true value for ``version``, :mod:`optparse` automatically adds a
835 :ref:`optparse-conflicts-between-options`.
839 :mod:`optparse` reformats this paragraph to fit the current terminal width
844 An instance of optparse.HelpFormatter that will be used for printing help
845 text. :mod:`optparse` provides two concrete classes for this purpose:
849 If true, :mod:`optparse` will add a help option (with option strings ``-h``
866 :ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
887 :mod:`optparse` may split Option into several classes, and :func:`make_option`
917 irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
920 An option's *action* determines what :mod:`optparse` does when it encounters
922 :mod:`optparse` are:
953 attributes; see :ref:`optparse-standard-option-actions`.)
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
965 one of the first things :mod:`optparse` does is create the ``options`` object::
980 then :mod:`optparse`, on seeing this option, will do the equivalent of ::
997 :mod:`optparse` raises :exc:`OptionError`.
1003 Determines :mod:`optparse`'s behaviour when this option is seen on the
1005 <optparse-standard-option-actions>`.
1013 <optparse-standard-option-types>`.
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
1034 option is seen. If > 1, :mod:`optparse` will store a tuple of values to
1049 is seen. See section :ref:`optparse-option-callbacks` for detail on the
1063 hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
1070 section :ref:`optparse-tutorial` for an example.
1080 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
1091 :ref:`optparse-standard-option-types` section.
1098 If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
1100 ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
1112 :mod:`optparse` will set ::
1132 If ``--noisy`` is seen, :mod:`optparse` will set ::
1155 supplied, an empty list is automatically created when :mod:`optparse` first
1167 If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
1206 The first time ``-v`` is seen on the command line, :mod:`optparse` does the
1224 See section :ref:`optparse-option-callbacks` for more detail.
1235 :data:`optparse.SUPPRESS_HELP`.
1237 :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
1242 from optparse import OptionParser, SUPPRESS_HELP
1255 If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
1268 After printing the help message, :mod:`optparse` terminates your process with
1278 since :mod:`optparse` automatically adds them when needed.
1286 :mod:`optparse` has five built-in option types: ``"string"``, ``"int"``,
1288 option types, see section :ref:`optparse-extending-optparse`.
1305 10, or 16). If this fails, so will :mod:`optparse`, although with a more useful
1313 set of allowed option arguments. :func:`optparse.check_choice` compares
1334 an :class:`optparse.Values` object to store option arguments in (default: a
1341 the same object that was passed in as ``values``, or the optparse.Values
1342 instance created by :mod:`optparse`
1370 ``-b`` are both simple options that take no arguments, :mod:`optparse`
1425 Every time you add an option, :mod:`optparse` checks for conflicts with existing
1452 At this point, :mod:`optparse` detects that a previously-added option is already
1465 the command-line. In that case, :mod:`optparse` removes that option completely,
1472 accessible, so :mod:`optparse` removes it, leaving this help text::
1504 string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
1547 When :mod:`optparse`'s built-in actions and types aren't quite enough for your
1548 needs, you have two choices: extend :mod:`optparse` or define a callback option.
1549 Extending :mod:`optparse` is more general, but overkill for a lot of simple
1573 case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
1580 :mod:`optparse` always passes four particular arguments to your callback, and it
1594 instructs :mod:`optparse` to consume one argument and convert it to
1596 though, :mod:`optparse` passes it to your callback function.
1599 also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
1633 is the argument to this option seen on the command-line. :mod:`optparse` will
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
1677 problems with the option or its argument(s). :mod:`optparse` catches this and
1777 Note that :mod:`optparse` takes care of consuming 3 arguments and converting
1788 For this case, you must write a callback, as :mod:`optparse` doesn't provide any
1790 conventional Unix command-line parsing that :mod:`optparse` normally handles for
1805 application (which is why :mod:`optparse` doesn't support this sort of thing
1839 .. _optparse-extending-optparse:
1841 Extending :mod:`optparse`
1844 Since the two major controlling factors in how :mod:`optparse` interprets
1854 To add new types, you need to define your own subclass of :mod:`optparse`'s
1856 :mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
1886 than it used to be, because :mod:`optparse` 1.3 added built-in support for
1892 from optparse import Option, OptionValueError
1912 up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
1917 any other :mod:`optparse`\ -based script, except you have to instruct your
1937 :mod:`optparse` has a couple of classifications for actions:
1940 actions that result in :mod:`optparse` storing a value to an attribute of the
1972 additionally listed here. The only effect of this is that :mod:`optparse`
2015 * to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
2020 control back to :meth:`Option.take_action` for the standard :mod:`optparse`