使用Python的optparse模块时如何遵守PEP 257文档字符串? [英] How to comply to PEP 257 docstrings when using Python's optparse module?

问题描述

根据 PEP 257 该文档字符串命令行脚本应该是其用法消息.

According to PEP 257 the docstring of command line script should be its usage message.

脚本的文档字符串(a 独立程序)应该可用 作为其使用情况"消息，打印时 脚本调用不正确 或缺少论点(或可能与 一个"-h"选项，代表帮助").这样的 docstring应该记录脚本的 功能和命令行语法， 环境变量和文件. 使用情况消息可能相当详尽 (几个屏幕已满)，并且应该 足以让新用户使用 正确地命令，以及 完整快速参考所有 选项和参数 经验丰富的用户.

The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's function and command line syntax, environment variables, and files. Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.

所以我的文档字符串看起来像这样:

So my docstring would look something like this:

<tool name> <copyright info>

Usage: <prog name> [options] [args]

some text explaining the usage...

Options:
  -h, --help  show this help message and exit
   ...

现在，我想使用optparse模块. optparse生成选项"部分和解释命令行语法的用法":

Now I want to use the optparse module. optparse generates the "Options" sections and a "usage" explaining the command line syntax:

from optparse import OptionParser

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

因此，使用"-h"标志调用脚本将打印:

So calling the script with the "-h" flag prints:

Usage: script.py [options]

Options:
    -h, --help  show this help message and exit

可以修改如下:

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

结果

Usage: script.py [options] [args]

some text explaining the usage...

Options:
  -h, --help  show this help message and exit

但是我如何在这里使用文档字符串?将文档字符串作为使用消息传递有两个问题.

But how can I use the docstring here? Passing the docstring as the usage message has two problems.

1. optparse如果文档字符串不是以"Usage:"开头，则将"Usage:"附加到文档字符串中.
2. 占位符'％prog'必须在文档字符串中使用

结果

根据答案，似乎没有办法重用optparse模块想要的文档字符串.因此，剩下的选项是手动解析文档字符串并构造OptionParser. (所以我会接受S.Loot的回答)

According to the answers it seems that there is no way to reuse the docstring intended by the optparse module. So the remaining option is to parse the docstring manually and construct the OptionParser. (So I'll accept S.Loot's answer)

用法:"部分由IndentedHelpFormatter引入，可以用OptionParser .__ init __()中的formatter参数代替.

The "Usage: " part is introduced by the IndentedHelpFormatter which can be replaced with the formatter parameter in OptionParser.__init__().

推荐答案

选择1:复制并粘贴.不是DRY，但可行.

Choice 1: Copy and paste. Not DRY, but workable.

选择2:解析您自己的文档字符串以删除描述段落.它始终是第二段，因此可以在'\ n \ n'上分割.

Choice 2: Parse your own docstring to strip out the description paragraph. It's always paragraph two, so you can split on '\n\n'.

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

由于optparse会生成用法，因此您可能不想为其提供用法语句.您的用法版本可能是错误的.如果您坚持要为optparse提供用法字符串，那么我将留给读者练习，以练习如何从上面产生的usage字符串的开头删除"Usage: ".

Since optparse generates usage, you may not want to supply the usage sentence to it. Your version of the usage my be wrong. If you insist on providing a usage string to optparse, I'll leave it as an exercise for the reader to work out how to remove "Usage: " from the front of the usage string produced above.

这篇关于使用Python的optparse模块时如何遵守PEP 257文档字符串?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！