[Python-checkins] r75674 - peps/trunk/pep-0389.txt
steven.bethard
python-checkins at python.org
Sat Oct 24 21:01:49 CEST 2009
Author: steven.bethard
Date: Sat Oct 24 21:01:49 2009
New Revision: 75674
Log:
Updates to argparse PEP based on python-dev feedback.
Modified:
peps/trunk/pep-0389.txt
Modified: peps/trunk/pep-0389.txt
==============================================================================
--- peps/trunk/pep-0389.txt (original)
+++ peps/trunk/pep-0389.txt Sat Oct 24 21:01:49 2009
@@ -8,7 +8,7 @@
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 @@
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 @@
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:
-
-* 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 3.3 -- Same as above
-
-* Python 3.4 -- Deprecation warnings for getopt and optparse, which
- by default *are* displayed.
-
-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.
+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 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 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.2 (estimated Jun 2010) -- Importing optparse will issue
+ a PendingDeprecationWarning, which is not displayed by default.
+
+* 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.
+
+
+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 ..
-Open Issues
-===========
+
+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 @@
.. [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
=========
More information about the Python-checkins
mailing list