5

PEP 257によると、コマンド ライン スクリプトの docstring はその使用法メッセージである必要があります。

スクリプト (スタンドアロン プログラム) の docstring は、その "使用法" メッセージとして使用できる必要があります。このメッセージは、スクリプトが誤った引数または欠落した引数で (または "ヘルプ" の場合は "-h" オプションで) 呼び出されたときに出力されます。このような docstring は、スクリプトの関数とコマンド ライン構文、環境変数、およびファイルを文書化する必要があります。使用方法のメッセージはかなり複雑 (数画面いっぱい) で、新しいユーザーがコマンドを適切に使用するのに十分なだけでなく、上級ユーザー向けのすべてのオプションと引数の完全なクイック リファレンスでもあります。

したがって、私のdocstringは次のようになります。

<ツール名> <著作権情報>

使用法: <プログラム名> [オプション] [引数]

使用法を説明するテキスト...

オプション:
  -h, --help このヘルプ メッセージを表示して終了します
   ...

次に、optparse モジュールを使用します。optparse は、「オプション」セクションと、コマンド ライン構文を説明する「使用方法」を生成します。

from optparse import OptionParser

if __name__ == "__main__":
    parser = OptionParser()
    (options, args) = parser.parse_args()

したがって、「-h」フラグを指定してスクリプトを呼び出すと、次のように出力されます。

使用法: script.py [オプション]

オプション:
    -h, --help このヘルプ メッセージを表示して終了します

これは次のように変更できます。

parser = OptionParser(usage="Usage: %prog [options] [args]",
                      description="some text explaining the usage...")

その結果、

使用法: script.py [オプション] [引数]

使用法を説明するテキスト...

オプション:
  -h, --help このヘルプ メッセージを表示して終了します

しかし、ここでdocstringをどのように使用できますか? 使用法メッセージとして docstring を渡すことには、2 つの問題があります。

  1. optparse は、"Usage: " で始まらない場合、docstring に "Usage: " を追加します。
  2. プレースホルダ '%prog' をドキュメント文字列で使用する必要があります

結果

回答によると、optparse モジュールが意図する docstring を再利用する方法はないようです。したがって、残りのオプションは、docstring を手動で解析し、OptionParser を構築することです。（だから私はS.Lootの答えを受け入れます）

"Usage: " の部分は IndentedHelpFormatter によって導入され、OptionParser.__init__() の formatter パラメータに置き換えることができます。

4

3 に答える 3

6

私はあなたが望むことを正確に行うためのモジュールdocoptを書きました.docstringに使用法メッセージを書き、DRYのままにしてください。また、usage-message に基づいてパーサーを生成するため、面倒なOptionParserコードの記述をまったく回避できます。docopt

それをチェックしてください：http://github.com/docopt/docopt

"""Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship [<name>] move <x> <y> [--speed=<kn>]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [--moored|--drifting]
  naval_fate.py -h | --help
  naval_fate.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='Naval Fate 2.0')
    print(arguments)
于 2012-04-08T19:02:58.483 に答える
4

選択肢 1: コピーして貼り付けます。DRYではありませんが、実行可能です。

選択肢 2: 独自の docstring を解析して、説明の段落を削除します。これは常に段落 2 であるため、'\n\n' で分割できます。

usage, description= __doc__.split('\n\n')[:2]

は使用法を生成するためoptparse、使用法文を提供したくない場合があります。あなたの使い方のバージョンは間違っているかもしれません。に使用文字列を提供することを主張する場合は、上記で生成された文字列の先頭optparseから削除する方法を読者が解決するための演習として残します。"Usage: "usage

于 2009-08-11T12:21:22.527 に答える
1

このPEPのアドバイスについては合理的である必要があると思います。モジュールをそのままにし__doc__て、長い使用法を要約した短い説明のままにしておくのは問題ないと思います。しかし、あなたが完璧主義者なら：

'''<tool name>

The full description and usage can be generated by optparse module.

Description: ...

'''

...

# Generate usage and options using optparse.
usage, options = ... 

# Modify the docstring on the fly.
docstring = __doc__.split('\n\n')
docstring[1:2] = [__license__, usage, options]
__doc__ = '\n\n'.join(docstring)
于 2009-08-11T16:57:39.333 に答える