Fabric¶

Environment as configuration¶

Most of Fabric’s behavior is controllable by modifying env variables, such as env.hosts (as seen in the tutorial). Other commonly-modified env vars include:

• user: Fabric defaults to your local username when making SSH connections, but you can use env.user to override this if necessary. The Execution model documentation also has info on how to specify usernames on a per-host basis.
• password: Used to explicitly set your connection or sudo password if desired. Fabric will prompt you when necessary if this isn’t set or doesn’t appear to be valid.
• warn_only: a Boolean setting determining whether Fabric exits when detecting errors on the remote end. See Execution model for more on this behavior.

There are a number of other env variables; for the full list, see Full list of env vars at the bottom of this document.

from fabric.api import settings, run

def exists(path):
    with settings(warn_only=True):
        return run('test -e %s' % path)

Environment as shared state¶

As mentioned, the env object is simply a dictionary subclass, so your own fabfile code may store information in it as well. This is sometimes useful for keeping state between multiple tasks within a single execution run.

Other considerations¶

While it subclasses dict, Fabric’s env has been modified so that its values may be read/written by way of attribute access, as seen in some of the above material. In other words, env.host_string and env['host_string'] are functionally identical. We feel that attribute access can often save a bit of typing and makes the code more readable, so it’s the recommended way to interact with env.

The fact that it’s a dictionary can be useful in other ways, such as with Python’s dict-based string interpolation, which is especially handy if you need to insert multiple env vars into a single string. Using “normal” string interpolation might look like this:

print("Executing on %s as %s" % (env.host, env.user))

Using dict-style interpolation is more readable and slightly shorter:

print("Executing on %(host)s as %(user)s" % env)

Full list of env vars¶

Below is a list of all predefined (or defined by Fabric itself during execution) environment variables. While any of them may be manipulated directly, it’s often best to use context_managers, either generally via settings or via specific context managers such as cd.

Note that many of these may be set via fab‘s command-line switches – see fab options and arguments for details. Cross-links will be provided where appropriate.

from fabric.api import env, run

env.user = 'implicit_user'
env.hosts = ['host1', 'explicit_user@host2', 'host3']

def print_user():
    with hide('running'):
        run('echo "%(user)s"' % env)

$ fab print_user

[host1] out: implicit_user
[explicit_user@host2] out: explicit_user
[host3] out: implicit_user

Done.
Disconnecting from host1... done.
Disconnecting from host2... done.
Disconnecting from host3... done.

Execution strategy¶

Fabric currently provides a single, serial execution method, though more options are planned for the future:

• A list of tasks is created. Currently this list is simply the arguments given to fab, preserving the order given.
• For each task, a task-specific host list is generated from various sources (see How host lists are constructed below for details.)
• The task list is walked through in order, and each task is run once per host in its host list.
• Tasks with no hosts in their host list are considered local-only, and will always run once and only once.

Thus, given the following fabfile:

from fabric.api import run, env

env.hosts = ['host1', 'host2']

def taskA():
    run('ls')

def taskB():
    run('whoami')

and the following invocation:

$ fab taskA taskB

you will see that Fabric performs the following:

• taskA executed on host1
• taskA executed on host2
• taskB executed on host1
• taskB executed on host2

While this approach is simplistic, it allows for a straightforward composition of task functions, and (unlike tools which push the multi-host functionality down to the individual function calls) enables shell script-like logic where you may introspect the output or return code of a given command and decide what to do next.

Defining tasks¶

When looking for tasks to execute, Fabric imports your fabfile and will consider any callable object, except for the following:

• Callables whose name starts with an underscore (_). In other words, Python’s usual “private” convention holds true here.
• Callables defined within Fabric itself. Fabric’s own functions such as run and sudo will not show up in your task list.

from urllib import urlopen

from fabric.api import run

def webservice_read():
    objects = urlopen('http://my/web/service/?foo=bar').read().split()
    print(objects)

$ fab --list
Available commands:

  my_task    List some directories.
  urlopen    urlopen(url [, data]) -> open file-like object

import urllib

from fabric.api import run

def webservice_read():
    objects = urllib.urlopen('http://my/web/service/?foo=bar').read().split()
    print(objects)

Defining host lists¶

Unless you’re using Fabric as a simple build system (which is possible, but not the primary use-case) having tasks won’t do you any good without the ability to specify remote hosts on which to execute them. There are a number of ways to do so, with scopes varying from global to per-task, and it’s possible mix and match as needed.

from fabric.api import env

env.roledefs['webservers'] = ['www1', 'www2', 'www3']

from fabric.api import env

env.roledefs = {
    'web': ['www1', 'www2', 'www3'],
    'dns': ['ns1', 'ns2']
}

from fabric.api import env, run

env.hosts = ['host1', 'host2']

def mytask():
    run('ls /var/www')

from fabric.api import env, run

def set_hosts():
    env.hosts = ['host1', 'host2']

def mytask():
    run('ls /var/www')

$ fab -H host1,host2 mytask

from fabric.api import env, run

env.hosts.extend(['host3', 'host4'])

def mytask():
    run('ls /var/www')

from fabric.api import run

def mytask():
    run('ls /var/www')

$ fab mytask:hosts="host1;host2"

from fabric.api import hosts, run

@hosts('host1', 'host2')
def mytask():
    run('ls /var/www')

from fabric.api import env, hosts, roles, run

env.roledefs = {'role1': ['b', 'c']}

@hosts('a', 'b')
@roles('role1')
def mytask():
    run('ls /var/www')

Failure handling¶

Once the task list has been constructed, Fabric will start executing them as outlined in Execution strategy, until all tasks have been run on the entirety of their host lists. However, Fabric defaults to a “fail-fast” behavior pattern: if anything goes wrong, such as a remote program returning a nonzero return value or your fabfile’s Python code encountering an exception, execution will halt immediately.

This is typically the desired behavior, but there are many exceptions to the rule, so Fabric provides env.warn_only, a Boolean setting. It defaults to False, meaning an error condition will result in the program aborting immediately. However, if env.warn_only is set to True at the time of failure – with, say, the settings context manager – Fabric will emit a warning message but continue executing.

Connections¶

fab itself doesn’t actually make any connections to remote hosts. Instead, it simply ensures that for each distinct run of a task on one of its hosts, the env var env.host_string is set to the right value. Users wanting to leverage Fabric as a library may do so manually to achieve similar effects.

env.host_string is (as the name implies) the “current” host string, and is what Fabric uses to determine what connections to make (or re-use) when network-aware functions are run. Operations like run or put use env.host_string as a lookup key in a shared dictionary which maps host strings to SSH connection objects.

from fabric.api import *

@hosts('host1')
def clean_and_upload():
    local('find assets/ -name "*.DS_Store" -exec rm '{}' \;')
    local('tar czf /tmp/assets.tgz assets/')
    put('/tmp/assets.tgz', '/tmp/assets.tgz')
    with cd('/var/www/myapp/'):
        run('tar xzf /tmp/assets.tgz')

Basic use¶

In its most simple form, fab may be called with no options at all, and with one or more arguments, which should be task names, e.g.:

$ fab task1 task2

As detailed in Overview and Tutorial and Execution model, this will run task1 followed by task2, assuming that Fabric was able to find a fabfile nearby containing Python functions with those names.

However, it’s possible to expand this simple usage into something more flexible, by using the provided options and/or passing arguments to individual tasks.

Command-line options¶

A quick overview of all possible command line options can be found via fab --help. If you’re looking for details on a specific option, we go into detail below.

-h, --help¶

Displays a standard help message, with all possible options and a brief overview of what they do, then exits.

-V, --version¶

Displays Fabric’s version number, then exits.

-l, --list¶

Imports a fabfile as normal, but then prints a list of all discovered tasks and exits. Will also print the first line of each task’s docstring, if it has one, next to it (truncating if necessary.)

-d COMMAND, --display=COMMAND¶

Prints the entire docstring for the given task, if there is one. Does not currently print out the task’s function signature, so descriptive docstrings are a good idea. (They’re always a good idea, of course – just moreso here.)

-r, --reject-unknown-hosts¶

Sets env.reject_unknown_hosts to True, causing Fabric to abort when connecting to hosts not found in the user’s SSH known_hosts file.

-D, --disable-known-hosts¶

Sets env.disable_known_hosts to True, preventing Fabric from loading the user’s SSH known_hosts file.

-u USER, --user=USER¶

Sets env.user to the given string; it will then be used as the default username when making SSH connections.

-p PASSWORD, --password=PASSWORD¶

Sets env.password to the given string; it will then be used as the default password when making SSH connections or calling the sudo program.

-H HOSTS, --hosts=HOSTS¶

Sets env.hosts to the given comma-delimited list of host strings.

-R ROLES, --roles=ROLES¶

Sets env.roles to the given comma-separated list of role names.

-i KEY_FILENAME¶

When set to a file path, will load the given file as an SSH identity file (usually a private key.) This option may be repeated multiple times.

-f FABFILE, --fabfile=FABFILE¶

The fabfile name pattern to search for (defaults to fabfile.py), or alternately an explicit file path to load as the fabfile (e.g. /path/to/my/fabfile.py.)

-w, --warn-only¶

Sets env.warn_only to True, causing Fabric to continue execution even when commands encounter error conditions.

-s SHELL, --shell=SHELL¶

Sets env.shell to the given string, overriding the default shell wrapper used to execute remote commands.

-c RCFILE, --config=RCFILE¶

Sets env.rcfile to the given file path, which Fabric will try to load on startup and use to update environment variables.

--hide=LEVELS¶

A comma-separated list of output levels to hide by default.

--show=LEVELS¶

A comma-separated list of output levels to show by default.

Per-task arguments¶

The options given in Command-line options apply to the invocation of fab as a whole; even if the order is mixed around, options still apply to all given tasks equally. Additionally, since tasks are just Python functions, it’s often desirable to pass in arguments to them at runtime.

Answering both these needs is the concept of “per-task arguments”, which is a special syntax you can tack onto the end of any task name:

• Use a colon (:) to separate the task name from its arguments;
• Use commas (,) to separate arguments from one another;
• Use equals signs (=) for keyword arguments, or omit them for positional arguments;

Additionally, since this process involves string parsing, all values will end up as Python strings, so plan accordingly. (We hope to improve upon this in future versions of Fabric, provided an intuitive syntax can be found.)

For example, a “create a new user” task might be defined like so (omitting the actual logic for brevity):

def new_user(username, admin='no'):
    pass

You can specify just the username:

$ fab new_user:myusername

Or treat it as an explicit keyword argument:

$ fab new_user:username=myusername

If both args are given, you can again give them as positional args:

$ fab new_user:myusername,yes

Or mix and match, just like in Python:

$ fab new_user:myusername,admin=yes

All of the above are translated into the expected Python function calls. For example, the last call above would become:

>>> new_user('myusername', admin='yes')

$ fab new_user:myusername,hosts="host1;host2"

Settings files¶

Fabric currently honors a simple user settings file, or fabricrc (think bashrc but for fab) which should contain one or more key-value pairs, one per line. These lines will be subject to string.split('='), and thus can currently only be used to specify string settings. Any such key-value pairs will be used to update env when fab runs, and is loaded prior to the loading of any fabfile.

By default, Fabric looks for ~/.fabricrc, and this may be overridden by specifying the -c flag to fab.

For example, if your typical SSH login username differs from your workstation username, and you don’t want to modify env.user in a project’s fabfile (possibly because you expect others to use it as well) you could write a fabricrc file like so:

user = ssh_user_name

Then, when running fab, your fabfile would load up with env.user set to 'ssh_user_name'. Other users of that fabfile could do the same, allowing the fabfile itself to be cleanly agnostic regarding the default username.

Fabfile discovery¶

By default, fab attempts to find a file named fabfile.py, in the invoking user’s current working directory or any parent directories. Thus, it is oriented around “project” use, where one keeps a fabfile.py at the root of a source code tree. Such a fabfile will then be discovered no matter where in the source code the user invokes fab.

The specific name of the fabfile may be overridden on the command-line with the -f option, or by adding a line setting the value of fabfile to one’s fabricrc. For example, if you wanted to name your fabfile fab_tasks.py, you could create such a file and then call fab -f fab_tasks.py <task name>, or add fabfile = fab_tasks.py to ~/.fabricrc.

If the given fabfile name contains path elements other than a filename (e.g. ../fabfile.py or /dir1/dir2/other.py) it will be treated as a file path and directly checked for existence without any sort of searching. When in this mode, tile-expansion will be applied, so one may refer to e.g. ~/personal_fabfile.py.

Importing Fabric¶

Because Fabric is just Python, you can import its components any way you want. However, for the purposes of encapsulation and convenience (and to make life easier for Fabric’s packaging script) Fabric’s public API is maintained in the fabric.api module.

All of Fabric’s Operations, Context Managers, Decorators and Utils are included in this module as a single, flat namespace. This enables a very simple and consistent interface to Fabric within your fabfiles:

from fabric.api import *

# call run(), sudo(), etc etc

This is not technically best practices (for a number of reasons) and if you’re only using a couple of Fab API calls, it is probably a good idea to explicitly from fabric.api import env, run or similar. However, in most nontrivial fabfiles, you’ll be using all or most of the API, and the star import:

from fabric.api import *

will be a lot easier to write and read than:

from fabric.api import abort, cd, env, get, hide, hosts, local, prompt, \
    put, require, roles, run, runs_once, settings, show, sudo, warn

so in this case we feel pragmatism overrides best practices.

Defining tasks and importing callables¶

For important information on what exactly Fabric will consider as a task when it loads your fabfile, as well as notes on how best to import other code, please see Defining tasks in the Execution model documentation.

Output levels¶

To aid in organizing task output, Fabric output is grouped into a number of non-overlapping levels or groups, each of which may be turned on or off independently. This provides flexible control over what is displayed to the user.

The standard, atomic output levels/groups are as follows:

• status: Status messages, i.e. noting when Fabric is done running, if the user used a keyboard interrupt, or when servers are disconnected from. These messages are almost always relevant and rarely verbose.
• aborts: Abort messages. Like status messages, these should really only be turned off when using Fabric as a library, and possibly not even then. Note that even if this output group is turned off, aborts will still occur – there just won’t be any output about why Fabric aborted!
• warnings: Warning messages. These are often turned off when one expects a given operation to fail, such as when using grep to test existence of text in a file. If paired with setting env.warn_only to True, this can result in fully silent warnings when remote programs fail. As with aborts, this setting does not control actual warning behavior, only whether warning messages are printed or hidden.
• running: Printouts of commands being executed or files transferred, e.g. [myserver] run: ls /var/www.
• stdout: Local, or remote, stdout, i.e. non-error output from commands.
• stderr: Local, or remote, stderr, i.e. error-related output from commands.

Hiding and/or showing output levels¶

You may toggle any of Fabric’s output levels in a number of ways; for examples, please see the API docs linked in each bullet point:

• Direct modification of fabric.state.output: fabric.state.output is a dictionary subclass (similar to env) whose keys are the output level names, and whose values are either True (show that particular type of output) or False (hide it.)

  fabric.state.output is the lowest-level implementation of output levels and is what Fabric’s internals reference when deciding whether or not to print their output.

• Context managers: hide and show are twin context managers that take one or more output level names as strings, and either hide or show them within the wrapped block. As with Fabric’s other context managers, the prior values are restored when the block exits.

  See also

  settings, which can nest calls to hide and/or show inside itself.

• Command-line arguments: You may use the --hide and/or --show arguments to fab options and arguments, which behave exactly like the context managers of the same names (but are, naturally, globally applied) and take comma-separated strings as input.

Unknown hosts¶

SSH’s host key tracking mechanism keeps tabs on all the hosts you attempt to connect to, and maintains a ~/.ssh/known_hosts file with mappings between identifiers (IP address, sometimes with a hostname as well) and SSH keys. (For details on how this works, please see the OpenSSH documentation.)

Paramiko is capable of loading up your known_hosts file, and will then compare any host it connects to, with that mapping. Settings are available to determine what happens when an unknown host (a host whose username or IP is not found in known_hosts) is seen:

• Reject: the host key is rejected and the connection is not made. This results in a Python exception, which will terminate your Fabric session with a message that the host is unknown.
• Add: the new host key is added to the in-memory list of known hosts, the connection is made, and things continue normally. Note that this does not modify your on-disk known_hosts file!
• Ask: not yet implemented at the Fabric level, this is a Paramiko option which would result in the user being prompted about the unknown key and whether to accept it.

Whether to reject or add hosts, as above, is controlled in Fabric via the env.reject_unknown_hosts option, which is False by default for convenience’s sake. We feel this is a valid tradeoff between convenience and security; anyone who feels otherwise can easily modify their fabfiles at module level to set env.reject_unknown_hosts = True.

Known hosts with changed keys¶

The point of SSH’s key/fingerprint tracking is so that man-in-the-middle attacks can be detected: if an attacker redirects your SSH traffic to a computer under his control, and pretends to be your original destination server, the host keys will not match. Thus, the default behavior of SSH – and Paramiko – is to immediately abort the connection when a host previously recorded in known_hosts suddenly starts sending us a different host key.

In some edge cases such as some EC2 deployments, you may want to ignore this potential problem. Paramiko, at the time of writing, doesn’t give us control over this exact behavior, but we can sidestep it by simply skipping the loading of known_hosts – if the host list being compared to is empty, then there’s no problem. Set env.disable_known_hosts to True when you want this behavior; it is False by default, in order to preserve default SSH behavior.

Major changes¶

You’ll want to at least skim the entire document, but the primary changes that will need to be made to one’s fabfiles are as follows:

@hosts('a', 'b')
def my_task():
    run('ls /var/www')
    sudo('mkdir /var/www/newsite')

from fabric.api import hosts, run, sudo

@hosts('a', 'b')
def my_task():
    run('ls /var/www')
    sudo('mkdir /var/www/newsite')

def my_task():
    config.foo = 'bar'

from fabric.api import env

def my_task():
    env.foo = 'bar'

print("Your current username is $(fab_user)")

print("Your current username is %s" % env.user)

Other backwards-incompatible changes¶

In no particular order:

• The Fabric config file location used to be ~/.fabric; in the interests of honoring Unix filename conventions, it’s now ~/.fabricrc.

• The old config object (now env) had a getAny method which took one or more key strings as arguments, and returned the value attached to the first valid key. This method still exists but has been renamed to first.

• Environment variables such as fab_host have been renamed to simply e.g. host. This looks cleaner and feels more natural, and requires less typing. Users will naturally need to be careful not to override these variables, but the same holds true for e.g. Python’s builtin methods and types already, so we felt it was worth the tradeoff.

• Fabric’s version header is no longer printed every time the program runs; you should now use the standard --version/-V command-line options to print version and exit.

• The old about command has been removed; other Unix programs don’t typically offer this. Users can always view the license and warranty info in their respective text files distributed with the software.

• The old help command is now the typical Unix options -h/--help.

  • Furthermore, there is no longer a listing of Fabric’s programming API available through the command line – those topics impact fabfile authors, not fab users (even though the former is a subset of the latter) and should stay in the documentation only.

• prompt‘s primary function is now to return a value to the caller, although it may still optionally store the entered value in env as well.

• prompt now considers the empty string to be valid input; this allows other functions to wrap prompt and handle “empty” input on their own terms.

• In addition to the above changes, prompt has been updated to behave more obviously, as its previous behavior was confusing in a few ways:

  • It will now overwrite pre-existing values in the environment dict, but will print a warning to the user if it does so.
  • Additionally, (and this appeared to be undocumented) the default argument could take a callable as well as a string, and would simply set the default message to the return value if a callable was given. This seemed to add unnecessary complexity (given that users may call e.g. prompt(blah, msg, default=my_callable()) so it has been removed.

• When connecting, Fabric used to use the undocumented fab_pkey env variable as a method of passing in a Paramiko PKey object to the SSH client’s connect method. This has been removed in favor of an ssh-like -i option, which allows one to specify a private key file to use; that should generally be enough for most users.

• download is now get in order to match up with put (the name mismatch was due to get being the old method of getting env vars.)

• The noshell argument to sudo (added late in its life to previous Fabric versions) has been renamed to shell (defaults to True, so the effective behavior remains the same) and has also been extended to the run operation.

  • Additionally, the global sudo_noshell option has been renamed to use_shell and also applies to both run and sudo.

• local_per_host has been removed, as it only applied to the now-removed “broad mode”.

• load has been removed; Fabric is now “just Python”, so use Python’s import mechanisms in order to stitch multiple fabfiles together.

• abort is no longer an “operation” per se and has been moved to fabric.utils. It is otherwise the same as before, taking a single string message, printing it to the user and then calling sys.exit(1).

• rsyncproject and upload_project have been moved into fabric.contrib (specifically, fabric.contrib.project), which is intended to be a new tree of submodules for housing “extra” code which may build on top of the core Fabric operations.

• invoke has been turned on its head, and is now the runs_once decorator (living in fabric.decorators). When used to decorate a function, that function will only execute one time during the lifetime of a fab run. Thus, where you might have used invoke multiple times to ensure a given command only runs once, you may now use runs_once to decorate the function and then call it multiple times in a normal fashion.

• It looks like the regex behavior of the validate argument to prompt was never actually implemented. It now works as advertised.

• Couldn’t think of a good reason for require to be a decorator and a function, and the function is more versatile in terms of where it may be used, so the decorator has been removed.

• As things currently stand with the execution model, the depends decorator doesn’t make a lot of sense: instead, it’s safest/best to simply make “meta” commands that just call whatever chain of “real” commands you need performed for a given overarching task.

  For example, instead of having command A say that it “depends on” command B, create a command C which calls A and B in the right order, e.g.:

  def build():
      local('make clean all')
  
  def upload():
      put('app.tgz', '/tmp/app.tgz')
      run('tar xzf /tmp/app.tgz')
  
  def symlink():
      run('ln -s /srv/media/photos /var/www/app/photos')
  
  def deploy():
      build()
      upload()
      symlink()
  

  Note

  The execution model is still subject to change as Fabric evolves. Please don’t hesitate to email the list or the developers if you have a use case that needs something Fabric doesn’t provide right now!

• Removed the old fab shell functionality, since the move to “just Python” should make vanilla python/ipython usage of Fabric much easier.

  • We may add it back in later as a convenient shortcut to what basically amounts to running ipython and performing a handful of from fabric.foo import bar calls.

• The undocumented fab_quiet option has been replaced by a much more granular set of output controls. For more info, see Managing output.

Changes from alpha 1 to alpha 2¶

The below list was generated by running git shortlog 0.9a1..0.9a2 and then manually sifting through and editing the resulting commit messages. This will probably occur for the rest of the alphas and betas; we hope to use Sphinx-specific methods of documenting changes once the final release is out the door.

• Various minor tweaks to the (still in-progress) documentation, including one thanks to Curt Micol.
• Added a number of TODO items based on user feedback (thanks!)
• Host information now available in granular form (user, host, port) in the env dict, alongside the full user@host:port host string.
• Parsing of host strings is now more lenient when examining the username (e.g. hyphens.)
• User/host info no longer cleared out between commands.
• Tweaked setup.py to use find_packages. Thanks to Pat McNerthney.
• Added ‘capture’ argument to local to allow local interactive tasks.
• Reversed default value of local‘s show_stderr kwarg; local stderr now prints by default instead of being hidden by default.
• Various internal fabfile tweaks.

Changes from alpha 2 to alpha 3¶

• Lots of updates to the documentation and TODO
• Added contrib.files with a handful of file-centric subroutines
• Added contrib.console for console UI stuff (so far, just confirm)
• Reworked config file mechanisms a bit, added CLI flag for setting it.
• Output controls (including CLI args, documentation) have been added
• Test coverage tweaked and grown a small amount (thanks in part to Peter Ellis)
• Roles overhauled/fixed (more like hosts now)
• Changed --list linewrap behavior to truncate instead.
• Make private key passphrase prompting more obvious to users.
• Add pty option to sudo. Thanks to José Muanis for the tip-off re: get_pty()
• Add CLI argument for setting the shell used in commands (thanks to Steve Steiner)
• Only load host keys when env.reject_unknown_keys is True. Thanks to Pat McNerthney.
• And many, many additional bugfixes and behavioral tweaks too small to merit cluttering up this list! Thanks as always to everyone who contributed bugfixes, feedback and/or patches.

Changes from alpha 3 to beta 1¶

This is closer to being a straight dump of the Git changelog than the previous sections; apologies for the overall change in tense.

• Add autodocs for fabric.contrib.console.
• Minor cleanup to package init and setup.py.
• Handle exceptions with strerror attributes that are None instead of strings.
• contrib.files.append may now take a list of strings if desired.
• Straighten out how prompt() deals with trailing whitespace
• Add ‘cd’ context manager.
• Update upload_template to correctly handle backing up target directories.
• upload_template() can now use Jinja2 if it’s installed and user asks for it.
• Handle case where remote host SSH key doesn’t match known_hosts.
• Fix race condition in run/sudo.
• Start fledgling FAQ; extended pty option to run(); related doc tweaks.
• Bring local() in line with run()/sudo() in terms of .failed attribute.
• Add dollar-sign backslash escaping to run/sudo.
• Add FAQ question re: backgrounding processes.
• Extend some of put()’s niceties to get(), plus docstring/comment updates
• Add debug output of chosen fabfile for troubleshooting fabfile discovery.
• Fix Python path bug which sometimes caused Fabric’s internal fabfile to pre-empt user’s fabfile during load phase.
• Gracefully handle “display” for tasks with no docstring.
• Fix edge case that comes up during some auth/prompt situations.
• Handle carriage returns in output_thread correctly. Thanks to Brian Rosner.

Changes from beta 1 to release candidate 1¶

As with the previous changelog, this is also mostly a dump of the Git log. We promise that future changelogs will be more verbose :)

• Near-total overhaul and expansion of documentation (this is the big one!) Other mentions of documentation in this list are items deserving their own mention, e.g. FAQ updates.
• Add FAQ question re: passphrase/password prompt
• Vendorized Paramiko: it is now included in our distribution and is no longer an external dependency, at least until upstream fixes a nasty 1.7.5 bug.
• Fix #34: switch upload_template to use mkstemp (also removes Python 2.5.2+ dependency – now works on 2.5.0 and up)
• Fix #62 by escaping backticks.
• Replace “ls” with “test” in exists()
• Fixes #50. Thanks to Alex Koshelev for the patch.
• local‘s return value now exhibits .return_code.
• Abort on bad role names instead of blowing up.
• Turn off DeprecationWarning when importing paramiko.
• Attempted fix re #32 (dropped output)
• Update role/host initialization logic (was missing some edge cases)
• Add note to install docs re: PyCrypto on win32.
• Add FAQ item re: changing env.shell.
• Rest of TODO migrated to tickets.
• fab test (when in source tree) now uses doctests.
• Add note to compatibility page re: fab_quiet.
• Update local() to honor context_managers.cd()