context

class invoke.context.Context(config=None)

Context-aware API wrapper & state-passing object.

Context objects are created during command-line parsing (or, if desired, by hand) and used to share parser and configuration state with executed tasks (see State handling: the context).

Specifically, the class offers wrappers for core API calls (such as run) which take into account CLI parser flags, configuration files, and/or changes made at runtime. It also acts as a proxy for its config attribute - see that attribute’s documentation for details.

Instances of Context may be shared between tasks when executing sub-tasks - either the same context the caller was given, or an altered copy thereof (or, theoretically, a brand new one).

__init__(config=None)
Parameters:config

Config object to use as the base configuration.

Defaults to an anonymous/default Config instance.

config

The fully merged Config object appropriate for this context.

Config settings (see their documentation for details) may be accessed like dictionary keys (ctx.config['foo']) or object attributes (ctx.config.foo).

As a convenience shorthand, the Context object proxies to its config attribute in the same way - e.g. ctx['foo'] or ctx.foo returns the same value as ctx.config['foo'].

run(command, **kwargs)

Execute a local shell command, honoring config options.

Specifically, this method instantiates a Runner subclass (according to the runner config option; default is Local) and calls its .run method with command and kwargs.

See Runner.run for details on command and the available keyword arguments.

sudo(command, **kwargs)

Execute a shell command, via sudo.

In general, this method is identical to run, but adds a handful of convenient behaviors around invoking the sudo program. It doesn’t do anything users could not do themselves by wrapping run, but the use case is too common to make users reinvent these wheels themselves.

Specifically, sudo:

  • Places a FailingResponder into the watchers kwarg (see Automatically responding to program output) which:

    • searches for the configured sudo password prompt;
    • responds with the configured sudo password (sudo.password from the configuration, or a runtime getpass input);
    • can tell when that response causes an authentication failure, and raises an exception if so.
  • Builds a sudo command string using the supplied command argument prefixed by the sudo.prefix configuration setting;

  • Executes that command via a call to run, returning the result.

As with run, these additional behaviors may be configured both via the run tree of configuration settings (like run.echo) or via keyword arguments, which will override the configuration system.

Parameters:
  • password (str) – Runtime override for sudo.password.
  • prefix (str) – Runtime override for sudo.prefix.
class invoke.context.MockContext(config=None, **kwargs)

A Context whose methods’ return values can be predetermined.

Primarily useful for testing Invoke-using codebases.

Note

Methods not given Results to yield will raise NotImplementedError if called (since the alternative is to call the real underlying method - typically undesirable when mocking.)

__init__(config=None, **kwargs)

Create a Context-like object whose methods yield Result objects.

Parameters:
  • config – A Configuration object to use. Identical in behavior to Context.
  • run

    A data structure of Results, to return from calls to the instantiated object’s run method (instead of actually executing the requested shell command).

    Specifically, this method accepts:

    • A single Result object, which will be returned once.
    • An iterable of Results, which will be returned on each subsequent call to .run.
    • A map of command strings to either of the above, allowing specific call-and-response semantics instead of assuming a call order.
  • sudo – Identical to run, but whose values are yielded from calls to sudo.
Raises:

TypeError, if the values given to run or other kwargs aren’t individual Result objects or iterables.