exceptions

自定义异常类。

这些在用例中有所不同，从“我们需要在用于消息传递的异常中使用特定的数据结构布局”到简单的“我们需要用一种容易区分其他真正意外错误的方式来表示错误条件”。

exception invoke.exceptions.AmbiguousEnvVar

加载env var配置键的目标不明确时引发。

在 1.0 版本加入.

__weakref__

对象的弱引用列表

exception invoke.exceptions.AuthFailure(result: Result, prompt: str)

身份验证失败，例如由于不正确的 sudo 密码。

备注

Result 附加到这些异常的对象通常缺少退出代码信息，因为命令从未完全执行-而是引发了异常。

在 1.0 版本加入.

__init__(result: Result, prompt: str) → None

__str__() → str

返回str(Self)。

exception invoke.exceptions.CollectionNotFound(name: str, start: str)

__init__(name: str, start: str) → None

__weakref__

对象的弱引用列表

exception invoke.exceptions.CommandTimedOut(result: Result, timeout: int)

当子进程未在所需的时间范围内退出时引发。

__init__(result: Result, timeout: int) → None

__repr__() → str

返回epr(Self)。

__str__() → str

返回str(Self)。

exception invoke.exceptions.Exit(message: str | None = None, code: int | None = None)

SystemExit的简单自定义替代。

取代分散的sys.exit调用，提高可测试性，允许用户在不拦截实际系统退出的情况下捕获退出请求(通常这是一件不友好的事情，因为大多数用户调用 sys.exit 而是期待它真正退出。)

如果未捕获异常，则默认为非打印的0退出友好终止行为。

如果 code (整型)给定时，该代码用于退出。

如果 message (字符串)给定，它被打印为标准错误，程序退出，并显示代码 1 默认情况下(除非还通过提供 code 明确地说。)

在 1.0 版本加入.

__init__(message: str | None = None, code: int | None = None) → None

__weakref__

对象的弱引用列表

exception invoke.exceptions.Failure(result: Result, reason: WatcherError | None = None)

代表命令执行失败的异常子类。

“失败”可能意味着执行了命令，并且Shell程序指示了不寻常的结果(通常是一个非零的退出代码)，或者它可能意味着其他一些东西，比如 sudo 当提供的密码身份验证失败时中止的命令。

有两个属性允许自省来确定问题的性质：

• result ：A Result 实例，其中包含有关正在执行的命令的信息，如果该命令运行到完成，则说明它如何退出。

• reason ：包装的异常实例(如果适用)(例如 StreamWatcher 已提高 WatcherError )或 None 否则，在这种情况下，它可能是一个 Failure 子类，指示其自身的特定性质，例如 UnexpectedExit 或 CommandTimedOut 。

这个类很少自己提出；大多数情况下 Runner.run (或相同的包装，如 Context.sudo )将引发一个特定的子类，如 UnexpectedExit 或 AuthFailure 。

在 1.0 版本加入.

__init__(result: Result, reason: WatcherError | None = None) → None

__repr__() → str

返回epr(Self)。

__weakref__

对象的弱引用列表

streams_for_display() → Tuple[str, str]

根据需要返回标准输出/错误流以显示错误。

须遵守以下规则：

• 如果给定流是 not 在执行期间隐藏，将使用占位符，以避免打印两次。

• 仅包括流文本的最后10行。

• PTY驱动的执行将缺少stderr，并且返回与此相关的特定消息，而不是stderr转储。

返回:

标准输出、标准错误字符串的两个元组。

在 1.3 版本加入.

exception invoke.exceptions.ParseError(msg: str, context: ParserContext | None = None)

解析命令行标志/参数时出现错误。

输入不明确、任务名称无效、标志无效等。

在 1.0 版本加入.

__init__(msg: str, context: ParserContext | None = None) → None

__weakref__

对象的弱引用列表

exception invoke.exceptions.PlatformError

在当前平台发生非法操作时引发。

例如，Windows用户尝试使用需要 pty 模块。

通常用于向用户显示更清晰的错误消息。

在 1.0 版本加入.

__weakref__

对象的弱引用列表

exception invoke.exceptions.ResponseNotAccepted

一个响应者/观察者类注意到它的提交得到了“不好的”响应。

主要由以下人员使用 FailingResponder 和子类，例如“哦，天哪，我自动提交了一个sudo密码，但它是不正确的。”

在 1.0 版本加入.

exception invoke.exceptions.SubprocessPipeError

处理子进程管道(stdout/err/in)时遇到一些问题。

通常仅适用于特殊情况；大多数情况下，此区域中的错误由解释器或操作系统引发，并最终包装在 ThreadException 。

在 1.3 版本加入.

__weakref__

对象的弱引用列表

exception invoke.exceptions.ThreadException(exceptions: List[ExceptionWrapper])

在后台线程中引发了一个或多个异常。

真正的底层异常存储在 exceptions 属性；有关数据结构的详细信息，请参阅其文档。

备注

未遇到异常的线程不会影响此异常对象，因此不会出现在内部 exceptions 。

在 1.0 版本加入.

__init__(exceptions: List[ExceptionWrapper]) → None

__str__() → str

返回str(Self)。

__weakref__

对象的弱引用列表

exceptions: Tuple[ExceptionWrapper, ...] = ()

一个元组 ExceptionWrappers 包含初始线程构造函数kwargs(因为 threading.Thread 子类应始终使用kwargs调用)，并捕获该线程的异常，如下所示 sys.exc_info (因此：类型、值、回溯)。

备注

此属性的顺序定义不明确。

备注

看起来很长的线程错误(例如IO缓冲区)将在打印时被截断，以避免显示巨大的不可读错误。

exception invoke.exceptions.UncastableEnvVar

在其缺省值太丰富的尝试环境变量加载时引发。

例如，试图填饱肚子 MY_VAR="foo" vt.进入，进入 {'my_var': ['uh', 'oh']} 在我们实现某种转换选项之前没有任何意义。

在 1.0 版本加入.

__weakref__

对象的弱引用列表

exception invoke.exceptions.UnexpectedExit(result: Result, reason: WatcherError | None = None)

Shell命令运行到完成，但退出时出现意外退出代码。

其字符串表示形式显示如下：

• 已执行命令；

• 退出代码；

• 最后10行标准输出，如果它被隐藏的话；

• 最后10行stderr，如果它是隐藏的且非空的(例如，pty=False；当pty=True时，永远不会发生stderr)。

在 1.0 版本加入.

__str__() → str

返回str(Self)。

exception invoke.exceptions.UnknownFileType

指定了未知类型的配置文件，无法加载。

在 1.0 版本加入.

__weakref__

对象的弱引用列表

exception invoke.exceptions.UnpicklableConfigMember

配置文件包含模块对象，无法对其进行浸泡/复制。

我们引发这个更容易捕获的异常，而不是让(措辞不明确的)TypeError从Pickle模块中冒出来。(但是，为了避免我们自己脆弱地捕获该错误，我们通过显式测试模块成员来防止错误。)

在 1.0.2 版本加入.

__weakref__

对象的弱引用列表

exception invoke.exceptions.WatcherError

的泛型父异常类 StreamWatcher -相关错误。

通常，这些异常之一指示 StreamWatcher 注意到输出流中出现异常情况，例如身份验证响应失败。

Runner 捕捉到这些并将它们连接到 Failure 异常，以便它们可以被中间代码引用和/或作为最终用户的额外信息。

在 1.0 版本加入.

__weakref__

对象的弱引用列表