Python 的 argh 库:在帮助消息中保留文档字符串格式 [英] 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 库:在帮助消息中保留文档字符串格式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！