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)

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.

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.

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

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 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'.)

fabric.contrib.files.contains(filename, text, exact=False, use_sudo=False, escape=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 the usual outer env.shell wrapper that most commands execute with.

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.)

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.

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.

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 which is passed to exists.

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

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>".

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.

sed will pass shell=False to run/sudo, in order to avoid problems with many nested levels of quotes and backslashes.

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.

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

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 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.)

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)

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

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 and mode kwargs are passed directly to an internal put call; please see its documentation for details on these two options.

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

Previous topic

Django Integration

Next topic

Project Tools

This Page