util
¶
Helpers and decorators, primarily for internal or advanced use.
-
patchwork.util.
set_runner
(f)¶ 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 therun
method of the first positional arg, which is expected to be aContext
(or subclass). Thus the default runner isContext.run
(or, if the function was given a FabricConnection
,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: givingsudo=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
:@set_runner 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 toc.run
:function(c, "my-arg1", arg2="my-arg2")
or one may specify
sudo
to trigger use ofc.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)
Note
If more than one of the
runner_method
,sudo
orrunner
kwargs are given simultaneously, only one will win, in the following order:runner
, thenrunner_method
, thensudo
.Note
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.
- By default,