diff options
Diffstat (limited to 'Doc/library/optparse.rst')
| -rw-r--r-- | Doc/library/optparse.rst | 62 |
1 files changed, 32 insertions, 30 deletions
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index c1a18e0..627eb7d 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -4,16 +4,17 @@ .. module:: optparse :synopsis: Command-line option parsing library. :deprecated: - .. moduleauthor:: Greg Ward <gward@python.net> .. sectionauthor:: Greg Ward <gward@python.net> -**Source code:** :source:`Lib/optparse.py` +.. versionadded:: 2.3 -.. deprecated:: 3.2 +.. deprecated:: 2.7 The :mod:`optparse` module is deprecated and will not be developed further; development will continue with the :mod:`argparse` module. +**Source code:** :source:`Lib/optparse.py` + -------------- :mod:`optparse` is a more convenient, flexible, and powerful library for parsing @@ -354,7 +355,7 @@ right up against the option: since ``-n42`` (one argument) is equivalent to ``-n 42`` (two arguments), the code :: (options, args) = parser.parse_args(["-n42"]) - print(options.num) + print options.num will print ``42``. @@ -370,7 +371,7 @@ default from the option strings: if the first long option string is long option strings, :mod:`optparse` looks at the first short option string: the default destination for ``-f`` is ``f``. -:mod:`optparse` also includes the built-in ``complex`` type. Adding +:mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding types is covered in section :ref:`optparse-extending-optparse`. @@ -379,8 +380,8 @@ types is covered in section :ref:`optparse-extending-optparse`. Handling boolean (flag) options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Flag options---set a variable to true or false when a particular option is -seen---are quite common. :mod:`optparse` supports them with two separate actions, +Flag options---set a variable to true or false when a particular option is seen +---are quite common. :mod:`optparse` supports them with two separate actions, ``store_true`` and ``store_false``. For example, you might have a ``verbose`` flag that is turned on with ``-v`` and off with ``-q``:: @@ -388,8 +389,8 @@ flag that is turned on with ``-v`` and off with ``-q``:: parser.add_option("-q", action="store_false", dest="verbose") Here we have two different options with the same destination, which is perfectly -OK. (It just means you have to be a bit careful when setting default -values---see below.) +OK. (It just means you have to be a bit careful when setting default values--- +see below.) When :mod:`optparse` encounters ``-v`` on the command line, it sets ``options.verbose`` to ``True``; when it encounters ``-q``, @@ -415,7 +416,7 @@ Some other actions supported by :mod:`optparse` are: ``"callback"`` call a specified function -These are covered in section :ref:`optparse-reference-guide`, +These are covered in section :ref:`optparse-reference-guide`, Reference Guide and section :ref:`optparse-option-callbacks`. @@ -525,9 +526,9 @@ help message: default: ``"Usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about - line-wrapping---\ :mod:`optparse` takes care of wrapping lines and making - the help output look good. +* every option defines a help string, and doesn't worry about line-wrapping--- + :mod:`optparse` takes care of wrapping lines and making the help output look + good. * options that take a value indicate this fact in their automatically-generated help message, e.g. for the "mode" option:: @@ -549,10 +550,11 @@ help message: semantic description "write output to FILE". This is a simple but effective way to make your help text a lot clearer and more useful for end users. -* options that have a default value can include ``%default`` in the help - string---\ :mod:`optparse` will replace it with :func:`str` of the option's - default value. If an option has no default value (or the default value is - ``None``), ``%default`` expands to ``none``. +.. versionadded:: 2.4 + Options that have a default value can include ``%default`` in the help + string---\ :mod:`optparse` will replace it with :func:`str` of the option's + default value. If an option has no default value (or the default value is + ``None``), ``%default`` expands to ``none``. Grouping Options ++++++++++++++++ @@ -567,7 +569,7 @@ An option group is obtained using the class :class:`OptionGroup`: where - * parser is the :class:`OptionParser` instance the group will be inserted in + * parser is the :class:`OptionParser` instance the group will be insterted in to * title is the group title * description, optional, is a long description of the group @@ -780,7 +782,7 @@ Here's what :mod:`optparse`\ -based scripts usually look like:: if len(args) != 1: parser.error("incorrect number of arguments") if options.verbose: - print("reading %s..." % options.filename) + print "reading %s..." % options.filename ... if __name__ == "__main__": @@ -928,10 +930,10 @@ The canonical way to create an :class:`Option` instance is with the store a constant value ``"store_true"`` - store ``True`` + store a true value ``"store_false"`` - store ``False`` + store a false value ``"append"`` append this option's argument to a list @@ -1135,12 +1137,12 @@ must specify for any option using that action. * ``"store_true"`` [relevant: :attr:`~Option.dest`] - A special case of ``"store_const"`` that stores ``True`` to + A special case of ``"store_const"`` that stores a true value to :attr:`~Option.dest`. * ``"store_false"`` [relevant: :attr:`~Option.dest`] - Like ``"store_true"``, but stores ``False``. + Like ``"store_true"``, but stores a false value. Example:: @@ -1283,14 +1285,14 @@ must specify for any option using that action. Standard option types ^^^^^^^^^^^^^^^^^^^^^ -:mod:`optparse` has five built-in option types: ``"string"``, ``"int"``, -``"choice"``, ``"float"`` and ``"complex"``. If you need to add new +:mod:`optparse` has six built-in option types: ``"string"``, ``"int"``, +``"long"``, ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new option types, see section :ref:`optparse-extending-optparse`. Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is. -Integer arguments (type ``"int"``) are parsed as follows: +Integer arguments (type ``"int"`` or ``"long"``) are parsed as follows: * if the number starts with ``0x``, it is parsed as a hexadecimal number @@ -1301,9 +1303,9 @@ Integer arguments (type ``"int"``) are parsed as follows: * otherwise, the number is parsed as a decimal number -The conversion is done by calling :func:`int` with the appropriate base (2, 8, -10, or 16). If this fails, so will :mod:`optparse`, although with a more useful -error message. +The conversion is done by calling either :func:`int` or :func:`long` with the +appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`, +although with a more useful error message. ``"float"`` and ``"complex"`` option arguments are converted directly with :func:`float` and :func:`complex`, with similar error-handling. @@ -1396,7 +1398,7 @@ provides several methods to help you out: .. method:: OptionParser.has_option(opt_str) - Return ``True`` if the OptionParser has an option with option string *opt_str* + Return true if the OptionParser has an option with option string *opt_str* (e.g., ``-q`` or ``--verbose``). .. method:: OptionParser.remove_option(opt_str) |