PEP 389: argparse - 新しいコマンドラインparseモジュール ========================================================== 原文: http://www.python.org/dev/peps/pep-0389/ 訳注: argparseの公式ドキュメントは http://argparse.googlecode.com/svn/trunk/doc/index.html +----------------+--------------------------------------------+ | PEP | 389 | +----------------+--------------------------------------------+ | Title | argparse - New Command Line Parsing Module | +----------------+--------------------------------------------+ | Version | 78618 | +----------------+--------------------------------------------+ | Last-Modified | 2010-03-03 03:55:24 +0100(Wed, 03 Mar 2010)| +----------------+--------------------------------------------+ | Author | Steven Bethard | +----------------+--------------------------------------------+ | Status | Accepted | +----------------+--------------------------------------------+ | 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 | +----------------+--------------------------------------------+ .. Acceptance ========== 承認 ---------- .. This PEP was approved by Guido on python-dev on February 21, 2010 [17]_. このPEPはGuidoによって、2010年4月21日のpython-devにて承認されました。 [17]_ .. Abstract ------== 概要 -------- .. This PEP proposes inclusion of the argparse [1]_ module in the Python standard library in Python 2.7 and 3.2. このPEPでは、Python 2.7と3.2で標準ライブラリに加わったargparse [1]_ モ ジュールに関して説明します。 .. 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. argparseモジュールは既存のコマンドライン引数を解釈するモジュールである getopt [2]_ とoptparse [3]_ よりも高機能なparseライブラリです。argparseは、 単なるオプションだけでなく固定引数(positional argument)、サブコマンド、必 須オプション、"/f"や"+rgb"といったオプション文法、0以上や1以上という形式 の引数、その他getoptとoptparseが持っていない多数の機能を提供します。 .. 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. argparseモジュールはこれらのモジュールを置き換えるサードパーティ製のモ ジュールとしてすでに人気があります。argparseはIPython(Scipy Python Shell) [4]_ で使われており、Debianのtestingとusntable [5]_ に含まれてお り、2007年から標準ライブラリに組み込むようたくさんのリクエストを受け取っ て来ました [6]_ [7]_ [8]_ 。これはPythonのライブラリに追加する価値がある ことを示唆しています。 .. Why aren't getopt and optparse enough? ====================================== なぜgetoptとoptparseは十分ではないの? --------------------------------------- .. 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: argparseに対する議論の一つとして「すでにもう二つの異なるOptionパーザがあ るじゃないか [9]_ 」というものがあります。以下にargparseにはあるが他の getoptとoptparseにはない機能のリストを記します。 .. * While it is true there are two *option* parsing libraries, there are no full command line parsing libraries -- both getopt and optparse support only options and have no support for positional arguments. The argparse module handles both, and as a result, is able to generate better help messages, avoiding redundancies like the ``usage=`` string usually required by optparse. * 既に二つの*option* パーザライブラリがあることは確かですが、完全なコマン ドラインパーズライブラリはありません。getoptとoptparseの両方とも、 optionしかサポートしておらず、固定引数(positional argument)をサポートし ていません。argparseは両方を扱うことができ、結果として、より良いヘルプ メッセージを生成でき、optparseで必要になってくる ``usage=`` 文字列といっ た冗長な記述を避けられます。 .. * The argparse module values practicality over purity. Thus, argparse allows required options and customization of which characters are used to identify options, while optparse explicitly states "the phrase 'required option' is self-contradictory" and that the option syntaxes ``-pf``, ``-file``, ``+f``, ``+rgb``, ``/f`` and ``/file`` "are not supported by optparse, and they never will be". * argparseモジュールは純正よりも実用性を評価します。従って、optparseが 「 'required option'は自己矛盾であり、 ``-pf``, ``-file``, ``+f``, ``+rgb``, ``/f``, ``/file`` はoptparseでサポートされず、今後もサポートさ れない」と明確に記載されているのと異なり、argparseは必要となるオプショ ンとオプションを識別するのに使われる文字のカスタマイズができます。 .. * The argparse module allows options to accept a variable number of arguments using ``nargs='?'``, ``nargs='*'`` or ``nargs='+'``. The optparse module provides an untested recipe for some part of this functionality [10]_ but admits that "things get hairy when you want an option to take a variable number of arguments." * argparseは ``nargs='?'``, ``nargs='*'`` あるいは ``nargs='+'`` を使って 可変長引数を記述できます。optparseはこの機能の一部をテストされていない レシピを使って提供していますが [10]_ 、「可変長引数を使おうとするとやば いことになりかねないよ」と認めています。 .. * The argparse module supports subcommands, where a main command line parser dispatches to other command line parsers depending on the command line arguments. This is a common pattern in command line interfaces, e.g. ``svn co`` and ``svn up``. * argparseはサブコマンドをサポートしています。これは、主となるコマンドラ インパーザが依存する引数を他のコマンドラインパーザに送ります。これは、 コマンドラインインタフェースではよく使われています。 例: ``svn co`` や ``svn up`` .. Why isn't the functionality just being added to optparse? ========================================================= 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: 明らかに、以上述べてきた機能追加はoptparseに追加して実現できる許容量を 越えています。利にかなった質問は、これらの機能はまったく新しいモジュー ルとしてではなく、なぜ単純にoptparseへのpatchとして提供されないのですか、 です。事実、argparseの開発初期段階はpatchとして行われていたのですが、 optparseの設計からくるさまざまな制約により、これは不可能だったのです。 以下に示すいくつかの問題がありました。 .. * The optparse module exposes the internals of its parsing algorithm. In particular, ``parser.largs`` and ``parser.rargs`` are guaranteed to be available to callbacks [11]_. This makes it extremely difficult to improve the parsing algorithm as was necessary in argparse for proper handling of positional arguments and variable length arguments. For example, ``nargs='+'`` in argparse is matched using regular expressions and thus has no notion of things like ``parser.largs``. * optparseモジュールは内部のパースアルゴリズムを公開しています。特に、 ``parser.largs`` と ``parser.rargs`` はコールバックがあることを前提とし ています [11]_ 。このことは、固定引数や可変長引数に対応するために argparseでパースアルゴリズムを改良することを阻害しています。例えば、 argparseで ``nargs='+'`` を使って正規表現にマッチさせる時は、 ``parser.largs`` などを使う意図はありません。(訳注:訳に自信なし) .. * The optparse extension APIs are extremely complex. For example, just to use a simple custom string-to-object conversion function, you have to subclass ``Option``, hack class attributes, and then specify your custom option type to the parser, like this:: * optparseの拡張APIは非常に複雑です。例えば、簡単なstringからobjectへと 変換する自作の関数を使おうとするときでも、 ``Option`` サブクラスを作 り、クラス変数をいじり、自作のオプションタイプをparserに指定する必要 があるのです。例を示します。:: class MyOption(Option): TYPES = Option.TYPES + ("mytype",) TYPE_CHECKER = copy(Option.TYPE_CHECKER) TYPE_CHECKER["mytype"] = check_mytype parser = optparse.OptionParser(option_class=MyOption) parser.add_option("-m", type="mytype") .. For comparison, argparse simply allows conversion functions to be used as ``type=`` arguments directly, e.g.:: 比較すると、argparseは単に変換関数を ``type=`` 引数に直接与えるだけで済み ます。 :: parser = argparse.ArgumentParser() parser.add_option("-m", type=check_mytype) .. But given the baroque customization APIs of optparse, it is unclear how such a feature should interact with those APIs, and it is quite possible that introducing the simple argparse API would break existing custom Option code. 与えられたoptparseの古典的なカスタムAPIでは、このような機能がこれらの APIをどのように使えばいいのか不明確です。そのため、単純なargparseのAPI を導入すると、既存の自作のOptionコードを壊す可能性が高いです。 .. * Both optparse and argparse parse command line arguments and assign them as attributes to an object returned by ``parse_args``. However, the optparse module guarantees that the ``take_action`` method of custom actions will always be passed a ``values`` object which provides an ``ensure_value`` method [12]_, while the argparse module allows attributes to be assigned to any object, e.g.:: * optparseとargparseは両方共コマンドラインの引数をパーズし、 ``parse_args`` によって返されたオブジェクトの属性を設定します。しかし、 optparseモジュールは自作のアクションである ``take_action`` メソッドに ``ensure_value`` メソッドを持つ ``values`` オブジェクトが常に渡されるこ とを前提としています [12]_ 。一方、argparseはどんなオブジェクトにでも属 性を設定することができます。例 :: 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 of a ``Values`` instance will break existing custom actions that depend on the ``ensure_value`` method. optparseをどんなオブジェクトでも受け入れるように変更することは難しいこ とでした。なぜなら、単に ``Values`` インスタンスの代わりに ``foo_object`` を渡すことは ``ensure_value`` メソッドに依存している既存 の自作アクションを壊すからです。 .. 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. このような問題により、argparseがoptparse APIと互換性を保ったままにする ことは難しく、argparseは独立したモジュールとして開発されました。付け加 えると、同じ理由によりargparseの全ての機能を後方互換性を保ったまま optparseに入れることは考えられません。 .. Deprecation of optparse ======================= optparseの廃止 ----------------------- .. Because all of optparse's features are available in argparse, the optparse module will be deprecated. However, because of the widespread use of optparse, the deprecation strategy contains only documentation changes and warnings that will not be visible by default: argparseで、optparseの全ての機能が実現されているため、optparseモジュール は将来的に廃止されます。しかし、optparseは広く使用されているため、廃止の 道筋は単に文書の変更だけであり、標準では警告は表示されません。 .. * Python 2.7+ and 3.2+ -- The following note will be added to the .. optparse documentation: .. The optparse module is deprecated and will not be developed further; development will continue with the argparse module. * Python 2.7以降と3.2以降 -- optparseの文章に以下の注意書きが付け加えら れます。 optparseモジュールは廃止され、以降開発されません。以降の開発は argparseモジュールで継続されます。 .. * 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 2.7以降 -- もしPython 3の互換性フラグ(``-3``)が与えられた場合、 optparseはDeprecationWarningという警告を出します。そうでなければ、警告 はなにも出ません。 .. * Python 3.2+ -- Importing optparse will issue a PendingDeprecationWarning, which is not displayed by default. * Python 3.2以上 -- optparseをimportすると、PendingDeprecationWarningと いう、標準では表示されない警告が出ます。 .. Note that no removal date is proposed for optparse. optparseが削除される日付に関してはなにも決まっていないことに注意してくだ さい。 .. Updates to getopt documentation =============================== getoptの文書の更新 ------------------------------- .. 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. getoptモジュールは廃止されません。しかし、その文書のいくつかの場所では argparseを示すように更新されます。モジュールの先頭には以下の注意書きが 付け加えられます。 :: getoptモジュールはC言語のgetopt関数のAPIに慣れ親しんだユーザのために作 られたコマンドラインオプションのパーズモジュールです。C言語のgetopt関数 に不慣れな、あるいは少ないコード量でより良いヘルプとエラーメッセージを 得たいユーザは、代わりにargparseモジュールを使ってください。 .. 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:: さらに、最後のgetoptの例の後に、以下の注意書きが付け加えられます。 :: 少ないコード量で同等のコマンドラインインタフェースが、argparseモジュールを使うことで得られます。 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. argparseモジュールはPython 2.3から3.2までサポートしますが、そのため、伝統 的な ``%(foo)s`` 形式の文字列フォーマットに依存します。これは新しい形式の ``{foo}`` フォーマットを使うように推奨されています [13]_ 。標準ライブラリ ではこの問題について議論され [14]_ 、何人かは%形式から{}形式に自動的に変 換する機能を開発しています [15]_ [16]_ 。この変換機能が標準ライブラリに付 け加えられた時には、argparseもこの両方のフォーマット形式をサポートします。 .. Rejected: getopt compatibility methods ====================================== getopt互換のメソッドは取り除かれました ----------------------------------------- .. Previously, when this PEP was suggesting the deprecation of getopt as well as optparse, there was some talk of adding a method like:: 以前、このPEPがoptparseと同じくgetoptの廃止も提案したとき、以下のような メソッドの追加に関する議論がありました。 :: 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. * getoptモジュールは廃止されないため、必要性は低いです。 .. * 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. * このメソッドはすでにusageのメッセージを管理しているgetoptユーザが移行 に使うには簡単ではありません。なぜならこのAPIは引数にヘルプメッセージ を追加する機能を提供していないからです。 .. * 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. * getoptが想定しているユーザのうち何人かは、関数を一回だけ呼べばいいとい うことを重要視しています。このAPIでは ``ArgumentParser()`` と ``parse_args()`` の両方を呼ぶ必要があるため、この要求を満たせません。 .. Out of Scope: Various Feature Requests ====================================== スコープ外: 機能要求 -------------------------- .. Several feature requests for argparse were made in the discussion of this PEP: argparseに対する機能要求のいくつかは、この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" * 環境変数からデフォルトの引数を設定する機能 * 設定ファイルからデフォルトの引数を設定する機能 * 現在の"foo subcommand --help"に加えて"foo --help subcommand"を解釈する 機能 .. 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. これらは全て正当な理由がある機能要求ですが、このPEPのスコープ外であり、 argparseのIssue Trackerで議論されます。 .. Discussion: sys.stderr and sys.exit =================================== 議論: sys.stderrとsys.exit ----------------------------------- .. There were some concerns that argparse by default always writes to ``sys.stderr`` 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.stderr``. 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. argparseを使うと、標準では常に ``sys.stderr`` に書き出し、不正な引数が与 えられた時に常に ``sys.exit`` を呼んでいます。これは簡単なコマンドライン インタフェースを提供するargparseのユースケースの大部分にとって期待された 振る舞いです。しかし、いくつかの場合では、argparseがexitしないようにして 欲しかったり、あるいは ``sys.stderr`` 以外に書き出して欲しかったりします。 このような場合、 ``ArgumentParser`` というサブクラスを作り、``exit`` や ``_print_message`` をオーバーライドすることで欲しい機能を実現できます。後 者は文書化されていない実相の詳細ですが、よく使われるようになれば公開しま す。 参考文献 ---------- .. [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=argparse) .. [6] 2007-01-03 request for argparse in the standard library (http://mail.python.org/pipermail/python-list/2007-January/472276.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/1086892.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/pytho .. [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) .. [17] Guido's approval (http://mail.python.org/pipermail/python-dev/2010-February/097839.html) .. Copyright ========== 著作権 ------- .. This document has been placed in the public domain. このドキュメントはパブリック・ドメインに属します。