Context managers for use with the with statement.
When using Python 2.5, you will need to start your fabfile with from __future__ import with_statement in order to make use of the with statement (which is a regular, non __future__ feature of Python 2.6+.)
Context manager that keeps directory state when calling remote operations.
Any calls to run, sudo, get, or put within the wrapped block will implicitly have a string similar to "cd <path> && " prefixed in order to give the sense that there is actually statefulness involved.
Like the actual ‘cd’ shell builtin, cd may be called with relative paths (keep in mind that your default starting directory is your remote user’s $HOME) and may be nested as well.
Below is a “normal” attempt at using the shell ‘cd’, which doesn’t work due to how shell-less SSH connections are implemented – state is not kept between invocations of run or sudo:
run('cd /var/www') run('ls')
The above snippet will list the contents of the remote user’s $HOME instead of /var/www. With cd, however, it will work as expected:
with cd('/var/www'): run('ls') # Turns into "cd /var/www && ls"
Finally, a demonstration (see inline comments) of nesting:
with cd('/var/www'): run('ls') # cd /var/www && ls with cd('website1'): run('ls') # cd /var/www/website1 && ls
This context manager is currently implemented by appending to (and, as always, restoring afterwards) the current value of an environment variable, env.cwd. However, this implementation may change in the future, so we do not recommend manually altering env.cwd – only the behavior of cd will have any guarantee of backwards compatibility.
Space characters will be escaped automatically to make dealing with such directory names easier.
Changed in version 1.0: Applies to get and put in addition to the command-running operations.
Context manager for setting the given output groups to False.
groups must be one or more strings naming the output groups defined in output. The given groups will be set to False for the duration of the enclosed block, and restored to their previous value afterwards.
For example, to hide the “[hostname] run:” status lines, as well as preventing printout of stdout and stderr, one might use hide as follows:
def my_task(): with hide('running', 'stdout', 'stderr'): run('ls /var/www')
Context manager for updating local current working directory.
New in version 1.0.
Append the given path to the PATH used to execute any wrapped commands.
Any calls to run or sudo within the wrapped block will implicitly have a string similar to "PATH=$PATH:<path> " prepended before the given command.
You may customize the behavior of path by specifying the optional behavior keyword argument, as follows:
This context manager is currently implemented by modifying (and, as always, restoring afterwards) the current value of environment variables, env.path and env.path_behavior. However, this implementation may change in the future, so we do not recommend manually altering them directly.
New in version 1.0.
Prefix all wrapped run/sudo commands with given command plus &&.
This is nearly identical to cd, except that nested invocations append to a list of command strings instead of modifying a single string.
Most of the time, you’ll want to be using this alongside a shell script which alters shell state, such as ones which export or alter shell environment variables.
For example, one of the most common uses of this tool is with the workon command from virtualenvwrapper:
with prefix('workon myvenv'): run('./manage.py syncdb')
In the above snippet, the actual shell command run would be this:
$ workon myvenv && ./manage.py syncdb
This context manager is compatible with cd, so if your virtualenv doesn’t cd in its postactivate script, you could do the following:
with cd('/path/to/app'): with prefix('workon myvenv'): run('./manage.py syncdb') run('./manage.py loaddata myfixture')
Which would result in executions like so:
$ cd /path/to/app && workon myvenv && ./manage.py syncdb $ cd /path/to/app && workon myvenv && ./manage.py loaddata myfixture
Finally, as alluded to near the beginning, prefix may be nested if desired, e.g.:
with prefix('workon myenv'): run('ls') with prefix('source /some/script'): run('touch a_file')
$ workon myenv && ls $ workon myenv && source /some/script && touch a_file
Contrived, but hopefully illustrative.
Nest context managers and/or override env variables.
settings serves two purposes:
Most usefully, it allows temporary overriding/updating of env with any provided keyword arguments, e.g. with settings(user='foo'):. Original values, if any, will be restored once the with block closes.
- The keyword argument clean_revert has special meaning for settings itself (see below) and will be stripped out before execution.
In addition, it will use contextlib.nested to nest any given non-keyword arguments, which should be other context managers, e.g. with settings(hide('stderr'), show('stdout')):.
These behaviors may be specified at the same time if desired. An example will hopefully illustrate why this is considered useful:
def my_task(): with settings( hide('warnings', 'running', 'stdout', 'stderr'), warn_only=True ): if run('ls /etc/lsb-release'): return 'Ubuntu' elif run('ls /etc/redhat-release'): return 'RedHat'
The above task executes a run statement, but will warn instead of aborting if the ls fails, and all output – including the warning itself – is prevented from printing to the user. The end result, in this scenario, is a completely silent task that allows the caller to figure out what type of system the remote host is, without incurring the handful of output that would normally occur.
Thus, settings may be used to set any combination of environment variables in tandem with hiding (or showing) specific levels of output, or in tandem with any other piece of Fabric functionality implemented as a context manager.
If clean_revert is set to True, settings will not revert keys which are altered within the nested block, instead only reverting keys whose values remain the same as those given. More examples will make this clear; below is how settings operates normally:
# Before the block, env.parallel defaults to False, host_string to None with settings(parallel=True, host_string='myhost'): # env.parallel is True # env.host_string is 'myhost' env.host_string = 'otherhost' # env.host_string is now 'otherhost' # Outside the block: # * env.parallel is False again # * env.host_string is None again
The internal modification of env.host_string is nullified – not always desirable. That’s where clean_revert comes in:
# Before the block, env.parallel defaults to False, host_string to None with settings(parallel=True, host_string='myhost', clean_revert=True): # env.parallel is True # env.host_string is 'myhost' env.host_string = 'otherhost' # env.host_string is now 'otherhost' # Outside the block: # * env.parallel is False again # * env.host_string remains 'otherhost'
Brand new keys which did not exist in env prior to using settings are also preserved if clean_revert is active. When False, such keys are removed when the block exits.
New in version 1.4.1: The clean_revert kwarg.
Context manager for setting the given output groups to True.
groups must be one or more strings naming the output groups defined in output. The given groups will be set to True for the duration of the enclosed block, and restored to their previous value afterwards.
For example, to turn on debug output (which is typically off by default):
def my_task(): with show('debug'): run('ls /var/www')
As almost all output groups are displayed by default, show is most useful for turning on the normally-hidden debug group, or when you know or suspect that code calling your own code is trying to hide output with hide.