Question

文档的这一部分列出了所有公共类和函数的完整 API 引用。

装饰器

click.command (name=None, cls=None, **attrs)

创建新的 Command 并将修饰函数用作回调函数。这也将自动附加所有装饰 option() S 和 argument() 作为命令的参数。

命令名默认为函数名。如果要更改该参数，可以将预期名称作为第一个参数传递。

所有关键字参数都转发到基础命令类。

一经装饰，功能就变成了 Command 可以作为命令行实用程序调用或附加到命令的实例 Group .

参数

• name -- 命令的名称。这将默认为函数名，下划线替换为破折号。
• cls -- 要实例化的命令类。默认为 Command .

click.group (name=None, **attrs)

创建新的 Group 具有回调函数。其工作原理与 command() 就这样 cls 参数设置为 Group .

click.argument (*param_decls, **attrs)

将参数附加到命令。所有位置参数都作为参数声明传递给 Argument ；所有关键字参数都是未更改的转发（除非 cls ）这相当于创建 Argument 手动实例并将其附加到 Command.params 名单。

参数

cls -- 要实例化的参数类。默认为 Argument .

click.option (*param_decls, **attrs)

将选项附加到命令。所有位置参数都作为参数声明传递给 Option ；所有关键字参数都是未更改的转发（除非 cls ）这相当于创建 Option 手动实例并将其附加到 Command.params 名单。

参数

cls -- 要实例化的选项类。默认为 Option .

click.password_option (*param_decls, **attrs)

密码提示的快捷方式。

这相当于用 option() 参数如下：

@click.command()
@click.option('--password', prompt=True, confirmation_prompt=True,
              hide_input=True)
def changeadmin(password):
    pass

click.confirmation_option (*param_decls, **attrs)

可通过传递忽略的确认提示的快捷方式 --yes 作为参数。

这相当于用 option() 参数如下：

def callback(ctx, param, value):
    if not value:
        ctx.abort()

@click.command()
@click.option('--yes', is_flag=True, callback=callback,
              expose_value=False, prompt='Do you want to continue?')
def dropdb():
    pass

click.version_option (version=None, *param_decls, **attrs)

添加一个 --version 选项，立即结束程序打印出版本号。这是作为一个热切的选项实现的，它打印版本并退出回调中的程序。

参数

• version -- 要显示的版本号。如果未提供，Click 尝试通过设置工具自动发现。
• prog_name -- 程序的名称（默认为自动检测）
• message -- 要显示的自定义消息，而不是默认消息 ( '%(prog)s, version %(version)s' ）
• others -- 其他所有内容都转发到 option() .

click.help_option (*param_decls, **attrs)

添加一个 --help 选项立即结束程序打印出帮助页。这通常不需要添加，因为在默认情况下，这会添加到所有命令中，除非被抑制。

喜欢 version_option() ，这是作为在回调中打印并退出的热切选项实现的。

所有参数都转发到 option() .

click.pass_context (f)

将回调标记为希望接收当前上下文对象作为第一个参数。

click.pass_obj (f)

类似 pass_context() ，但只将上下文中的对象向前传递 ( Context.obj ）如果该对象表示嵌套系统的状态，则此选项非常有用。

click.make_pass_decorator (object_type, ensure=False)

给定一个对象类型，这将创建一个类似于 pass_obj() 但它不会传递当前上下文的对象，而是查找类型的最内部上下文 object_type() .

这会生成一个大致工作方式如下的装饰器：

from functools import update_wrapper

def decorator(f):
    @pass_context
    def new_func(ctx, *args, **kwargs):
        obj = ctx.find_object(object_type)
        return ctx.invoke(f, obj, *args, **kwargs)
    return update_wrapper(new_func, f)
return decorator

参数

• object_type -- 要传递的对象的类型。
• ensure -- 如果设置为 True 如果一个新对象还没有出现，它将在上下文中被创建和记住。

公用事业

click.echo (message=None, file=None, nl=True, err=False, color=None)

将消息加新行打印到给定文件或 stdout。乍一看，这看起来像 print 函数，但它改进了对处理 Unicode 和二进制数据的支持，无论系统配置多么糟糕，这些数据都不会失败。

主要是指您可以以最合适的方式将二进制数据以及 2.x 和 3.x 上的 Unicode 数据打印到给定文件。这是一个非常无忧无虑的功能，因为它会尽力不失败。从 Click6.0 开始，这包括对 Windows 控制台上的 Unicode 输出的支持。

除此之外，如果 colorama 安装后，echo 函数还将支持对 ansi 代码的巧妙处理。基本上，它将执行以下操作：

• 在窗口上添加对 ANSI 颜色代码的透明处理。
• 如果目标文件不是终端，则自动隐藏 ANSI 代码。

在 6.0 版更改: 从 Click6.0 开始，echo 函数将正确支持 Windows 控制台上的 Unicode 输出。Click 不会以任何方式修改解释器，这意味着 sys.stdout 或者打印语句或函数仍不提供 Unicode 支持。

在 2.0 版更改: 从 2.0 版的 click 开始，如果安装了 echo 函数，它将与 colorama 一起工作。

3.0 新版功能: 这个 err 已添加参数。

在 4.0 版更改: 增加了 color 标志符。

参数

• message -- 要打印的消息
• file -- 要写入的文件（默认为 stdout ）
• err -- 如果设置为 true，则文件默认为 stderr 而不是 stdout . 这比调用更快更容易 get_text_stderr() 你自己。
• nl -- 如果设置为 True （默认值）之后将打印新行。
• color -- 控制终端是否支持 ANSI 颜色。默认为自动检测。

click.echo_via_pager (text_or_generator, color=None)

此函数接受文本并通过 stdout 上特定于环境的 pager 显示它。

在 3.0 版更改: 增加了 color 标志符。

参数

• text_or_generator -- 文本到页面，或者，将文本发送到页面的生成器。
• color -- 控制页导航是否支持 ANSI 颜色。默认为自动检测。

click.prompt (text, default=None, hide_input=False, confirmation_prompt=False, type=None, value_proc=None, prompt_suffix=': ', show_default=True, err=False, show_choices=True)

提示用户输入。这是一个方便的函数，可用于提示用户以后输入。

如果用户通过发送中断信号中止输入，此函数将捕获它并引发 Abort 例外。

7.0 新版功能: 添加了“显示选项”参数。

6.0 新版功能: 在 Windows 上添加了对 cmd.exe 的 Unicode 支持。

4.0 新版功能: 增加了 err 参数。

参数

• text -- 为提示显示的文本。
• default -- 如果没有输入将使用的默认值。如果不提供，它将提示直到中止。
• hide_input -- 如果设置为真，则输入值将隐藏。
• confirmation_prompt -- 要求确认值。
• type -- 用于检查值的类型。
• value_proc -- 如果提供此参数，则调用该函数而不是类型转换来转换值。
• prompt_suffix -- 应添加到提示中的后缀。
• show_default -- 在提示中显示或隐藏默认值。
• err -- 如果设置为 true，则文件默认为 stderr 而不是 stdout 与 Echo 相同。
• show_choices -- 如果传递的类型是选项，则显示或隐藏选项。例如，如果 type 是 day 或 week 的选项，则 show_choices 为 true，text 为“group by”，则提示将为“group by（day，week）：”。

click.confirm (text, default=False, abort=False, prompt_suffix=': ', show_default=True, err=False)

提示确认（是/否问题）。

如果用户通过发送中断信号中止输入，此函数将捕获它并引发 Abort 例外。

4.0 新版功能: 增加了 err 参数。

参数

• text -- 要问的问题。
• default -- 提示的默认值。
• abort -- 如果设置为 True 否定的回答通过引发 Abort .
• prompt_suffix -- 应添加到提示中的后缀。
• show_default -- 在提示中显示或隐藏默认值。
• err -- 如果设置为 true，则文件默认为 stderr 而不是 stdout 与 Echo 相同。

click.progressbar (iterable=None, length=None, label=None, show_eta=True, show_percent=None, show_pos=False, item_show_func=None, fill_char='#', empty_char='-', bar_template='%(label)s [%(bar)s] %(info)s', info_sep=' ', width=36, file=None, color=None)

此函数创建一个可 Iterable 上下文管理器，可用于在显示进度条时迭代某个内容。它将迭代 iterable 或 length 项目（已计数）。当迭代发生时，此函数将向给定的 file （默认为 stdout）并将尝试计算剩余时间等。默认情况下，如果文件不是终端，则不会呈现此进度条。

上下文管理器创建进度条。当输入上下文管理器时，进度条已显示。每次在进度条上迭代时，传递给进度条的 iterable 都是高级的，进度条也会更新。当上下文管理器退出时，将打印新行并在屏幕上完成进度条。

不得进行打印，否则进度条将被无意中损坏。

示例用法：

with progressbar(items) as bar:
    for item in bar:
        do_something_with(item)

或者，如果未指定 ITerable，则可以通过 update() 方法，而不是直接在进度条上迭代。update 方法接受递增条的步数：：

with progressbar(length=chunks.total_bytes) as bar:
    for chunk in chunks:
        process_chunk(chunk)
        bar.update(chunks.bytes)

2.0 新版功能。

4.0 新版功能: 增加了 color 参数。增加了一个 update ProgressBar 对象的方法。

参数

• iterable -- 可重复的 iterable。如果没有提供，则需要长度。
• length -- 要迭代的项数。默认情况下，ProgressBar 将尝试向迭代器询问其长度，这可能有效，也可能无效。如果还提供了 ITerable，则此参数可用于覆盖长度。如果未提供 ITerable，进度条将在该长度的范围内迭代。
• label -- 要显示在进度条旁边的标签。
• show_eta -- 启用或禁用估计时间显示。如果无法确定长度，将自动禁用此选项。
• show_percent -- 启用或禁用百分比显示。默认值为 True 如果 iterable 有一个长度或 False 如果没有。
• show_pos -- 启用或禁用绝对位置显示。默认值为 False .
• item_show_func -- 用当前项调用的函数，它可以返回一个字符串来显示进度条旁边的当前项。请注意，当前项目可以 None 你说什么？
• fill_char -- 用于显示进度条已填充部分的字符。
• empty_char -- 用于显示进度条未填充部分的字符。
• bar_template -- 用作条形图模板的格式字符串。其中的参数是 label 对于标签， bar 对于进度条和 info 对于信息部分。
• info_sep -- 多个信息项（eta 等）之间的分隔符。
• width -- 进度条的宽度（以字符为单位），0 表示整个终端宽度。
• file -- 要写入的文件。如果这不是终端，则只打印标签。
• color -- 控制终端是否支持 ANSI 颜色。默认为自动检测。只有当进度条输出中的任何地方包含 ANSI 代码时，才需要这样做，默认情况下不是这样。

click.clear ()

清除终端屏幕。这将清除终端的整个可见空间，并将光标移到左上角。如果没有连接到终端，这将不起任何作用。

2.0 新版功能。

click.style (text, fg=None, bg=None, bold=None, dim=None, underline=None, blink=None, reverse=None, reset=True)

使用 ANSI 样式设置文本样式并返回新字符串。默认情况下，样式是自包含的，这意味着在字符串末尾发出重置代码。这可以通过超车来防止 reset=False .

实例：

click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))

支持的颜色名称：

• black （可能是灰色）
• red
• green
• yellow （可能是橙色）
• blue
• magenta
• cyan
• white （可能是浅灰色）
• bright_black
• bright_red
• bright_green
• bright_yellow
• bright_blue
• bright_magenta
• bright_cyan
• bright_white
• reset （仅重置颜色代码）

2.0 新版功能。

7.0 新版功能: 增加了对亮色的支持。

参数

• text -- 要与 ANSI 代码一起使用的字符串。
• fg -- 如果提供，这将成为前景颜色。
• bg -- 如果提供，这将成为背景色。
• bold -- 如果提供，将启用或禁用粗体模式。
• dim -- 如果提供，将启用或禁用变暗模式。这是很糟糕的支持。
• underline -- 如果提供，将启用或禁用下划线。
• blink -- 如果提供，这将启用或禁用闪烁。
• reverse -- 如果提供此选项，将启用或禁用反向渲染（前景变为背景，反之亦然）。
• reset -- 默认情况下，重置所有代码都添加在字符串的末尾，这意味着样式不会延续。可以禁用此选项来组合样式。

click.unstyle (text)

从字符串中删除 ANSI 样式信息。通常不需要使用此功能，因为如果需要，Click 的 Echo 功能将自动删除样式。

2.0 新版功能。

参数

text -- 要从中删除样式信息的文本。

click.secho (message=None, file=None, nl=True, err=False, color=None, **styles)

此功能结合 echo() 和 style() 一次通话。因此，以下两个调用是相同的：

click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))

所有关键字参数都将转发到基础函数，具体取决于它们使用的是哪个函数。

2.0 新版功能。

click.edit (text=None, editor=None, env=None, require_save=True, extension='.txt', filename=None)

在定义的编辑器中编辑给定的文本。如果给定了一个编辑器（应该是可执行文件的完整路径，但常规操作系统搜索路径用于查找可执行文件），它将覆盖检测到的编辑器。或者，可以使用一些环境变量。如果编辑器未经更改而关闭， None 返回。如果直接编辑文件，返回值始终为 None 和 require_save 和 extension 被忽略。

如果无法打开编辑器 UsageError 提高了。

注意：为了简化跨平台的使用，换行符将自动从 POSIX 转换为 Windows，反之亦然。因此，这里的信息 \n 作为换行标记。

参数

• text -- 要编辑的文本。
• editor -- 可选择要使用的编辑器。默认为自动检测。
• env -- 要转发到编辑器的环境变量。
• require_save -- 如果为真，则不在编辑器中保存将使返回值变为 None .
• extension -- 告诉编辑器的扩展名。默认为 .txt 但是改变这个可能会改变语法突出显示。
• filename -- 如果提供，它将编辑此文件而不是提供的文本内容。在这种情况下，它不会使用临时文件作为间接寻址。

click.launch (url, wait=False, locate=False)

此函数在该文件类型的默认查看器应用程序中启动给定的 URL（或文件名）。如果这是一个可执行文件，它可能会在新会话中启动该可执行文件。返回值是已启动应用程序的退出代码。通常， 0 表示成功。

实例：

click.launch('https://click.palletsprojects.com/')
click.launch('/my/downloaded/file', locate=True)

2.0 新版功能。

参数

• url -- 要启动的对象的 URL 或文件名。
• wait -- 等待程序停止。
• locate -- 如果设置为 True 然后，它将尝试启动文件管理器，而不是启动与 URL 关联的应用程序。如果 URL 没有指向文件系统，这可能会产生奇怪的效果。

click.getchar (echo=False)

从终端提取单个字符并返回它。这将始终返回一个 Unicode 字符，在某些罕见情况下，这可能返回多个字符。返回多个字符的情况是，无论出于什么原因，多个字符最终出现在终端缓冲区中，或者标准输入实际上不是终端。

请注意，这将始终从终端读取数据，即使有一些数据通过管道传输到标准输入中。

Windows 注意：在少数情况下，键入非 ASCII 字符时，此函数可能会等待第二个字符，然后立即返回这两个字符。这是因为某些 Unicode 字符看起来像特殊的键标记。

2.0 新版功能。

参数

echo -- 如果设置为 True ，读取的字符也将显示在终端上。默认情况是不显示它。

click.pause (info='Press any key to continue ...', err=False)

此命令停止执行并等待用户按任意键继续。这类似于 Windows 批处理“暂停”命令。如果程序不是通过终端运行的，那么这个命令将不做任何事情。

2.0 新版功能。

4.0 新版功能: 增加了 err 参数。

参数

• info -- 暂停前要打印的信息字符串。
• err -- 如果设置为 message，则转到 stderr 而不是 stdout 与 Echo 相同。

click.get_terminal_size ()

以元组形式返回终端的当前大小 (width, height) 列和行中。

click.get_binary_stream (name)

返回用于字节处理的系统流。这本质上是用给定的名称从 sys 模块返回流，但它解决了不同 Python 版本之间的一些兼容性问题。基本上，这个函数对于在 Python3 上获取二进制流是必需的。

参数

name -- 要打开的流的名称。有效名称是 'stdin' ， 'stdout' 和 'stderr'

click.get_text_stream (name, encoding=None, errors='strict')

返回用于文本处理的系统流。这通常返回围绕从返回的二进制流的包装流 get_binary_stream() 但对于已经正确配置的流，它也可以在 python 3 上使用快捷方式。

参数

• name -- 要打开的流的名称。有效名称是 'stdin' ， 'stdout' 和 'stderr'
• encoding -- 覆盖检测到的默认编码。
• errors -- 覆盖默认错误模式。

click.open_file (filename, mode='r', encoding=None, errors='strict', lazy=False, atomic=False)

这与 File 可手动使用。默认情况下，文件是非延迟打开的。这可以打开常规文件以及 stdin/stdout，如果 '-' 通过。

如果返回 stdin/stdout，那么流将被包装，这样上下文管理器就不会意外地关闭流。这样就可以始终使用这样的函数，而不必担心意外关闭标准流：

with open_file(filename) as f:
    ...

3.0 新版功能。

参数

• filename -- 要打开的文件的名称（或 '-' 对于 stdin/stdout）。
• mode -- 打开文件的模式。
• encoding -- 要使用的编码。
• errors -- 此文件的错误处理。
• lazy -- 可以翻转为 true 以延迟打开文件。
• atomic -- 在原子模式下，写入进入一个临时文件，并在关闭时移动。

click.get_app_dir (app_name, roaming=True, force_posix=False)

返回应用程序的配置文件夹。默认行为是返回最适合操作系统的内容。

给你一个想法，一个叫做 "Foo Bar" ，可以返回如下文件夹：

Mac OS X：

~/Library/Application Support/Foo Bar

Mac OS X（POSIX）：

~/.foo-bar

UNIX：

~/.config/foo-bar

UNIX（POSIX）：

~/.foo-bar

Win XP（漫游）：

C:\Documents and Settings\<user>\Local Settings\Application Data\Foo Bar

Win XP（非漫游）：

C:\Documents and Settings\<user>\Application Data\Foo Bar

Win 7（漫游）：

C:\Users\<user>\AppData\Roaming\Foo Bar

Win 7（非漫游）：

C:\Users\<user>\AppData\Local\Foo Bar

2.0 新版功能。

参数

• app_name -- 应用程序名称。这应该是适当的大写，可以包含空格。
• roaming -- 控制文件夹是否应在 Windows 上漫游。没有其他影响。
• force_posix -- 如果设置为 True 然后，在任何 POSIX 系统上，文件夹都将存储在主文件夹中，并带有前导点，而不是 xdg config home 或 darwin 的应用程序支持文件夹。

click.format_filename (filename, shorten=False)

为用户显示设置文件名格式。此函数的主要目的是确保文件名完全可以显示。如果需要的话，这会将文件名解码为 Unicode，并且不会失败。或者，它可以缩短文件名，使其不包含文件名的完整路径。

参数

• filename -- 为 UI 显示设置文件名格式。这也会将文件名转换为 Unicode 而不会失败。
• shorten -- 这可以选择将文件名缩短为指向它的路径的条带。

命令

class click.BaseCommand (name, context_settings=None)

基本命令实现命令的最小 API 约定。大多数代码永远不会使用它，因为它不实现很多有用的功能，但它可以作为不依赖于 click 解析器的可选解析方法的直接子类。

例如，这可以用于桥接 click 和其他系统，如 argparse 或 docopt。

因为基本命令并不实现许多其他部分认为是理所当然的 API，所以并非所有操作都支持它们。例如，它们通常不能与修饰符一起使用，并且没有内置的回调系统。

在 2.0 版更改: 增加了 context_settings 参数。

参数

• name -- 要使用的命令的名称，除非某个组重写了该命令。
• context_settings -- 带有传递给上下文对象的默认值的可选字典。

allow_extra_args = False

的默认值 Context.allow_extra_args 标志符。

allow_interspersed_args = True

的默认值 Context.allow_interspersed_args 标志符。

context_settings = None

具有传递给上下文的默认值的可选字典。

ignore_unknown_options = False

的默认值 Context.ignore_unknown_options 标志符。

invoke (ctx)

给定一个上下文，这将调用该命令。默认实现正在引发未实现的错误。

main (args=None, prog_name=None, complete_var=None, standalone_mode=True, **extra)

这是调用一个脚本的方法，所有的铃声和口哨声都作为命令行应用程序。这将始终在调用后终止应用程序。如果不需要， SystemExit 需要被抓住。

通过直接调用 Command .

3.0 新版功能: 增加了 standalone_mode 用于控制独立模式的标志。

参数

• args -- 用于解析的参数。如果没有提供， sys.argv[1:] 使用。
• prog_name -- 应使用的程序名。默认情况下，程序名是通过从 sys.argv[0] .
• complete_var -- 控制 bash 完成支持的环境变量。默认值为 "_<prog_name>_COMPLETE" 程序名为大写。
• standalone_mode -- 默认行为是在独立模式下调用脚本。Click 将处理异常并将其转换为错误消息，该函数将永远不会返回，而是关闭解释器。如果设置为 False 它们将传播到调用方，此函数的返回值是 invoke() .
• extra -- 额外的关键字参数被转发到上下文构造函数。见 Context 更多信息。

make_context (info_name, args, parent=None, **extra)

当给定信息名和参数时，此函数将启动分析并创建新的 Context . 但它不会调用实际的命令回调。

参数

• info_name -- 此调用的信息名称。通常，这是脚本或命令最具描述性的名称。对于顶级脚本，它通常是脚本的名称，对于下面的命令，它是脚本的名称。
• args -- 要解析为字符串列表的参数。
• parent -- 父上下文（如果可用）。
• extra -- 转发到上下文构造函数的额外关键字参数。

name = None

命令认为它具有的名称。在 Group 该组将使用此信息默认命令名。你应该使用 Context 的 info_name 属性。

parse_args (ctx, args)

给定一个上下文和参数列表，这将创建解析器并解析参数，然后根据需要修改上下文。这是由自动调用的 make_context() .

class click.Command (name, context_settings=None, callback=None, params=None, help=None, epilog=None, short_help=None, options_metavar='[OPTIONS]', add_help_option=True, hidden=False, deprecated=False)

命令是 click 中命令行接口的基本构建块。基本命令处理命令行分析，并可能将更多的分析分派给嵌套在它下面的命令。

在 2.0 版更改: 增加了 context_settings 参数。

参数

• name -- 要使用的命令的名称，除非某个组重写了该命令。
• context_settings -- 带有传递给上下文对象的默认值的可选字典。
• callback -- 要调用的回调。这是可选的。
• params -- 要用此命令注册的参数。这可以是 Option 或 Argument 物体。
• help -- 用于此命令的帮助字符串。
• epilog -- 类似于帮助字符串，但它在帮助页的末尾打印。
• short_help -- 用于此命令的简短帮助。这显示在父命令的命令列表中。
• add_help_option -- 默认情况下，每个命令注册一个 --help 选择权。此参数可以禁用此功能。
• hidden -- 从帮助输出中隐藏此命令。
• deprecated -- 发出一条消息，指示命令已被弃用。

callback = None

命令触发时要执行的回调。这可能是 None 在这种情况下什么也不会发生。

collect_usage_pieces (ctx)

返回进入使用行的所有片段，并将其作为字符串列表返回。

format_epilog (ctx, formatter)

将 epilog 写入格式化程序（如果存在）。

format_help (ctx, formatter)

将帮助写入格式化程序（如果存在）。

这将调用以下方法：

• format_usage()
• format_help_text()
• format_options()
• format_epilog()

format_help_text (ctx, formatter)

将帮助文本写入格式化程序（如果存在）。

format_options (ctx, formatter)

将所有选项写入格式化程序（如果存在）。

format_usage (ctx, formatter)

将使用行写入格式化程序。

get_help (ctx)

将帮助格式化为字符串并返回。这将创建格式化程序并调用以下格式化方法：

get_help_option (ctx)

返回帮助选项对象。

get_help_option_names (ctx)

返回帮助选项的名称。

get_short_help_str (limit=45)

获取命令的简短帮助，或者通过缩短长帮助字符串来实现。

invoke (ctx)

给定一个上下文，这将以正确的方式调用附加的回调（如果它存在的话）。

make_parser (ctx)

为此命令创建基础选项分析器。

params = None

此命令的参数列表，其顺序应显示在帮助页中并执行。在处理非预处理参数之前，将自动处理预处理参数。

parse_args (ctx, args)

给定一个上下文和参数列表，这将创建解析器并解析参数，然后根据需要修改上下文。这是由自动调用的 make_context() .

class click.MultiCommand (name=None, invoke_without_command=False, no_args_is_help=None, subcommand_metavar=None, chain=False, result_callback=None, **attrs)

多命令是将命令分派给子命令的基本实现。最常见的版本是 Group .

参数

• invoke_without_command -- 这控制如何调用多命令本身。默认情况下，只有在提供了子命令时才调用它。
• no_args_is_help -- 这控制了如果没有提供参数会发生什么。默认情况下，如果 invoke_without_command 禁用或禁用（如果启用）。如果启用，将添加 --help 如果没有传递参数，则作为参数。
• subcommand_metavar -- 文档中用于指示子命令位置的字符串。
• chain -- 如果设置为 True 已启用多个子命令的链接。这限制了命令的形式，因为它们不能有可选参数，但允许将多个命令链接在一起。
• result_callback -- 要附加到此多命令的结果回调。

collect_usage_pieces (ctx)

返回进入使用行的所有片段，并将其作为字符串列表返回。

format_commands (ctx, formatter)

用于在选项后添加所有命令的多方法的额外格式方法。

format_options (ctx, formatter)

将所有选项写入格式化程序（如果存在）。

get_command (ctx, cmd_name)

如果给定上下文和命令名，则返回 Command 对象（如果它存在或返回） None .

invoke (ctx)

给定一个上下文，这将以正确的方式调用附加的回调（如果它存在的话）。

list_commands (ctx)

返回子命令名称的列表，其显示顺序为。

parse_args (ctx, args)

给定一个上下文和参数列表，这将创建解析器并解析参数，然后根据需要修改上下文。这是由自动调用的 make_context() .

result_callback = None

存储的结果回调。可以使用 resultcallback() 装饰者。

resultcallback (replace=False)

向 chain 命令添加结果回调。默认情况下，如果已注册结果回调，则会将其链接起来，但可以使用 replace 参数。调用结果回调时使用子命令的返回值（如果启用了链接，则使用所有子命令的返回值列表）以及将传递给主回调的参数。

例子：：

@click.group()
@click.option('-i', '--input', default=23)
def cli(input):
    return 42

@cli.resultcallback()
def process_result(result, input):
    return result + input

3.0 新版功能。

参数

replace -- 如果设置为 True 将删除已存在的结果回调。

class click.Group (name=None, commands=None, **attrs)

组允许命令附加子命令。这是在 click 中实现嵌套的最常见方法。

参数

commands -- 命令字典。

add_command (cmd, name=None)

注册另一个 Command 和这个小组。如果未提供名称，则使用命令的名称。

command (*args, **kwargs)

用于声明命令并将其附加到组的快捷修饰符。这与 command() 但通过调用 add_command() .

commands = None

通过导出的名称注册的子命令。

get_command (ctx, cmd_name)

如果给定上下文和命令名，则返回 Command 对象（如果它存在或返回） None .

group (*args, **kwargs)

用于声明组和将组附加到组的快捷修饰符。这与 group() 但通过调用 add_command() .

list_commands (ctx)

返回子命令名称的列表，其显示顺序为。

class click.CommandCollection (name=None, sources=None, **attrs)

命令集合是将多个多命令合并为一个多命令的多命令。这是一个简单的实现，它接受不同的多命令列表作为源，并为每个命令提供所有命令。

add_source (multi_cmd)

向链调度程序添加新的多命令。

get_command (ctx, cmd_name)

如果给定上下文和命令名，则返回 Command 对象（如果它存在或返回） None .

list_commands (ctx)

返回子命令名称的列表，其显示顺序为。

sources = None

已注册的多命令列表。

参数

class click.Parameter (param_decls=None, type=None, required=False, default=None, callback=None, nargs=None, metavar=None, expose_value=True, is_eager=False, envvar=None, autocompletion=None)

命令的参数有两种版本：一种是 Option S 或 Argument 其他的子类目前不受设计支持，因为解析的一些内部构件是故意不确定的。

选项和参数都支持某些设置。

在 2.0 版更改: 已更改参数回调的签名以同时传递该参数。在 Click2.0 中，旧的回调格式仍然有效，但它会发出警告，让您更容易地迁移代码。

参数

• param_decls -- 此选项或参数的参数声明。这是标记或参数名称的列表。
• type -- 应使用的类型。要么是 ParamType 或者是 python 类型。如果支持，后者将自动转换为前者。
• required -- 控制是否可选。
• default -- 如果省略，则为默认值。这也可以是可调用的，在这种情况下，当需要不带任何参数的默认值时调用它。
• callback -- 匹配参数后应执行的回调。这叫做 fn(ctx, param, value) 需要返回值。在 Click2.0 之前，签名是 (ctx, value) .
• nargs -- 要匹配的参数数。如果没有 1 返回值是一个元组，而不是单个值。nargs 的默认值是 1 （除非类型是元组，否则它是元组的 arity）。
• metavar -- 值在帮助页中的表示方式。
• expose_value -- 如果这是 True 然后将该值传递给命令回调并存储在上下文中，否则将跳过该值。
• is_eager -- 在处理非渴望值之前，先处理渴望值。这不应该为参数设置，否则它将反转处理顺序。
• envvar -- 应检查的环境变量字符串或字符串列表。

get_default (ctx)

给定一个上下文变量，它将计算默认值。

get_error_hint (ctx)

获取参数的字符串化版本，以便在错误消息中使用，以指示哪个参数导致了错误。

human_readable_name

返回此参数的可读名称。这与选项的名称相同，但参数的 metavar 相同。

process_value (ctx, value)

如果给定一个值和上下文，它将运行逻辑来根据需要转换该值。

type_cast_value (ctx, value)

给定一个值，它将通过类型系统正确地运行它。这会自动处理类似 nargs 和 multiple 以及复合类型。

class click.Option (param_decls=None, show_default=False, prompt=False, confirmation_prompt=False, hide_input=False, is_flag=None, flag_value=None, multiple=False, count=False, allow_from_autoenv=True, type=None, help=None, hidden=False, show_choices=True, show_envvar=False, **attrs)

选项通常是命令行上的可选值，并且具有参数不具备的一些额外功能。

所有其他参数都将传递给参数构造函数。

参数

• show_default -- 控制是否应在帮助页上显示默认值。通常不显示默认值。如果该值是字符串，则显示的是字符串而不是值。这对于动态选项特别有用。
• show_envvar -- 控制是否应在帮助页上显示环境变量。通常不显示环境变量。
• prompt -- 如果设置为 True 或者是一个非空字符串，那么将提示用户输入。如果设置为 True 提示将是大写的选项名称。
• confirmation_prompt -- 如果已设置，则如果提示输入值，则需要确认该值。
• hide_input -- 如果这是 True 然后提示上的输入将对用户隐藏。这对于输入密码很有用。
• is_flag -- 强制此选项作为标志。默认为自动检测。
• flag_value -- 如果启用了该标志，则应使用哪个值。如果选项字符串包含用于标记两个选项的斜线，则自动将其设置为布尔值。
• multiple -- 如果设置为 True 然后多次接受并记录参数。这和 nargs 但支持任意数量的参数。
• count -- 此标志使选项递增为整数。
• allow_from_autoenv -- 如果启用了此选项，则在上下文中定义前缀的情况下，此参数的值将从环境变量中提取。
• help -- 帮助字符串。
• hidden -- 从帮助输出中隐藏此选项。

class click.Argument (param_decls, required=None, **attrs)

参数是命令的位置参数。它们通常提供的功能比选项少，但可以具有无限的 nargs 默认情况下是必需的。

所有参数都将传递给参数构造函数。

语境

class click.Context (command, parent=None, info_name=None, obj=None, auto_envvar_prefix=None, default_map=None, terminal_width=None, max_content_width=None, resilient_parsing=False, allow_extra_args=None, allow_interspersed_args=None, ignore_unknown_options=None, help_option_names=None, token_normalize_func=None, color=None)

上下文是一个特殊的内部对象，它在每个级别上保持与脚本执行相关的状态。命令通常不可见，除非他们选择访问它。

上下文非常有用，因为它可以传递内部对象，并且可以控制特殊的执行特性，例如从环境变量读取数据。

上下文可以用作上下文管理器，在这种情况下，它将调用 close() 撕毁。

2.0 新版功能: 增加了 resilient_parsing ， help_option_names ， token_normalize_func 参数。

3.0 新版功能: 增加了 allow_extra_args 和 allow_interspersed_args 参数。

4.0 新版功能: 增加了 color ， ignore_unknown_options 和 max_content_width 参数。

参数

• command -- 此上下文的命令类。
• parent -- 父上下文。
• info_name -- 此调用的信息名称。通常，这是脚本或命令最具描述性的名称。对于顶级脚本，它通常是脚本的名称，对于下面的命令，它是脚本的名称。
• obj -- 用户数据的任意对象。
• auto_envvar_prefix -- 用于自动环境变量的前缀。如果这是 None 然后禁用从环境变量读取。这不会影响手动设置始终读取的环境变量。
• default_map -- 带有参数默认值的字典（类似对象）。
• terminal_width -- 终端的宽度。默认值是从父上下文继承。如果没有上下文定义终端宽度，则将应用自动检测。
• max_content_width -- 通过 Click 呈现的内容的最大宽度（这当前只影响帮助页）。如果不重写，则默认为 80 个字符。换句话说：即使终端大于此，默认情况下，Click 也不会格式化超过 80 个字符的内容。除此之外，格式化程序可能会在右侧添加一些安全映射。
• resilient_parsing -- 如果启用此标志，则 Click“将解析”，而不进行任何交互或回调调用。默认值也将被忽略。这对于实现诸如完成支持之类的事情很有用。
• allow_extra_args -- 如果设置为 True 然后，末尾的额外参数不会引发错误，并将保留在上下文中。默认值是从命令继承。
• allow_interspersed_args -- 如果设置为 False 那么选项和参数不能混合。默认值是从命令继承。
• ignore_unknown_options -- 指示 Click 忽略它不知道的选项，并将其保留以供以后处理。
• help_option_names -- （可选）定义默认帮助参数命名方式的字符串列表。默认值为 ['--help'] .
• token_normalize_func -- 用于规范化令牌（选项、选项等）的可选函数。例如，这可以用于实现不区分大小写的行为。
• color -- 控制终端是否支持 ANSI 颜色。默认为自动检测。只有在 Click 打印的文本中使用了 ANSI 代码时才需要这样做，默认情况下不是这样。例如，这将影响帮助输出。

abort ()

中止脚本。

allow_extra_args = None

指示上下文是否允许额外的参数，或者它在解析时是否应该失败。

3.0 新版功能。

allow_interspersed_args = None

指示上下文是否允许混合参数和选项。

3.0 新版功能。

args = None

剩下的参数。

call_on_close (f)

这个修饰器将函数记为回调，当上下文关闭时应该执行该回调。这对于将资源处理绑定到脚本执行最有用。例如，文件对象由 File 类型将在此处注册其关闭回调。

参数

f -- 要在拆卸时执行的函数。

close ()

调用所有关闭回调。

color = None

控制是否需要样式输出。

command = None

这个 Command 对于这个上下文。

command_path

计算的命令路径。这是用来 usage 帮助页上的信息。它是通过将上下文链的信息名称组合到根目录自动创建的。

ensure_object (object_type)

喜欢 find_object() 但将最内部的对象设置为 object_type 如果它不存在。

exit (code=0)

使用给定的退出代码退出应用程序。

fail (message)

用特定的错误消息中止程序的执行。

参数

message -- 要失败的错误消息。

find_object (object_type)

查找给定类型的最近对象。

find_root ()

查找最外部的上下文。

forward (**kwargs)

类似 invoke() 但如果其他命令需要，则从当前上下文填充默认关键字参数。这不能直接调用回调，只能调用其他命令。

get_help ()

用于获取当前上下文和命令的格式化帮助页的 Helper 方法。

get_usage ()

用于获取当前上下文和命令的格式化用法字符串的 Helper 方法。

help_option_names = None

帮助选项的名称。

ignore_unknown_options = None

指示 Click 忽略命令不理解的选项，并将其存储在上下文中以供以后处理。这对于您希望调用外部程序的情况非常有用。一般来说，这种模式是强烈不鼓励的，因为它不可能无损地转发所有参数。

4.0 新版功能。

info_name = None

描述性信息名称

invoke (**kwargs)

按预期的方式调用命令回调。有两种方法可以调用此方法：

1. 第一个参数可以是回调，所有其他参数和关键字参数都可以直接转发给函数。
2. 第一个参数是 click 命令对象。在这种情况下，所有参数都会被转发，但正确的 Click 参数（选项和 Click 参数）必须是关键字参数，Click 将填充默认值。

请注意，在 click 3.2 之前，关键字参数没有按照此代码的意图正确填写，并且没有创建上下文。有关此更改以及在错误修复版本中进行更改的原因的详细信息，请参阅 升级到 3.2 .

invoked_subcommand = None

此标志指示是否要执行子命令。组回调可以使用此信息来确定它是直接执行的，还是因为执行流向前传递到子命令。默认情况下，它是 none，但它可以是要执行的子命令的名称。

如果启用了链接，将设置为 '*' 如果执行了任何命令。然而，不可能找出哪一个。如果你需要这些知识，你应该使用 resultcallback() .

lookup_default (name)

查找参数名的默认值。默认情况下，这会查看 default_map 如果有的话。

make_formatter ()

为帮助和使用率输出创建格式化程序。

max_content_width = None

格式化内容的最大宽度（无表示合理的默认值，大多数情况下为 80）。

meta

这是一个与嵌套的所有上下文共享的字典。它的存在使得 Click 实用程序可以在需要时在这里存储一些状态。然而，该代码的职责是管理好这本词典。

这些键应该是唯一的虚线。例如，模块路径是一个很好的选择。其中存储的内容与 Click 操作无关。然而，重要的是，在这里放置数据的代码遵循系统的一般语义。

示例用法：

LANG_KEY = __name__ + '.lang'

def set_language(value):
    ctx = get_current_context()
    ctx.meta[LANG_KEY] = value

def get_language():
    return get_current_context().meta.get(LANG_KEY, 'en_US')

5.0 新版功能。

obj = None

存储的用户对象。

params = None

解析的参数，除非该值是隐藏的，在这种情况下，它不会被记住。

parent = None

父上下文或 None 如果不存在。

protected_args = None

受保护的参数。这些是预先准备好的论点 args 当遇到某些解析方案，但不能传播到其他参数时。这用于实现嵌套解析。

resilient_parsing = None

指示是否启用弹性分析。在这种情况下，Click 将尽最大努力避免导致任何故障，默认值将被忽略。有助于完成。

scope (cleanup=True)

此帮助器方法可与上下文对象一起使用，以将其提升为当前的本地线程（请参见 get_current_context() ）其默认行为是调用可通过设置禁用的清理函数 cleanup 到 False . 清理函数通常用于关闭文件句柄等操作。

如果要进行清理，则上下文对象也可以直接用作上下文管理器。

示例用法：

with ctx.scope():
    assert get_current_context() is ctx

这相当于：

with ctx:
    assert get_current_context() is ctx

5.0 新版功能。

参数

cleanup -- 控制是否应运行清除函数。默认设置是运行这些函数。在某些情况下，上下文只希望被临时推送，在这种情况下，可以禁用它。嵌套推送会自动推迟清理。

terminal_width = None

终端的宽度（无为自动检测）。

token_normalize_func = None

令牌的可选规范化函数。这是选项、选项、命令等。

click.get_current_context (silent=False)

返回当前的 Click 上下文。这可以用作从任意位置访问当前上下文对象的方法。这是比 pass_context() 装饰者。此函数主要用于帮助者，如 echo() 它可能对基于当前上下文更改其行为感兴趣。

要推送当前上下文， Context.scope() 可以使用。

5.0 新版功能。

参数

silent -- 设置为 True 返回值为 None 如果没有上下文可用。默认行为是引发 RuntimeError .

类型

click.STRING = STRING

click.INT = INT

click.FLOAT = FLOAT

click.BOOL = BOOL

click.UUID = UUID

click.UNPROCESSED = UNPROCESSED

class click.File (mode='r', encoding=None, errors='strict', lazy=None, atomic=False)

将参数声明为用于读取或写入的文件。上下文关闭后（命令完成工作后），文件将自动关闭。

可以打开文件进行读写。特殊价值 - 根据模式指示 stdin 或 stdout。

默认情况下，打开文件是为了读取文本数据，但也可以以二进制模式打开或写入。编码参数可用于强制特定编码。

这个 lazy 标志控制是否应立即或在第一个 IO 时打开文件。对于标准输入和输出流以及为读取而打开的文件，默认值为非惰性。 lazy 否则。当延迟打开一个文件进行读取时，它仍会临时打开进行验证，但直到第一个 IO 时才会保持打开状态。lazy 主要用于打开进行写入，以避免在需要之前创建文件。

从 click 2.0 开始，文件也可以自动打开，在这种情况下，所有的写操作都将进入同一文件夹中的一个单独的文件，完成后，文件将移到原始位置。如果修改了其他用户定期读取的文件，则此功能非常有用。

见 文件参数 更多信息。

class click.Path (exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False, allow_dash=False, path_type=None)

路径类型与 File 但它执行不同的检查。首先，它不返回打开的文件句柄，只返回文件名。其次，它可以对文件或目录进行各种基本检查。

在 6.0 版更改: allow_dash 加入。

参数

• exists -- 如果设置为 true，则该文件或目录需要存在才能使该值有效。如果这不是必需的，并且文件确实不存在，那么将自动跳过所有进一步的检查。
• file_okay -- 控制文件是否为可能值。
• dir_okay -- 控制目录是否为可能值。
• writable -- 如果为真，则执行可写检查。
• readable -- 如果为真，则执行可读检查。
• resolve_path -- 如果这是真的，那么在向前进传递值之前，将完全解析路径。这意味着它是绝对的，符号链接被解析。它不会扩展 tilde 前缀，因为这只由 shell 完成。
• allow_dash -- 如果设置为 True ，允许使用一个短划线指示标准流。
• path_type -- （可选）应用于表示路径的字符串类型。默认值为 None 这意味着返回值可以是字节，也可以是 Unicode，这取决于 Click 处理的输入数据最有意义的是什么。

class click.Choice (choices, case_sensitive=True)

选项类型允许根据一组固定的支持值检查值。所有这些值都必须是字符串。

您应该只传递选项列表或元组。其他 iTerables（如发电机）可能会产生令人惊讶的结果。

见 选择选项 举个例子。

参数

case_sensitive -- 设置为 false 可使选项不区分大小写。默认为 true。

class click.IntRange (min=None, max=None, clamp=False)

工作原理类似于 click.INT 但限制该值适应范围。如果值超出范围，默认行为将失败，但也可以在两条边之间静默夹持。

见 范围选项 举个例子。

class click.Tuple (types)

Click 的默认行为是直接对值应用类型。这在大多数情况下都很有效，除了 nargs 设置为固定计数，不同的项目应使用不同的类型。在这种情况下， Tuple 不能使用类型。此类型只能在以下情况下使用 nargs 设置为固定数字。

有关详细信息，请参阅 元组作为多值选项 .

这可以通过使用 python tuple 文本作为类型来选择。

参数

types -- 应用于元组项的类型列表。

class click.ParamType

用于通过类型转换值的帮助器。以下是有效类型所必需的：

• 它需要一个名字
• 它需要通过一个不变的
• 它需要从字符串转换
• 它需要将结果类型转换为未更改的类型（例如：需要等幂）
• 它需要能够处理参数和上下文 None . 当对象与提示输入一起使用时，可能会出现这种情况。

convert (value, param, ctx)

转换值。这不会为以下值调用 None （缺少的值）。

envvar_list_splitter = None

如果需要此类型的列表，并且该值是从字符串环境变量中提取的，那么这就是将其拆分的原因。 None 表示任何空白。对于所有参数，一般规则是空格将它们拆分。例外情况是路径和文件 os.path.pathsep 默认情况下（在 Unix 上为“：”，在 Windows 上为“；”。

fail (message, param=None, ctx=None)

Helper 方法失败，返回无效的值消息。

get_metavar (param)

返回此参数的 metavar 默认值（如果提供）。

get_missing_message (param)

或者可能返回关于缺少参数的额外信息。

2.0 新版功能。

name = None

此类型的描述性名称

split_envvar_value (rv)

给定一个来自环境变量的值，这将根据定义的 envvar 列表拆分器将其拆分为小块。

如果拆分器设置为 None ，这意味着空格将被拆分，然后忽略前导空格和尾随空格。否则，前导和尾随拆分器通常会导致包含空项。

例外情况

exception click.ClickException (message)

Click 可以处理并向用户显示的异常。

exception click.Abort

一种内部信号异常，它发出 Click 中止的信号。

exception click.UsageError (message, ctx=None)

表示使用错误的内部异常。这通常会中止任何进一步的处理。

参数

• message -- 要显示的错误消息。
• ctx -- （可选）导致此错误的上下文。在某些情况下，Click 将自动填充上下文。

exception click.BadParameter (message, ctx=None, param=None, param_hint=None)

为错误参数格式化标准化错误消息的异常。这在从回调或类型中抛出时非常有用，因为 Click 会将上下文信息附加到回调或类型中（例如，它是哪个参数）。

2.0 新版功能。

参数

• param -- 导致此错误的参数对象。这可以省略，如果可能，Click 将附加此信息本身。
• param_hint -- 显示为参数名的字符串。这可以作为替代 param 在应该进行自定义验证的情况下。如果它是一个这样使用的字符串，如果它是一个列表，那么每个项目都被引用并分隔开。

exception click.FileError (filename, hint=None)

无法打开文件时引发。

exception click.NoSuchOption (option_name, message=None, possibilities=None, ctx=None)

在 Click 尝试处理不存在的选项时引发。

4.0 新版功能。

exception click.BadOptionUsage (option_name, message, ctx=None)

如果通常提供选项，但该选项的使用不正确，则引发。例如，如果选项的参数数目不正确，则会引发此问题。

4.0 新版功能。

参数

option_name -- 不正确使用的选项的名称。

exception click.BadArgumentUsage (message, ctx=None)

如果通常提供参数，但参数的使用不正确，则引发。例如，如果参数的值数目不正确，则会引发此问题。

6.0 新版功能。

格式化

class click.HelpFormatter (indent_increment=2, width=None, max_width=None)

此类有助于格式化基于文本的帮助页。它通常只需要用于非常特殊的内部案例，但它也被公开，这样开发人员就可以编写自己的奇特输出。

目前，它总是写入内存。

参数

• indent_increment -- 每个级别的额外增量。
• width -- 文本的宽度。默认情况下，终端宽度最大为 78。

dedent ()

减小缩进。

getvalue ()

返回缓冲区内容。

indent ()

增加缩进量。

indentation ()

增加缩进的上下文管理器。

section (name)

编写段落、标题和缩进的有用上下文管理器。

参数

name -- 作为标题写入的节名。

write (string)

将 Unicode 字符串写入内部缓冲区。

write_dl (rows, col_max=30, col_spacing=2)

将定义列表写入缓冲区。这就是选项和命令通常的格式化方式。

参数

• rows -- 术语和值的两个项元组的列表。
• col_max -- 第一列的最大宽度。
• col_spacing -- 第一列和第二列之间的空格数。

write_heading (heading)

将标题写入缓冲区。

write_paragraph ()

将段落写入缓冲区。

write_text (text)

将重新缩进的文本写入缓冲区。这改写并保留了段落。

write_usage (prog, args='', prefix='Usage: ')

将使用行写入缓冲区。

参数

• prog -- 程序名。
• args -- 用空格分隔的参数列表。
• prefix -- 第一行的前缀。

click.wrap_text (text, width=78, initial_indent='', subsequent_indent='', preserve_paragraphs=False)

智能包装文本的助手函数。默认情况下，它假定对单个文本段落进行操作，但如果 preserve_paragraphs 提供了参数，它将智能地处理段落（由两个空行定义）。

如果处理段落，则可以在段落前面加上包含 \b 性格 ( \x08 ）以表明在该块中不应发生重绕。

参数

• text -- 应该重写的文本。
• width -- 文本的最大宽度。
• initial_indent -- 应作为字符串放在第一行上的初始缩进。
• subsequent_indent -- 应该放在每个连续行上的缩进字符串。
• preserve_paragraphs -- 如果设置了此标志，包装将智能地处理段落。

句法分析

class click.OptionParser (ctx=None)

选项分析器是一个内部类，最终用于分析选项和参数。它是在 optparse 之后建模的，带来了一个类似但非常简单的 API。通常不应该直接使用它，因为高级 Click 类会为您包装它。

它的可扩展性不如 optparse 或 argparse，因为它不实现在更高级别上实现的功能（如类型或默认值）。

参数

ctx -- 可选地 Context 这个解析器应该放在哪里。

add_argument (dest, nargs=1, obj=None)

添加名为的位置参数 dest 到解析器。

这个 obj 可用于标识从分析器返回的订单列表中的选项。

add_option (opts, dest, action=None, nargs=1, const=None, obj=None)

添加名为的新选项 dest 到解析器。目的地不是推断出来的（与 optparse 不同），需要明确提供。行动可以是 store ， store_const ， append ， appnd_const 或 count .

这个 obj 可用于标识从分析器返回的订单列表中的选项。

allow_interspersed_args = None

这控制了解析器如何处理分散的参数。如果设置为 False ，解析器将在第一个非选项上停止。Click“使用此项”可以安全地实现嵌套的子命令。

ctx = None

这个 Context 对于这个解析器。这可能是 None 对于一些高级用例。

ignore_unknown_options = None

这将告诉解析器如何处理未知选项。默认情况下，它将出错（这是合理的），但还有第二种模式，在这种模式下，它将忽略它，并在将所有未知选项转移到结果参数后继续处理。

parse_args (args)

分析位置参数并返回 (values, args, order) 对于已解析的选项和参数以及剩余的参数（如果有）。顺序是显示在命令行上的对象列表。如果参数出现多次，它们也会被记住多次。

测试

class click.testing.CliRunner (charset=None, env=None, echo_stdin=False, mix_stderr=True)

cli 运行程序提供了在独立环境中为单元测试目的调用 click 命令行脚本的功能。这只在单线程系统中工作，而不需要任何并发性，因为它会更改全局解释器状态。

参数

• charset -- 输入和输出数据的字符集。默认情况下，这是 UTF-8，当前不应更改，因为只在 python 2 中报告 click 可以正常工作。
• env -- 一种具有用于重写的环境变量的字典。
• echo_stdin -- 如果设置为 True ，然后从 stdin 读取写入 stdout。这对于在某些情况下显示示例很有用。请注意，常规提示将自动回送输入。
• mix_stderr -- 如果设置为 False ，则 stdout 和 stderr 保留为独立的流。这对于具有可预测的 stdout 和嘈杂的 stderr 的 Unix 哲学应用程序很有用，这样每个应用程序都可以独立测量。

get_default_prog_name (cli)

给定一个命令对象，它将返回它的默认程序名。默认值是 name 属性或 "root" 如果没有设置。

invoke (cli, args=None, input=None, env=None, catch_exceptions=True, color=False, mix_stderr=False, **extra)

在隔离环境中调用命令。参数直接转发到命令行脚本， extra 关键字参数传递给 main() 命令的功能。

返回一个 Result 对象。

3.0 新版功能: 这个 catch_exceptions 已添加参数。

在 3.0 版更改: 结果对象现在有一个 exc_info 如果可用，则具有回溯的属性。

4.0 新版功能: 这个 color 已添加参数。

参数

• cli -- 要调用的命令
• args -- 要调用的参数。它可以作为 iterable 或 string 给出。当作为字符串给出时，它将被解释为一个 unix shell 命令。更多细节 shlex.split() .
• input -- 的输入数据 sys.stdin .
• env -- 环境将覆盖。
• catch_exceptions -- 是否捕获除 SystemExit .
• extra -- 要传递给的关键字参数 main() .
• color -- 输出是否应包含颜色代码。应用程序仍然可以显式地重写这一点。

isolated_filesystem ()

一个上下文管理器，用于创建一个临时文件夹，并将当前工作目录更改为它，以进行独立的文件系统测试。

isolation (input=None, env=None, color=False)

为调用命令行工具设置隔离的上下文管理器。这将使用给定的输入数据和 os.environ 使用给定字典中的重写。这还重新显示了 Click 模拟（如提示功能）中的一些内部内容。

这是自动完成的 invoke() 方法。

4.0 新版功能: 这个 color 已添加参数。

参数

• input -- 要放入 sys.stdin 的输入流。
• env -- 环境将重写为字典。
• color -- 输出是否应包含颜色代码。应用程序仍然可以显式地重写这一点。

make_env (overrides=None)

返回用于调用脚本的环境重写。

class click.testing.Result (runner, stdout_bytes, stderr_bytes, exit_code, exception, exc_info=None)

保存已调用的 CLI 脚本的捕获结果。

exc_info = None

追溯

exception = None

如果有例外的话会发生。

exit_code = None

退出代码为整数。

output

（标准）输出为 Unicode 字符串。

runner = None

创建结果的运行者

stderr

标准错误为 Unicode 字符串。

stderr_bytes = None

标准错误为字节，如果不可用则为假（Y）

stdout

标准输出为 Unicode 字符串。

stdout_bytes = None

标准输出为字节。