watchers

class invoke.watchers.FailingResponder(pattern: str, response: str, sentinel: str)

Variant of Responder which is capable of detecting incorrect responses.

This class adds a sentinel parameter to __init__, and its submit will raise ResponseNotAccepted if it detects that sentinel value in the stream.

Added in version 1.0.

__init__(pattern: str, response: str, sentinel: str) → None

Imprint this Responder with necessary parameters.

Parameters:

  • pattern – A raw string (e.g. r"\[sudo\] password for .*:") which will be turned into a regular expression.

  • response – The string to submit to the subprocess’ stdin when pattern is detected.

submit(stream: str) → Generator[str, None, None]

Act on stream data, potentially returning responses.

Parameters:

stream (str) – All data read on this stream since the beginning of the session.

Returns:

An iterable of str (which may be empty).

Added in version 1.0.

class invoke.watchers.Responder(pattern: str, response: str)

A parameterizable object that submits responses to specific patterns.

Commonly used to implement password auto-responds for things like sudo.

Added in version 1.0.

__init__(pattern: str, response: str) → None

Imprint this Responder with necessary parameters.

Parameters:

  • pattern – A raw string (e.g. r"\[sudo\] password for .*:") which will be turned into a regular expression.

  • response – The string to submit to the subprocess’ stdin when pattern is detected.

pattern_matches(stream: str, pattern: str, index_attr: str) → Iterable[str]

Generic “search for pattern in stream, using index” behavior.

Used here and in some subclasses that want to track multiple patterns concurrently.

Parameters:

  • stream (str) – The same data passed to submit.

  • pattern (str) – The pattern to search for.

  • index_attr (str) – The name of the index attribute to use.

Returns:

An iterable of string matches.

Added in version 1.0.

submit(stream: str) → Generator[str, None, None]

Act on stream data, potentially returning responses.

Parameters:

stream (str) – All data read on this stream since the beginning of the session.

Returns:

An iterable of str (which may be empty).

Added in version 1.0.

class invoke.watchers.StreamWatcher

A class whose subclasses may act on seen stream data from subprocesses.

Subclasses must exhibit the following API; see Responder for a concrete example.

  • __init__ is completely up to each subclass, though as usual, subclasses of subclasses should be careful to make use of super where appropriate.

  • submit must accept the entire current contents of the stream being watched, as a string, and may optionally return an iterable of strings (or act as a generator iterator, i.e. multiple calls to yield <string>), which will each be written to the subprocess’ standard input.

Note

StreamWatcher subclasses exist in part to enable state tracking, such as detecting when a submitted password didn’t work & erroring (or prompting a user, or etc). Such bookkeeping isn’t easily achievable with simple callback functions.

Note

StreamWatcher subclasses threading.local so that its instances can be used to ‘watch’ both subprocess stdout and stderr in separate threads.

Added in version 1.0.

submit(stream: str) → Iterable[str]

Act on stream data, potentially returning responses.

Parameters:

stream (str) – All data read on this stream since the beginning of the session.

Returns:

An iterable of str (which may be empty).

Added in version 1.0.