API

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

装饰器

click.command(name: Callable[[...], Any]) → Command
click.command(name: str | None, cls: Type[CmdType], **attrs: Any) → Callable[[Callable[[...], Any]], CmdType]
click.command(name: None = None, *, cls: Type[CmdType], **attrs: Any) → Callable[[Callable[[...], Any]], CmdType]
click.command(name: str | None = None, cls: None = None, **attrs: Any) → Callable[[Callable[[...], Any]], Command]

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

命令的名称默认为函数的名称，并用破折号替换了虚线。 如果您想更改它，可以将所需的名称作为第一个参数传递。

所有关键字参数都被转发到基础命令类。对于 params 参数，则任何修饰参数都将追加到列表的末尾。

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

参数:

  • name -- 命令的名称。 这默认为函数名称，其中虚线被破折号替换。

  • cls -- 要实例化的命令类。 其默认值为 Command .

在 8.1 版本发生变更: 此修饰符不带括号即可应用。

在 8.1 版本发生变更: 这个 params 可以使用参数。修饰后的参数将附加到列表的末尾。

click.group(name: Callable[[...], Any]) → Group
click.group(name: str | None, cls: Type[GrpType], **attrs: Any) → Callable[[Callable[[...], Any]], GrpType]
click.group(name: None = None, *, cls: Type[GrpType], **attrs: Any) → Callable[[Callable[[...], Any]], GrpType]
click.group(name: str | None = None, cls: None = None, **attrs: Any) → Callable[[Callable[[...], Any]], Group]

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

在 8.1 版本发生变更: 此修饰符不带括号即可应用。

click.argument(*param_decls, cls=None, **attrs)

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

有关默认参数类，请参阅 Argument 和 Parameter 有关参数的说明。

参数:

  • cls (Type[Argument] | None) -- 要实例化的参数类。默认为 Argument .

  • param_decls (str) -- 作为位置参数传递给 cls 。

  • attrs (Any) -- 作为关键字参数传递给 cls 。

返回类型:

Callable[[FC], FC]

click.option(*param_decls, cls=None, **attrs)

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

有关缺省选项类，请参阅 Option 和 Parameter 有关参数的说明。

参数:

  • cls (Type[Option] | None) -- 要实例化的选项类。默认为 Option .

  • param_decls (str) -- 作为位置参数传递给 cls 。

  • attrs (Any) -- 作为关键字参数传递给 cls 。

返回类型:

Callable[[FC], FC]

click.password_option(*param_decls, **kwargs)

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

参数:

  • param_decls (str) -- 一个或多个选项名称。默认为单个值 "--password" .

  • kwargs (Any) -- 将额外的参数传递给 option() .

返回类型:

Callable[[FC], FC]

click.confirmation_option(*param_decls, **kwargs)

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

参数:

  • param_decls (str) -- 一个或多个选项名称。默认为单个值 "--yes" .

  • kwargs (Any) -- 将额外的参数传递给 option() .

返回类型:

Callable[[FC], FC]

click.version_option(version=None, *param_decls, package_name=None, prog_name=None, message=None, **kwargs)

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

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

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

参数:

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

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

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

  • prog_name (str | None) -- 要在消息中显示的CLI的名称。如果未提供，将从命令中检测到。

  • message (str | None) -- 要显示的消息。这些价值 %(prog)s ， %(package)s ，以及 %(version)s 都是有空的。默认为 "%(prog)s, version %(version)s" 。

  • kwargs (Any) -- 将额外的参数传递给 option() .

抛出:

RuntimeError -- version 无法检测到。

返回类型:

Callable[[FC], FC]

Changelog

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

在 8.0 版本发生变更: 使用 importlib.metadata 而不是 pkg_resources 。根据包名称(而不是入口点名称)检测版本。Python包名称必须与安装的包名称匹配，或者与一起传递 package_name= 。

click.help_option(*param_decls, **kwargs)

预配置的装饰器 --help 上面定义的选项。

参数:

  • param_decls (str) -- 一个或多个选项名称。默认为单个值 "--help" .

  • kwargs (Any) -- 将额外的参数传递给 option() .

返回类型:

Callable[[FC], FC]

click.pass_context(f)

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

参数:

f (t.Callable[te.Concatenate[Context, P], R])

返回类型:

t.Callable[P, R]

click.pass_obj(f)

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

参数:

f (t.Callable[te.Concatenate[t.Any, P], R])

返回类型:

t.Callable[P, R]

click.make_pass_decorator(object_type, ensure=False)

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

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

from functools import update_wrapper

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

  • object_type (Type[T]) -- 要传递的对象的类型。

  • ensure (bool) -- 如果设置为 True 如果一个新对象还没有出现，它将在上下文中被创建和记住。

返回类型:

Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]

click.decorators.pass_meta_key(key, *, doc_description=None)

创建一个从传递密钥的装饰器 click.Context.meta 作为修饰函数的第一个参数。

参数:

  • key (str) -- 键入 Context.meta 才能通过。

  • doc_description (str | None) -- 正在传递的对象的描述，插入到修饰者的文档字符串中。默认为“the‘key’key from Conext.meta”。

返回类型:

t.Callable[[t.Callable[te.Concatenate[t.Any, P], R]], t.Callable[P, R]]

Changelog

Added in version 8.0.

公用事业

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

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

与 print() ，这将执行以下操作：

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

  • 在Windows控制台中支持Unicode。

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

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

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

  • 始终刷新输出。

参数:

  • message (Any | None) -- 要输出的字符串或字节。其他对象被转换为字符串。

  • file (IO[Any] | None) -- 要写入的文件。默认为 stdout 。

  • err (bool) -- 写信给 stderr 而不是 stdout 。

  • nl (bool) -- 在消息后打印换行符。默认情况下启用。

  • color (bool | None) -- 强制显示或隐藏颜色和其他样式。默认情况下，如果输出看起来不像交互式终端，单击将删除颜色。

返回类型:

None

Changelog

在 6.0 版本发生变更: 在Windows控制台上支持Unicode输出。单击不会修改 sys.stdout ，所以 sys.stdout.write() 和 print() 仍然不支持Unicode。

在 4.0 版本发生变更: 增加了 color 参数。

Added in version 3.0: 添加了 err 参数。

在 2.0 版本发生变更: 如果安装了Colorama，则支持Windows上的颜色。

click.echo_via_pager(text_or_generator, color=None)

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

Changelog

在 3.0 版本发生变更: 增加了 color 标志符。

参数:

  • text_or_generator (Iterable[str] | Callable[[], Iterable[str]] | str) -- 文本到页面，或者，将文本发送到页面的生成器。

  • color (bool | None) -- 控制页导航是否支持ANSI颜色。默认为自动检测。

返回类型:

None

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

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

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

参数:

  • text (str) -- 为提示显示的文本。

  • default (Any | None) -- 如果没有输入将使用的默认值。如果不提供，它将提示直到中止。

  • hide_input (bool) -- 如果设置为真，则输入值将隐藏。

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

  • type (ParamType | Any | None) -- 用于检查值的类型。

  • value_proc (Callable[[str], Any] | None) -- 如果提供此参数，则调用该函数而不是类型转换来转换值。

  • prompt_suffix (str) -- 应添加到提示中的后缀。

  • show_default (bool) -- 在提示中显示或隐藏默认值。

  • err (bool) -- 如果设置为true，则文件默认为 stderr 而不是 stdout 与Echo相同。

  • show_choices (bool) -- 如果传递的类型是选项，则显示或隐藏选项。例如，如果type是day或week的选项，则show_choices为true，text为“group by”，则提示将为“group by（day，week）：”。

返回类型:

Any

Changelog

Added in version 8.0: confirmation_prompt 可以是自定义字符串。

Added in version 7.0: 添加了 show_choices 参数。

Added in version 6.0: 在Windows上添加了对cmd.exe的Unicode支持。

Added in version 4.0: 增加了 err 参数。

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

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

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

参数:

  • text (str) -- 要问的问题。

  • default (bool | None) -- 未提供输入时使用的默认值。如果 None ，重复执行，直到输入。

  • abort (bool) -- 如果设置为 True 否定的回答通过引发 Abort .

  • prompt_suffix (str) -- 应添加到提示中的后缀。

  • show_default (bool) -- 在提示中显示或隐藏默认值。

  • err (bool) -- 如果设置为true，则文件默认为 stderr 而不是 stdout 与Echo相同。

返回类型:

bool

Changelog

在 8.0 版本发生变更: 如果出现以下情况，则重复此操作，直到提供输入 default 是 None 。

Added in version 4.0: 添加了 err 参数。

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

此函数创建一个可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[V] | None) -- 可重复的iterable。如果没有提供，则需要长度。

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

  • label (str | None) -- 要显示在进度条旁边的标签。

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

  • show_percent (bool | None) -- 启用或禁用百分比显示。默认值为 True 如果iterable有一个长度或 False 如果没有。

  • show_pos (bool) -- 启用或禁用绝对位置显示。默认值为 False .

  • item_show_func (Callable[[V | None], str | None] | None) -- 使用当前项调用的函数，该函数可以返回要在进度条旁边显示的字符串。如果函数返回 None 没有显示任何内容。当前项可以是 None 例如进入和离开酒吧时。

  • fill_char (str) -- 用于显示进度条已填充部分的字符。

  • empty_char (str) -- 用于显示进度条未填充部分的字符。

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

  • info_sep (str) -- 多个信息项（eta等）之间的分隔符。

  • width (int) -- 进度条的宽度（以字符为单位），0表示整个终端宽度。

  • file (TextIO | None) -- 要写入的文件。如果这不是终端，则只打印标签。

  • color (bool | None) -- 控制终端是否支持ANSI颜色。默认为自动检测。只有当进度条输出中的任何地方包含ANSI代码时，才需要这样做，默认情况下不是这样。

  • update_min_steps (int) -- 仅在完成此数量的更新后进行渲染。这允许对非常快的迭代器进行调优。

返回类型:

ProgressBar[V]

Changelog

在 8.0 版本发生变更: 即使执行时间小于0.5秒，也会显示输出。

在 8.0 版本发生变更: item_show_func 显示当前项，而不是上一项。

在 8.0 版本发生变更: 如果输出不是TTY，则回显标签。恢复7.0中删除所有输出的更改。

Added in version 8.0: 增加了 update_min_steps 参数。

在 4.0 版本发生变更: 增加了 color 参数。添加了 update 方法添加到对象。

Added in version 2.0.

click.clear()

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

Changelog

Added in version 2.0.

返回类型:

None

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

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

实例：

click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
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 (Any) -- 要与ANSI代码一起使用的字符串。

  • fg (int | Tuple[int, int, int] | str | None) -- 如果提供，这将成为前景颜色。

  • bg (int | Tuple[int, int, int] | str | None) -- 如果提供，这将成为背景色。

  • bold (bool | None) -- 如果提供，将启用或禁用粗体模式。

  • dim (bool | None) -- 如果提供，将启用或禁用变暗模式。这是很糟糕的支持。

  • underline (bool | None) -- 如果提供，将启用或禁用下划线。

  • overline (bool | None) -- 如果提供，这将启用或禁用上划线。

  • italic (bool | None) -- 如果提供，这将启用或禁用斜体。

  • blink (bool | None) -- 如果提供，这将启用或禁用闪烁。

  • reverse (bool | None) -- 如果提供此选项，将启用或禁用反向渲染（前景变为背景，反之亦然）。

  • strikethrough (bool | None) -- 如果提供，这将启用或禁用穿透文本。

  • reset (bool) -- 默认情况下，重置所有代码都添加在字符串的末尾，这意味着样式不会延续。可以禁用此选项来组合样式。

返回类型:

str

Changelog

在 8.0 版本发生变更: 非字符串 message 转换为字符串。

在 8.0 版本发生变更: 添加了对256和RGB色码的支持。

在 8.0 版本发生变更: 添加了 strikethrough ， italic ，以及 overline 参数。

在 7.0 版本发生变更: 增加了对亮色的支持。

Added in version 2.0.

click.unstyle(text)

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

Changelog

Added in version 2.0.

参数:

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

返回类型:

str

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

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

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

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

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

Changelog

在 8.0 版本发生变更: 非字符串 message 转换为字符串。字节在未应用样式的情况下传递。

Added in version 2.0.

参数:
返回类型:

None

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

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

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

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

参数:

  • text (AnyStr | None) -- 要编辑的文本。

  • editor (str | None) -- 可选择要使用的编辑器。默认为自动检测。

  • env (Mapping[str, str] | None) -- 要转发到编辑器的环境变量。

  • require_save (bool) -- 如果为真，则不在编辑器中保存将使返回值变为 None .

  • extension (str) -- 告诉编辑器的扩展名。默认为 .txt 但是改变这个可能会改变语法突出显示。

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

返回类型:

AnyStr | None

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

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

实例：

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

Added in version 2.0.

参数:

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

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

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

返回类型:

int

click.getchar(echo=False)

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

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

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

Changelog

Added in version 2.0.

参数:

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

返回类型:

str

click.pause(info=None, err=False)

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

Changelog

Added in version 4.0: 增加了 err 参数。

Added in version 2.0.

参数:

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

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

返回类型:

None

click.get_binary_stream(name)

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

参数:

name (te.Literal['stdin', 'stdout', 'stderr']) -- 要打开的流的名称。有效名称是 'stdin' ， 'stdout' 和 'stderr'

返回类型:

BinaryIO

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

返回用于文本处理的系统流。这通常返回围绕从返回的二进制流的包装流 get_binary_stream() 但是它也可以为已经正确配置的流选择快捷方式。

参数:

  • name (te.Literal['stdin', 'stdout', 'stderr']) -- 要打开的流的名称。有效名称是 'stdin' ， 'stdout' 和 'stderr'

  • encoding (str | None) -- 覆盖检测到的默认编码。

  • errors (str | None) -- 覆盖默认错误模式。

返回类型:

TextIO

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

打开一个文件，需要处理额外的行为 '-' 指示标准流、写入时延迟打开和原子写入。类似于 File 参数类型。

如果 '-' 是给打开的 stdout 或 stdin 流被包装，因此在上下文管理器中使用它不会关闭它。这使得可以在不意外关闭标准流的情况下使用该函数：

with open_file(filename) as f:
    ...
参数:

  • filename (str | PathLike[str]) -- 要打开的文件的名称或路径，或 '-' for stdin/stdout .

  • mode (str) -- 打开文件的模式。

  • encoding (str | None) -- 对以文本模式打开的文件进行解码或编码的编码。

  • errors (str | None) -- 错误处理模式。

  • lazy (bool) -- 等待打开该文件，直到它被访问。对于读取模式，文件被临时打开以提前引发访问错误，然后关闭，直到再次读取。

  • atomic (bool) -- 写入临时文件并在关闭时替换给定的文件。

返回类型:

IO[Any]

Changelog

Added in version 3.0.

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

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

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

Mac OS X：

~/Library/Application Support/Foo Bar

Mac OS X（POSIX）：

~/.foo-bar

UNIX：

~/.config/foo-bar

UNIX（POSIX）：

~/.foo-bar

Windows(漫游)：

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

Windows(非漫游)：

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

Changelog

Added in version 2.0.

参数:

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

  • roaming (bool) -- 控制文件夹是否应该在Windows上漫游。否则不会有任何效果。

  • force_posix (bool) -- 如果设置为 True 然后，在任何POSIX系统上，文件夹都将存储在主文件夹中，并带有前导点，而不是xdg config home或darwin的应用程序支持文件夹。

返回类型:

str

click.format_filename(filename, shorten=False)

将文件名格式化为字符串以供显示。通过将名称中的任何无效字节或代理项转义替换为替换字符，确保可以显示文件名 � 。

将无效字节或代理异常写入流时将引发错误 errors="strict" .这通常会发生在 stdout 当地点类似于 en_GB.UTF-8 .

许多场景 are 但是，由于PEP 538和PEP 540，可以安全地写入代理，包括：

  • 写信给 stderr ，它使用 errors="backslashreplace" 。

  • 该系统具有 LANG=C.UTF-8 ， C ，或 POSIX 。Python使用以下命令打开stdout和stderr errors="surrogateescape" 。

  • 没有一个 LANG/LC_* 都准备好了。Python假设 LANG=C.UTF-8 。

  • 在UTF-8模式下启动Python时， PYTHONUTF8=1 或 -X utf8 。Python使用以下命令打开stdout和stderr errors="surrogateescape" 。

参数:

  • filename (str | bytes | PathLike[str] | PathLike[bytes]) -- 为UI显示设置文件名格式。这也会将文件名转换为Unicode而不会失败。

  • shorten (bool) -- 这可以选择将文件名缩短为指向它的路径的条带。

返回类型:

str

命令

class click.BaseCommand(name, context_settings=None)

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

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

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

Changelog

在 2.0 版本发生变更: 添加了 context_settings 参数.

参数:

  • name (str | None) -- 要使用的命令的名称，除非某个组重写了该命令。

  • context_settings (MutableMapping[str, Any] | None) -- 带有传递给上下文对象的默认值的可选字典。

context_class

Context 的别名

allow_extra_args = False

的默认值 Context.allow_extra_args 标志符。

allow_interspersed_args = True

的默认值 Context.allow_interspersed_args 标志符。

ignore_unknown_options = False

的默认值 Context.ignore_unknown_options 标志符。

name

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

context_settings: MutableMapping[str, Any]

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

to_info_dict(ctx)

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

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

参数:

ctx (Context) -- A Context 代表这个命令。

返回类型:

Dict[str, Any]

Changelog

Added in version 8.0.

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

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

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

参数:

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

  • args (List[str]) -- 要解析为字符串列表的参数。

  • parent (Context | None) -- 父上下文（如果可用）。

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

返回类型:

Context

Changelog

在 8.0 版本发生变更: 增加了 context_class 属性。

parse_args(ctx, args)

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

参数:
返回类型:

List[str]

invoke(ctx)

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

参数:

ctx (Context)

返回类型:

Any

shell_complete(ctx, incomplete)

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

任何命令都可以是连锁多命令的一部分，因此兄弟命令在命令完成期间的任何时刻都有效。其他命令类将返回更多完成。

参数:

  • ctx (Context) -- 此命令的调用上下文。

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

返回类型:

List[CompletionItem]

Changelog

Added in version 8.0.

main(args: Sequence[str] | None = None, prog_name: str | None = None, complete_var: str | None = None, standalone_mode: te.Literal[True] = True, **extra: Any) → te.NoReturn
main(args: Sequence[str] | None = None, prog_name: str | None = None, complete_var: str | None = None, standalone_mode: 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 更多信息。

Changelog

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

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

在 3.0 版本发生变更: 添加了 standalone_mode 参数。

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

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

参数:

  • name (str | None) -- 要使用的命令的名称，除非某个组重写了该命令。

  • context_settings (MutableMapping[str, Any]) -- 带有传递给上下文对象的默认值的可选字典。

  • callback (Callable[[...], Any] | None) -- 要调用的回调。这是可选的。

  • params (List[Parameter] | None) -- 要用此命令注册的参数。这可以是 Option 或 Argument 物体。

  • help (str | None) -- 用于此命令的帮助字符串。

  • epilog (str | None) -- 类似于帮助字符串，但它在帮助页的末尾打印。

  • short_help (str | None) -- 用于此命令的简短帮助。这显示在父命令的命令列表中。

  • add_help_option (bool) -- 默认情况下，每个命令注册一个 --help 选择权。此参数可以禁用此功能。

  • no_args_is_help (bool) -- 这控制在没有提供参数时发生的情况。默认情况下，此选项处于禁用状态。如果启用，这将添加 --help 如果未传递任何参数，则作为参数

  • hidden (bool) -- 从帮助输出中隐藏此命令。

  • deprecated (bool) -- 发出一条消息，指示命令已被弃用。

  • options_metavar (str | None)

在 8.1 版本发生变更: help ， epilog ，以及 short_help 在未经处理的情况下存储，则所有格式化都是在输出帮助文本时完成的，而不是在初始化时完成的，即使不使用 @command 装饰师。

Changelog

在 8.0 版本发生变更: 添加了一个 repr 显示命令名称。

在 7.1 版本发生变更: 添加了 no_args_is_help 参数。

在 2.0 版本发生变更: 添加了 context_settings 参数。

callback

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

params: t.List[Parameter]

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

to_info_dict(ctx)

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

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

参数:

ctx (Context) -- A Context 代表这个命令。

返回类型:

Dict[str, Any]

Changelog

Added in version 8.0.

get_usage(ctx)

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

调用 format_usage() 内部的。

参数:

ctx (Context)

返回类型:

str

format_usage(ctx, formatter)

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

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

参数:
返回类型:

None

collect_usage_pieces(ctx)

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

参数:

ctx (Context)

返回类型:

List[str]

get_help_option_names(ctx)

返回帮助选项的名称。

参数:

ctx (Context)

返回类型:

List[str]

get_help_option(ctx)

返回帮助选项对象。

除非 add_help_option 是 False .

在 8.1.8 版本发生变更: 帮助选项现在已被缓存，以避免多次创建。

参数:

ctx (Context)

返回类型:

Option | None

make_parser(ctx)

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

参数:

ctx (Context)

返回类型:

OptionParser

get_help(ctx)

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

调用 format_help() 内部的。

参数:

ctx (Context)

返回类型:

str

get_short_help_str(limit=45)

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

参数:

limit (int)

返回类型:

str

format_help(ctx, formatter)

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

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

这将调用以下方法：

参数:
返回类型:

None

format_help_text(ctx, formatter)

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

参数:
返回类型:

None

format_options(ctx, formatter)

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

参数:
返回类型:

None

format_epilog(ctx, formatter)

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

参数:
返回类型:

None

parse_args(ctx, args)

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

参数:
返回类型:

List[str]

invoke(ctx)

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

参数:

ctx (Context)

返回类型:

Any

shell_complete(ctx, incomplete)

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

参数:

  • ctx (Context) -- 此命令的调用上下文。

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

返回类型:

List[CompletionItem]

Changelog

Added in version 8.0.

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

多命令是调度到子命令的命令的基本实现。 最常见的版本是 Group .

参数:

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

  • no_args_is_help (bool | None) -- 这控制了如果不提供参数会发生什么。 如果出现以下情况，默认情况下会启用此选项 invoke_without_command 已禁用或禁用（如果已启用）。 如果启用，将添加 --help 如果没有参数被传递，则作为参数。

  • subcommand_metavar (str | None) -- 文档中用于指示子命令位置的字符串。

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

  • result_callback (Callable[[...], Any] | None) -- 要附加到此多命令的结果回调。稍后可以使用 result_callback() 装饰师。

  • attrs (Any) -- 中描述的其他命令参数 Command .

  • name (str | None)

allow_extra_args = True

的默认值 Context.allow_extra_args 标志符。

allow_interspersed_args = False

的默认值 Context.allow_interspersed_args 标志符。

to_info_dict(ctx)

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

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

参数:

ctx (Context) -- A Context 代表这个命令。

返回类型:

Dict[str, Any]

Changelog

Added in version 8.0.

collect_usage_pieces(ctx)

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

参数:

ctx (Context)

返回类型:

List[str]

format_options(ctx, formatter)

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

参数:
返回类型:

None

result_callback(replace=False)

将结果回调添加到命令。默认情况下，如果已经注册了结果回调，这将链接它们，但可以使用 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 (bool) -- 如果设置为 True 将删除已存在的结果回调。

返回类型:

Callable[[F], F]

Changelog

在 8.0 版本发生变更: 重命名自 resultcallback 。

Added in version 3.0.

format_commands(ctx, formatter)

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

参数:
返回类型:

None

parse_args(ctx, args)

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

参数:
返回类型:

List[str]

invoke(ctx)

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

参数:

ctx (Context)

返回类型:

Any

get_command(ctx, cmd_name)

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

参数:
返回类型:

Command | None

list_commands(ctx)

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

参数:

ctx (Context)

返回类型:

List[str]

shell_complete(ctx, incomplete)

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

参数:

  • ctx (Context) -- 此命令的调用上下文。

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

返回类型:

List[CompletionItem]

Changelog

Added in version 8.0.

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

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

参数:
Changelog

在 8.0 版本发生变更: 这个 commands 参数可以是命令对象的列表。

command_class: Type[Command] | None = None

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

Changelog

Added in version 8.0.

group_class: Type[Group] | Type[type] | None = None

如果设置，则该组的 group() 默认设置为装饰器 Group 班级。这对于使所有子组使用自定义组类非常有用。

如果设置为特殊值，则 type (字面意思是 group_class = type )，则此组的类将用作默认类。这使得自定义组类继续生成自定义组。

Changelog

Added in version 8.0.

commands: t.MutableMapping[str, Command]

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

add_command(cmd, name=None)

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

参数:
返回类型:

None

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

用于声明命令并将命令附加到组的快捷装饰器。这采用了与以下内容相同的参数 command() 并立即将创建的命令注册到该组，方法是调用 add_command() .

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

在 8.1 版本发生变更: 此修饰符不带括号即可应用。

Changelog

在 8.0 版本发生变更: 增加了 command_class 属性。

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

用于声明组并将其附加到组的快捷装饰器。这采用了与以下内容相同的参数 group() 并立即将创建的组注册到该组，方法是调用 add_command() .

若要自定义使用的组类，请将 group_class 属性。

在 8.1 版本发生变更: 此修饰符不带括号即可应用。

Changelog

在 8.0 版本发生变更: 增加了 group_class 属性。

get_command(ctx, cmd_name)

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

参数:
返回类型:

Command | None

list_commands(ctx)

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

参数:

ctx (Context)

返回类型:

List[str]

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

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

看到 MultiCommand 和 Command 的描述 name 和 attrs .

参数:
sources: t.List[MultiCommand]

已注册的多命令列表。

add_source(multi_cmd)

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

参数:

multi_cmd (MultiCommand)

返回类型:

None

get_command(ctx, cmd_name)

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

参数:
返回类型:

Command | None

list_commands(ctx)

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

参数:

ctx (Context)

返回类型:

List[str]

参数

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

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

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

参数:

  • param_decls (Sequence[str] | None) -- 此选项或参数的参数声明。这是标记或参数名称的列表。

  • type (ParamType | Any | None) -- 应该使用的类型。要么是A ParamType 或者是一种 Python 类型。如果支持，则会自动将后者转换为前者。

  • required (bool) -- 控制是否可选。

  • default (Any | Callable[[], Any] | None) -- 如果省略，则为默认值。这也可以是可调用的，在这种情况下，当需要不带任何参数的默认值时调用它。

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

  • nargs (int | None) -- 要匹配的参数数。如果没有 1 返回值是一个元组，而不是单个值。nargs的默认值是 1 (除非类型是元组，那么它就是元组的数量)。如果 nargs=-1 ，则收集所有剩余的参数。

  • metavar (str | None) -- 值在帮助页中的表示方式。

  • expose_value (bool) -- 如果这是 True 然后将该值传递给命令回调并存储在上下文中，否则将跳过该值。

  • is_eager (bool) -- 在处理非渴望值之前，先处理渴望值。这不应该为参数设置，否则它将反转处理顺序。

  • envvar (Sequence[str] | str | None) -- 应检查的环境变量字符串或字符串列表。

  • shell_complete (Callable[[Context, Parameter, str], List[CompletionItem] | List[str]] | None) -- 返回自定义Shell完成的函数。如果给定，则用来代替参数的类型完成。拿走 ctx, param, incomplete ，并且必须返回 CompletionItem 或字符串列表。

  • multiple (bool)

Changelog

在 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 版本发生变更: 已将参数回调的签名更改为也传递给该参数。旧的回调格式仍然有效，但它会发出警告，让您有机会更轻松地迁移代码。

to_info_dict()

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

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

Changelog

Added in version 8.0.

返回类型:

Dict[str, Any]

property human_readable_name: str

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

get_default(ctx: Context, call: te.Literal[True] = True) → Any | None
get_default(ctx: Context, call: bool = True) → Any | Callable[[], Any] | None

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

参数:

  • ctx -- 当前上下文。

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

Changelog

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

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

在 8.0 版本发生变更: 看着 ctx.default_map 第一。

在 8.0 版本发生变更: 增加了 call 参数。

type_cast_value(ctx, value)

根据选项的转换和验证值 type ， multiple ，以及 nargs 。

参数:
返回类型:

Any

get_error_hint(ctx)

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

参数:

ctx (Context)

返回类型:

str

shell_complete(ctx, incomplete)

返回不完整值的完成列表。如果一个 shell_complete 函数是在初始化过程中给出的，正在使用。否则， type shell_complete() 函数被使用。

参数:

  • ctx (Context) -- 此命令的调用上下文。

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

返回类型:

List[CompletionItem]

Changelog

Added in version 8.0.

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

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

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

参数:

  • show_default (bool | str | None) -- 在其帮助文本中显示此选项的默认值。默认情况下，值不会显示，除非 Context.show_default 是 True 。如果该值是一个字符串，它将在括号中显示该字符串，而不是实际值。这对于动态选项特别有用。对于单选项布尔标志，如果其值为 False 。

  • show_envvar (bool) -- 控制是否应在帮助页上显示环境变量。通常，不会显示环境变量。

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

  • confirmation_prompt (bool | str) -- 如果提示输入，则再次提示以确认值。可以设置为字符串，而不是 True 若要自定义消息，请执行以下操作。

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

  • hide_input (bool) -- 如果这是 True 则提示上的输入将对用户隐藏。这对于密码输入很有用。

  • is_flag (bool | None) -- 强制此选项作为标志。默认为自动检测。

  • flag_value (Any | None) -- 如果启用了该标志，则应使用哪个值。如果选项字符串包含用于标记两个选项的斜线，则自动将其设置为布尔值。

  • multiple (bool) -- 如果设置为 True 然后多次接受并记录参数。这和 nargs 但支持任意数量的参数。

  • count (bool) -- 此标志使选项递增为整数。

  • allow_from_autoenv (bool) -- 如果启用了此选项，则在上下文中定义前缀的情况下，此参数的值将从环境变量中提取。

  • help (str | None) -- 帮助字符串。

  • hidden (bool) -- 从帮助输出中隐藏此选项。

  • attrs (Any) -- 中介绍的其他命令参数 Parameter 。

  • param_decls (Sequence[str] | None)

  • type (ParamType | Any | None)

  • show_choices (bool)

在 8.1.0 版本发生变更: 帮助文本缩进在此处被清除，而不是仅在 @option 装饰师。

在 8.1.0 版本发生变更: 这个 show_default 参数覆盖 Context.show_default 。

在 8.1.0 版本发生变更: 如果缺省值为，则不显示单个选项布尔标志的缺省值 False 。

Changelog

在 8.0.1 版本发生变更: type 是从以下位置检测到的 flag_value 如果给的话。

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

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

所有参数都向前传递给 Parameter 。

参数:

语境

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

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

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

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

参数:

  • command (Command) -- 此上下文的命令类。

  • parent (Context | None) -- 父上下文。

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

  • obj (Any | None) -- 用户数据的任意对象。

  • auto_envvar_prefix (str | None) -- 用于自动环境变量的前缀。如果这是 None 然后禁用从环境变量读取。这不会影响手动设置始终读取的环境变量。

  • default_map (MutableMapping[str, Any] | None) -- 带有参数默认值的字典（类似对象）。

  • terminal_width (int | None) -- 终端的宽度。默认值是从父上下文继承。如果没有上下文定义终端宽度，则将应用自动检测。

  • max_content_width (int | None) -- 通过Click呈现的内容的最大宽度（这当前只影响帮助页）。如果不重写，则默认为80个字符。换句话说：即使终端大于此，默认情况下，Click也不会格式化超过80个字符的内容。除此之外，格式化程序可能会在右侧添加一些安全映射。

  • resilient_parsing (bool) -- 如果启用此标志，则Click“将解析”，而不进行任何交互或回调调用。默认值也将被忽略。这对于实现诸如完成支持之类的事情很有用。

  • allow_extra_args (bool | None) -- 如果设置为 True 然后，末尾的额外参数不会引发错误，并将保留在上下文中。默认值是从命令继承。

  • allow_interspersed_args (bool | None) -- 如果设置为 False 那么选项和参数不能混合。默认值是从命令继承。

  • ignore_unknown_options (bool | None) -- 指示Click忽略它不知道的选项，并将其保留以供以后处理。

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

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

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

  • show_default (bool | None) -- 显示命令的默认值。如果未设置此值，则默认为父上下文中的值。 Command.show_default 覆盖特定命令的此默认值。

在 8.1 版本发生变更: 这个 show_default 参数被重写为 Command.show_default ，而不是反过来。

Changelog

在 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 参数。

formatter_class

HelpFormatter 的别名

parent

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

command

这个 Command 对于这个上下文。

info_name

描述性信息名称

params: Dict[str, Any]

将参数名称映射到它们解析的值。参数使用 expose_value=False 没有存储。

args: List[str]

剩下的参数。

protected_args: List[str]

受保护的论点。 这些都是预先设定的论点 args 当遇到某些解析场景但绝不能传播到另一个参数时。 这用于实现嵌套解析。

obj: Any

存储的用户对象。

invoked_subcommand: str | None

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

如果启用了链接，则会将其设置为 '*' 以防执行任何命令。然而，无法计算出是哪几个。如果需要此知识，则应使用 result_callback() 。

terminal_width: int | None

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

max_content_width: int | None

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

allow_extra_args

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

Changelog

Added in version 3.0.

allow_interspersed_args: bool

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

Changelog

Added in version 3.0.

ignore_unknown_options: bool

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

Changelog

Added in version 4.0.

help_option_names: List[str]

帮助选项的名称。

token_normalize_func: Callable[[str], str] | None

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

resilient_parsing: bool

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

color: bool | None

控制是否需要样式输出。

show_default: bool | None

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

to_info_dict()

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

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

Added in version 8.0.

返回类型:

Dict[str, Any]

scope(cleanup=True)

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

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

示例用法：

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

这相当于：

with ctx:
    assert get_current_context() is ctx
Changelog

Added in version 5.0.

参数:

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

返回类型:

Iterator[Context]

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

Added in version 5.0.

make_formatter()

创建 HelpFormatter 有关帮助和用法输出的信息。

若要在不重写此方法的情况下快速自定义使用的格式化程序类，请将 formatter_class 属性。

Changelog

在 8.0 版本发生变更: 增加了 formatter_class 属性。

返回类型:

HelpFormatter

with_resource(context_manager)

注册资源，就像在 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 (ContextManager[V, bool | None]) -- 要进入的上下文管理器。

返回:

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

返回类型:

V

Changelog

Added in version 8.0.

call_on_close(f)

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

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

参数:

f (Callable[[...], Any]) -- 要在tearDown上执行的函数。

返回类型:

Callable[[...], Any]

close()

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

返回类型:

None

property command_path: str

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

find_root()

查找最外部的上下文。

返回类型:

Context

find_object(object_type)

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

参数:

object_type (Type[V])

返回类型:

V | None

ensure_object(object_type)

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

参数:

object_type (Type[V])

返回类型:

V

lookup_default(name: str, call: te.Literal[True] = True) → Any | None
lookup_default(name: str, call: te.Literal[False] = True) → Any | Callable[[], Any] | None

从获取参数的默认值 default_map .

参数:

  • name -- 参数的名称。

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

Changelog

在 8.0 版本发生变更: 增加了 call 参数。

fail(message)

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

参数:

message (str) -- 要失败的错误消息。

返回类型:

te.NoReturn

abort()

中止脚本。

返回类型:

te.NoReturn

exit(code=0)

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

参数:

code (int)

返回类型:

te.NoReturn

get_usage()

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

返回类型:

str

get_help()

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

返回类型:

str

invoke(__callback: Callable[[...], V], *args: Any, **kwargs: Any) → V
invoke(__callback: Command, *args: Any, **kwargs: Any) → Any

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

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

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

请注意，在Click 3.2之前，关键字参数没有按照此代码的意图正确填写，并且没有创建上下文。 有关此更改以及为什么在错误修复版本中进行更改的更多信息，请参阅 upgrade-to-3.2 .

Changelog

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

forward(_Context__cmd, *args, **kwargs)

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

Changelog

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

参数:
返回类型:

Any

set_parameter_source(name, source)

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

参数:
返回类型:

None

get_parameter_source(name)

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

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

参数:

name (str) -- 参数的名称。

返回类型:

ParameterSource

Changelog

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

click.get_current_context(silent: te.Literal[False] = False) → Context
click.get_current_context(silent: bool = False) → t.Optional['Context']

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

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

Changelog

Added in version 5.0.

参数:

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

class click.core.ParameterSource(*values)

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

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

Changelog

在 8.0 版本发生变更: 使用 Enum 并丢弃 validate 方法。

在 8.0 版本发生变更: 增加了 PROMPT 价值。

COMMANDLINE = 1

该值由命令行参数提供。

ENVIRONMENT = 2

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

DEFAULT = 3

使用参数指定的默认值。

DEFAULT_MAP = 4

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

PROMPT = 5

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

类型

click.STRING = STRING
参数:
返回类型:

Any

click.INT = INT
参数:
返回类型:

Any

click.FLOAT = FLOAT
参数:
返回类型:

Any

click.BOOL = BOOL
参数:
返回类型:

Any

click.UUID = UUID
参数:
返回类型:

Any

click.UNPROCESSED = UNPROCESSED
参数:
返回类型:

Any

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

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

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

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

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

文件也可以原子打开，在这种情况下，所有写入都会进入同一文件夹中的单独文件，完成后，文件将被移动到原始位置。 如果其他用户定期读取的文件被修改，这很有用。

见 文件参数 更多信息。

Changelog

在 2.0 版本发生变更: 添加了 atomic 参数.

参数:

  • mode (str)

  • encoding (str | None)

  • errors (str | None)

  • lazy (bool | None)

  • atomic (bool)

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

这个 Path 类型类似于 File 类型，但返回文件名，而不是打开的文件。可以启用各种检查来验证文件类型和权限。

参数:

  • exists (bool) -- 要使该值有效，文件或目录必须存在。如果未将其设置为 True ，并且该文件不存在，则会以静默方式跳过所有进一步检查。

  • file_okay (bool) -- 允许将文件作为值。

  • dir_okay (bool) -- 允许将目录作为值。

  • readable (bool) -- 如果为真，则执行可读检查。

  • writable (bool) -- 如果为真，则执行可写检查。

  • executable (bool) -- 如果为True，则执行可执行检查。

  • resolve_path (bool) -- 将该值设为绝对值并解析所有符号链接。一个 ~ 不会展开，因为这应该只由Shell程序来完成。

  • allow_dash (bool) -- 允许使用单个破折号作为值，这表示标准流(但不会打开它)。使用 open_file() 来处理打开此值的操作。

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

在 8.1 版本发生变更: 添加了 executable 参数。

Changelog

在 8.0 版本发生变更: 允许通过 path_type=pathlib.Path 。

在 6.0 版本发生变更: 添加了 allow_dash 参数。

class click.Choice(choices, case_sensitive=True)

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

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

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

见 选择 举个例子。

参数:

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

  • choices (Sequence[str])

name: str = 'choice'

此类型的描述性名称

to_info_dict()

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

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

Changelog

Added in version 8.0.

返回类型:

Dict[str, Any]

get_metavar(param)

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

参数:

param (Parameter)

返回类型:

str

get_missing_message(param)

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

Changelog

Added in version 2.0.

参数:

param (Parameter)

返回类型:

str

convert(value, param, ctx)

将值转换为正确的类型。如果值为 None （缺少的值）。

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

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

如果该值无法转换，则调用 fail() 带有描述性信息。

参数:

  • value (Any) -- 要转换的值。

  • param (Parameter | None) -- 使用此类型转换其值的参数。可能是 None .

  • ctx (Context | None) -- 达到此值的当前上下文。可能是 None .

返回类型:

Any

shell_complete(ctx, param, incomplete)

以不完整值开始的完整选择。

参数:

  • ctx (Context) -- 此命令的调用上下文。

  • param (Parameter) -- 请求完成的参数。

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

返回类型:

List[CompletionItem]

Changelog

Added in version 8.0.

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

限制 click.INT 值设置为可接受的值范围。看见 Int和Float范围 .

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

如果 clamp 启用时，范围外的值将被钳制到边界，而不是失败。

Changelog

在 8.0 版本发生变更: 增加了 min_open 和 max_open 参数。

参数:
class click.FloatRange(min=None, max=None, min_open=False, max_open=False, clamp=False)

限制为 click.FLOAT 值设置为可接受的值范围。看见 Int和Float范围 .

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

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

Changelog

在 8.0 版本发生变更: 增加了 min_open 和 max_open 参数。

参数:
class click.DateTime(formats=None)

DateTime类型将日期字符串转换为 datetime 物体。

选中的格式字符串是可配置的，但默认为一些常见的(不支持时区的)ISO 8601格式。

当指定 DateTime 格式，则应仅传递列表或元组。其他可迭代的，如生成器，可能会产生令人惊讶的结果。

使用以下命令处理格式字符串 datetime.strptime ，因此这定义了允许的格式字符串。

按顺序使用每种格式尝试解析，并使用解析成功的第一个格式。

参数:

formats (Sequence[str] | None) -- 日期格式字符串的列表或元组，按应尝试的顺序排列。默认为 '%Y-%m-%d' ， '%Y-%m-%dT%H:%M:%S' ， '%Y-%m-%d %H:%M:%S' 。

class click.Tuple(types)

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

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

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

参数:

types (Sequence[Type[Any] | ParamType]) -- 应用于元组项的类型列表。

class click.ParamType

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

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

  • 这个 name 必须设置类属性。

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

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

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

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

name: str

此类型的描述性名称

envvar_list_splitter: ClassVar[str | None] = None

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

to_info_dict()

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

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

Changelog

Added in version 8.0.

返回类型:

Dict[str, Any]

get_metavar(param)

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

参数:

param (Parameter)

返回类型:

str | None

get_missing_message(param)

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

Changelog

Added in version 2.0.

参数:

param (Parameter)

返回类型:

str | None

convert(value, param, ctx)

将值转换为正确的类型。如果值为 None （缺少的值）。

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

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

如果该值无法转换，则调用 fail() 带有描述性信息。

参数:

  • value (Any) -- 要转换的值。

  • param (Parameter | None) -- 使用此类型转换其值的参数。可能是 None .

  • ctx (Context | None) -- 达到此值的当前上下文。可能是 None .

返回类型:

Any

split_envvar_value(rv)

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

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

参数:

rv (str)

返回类型:

Sequence[str]

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

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

参数:
返回类型:

t.NoReturn

shell_complete(ctx, param, incomplete)

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

参数:

  • ctx (Context) -- 此命令的调用上下文。

  • param (Parameter) -- 请求完成的参数。

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

返回类型:

List[CompletionItem]

Changelog

Added in version 8.0.

例外情况

exception click.ClickException(message)

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

参数:

message (str)

返回类型:

None

exception click.Abort

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

exception click.UsageError(message, ctx=None)

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

参数:

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

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

返回类型:

None

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

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

Changelog

Added in version 2.0.

参数:

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

  • param_hint (str | None) -- 显示为参数名的字符串。这可以作为替代 param 在应该进行自定义验证的情况下。如果它是一个这样使用的字符串，如果它是一个列表，那么每个项目都被引用并分隔开。

  • message (str)

  • ctx (Context | None)

返回类型:

None

exception click.FileError(filename, hint=None)

无法打开文件时引发。

参数:

  • filename (str)

  • hint (str | None)

返回类型:

None

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

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

Changelog

Added in version 4.0.

参数:
返回类型:

None

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

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

Changelog

Added in version 4.0.

参数:

  • option_name (str) -- 不正确使用的选项的名称。

  • message (str)

  • ctx (Context | None)

返回类型:

None

exception click.BadArgumentUsage(message, ctx=None)

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

Changelog

Added in version 6.0.

参数:
返回类型:

None

格式化

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

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

目前，它总是写入内存。

参数:

  • indent_increment (int) -- 每个级别的额外增量。

  • width (int | None) -- 文本的宽度。默认情况下，终端宽度最大为78。

  • max_width (int | None)

write(string)

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

参数:

string (str)

返回类型:

None

indent()

增加缩进量。

返回类型:

None

dedent()

减小缩进。

返回类型:

None

write_usage(prog, args='', prefix=None)

将使用行写入缓冲区。

参数:

  • prog (str) -- 程序名。

  • args (str) -- 用空格分隔的参数列表。

  • prefix (str | None) -- 第一行的前缀。默认为 "Usage: " 。

返回类型:

None

write_heading(heading)

将标题写入缓冲区。

参数:

heading (str)

返回类型:

None

write_paragraph()

将段落写入缓冲区。

返回类型:

None

write_text(text)

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

参数:

text (str)

返回类型:

None

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

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

参数:

  • rows (Sequence[Tuple[str, str]]) -- 术语和值的两个项元组的列表。

  • col_max (int) -- 第一列的最大宽度。

  • col_spacing (int) -- 第一列和第二列之间的空格数。

返回类型:

None

section(name)

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

参数:

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

返回类型:

Iterator[None]

indentation()

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

返回类型:

Iterator[None]

getvalue()

返回缓冲区内容。

返回类型:

str

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

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

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

参数:

  • text (str) -- 应该重写的文本。

  • width (int) -- 文本的最大宽度。

  • initial_indent (str) -- 应作为字符串放在第一行上的初始缩进。

  • subsequent_indent (str) -- 应该放在每个连续行上的缩进字符串。

  • preserve_paragraphs (bool) -- 如果设置了此标志，包装将智能地处理段落。

返回类型:

str

句法分析

class click.OptionParser(ctx=None)

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

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

参数:

ctx (Context | None) -- 任选地所述 Context 这个解析器应该使用的位置。

ctx

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

allow_interspersed_args: bool

这控制解析器如何处理散布的参数。如果值是 False ，解析器将在第一个非选项时停止。 Click使用此功能来安全地实现嵌套子命令。

ignore_unknown_options: bool

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

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

添加名为的新选项 dest 到解析器。 目的地不会被推断（与optparse不同），并且需要显式提供。 行动可以是任何 store , store_const , append , append_const 或 count .

的 obj 可用于识别解析器返回的顺序列表中的选项。

参数:
返回类型:

None

add_argument(obj, dest, nargs=1)

添加一个名为 dest 到解析器。

的 obj 可用于识别解析器返回的顺序列表中的选项。

参数:

  • obj (CoreArgument)

  • dest (str | None)

  • nargs (int)

返回类型:

None

parse_args(args)

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

参数:

args (List[str])

返回类型:

Tuple[Dict[str, Any], List[str], List[CoreParameter]]

Shell完成

见 壳牌完工 有关启用和自定义Click的shell完成系统的信息。

class click.shell_completion.CompletionItem(value, type='plain', help=None, **kwargs)

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

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

参数:

  • value (Any) -- 竣工建议书。

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

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

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

class click.shell_completion.ShellComplete(cli, ctx_args, prog_name, complete_var)

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

参数:

  • cli (BaseCommand) -- 正在调用命令。

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

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

  • ctx_args (MutableMapping[str, Any])

Changelog

Added in version 8.0.

name: ClassVar[str]

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

source_template: ClassVar[str]

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

property func_name: str

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

source_vars()

用于格式设置的变量 source_template .

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

返回类型:

Dict[str, Any]

source()

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

返回类型:

str

get_completion_args()

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

返回类型:

Tuple[List[str], str]

get_completions(args, incomplete)

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

参数:

  • args (List[str]) -- 不完整值之前的完整参数列表。

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

返回类型:

List[CompletionItem]

format_completion(item)

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

参数:

item (CompletionItem) -- 要格式化的完成项。

返回类型:

str

complete()

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

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

返回类型:

str

click.shell_completion.add_completion_class(cls, name=None)

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

参数:

  • cls (ShellCompleteType) -- 将处理Shell完成的完成类。

  • name (str | None) -- 要在其下注册类的名称。默认为类的 name 属性。

返回类型:

ShellCompleteType

测试

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

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

参数:

  • charset (str) -- 输入和输出数据的字符集。

  • env (Mapping[str, str | None] | None) -- 一种具有用于重写的环境变量的字典。

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

  • mix_stderr (bool) -- 如果设置为 False ，则stdout和stderr保留为独立的流。这对于具有可预测的stdout和嘈杂的stderr的Unix哲学应用程序很有用，这样每个应用程序都可以独立测量。

get_default_prog_name(cli)

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

参数:

cli (BaseCommand)

返回类型:

str

make_env(overrides=None)

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

参数:

overrides (Mapping[str, str | None] | None)

返回类型:

Mapping[str, str | None]

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

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

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

参数:

  • input (str | bytes | IO[Any] | None) -- 要放入sys.stdin的输入流。

  • env (Mapping[str, str | None] | None) -- 环境将重写为字典。

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

返回类型:

Iterator[Tuple[BytesIO, BytesIO | None]]

Changelog

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

在 4.0 版本发生变更: 增加了 color 参数。

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

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

返回一个 Result 对象。

参数:

  • cli (BaseCommand) -- 要调用的命令

  • args (Sequence[str] | str | None) -- 要调用的参数。它可以作为iterable或string给出。当作为字符串给出时，它将被解释为一个unix shell命令。更多细节 shlex.split() .

  • input (str | bytes | IO[Any] | None) -- 的输入数据 sys.stdin .

  • env (Mapping[str, str | None] | None) -- 环境将覆盖。

  • catch_exceptions (bool) -- 是否捕获除 SystemExit .

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

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

返回类型:

Result

Changelog

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

在 4.0 版本发生变更: 增加了 color 参数。

在 3.0 版本发生变更: 增加了 catch_exceptions 参数。

在 3.0 版本发生变更: 结果对象具有 exc_info 如果可用，则具有回溯的属性。

isolated_filesystem(temp_dir=None)

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

参数:

temp_dir (str | PathLike[str] | None) -- 在此目录下创建临时目录。如果给定，则退出时不会删除创建的目录。

返回类型:

Iterator[str]

Changelog

在 8.0 版本发生变更: 添加了 temp_dir 参数。

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

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

参数:
runner

创建结果的运行者

stdout_bytes

标准输出为字节。

stderr_bytes

标准错误(以字节为单位)，如果不可用，则为NONE

return_value

从调用的命令返回的值。

Changelog

Added in version 8.0.

exit_code

退出代码为整数。

exception

如果有例外的话会发生。

exc_info

追溯

property output: str

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

property stdout: str

标准输出为Unicode字符串。

property stderr: str

标准错误为Unicode字符串。