记录脚本¶
Click可以很容易地记录命令行工具。首先，它会自动为您生成帮助页面。虽然目前还不能自定义它们的布局，但是可以更改所有文本。
帮助文本¶
命令和选项接受帮助参数。在命令的情况下，函数的docstring将自动使用（如果提供）。
简单例子：
@click.command()
@click.option('--count', default=1, help='number of greetings')
@click.argument('name')
def hello(count, name):
"""This script prints hello NAME COUNT times."""
for x in range(count):
click.echo(f"Hello {name}!")
看起来像是：
$ hello --help
Usage: hello [OPTIONS] NAME
This script prints hello NAME COUNT times.
Options:
--count INTEGER number of greetings
--help Show this message and exit.
记录参数¶
click.argument() 不采取 help 参数。这是遵循Unix工具的一般约定，即只对最必要的事情使用参数，并通过按名称引用参数来将它们记录在命令帮助文本中。
您可能更喜欢在描述中引用参数：
@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.
有关更多示例，请参见中的示例 参数 .
防止重击¶
Click的默认行为是根据终端的宽度重新排列文本。在某些情况下，这可能成为一个问题。主要问题是在显示代码示例时，换行很重要。
通过单独添加一行 \b 里面有逃生标志。此行将从帮助文本中删除，并且将禁用重新排序。
例子：
@click.command()
def cli():
"""First paragraph.
This is a very long second 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.
\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 very long second 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
without rewrapping.
And this is a paragraph that will be rewrapped again.
Options:
--help Show this message and exit.
截断帮助文本¶
Click从函数docstrings获取命令帮助文本。但是，如果已经使用docstrings来记录函数参数，您可能不希望在帮助文本中看到：param:和：return:行。
你可以使用 \f 转义标记，让Click截断标记后的帮助文本。
例子：
@click.command()
@click.pass_context
def cli(ctx):
"""First paragraph.
This is a very long second
paragraph and not correctly
wrapped but it will be rewrapped.
\f
:param click.core.Context ctx: Click context.
"""
看起来像是：
$ cli --help
Usage: cli [OPTIONS]
First paragraph.
This is a very long second paragraph and not correctly wrapped but it will be
rewrapped.
Options:
--help Show this message and exit.
元变量¶
选项和参数接受 metavar 可以更改帮助页中的元变量的参数。默认版本是参数名（大写，带下划线），但可以根据需要进行不同的注释。这可以在所有级别进行定制：
@click.command(options_metavar='<options>')
@click.option('--count', default=1, help='number of greetings',
metavar='<int>')
@click.argument('name', metavar='<name>')
def hello(count, name):
"""This script prints hello <name> <int> times."""
for x in range(count):
click.echo(f"Hello {name}!")
例子：
$ hello --help
Usage: hello <options> <name>
This script prints hello <name> <int> times.
Options:
--count <int> number of greetings
--help Show this message and exit.
命令简短帮助¶
对于命令，将生成一个简短的帮助片段。默认情况下，它是命令帮助消息的第一句话，除非它太长。也可以覆盖：
@click.group()
def cli():
"""A simple command line tool."""
@cli.command('init', short_help='init the repo')
def init():
"""Initializes the repository."""
@cli.command('delete', short_help='delete the repo')
def delete():
"""Deletes the repository."""
看起来像是：
$ repo.py
Usage: repo.py [OPTIONS] COMMAND [ARGS]...
A simple command line tool.
Options:
--help Show this message and exit.
Commands:
delete delete the repo
init init the repo
帮助参数自定义¶
Changelog
2.0 新版功能.
帮助参数是以一种非常特殊的方式在click中实现的。与常规参数不同的是，它通过Click任意命令自动添加，并执行自动冲突解决。默认情况下，它被称为 --help 但这是可以改变的。如果命令本身实现了同名参数，则默认帮助参数将停止接受该参数。有一个上下文设置可用于重写调用的帮助参数的名称 help_option_names .
此示例将默认参数更改为 -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.
