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] ¶
- 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.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的应用程序支持文件夹。
命令¶
- 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
- 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
属性。
- 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 -- 要调用的回调。这是可选的。
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_usage(ctx: click.core.Context) str ¶
将用法行格式化为字符串并返回。
调用
format_usage()
内部的。
- invoke(ctx: click.core.Context) Any ¶
给定一个上下文,这将以正确的方式调用附加的回调(如果它存在的话)。
- make_parser(ctx: click.core.Context) click.parser.OptionParser ¶
为此命令创建基础选项分析器。
- 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 ¶
获取参数的字符串化版本,以便在错误消息中使用,以指示哪个参数导致了错误。
- 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.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 新版功能.
- call_on_close(f: Callable[[...], Any]) Callable[[...], Any] ¶
注册一个要在上下文中断时调用的函数。
这可用于关闭脚本执行期间打开的资源。支持Python的上下文管理器协议的资源,该协议将在
with
语句应注册到with_resource()
相反。- 参数
f -- 要在tearDown上执行的函数。
- close() None ¶
调用向注册的所有关闭回调
call_on_close()
,并退出使用输入的所有上下文管理器with_resource()
.
- ensure_object(object_type: Type[click.core.V]) click.core.V ¶
喜欢
find_object()
但将最内部的对象设置为 object_type 如果它不存在。
- 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_parameter_source(name: str) Optional[click.core.ParameterSource] ¶
获取参数的源。这表示从中获取参数值的位置。
这对于确定用户何时在命令行上指定了与默认值相同的值非常有用。它将会是
DEFAULT
仅当该值实际上取自默认值时。- 参数
name -- 参数的名称。
- 返回类型
在 8.0 版更改: 返回
None
如果参数不是从任何来源提供的。
- ignore_unknown_options: bool¶
指示Click忽略命令不理解的选项,并将其存储在上下文中以供以后处理。这对于您希望调用外部程序的情况非常有用。一般来说,这种模式是强烈不鼓励的,因为它不可能无损地转发所有参数。
Changelog
4.0 新版功能.
- info_name¶
描述性信息名称
- invoke(_Context__callback: Union[click.core.Command, Callable[[...], Any]], *args: Any, **kwargs: Any) Any ¶
按预期的方式调用命令回调。有两种方法可以调用此方法:
第一个参数可以是回调,所有其他参数和关键字参数都可以直接转发给函数。
第一个参数是click命令对象。在这种情况下,所有参数都会被转发,但正确的Click参数(选项和Click参数)必须是关键字参数,Click将填充默认值。
请注意,在click 3.2之前,关键字参数没有按照此代码的意图正确填写,并且没有创建上下文。有关此更改以及在错误修复版本中进行更改的原因的详细信息,请参阅 升级到3.2 .
- 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
属性。
- 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¶
存储的用户对象。
- parent¶
父上下文或 None 如果不存在。
- 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 ¶
设置参数的来源。这表示从中获取参数值的位置。
- 参数
name -- 参数的名称。
source -- 成员
ParameterSource
.
- to_info_dict() Dict[str, Any] ¶
收集可能对生成面向用户的文档的工具有用的信息。这将遍历整个CLI结构。
with Context(cli) as ctx: info = ctx.to_info_dict()
8.0 新版功能.
- 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方法失败,返回无效的值消息。
- 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.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.NoSuchOption(option_name: str, message: Optional[str] = None, possibilities: Optional[Sequence[str]] = None, ctx: Optional[Context] = None)¶
在Click尝试处理不存在的选项时引发。
Changelog
4.0 新版功能.
格式化¶
- class click.HelpFormatter(indent_increment: int = 2, width: Optional[int] = None, max_width: Optional[int] = None)¶
此类有助于格式化基于文本的帮助页。它通常只需要用于非常特殊的内部案例,但它也被公开,这样开发人员就可以编写自己的奇特输出。
目前,它总是写入内存。
- 参数
indent_increment -- 每个级别的额外增量。
width -- 文本的宽度。默认情况下,终端宽度最大为78。
- 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“使用此项”可以安全地实现嵌套的子命令。
- ignore_unknown_options¶
这将告诉解析器如何处理未知选项。默认情况下,它将出错(这是合理的),但还有第二种模式,在这种模式下,它将忽略它,并在将所有未知选项转移到结果参数后继续处理。
外壳完成¶
见 殻が完成する. 有关启用和自定义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_vars() Dict[str, Any] ¶
用于格式设置的变量
source_template
.默认情况下,这将提供
complete_func
,complete_var
和prog_name
.
- source() str ¶
生成定义完成函数的shell脚本。默认情况下,这是
%
-样式格式source_template
使用由返回的DICTsource_vars()
.
- 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哲学应用程序很有用,这样每个应用程序都可以独立测量。
- 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
参数。
- 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¶
退出代码为整数。
- return_value¶
从调用的命令返回的值。
8.0 新版功能.
- runner¶
创建结果的运行者
- stderr_bytes¶
标准错误(以字节为单位),如果不可用,则为NONE
- stdout_bytes¶
标准输出为字节。