This documentation is for the latest stable (0.9.3) release of Fabric. To view documentation for the in-development (1.0) version, please click here.
Functions to be used in fabfiles and other non-core code, such as run()/sudo().
- fabric.operations.sudo(command, shell=True, user=None, pty=False)¶
Run a shell command on a remote host, with superuser privileges.
As with run(), sudo() executes within a shell command defaulting to the value of env.shell, although it goes one step further and wraps the command with sudo as well. Like run, this behavior may be disabled by specifying shell=False.
You may specify a user keyword argument, which is passed to sudo and allows you to run as some user other than root (which is the default). On most systems, the sudo program can take a string username or an integer userid (uid); user may likewise be a string or an int.
Some remote systems may be configured to disallow sudo access unless a terminal or pseudoterminal is being used (e.g. when Defaults requiretty exists in /etc/sudoers.) If updating the remote system’s sudoers configuration is not possible or desired, you may pass pty=True to sudo to force allocation of a pseudo tty on the remote end.
sudo("~/install_script.py") sudo("mkdir /var/www/new_docroot", user="www-data") sudo("ls /home/jdoe", user=1001) result = sudo("ls /tmp/")
Changed in version 0.9.3: Added stderr and succeeded attributes to the return value.
- fabric.operations.put(local_path, remote_path, mode=None)¶
Upload one or more files to a remote host.
local_path may be a relative or absolute local file path, and may contain shell-style wildcards, as understood by the Python glob module. Tilde expansion (as implemented by os.path.expanduser) is also performed.
remote_path may also be a relative or absolute location, but applied to the remote host. Relative paths are relative to the remote user’s home directory, but tilde expansion (e.g. ~/.ssh/) will also be performed if necessary.
By default, put preserves file modes when uploading. However, you can also set the mode explicitly by specifying the mode keyword argument, which sets the numeric mode of the remote file. See the os.chmod documentation or man chmod for the format of this argument.
put('bin/project.zip', '/tmp/project.zip') put('*.py', 'cgi-bin/') put('index.html', 'index.html', mode=0755)
- fabric.operations.run(command, shell=True, pty=False)¶
Run a shell command on a remote host.
If shell is True (the default), run() will execute the given command string via a shell interpreter, the value of which may be controlled by setting env.shell (defaulting to something similar to /bin/bash -l -c "<command>".) Any double-quote (") characters in command will be automatically escaped when shell is True.
run will return the result of the remote program’s stdout as a single (likely multiline) string. This string will exhibit failed and succeeded boolean attributes specifying whether the command failed or succeeded, and will also include the return code as the return_code attribute. It will also have a stderr attribute containing the remote standard error, if any.
You may pass pty=True to force allocation of a pseudo tty on the remote end. This is not normally required, but some programs may complain (or, even more rarely, refuse to run) if a tty is not present.
run("ls /var/www/") run("ls /home/myuser", shell=False) output = run('ls /var/www/site1')
Changed in version 0.9.3: Added stderr and succeeded attributes to the return value.
- fabric.operations.get(remote_path, local_path)¶
Download a file from a remote host.
remote_path should point to a specific file, while local_path may be a directory (in which case the remote filename is preserved) or something else (in which case the downloaded file is renamed). Tilde expansion is performed on both ends.
For example, get('~/info.txt', '/tmp/') will create a new file, /tmp/info.txt, because /tmp is a directory. However, a call such as get('~/info.txt', '/tmp/my_info.txt') would result in a new file named /tmp/my_info.txt, as that path didn’t exist (and thus wasn’t a directory.)
If local_path names a file that already exists locally, that file will be overwritten without complaint.
Finally, if get detects that it will be run on more than one host, it will suffix the current host string to the local filename, to avoid clobbering when it is run multiple times.
For example, the following snippet will produce two files on your local system, called server.log.host1 and server.log.host2 respectively:
@hosts('host1', 'host2') def my_download_task(): get('/var/log/server.log', 'server.log')
However, with a single host (e.g. @hosts('host1')), no suffixing is performed, leaving you with a single, pristine server.log.
- fabric.operations.local(command, capture=True)¶
Run a command on the local system.
local is simply a convenience wrapper around the use of the builtin Python subprocess module with shell=True activated. If you need to do anything special, consider using the subprocess module directly.
local will, by default, capture and return the contents of the command’s stdout as a string, and will not print anything to the user (the command’s stderr is captured but discarded).
This differs from the default behavior of run and sudo due to the different mechanisms involved: it is difficult to simultaneously capture and print local commands, so we have to choose one or the other. We hope to address this in later releases.
local‘s return value, like that of run, exhibits the attributes succeeded/failed (booleans), stderr (string) and return_code (integer). Please see run‘s API docs for details, and remember that this return value is only set when capture=True, as above.
If you need full interactivity with the command being run (and are willing to accept the loss of captured stdout) you may specify capture=False so that the subprocess’ stdout and stderr pipes are connected to your terminal instead of captured by Fabric.
When capture is False, global output controls (output.stdout and output.stderr will be used to determine what is printed and what is discarded.
Changed in version 0.9.3: Added the succeeded and stderr return code attributes.
- fabric.operations.prompt(text, key=None, default='', validate=None)¶
Prompt user with text and return the input (like raw_input).
A single space character will be appended for convenience, but nothing else. Thus, you may want to end your prompt text with a question mark or a colon, e.g. prompt("What hostname?").
If key is given, the user’s input will be stored as env.<key> in addition to being returned by prompt. If the key already existed in env, its value will be overwritten and a warning printed to the user.
If default is given, it is displayed in square brackets and used if the user enters nothing (i.e. presses Enter without entering any text). default defaults to the empty string. If non-empty, a space will be appended, so that a call such as prompt("What hostname?", default="foo") would result in a prompt of What hostname? [foo] (with a trailing space after the [foo].)
The optional keyword argument validate may be a callable or a string:
- If a callable, it is called with the user’s input, and should return the value to be stored on success. On failure, it should raise an exception with an exception message, which will be printed to the user.
- If a string, the value passed to validate is used as a regular expression. It is thus recommended to use raw strings in this case. Note that the regular expression, if it is not fully matching (bounded by ^ and $) it will be made so. In other words, the input must fully match the regex.
Either way, prompt will re-prompt until validation passes (or the user hits Ctrl-C).
# Simplest form: environment = prompt('Please specify target environment: ') # With default, and storing as env.dish: prompt('Specify favorite dish: ', 'dish', default='spam & eggs') # With validation, i.e. requiring integer input: prompt('Please specify process nice level: ', key='nice', validate=int) # With validation against a regular expression: release = prompt('Please supply a release name', validate=r'^\w+-\d+(\.\d+)?$')
Reboot the remote system, disconnect, and wait for wait seconds.
New in version 0.9.2.
- fabric.operations.require(*keys, **kwargs)¶
Check for given keys in the shared environment dict and abort if not found.
Positional arguments should be strings signifying what env vars should be checked for. If any of the given arguments do not exist, Fabric will abort execution and print the names of the missing keys.
The optional keyword argument used_for may be a string, which will be printed in the error output to inform users why this requirement is in place. used_for is printed as part of a string similar to:
"Th(is|ese) variable(s) (are|is) used for %s"
so format it appropriately.
The optional keyword argument provided_by may be a list of functions or function names which the user should be able to execute in order to set the key or keys; it will be included in the error output if requirements are not met.
Note: it is assumed that the keyword arguments apply to all given keys as a group. If you feel the need to specify more than one used_for, for example, you should break your logic into multiple calls to require().