Decorators¶
Convenience decorators for use in fabfiles.
-
fabric.decorators.
hosts
(*host_list)¶ Decorator defining which host or hosts to execute the wrapped function on.
For example, the following will ensure that, barring an override on the command line,
my_func
will be run onhost1
,host2
andhost3
, and with specific users onhost1
andhost3
:@hosts('user1@host1', 'host2', 'user2@host3') def my_func(): pass
hosts
may be invoked with either an argument list (@hosts('host1')
,@hosts('host1', 'host2')
) or a single, iterable argument (@hosts(['host1', 'host2'])
).Note that this decorator actually just sets the function’s
.hosts
attribute, which is then read prior to executing the function.Changed in version 0.9.2: Allow a single, iterable argument (
@hosts(iterable)
) to be used instead of requiring@hosts(*iterable)
.
-
fabric.decorators.
parallel
(pool_size=None)¶ Forces the wrapped function to run in parallel, instead of sequentially.
This decorator takes precedence over the global value of env.parallel. It also takes precedence over
serial
if a task is decorated with both.New in version 1.3.
-
fabric.decorators.
roles
(*role_list)¶ Decorator defining a list of role names, used to look up host lists.
A role is simply defined as a key in
env
whose value is a list of one or more host connection strings. For example, the following will ensure that, barring an override on the command line,my_func
will be executed against the hosts listed in thewebserver
anddbserver
roles:env.roledefs.update({ 'webserver': ['www1', 'www2'], 'dbserver': ['db1'] }) @roles('webserver', 'dbserver') def my_func(): pass
As with
hosts
,roles
may be invoked with either an argument list or a single, iterable argument. Similarly, this decorator uses the same mechanism ashosts
and simply sets<function>.roles
.Changed in version 0.9.2: Allow a single, iterable argument to be used (same as
hosts
).
-
fabric.decorators.
runs_once
(func)¶ Decorator preventing wrapped function from running more than once.
By keeping internal state, this decorator allows you to mark a function such that it will only run once per Python interpreter session, which in typical use means “once per invocation of the
fab
program”.Any function wrapped with this decorator will silently fail to execute the 2nd, 3rd, ..., Nth time it is called, and will return the value of the original run.
Note
runs_once
does not work with parallel task execution.
-
fabric.decorators.
serial
(func)¶ Forces the wrapped function to always run sequentially, never in parallel.
This decorator takes precedence over the global value of env.parallel. However, if a task is decorated with both
serial
andparallel
,parallel
wins.New in version 1.3.
-
fabric.decorators.
task
(*args, **kwargs)¶ Decorator declaring the wrapped function to be a new-style task.
May be invoked as a simple, argument-less decorator (i.e.
@task
) or with arguments customizing its behavior (e.g.@task(alias='myalias')
).Please see the new-style task documentation for details on how to use this decorator.
Changed in version 1.2: Added the
alias
,aliases
,task_class
anddefault
keyword arguments. See Arguments for details.Changed in version 1.5: Added the
name
keyword argument.See also
-
fabric.decorators.
with_settings
(*arg_settings, **kw_settings)¶ Decorator equivalent of
fabric.context_managers.settings
.Allows you to wrap an entire function as if it was called inside a block with the
settings
context manager. This may be useful if you know you want a given setting applied to an entire function body, or wish to retrofit old code without indenting everything.For example, to turn aborts into warnings for an entire task function:
@with_settings(warn_only=True) def foo(): ...
See also
New in version 1.1.