invoke.runners.Local

class documentation

class Local(Runner): (source)

View In Hierarchy

Execute a command on the local system in a subprocess. .. note:: When Invoke itself is executed without a controlling terminal (e.g. when ``sys.stdin`` lacks a useful ``fileno``), it's not possible to present a handle on our PTY to local subprocesses. In such situations, `Local` will fallback to behaving as if ``pty=False`` (on the theory that degraded execution is better than none at all) as well as printing a warning to stderr. To disable this behavior, say ``fallback=False``. .. versionadded:: 1.0

Method __init__ Create a new runner with a handle on some `.Context`.
Method close_proc_stdin Close running process' stdin.
Method kill Forcibly terminate the subprocess.
Method read_proc_stderr Read ``num_bytes`` from the running process' stderr stream.
Method read_proc_stdout Read ``num_bytes`` from the running process' stdout stream.
Method returncode Return the numeric return/exit code resulting from command execution.
Method should_use_pty Should execution attempt to use a pseudo-terminal?
Method start Initiate execution of ``command`` (via ``shell``, with ``env``).
Method stop Perform final cleanup, if necessary.
Instance Variable parent_fd Undocumented
Instance Variable pid Undocumented
Instance Variable status Undocumented
Instance Variable warned_about_pty_fallback Undocumented
Property process_is_finished Determine whether our subprocess has terminated.
Method _write_proc_stdin Write ``data`` to running process' stdin.

Inherited from Runner:

Method create_io_threads Create and return a dictionary of IO thread worker objects.
Method decode Decode some ``data`` bytes, returning Unicode.
Method default_encoding Return a string naming the expected encoding of subprocess streams.
Method echo Undocumented
Method generate_env Return a suitable environment dict based on user input & behavior.
Method generate_result Create & return a suitable `Result` instance from the given ``kwargs``.
Method handle_stderr Read process' stderr, storing into a buffer & printing/parsing.
Method handle_stdin Read local stdin, copying into process' stdin as necessary.
Method handle_stdout Read process' stdout, storing into a buffer & printing/parsing.
Method make_promise Return a `Promise` allowing async control of the rest of lifecycle.
Method read_our_stdin Read & decode bytes from a local stdin stream.
Method read_proc_output Iteratively read & decode bytes from a subprocess' out/err stream.
Method respond Write to the program's stdin in response to patterns in ``buffer_``.
Method run Execute ``command``, returning an instance of `Result` once complete.
Method send_interrupt Submit an interrupt signal to the running subprocess.
Method should_echo_stdin Determine whether data read from ``input_`` should echo to ``output``.
Method start_timer Start a timer to `kill` our subprocess after ``timeout`` seconds.
Method wait Block until the running command appears to have exited.
Method write_our_output Write ``string`` to ``stream``.
Method write_proc_stdin Write encoded ``data`` to the running process' stdin.
Instance Variable context Undocumented
Instance Variable encoding Undocumented
Instance Variable env Undocumented
Instance Variable input_sleep Undocumented
Instance Variable opts Undocumented
Instance Variable program_finished Undocumented
Instance Variable read_chunk_size Undocumented
Instance Variable result_kwargs Undocumented
Instance Variable stderr Undocumented
Instance Variable stdout Undocumented
Instance Variable streams Undocumented
Instance Variable threads Undocumented
Instance Variable using_pty Undocumented
Instance Variable watchers Undocumented
Property has_dead_threads Detect whether any IO threads appear to have terminated unexpectedly.
Property timed_out Returns ``True`` if the subprocess stopped because it timed out.
Method _collate_result Undocumented
Method _finish Undocumented
Method _handle_output Undocumented
Method _run_body Undocumented
Method _setup Prepare data on ``self`` so we're ready to start running.
Method _thread_join_timeout Undocumented
Method _unify_kwargs_with_config Unify `run` kwargs with config options to arrive at local options.
Instance Variable _asynchronous Undocumented
Instance Variable _disowned Undocumented
Instance Variable _timer Undocumented
def __init__(self, context): (source)
overrides invoke.runners.Runner.__init__

Create a new runner with a handle on some `.Context`. :param context: a `.Context` instance, used to transmit default options and provide access to other contextualized information (e.g. a remote-oriented `.Runner` might want a `.Context` subclass holding info about hostnames and ports.) .. note:: The `.Context` given to `.Runner` instances **must** contain default config values for the `.Runner` class in question. At a minimum, this means values for each of the default `.Runner.run` keyword arguments such as ``echo`` and ``warn``. :raises exceptions.ValueError: if not all expected default values are found in ``context``.

def close_proc_stdin(self): (source)
overrides invoke.runners.Runner.close_proc_stdin

Close running process' stdin. :returns: ``None``. .. versionadded:: 1.3

def kill(self): (source)
overrides invoke.runners.Runner.kill

Forcibly terminate the subprocess. Typically only used by the timeout functionality. This is often a "best-effort" attempt, e.g. remote subprocesses often must settle for simply shutting down the local side of the network connection and hoping the remote end eventually gets the message.

def read_proc_stderr(self, num_bytes): (source)
overrides invoke.runners.Runner.read_proc_stderr

Read ``num_bytes`` from the running process' stderr stream. :param int num_bytes: Number of bytes to read at maximum. :returns: A string/bytes object. .. versionadded:: 1.0

def read_proc_stdout(self, num_bytes): (source)
overrides invoke.runners.Runner.read_proc_stdout

Read ``num_bytes`` from the running process' stdout stream. :param int num_bytes: Number of bytes to read at maximum. :returns: A string/bytes object. .. versionadded:: 1.0

def returncode(self): (source)
overrides invoke.runners.Runner.returncode

Return the numeric return/exit code resulting from command execution. :returns: `int` .. versionadded:: 1.0

def should_use_pty(self, pty=False, fallback=True): (source)
overrides invoke.runners.Runner.should_use_pty

Should execution attempt to use a pseudo-terminal? :param bool pty: Whether the user explicitly asked for a pty. :param bool fallback: Whether falling back to non-pty execution should be allowed, in situations where ``pty=True`` but a pty could not be allocated. .. versionadded:: 1.0

def start(self, command, shell, env): (source)
overrides invoke.runners.Runner.start

Initiate execution of ``command`` (via ``shell``, with ``env``). Typically this means use of a forked subprocess or requesting start of execution on a remote system. In most cases, this method will also set subclass-specific member variables used in other methods such as `wait` and/or `returncode`. :param str command: Command string to execute. :param str shell: Shell to use when executing ``command``. :param dict env: Environment dict used to prep shell environment. .. versionadded:: 1.0

def stop(self): (source)
overrides invoke.runners.Runner.stop

Perform final cleanup, if necessary. This method is called within a ``finally`` clause inside the main `run` method. Depending on the subclass, it may be a no-op, or it may do things such as close network connections or open files. :returns: ``None`` .. versionadded:: 1.0

parent_fd = (source)

Undocumented

pid = (source)

Undocumented

status = (source)

Undocumented

warned_about_pty_fallback: bool = (source)
overrides invoke.runners.Runner.warned_about_pty_fallback

Undocumented

@property
process_is_finished = (source)
overrides invoke.runners.Runner.process_is_finished

Determine whether our subprocess has terminated. .. note:: The implementation of this method should be nonblocking, as it is used within a query/poll loop. :returns: ``True`` if the subprocess has finished running, ``False`` otherwise. .. versionadded:: 1.0

def _write_proc_stdin(self, data): (source)
overrides invoke.runners.Runner._write_proc_stdin

Write ``data`` to running process' stdin. This should never be called directly; it's for subclasses to implement. See `write_proc_stdin` for the public API call. :param data: Already-encoded byte data suitable for writing. :returns: ``None``. .. versionadded:: 1.0