帮助页面

单击可以轻松记录您的命令行工具。对于大多数事情，单击会自动为您生成帮助页面。通过设计，文本是可定制的，但布局不是。

帮助文本

命令和选项接受帮助参数。对于命令，如果提供，则会自动使用该函数的文档字符串。

简单例子：

@click.command()
@click.argument('name')
@click.option('--count', default=1, help='number of greetings')
def hello(name: str, count: int):
    """This script prints hello and a name one or more times."""
    for x in range(count):
        if name:
            click.echo(f"Hello {name}!")
        else:
            click.echo("Hello!")

$ hello --help
Usage: hello [OPTIONS] NAME

  This script prints hello and a name one or more times.

Options:
  --count INTEGER  number of greetings
  --help           Show this message and exit.

命令简短帮助

对于子命令，会生成一个简短的帮助片段。默认情况下，这是文档字符串的第一句话。如果太长，那么它会将无法容纳在一条线上的内容椭圆化 ... . 简短的帮助片段也可以被重写 short_help :

@click.group()
def cli():
    """A simple command line tool."""

@cli.command('init', short_help='init the repo')
def init():
    """Initializes the repository."""

$ cli --help
Usage: cli [OPTIONS] COMMAND [ARGS]...

  A simple command line tool.

Options:
  --help  Show this message and exit.

Commands:
  init  init the repo

命令摘要帮助

帮助附录打印在帮助的末尾，对于显示示例命令用法或引用其他帮助资源非常有用。

@click.command(
    epilog='See https://example.com for more details',
    )
def init():
    """Initializes the repository."""

$ init --help
Usage: init [OPTIONS]

  Initializes the repository.

Options:
  --help  Show this message and exit.

  See https://example.com for more details

记录参数

click.argument 不持 help 参数.这遵循了Unix命令行工具的惯例，即仅对必要的事情使用参数，并按名称将它们记录在命令帮助文本中。然后应该通过doc字符串完成这一操作。

一个简短的例子：

@click.command()
@click.argument('filename')
def touch(filename):
    """Print FILENAME."""
    click.echo(filename)

$ touch --help
Usage: touch [OPTIONS] FILENAME

  Print FILENAME.

Options:
  --help  Show this message and exit.

或者更明确地说：

@click.command()
@click.argument('filename')
def touch(filename):
    """Print FILENAME.

    FILENAME is the name of the file to check.
    """
    click.echo(filename)

$ touch --help
Usage: touch [OPTIONS] FILENAME

  Print FILENAME.

  FILENAME is the name of the file to check.

Options:
  --help  Show this message and exit.

显示收件箱

要控制默认值的外观，请通过 show_default .

@click.command()
@click.option('--n', default=1, show_default=False, help='number of dots')
def dots(n):
    click.echo('.' * n)

$ dots --help
Usage: dots [OPTIONS]

Options:
  --n INTEGER  number of dots
  --help       Show this message and exit.

对于单选项布尔标志，如果默认值为False，即使show默认值为True，默认值也会保持隐藏。

@click.command()
@click.option('--n', default=1, show_default=True)
@click.option("--gr", is_flag=True, show_default=True, default=False, help="Greet the world.")
@click.option("--br", is_flag=True, show_default=True, default=True, help="Add a thematic break")
def dots(n, gr, br):
    if gr:
        click.echo('Hello world!')
    click.echo('.' * n)
    if br:
        click.echo('-' * n)

$ dots --help
Usage: dots [OPTIONS]

Options:
  --n INTEGER  [default: 1]
  --gr         Greet the world.
  --br         Add a thematic break  [default: True]
  --help       Show this message and exit.

Click的包裹行为

Click的默认换行忽略单个新行，并根据终端的宽度重新换行，最多80个字符。在这个例子中，请注意第二组三行代码是如何重新包装成一个段落的。

@click.command()
def cli():
    """
    This is a very long paragraph and as you
    can see wrapped very early in the source text
    but will be rewrapped to the terminal width in
    the final output.

    This is
    a paragraph
    that is compacted.
    """

$ cli --help
Usage: cli [OPTIONS]

  This is a very long paragraph and as you can see wrapped very early in the
  source text but will be rewrapped to the terminal width in the final output.

  This is a paragraph that is compacted.

Options:
  --help  Show this message and exit.

逃离Click ' s Wrapping

有时，Click的包装可能会成为一个问题，例如在显示新元素很重要的代码示例时。通过添加仅包含的行，可以逐段避免此行为 \b .的 \b 从呈现的帮助文本中删除。

例子：

@click.command()
def cli():
    """First paragraph.

    \b
    This is
    a paragraph
    without rewrapping.

    And this is a paragraph
    that will be rewrapped again.
    """

$ cli --help
Usage: cli [OPTIONS]

  First paragraph.

  This is
  a paragraph
  without rewrapping.

  And this is a paragraph that will be rewrapped again.

Options:
  --help  Show this message and exit.

要更改渲染最大宽度，请传递 max_content_width 当调用命令时。

cli(max_content_width=120)

截断帮助文本

点击获得 Command 来自文档字符串的帮助文本。如果您不想包含部分文档字符串，请添加 \f 逸出标记以让单击在标记后面截断帮助文本。

例子：

@click.command()
def cli():
    """First paragraph.
    \f

    Words to not be included.
    """

$ cli --help
Usage: cli [OPTIONS]

  First paragraph.

Options:
  --help  Show this message and exit.

占位符/ Meta变量

默认占位符变量 (meta variable ）是带下划线的参数名称。这可以更改为命令和参数， options_metavar 和 metavar 夸格斯。

# This controls entry on the usage line.
@click.command(options_metavar='[[options]]')
@click.option('--count', default=1, help='number of greetings',
              metavar='<int>')
@click.argument('name', metavar='<name>')
def hello(name: str, count: int) -> None:
    """This script prints 'hello <name>' a total of <count> times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

例子：

$ hello --help
Usage: hello [[options]] <name>

  This script prints 'hello <name>' a total of <count> times.

Options:
  --count <int>  number of greetings
  --help         Show this message and exit.

帮助参数自定义

对于任何命令，单击都会自动添加帮助参数。默认值为 --help 但是可以被上下文设置覆盖 help_option_names . Click还对默认帮助参数执行自动冲突解决，因此如果命令本身实现名为 help 那么默认帮助将不会运行。

此示例将默认参数更改为 -h 和 --help --help ：

CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])

@click.command(context_settings=CONTEXT_SETTINGS)
def cli():
    pass

$ cli -h
Usage: cli [OPTIONS]

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