Updates to argparse PEP based on python-dev feedback.
This commit is contained in:
parent
4a40d09d74
commit
096c0e1222
154
pep-0389.txt
154
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:
|
||||
|
||||
* Python 3.3 -- Same as above
|
||||
The optparse module is deprecated, and has been replaced by the
|
||||
argparse module.
|
||||
|
||||
* Python 3.4 -- Deprecation warnings for getopt and optparse, which
|
||||
by default *are* displayed.
|
||||
* 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.
|
||||
|
||||
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.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.
|
||||
|
||||
|
||||
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
|
||||
=========
|
||||
|
|
Loading…
Reference in New Issue