API — 单击文档

应用程序接口

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

装饰器

click.command(name: Optional[str] = None, cls: Optional[Type[click.core.Command]] = None, **attrs: Any) → Callable[[click.decorators.F], click.core.Command]

创建一个新的 Command 并使用装饰函数作为回调。 这还将自动将所有装饰的 option() 和 argument() 作为参数附加到命令中。

命令的名称默认为函数的名称，下划线替换为破折号。 如果你想改变它，你可以将预期的名称作为第一个参数传递。

所有关键字参数都转发到底层命令类。

一旦修饰，函数就会变成一个 Command 实例，可以作为命令行实用程序调用或附加到命令 Group。

参数

• name – 命令的名称。 这默认为函数名称，下划线替换为破折号。

• cls – 要实例化的命令类。 默认为 Command。

click.group(name: Optional[str] = None, **attrs: Any) → Callable[[click.decorators.F], click.core.Group]

使用函数作为回调创建一个新的 Group。 这在其他方面与 command() 相同，只是 cls 参数设置为 Group。

click.argument(*param_decls: str, **attrs: Any) → Callable[[click.decorators.FC], click.decorators.FC]

将参数附加到命令。 所有位置参数都作为参数声明传递给 Argument； 所有关键字参数都保持不变（cls 除外）。 这相当于手动创建一个 Argument 实例并将其附加到 Command.params 列表中。

参数

cls – 要实例化的参数类。 默认为 参数 。

click.option(*param_decls: str, **attrs: Any) → Callable[[click.decorators.FC], click.decorators.FC]

将选项附加到命令。 所有位置参数都作为参数声明传递给 Option; 所有关键字参数都保持不变（cls 除外）。 这相当于手动创建一个 Option 实例并将其附加到 Command.params 列表中。

参数

cls – 要实例化的选项类。 默认为 选项 。

click.password_option(*param_decls: str, **kwargs: Any) → Callable[[click.decorators.FC], click.decorators.FC]

添加 --password 选项，提示输入密码，隐藏输入并要求再次输入值以进行确认。

参数

;;* param_decls – 一个或多个选项名称。 默认为单个值 "--password"。

• kwargs – 额外的参数传递给 option()。

click.confirmation_option(*param_decls: str, **kwargs: Any) → Callable[[click.decorators.FC], click.decorators.FC]

添加 --yes 选项，如果未通过，则在继续之前显示提示。 如果提示被拒绝，程序将退出。

参数

;;* param_decls – 一个或多个选项名称。 默认为单个值 "--yes"。

• kwargs – 额外的参数传递给 option()。

click.version_option(version: Optional[str] = None, *param_decls: str, package_name: Optional[str] = None, prog_name: Optional[str] = None, message: Optional[str] = None, **kwargs: Any) → Callable[[click.decorators.FC], click.decorators.FC]

添加一个 --version 选项，它会立即打印版本号并退出程序。

如果未提供 version，Click 将尝试使用 importlib.metadata.version() 检测它以获取 package_name 的版本。 在 Python < 3.8 上，importlib_metadata 必须安装 backport。

如果未提供 package_name，Click 将尝试通过检查堆栈帧来检测它。 这将用于检测版本，因此它必须与已安装包的名称匹配。

参数

• version – 要显示的版本号。 如果未提供，Click 将尝试检测它。

• param_decls – 一个或多个选项名称。 默认为单个值 "--version"。

• package_name – 要从中检测版本的包名称。 如果未提供，Click 将尝试检测它。

• prog_name – 要在消息中显示的 CLI 的名称。 如果未提供，将从命令中检测到。

• message – 要显示的消息。 值 %(prog)s、%(package)s 和 %(version)s 可用。 默认为 "%(prog)s, version %(version)s"。

• kwargs – 额外的参数传递给 option()。

加注

RuntimeError – 无法检测到 version。

8.0 版本变更： 添加 package_name 参数，以及消息的 %(package)s 值。

8.0 版更改： 使用 importlib.metadata 代替 pkg_resources。 版本是根据包名称检测的，而不是入口点名称。 Python 包名称必须与已安装的包名称匹配，或者使用 package_name= 传递。

click.help_option(*param_decls: str, **kwargs: Any) → Callable[[click.decorators.FC], click.decorators.FC]

添加 --help 选项，可立即打印帮助页面并退出程序。

这通常是不必要的，因为 --help 选项会自动添加到每个命令中，除非通过 add_help_option=False。

参数

• param_decls – 一个或多个选项名称。 默认为单个值 "--help"。

• kwargs – 额外的参数传递给 option()。

click.pass_context(f: click.decorators.F) → click.decorators.F

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

click.pass_obj(f: click.decorators.F) → click.decorators.F

类似于 pass_context()，但只在上下文中传递对象（Context.obj）。 如果该对象表示嵌套系统的状态，这将很有用。

click.make_pass_decorator(object_type: Type, ensure: bool = False) → Callable[[click.decorators.F], click.decorators.F]

给定一个对象类型，这将创建一个装饰器，其工作方式类似于 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: Optional[Any] = None, file: Optional[IO] = None, nl: bool = True, err: bool = False, color: Optional[bool] = None) → None

将消息和换行符打印到标准输出或文件。 应该使用它来代替 print()，因为它为不同的数据、文件和环境提供了更好的支持。

与 print() 相比，它执行以下操作：

• 确保输出编码在 Linux 上没有错误配置。

• 在 Windows 控制台中支持 Unicode。

• 支持写入二进制输出，并支持将字节写入文本输出。

• 支持 Windows 上的颜色和样式。

• 如果输出看起来不像交互式终端，则删除 ANSI 颜色和样式代码。

• 始终刷新输出。

参数

• message – 要输出的字符串或字节。 其他对象被转换为字符串。

• file – 要写入的文件。 默认为 stdout。

• err – 写入 stderr 而不是 stdout。

• nl – 在消息后打印一个换行符。 默认启用。

• color – 强制显示或隐藏颜色和其他样式。 默认情况下，如果输出看起来不像交互式终端，则 Click 将删除颜色。

6.0 版本变化： 支持 Windows 控制台上的 Unicode 输出。 点击不会修改sys.stdout，所以sys.stdout.write()和print()仍然不支持Unicode。

4.0 版本变化： 增加了 color 参数。

3.0 新功能：增加了err参数。

在 2.0 版更改：如果安装了 colorama，则支持 Windows 上的颜色。

click.echo_via_pager(text_or_generator: Union[Iterable[str], Callable[[], Iterable[str]], str], color: Optional[bool] = None) → None

此函数采用文本并通过标准输出上的特定于环境的寻呼机显示它。

3.0 版变更： 增加了 color 标志。

参数

• text_or_generator – 要页面的文本，或者将文本发送到页面的生成器。

• color – 控制寻呼机是否支持 ANSI 颜色。 默认为自动检测。

click.prompt(text: str, default: Optional[Any] = None, hide_input: bool = False, confirmation_prompt: Union[bool, str] = False, type: Optional[click.types.ParamType] = None, value_proc: Optional[Callable[[str], Any]] = None, prompt_suffix: str = ': ', show_default: bool = True, err: bool = False, show_choices: bool = True) → Any

提示用户输入。 这是一个方便的功能，可用于提示用户稍后输入。

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

参数

• text – 要显示的提示文本。

• default – 没有输入时使用的默认值。 如果没有给出，它会提示直到它被中止。

• hide_input – 如果设置为 true，则输入值将被隐藏。

• confirmation_prompt – 再次提示确认值。 可以设置为字符串而不是 True 来自定义消息。

• type – 用于检查值的类型。

• value_proc – 如果提供此参数，则它是一个调用函数而不是类型转换来转换值。

• prompt_suffix – 应添加到提示中的后缀。

• show_default – 在提示中显示或隐藏默认值。

• err – 如果设置为 true，则文件默认为 stderr 而不是 stdout，与 echo 相同。

• show_choices – 如果传递的类型是选择，则显示或隐藏选择。 例如，如果类型是日或周的选择，show_choices 为真，文本为“分组依据”，则提示将是“分组依据（天，周）：”。

8.0 新功能：confirmation_prompt 可以是自定义字符串。

7.0 新功能：增加了show_choices参数。

6.0 新功能： 在 Windows 上添加了对 cmd.exe 的 unicode 支持。

4.0 新功能： 增加了 err 参数。

click.confirm(text: str, default: Optional[bool] = False, abort: bool = False, prompt_suffix: str = ': ', show_default: bool = True, err: bool = False) → bool

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

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

参数

• text – 要问的问题。

• default – 没有输入时使用的默认值。 如果是 None，则重复直到给出输入。

• abort – 如果设置为 True，否定回答会通过引发 Abort 来中止异常。

• prompt_suffix – 应添加到提示中的后缀。

• show_default – 在提示中显示或隐藏默认值。

• err – 如果设置为 true，则文件默认为 stderr 而不是 stdout，与 echo 相同。

在 8.0 版更改： 如果 default 是 None，则重复直到给出输入。

4.0新功能：增加了err参数。

click.progressbar(iterable: Optional[Iterable[click.termui.V]] = None, length: Optional[int] = None, label: Optional[str] = None, show_eta: bool = True, show_percent: Optional[bool] = None, show_pos: bool = False, item_show_func: Optional[Callable[[Optional[click.termui.V]], Optional[str]]] = None, fill_char: str = '#', empty_char: str = '-', bar_template: str = '%(label)s  [%(bar)s]  %(info)s', info_sep: str = '  ', width: int = 36, file: Optional[TextIO] = None, color: Optional[bool] = None, update_min_steps: int = 1) → ProgressBar[V]

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

上下文管理器创建进度条。 当进入上下文管理器时，进度条已经创建。 随着进度条上的每次迭代，传递给进度条的可迭代对象都会被推进并更新进度条。 当上下文管理器退出时，会打印一个换行符，并在屏幕上完成进度条。

注意：进度条目前是为预计总进度至少需要几秒钟的用例而设计的。 因此，ProgressBar 类对象不会显示被认为太快的进度，以及步骤之间的时间少于一秒的进度。

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

用法示例：

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

或者，如果未指定迭代，则可以通过 update() 方法手动更新进度条，而不是直接迭代进度条。 update 方法接受步骤数以增加条形：

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

update() 方法还采用一个可选值，指定新位置的 current_item。 这在与 item_show_func 一起使用时很有用，以自定义每个手动步骤的输出：

with click.progressbar(
    length=total_size,
    label='Unzipping archive',
    item_show_func=lambda a: a.filename
) as bar:
    for archive in zip_file:
        archive.extract()
        bar.update(archive.size, archive)

参数

• iterable – 一个可迭代的迭代。 如果未提供，则需要长度。

• length – 要迭代的项目数。 默认情况下，进度条会尝试向迭代器询问它的长度，这可能有效也可能无效。 如果还提供了可迭代对象，则此参数可用于覆盖长度。 如果未提供可迭代对象，则进度条将在该长度范围内进行迭代。

• label – 显示在进度条旁边的标签。

• show_eta – 启用或禁用估计时间显示。 如果无法确定长度，这将自动禁用。

• show_percent – 启用或禁用百分比显示。 如果可迭代对象具有长度，则默认值为 True，否则为 False。

• show_pos – 启用或禁用绝对位置显示。 默认值为 False。

• item_show_func – 一个用当前项目调用的函数，它可以返回一个字符串显示在进度条旁边。 如果函数返回 None，则不显示任何内容。 当前项目可以是None，比如进出栏时。

• fill_char – 用于显示进度条填充部分的字符。

• empty_char – 用于显示进度条未填充部分的字符。

• bar_template – 用作条形模板的格式字符串。 其中的参数是标签的label，进度条的bar和信息部分的info。

• info_sep – 多个信息项（eta 等）之间的分隔符

• width – 进度条的宽度（以字符为单位），0 表示终端全宽

• file – 要写入的文件。 如果这不是终端，则仅打印标签。

• color – 控制终端是否支持 ANSI 颜色。 默认为自动检测。 仅当 ANSI 代码包含在进度条输出中的任何位置时才需要，默认情况下并非如此。

• update_min_steps – 仅在完成这么多更新后才渲染。 这允许对非常快速的迭代器进行调整。

8.0 版本变更：即使执行时间小于 0.5 秒也会显示输出。

8.0 版本更改： item_show_func 显示当前项目，而不是上一个。

8.0 版更改： 如果输出不是 TTY，则回显标签。 恢复 7.0 中删除所有输出的更改。

8.0 新功能：增加了update_min_steps参数。

4.0 版本变化： 增加了 color 参数。 向对象添加了 update 方法。

2.0 版中的新功能。

click.clear() → None

清除终端屏幕。 这将具有清除终端的整个可见空间并将光标移动到左上角的效果。 如果没有连接到终端，这不会做任何事情。

2.0 版中的新功能。

click.style(text: Any, fg: Optional[Union[int, Tuple[int, int, int], str]] = None, bg: Optional[Union[int, Tuple[int, int, int], str]] = None, bold: Optional[bool] = None, dim: Optional[bool] = None, underline: Optional[bool] = None, overline: Optional[bool] = None, italic: Optional[bool] = None, blink: Optional[bool] = None, reverse: Optional[bool] = None, strikethrough: Optional[bool] = None, reset: bool = True) → str

使用 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'))
click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))

支持的颜色名称：

• 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（仅重置色码）

如果终端支持，颜色也可以指定为：

• 区间 [0, 255] 中的整数。 终端必须支持 8 位/256 色模式。

• [0, 255] 中三个整数的 RGB 元组。 终端必须支持 24 位/真彩色模式。

有关更多信息，请参阅 https://en.wikipedia.org/wiki/ANSI_color 和 https://gist.github.com/XVilka/8346728。

参数

• text – 要使用 ansi 代码设置样式的字符串。

• fg - 如果提供，这将成为前景色。

• bg – 如果提供，这将成为背景颜色。

• bold – 如果提供，这将启用或禁用粗体模式。

• dim – 如果提供，这将启用或禁用暗淡模式。 这得到了很好的支持。

• underline - 如果提供，这将启用或禁用下划线。

• overline – 如果提供，这将启用或禁用上划线。

• italic – 如果提供，这将启用或禁用斜体。

• blink – 如果提供，这将启用或禁用闪烁。

• reverse – 如果提供，这将启用或禁用反向渲染（前景变为背景，反之亦然）。

• strikethrough – 如果提供，这将启用或禁用文本划线。

• reset – 默认情况下，在字符串末尾添加了一个重置所有代码，这意味着样式不会被保留。 可以禁用此功能以编写样式。

8.0 版更改： 非字符串 message 转换为字符串。

8.0 版更改： 增加了对 256 和 RGB 颜色代码的支持。

8.0 版本变更： 添加了 strikethrough、italic 和 overline 参数。

7.0 版本变化： 增加了对亮色的支持。

2.0 版中的新功能。

click.unstyle(text: str) → str

从字符串中删除 ANSI 样式信息。 通常不需要使用此功能，因为 Click 的 echo 功能会在必要时自动删除样式。

2.0 版中的新功能。

参数

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

click.secho(message: Optional[Any] = None, file: Optional[IO] = None, nl: bool = True, err: bool = False, color: Optional[bool] = None, **styles: Any) → None

此函数将 echo() 和 style() 组合到一个调用中。 因此，以下两个调用是相同的：

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

所有关键字参数都被转发到底层函数，具体取决于它们使用的是哪一个。

非字符串类型将转换为 str。 但是， bytes 直接传递给 echo() 而不应用样式。 如果要设置表示文本的字节的样式，请先调用 bytes.decode()。

8.0 版更改： 非字符串 message 转换为字符串。 字节在不应用样式的情况下传递。

2.0 版中的新功能。

click.edit(text: Optional[AnyStr] = None, editor: Optional[str] = None, env: Optional[Mapping[str, str]] = None, require_save: bool = True, extension: str = '.txt', filename: Optional[str] = None) → Optional[AnyStr]

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

如果无法打开编辑器，则会引发 UsageError。

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

参数

• text – 要编辑的文本。

• editor – 可选的编辑器。 默认为自动检测。

• env – 要转发到编辑器的环境变量。

• require_save – 如果是这样，那么不保存在编辑器中会使返回值变成 None。

• extension – 告诉编辑器的扩展名。 默认为 .txt，但更改此设置可能会更改语法突出显示。

• filename – 如果提供，它将编辑此文件而不是提供的文本内容。 在这种情况下，它不会使用临时文件作为间接文件。

click.launch(url: str, wait: bool = False, locate: bool = False) → int

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

例子：

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

2.0 版中的新功能。

参数

• url – 要启动的事物的 URL 或文件名。

• wait – 等待程序退出后再返回。 这仅在启动的程序阻塞时才有效。 特别是 Linux 上的 xdg-open 不会阻塞。

• locate – 如果设置为 True，那么它不会启动与 URL 关联的应用程序，而是尝试启动包含文件所在的文件管理器。 如果 URL 不指向文件系统，这可能会产生奇怪的效果。

click.getchar(echo: bool = False) → str

从终端获取单个字符并返回它。 这将始终返回一个 unicode 字符，在某些极少数情况下，这可能会返回多个字符。 返回多个字符的情况是，无论出于何种原因，多个字符最终出现在终端缓冲区或标准输入实际上不是终端时。

请注意，这将始终从终端读取，即使某些内容已通过管道传输到标准输入中。

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

2.0 版中的新功能。

参数

echo – 如果设置为 True，读取的字符也会显示在终端上。 默认是不显示。

click.pause(info: Optional[str] = None, err: bool = False) → None

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

2.0 版中的新功能。

4.0 新功能： 增加了 err 参数。

参数

• info – 暂停前要打印的消息。 默认为 "Press any key to continue..."。

• err - 如果设置为消息将转到 stderr 而不是 stdout，与回声相同。

click.get_terminal_size() → os.terminal_size

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

自 8.0 版起已弃用： 将在 Click 8.1 中删除。 请改用 shutil.get_terminal_size()。

click.get_binary_stream(name: te.Literal[stdin, stdout, stderr]) → BinaryIO

返回用于字节处理的系统流。

参数

name – 要打开的流的名称。 有效名称为 'stdin'、'stdout' 和 'stderr'

click.get_text_stream(name: te.Literal[stdin, stdout, stderr], encoding: Optional[str] = None, errors: Optional[str] = 'strict') → TextIO

返回用于文本处理的系统流。 这通常会返回一个环绕从 get_binary_stream() 返回的二进制流的包装流，但它也可以为已经正确配置的流采取快捷方式。

参数

;;* name – 要打开的流的名称。 有效名称为 'stdin'、'stdout' 和 'stderr'

• encoding – 覆盖检测到的默认编码。
• errors – 覆盖默认错误模式。

click.open_file(filename: str, mode: str = 'r', encoding: Optional[str] = None, errors: Optional[str] = 'strict', lazy: bool = False, atomic: bool = False) → IO

这类似于 File 的工作方式，但用于手动使用。 默认情况下，文件以非延迟方式打开。 如果通过 '-'，这可以打开常规文件以及 stdin/stdout。

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

with open_file(filename) as f:
    ...

3.0 版中的新功能。

参数

• filename – 要打开的文件的名称（或 '-' 用于 stdin/stdout）。

• mode – 打开文件的模式。

• encoding – 要使用的编码。

• errors – 此文件的错误处理。

• lazy – 可以翻转为真以延迟打开文件。

• atomic – 在原子模式下写入进入临时文件并在关闭时移动。

click.get_app_dir(app_name: str, roaming: bool = True, force_posix: bool = False) → str

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

给您一个想法，对于名为 "Foo Bar" 的应用程序，可能会返回以下文件夹：

Mac OS X：

~/Library/Application Support/Foo Bar

Mac OS X (POSIX)：

~/.foo-bar

Unix：

~/.config/foo-bar

Unix (POSIX)：

~/.foo-bar

Windows（漫游）：

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

Windows（非漫游）：

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

2.0 版中的新功能。

参数

• app_name – 应用程序名称。 这应该正确地大写并且可以包含空格。

• roaming – 控制文件夹是否应该在 Windows 上漫游。 其他方面没有影响。

• force_posix – 如果设置为 True，则在任何 POSIX 系统上，该文件夹将存储在主文件夹中，并带有前导点，而不是 XDG 配置主文件夹或 darwin 的应用程序支持文件夹。

click.format_filename(filename: Union[str, bytes, os.PathLike], shorten: bool = False) → str

格式化文件名以供用户显示。 该函数的主要目的是确保文件名完全可以显示。 如有必要，这将以不会失败的方式将文件名解码为 unicode。 或者，它可以缩短文件名以不包括文件名的完整路径。

参数

;;* filename – 格式化用于 UI 显示的文件名。 这也会将文件名转换为 unicode 而不会失败。

• shorten - 这可以选择缩短文件名以去除通向它的路径。

命令

class click.BaseCommand(name: Optional[str], context_settings: Optional[Dict[str, Any]] = None)

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

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

由于基本命令没有实现 Click 的其他部分认为理所当然的许多 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_class

使用 make_context() 创建的上下文类。

8.0 版中的新功能。

click.core.Context 的别名

context_settings: Dict[str, Any]

一个可选的字典，默认值传递给上下文。

ignore_unknown_options = False

Context.ignore_unknown_options 标志的默认值。

invoke(ctx: click.core.Context) → Any

给定上下文，这将调用命令。 默认实现会引发未实现的错误。

main(args: Optional[Sequence[str]] = None, prog_name: Optional[str] = None, complete_var: Optional[str] = None, standalone_mode: bool = True, windows_expand_args: bool = True, **extra: Any) → Any

这是调用具有所有功能的脚本作为命令行应用程序的方法。 这将始终在调用后终止应用程序。 如果这不是想要的，则需要捕获 SystemExit。

也可以通过直接调用 Command 的实例来使用此方法。

参数

• args – 应该用于解析的参数。 如果未提供，则使用 sys.argv[1:]。

• prog_name – 应该使用的程序名称。 默认情况下，程序名是通过从 sys.argv[0] 中获取文件名来构造的。

• complete_var – 控制 bash 完成支持的环境变量。 默认值为 "_<prog_name>_COMPLETE"，prog_name 为大写。

• standalone_mode – 默认行为是在独立模式下调用脚本。 Click 然后将处理异常并将它们转换为错误消息，该函数将永远不会返回但会关闭解释器。 如果将其设置为 False，它们将被传播到调用者，并且该函数的返回值是 invoke() 的返回值。

• windows_expand_args – 在 Windows 的命令行参数中扩展全局模式、用户目录和环境变量。

• extra – 额外的关键字参数被转发到上下文构造函数。 有关更多信息，请参阅 上下文 。

在 8.0.1 版更改： 添加了 windows_expand_args 参数以允许在 Windows 上禁用命令行参数扩展。

8.0 版更改： 在 Windows 上从 sys.argv 获取参数时，glob 模式、用户目录和环境变量被扩展。

3.0 版本变化： 增加了 standalone_mode 参数。

make_context(info_name: Optional[str], args: List[str], parent: Optional[click.core.Context] = None, **extra: Any) → click.core.Context

当给定信息名称和参数时，此函数将开始解析并创建一个新的 上下文 。 但是它不会调用实际的命令回调。

要在不覆盖此方法的情况下快速自定义使用的上下文类，请设置 context_class 属性。

参数

• info_name – 此调用的信息名称。 通常，这是脚本或命令最具描述性的名称。 对于顶层脚本，它通常是脚本的名称，对于它下面的命令，它是命令的名称。

• args – 解析为字符串列表的参数。

• parent – 父上下文（如果可用）。

• extra – 转发给上下文构造函数的额外关键字参数。

8.0 版变更： 添加 context_class 属性。

name

命令认为它具有的名称。 在 Group 上注册命令后，该组将使用此信息默认命令名称。 您应该改为使用 Context's info_name 属性。

parse_args(ctx: click.core.Context, args: List[str]) → List[str]

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

shell_complete(ctx: click.core.Context, incomplete: str) → List[CompletionItem]

返回不完整值的完成列表。 查看链接的多命令的名称。

任何命令都可以是链接的多命令的一部分，因此同级命令在命令完成期间的任何时候都是有效的。 其他命令类将返回更多完成。

参数

• ctx – 此命令的调用上下文。

• incomplete – 正在完成的值。 可能是空的。

8.0 版中的新功能。

to_info_dict(ctx: click.core.Context) → Dict[str, Any]

收集可能对生成面向用户的文档的工具有用的信息。 这将遍历此命令下方的整个结构。

使用 click.Context.to_info_dict() 遍历整个 CLI 结构。

参数

ctx – 表示此命令的 Context。

8.0 版中的新功能。

class click.Command(name: Optional[str], context_settings: Optional[Dict[str, Any]] = None, callback: Optional[Callable[[...], Any]] = None, params: Optional[List[click.core.Parameter]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False)

命令是 Click 中命令行界面的基本构建块。 一个基本命令处理命令行解析，并且可能会向嵌套在它下面的命令分派更多的解析。

2.0 版更改： 添加 context_settings 参数。

在 8.0 版更改： 添加了显示命令名称的 repr

7.1 版更改： 添加 no_args_is_help 参数。

参数

• name – 要使用的命令的名称，除非组覆盖它。

• context_settings – 一个可选的字典，带有传递给上下文对象的默认值。

• callback – 要调用的回调。 这是可选的。

• params – 使用此命令注册的参数。 这可以是 Option 或 Argument 对象。

• help – 用于此命令的帮助字符串。

• epilog – 类似于帮助字符串，但它在帮助页面的末尾打印在其他所有内容之后。

• short_help – 用于此命令的简短帮助。 这显示在父命令的命令列表中。

• add_help_option – 默认情况下，每个命令都会注册一个 --help 选项。 这可以通过此参数禁用。

• no_args_is_help – 这控制了如果没有提供参数会发生什么。 默认情况下禁用此选项。 如果启用，如果没有传递参数，这将添加 --help 作为参数

• hidden – 在帮助输出中隐藏此命令。

• deprecated – 发出一条消息，指示该命令已被弃用。

callback

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

collect_usage_pieces(ctx: click.core.Context) → List[str]

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

format_epilog(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

如果存在，则将结语写入格式化程序。

format_help(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

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

这是一个由 get_help() 调用的低级方法。

这会调用以下方法：

• format_usage()

• format_help_text()

• format_options()

• format_epilog()

format_help_text(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

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

format_options(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

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

format_usage(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

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

这是一个由 get_usage() 调用的低级方法。

get_help(ctx: click.core.Context) → str

将帮助格式化为字符串并返回它。

在内部调用 format_help()。

get_help_option(ctx: click.core.Context) → Optional[click.core.Option]

返回帮助选项对象。

get_help_option_names(ctx: click.core.Context) → List[str]

返回帮助选项的名称。

get_short_help_str(limit: int = 45) → str

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

get_usage(ctx: click.core.Context) → str

将用法行格式化为字符串并返回它。

在内部调用 format_usage()。

invoke(ctx: click.core.Context) → Any

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

make_parser(ctx: click.core.Context) → click.parser.OptionParser

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

params: List[click.core.Parameter]

此命令的参数列表，按照它们在帮助页面中显示和执行的顺序排列。 急切参数将在非急切参数之前自动处理。

parse_args(ctx: click.core.Context, args: List[str]) → List[str]

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

shell_complete(ctx: click.core.Context, incomplete: str) → List[CompletionItem]

返回不完整值的完成列表。 查看选项和链接的多命令的名称。

参数

• ctx – 此命令的调用上下文。

• incomplete – 正在完成的值。 可能是空的。

8.0 版中的新功能。

to_info_dict(ctx: click.core.Context) → Dict[str, Any]

收集可能对生成面向用户的文档的工具有用的信息。 这将遍历此命令下方的整个结构。

使用 click.Context.to_info_dict() 遍历整个 CLI 结构。

参数

ctx – 表示此命令的 Context。

8.0 版中的新功能。

class click.MultiCommand(name: Optional[str] = None, invoke_without_command: bool = False, no_args_is_help: Optional[bool] = None, subcommand_metavar: Optional[str] = None, chain: bool = False, result_callback: Optional[Callable[[...], Any]] = None, **attrs: Any)

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

参数

• invoke_without_command – 这控制如何调用多命令本身。 默认情况下，只有在提供了子命令时才会调用它。

• no_args_is_help – 这控制了如果没有提供参数会发生什么。 如果 invoke_without_command 禁用或禁用（如果启用），则默认启用此选项。 如果启用，如果没有传递参数，这将添加 --help 作为参数。

• subcommand_metavar – 文档中用于指示子命令位置的字符串。

• chain – 如果设置为 True 启用多个子命令的链接。 这限制了命令的形式，因为它们不能有可选参数，但它允许将多个命令链接在一起。

• result_callback – 要附加到此多命令的结果回调。 这可以稍后使用 result_callback() 装饰器设置或更改。

collect_usage_pieces(ctx: click.core.Context) → List[str]

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

format_commands(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

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

format_options(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) → None

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

get_command(ctx: click.core.Context, cmd_name: str) → Optional[click.core.Command]

给定上下文和命令名称，如果存在，则返回 Command 对象或返回 None。

invoke(ctx: click.core.Context) → Any

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

list_commands(ctx: click.core.Context) → List[str]

按应出现的顺序返回子命令名称的列表。

parse_args(ctx: click.core.Context, args: List[str]) → List[str]

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

result_callback(replace: bool = False) → Callable[[click.core.F], click.core.F]

向命令添加结果回调。 默认情况下，如果结果回调已经注册，这将链接它们，但可以使用 replace 参数禁用它。 结果回调使用子命令的返回值（或所有子命令的返回值列表，如果启用链接）以及将传递给主回调的参数调用。

例子：

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

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

参数

replace – 如果设置为 True 一个已经存在的结果回调将被删除。

8.0 版变更： 由 resultcallback 重命名。

3.0 版中的新功能。

shell_complete(ctx: click.core.Context, incomplete: str) → List[CompletionItem]

返回不完整值的完成列表。 查看选项、子命令和链接的多命令的名称。

参数

• ctx – 此命令的调用上下文。

• incomplete – 正在完成的值。 可能是空的。

8.0 版中的新功能。

to_info_dict(ctx: click.core.Context) → Dict[str, Any]

收集可能对生成面向用户的文档的工具有用的信息。 这将遍历此命令下方的整个结构。

使用 click.Context.to_info_dict() 遍历整个 CLI 结构。

参数

ctx – 表示此命令的 Context。

8.0 版中的新功能。

class click.Group(name: Optional[str] = None, commands: Optional[Union[Dict[str, click.core.Command], Sequence[click.core.Command]]] = None, **attrs: Any)

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

参数

• name – 组命令的名称。

• commands – 将名称映射到 Command 对象的字典。 也可以是 Command 的列表，它将使用 Command.name 创建字典。

• attrs – MultiCommand、Command 和 BaseCommand 中描述的其他命令参数。

在 8.0 版更改： commmands 参数可以是命令对象列表。

add_command(cmd: click.core.Command, name: Optional[str] = None) → None

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

command(*args: Any, **kwargs: Any) → Callable[[Callable[[...], Any]], click.core.Command]

用于声明和附加命令到组的快捷方式装饰器。 这采用与 command() 相同的参数，并通过调用 add_command() 立即向该组注册创建的命令。

要自定义使用的命令类，请设置 command_class 属性。

8.0 版变更： 添加 command_class 属性。

command_class: Optional[Type[click.core.Command]] = None

如果设置，它被组的 command() 装饰器用作默认的 Command 类。 这对于使所有子命令使用自定义命令类很有用。

8.0 版中的新功能。

commands: Dict[str, click.core.Command]

按其导出名称注册的子命令。

get_command(ctx: click.core.Context, cmd_name: str) → Optional[click.core.Command]

给定上下文和命令名称，如果存在，则返回 Command 对象或返回 None。

group(*args: Any, **kwargs: Any) → Callable[[Callable[[...], Any]], click.core.Group]

用于声明组并将其附加到组的快捷方式装饰器。 这采用与 group() 相同的参数，并通过调用 add_command() 立即向该组注册创建的组。

要自定义使用的组类，请设置 group_class 属性。

8.0 版本变更： 添加 group_class 属性。

group_class: Optional[Union[Type[click.core.Group], Type[type]]] = None

如果设置，它被组的 group() 装饰器用作默认的 Group 类。 这对于使所有子组使用自定义组类很有用。

如果设置为特殊值 type（字面意思是 group_class = type），则该组的类将用作默认类。 这使得自定义组类继续创建自定义组。

8.0 版中的新功能。

list_commands(ctx: click.core.Context) → List[str]

按应出现的顺序返回子命令名称的列表。

class click.CommandCollection(name: Optional[str] = None, sources: Optional[List[click.core.MultiCommand]] = None, **attrs: Any)

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

add_source(multi_cmd: click.core.MultiCommand) → None

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

get_command(ctx: click.core.Context, cmd_name: str) → Optional[click.core.Command]

给定上下文和命令名称，如果存在，则返回 Command 对象或返回 None。

list_commands(ctx: click.core.Context) → List[str]

按应出现的顺序返回子命令名称的列表。

sources: List[click.core.MultiCommand]

已注册的多命令列表。

参数

class click.Parameter(param_decls: Optional[Sequence[str]] = None, type: Optional[Union[click.types.ParamType, Any]] = None, required: bool = False, default: Optional[Union[Any, Callable[[], Any]]] = None, callback: Optional[Callable[[click.core.Context, Parameter, Any], Any]] = None, nargs: Optional[int] = None, multiple: bool = False, metavar: Optional[str] = None, expose_value: bool = True, is_eager: bool = False, envvar: Optional[Union[Sequence[str], str]] = None, shell_complete: Optional[Callable[[click.core.Context, Parameter, str], Union[List[CompletionItem], List[str]]]] = None, autocompletion: Optional[Callable[[click.core.Context, List[str], str], List[Union[Tuple[str, str], str]]]] = None)

命令的参数有两个版本：它们是 Options 或 Arguments。 其他子类目前不受设计支持，因为一些用于解析的内部结构不是有意完成的。

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

参数

• param_decls – 此选项或参数的参数声明。 这是一个标志或参数名称的列表。

• type – 应该使用的类型。 ParamType 或 Python 类型。 如果支持，后者会自动转换为前者。

• required – 控制这是否是可选的。

• default – 如果省略则为默认值。 这也可以是可调用的，在这种情况下，它会在不需要任何参数的情况下需要默认值时调用。

• callback – 在类型转换后进一步处理或验证值的函数。 它被称为 f(ctx, param, value) 并且必须返回值。 它适用于所有来源，包括提示。

• nargs – 要匹配的参数数量。 如果不是 1，则返回值是一个元组而不是单个值。 nargs 的默认值是 1（除非类型是元组，否则它是元组的元数）。 如果是 nargs=-1，则收集所有剩余参数。

• metavar – 值在帮助页面中的表示方式。

• expose_value – 如果这是 True 则该值将继续传递给命令回调并存储在上下文中，否则将被跳过。

• is_eager – 急切值在非急切值之前处理。 这不应为参数设置，否则会颠倒处理顺序。

• envvar – 应检查的环境变量的字符串或字符串列表。

• shell_complete – 返回自定义 shell 完成的函数。 如果给定，则用于代替参数的类型完成。 采用 ctx, param, incomplete 并且必须返回 CompletionItem 列表或字符串列表。

8.0 版本变更： process_value 验证所需参数并有界 nargs，并在返回值之前调用参数回调。 这允许回调验证提示。 full_process_value 被移除。

8.0 版更改：autocompletion 重命名为 shell_complete 并具有上述新语义。 旧名称已弃用，并将在 8.1 中删除，直到那时它将被包装以匹配新要求。

8.0 版本变更：对于multiple=True, nargs>1，默认必须是元组列表。

8.0 版本更改： nargs>1 不再需要设置默认值，将默认为 None。 multiple=True 或 nargs=-1 将默认为 ()。

7.1 版更改： 忽略空环境变量而不是采用空字符串值。 这使得脚本可以在无法取消设置的情况下清除变量。

在 2.0 版更改：更改了参数回调的签名也可以传递参数。 旧的回调格式仍然有效，但它会发出警告，让您有机会更轻松地迁移代码。

get_default(ctx: click.core.Context, call: bool = True) → Optional[Union[Any, Callable[[], Any]]]

获取参数的默认值。 首先尝试 Context.lookup_value()，然后是本地默认值。

参数

• ctx – 当前上下文。

• call – 如果默认是可调用的，调用它。 禁用以返回可调用对象。

8.0.1 版更改： 类型转换在弹性解析模式下可能会失败。 无效的默认值不会阻止显示帮助文本。

8.0 更改： 先看ctx.default_map。

8.0 版本变化： 增加了 call 参数。

get_error_hint(ctx: click.core.Context) → str

获取参数的字符串化版本以用于错误消息以指示哪个参数导致错误。

property human_readable_name: str

返回此参数的人类可读名称。 这与选项的名称相同，但与参数的元变量相同。

shell_complete(ctx: click.core.Context, incomplete: str) → List[CompletionItem]

返回不完整值的完成列表。 如果在 init 期间给出了 shell_complete 函数，则使用它。 否则，使用 type shell_complete() 功能。

参数

• ctx – 此命令的调用上下文。

• incomplete – 正在完成的值。 可能是空的。

8.0 版中的新功能。

to_info_dict() → Dict[str, Any]

收集可能对生成面向用户的文档的工具有用的信息。

使用 click.Context.to_info_dict() 遍历整个 CLI 结构。

8.0 版中的新功能。

type_cast_value(ctx: click.core.Context, value: Any) → Any

根据选项的 type、multiple 和 nargs 转换和验证值。

class click.Option(param_decls: Optional[Sequence[str]] = None, show_default: bool = False, prompt: Union[bool, str] = False, confirmation_prompt: Union[bool, str] = False, prompt_required: bool = True, hide_input: bool = False, is_flag: Optional[bool] = None, flag_value: Optional[Any] = None, multiple: bool = False, count: bool = False, allow_from_autoenv: bool = True, type: Optional[Union[click.types.ParamType, Any]] = None, help: Optional[str] = None, hidden: bool = False, show_choices: bool = True, show_envvar: bool = False, **attrs: Any)

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

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

参数

• show_default – 控制是否应在帮助页面上显示默认值。 通常，不显示默认值。 如果此值是字符串，则显示字符串而不是值。 这对于动态选项特别有用。

• show_envvar – 控制是否应在帮助页面上显示环境变量。 通常，不显示环境变量。

• prompt – 如果设置为 True 或非空字符串，则将提示用户输入。 如果设置为 True，提示将是大写的选项名称。

• confirmation_prompt – 如果有提示，则再次提示确认该值。 可以设置为字符串而不是 True 来自定义消息。

• prompt_required – 如果设置为 False，则仅当该选项被指定为没有值的标志时，才会提示用户输入。

• hide_input – 如果这是 True 那么提示上的输入将对用户隐藏。 这对于密码输入很有用。

• is_flag – 强制此选项充当标志。 默认为自动检测。

• flag_value – 如果启用该标志，应使用哪个值。 如果选项字符串包含用于标记两个选项的斜杠，则它会自动设置为布尔值。

• multiple – 如果设置为 True，则参数被多次接受并记录。 这类似于 nargs 的工作方式，但支持任意数量的参数。

• count – 此标志使选项递增一个整数。

• allow_from_autoenv – 如果启用此选项，则该参数的值将从环境变量中提取，以防在上下文中定义前缀。

• help – 帮助字符串。

• hidden – 在帮助输出中隐藏此选项。

在 8.0.1 版更改：如果给出，则从 flag_value 检测到 type。

class click.Argument(param_decls: Sequence[str], required: Optional[bool] = None, **attrs: Any)

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

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

语境

class click.Context(command: click.core.Command, parent: Optional[click.core.Context] = None, info_name: Optional[str] = None, obj: Optional[Any] = None, auto_envvar_prefix: Optional[str] = None, default_map: Optional[Dict[str, Any]] = None, terminal_width: Optional[int] = None, max_content_width: Optional[int] = None, resilient_parsing: bool = False, allow_extra_args: Optional[bool] = None, allow_interspersed_args: Optional[bool] = None, ignore_unknown_options: Optional[bool] = None, help_option_names: Optional[List[str]] = None, token_normalize_func: Optional[Callable[[str], str]] = None, color: Optional[bool] = None, show_default: Optional[bool] = None)

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

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

上下文可以用作上下文管理器，在这种情况下，它会在拆卸时调用 close()。

参数

• 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 – 指示点击忽略它不知道的选项并保留它们以供以后处理。

• help_option_names – 可选的字符串列表，用于定义默认帮助参数的命名方式。 默认值为 ['--help']。

• token_normalize_func – 一个可选函数，用于规范化标记（选项、选择等）。 例如，这可用于实现不区分大小写的行为。

• color – 控制终端是否支持 ANSI 颜色。 默认为自动检测。 仅当在 Click 打印的文本中使用 ANSI 代码时才需要这样做，但默认情况下并非如此。 例如，这会影响帮助输出。

• show_default – 显示所有选项的默认值。 如果未设置，则默认为来自父上下文的值。 覆盖选项的 show_default 参数。

8.0 版更改： show_default 参数默认为来自父上下文的值。

7.1 版变更： 增加了 show_default 参数。

4.0 版本变更： 添加了 color、ignore_unknown_options 和 max_content_width 参数。

3.0 版本变更： 增加了 allow_extra_args 和 allow_interspersed_args 参数。

2.0 版本变更： 添加了 resilient_parsing、help_option_names 和 token_normalize_func 参数。

abort() → te.NoReturn

中止脚本。

allow_extra_args

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

3.0 版中的新功能。

allow_interspersed_args: bool

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

3.0 版中的新功能。

args: List[str]

剩下的论点。

call_on_close(f: Callable[[...], Any]) → Callable[[...], Any]

注册一个在上下文拆除时要调用的函数。

这可用于关闭在脚本执行期间打开的资源。 支持将在 with 语句中使用的 Python 上下文管理器协议的资源应改为使用 with_resource() 注册。

参数

f – 在拆卸时执行的函数。

close() → None

调用所有用 call_on_close() 注册的关闭回调，并退出所有用 with_resource() 输入的上下文管理器。

color: Optional[bool]

控制是否需要样式输出。

command

此上下文的 Command。

property command_path: str

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

ensure_object(object_type: Type[click.core.V]) → click.core.V

类似于 find_object() 但如果它不存在，则将最里面的对象设置为 object_type 的新实例。

exit(code: int = 0) → te.NoReturn

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

fail(message: str) → te.NoReturn

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

参数

message – 失败的错误消息。

find_object(object_type: Type[click.core.V]) → Optional[click.core.V]

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

find_root() → click.core.Context

找到最外层的上下文。

formatter_class

click.formatting.HelpFormatter 的别名

forward(_Context__cmd: click.core.Command, *args: Any, **kwargs: Any) → Any

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

在 8.0 版更改： 所有 kwargs 在 params 中进行跟踪，因此如果在多个级别调用 forward，它们将被传递。

get_help() → str

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

get_parameter_source(name: str) → Optional[click.core.ParameterSource]

获取参数的来源。 这表示获取参数值的位置。

这对于确定用户何时在命令行上指定与默认值相同的值非常有用。 仅当该值实际上取自默认值时，它才会是 DEFAULT。

参数

name – 参数的名称。

返回类型

参数源

在 8.0 版中更改： 如果参数未从任何来源提供，则返回 None。

get_usage() → str

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

help_option_names: List[str]

帮助选项的名称。

ignore_unknown_options: bool

指示单击忽略命令不理解的选项并将其存储在上下文中以供以后处理。 这主要用于您想要调用外部程序的情况。 通常，强烈建议不要使用这种模式，因为不可能无损地转发所有参数。

4.0 版中的新功能。

info_name

描述性信息名称

invoke(_Context__callback: Union[click.core.Command, Callable[[...], Any]], *args: Any, **kwargs: Any) → Any

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

1. 第一个参数可以是回调，所有其他参数和关键字参数都直接转发给函数。

2. 第一个参数是一个单击命令对象。 在这种情况下，所有参数也会被转发，但正确的点击参数（选项和点击参数）必须是关键字参数，并且 Click 将填充默认值。

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

8.0 版更改：所有 kwargs 都在 params 中进行跟踪，因此如果在多个级别调用 forward()，它们将被传递。

invoked_subcommand: Optional[str]

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

如果启用链接，这将设置为 '*'，以防执行任何命令。 然而，无法弄清楚哪些是。 如果您需要这些知识，您应该使用 result_callback()。

lookup_default(name: str, call: bool = True) → Optional[Any]

从 default_map 获取参数的默认值。

参数

• name – 参数名称。

• call – 如果默认是可调用的，调用它。 禁用以返回可调用对象。

8.0 版本变化： 增加了 call 参数。

make_formatter() → click.formatting.HelpFormatter

为帮助和用法输出创建 HelpFormatter。

要在不覆盖此方法的情况下快速自定义使用的格式化程序类，请设置 formatter_class 属性。

8.0 版变更： 添加 formatter_class 属性。

max_content_width: Optional[int]

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

property meta: Dict[str, Any]

这是一个与所有嵌套上下文共享的字典。 它的存在是为了让 click 实用程序可以在需要时在此处存储一些状态。 然而，管理这本字典是该代码的责任。

键应该是唯一的虚线字符串。 例如模块路径是一个不错的选择。 里面存放的是什么与点击操作无关。 然而，重要的是将数据放置在这里的代码符合系统的一般语义。

用法示例：

LANG_KEY = f'{__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: Any

存储的用户对象。

params: Dict[str, Any]

参数名称到其解析值的映射。 不存储带有 expose_value=False 的参数。

parent

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

protected_args: List[str]

受保护的参数。 这些是在遇到某些解析场景时附加到 args 的参数，但绝不能传播到另一个参数。 这用于实现嵌套解析。

resilient_parsing: bool

指示是否启用了弹性解析。 在这种情况下，Click 将尽最大努力不导致任何失败，并且默认值将被忽略。 对完成有用。

scope(cleanup: bool = True) → Iterator[click.core.Context]

此辅助方法可与上下文对象一起使用以将其提升到当前线程本地（请参阅 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 – 控制是否应该运行清理功能。 默认是运行这些函数。 在某些情况下，上下文只想暂时推送，在这种情况下可以禁用它。 嵌套推送会自动推迟清理。

set_parameter_source(name: str, source: click.core.ParameterSource) → None

设置参数的来源。 这表示获取参数值的位置。

参数

• name – 参数的名称。

• source – ParameterSource 的成员。

show_default: Optional[bool]

格式化帮助文本时显示选项默认值。

terminal_width: Optional[int]

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

to_info_dict() → Dict[str, Any]

收集可能对生成面向用户的文档的工具有用的信息。 这将遍历整个 CLI 结构。

with Context(cli) as ctx:
    info = ctx.to_info_dict()

8.0 版中的新功能。

token_normalize_func: Optional[Callable[[str], str]]

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

with_resource(context_manager: ContextManager[click.core.V]) → click.core.V

注册一个资源，就像它在 with 语句中使用一样。 弹出上下文时将清理资源。

使用 contextlib.ExitStack.enter_context()。 它调用资源的 __enter__() 方法并返回结果。 当上下文被弹出时，它关闭堆栈，调用资源的 __exit__() 方法。

要为不是上下文管理器的东西注册清理函数，请使用 call_on_close()。 或者先用 contextlib 中的东西把它变成一个上下文管理器。

@click.group()
@click.option("--name")
@click.pass_context
def cli(ctx):
    ctx.obj = ctx.with_resource(connect_db(name))

参数

context_manager – 要进入的上下文管理器。

退货

无论 context_manager.__enter__() 返回什么。

8.0 版中的新功能。

click.get_current_context(silent: bool = False) → Optional[Context]

返回当前点击上下文。 这可以用作从任何地方访问当前上下文对象的一种方式。 这是 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: str = 'r', encoding: Optional[str] = None, errors: Optional[str] = 'strict', lazy: Optional[bool] = None, atomic: bool = False)

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

可以打开文件进行读取或写入。 特殊值 - 根据模式指示标准输入或标准输出。

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

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

从 Click 2.0 开始，还可以自动打开文件，在这种情况下，所有写入都会进入同一文件夹中的单独文件，完成后文件将移至原始位置。 如果修改了其他用户定期读取的文件，这将非常有用。

有关详细信息，请参阅 文件参数 。

class click.Path(exists: bool = False, file_okay: bool = True, dir_okay: bool = True, writable: bool = False, readable: bool = True, resolve_path: bool = False, allow_dash: bool = False, path_type: Optional[Type] = None)

路径类型类似于 File 类型，但它执行不同的检查。 首先，它不返回打开的文件句柄，而是只返回文件名。 其次，它可以执行关于文件或目录应该是什么的各种基本检查。

参数

• exists – 如果设置为 true，则文件或目录需要存在才能使此值有效。 如果这不是必需的并且文件确实不存在，那么所有进一步的检查都将被静默跳过。

• file_okay – 控制文件是否是可能的值。

• dir_okay – 控制目录是否是可能的值。

• writable – 如果为真，则执行可写检查。

• readable – 如果为真，则执行可读检查。

• resolve_path – 如果这是真的，那么在传递值之前路径被完全解析。 这意味着它是绝对的并且符号链接已解决。 它不会扩展波浪号前缀，因为这应该仅由 shell 完成。

• allow_dash – 如果设置为 True，则允许使用单个破折号来指示标准流。

• path_type – 将传入路径值转换为此类型。 如果是 None，则保留 Python 的默认值，即 str。 用于转换为 pathlib.Path。

8.0 版本变更：允许通过 type=pathlib.Path。

6.0 版本变化： 增加了 allow_dash 参数。

class click.Choice(choices: Sequence[str], case_sensitive: bool = True)

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

您应该只传递选择列表或元组。 其他可迭代对象（如生成器）可能会导致令人惊讶的结果。

无论指定 case_sensitive 或任何 ctx.token_normalize_func，结果值将始终是最初传递的选项之一。

有关示例，请参阅 选择选项 。

参数

case_sensitive – 设置为 false 以使选择不区分大小写。 默认为真。

class click.IntRange(min: Optional[float] = None, max: Optional[float] = None, min_open: bool = False, max_open: bool = False, clamp: bool = False)

将 click.INT 值限制为可接受值的范围。 请参阅 范围选项 。

如果未通过 min 或 max，则在该方向上接受任何值。 如果启用了 min_open 或 max_open，则相应的边界不包含在范围内。

如果启用 clamp，超出范围的值将被限制在边界上而不是失败。

8.0 版本变更： 增加了 min_open 和 max_open 参数。

class click.Tuple(types: Sequence[Union[Type, click.types.ParamType]])

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

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

这可以通过使用 Python 元组文字作为类型来选择。

参数

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

class click.ParamType

表示参数的类型。 验证命令行或 Python 中的值并将其转换为正确的类型。

要实现自定义类型，子类并至少实现以下内容：

• 必须设置 name 类属性。

• 使用 None 调用类型的实例必须返回 None。 这已经默认实现了。

• convert() 必须将字符串值转换为正确的类型。

• convert() 必须接受已经是正确类型的值。

• 如果 ctx 和 param 参数是 None，它必须能够转换一个值。 转换提示输入时可能会发生这种情况。

convert(value: Any, param: Optional[Parameter], ctx: Optional[Context]) → Any

将值转换为正确的类型。 如果值为 None（缺失值），则不会调用此方法。

这必须接受来自命令行的字符串值，以及已经是正确类型的值。 它还可以转换其他兼容类型。

param 和 ctx 参数在某些情况下可能是 None，例如在转换提示输入时。

如果无法转换该值，请使用描述性消息调用 fail()。

参数

• value – 要转换的值。

• param – 使用此类型转换其值的参数。 可能是 None。

• ctx – 到达此值的当前上下文。 可能是 None。

envvar_list_splitter: ClassVar[Optional[str]] = None

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

fail(message: str, param: Optional[Parameter] = None, ctx: Optional[Context] = None) → t.NoReturn

帮助方法失败并显示无效值消息。

get_metavar(param: Parameter) → Optional[str]

如果提供此参数，则返回此参数的元变量默认值。

get_missing_message(param: Parameter) → Optional[str]

可以选择返回有关缺失参数的额外信息。

2.0 版中的新功能。

name: str

这种类型的描述性名称

shell_complete(ctx: Context, param: Parameter, incomplete: str) → List[CompletionItem]

返回不完整值的 CompletionItem 对象列表。 大多数类型不提供补全，但有些提供，这允许自定义类型也提供自定义补全。

参数

• ctx – 此命令的调用上下文。

• param – 请求完成的参数。

• incomplete – 正在完成的值。 可能是空的。

8.0 版中的新功能。

split_envvar_value(rv: str) → Sequence[str]

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

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

to_info_dict() → Dict[str, Any]

收集可能对生成面向用户的文档的工具有用的信息。

使用 click.Context.to_info_dict() 遍历整个 CLI 结构。

8.0 版中的新功能。

例外

exception click.ClickException(message: str)

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

exception click.Abort

一个内部信号异常，它发出单击以中止的信号。

exception click.UsageError(message: str, ctx: Optional[Context] = None)

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

参数

;;* message – 要显示的错误消息。

• ctx – 可选的导致此错误的上下文。 在某些情况下，单击会自动填充上下文。

exception click.BadParameter(message: str, ctx: Optional[Context] = None, param: Optional[Parameter] = None, param_hint: Optional[str] = None)

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

2.0 版中的新功能。

参数

• param – 导致此错误的参数对象。 这可以省略，如果可能，Click 将附加此信息本身。

• param_hint – 显示为参数名称的字符串。 在应该发生自定义验证的情况下，这可以用作 param 的替代方法。 如果它是一个字符串，它就这样使用，如果它是一个列表，那么每个项目都被引用和分隔。

exception click.FileError(filename: str, hint: Optional[str] = None)

如果无法打开文件，则引发。

exception click.NoSuchOption(option_name: str, message: Optional[str] = None, possibilities: Optional[Sequence[str]] = None, ctx: Optional[Context] = None)

如果单击尝试处理不存在的选项，则引发。

4.0 版中的新功能。

exception click.BadOptionUsage(option_name: str, message: str, ctx: Optional[Context] = None)

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

4.0 版中的新功能。

参数

option_name – 错误使用的选项名称。

exception click.BadArgumentUsage(message: str, ctx: Optional[Context] = None)

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

6.0 版中的新功能。

格式化

class click.HelpFormatter(indent_increment: int = 2, width: Optional[int] = None, max_width: Optional[int] = None)

此类有助于格式化基于文本的帮助页面。 它通常只在非常特殊的内部情况下才需要，但它也被公开，以便开发人员可以编写自己的奇特输出。

目前，它总是写入内存。

参数

• indent_increment – 每个级别的附加增量。

• width – 文本的宽度。 这默认为端子宽度限制为最大值 78。

dedent() → None

减少缩进。

getvalue() → str

返回缓冲区内容。

indent() → None

增加缩进。

indentation() → Iterator[None]

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

section(name: str) → Iterator[None]

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

参数

name – 写为标题的部分名称。

write(string: str) → None

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

write_dl(rows: Sequence[Tuple[str, str]], col_max: int = 30, col_spacing: int = 2) → None

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

参数

• rows – 术语和值的两个项目元组的列表。

• col_max – 第一列的最大宽度。

• col_spacing – 第一列和第二列之间的空格数。

write_heading(heading: str) → None

将标题写入缓冲区。

write_paragraph() → None

将一个段落写入缓冲区。

write_text(text: str) → None

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

write_usage(prog: str, args: str = , prefix: Optional[str] = None) → None

将用法行写入缓冲区。

参数

• prog – 程序名称。

• args – 以空格分隔的参数列表。

• prefix – 第一行的前缀。 默认为 "Usage: "。

click.wrap_text(text: str, width: int = 78, initial_indent: str = , subsequent_indent: str = , preserve_paragraphs: bool = False) → str

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

如果处理了段落，则段落可以以包含 \b 字符 (\x08) 的空行作为前缀，以指示该块中不应发生重新换行。

参数

• text – 应该重新包装的文本。

• width – 文本的最大宽度。

• initial_indent – 应该作为字符串放在第一行的初始缩进。

• subsequent_indent – 应该放在每个连续行上的缩进字符串。

• preserve_paragraphs – 如果设置了此标志，则换行将智能地处理段落。

解析

class click.OptionParser(ctx: Optional[Context] = None)

选项解析器是一个内部类，最终用于解析选项和参数。 它以 optparse 为模型，并带来了类似但大大简化的 API。 通常不应直接使用它，因为高级 Click 类会为您包装它。

它不像 optparse 或 argparse 那样可扩展，因为它没有实现在更高级别实现的功能（例如类型或默认值）。

参数

ctx – 可选的 Context 这个解析器应该去的地方。

add_argument(obj: CoreArgument, dest: Optional[str], nargs: int = 1) → None

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

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

add_option(obj: CoreOption, opts: Sequence[str], dest: Optional[str], action: Optional[str] = None, nargs: int = 1, const: Optional[Any] = None) → None

向解析器添加一个名为 dest 的新选项。 目的地不是推断出来的（与 optparse 不同），需要明确提供。 动作可以是 store、store_const、append、appnd_const 或 count 中的任何一个。

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

allow_interspersed_args

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

ctx

此解析器的 Context。 对于某些高级用例，这可能是 None。

ignore_unknown_options

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

parse_args(args: List[str]) → Tuple[Dict[str, Any], List[str], List[CoreParameter]]

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

测试

class click.testing.CliRunner(charset: str = 'utf-8', env: Optional[Mapping[str, Optional[str]]] = None, echo_stdin: bool = False, mix_stderr: bool = True)

CLI 运行程序提供调用 Click 命令行脚本以在隔离环境中进行单元测试的功能。 这仅适用于没有任何并发性的单线程系统，因为它会更改全局解释器状态。

参数

• charset – 输入和输出数据的字符集。

• env – 带有用于覆盖的环境变量的字典。

• echo_stdin – 如果设置为 True，则从 stdin 读取写入到 stdout。 这对于在某些情况下显示示例很有用。 请注意，常规提示将自动回显输入。

• mix_stderr – 如果将其设置为 False，则 stdout 和 stderr 将保留为独立的流。 这对于具有可预测标准输出和嘈杂标准错误的 Unix 哲学应用程序非常有用，这样每个应用程序都可以独立测量

get_default_prog_name(cli: BaseCommand) → str

给定一个命令对象，它将为其返回默认程序名称。 默认值为 name 属性或 "root" 如果未设置。

invoke(cli: BaseCommand, args: Optional[Union[str, Sequence[str]]] = None, input: Optional[Union[str, bytes, IO]] = None, env: Optional[Mapping[str, Optional[str]]] = None, catch_exceptions: bool = True, color: bool = False, **extra: Any) → click.testing.Result

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

这将返回一个 Result 对象。

参数

• cli – 要调用的命令

• args – 要调用的参数。 它可以作为可迭代对象或字符串给出。 当作为字符串给出时，它将被解释为 Unix shell 命令。 更多详情请见 shlex.split()。

• input – sys.stdin 的输入数据。

• env – 环境覆盖。

• catch_exceptions – 是否捕获除 SystemExit 之外的任何其他异常。

• extra – 传递给 main() 的关键字参数。

• color – 输出是否应包含颜色代码。 应用程序仍然可以显式地覆盖它。

8.0 版更改： 结果对象具有 return_value 属性，其值从调用的命令返回。

4.0 版本变化： 增加了 color 参数。

3.0 版本变化： 增加了 catch_exceptions 参数。

在 3.0 版更改： 结果对象具有 exc_info 属性，如果可用，则带有回溯。

isolated_filesystem(temp_dir: Optional[Union[str, os.PathLike]] = None) → Iterator[str]

创建临时目录并将当前工作目录更改为该目录的上下文管理器。 这会隔离影响 CWD 内容的测试，以防止它们相互干扰。

参数

temp_dir – 在该目录下创建临时目录。 如果给定，则退出时不会删除创建的目录。

8.0 版本变化： 增加了 temp_dir 参数。

isolation(input: Optional[Union[str, bytes, IO]] = None, env: Optional[Mapping[str, Optional[str]]] = None, color: bool = False) → Iterator[Tuple[_io.BytesIO, Optional[_io.BytesIO]]]

为调用命令行工具设置隔离的上下文管理器。 这将使用给定的输入数据和 os.environ 使用给定字典中的覆盖设置 stdin。 这也会重新绑定 Click 中的一些内部结构以进行模拟（如提示功能）。

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

参数

• input – 要放入 sys.stdin 的输入流。

• env – 环境覆盖为字典。

• color – 输出是否应包含颜色代码。 应用程序仍然可以显式地覆盖它。

8.0 版本更改： stderr 用 errors="backslashreplace" 打开，而不是默认的 "strict"。

4.0 版本变化： 增加了 color 参数。

make_env(overrides: Optional[Mapping[str, Optional[str]]] = None) → Mapping[str, Optional[str]]

返回用于调用脚本的环境覆盖。

class click.testing.Result(runner: click.testing.CliRunner, stdout_bytes: bytes, stderr_bytes: Optional[bytes], return_value: Any, exit_code: int, exception: Optional[BaseException], exc_info: Optional[Tuple[Type[BaseException], BaseException, types.TracebackType]] = None)

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

exc_info

回溯

exception

如果有人这样做就会发生异常。

exit_code

退出代码为整数。

property output: str

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

return_value

从调用的命令返回的值。

8.0 版中的新功能。

runner

创建结果的跑步者

property stderr: str

作为 unicode 字符串的标准错误。

stderr_bytes

以字节为单位的标准错误，如果不可用，则为 None

property stdout: str

标准输出为 unicode 字符串。

stdout_bytes

以字节为单位的标准输出。