context

class invoke.context.Context(config: Config | None = None)

上下文感知API包装器&状态传递对象。

Context 对象是在命令行解析过程中创建的(如果需要，也可以手动创建)，用于与执行的任务共享解析器和配置状态(请参见 旁白：这个“context”参数到底是什么？ )。

具体地说，该类为核心API调用(如 run )，其考虑了CLI解析器标志、配置文件和/或在运行时做出的改变。它还充当其 config 属性-有关详细信息，请参阅该属性的文档。

实例 Context 可以在执行子任务时在任务之间共享-要么与调用者获得的上下文相同，要么是其更改的副本(理论上，或者是全新的)。

在 1.0 版本加入.

__init__(config: Config | None = None) → None
参数:

config -- Config 对象以用作基本配置。缺省为匿名/缺省 Config 举个例子。

cd(path: PathLike | str) → Generator[None, None, None]

在执行命令时保持目录状态的上下文管理器。

任何呼叫 run ， sudo ，将隐式具有一个类似于 "cd <path> && " 添加前缀，以便给人一种实际上涉及状态化的感觉。

因为使用了 cd 会影响所有此类调用，任何利用 cwd 属性的使用也将影响 cd 。

就像真正的‘CD’Shell一样， cd 可以使用相对路径调用(请记住，您的默认起始目录是您的用户的 $HOME )，并且也可以嵌套。

下面是使用Shell‘cd’的“正常”尝试，它不起作用，因为所有命令都在单独的子进程中执行--状态为 not 在调用之间保留 run 或 sudo **

c.run('cd /var/www')
c.run('ls')

上面的代码片段将列出用户的 $HOME 而不是 /var/www 。使用 cd 然而，它将按预期工作：：

with c.cd('/var/www'):
    c.run('ls')  # Turns into "cd /var/www && ls"

最后，一个嵌套的演示(请参阅内联注释)：

with c.cd('/var/www'):
    c.run('ls') # cd /var/www && ls
    with c.cd('website1'):
        c.run('ls')  # cd /var/www/website1 && ls

备注

空格字符将自动转义，以便更轻松地处理此类目录名。

在 1.0 版本加入.

在 1.5 版本发生变更: 显式地将 path 参数(唯一的参数)转换为字符串；这允许任何定义 __str__ 要上交的(如各种 Path 对象)，而不仅仅是字符串文字。

property cwd: str

返回当前工作目录，说明 cd 。

在 1.0 版本加入.

prefix(command: str) → Generator[None, None, None]

为所有嵌套项添加前缀 run /sudo`带有给定命令的命令以及  ``&&` 。

在大多数情况下，您会希望将其与更改Shell状态的Shell脚本一起使用，例如用于导出或更改Shell环境变量的脚本。

例如，此工具最常见的用法之一是与 workon 命令来自 virtualenvwrapper **

with c.prefix('workon myvenv'):
    c.run('./manage.py migrate')

在上面的代码片段中，实际运行的Shell命令如下：

$ workon myvenv && ./manage.py migrate

此上下文管理器与 cd ，所以如果您的Virtualenv cd 在ITS中 postactivate 脚本，您可以执行以下操作：

with c.cd('/path/to/app'):
    with c.prefix('workon myvenv'):
        c.run('./manage.py migrate')
        c.run('./manage.py loaddata fixture')

这将导致如下的执行：：

$ cd /path/to/app && workon myvenv && ./manage.py migrate
$ cd /path/to/app && workon myvenv && ./manage.py loaddata fixture

最后，正如上面提到的， prefix 如果需要，可以嵌套，例如：

with c.prefix('workon myenv'):
    c.run('ls')
    with c.prefix('source /some/script'):
        c.run('touch a_file')

结果：：

$ workon myenv && ls
$ workon myenv && source /some/script && touch a_file

做作，但希望是说明性的。

在 1.0 版本加入.

run(command: str, **kwargs: Any) → Result | None

执行本地Shell命令，遵守配置选项。

具体地说，此方法实例化 Runner 子类(根据 runner 配置选项；默认为 Local )，并调用其 .run 方法： command 和 kwargs 。

看见 Runner.run 有关以下内容的详细信息 command 和可用的关键字参数。

在 1.0 版本加入.

sudo(command: str, **kwargs: Any) → Result | None

通过以下方式执行Shell命令 sudo 具有密码自动响应功能。

Basics

此方法与 run ，但添加了几个围绕调用 sudo 程序。它不会做任何用户无法通过包装自己做的事情 run ，但这种用例太常见了，无法让用户自己重新发明这些轮子。

备注

如果您打算手动响应sudo的密码提示，只需使用 run("sudo command") 相反，是这样！此方法中的自动响应功能只会阻碍您的工作。

具体来说， sudo ：

  • 放置了一个 FailingResponder 进入 watchers Kwarg(请参见 自动响应程序输出 )，其中：

    • 搜索已配置的 sudo 密码提示；

    • 使用配置的sudo密码进行响应 (sudo.password 从 configuration )；

    • 可以判断该响应何时导致身份验证失败(例如，如果系统需要密码但未配置密码)，并引发 AuthFailure 如果是这样的话。

  • 构建一个 sudo 命令字符串使用提供的 command 参数，以各种标志为前缀(见下文)；

  • 通过调用 run ，返回结果。

Flags used

sudo 引擎盖下使用的旗帜包括：

  • -S 允许通过标准输入自动响应密码；

  • -p <prompt> 明确说明要使用的提示符，这样我们就可以确保我们的自动响应器知道要查找什么；

  • -u <user> 如果 user 不是 None ，以非用户身份执行命令 root ；

  • 什么时候 -u 是存在的， -H ，以确保子流程具有请求的用户的 $HOME 正确设置。

Configuring behavior

有几种方法可以更改此方法的行为方式：

  • 因为它包裹着 run ，它向所有人致敬 run 配置参数和关键字参数，其方式与 run 的确如此。

    • 因此，调用，如 c.sudo('command', echo=True) 是可能的，并且如果配置层(例如配置文件或环境变量)指定例如 run.warn = True ，这也将在以下情况下生效 sudo 。

  • sudo 有自己的一组关键字参数(见下文)，它们也都可以通过配置系统控制，在 sudo.* 树。

    • 因此，例如，您可以在配置文件中预先设置sudo用户； invoke.json 含 {"sudo": {"user": "someuser"}} 。

参数:

  • password (str) -- 的运行时覆盖 sudo.password 。

  • user (str) -- 的运行时覆盖 sudo.user 。

在 1.0 版本加入.

class invoke.context.MockContext(config: Config | None = None, **kwargs: Any)

A Context 其方法的返回值可以预先确定。

主要用于测试使用代码库的调用。

备注

此类包装了它的 run 、ETC中的方法 unittest.mock.Mock 物体。这允许您轻松地断言这些方法(仍然返回您准备它们的值)实际上是被调用的。

备注

未给出方法 Results 屈服就会提高 NotImplementedError 如果被调用(因为另一种选择是调用真正的底层方法--这在模拟时通常是不可取的。)

在 1.0 版本加入.

在 1.5 版本发生变更: 增列 Mock 包装 run 和 sudo 。

__init__(config: Config | None = None, **kwargs: Any) → None

创建 Context -类对象，其方法产生 Result 物体。

参数:

  • config -- 要使用的配置对象。在行为上与 Context 。

  • run -- 指示内容的数据结构 Result 从对实例化对象的 run 方法(而不是实际执行所请求的Shell命令)。具体地说，这位考官接受：-单人 Result 对象。-布尔值；如果为True，则生成 Result 谁的 exited 是 0 ，如果为假， 1 。-上述值的可迭代数，它将在每次后续调用时返回 .run (第一次调用第一项，第二次调用第二项，依此类推)。-将命令字符串或编译的regexen映射到上述值(包括迭代值)的dict，允许特定的调用和响应语义，而不是假定调用顺序。

  • sudo -- 等同于 run ，但其值是通过调用 sudo 。

  • repeat (bool) -- 确定此类的方法产生的结果是重复还是被使用的标志。例如，当指示单个结果时，它通常只返回一次，从而导致 NotImplementedError 之后。但当 repeat=True ，则该结果将永远在每次调用时返回。类似地，可迭代结果通常会耗尽一次，但当启用此设置时，它们会被包装在 itertools.cycle 。默认： True 。

加薪:

TypeError ，如果给出的值 run 或者其他的科瓦克不是预期的类型。

在 1.5 版本发生变更: 添加了对布尔型和字符串结果值的支持。

在 1.5 版本发生变更: 添加了对regex Dict键的支持。

在 1.5 版本发生变更: 添加了 repeat 关键字参数。

在 2.0 版本发生变更: 变化 repeat 缺省值来自 False 至 True 。

run(command: str, *args: Any, **kwargs: Any) → Result

执行本地Shell命令，遵守配置选项。

具体地说，此方法实例化 Runner 子类(根据 runner 配置选项；默认为 Local )，并调用其 .run 方法： command 和 kwargs 。

看见 Runner.run 有关以下内容的详细信息 command 和可用的关键字参数。

在 1.0 版本加入.

set_result_for(attname: str, command: str, result: Result) → None

修改存储的给定模拟结果 attname (例如： run )。

这类似于实例化 MockContext 使用一个 run 或 sudo Dict Kwarg。例如，这是：：

mc = MockContext(run={'mycommand': Result("mystdout")})
assert mc.run('mycommand').stdout == "mystdout"

在功能上等同于：：

mc = MockContext()
mc.set_result_for('run', 'mycommand', Result("mystdout"))
assert mc.run('mycommand').stdout == "mystdout"

set_result_for 对于修改已实例化的 MockContext ，例如由测试设置或帮助器方法创建的。

在 1.0 版本加入.

sudo(command: str, *args: Any, **kwargs: Any) → Result

通过以下方式执行Shell命令 sudo 具有密码自动响应功能。

Basics

此方法与 run ，但添加了几个围绕调用 sudo 程序。它不会做任何用户无法通过包装自己做的事情 run ，但这种用例太常见了，无法让用户自己重新发明这些轮子。

备注

如果您打算手动响应sudo的密码提示，只需使用 run("sudo command") 相反，是这样！此方法中的自动响应功能只会阻碍您的工作。

具体来说， sudo ：

  • 放置了一个 FailingResponder 进入 watchers Kwarg(请参见 自动响应程序输出 )，其中：

    • 搜索已配置的 sudo 密码提示；

    • 使用配置的sudo密码进行响应 (sudo.password 从 configuration )；

    • 可以判断该响应何时导致身份验证失败(例如，如果系统需要密码但未配置密码)，并引发 AuthFailure 如果是这样的话。

  • 构建一个 sudo 命令字符串使用提供的 command 参数，以各种标志为前缀(见下文)；

  • 通过调用 run ，返回结果。

Flags used

sudo 引擎盖下使用的旗帜包括：

  • -S 允许通过标准输入自动响应密码；

  • -p <prompt> 明确说明要使用的提示符，这样我们就可以确保我们的自动响应器知道要查找什么；

  • -u <user> 如果 user 不是 None ，以非用户身份执行命令 root ；

  • 什么时候 -u 是存在的， -H ，以确保子流程具有请求的用户的 $HOME 正确设置。

Configuring behavior

有几种方法可以更改此方法的行为方式：

  • 因为它包裹着 run ，它向所有人致敬 run 配置参数和关键字参数，其方式与 run 的确如此。

    • 因此，调用，如 c.sudo('command', echo=True) 是可能的，并且如果配置层(例如配置文件或环境变量)指定例如 run.warn = True ，这也将在以下情况下生效 sudo 。

  • sudo 有自己的一组关键字参数(见下文)，它们也都可以通过配置系统控制，在 sudo.* 树。

    • 因此，例如，您可以在配置文件中预先设置sudo用户； invoke.json 含 {"sudo": {"user": "someuser"}} 。

参数:

  • password (str) -- 的运行时覆盖 sudo.password 。

  • user (str) -- 的运行时覆盖 sudo.user 。

在 1.0 版本加入.