[Python-checkins] r81490 - in python/trunk/Doc/library: argparse.rst getopt.rst optparse.rst

[steven.bethard]

Author: steven.bethard
Date: Mon May 24 04:38:00 2010
New Revision: 81490

Log:
argparse documentation updates (including updates to optparse and getopt documentation that were promised in the PEP)

Modified:
   python/trunk/Doc/library/argparse.rst
   python/trunk/Doc/library/getopt.rst
   python/trunk/Doc/library/optparse.rst

Modified: python/trunk/Doc/library/argparse.rst
==============================================================================
--- python/trunk/Doc/library/argparse.rst	(original)
+++ python/trunk/Doc/library/argparse.rst	Mon May 24 04:38:00 2010
@@ -672,8 +672,8 @@
 
     >>> import argparse
     >>> parser = argparse.ArgumentParser(prog='PROG')
-    >>> parser.add_argument('-v', '--version', action='version', version='%(prog)s 2.0')
-    >>> parser.parse_args(['-v'])
+    >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
+    >>> parser.parse_args(['--version'])
     PROG 2.0
 
 You can also specify an arbitrary action by passing an object that implements
@@ -1725,3 +1725,6 @@
 * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
   the standard python syntax to use dictionaries to format strings, that is,
   ``%(default)s`` and ``%(prog)s``.
+
+* Replace the OptionParser constructor ``version`` argument with a call to
+  ``parser.add_argument('--version', action='version', version='<the version>')``

Modified: python/trunk/Doc/library/getopt.rst
==============================================================================
--- python/trunk/Doc/library/getopt.rst	(original)
+++ python/trunk/Doc/library/getopt.rst	Mon May 24 04:38:00 2010
@@ -6,6 +6,12 @@
    :synopsis: Portable parser for command line options; support both short and long option
               names.
 
+.. note::
+   The :mod:`getopt` module is a parser for command line options whose API is
+   designed to be familiar to users of the C :cfunc:`getopt` function. Users who
+   are unfamiliar with the C :cfunc:`getopt` function or who would like to write
+   less code and get better help and error messages should consider using the
+   :mod:`argparse` module instead.
 
 This module helps scripts to parse the command line arguments in ``sys.argv``.
 It supports the same conventions as the Unix :cfunc:`getopt` function (including
@@ -142,9 +148,21 @@
    if __name__ == "__main__":
        main()
 
+Note that an equivalent command line interface could be produced with less code
+and more informative help and error messages by using the :mod:`argparse` module::
+
+   import argparse
+
+   if __name__ == '__main__':
+       parser = argparse.ArgumentParser()
+       parser.add_argument('-o', '--output')
+       parser.add_argument('-v', dest='verbose', action='store_true')
+       args = parser.parse_args()
+       # ... do something with args.output ...
+       # ... do something with args.verbose ..
 
 .. seealso::
 
-   Module :mod:`optparse`
-      More object-oriented command line option parsing.
+   Module :mod:`argparse`
+      Alternative command line option and argument parsing library.
 

Modified: python/trunk/Doc/library/optparse.rst
==============================================================================
--- python/trunk/Doc/library/optparse.rst	(original)
+++ python/trunk/Doc/library/optparse.rst	Mon May 24 04:38:00 2010
@@ -3,8 +3,13 @@
 
 .. module:: optparse
    :synopsis: Command-line option parsing library.
-.. moduleauthor:: Greg Ward <gward at python.net>
+   :deprecated:
+
+.. deprecated:: 2.7
+   The :mod:`optparse` module is deprecated and will not be developed further;
+   development will continue with the :mod:`argparse` module.
 
+.. moduleauthor:: Greg Ward <gward at python.net>
 
 .. versionadded:: 2.3