[Python-Dev] updated PEP 389: argparse (original) (raw)

Steven Bethard steven.bethard at gmail.com
Sat Oct 24 21:10:34 CEST 2009

Sorry for the delay, but I've finally updated PEP 389, the argparse PEP, based on all the feedback from python-dev. The full PEP is below, but in short, the important changes are:

Steve

PEP: 389 Title: argparse - new command line parsing module Version: Revision:75674Revision: 75674 Revision:75674 Last-Modified: Date:2009−10−2412:01:49−0700(Sat,24Oct2009)Date: 2009-10-24 12:01:49 -0700 (Sat, 24 Oct 2009) Date:2009−10−2412:01:49−0700(Sat,24Oct2009) Author: Steven Bethard <steven.bethard at gmail.com> Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 25-Sep-2009 Python-Version: 2.7 and 3.2 Post-History: 27-Sep-2009, 24-Oct-2009

Abstract

This PEP proposes inclusion of the argparse [1]_ module in the Python standard library in Python 2.7 and 3.2.

Motivation

The argparse module is a command line parsing library which provides more functionality than the existing command line parsing modules in the standard library, getopt [2]_ and optparse [3]_. It includes support for positional arguments (not just options), subcommands, required options, options syntaxes like "/f" and "+rgb", zero-or-more and one-or-more style arguments, and many other features the other two lack.

The argparse module is also already a popular third-party replacement for these modules. It is used in projects like IPython (the Scipy Python shell) [4], is included in Debian testing and unstable [5], and since 2007 has had various requests for its inclusion in the standard library [6]_ [7]_ [8]_. This popularity suggests it may be a valuable addition to the Python libraries.

Why aren't getopt and optparse enough?

One argument against adding argparse is that thare are "already two different option parsing modules in the standard library" [9]_. The following is a list of features provided by argparse but not present in getopt or optparse:

Why isn't the functionality just being added to optparse?

Clearly all the above features offer improvements over what is available through optparse. A reasonable question then is why these features are not simply provided as patches to optparse, instead of introducing an entirely new module. In fact, the original development of argparse intended to do just that, but because of various fairly constraining design decisions of optparse, this wasn't really possible. Some of the problems included:

Because of issues like these, which made it unreasonably difficult for argparse to stay compatible with the optparse APIs, argparse was developed as an independent module. Given these issues, merging all the argparse features into optparse with no backwards incompatibilities seems unlikely.

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:

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 ..

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]. 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:

Out of Scope: Various Feature Requests

Several feature requests for argparse were made in the discussion of this PEP:

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

.. [1] argparse (http://code.google.com/p/argparse/)

.. [2] getopt (http://docs.python.org/library/getopt.html)

.. [3] optparse (http://docs.python.org/library/optparse.html)

.. [4] argparse in IPython (http://mail.scipy.org/pipermail/ipython-dev/2009-April/005102.html)

.. [5] argparse in Debian (http://packages.debian.org/search?keywords=python-argparse)

.. [6] 2007-01-03 request for argparse in the standard library (http://mail.python.org/pipermail/python-list/2007-January/592646.html)

.. [7] 2009-06-09 request for argparse in the standard library (http://bugs.python.org/issue6247)

.. [8] 2009-09-10 request for argparse in the standard library (http://mail.python.org/pipermail/stdlib-sig/2009-September/000342.html)

.. [9] Fredrik Lundh response to [6]_ (http://mail.python.org/pipermail/python-list/2007-January/592675.html)

.. [10] optparse variable args (http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments)

.. [11] parser.largs and parser.rargs (http://docs.python.org/library/optparse.html#how-callbacks-are-called)

.. [12] take_action values argument (http://docs.python.org/library/optparse.html#adding-new-actions)

.. [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

This document has been placed in the public domain.

.. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 coding: utf-8 End:

More information about the Python-Dev mailing list