Helpers and decorators, primarily for internal or advanced use.


Set 2nd posarg of decorated function to some callable runner.

The final value of runner depends on other args given to the decorated function (note: not the decorator itself!) as follows:

  • By default, runner is set to the run method of the first positional arg, which is expected to be a Context (or subclass). Thus the default runner is Context.run (or, if the function was given a Fabric Connection, Connection.run).
  • You can override which method on the context is selected, by handing an attribute name string to runner_method.
  • Since the common case for overriding the runner is to trigger use of sudo, there is a convenient shorthand: giving sudo=True.
  • Finally, you may give a callable object to runner directly, in which case nothing special really happens (it’s largely as if you called the function undecorated, albeit with a kwarg instead of a positional argument). This is mostly useful for cases where you’re calling one decorated function from within another.

Given this function:

def function(c, runner, arg1, arg2=None):
    runner("some command based on arg1 and arg2")

one may call it without any runner-related arguments, in which case runner ends up being a reference to c.run:

function(c, "my-arg1", arg2="my-arg2")

or one may specify sudo to trigger use of c.sudo:

function(c, "my-arg1", arg2="my-arg2", sudo=True)

If one is using a custom Context subclass with other command runner methods, one may give runner_method explicitly:

class AdminContext(Context):
    def run_admin(self, *args, **kwargs):
        kwargs["user"] = "admin"
        return self.sudo(*args, **kwargs)

function(AdminContext(), "my-arg1", runner_method="run_admin")

As noted above, you can always give runner (as a kwarg) directly to avoid most special processing:

function(c, "my-arg1", runner=some_existing_runner_object)


If more than one of the runner_method, sudo or runner kwargs are given simultaneously, only one will win, in the following order: runner, then runner_method, then sudo.


As part of the signature modification, set_runner also modifies the resulting value’s docstring as follows:

  • Prepends a Sphinx autodoc compatible signature string, which is stripped out automatically on doc builds; see the Sphinx autodoc_docstring_signature setting.
  • Adds trailing :param: annotations for the extra args as well.