inv[oke] 核心用途

参见

本页文档 invoke 的核心参数、选项和行为(包括 custom Invoke-based binaries )有关调用用户指定任务和其他与解析器相关的详细信息,请参见 调用任务 .

核心选项和标志

invoke 的用法如下:

$ inv[oke] [--core-opts] task1 [--task1-opts] ... taskN [--taskN-opts]

所有核心选项和标志如下;几乎所有这些都必须给出 之前 任何任务名称,加上一些(例如 --help )在命令行的任何地方被特别寻找。(有关分析详细信息,请参见 基本命令行布局

--complete

将调用命令行的有效制表符完成选项打印(行分隔)为“余数”(即 -- )用于建筑 shell completion scripts .

例如,当本地任务树包含名为 foobar 以及何时 foo 带旗 --foo-arg--foo-arg-2 ,您可以这样使用它:

# Empty input: just task names
$ inv --complete --
foo
bar

# Input not ending with a dash: task names still
$ inv --complete -- foo --foo-arg
foo
bar

# Input ending with a dash: current context's flag names
$ inv --complete -- foo -
--foo-arg
--foo-arg-2

有关如何充分利用此选项的详细信息,请参见 --print-completion-script .

--hide=STRING

设置run()的“hide”kwarg的默认值。

--no-dedupe

禁用任务重复数据消除。

--print-completion-script=SHELL

打印所需的完成脚本 SHELL (例如) bashzsh 等)。这可以源于当前会话以便享受。 tab-completion for tasks and options .

这些脚本与invoke的分布式代码库捆绑在一起,并在内部使用 --complete .

--prompt-for-sudo-password

在会话开始时(在执行任何任务之前)提示 sudo.password 配置值。这使得不想在配置系统或shell环境中保存敏感材料的用户可以依赖用户输入,而不会中断程序的流程。

--write-pyc

默认情况下,调用禁用字节码缓存,因为它会导致任务文件难以调试的问题(以及通常用于调用的事物)不能提供明显的速度效益。如果你真的想 .pyc 文件返回,给这个选项。

-c STRING, --collection=STRING

指定要加载的集合名称。

-d, --debug

启用调试输出。

--dry

回送命令而不是实际运行它们;特别是,导致 run 呼叫:

  • 表现得好像 echo 选项已打开,打印要运行到stdout的命令;

  • 跳过实际的子进程调用(在任何机器开始运行之前返回);

  • 返回一个假人 Result 具有“blank”值的对象(空stdout/err字符串, 0 退出代码等)。

-D, --list-depth=INT

限制 --list 显示到指定数量的级别,例如 --list-depth 1 只显示顶级任务和命名空间。

如果一个论点 --list ,那么这个深度是相对的;所以 --list build --list-depth 1 显示了 build 子树。

如果未指定此选项,则默认行为是显示整个任务树的所有级别。

-e, --echo

在运行之前回显执行的命令。

-f, --config

指定一个 runtime configuration file 加载。

请注意,您可以使用 INVOKE_RUNTIME_CONFIG 替换此选项的环境变量。如果两者都给出,那么cli选项将胜出。

-F, --list-format=STRING

更改用于显示输出的格式 --list ;可能是:

  • flat (默认值):带有虚线任务名称的单列、平直列表。

  • nested :嵌套(4空间缩进)垂直列表,其中每个级别隐式包含其父级(前导点作为强视觉线索,表明这些仍然是子集合任务)。

  • json :此格式旨在供脚本或其他程序使用,它发出代表任务树的json,树中的每个“节点”(最外面的文档是根节点,因此是json对象)由以下键组成:

    • name :集合的字符串名称;对于根集合,这通常是模块名称,因此除非向加载进程提供备用集合名称,否则通常是 "tasks" (从 tasks.py

    • help :集合的docstring的第一行,如果它来自模块;否则为空(或者如果模块缺少docstring)。

    • tasks :此集合的直接子级;以下形式的对象数组:

      • name :任务在其集合中的本地名称(即,不是使用 flat 格式化;重新构建该路径由使用者决定。)

      • help :任务的docstring的第一行,如果没有,则为空。

      • aliases :此任务的字符串别名数组。

    • default :字符串命名此集合中的哪个任务(如果有)是默认任务。如果没有默认任务,则为空。

    • collections :此集合中任何子集合的数组,其成员将递归地具有与此最外层文档相同的结构。

    发出的json不是很好地打印出来的,而是以一个尾随的换行符结尾。

-h STRING, --help=STRING

如果给定时没有任何任务名称,则显示核心帮助;如果给定时有任务名称(可能在 or 在任务名称之后)显示该特定任务的帮助。

-l, --list=STRING

列出可用任务。默认情况下显示所有任务;可能会将显式命名空间指定给“root”;显示的任务树仅指定给该命名空间。(此参数可能包含句点,与任务名称一样,因此如果需要,可以仅显示整个树的一小部分深度部分。)

-p, --pty

执行shell命令时使用pTy。

-r STRING, --search-root=STRING

更改用于查找任务模块的根目录。

-T INT, --command-timeout=INT

将默认命令执行超时设置为int秒。地图到 timeouts.command 配置设置。

-V, --version

显示版本并退出。

-w, --warn-only

当shell命令失败时发出警告,而不是失败。

外壳标签完成

生成完成脚本

invoke的理念是实现通用api,然后在这些api的基础上“引入”一些常见的用例;tab完成也不例外。通用的制表符完成功能(为给定的命令行上下文输出与shell兼容的完成标记列表)由 --complete 上面描述的core cli选项。

但是,您可能不需要自己使用该标志:我们分发了一些现成的包装脚本,这些脚本针对最常见的shell,如 bashzsh (加上其他)。这些脚本可以从调用或调用自动生成。 any Invoke-driven command-line tool 使用 --print-completion-script ;打印的脚本将包含生成它们的程序的正确二进制名称。

例如,下面的命令打印(到stdout)一个用于 zsh 指导 zsh 把它用在 invinvoke 程序和呼叫 invoke --complete 在运行时获取动态完成信息:

$ invoke --print-completion-script zsh

注解

您可能希望将此命令作为源或将其输出永久存储在某个地方;下一节将详细介绍这一点。

同样, Fabric 工具继承自invoke,并且只有一个二进制名称 (fab );如果你想完成织物 bash ,你会说:

$ fab --print-completion-script bash

在本节的其余部分中,我们将使用 inv 在示例中,但请记住,如果不是调用本身,请用实际使用的程序替换它!

源代码脚本

根据您的需要、程序的安装位置和shell,有几种方法可以利用上述命令的输出:

  • 最简单、破坏性最小的方法是 source 打印的内联完成脚本,它不会在磁盘上放置任何内容,只会影响当前的shell会话:

    $ source <(inv --print-completion-script zsh)
    
  • 如果您在系统的全局python解释器中有可用的程序(并且您可以在每个shell会话启动时运行该程序——python的速度显然不是它的强项),那么可以将该片段添加到shell的启动文件中,例如 ~/.zshrc~/.bashrc .

  • 如果该计划在全球范围内可用,但您希望 避免 在shell启动过程中运行一个额外的Python程序,你可以缓存命令在自己的文件中的输出;这个文件的生命完全取决于你和你的shell是如何配置的。例如,您可以将其作为隐藏文件放入主目录:

    $ inv --print-completion-script zsh > ~/.invoke-completion.sh
    

    然后在结尾处添加以下内容 ~/.zshrc ::

    source ~/.invoke-completion.sh
    

    但再一次,这完全取决于你和你的壳。

    注解

    如果你在用 fishmust 使用此策略,因为我们的鱼完成脚本不适合直接采购。fish shell用户应该将命令的输出指向 ~/.config/fish/completions/ 目录。

  • 最后,如果需要完成程序的副本只安装在一个特定环境(如ValueLeNV)中,则可以使用上述任一技术:

    • 在这种情况下,缓存输出并在全局shell启动文件中引用它仍然可以工作,因为它不要求程序在shell加载时可用——仅当您实际尝试制表符complete时。

    • 使用 source <(inv --print-completion-script yourshell) 方法将起作用 只要 您可以将它放在某个适当的每个环境启动文件中,该文件将根据您管理python环境的方式而有所不同。例如,如果使用 virtualenvwrapper ,您可以附加 source 行在 /path/to/virtualenv/bin/postactivate .

利用制表符完成本身

您已确保完成脚本在您的环境中处于活动状态—您获得了什么?

  • 默认情况下,键入后切换 invinvoke 将显示当前目录/项目任务文件中的任务名称。

  • 键入破折号后的制表符 (- )或双破折号 (-- )将显示当前上下文的有效选项/标志:如果尚未键入任务名称,则显示核心调用选项;否则显示最近键入的任务的选项。

    • 键入部分long选项时的制表符将使用shell的原生子字符串完成与long选项的匹配。例如,如果尚未键入任务名称, --e<tab> 将提供 --echo 作为完成选项。

  • 当最新键入/完成的标记是一个接受值的标志时,点击tab键将“通过”shell的本机文件名完成。

    • 例如,在键入任务名称之前, --config <tab> 将完成本地文件路径以帮助填写配置文件。