util

class invoke.util.ExceptionHandlingThread(**kwargs: Any)

Thread handler making it easier for parent to handle thread exceptions.

Based in part on Fabric 1’s ThreadHandler. See also Fabric GH issue #204.

When used directly, can be used in place of a regular threading.Thread. If subclassed, the subclass must do one of:

• supply target to __init__

• define _run() instead of run()

This is because this thread’s entire point is to wrap behavior around the thread’s execution; subclasses could not redefine run() without breaking that functionality.

New in version 1.0.

__init__(**kwargs: Any) → None

Create a new exception-handling thread instance.

Takes all regular threading.Thread keyword arguments, via **kwargs for easier display of thread identity when raising captured exceptions.

__repr__() → str

Return repr(self).

exception() → ExceptionWrapper | None

If an exception occurred, return an ExceptionWrapper around it.

Returns:

An ExceptionWrapper managing the result of sys.exc_info, if an exception was raised during thread execution. If no exception occurred, returns None instead.

New in version 1.0.

property is_dead: bool

Returns True if not alive and has a stored exception.

Used to detect threads that have excepted & shut down.

New in version 1.0.

run() → None

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

invoke.util.has_fileno(stream: IO) → bool

Cleanly determine whether stream has a useful .fileno().

Note

This function helps determine if a given file-like object can be used with various terminal-oriented modules and functions such as select, termios, and tty. For most of those, a fileno is all that is required; they’ll function even if stream.isatty() is False.

Parameters:

stream – A file-like object.

Returns:

True if stream.fileno() returns an integer, False otherwise (this includes when stream lacks a fileno method).

New in version 1.0.

invoke.util.helpline(obj: object) → str | None

Yield an object’s first docstring line, or None if there was no docstring.

New in version 1.0.

invoke.util.isatty(stream: IO) → bool | Any

Cleanly determine whether stream is a TTY.

Specifically, first try calling stream.isatty(), and if that fails (e.g. due to lacking the method entirely) fallback to os.isatty.

Note

Most of the time, we don’t actually care about true TTY-ness, but merely whether the stream seems to have a fileno (per has_fileno). However, in some cases (notably the use of pty.fork to present a local pseudoterminal) we need to tell if a given stream has a valid fileno but isn’t tied to an actual terminal. Thus, this function.

Parameters:

stream – A file-like object.

Returns:

A boolean depending on the result of calling .isatty() and/or os.isatty.

New in version 1.0.

invoke.util.task_name_sort_key(name: str) → Tuple[List[str], str]

Return key tuple for use sorting dotted task names, via e.g. sorted.

New in version 1.0.

class invoke.util.ExceptionWrapper(kwargs, type, value, traceback)

A namedtuple wrapping a thread-borne exception & that thread’s arguments. Mostly used as an intermediate between ExceptionHandlingThread (which preserves initial exceptions) and ThreadException (which holds 1..N such exceptions, as typically multiple threads are involved.)