Updates to argparse PEP based on python-dev feedback.

This commit is contained in:
Steven Bethard 2009-10-24 19:01:49 +00:00
parent 4a40d09d74
commit 096c0e1222
1 changed files with 128 additions and 26 deletions

View File

@ -8,7 +8,7 @@ Type: Standards Track
Content-Type: text/x-rst Content-Type: text/x-rst
Created: 25-Sep-2009 Created: 25-Sep-2009
Python-Version: 2.7 and 3.2 Python-Version: 2.7 and 3.2
Post-History: 27-Sep-2009 Post-History: 27-Sep-2009, 24-Oct-2009
Abstract Abstract
@ -117,9 +117,9 @@ possible. Some of the problems included:
which provides an ``ensure_value`` method [12]_, while the argparse which provides an ``ensure_value`` method [12]_, while the argparse
module allows attributes to be assigned to any object, e.g.:: module allows attributes to be assigned to any object, e.g.::
foo_object = ... foo_object = ...
parser.parse_args(namespace=foo_object) parser.parse_args(namespace=foo_object)
foo_object.some_attribute_parsed_from_command_line foo_object.some_attribute_parsed_from_command_line
Modifying optparse to allow any object to be passed in would be Modifying optparse to allow any object to be passed in would be
difficult because simply passing the ``foo_object`` around instead difficult because simply passing the ``foo_object`` around instead
@ -133,37 +133,130 @@ the argparse features into optparse with no backwards
incompatibilities seems unlikely. incompatibilities seems unlikely.
Deprecation of getopt and optparse Deprecation of optparse
================================== =======================
There is still some debate over the best way (if at all) to encourage Because all of optparse's features are available in argparse, the
users to move from getopt and optparse to their replacement, optparse module will be deprecated. The following very conservative
argparse. The current recommendation of this PEP is the following deprecation strategy will be followed:
conservative deprecation strategy:
* Python 3.2, Python 2.7 and any later Python 2.X releases -- * Python 2.7+ and 3.2+ -- The following note will be added to the
PendingDeprecation warnings, which by default are not displayed, optparse documentation:
and documentation notes directing users of getopt and optparse to
argparse. 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 * Python 3.2 (estimated Jun 2010) -- Importing optparse will issue
by default *are* displayed. a PendingDeprecationWarning, which is not displayed by default.
Though this is slower than the usual deprecation process, it seems * Python 3.3 (estimated Jan 2012) -- Importing optparse will issue
prudent to avoid producing any casually visible Deprecation warnings a PendingDeprecationWarning, which is not displayed by default.
until Python 3.X has had some additional time to attract developers.
* 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 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 result relies on traditional ``%(foo)s`` style string formatting. It
has been suggested that it might be better to use the new style has been suggested that it might be better to use the new style
``{foo}`` string formatting [13]_. This seems like a good idea, but ``{foo}`` string formatting [13]_. There was some discussion about
would break backwards compatibility for existing argparse-based how best to do this for modules in the standard library [14]_ and
scripts unless we can come up with a way to reasonably support both several people are developing functions for automatically converting
syntaxes. %-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 References
@ -207,6 +300,15 @@ References
.. [13] use {}-formatting instead of %-formatting .. [13] use {}-formatting instead of %-formatting
(http://bugs.python.org/msg89279) (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 Copyright
========= =========