File and Directory Management

Module providing easy API for working with remote files and folders.

fabric.contrib.files.append(filename, text, use_sudo=False, partial=False, escape=True, shell=False)

Append string (or list of strings) text to filename.

When a list is given, each string inside is handled independently (but in the order given.)

If text is already found in filename, the append is not run, and None is returned immediately. Otherwise, the given text is appended to the end of the given filename via e.g. echo '$text' >> $filename.

The test for whether text already exists defaults to a full line match, e.g. ^<text>$, as this seems to be the most sensible approach for the “append lines to a file” use case. You may override this and force partial searching (e.g. ^<text>) by specifying partial=True.

Because text is single-quoted, single quotes will be transparently backslash-escaped. This can be disabled with escape=False.

If use_sudo is True, will use sudo instead of run.

The shell argument will be eventually passed to run/sudo. See description of the same argumnet in ~fabric.contrib.sed for details.

Changed in version 0.9.1: Added the partial keyword argument.

Changed in version 1.0: Swapped the order of the filename and text arguments to be consistent with other functions in this module.

Changed in version 1.0: Changed default value of partial kwarg to be False.

Changed in version 1.4: Updated the regular expression related escaping to try and solve various corner cases.

New in version 1.6: Added the shell keyword argument.

fabric.contrib.files.comment(filename, regex, use_sudo=False, char='#', backup='.bak', shell=False)

Attempt to comment out all lines in filename matching regex.

The default commenting character is # and may be overridden by the char argument.

This function uses the sed function, and will accept the same use_sudo, shell and backup keyword arguments that sed does.

comment will prepend the comment character to the beginning of the line, so that lines end up looking like so:

this line is uncommented
#this line is commented
#   this line is indented and commented

In other words, comment characters will not “follow” indentation as they sometimes do when inserted by hand. Neither will they have a trailing space unless you specify e.g. char='# '.

Note

In order to preserve the line being commented out, this function will wrap your regex argument in parentheses, so you don’t need to. It will ensure that any preceding/trailing ^ or $ characters are correctly moved outside the parentheses. For example, calling comment(filename, r'^foo$') will result in a sed call with the “before” regex of r'^(foo)$' (and the “after” regex, naturally, of r'#\1'.)

New in version 1.5: Added the shell keyword argument.

fabric.contrib.files.contains(filename, text, exact=False, use_sudo=False, escape=True, shell=False, case_sensitive=True)

Return True if filename contains text (which may be a regex.)

By default, this function will consider a partial line match (i.e. where text only makes up part of the line it’s on). Specify exact=True to change this behavior so that only a line containing exactly text results in a True return value.

This function leverages egrep on the remote end (so it may not follow Python regular expression syntax perfectly), and skips env.shell wrapper by default.

If use_sudo is True, will use sudo instead of run.

If escape is False, no extra regular expression related escaping is performed (this includes overriding exact so that no ^/$ is added.)

The shell argument will be eventually passed to run/sudo. See description of the same argument in ~fabric.contrib.sed for details.

If case_sensitive is False, the -i flag will be passed to egrep.

Changed in version 1.0: Swapped the order of the filename and text arguments to be consistent with other functions in this module.

Changed in version 1.4: Updated the regular expression related escaping to try and solve various corner cases.

Changed in version 1.4: Added escape keyword argument.

New in version 1.6: Added the shell keyword argument.

New in version 1.11: Added the case_sensitive keyword argument.

fabric.contrib.files.exists(path, use_sudo=False, verbose=False)

Return True if given path exists on the current remote host.

If use_sudo is True, will use sudo instead of run.

exists will, by default, hide all output (including the run line, stdout, stderr and any warning resulting from the file not existing) in order to avoid cluttering output. You may specify verbose=True to change this behavior.

Changed in version 1.13: Replaced internal use of test -e with stat for improved remote cross-platform (e.g. Windows) compatibility.

fabric.contrib.files.first(*args, **kwargs)

Given one or more file paths, returns first one found, or None if none exist. May specify use_sudo and verbose which are passed to exists.

Return True if the given path is a symlink on the current remote host.

If use_sudo is True, will use sudo instead of run.

is_link will, by default, hide all output. Give verbose=True to change this.

fabric.contrib.files.is_win()

Return True if remote SSH server is running Windows, False otherwise.

The idea is based on echoing quoted text: *NIX systems will echo quoted text only, while Windows echoes quotation marks as well.

fabric.contrib.files.sed(filename, before, after, limit='', use_sudo=False, backup='.bak', flags='', shell=False)

Run a search-and-replace on filename with given regex patterns.

Equivalent to sed -i<backup> -r -e "/<limit>/ s/<before>/<after>/<flags>g" <filename>. Setting backup to an empty string will, disable backup file creation.

For convenience, before and after will automatically escape forward slashes, single quotes and parentheses for you, so you don’t need to specify e.g. http:\/\/foo\.com, instead just using http://foo\.com is fine.

If use_sudo is True, will use sudo instead of run.

The shell argument will be eventually passed to run/sudo. It defaults to False in order to avoid problems with many nested levels of quotes and backslashes. However, setting it to True may help when using ~fabric.operations.cd to wrap explicit or implicit sudo calls. (cd by it’s nature is a shell built-in, not a standalone command, so it should be called within a shell.)

Other options may be specified with sed-compatible regex flags – for example, to make the search and replace case insensitive, specify flags="i". The g flag is always specified regardless, so you do not need to remember to include it when overriding this parameter.

New in version 1.1: The flags parameter.

New in version 1.6: Added the shell keyword argument.

fabric.contrib.files.uncomment(filename, regex, use_sudo=False, char='#', backup='.bak', shell=False)

Attempt to uncomment all lines in filename matching regex.

The default comment delimiter is # and may be overridden by the char argument.

This function uses the sed function, and will accept the same use_sudo, shell and backup keyword arguments that sed does.

uncomment will remove a single whitespace character following the comment character, if it exists, but will preserve all preceding whitespace. For example, # foo would become foo (the single space is stripped) but `` # foo`` would become `` foo`` (the single space is still stripped, but the preceding 4 spaces are not.)

Changed in version 1.6: Added the shell keyword argument.

fabric.contrib.files.upload_template(filename, destination, context=None, use_jinja=False, template_dir=None, use_sudo=False, backup=True, mirror_local_mode=False, mode=None, pty=None, keep_trailing_newline=False, temp_dir='')

Render and upload a template text file to a remote host.

Returns the result of the inner call to put – see its documentation for details.

filename should be the path to a text file, which may contain Python string interpolation formatting and will be rendered with the given context dictionary context (if given.)

Alternately, if use_jinja is set to True and you have the Jinja2 templating library available, Jinja will be used to render the template instead. Templates will be loaded from the invoking user’s current working directory by default, or from template_dir if given.

The resulting rendered file will be uploaded to the remote file path destination. If the destination file already exists, it will be renamed with a .bak extension unless backup=False is specified.

By default, the file will be copied to destination as the logged-in user; specify use_sudo=True to use sudo instead.

The mirror_local_mode, mode, and temp_dir kwargs are passed directly to an internal put call; please see its documentation for details on these two options.

The pty kwarg will be passed verbatim to any internal run/sudo calls, such as those used for testing directory-ness, making backups, etc.

The keep_trailing_newline kwarg will be passed when creating Jinja2 Environment which is False by default, same as Jinja2’s behaviour.

Changed in version 1.1: Added the backup, mirror_local_mode and mode kwargs.

Changed in version 1.9: Added the pty kwarg.

Changed in version 1.11: Added the keep_trailing_newline kwarg.

Changed in version 1.11: Added the temp_dir kwarg.