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() S和 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 -- 要实例化的参数类。默认为 Argument .

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

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

参数

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

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 必须安装后端口。

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

参数

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

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

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

  • 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 -- 强制显示或隐藏颜色和其他样式。默认情况下，如果输出看起来不像交互式终端，单击将删除颜色。

Changelog

在 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

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

Changelog

在 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[Union[click.types.ParamType, Any]] = 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 -- 如果设置为真，则输入值将隐藏。

  • confirmation_prompt -- 再次提示确认该值。可以设置为字符串，而不是 True 若要自定义消息，请执行以下操作。

  • 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）：”。

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

Changelog

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 。

Changelog

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

上下文管理器创建进度条。当输入上下文管理器时，进度条已经创建。随着进度条上的每一次迭代，传递给该条的迭代值都会前进，并且该条会被更新。当上下文管理器退出时，将打印一个换行符，并在屏幕上结束进度条。

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

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

示例用法：

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)

这个 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 -- 可重复的iterable。如果没有提供，则需要长度。

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

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

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

  • show_percent -- 启用或禁用百分比显示。默认值为 True 如果iterable有一个长度或 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 参数。

Changelog

在 4.0 版更改: 增加了 color 参数。添加了 update 方法添加到对象。

2.0 新版功能.

click.clear() → None

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

Changelog

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色模式。

  • 中三个整数的RGB元组 [0, 255] 。终端必须支持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 参数。

Changelog

在 7.0 版更改: 增加了对亮色的支持。

2.0 新版功能.

click.unstyle(text: str) → str

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

Changelog

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 转换为字符串。字节在未应用样式的情况下传递。

Changelog

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 提高了。

注意：为了简化跨平台的使用，换行符将自动从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)
Changelog

2.0 新版功能.

参数

  • url -- 要启动的对象的URL或文件名。

  • wait -- 等待程序退出后再返回。这仅在启动的程序阻止时才起作用。具体地说， xdg-open 在linux上不支持挡路。

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

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

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

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

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

Changelog

2.0 新版功能.

参数

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

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

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

Changelog

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

2.0 新版功能.

参数

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

  • err -- 如果设置为message，则转到 stderr 而不是 stdout 与Echo相同。

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:
    ...
Changelog

3.0 新版功能.

参数

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

  • mode -- 打开文件的模式。

  • encoding -- 要使用的编码。

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

  • lazy -- 可以翻转为true以延迟打开文件。

  • 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

Changelog

2.0 新版功能.

参数

  • app_name -- 应用程序名称。这应该是适当的大写，可以包含空格。

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

  • force_posix -- 如果设置为 True 然后，在任何POSIX系统上，文件夹都将存储在主文件夹中，并带有前导点，而不是xdg config home或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。

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

Changelog

在 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 新版功能.

alias of 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" 程序名为大写。

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

  • windows_expand_args -- 在Windows的命令行参数中展开glob模式、用户目录和环境变量。

  • extra -- 额外的关键字参数被转发到上下文构造函数。见 Context 更多信息。

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

在 8.0 版更改: 从以下位置获取参数时 sys.argv 在Windows上，展开了glob模式、用户目录和环境变量。

Changelog

在 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 . 但它不会调用实际的命令回调。

若要在不重写此方法的情况下快速自定义使用的上下文类，请将 context_class 属性。

参数

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

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

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

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

在 8.0 版更改: 增加了 context_class 属性。

name

命令认为它具有的名称。在 Group 该组将使用此信息默认命令名。你应该使用 Context 的 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 -- A 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中命令行接口的基本构建块。基本命令处理命令行分析，并可能将更多的分析分派给嵌套在它下面的命令。

在 8.0 版更改: 添加了显示命令名称的REPR

Changelog

在 7.1 版更改: 增加了 no_args_is_help 参数。

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

参数

  • 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

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

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

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

这是由调用的低级方法 get_help() .

这将调用以下方法：

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[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 -- A 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 。

Changelog

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 -- A 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)

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

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

参数

  • 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 -- 返回自定义外壳完成的函数。如果给定，则用来代替参数的类型完成。拿走 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 将默认为 () .

Changelog

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

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

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

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

参数

  • ctx -- 当前上下文。

  • call -- 如果默认值是Callable，则将其调用。禁用以返回可调用对象。

在 8.0.2 版更改: 获取默认值时不再执行类型转换。

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

在 8.0 版更改: 看着 ctx.default_map 第一。

在 8.0 版更改: 增加了 call 参数。

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

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

property human_readable_name: str

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

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

返回不完整值的完成列表。如果一个 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: Union[bool, str] = 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 版更改: type 是从以下位置检测到的 flag_value 如果给的话。

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 -- 指示Click忽略它不知道的选项，并将其保留以供以后处理。

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

  • token_normalize_func -- 用于规范化令牌（选项、选项等）的可选函数。例如，这可以用于实现不区分大小写的行为。

  • color -- 控制终端是否支持ANSI颜色。默认为自动检测。只有在Click打印的文本中使用了ANSI代码时才需要这样做，默认情况下不是这样。例如，这将影响帮助输出。

  • show_default -- 显示所有选项的默认值。如果未设置，则默认为父上下文中的值。覆盖选项的 show_default 争论。

在 8.0 版更改: 这个 show_default 参数默认为父上下文中的值。

Changelog

在 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

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

Changelog

3.0 新版功能.

allow_interspersed_args: bool

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

Changelog

3.0 新版功能.

args: List[str]

剩下的参数。

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

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

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

参数

f -- 要在tearDown上执行的函数。

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

alias of click.formatting.HelpFormatter

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

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

在 8.0 版更改: 全 kwargs 被追踪到 params 因此，如果符合以下条件，它们将获得通过 forward 在多个级别上调用。

get_help() → str

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

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

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

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

参数

name -- 参数的名称。

返回类型

ParameterSource

在 8.0 版更改: 返回 None 如果参数不是从任何来源提供的。

get_usage() → str

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

help_option_names: List[str]

帮助选项的名称。

ignore_unknown_options: bool

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

Changelog

4.0 新版功能.

info_name

描述性信息名称

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

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

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

  2. 第一个参数是click命令对象。在这种情况下，所有参数都会被转发，但正确的Click参数（选项和Click参数）必须是关键字参数，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 -- 如果默认值是Callable，则将其调用。禁用以返回可调用对象。

在 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实用程序可以在需要时在这里存储一些状态。然而，该代码的职责是管理好这本词典。

这些键应该是唯一的虚线。例如，模块路径是一个很好的选择。其中存储的内容与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')
Changelog

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[Context]

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

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

示例用法：

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

这相当于：

with ctx:
    assert get_current_context() is ctx
Changelog

5.0 新版功能.

参数

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

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

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

参数
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: AbstractContextManager[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]

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

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

Changelog

5.0 新版功能.

参数

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

class click.core.ParameterSource(value)

这是一个 Enum 它指示参数值的来源。

使用 click.Context.get_parameter_source() 若要按名称获取参数的源，请执行以下操作。

在 8.0 版更改: 使用 Enum 并丢弃 validate 方法。

在 8.0 版更改: 增加了 PROMPT 价值。

COMMANDLINE = 1

该值由命令行参数提供。

ENVIRONMENT = 2

该值随环境变量一起提供。

DEFAULT = 3

使用参数指定的默认值。

DEFAULT_MAP = 4

使用由提供的默认值 Context.default_map .

PROMPT = 5

已使用提示确认默认值或提供值。

类型

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)

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

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

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

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

从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 -- 如果这是真的，那么在向前进传递值之前，将完全解析路径。这意味着它是绝对的，符号链接被解析。它不会扩展tilde前缀，因为这只由shell完成。

  • allow_dash -- 如果设置为 True ，允许使用一个短划线指示标准流。

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

在 8.0 版更改: 允许通过 type=pathlib.Path 。

Changelog

在 6.0 版更改: 添加了 allow_dash 参数。

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

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

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

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

见 选择选项 举个例子。

参数

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

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.FloatRange(min: Optional[float] = None, max: Optional[float] = None, min_open: bool = False, max_open: bool = False, clamp: bool = False)

限制为 click.FLOAT 值设置为可接受的值范围。看见 范围选项 .

如果 min 或 max 不传递，则在该方向上接受任何值。如果 min_open 或 max_open 则相应的边界不包括在该范围内。

如果 clamp 启用时，范围外的值将被钳制到边界，而不是失败。如果标记了任一边界，则不支持此操作 open .

在 8.0 版更改: 增加了 min_open 和 max_open 参数。

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

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

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

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

参数

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

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

get_metavar(param: Parameter) → Optional[str]

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

get_missing_message(param: Parameter) → Optional[str]

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

Changelog

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

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

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

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

参数

  • message -- 要显示的错误消息。

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

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

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

Changelog

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)

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

Changelog

4.0 新版功能.

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

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

Changelog

4.0 新版功能.

参数

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

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

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

Changelog

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 ， append_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) 对于已解析的选项和参数以及剩余的参数（如果有）。顺序是显示在命令行上的对象列表。如果参数出现多次，它们也会被记住多次。

外壳完成

见 殻が完成する. 有关启用和自定义Click的shell完成系统的信息。

class click.shell_completion.CompletionItem(value: Any, type: str = 'plain', help: Optional[str] = None, **kwargs: Any)

表示完成值和有关该值的元数据。默认元数据为 type 以指示特殊外壳处理，以及 help 如果外壳程序支持在值旁边显示帮助字符串。

创建对象时可以传递任意参数，并使用 item.attr 。如果未传递属性，则访问该属性将返回 None .

参数

  • value -- 竣工建议书。

  • type -- 通知shell脚本为该类型提供特殊的完成支持。单击使用 "dir" 和 "file" .

  • help -- 值旁边显示的字符串(如果支持)。

  • kwargs -- 任意元数据。内置实现不使用它，但是与自定义shell支持搭配使用的自定义类型完成可以使用它。

class click.shell_completion.ShellComplete(cli: click.core.BaseCommand, ctx_args: Dict[str, Any], prog_name: str, complete_var: str)

用于提供外壳完成支持的基类。给定shell的子类将重写属性和方法以实现完成指令 (source 和 complete ）

参数

  • cli -- 正在调用命令。

  • prog_name -- shell中的可执行文件的名称。

  • complete_var -- 保存完成指令的环境变量的名称。

8.0 新版功能.

name: ClassVar[str]

要将外壳注册为的名称 add_completion_class() 。这在完成说明中使用 ({{name}}_source 和 {{name}}_complete ）

source_template: ClassVar[str]

完成脚本模板的格式化方式 source() 。这必须由子类提供。

property func_name: str

由完成脚本定义的shell函数的名称。

source_vars() → Dict[str, Any]

用于格式设置的变量 source_template .

默认情况下，这将提供 complete_func ， complete_var 和 prog_name .

source() → str

生成定义完成函数的shell脚本。默认情况下，这是 % -样式格式 source_template 使用由返回的DICT source_vars() .

get_completion_args() → Tuple[List[str], str]

使用shell脚本定义的env变量返回 args, incomplete 。这必须由子类实现。

get_completions(args: List[str], incomplete: str) → List[click.shell_completion.CompletionItem]

从完整的参数中确定上下文和最后一个完整的命令或参数。调用该对象的 shell_complete 方法来获取不完整值的完备值。

参数

  • args -- 不完整值之前的完整参数列表。

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

format_completion(item: click.shell_completion.CompletionItem) → str

将完成项格式化为shell脚本可识别的表单。这必须由子类实现。

参数

item -- 要格式化的完成项。

complete() → str

生成完成数据以发送回shell。

默认情况下，此调用 get_completion_args() ，获取完成，然后调用 format_completion() 每完成一次。

click.shell_completion.add_completion_class(cls: Type[click.shell_completion.ShellComplete], name: Optional[str] = None) → None

注册A ShellComplete 给定名称下的子类。在完成期间，名称将由完成指令环境变量提供。

参数

  • cls -- 将处理外壳完成的完成类。

  • name -- 要在其下注册类的名称。默认为类的 name 属性。

测试

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保留为独立的流。这对于具有可预测的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 -- 要调用的参数。它可以作为iterable或string给出。当作为字符串给出时，它将被解释为一个unix shell命令。更多细节 shlex.split() .

  • input -- 的输入数据 sys.stdin .

  • env -- 环境将覆盖。

  • catch_exceptions -- 是否捕获除 SystemExit .

  • extra -- 要传递给的关键字参数 main() .

  • color -- 输出是否应包含颜色代码。应用程序仍然可以显式地重写这一点。

在 8.0 版更改: 结果对象具有 return_value 属性设置为从调用的命令返回的值。

Changelog

在 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 使用给定字典中的重写。这还重新显示了Click模拟（如提示功能）中的一些内部内容。

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

参数

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

  • env -- 环境将重写为字典。

  • color -- 输出是否应包含颜色代码。应用程序仍然可以显式地重写这一点。

在 8.0 版更改: stderr 打开时为 errors="backslashreplace" 而不是默认设置 "strict" 。

Changelog

在 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

标准输出为字节。