invoke.runners.Runner

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``.

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

Create and return a dictionary of IO thread worker objects. Caller is expected to handle persisting and/or starting the wrapped threads.

Decode some ``data`` bytes, returning Unicode. .. versionadded:: 1.0

Return a string naming the expected encoding of subprocess streams. This return value should be suitable for use by encode/decode methods. .. versionadded:: 1.0

Undocumented

Return a suitable environment dict based on user input & behavior. :param dict env: Dict supplying overrides or full env, depending. :param bool replace_env: Whether ``env`` updates, or is used in place of, the value of `os.environ`. :returns: A dictionary of shell environment vars. .. versionadded:: 1.0

Create & return a suitable `Result` instance from the given ``kwargs``. Subclasses may wish to override this in order to manipulate things or generate a `Result` subclass (e.g. ones containing additional metadata besides the default). .. versionadded:: 1.0

Read process' stderr, storing into a buffer & printing/parsing. Identical to `handle_stdout` except for the stream read from; see its docstring for API details. .. versionadded:: 1.0

Read local stdin, copying into process' stdin as necessary. Intended for use as a thread target. .. note:: Because real terminal stdin streams have no well-defined "end", if such a stream is detected (based on existence of a callable ``.fileno()``) this method will wait until `program_finished` is set, before terminating. When the stream doesn't appear to be from a terminal, the same semantics as `handle_stdout` are used - the stream is simply ``read()`` from until it returns an empty value. :param input_: Stream (file-like object) from which to read. :param output: Stream (file-like object) to which echoing may occur. :param bool echo: User override option for stdin-stdout echoing. :returns: ``None``. .. versionadded:: 1.0

Read process' stdout, storing into a buffer & printing/parsing. Intended for use as a thread target. Only terminates when all stdout from the subprocess has been read. :param buffer_: The capture buffer shared with the main thread. :param bool hide: Whether or not to replay data into ``output``. :param output: Output stream (file-like object) to write data into when not hiding. :returns: ``None``. .. versionadded:: 1.0

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.

Return a `Promise` allowing async control of the rest of lifecycle. .. versionadded:: 1.4

Read & decode bytes from a local stdin stream. :param input_: Actual stream object to read from. Maps to ``in_stream`` in `run`, so will often be ``sys.stdin``, but might be any stream-like object. :returns: A Unicode string, the result of decoding the read bytes (this might be the empty string if the pipe has closed/reached EOF); or ``None`` if stdin wasn't ready for reading yet. .. versionadded:: 1.0

Iteratively read & decode bytes from a subprocess' out/err stream. :param reader: A literal reader function/partial, wrapping the actual stream object in question, which takes a number of bytes to read, and returns that many bytes (or ``None``). ``reader`` should be a reference to either `read_proc_stdout` or `read_proc_stderr`, which perform the actual, platform/library specific read calls. :returns: A generator yielding strings. Specifically, each resulting string is the result of decoding `read_chunk_size` bytes read from the subprocess' out/err stream. .. versionadded:: 1.0

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

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

Write to the program's stdin in response to patterns in ``buffer_``. The patterns and responses are driven by the `.StreamWatcher` instances from the ``watchers`` kwarg of `run` - see :doc:`/concepts/watchers` for a conceptual overview. :param buffer: The capture buffer for this thread's particular IO stream. :returns: ``None``. .. versionadded:: 1.0

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

Execute ``command``, returning an instance of `Result` once complete. By default, this method is synchronous (it only returns once the subprocess has completed), and allows interactive keyboard communication with the subprocess. It can instead behave asynchronously (returning early & requiring interaction with the resulting object to manage subprocess lifecycle) if you specify ``asynchronous=True``. Furthermore, you can completely disassociate the subprocess from Invoke's control (allowing it to persist on its own after Python exits) by saying ``disown=True``. See the per-kwarg docs below for details on both of these. .. note:: All kwargs will default to the values found in this instance's `~.Runner.context` attribute, specifically in its configuration's ``run`` subtree (e.g. ``run.echo`` provides the default value for the ``echo`` keyword, etc). The base default values are described in the parameter list below. :param str command: The shell command to execute. :param bool asynchronous: When set to ``True`` (default ``False``), enables asynchronous behavior, as follows: - Connections to the controlling terminal are disabled, meaning you will not see the subprocess output and it will not respond to your keyboard input - similar to ``hide=True`` and ``in_stream=False`` (though explicitly given ``(out|err|in)_stream`` file-like objects will still be honored as normal). - `.run` returns immediately after starting the subprocess, and its return value becomes an instance of `Promise` instead of `Result`. - `Promise` objects are primarily useful for their `~Promise.join` method, which blocks until the subprocess exits (similar to threading APIs) and either returns a final `~Result` or raises an exception, just as a synchronous ``run`` would. - As with threading and similar APIs, users of ``asynchronous=True`` should make sure to ``join`` their `Promise` objects to prevent issues with interpreter shutdown. - One easy way to handle such cleanup is to use the `Promise` as a context manager - it will automatically ``join`` at the exit of the context block. .. versionadded:: 1.4 :param bool disown: When set to ``True`` (default ``False``), returns immediately like ``asynchronous=True``, but does not perform any background work related to that subprocess (it is completely ignored). This allows subprocesses using shell backgrounding or similar techniques (e.g. trailing ``&``, ``nohup``) to persist beyond the lifetime of the Python process running Invoke. .. note:: If you're unsure whether you want this or ``asynchronous``, you probably want ``asynchronous``! Specifically, ``disown=True`` has the following behaviors: - The return value is ``None`` instead of a `Result` or subclass. - No I/O worker threads are spun up, so you will have no access to the subprocess' stdout/stderr, your stdin will not be forwarded, ``(out|err|in)_stream`` will be ignored, and features like ``watchers`` will not function. - No exit code is checked for, so you will not receive any errors if the subprocess fails to exit cleanly. - ``pty=True`` may not function correctly (subprocesses may not run at all; this seems to be a potential bug in Python's ``pty.fork``) unless your command line includes tools such as ``nohup`` or (the shell builtin) ``disown``. .. versionadded:: 1.4 :param bool dry: Whether to dry-run instead of truly invoking the given command. See :option:`--dry` (which flips this on globally) for details on this behavior. .. versionadded:: 1.3 :param bool echo: Controls whether `.run` prints the command string to local stdout prior to executing it. Default: ``False``. .. note:: ``hide=True`` will override ``echo=True`` if both are given. :param echo_format: A string, which when passed to Python's inbuilt ``.format`` method, will change the format of the output when ``run.echo`` is set to true. Currently, only ``{command}`` is supported as a parameter. Defaults to printing the full command string in ANSI-escaped bold. :param bool echo_stdin: Whether to write data from ``in_stream`` back to ``out_stream``. In other words, in normal interactive usage, this parameter controls whether Invoke mirrors what you type back to your terminal. By default (when ``None``), this behavior is triggered by the following: * Not using a pty to run the subcommand (i.e. ``pty=False``), as ptys natively echo stdin to stdout on their own; * And when the controlling terminal of Invoke itself (as per ``in_stream``) appears to be a valid terminal device or TTY. (Specifically, when `~invoke.util.isatty` yields a ``True`` result when given ``in_stream``.) .. note:: This property tends to be ``False`` when piping another program's output into an Invoke session, or when running Invoke within another program (e.g. running Invoke from itself). If both of those properties are true, echoing will occur; if either is false, no echoing will be performed. When not ``None``, this parameter will override that auto-detection and force, or disable, echoing. :param str encoding: Override auto-detection of which encoding the subprocess is using for its stdout/stderr streams (which defaults to the return value of `default_encoding`). :param err_stream: Same as ``out_stream``, except for standard error, and defaulting to ``sys.stderr``. :param dict env: By default, subprocesses receive a copy of Invoke's own environment (i.e. ``os.environ``). Supply a dict here to update that child environment. For example, ``run('command', env={'PYTHONPATH': '/some/virtual/env/maybe'})`` would modify the ``PYTHONPATH`` env var, with the rest of the child's env looking identical to the parent. .. seealso:: ``replace_env`` for changing 'update' to 'replace'. :param bool fallback: Controls auto-fallback behavior re: problems offering a pty when ``pty=True``. Whether this has any effect depends on the specific `Runner` subclass being invoked. Default: ``True``. :param hide: Allows the caller to disable ``run``'s default behavior of copying the subprocess' stdout and stderr to the controlling terminal. Specify ``hide='out'`` (or ``'stdout'``) to hide only the stdout stream, ``hide='err'`` (or ``'stderr'``) to hide only stderr, or ``hide='both'`` (or ``True``) to hide both streams. The default value is ``None``, meaning to print everything; ``False`` will also disable hiding. .. note:: Stdout and stderr are always captured and stored in the ``Result`` object, regardless of ``hide``'s value. .. note:: ``hide=True`` will also override ``echo=True`` if both are given (either as kwargs or via config/CLI). :param in_stream: A file-like stream object to used as the subprocess' standard input. If ``None`` (the default), ``sys.stdin`` will be used. If ``False``, will disable stdin mirroring entirely (though other functionality which writes to the subprocess' stdin, such as autoresponding, will still function.) Disabling stdin mirroring can help when ``sys.stdin`` is a misbehaving non-stream object, such as under test harnesses or headless command runners. :param out_stream: A file-like stream object to which the subprocess' standard output should be written. If ``None`` (the default), ``sys.stdout`` will be used. :param bool pty: By default, ``run`` connects directly to the invoked process and reads its stdout/stderr streams. Some programs will buffer (or even behave) differently in this situation compared to using an actual terminal or pseudoterminal (pty). To use a pty instead of the default behavior, specify ``pty=True``. .. warning:: Due to their nature, ptys have a single output stream, so the ability to tell stdout apart from stderr is **not possible** when ``pty=True``. As such, all output will appear on ``out_stream`` (see below) and be captured into the ``stdout`` result attribute. ``err_stream`` and ``stderr`` will always be empty when ``pty=True``. :param bool replace_env: When ``True``, causes the subprocess to receive the dictionary given to ``env`` as its entire shell environment, instead of updating a copy of ``os.environ`` (which is the default behavior). Default: ``False``. :param str shell: Which shell binary to use. Default: ``/bin/bash`` (on Unix; ``COMSPEC`` or ``cmd.exe`` on Windows.) :param timeout: Cause the runner to submit an interrupt to the subprocess and raise `.CommandTimedOut`, if the command takes longer than ``timeout`` seconds to execute. Defaults to ``None``, meaning no timeout. .. versionadded:: 1.3 :param bool warn: Whether to warn and continue, instead of raising `.UnexpectedExit`, when the executed command exits with a nonzero status. Default: ``False``. .. note:: This setting has no effect on exceptions, which will still be raised, typically bundled in `.ThreadException` objects if they were raised by the IO worker threads. Similarly, `.WatcherError` exceptions raised by `.StreamWatcher` instances will also ignore this setting, and will usually be bundled inside `.Failure` objects (in order to preserve the execution context). Ditto `.CommandTimedOut` - basically, anything that prevents a command from actually getting to "exited with an exit code" ignores this flag. :param watchers: A list of `.StreamWatcher` instances which will be used to scan the program's ``stdout`` or ``stderr`` and may write into its ``stdin`` (typically ``bytes`` objects) in response to patterns or other heuristics. See :doc:`/concepts/watchers` for details on this functionality. Default: ``[]``. :returns: `Result`, or a subclass thereof. :raises: `.UnexpectedExit`, if the command exited nonzero and ``warn`` was ``False``. :raises: `.Failure`, if the command didn't even exit cleanly, e.g. if a `.StreamWatcher` raised `.WatcherError`. :raises: `.ThreadException` (if the background I/O threads encountered exceptions other than `.WatcherError`). .. versionadded:: 1.0

Submit an interrupt signal to the running subprocess. In almost all implementations, the default behavior is what will be desired: submit ```` to the subprocess' stdin pipe. However, we leave this as a public method in case this default needs to be augmented or replaced. :param interrupt: The locally-sourced ``KeyboardInterrupt`` causing the method call. :returns: ``None``. .. versionadded:: 1.0

Determine whether data read from ``input_`` should echo to ``output``. Used by `handle_stdin`; tests attributes of ``input_`` and ``output``. :param input_: Input stream (file-like object). :param output: Output stream (file-like object). :returns: A ``bool``. .. versionadded:: 1.0

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

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

Start a timer to `kill` our subprocess after ``timeout`` seconds.

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

Block until the running command appears to have exited. :returns: ``None``. .. versionadded:: 1.0

Write ``string`` to ``stream``. Also calls ``.flush()`` on ``stream`` to ensure that real terminal streams don't buffer. :param stream: A file-like stream object, mapping to the ``out_stream`` or ``err_stream`` parameters of `run`. :param string: A Unicode string object. :returns: ``None``. .. versionadded:: 1.0

Write encoded ``data`` to the running process' stdin. :param data: A Unicode string. :returns: ``None``. .. versionadded:: 1.0