exceptions

Custom exception classes.

These vary in use case from “we needed a specific data structure layout in exceptions used for message-passing” to simply “we needed to express an error condition in a way easily told apart from other, truly unexpected errors”.

exception invoke.exceptions.AmbiguousEnvVar

Raised when loading env var config keys has an ambiguous target.

New in version 1.0.

__weakref__

list of weak references to the object (if defined)

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

An authentication failure, e.g. due to an incorrect sudo password.

Note

Result objects attached to these exceptions typically lack exit code information, since the command was never fully executed - the exception was raised instead.

New in version 1.0.

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

__str__() → str

Return str(self).

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

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

__weakref__

list of weak references to the object (if defined)

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

Raised when a subprocess did not exit within a desired timeframe.

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

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).

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

Simple custom stand-in for SystemExit.

Replaces scattered sys.exit calls, improves testability, allows one to catch an exit request without intercepting real SystemExits (typically an unfriendly thing to do, as most users calling sys.exit rather expect it to truly exit.)

Defaults to a non-printing, exit-0 friendly termination behavior if the exception is uncaught.

If code (an int) given, that code is used to exit.

If message (a string) given, it is printed to standard error, and the program exits with code 1 by default (unless overridden by also giving code explicitly.)

New in version 1.0.

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

__weakref__

list of weak references to the object (if defined)

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

Exception subclass representing failure of a command execution.

“Failure” may mean the command executed and the shell indicated an unusual result (usually, a non-zero exit code), or it may mean something else, like a sudo command which was aborted when the supplied password failed authentication.

Two attributes allow introspection to determine the nature of the problem:

• result: a Result instance with info about the command being executed and, if it ran to completion, how it exited.

• reason: a wrapped exception instance if applicable (e.g. a StreamWatcher raised WatcherError) or None otherwise, in which case, it’s probably a Failure subclass indicating its own specific nature, such as UnexpectedExit or CommandTimedOut.

This class is only rarely raised by itself; most of the time Runner.run (or a wrapper of same, such as Context.sudo) will raise a specific subclass like UnexpectedExit or AuthFailure.

New in version 1.0.

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

__repr__() → str

Return repr(self).

__weakref__

list of weak references to the object (if defined)

streams_for_display() → Tuple[str, str]

Return stdout/err streams as necessary for error display.

Subject to the following rules:

• If a given stream was not hidden during execution, a placeholder is used instead, to avoid printing it twice.

• Only the last 10 lines of stream text is included.

• PTY-driven execution will lack stderr, and a specific message to this effect is returned instead of a stderr dump.

Returns:

Two-tuple of stdout, stderr strings.

New in version 1.3.

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

An error arising from the parsing of command-line flags/arguments.

Ambiguous input, invalid task names, invalid flags, etc.

New in version 1.0.

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

__weakref__

list of weak references to the object (if defined)

exception invoke.exceptions.PlatformError

Raised when an illegal operation occurs for the current platform.

E.g. Windows users trying to use functionality requiring the pty module.

Typically used to present a clearer error message to the user.

New in version 1.0.

__weakref__

list of weak references to the object (if defined)

exception invoke.exceptions.ResponseNotAccepted

A responder/watcher class noticed a ‘bad’ response to its submission.

Mostly used by FailingResponder and subclasses, e.g. “oh dear I autosubmitted a sudo password and it was incorrect.”

New in version 1.0.

exception invoke.exceptions.SubprocessPipeError

Some problem was encountered handling subprocess pipes (stdout/err/in).

Typically only for corner cases; most of the time, errors in this area are raised by the interpreter or the operating system, and end up wrapped in a ThreadException.

New in version 1.3.

__weakref__

list of weak references to the object (if defined)

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

One or more exceptions were raised within background threads.

The real underlying exceptions are stored in the exceptions attribute; see its documentation for data structure details.

Note

Threads which did not encounter an exception, do not contribute to this exception object and thus are not present inside exceptions.

New in version 1.0.

__init__(exceptions: List[ExceptionWrapper]) → None

__str__() → str

Return str(self).

__weakref__

list of weak references to the object (if defined)

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

A tuple of ExceptionWrappers containing the initial thread constructor kwargs (because threading.Thread subclasses should always be called with kwargs) and the caught exception for that thread as seen by sys.exc_info (so: type, value, traceback).

Note

The ordering of this attribute is not well-defined.

Note

Thread kwargs which appear to be very long (e.g. IO buffers) will be truncated when printed, to avoid huge unreadable error display.

exception invoke.exceptions.UncastableEnvVar

Raised on attempted env var loads whose default values are too rich.

E.g. trying to stuff MY_VAR="foo" into {'my_var': ['uh', 'oh']} doesn’t make any sense until/if we implement some sort of transform option.

New in version 1.0.

__weakref__

list of weak references to the object (if defined)

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

A shell command ran to completion but exited with an unexpected exit code.

Its string representation displays the following:

• Command executed;

• Exit code;

• The last 10 lines of stdout, if it was hidden;

• The last 10 lines of stderr, if it was hidden and non-empty (e.g. pty=False; when pty=True, stderr never happens.)

New in version 1.0.

__str__() → str

Return str(self).

exception invoke.exceptions.UnknownFileType

A config file of an unknown type was specified and cannot be loaded.

New in version 1.0.

__weakref__

list of weak references to the object (if defined)

exception invoke.exceptions.UnpicklableConfigMember

A config file contained module objects, which can’t be pickled/copied.

We raise this more easily catchable exception instead of letting the (unclearly phrased) TypeError bubble out of the pickle module. (However, to avoid our own fragile catching of that error, we head it off by explicitly testing for module members.)

New in version 1.0.2.

__weakref__

list of weak references to the object (if defined)

exception invoke.exceptions.WatcherError

Generic parent exception class for StreamWatcher-related errors.

Typically, one of these exceptions indicates a StreamWatcher noticed something anomalous in an output stream, such as an authentication response failure.

Runner catches these and attaches them to Failure exceptions so they can be referenced by intermediate code and/or act as extra info for end users.

New in version 1.0.

__weakref__

list of weak references to the object (if defined)