Useful non-core functionality, e.g. functions composing multiple operations.
Synchronize a remote directory with the current project directory via rsync.
upload_project()makes use of
scpto copy one’s entire project every time it is invoked,
rsynccommand-line utility, which only transfers files newer than those on the remote end.
rsync_project()is thus a simple wrapper around
rsync; for details on how
rsyncworks, please see its manpage.
rsyncmust be installed on both your local and remote systems in order for this operation to work correctly.
This function makes use of Fabric’s
local()operation, and returns the output of that function call; thus it will return the stdout, if any, of the resultant
rsync_project()uses the current Fabric connection parameters (user, host, port) by default, adding them to rsync’s ssh options (then mixing in
ssh_opts, if given – see below.)
rsync_project()takes the following parameters:
remote_dir: the only required parameter, this is the path to the directory on the remote server. Due to how
rsyncis implemented, the exact behavior depends on the value of
local_dirends with a trailing slash, the files will be dropped inside of
rsync_project("/home/username/project/", "foldername/")will drop the contents of
local_dirdoes not end with a trailing slash (and this includes the default scenario, when
local_diris not specified),
remote_diris effectively the “parent” directory, and a new directory named after
local_dirwill be created inside of it. So
rsync_project("/home/username", "foldername")would create a new directory
/home/username/foldername(if needed) and place the files there.
local_dir: by default,
rsync_projectuses your current working directory as the source directory. This may be overridden by specifying
local_dir, which is a string passed verbatim to
rsync, and thus may be a single directory (
"my_directory") or multiple directories (
"dir1 dir2"). See the
rsyncdocumentation for details.
exclude: optional, may be a single string, or an iterable of strings, and is used to pass one or more
delete: a boolean controlling whether
--deleteoption is used. If True, instructs
rsyncto remove remote files that no longer exist locally. Defaults to False.
extra_opts: an optional, arbitrary string which you may use to pass custom arguments or options to
extra_optsbut specifically for the SSH options string (rsync’s
capture: Sent directly into an inner
upload: a boolean controlling whether file synchronization is performed up or downstream. Upstream by default.
default_opts: the default rsync options
-pthrvz, override if desired (e.g. to remove verbosity, etc).
Furthermore, this function transparently honors Fabric’s port and SSH key settings. Calling this function when the current host string contains a nonstandard port, or when
env.key_filenameis non-empty, will use the specified port and/or SSH key filename(s).
For reference, the approximate
rsynccommand-line call that is constructed by this function is the following:
rsync [--delete] [--exclude exclude[, --exclude[, ...]]] \ [default_opts] [extra_opts] <local_dir> <host_string>:<remote_dir>
New in version 1.4.0: The
New in version 1.4.1: The
New in version 1.8.0: The
upload_project(local_dir=None, remote_dir='', use_sudo=False)¶
Upload the current project to a remote system via
local_dirspecifies the local project directory to upload, and defaults to the current working directory.
remote_dirspecifies the target directory to upload into (meaning that a copy of
local_dirwill appear as a subdirectory of
remote_dir) and defaults to the remote user’s home directory.
use_sudospecifies which method should be used when executing commands remotely.
sudowill be used if use_sudo is True, otherwise
runwill be used.
This function makes use of the
gzipprograms/libraries, thus it will not work too well on Win32 systems unless one is using Cygwin or something similar. It will attempt to clean up the local and remote tarfiles when it finishes executing, even in the event of a failure.
Changed in version 1.1: Added the
Changed in version 1.7: Added the