Updates to argparse PEP based on python-dev feedback.

pep-0389.txt

@@ -8,7 +8,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 25-Sep-2009
 Python-Version: 2.7 and 3.2
-Post-History: 27-Sep-2009
+Post-History: 27-Sep-2009, 24-Oct-2009
 
 
 Abstract
@@ -117,9 +117,9 @@ possible. Some of the problems included:
   which provides an ``ensure_value`` method [12]_, while the argparse
   module allows attributes to be assigned to any object, e.g.::
   
-	foo_object = ...
-	parser.parse_args(namespace=foo_object)
-	foo_object.some_attribute_parsed_from_command_line
+    foo_object = ...
+    parser.parse_args(namespace=foo_object)
+    foo_object.some_attribute_parsed_from_command_line
   
   Modifying optparse to allow any object to be passed in would be
   difficult because simply passing the ``foo_object`` around instead
@@ -133,37 +133,130 @@ the argparse features into optparse with no backwards
 incompatibilities seems unlikely.
 
 
-Deprecation of getopt and optparse
-==================================
-There is still some debate over the best way (if at all) to encourage
-users to move from getopt and optparse to their replacement,
-argparse. The current recommendation of this PEP is the following
-conservative deprecation strategy:
+Deprecation of optparse
+=======================
+Because all of optparse's features are available in argparse, the
+optparse module will be deprecated. The following very conservative
+deprecation strategy will be followed:
 
-* Python 3.2, Python 2.7 and any later Python 2.X releases --
-  PendingDeprecation warnings, which by default are not displayed,
-  and documentation notes directing users of getopt and optparse to
-  argparse.
+* Python 2.7+ and 3.2+ -- The following note will be added to the
+  optparse documentation:
+  
+    The optparse module is deprecated, and has been replaced by the
+    argparse module.
 
-* Python 3.3 -- Same as above
+* Python 2.7+ -- If the Python 3 compatibility flag, ``-3``, is
+  provided at the command line, then importing optparse will issue a
+  DeprecationWarning. Otherwise no warnings will be issued.
 
-* Python 3.4 -- Deprecation warnings for getopt and optparse, which
-  by default *are* displayed.
+* Python 3.2 (estimated Jun 2010) -- Importing optparse will issue
+  a PendingDeprecationWarning, which is not displayed by default.
 
-Though this is slower than the usual deprecation process, it seems
-prudent to avoid producing any casually visible Deprecation warnings
-until Python 3.X has had some additional time to attract developers.
+* Python 3.3 (estimated Jan 2012) -- Importing optparse will issue
+  a PendingDeprecationWarning, which is not displayed by default.
+
+* Python 3.4 (estimated Jun 2013) -- Importing optparse will issue
+  a DeprecationWarning, which *is* displayed by default.
+
+* Python 3.5 (estimated Jan 2015) -- The optparse module will be
+  removed.
+
+Though this is slower than the usual deprecation process, with two 
+releases of PendingDeprecationWarnings instead of the usual one, it
+seems prudent to avoid producing any casually visible Deprecation
+warnings until Python 3.X has had some additional time to attract
+developers.
 
 
-Open Issues
-===========
+Updates to getopt documentation
+===============================
+The getopt module will not be deprecated. However, its documentation
+will be updated to point to argparse in a couple of places. At the
+top of the module, the following note will be added:
+
+  The getopt module is a parser for command line options whose API
+  is designed to be familiar to users of the C getopt function.
+  Users who are unfamiliar with the C getopt function or who would
+  like to write less code and get better help and error messages
+  should consider using the argparse module instead.
+
+Additionally, after the final getopt example, the following note will
+be added:
+
+  Note that an equivalent command line interface could be produced
+  with less code by using the 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 ..
+
+
+Deferred: string formatting
+===========================
 The argparse module supports Python from 2.3 up through 3.2 and as a
 result relies on traditional ``%(foo)s`` style string formatting. It
 has been suggested that it might be better to use the new style
-``{foo}`` string formatting [13]_. This seems like a good idea, but
-would break backwards compatibility for existing argparse-based
-scripts unless we can come up with a way to reasonably support both
-syntaxes.
+``{foo}`` string formatting [13]_. There was some discussion about
+how best to do this for modules in the standard library [14]_ and
+several people are developing functions for automatically converting
+%-formatting to {}-formatting [15]_ [16]_. When one of these is added
+to the standard library, argparse will use them to support both
+formatting styles.
+
+
+Rejected: getopt compatibility methods
+======================================
+Previously, when this PEP was suggesting the deprecation of getopt
+as well as optparse, there was some talk of adding a method like::
+
+  ArgumentParser.add_getopt_arguments(options[, long_options])
+
+However, this method will not be added for a number of reasons:
+
+* The getopt module is not being deprecated, so there is less need.
+* This method would not actually ease the transition for any getopt
+  users who were already maintaining usage messages, because the API
+  above gives no way of adding help messages to the arguments.
+* Some users of getopt consider it very important that only a single
+  function call is necessary. The API above does not satisfy this
+  requirement because both ``ArgumentParser()`` and ``parse_args()``
+  must also be called.
+
+
+Out of Scope: Various Feature Requests
+======================================
+Several feature requests for argparse were made in the discussion of
+this PEP:
+
+* Support argument defaults from environment variables
+* Support argument defaults from configuration files
+* Support "foo --help subcommand" in addition to the currently
+  supported "foo subcommand --help"
+
+These are all reasonable feature requests for the argparse module,
+but are out of the scope of this PEP, and have been redirected to
+the argparse issue tracker.
+
+
+Discussion: sys.err and sys.exit
+================================
+There were some concerns that argparse by default always writes to
+``sys.err`` and always calls ``sys.exit`` when invalid arguments are
+provided. This is the desired behavior for the vast majority of
+argparse use cases which revolve around simple command line
+interfaces. However, in some cases, it may be desirable to keep
+argparse from exiting, or to have it write its messages to something
+other than ``sys.err``. These use cases can be supported by
+subclassing ``ArgumentParser`` and overriding the ``exit`` or
+``_print_message`` methods. The latter is an undocumented
+implementation detail, but could be officially exposed if this turns
+out to be a common need.
 
 
 References
@@ -207,6 +300,15 @@ References
 .. [13] use {}-formatting instead of %-formatting
    (http://bugs.python.org/msg89279)
 
+.. [14] transitioning from % to {} formatting
+   (http://mail.python.org/pipermail/python-dev/2009-September/092326.html)
+
+.. [15] Vinay Sajip's %-to-{} converter
+   (http://gist.github.com/200936)
+
+.. [16] Benjamin Peterson's %-to-{} converter
+   (http://bazaar.launchpad.net/~gutworth/+junk/mod2format/files)
+
 
 Copyright
 =========