Functions to be used in fabfiles and other non-core code, such as run()/sudo().
Download one or more files from a remote host.
get returns an iterable containing the absolute paths to all local files downloaded, which will be empty if local_path was a StringIO object (see below for more on using StringIO). This object will also exhibit a .failed attribute containing any remote file paths which failed to download, and a .succeeded attribute equivalent to not .failed.
remote_path is the remote file or directory path to download, which may contain shell glob syntax, e.g. "/var/log/apache2/*.log", and will have tildes replaced by the remote home directory. Relative paths will be considered relative to the remote user’s home directory, or the current remote working directory as manipulated by cd. If the remote path points to a directory, that directory will be downloaded recursively.
local_path is the local file path where the downloaded file or files will be stored. If relative, it will honor the local current working directory as manipulated by lcd. It may be interpolated, using standard Python dict-based interpolation, with the following variables:
Note
When remote_path is an absolute directory path, only the inner directories will be recreated locally and passed into the above variables. So for example, get('/var/log', '%(path)s') would start writing out files like apache2/access.log, postgresql/8.4/postgresql.log, etc, in the local working directory. It would not write out e.g. var/log/apache2/access.log.
Additionally, when downloading a single file, %(dirname)s and %(path)s do not make as much sense and will be empty and equivalent to %(basename)s, respectively. Thus a call like get('/var/log/apache2/access.log', '%(path)s') will save a local file named access.log, not var/log/apache2/access.log.
This behavior is intended to be consistent with the command-line scp program.
If left blank, local_path defaults to "%(host)s/%(path)s" in order to be safe for multi-host invocations.
Warning
If your local_path argument does not contain %(host)s and your get call runs against multiple hosts, your local files will be overwritten on each successive run!
If local_path does not make use of the above variables (i.e. if it is a simple, explicit file path) it will act similar to scp or cp, overwriting pre-existing files if necessary, downloading into a directory if given (e.g. get('/path/to/remote_file.txt', 'local_directory') will create local_directory/remote_file.txt) and so forth.
local_path may alternately be a file-like object, such as the result of open('path', 'w') or a StringIO instance.
Note
Attempting to get a directory into a file-like object is not valid and will result in an error.
Note
This function will use seek and tell to overwrite the entire contents of the file-like object, in order to be consistent with the behavior of put (which also considers the entire file). However, unlike put, the file pointer will not be restored to its previous location, as that doesn’t make as much sense here and/or may not even be possible.
Note
Due to how our SSH layer works, a temporary file will still be written to your hard disk even if you specify a file-like object such as a StringIO for the local_path argument. Cleanup is performed, however – we just note this for users expecting straight-to-memory transfers. (We hope to patch our SSH layer in the future to enable true straight-to-memory downloads.)
Changed in version 1.0: Now honors the remote working directory as manipulated by cd, and the local working directory as manipulated by lcd.
Changed in version 1.0: Now allows file-like objects in the local_path argument.
Changed in version 1.0: local_path may now contain interpolated path- and host-related variables.
Changed in version 1.0: Directories may be specified in the remote_path argument and will trigger recursive downloads.
Changed in version 1.0: Return value is now an iterable of downloaded local file paths, which also exhibits the .failed and .succeeded attributes.
Invoke a fully interactive shell on the remote end.
If command is given, it will be sent down the pipe before handing control over to the invoking user.
This function is most useful for when you need to interact with a heavily shell-based command or series of commands, such as when debugging or when fully interactive recovery is required upon remote program failure.
It should be considered an easy way to work an interactive shell session into the middle of a Fabric script and is not a drop-in replacement for run, which is also capable of interacting with the remote end (albeit only while its given command is executing) and has much stronger programmatic abilities such as error handling and stdout/stderr capture.
Specifically, open_shell provides a better interactive experience than run, but use of a full remote shell prevents Fabric from determining whether programs run within the shell have failed, and pollutes the stdout/stderr stream with shell output such as login banners, prompts and echoed stdin.
Thus, this function does not have a return value and will not trigger Fabric’s failure handling if any remote programs result in errors.
New in version 1.0.
Upload one or more files to a remote host.
put returns an iterable containing the absolute file paths of all remote files uploaded. This iterable also exhibits a .failed attribute containing any local file paths which failed to upload (and may thus be used as a boolean test.) You may also check .succeeded which is equivalent to not .failed.
local_path may be a relative or absolute local file or directory 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.
local_path may alternately be a file-like object, such as the result of open('path') or a StringIO instance.
Note
In this case, put will attempt to read the entire contents of the file-like object by rewinding it using seek (and will use tell afterwards to preserve the previous file position).
Note
Use of a file-like object in put‘s local_path argument will cause a temporary file to be utilized due to limitations in our SSH layer’s API.
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.
An empty string, in either path argument, will be replaced by the appropriate end’s current working directory.
While the SFTP protocol (which put uses) has no direct ability to upload files to locations not owned by the connecting user, you may specify use_sudo=True to work around this. When set, this setting causes put to upload the local files to a temporary location on the remote end, and then use sudo to move them to remote_path.
In some use cases, it is desirable to force a newly uploaded file to match the mode of its local counterpart (such as when uploading executable scripts). To do this, specify mirror_local_mode=True.
Alternately, you may use the mode kwarg to specify an exact mode, in the same vein as os.chmod or the Unix chmod command.
put will honor cd, so relative values in remote_path will be prepended by the current remote working directory, if applicable. Thus, for example, the below snippet would attempt to upload to /tmp/files/test.txt instead of ~/files/test.txt:
with cd('/tmp'):
put('/path/to/local/test.txt', 'files')
Use of lcd will affect local_path in the same manner.
Examples:
put('bin/project.zip', '/tmp/project.zip')
put('*.py', 'cgi-bin/')
put('index.html', 'index.html', mode=0755)
Changed in version 1.0: Now honors the remote working directory as manipulated by cd, and the local working directory as manipulated by lcd.
Changed in version 1.0: Now allows file-like objects in the local_path argument.
Changed in version 1.0: Directories may be specified in the local_path argument and will trigger recursive uploads.
Changed in version 1.0: Return value is now an iterable of uploaded remote file paths which also exhibits the .failed and .succeeded attributes.
Reboot the remote system, disconnect, and wait for wait seconds.
After calling this operation, further execution of run or sudo will result in a normal reconnection to the server, including any password prompts.
New in version 0.9.2.
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 (") or dollar-sign ($) 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.
Any text entered in your local terminal will be forwarded to the remote program as it runs, thus allowing you to interact with password or other prompts naturally. For more on how this works, see Interaction with remote programs.
You may pass pty=False to forego creation of a pseudo-terminal on the remote end in case the presence of one causes problems for the command in question. However, this will force Fabric itself to echo any and all input you type while the command is running, including sensitive passwords. (With pty=True, the remote pseudo-terminal will echo for you, and will intelligently handle password-style prompts.) See Pseudo-terminals for details.
Similarly, if you need to programmatically examine the stderr stream of the remote program (exhibited as the stderr attribute on this function’s return value), you may set combine_stderr=False. Doing so has a high chance of causing garbled output to appear on your terminal (though the resulting strings returned by run will be properly separated). For more info, please read Combining stdout and stderr.
Examples:
run("ls /var/www/")
run("ls /home/myuser", shell=False)
output = run('ls /var/www/site1')
New in version 1.0: The succeeded and stderr return value attributes, the combine_stderr kwarg, and interactive behavior.
Changed in version 1.0: The default value of pty is now True.
Changed in version 1.0.2: The default value of combine_stderr is now None instead of True. However, the default behavior is unchanged, as the global setting is still True.
Run a shell command on a remote host, with superuser privileges.
sudo is identical in every way to run, except that it will always wrap the given command in a call to the sudo program to provide superuser privileges.
sudo accepts an additional user argument, which is passed to sudo and allows you to run as some user other than root. 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.
Examples:
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 1.0: See the changed and added notes for run.
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 is not currently capable of simultaneously printing and capturing output, as run/sudo do. The capture kwarg allows you to switch between printing and capturing as necessary, and defaults to False.
When capture=False, the local subprocess’ stdout and stderr streams are hooked up directly to your terminal, though you may use the global output controls output.stdout and output.stderr to hide one or both if desired. In this mode, local returns None.
When capture=True, this function will return the contents of the command’s stdout as a string-like object; as with run and sudo, this return value exhibits the return_code, stderr, failed and succeeded attributes. See run for details.
local will honor the lcd context manager, allowing you to control its current working directory independently of the remote end (which honors cd).
Changed in version 1.0: Added the succeeded and stderr attributes.
Changed in version 1.0: Now honors the lcd context manager.
Changed in version 1.0: Changed the default value of capture from True to False.
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:
Either way, prompt will re-prompt until validation passes (or the user hits Ctrl-C).
Note
prompt honors env.abort_on_prompts and will call abort instead of prompting if that flag is set to True. If you want to block on user input regardless, try wrapping with settings.
Examples:
# 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+)?$')
# Prompt regardless of the global abort-on-prompts setting:
with settings(abort_on_prompts=False):
prompt('I seriously need an answer on this! ')
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 or a single function or function name 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().
Changed in version 1.1: Allow iterable provided_by values instead of just single values.