Python的argh库:在帮助消息中保留docstring格式 [英] Python’s argh library: preserve docstring formatting in help message

问题描述

在寻找更快的方法来解析脚本中的命令行参数时，我遇到了 argh库.

While searching for faster ways to parse command-line arguments in my scripts I came across the argh library.

我真的很喜欢argh的功能，但是遇到了一个缺点，使我无法使用它，这与我调用-help选项时显示的默认帮助消息有关: 默认情况下，函数的文档字符串显示在参数列表的顶部.很好，但是初始格式丢失了.例如，请参见以下示例脚本

I really like the features of argh but I’ve encountered one drawback that stops me from using it, and this has to do with the default help message that gets displayed if I’m invoking the —help option: per default the function’s docstring is displayed on top of the arguments list. This is great, however the initial formatting is lost. See, for example, the following example script

import argh

def func(foo=1, bar=True):
    """Sample function.

        Parameters:
            foo: float
                An example argument.
            bar: bool
                Another argument.
    """
    print foo, bar

argh.dispatch_command(func, argv=['-h'])

这将导致以下输出

usage: script.py [-h] [-f FOO] [-b]

Sample function. Parameters: foo: float An example argument. bar: bool Another
argument.

optional arguments:
  -h, --help         show this help message and exit
  -f FOO, --foo FOO
  -b, --bar

是否有一种(简单的)方法来获得如下所示的输出?

Is there an (easy) way to get an output like the following?

usage: script.py [-h] [-f FOO] [-b]

Sample function.

    Parameters:
        foo: float
            An example argument.
        bar: bool
            Another argument.

optional arguments:
  -h, --help         show this help message and exit
  -f FOO, --foo FOO
  -b, --bar

我宁愿不使用批注来定义参数帮助消息，因为这将要求我在每次更改时都更改函数的文档字符串和帮助文本.

I'd prefer to not use annotations to define the argument help messages since that would require me to alter both the function's docstring AND the help text each time there is something to change.

推荐答案

我不熟悉argh，但显然它是argparse的包装.我的猜测是它将函数__doc__用作解析器的description，例如

I'm not familiar with argh, but apparently it is a wrapper to argparse. My guess is that it is taking your function __doc__, and making it the description of a parser, e.g.

parser = argparse.ArgumentParser(description=func.__doc__)

https://docs.python.org/2.7/library/argparse.html#argparse.RawDescriptionHelpFormatter

argparse的RawDescriptionHelpFormatter可以按原样显示说明.

argparse has a RawDescriptionHelpFormatter that displays the description as is.

parser = argparse.ArgumentParser(description=func.__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter)

所以问题是，有没有办法让argh使用此格式化程序?

So the question is, is there a way of getting argh to use this formatter?

此argparse脚本产生所需的帮助:

This argparse script produces the help that you want:

import argparse

def func(foo=1, bar=True):
    """Sample function.

        Parameters:
            foo: float
                An example argument.
            bar: bool
                Another argument.
    """
    print foo, bar

parser = argparse.ArgumentParser(prog='script.py',
    description=func.__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('-f', '--foo', type=float)
parser.add_argument('-b', '--bar', action='store_false')
parser.print_help()

---

在argh/dispatching.py

def dispatch_command(function, *args, **kwargs):
    ...
    parser = argparse.ArgumentParser(formatter_class=PARSER_FORMATTER)
    set_default_command(parser, function)
    dispatch(parser, *args, **kwargs)

因此您可以设置:

PARSER_FORMATTER = argparse.RawDescriptionHelpFormatter

或编写您自己的函数:

def raw_dispatch_command(function, *args, **kwargs):
    ...
    parser = argparse.ArgumentParser(formatter_class=argparse.RawDescriptionHelpFormatter)
    set_default_command(parser, function)
    dispatch(parser, *args, **kwargs)

这篇关于Python的argh库:在帮助消息中保留docstring格式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！