======
Fabric
======
-----------------------------
A general purpose python tool
-----------------------------


.. class:: right

    Morgan Goose
    
    Febuary 2011
    
.. class:: handout

    This work is licensed under the Creative Commons
    Attribution-Noncommercial-Share Alike 3.0 United
    States License. To view a copy of this license, visit
    http://creativecommons.org/licenses/by-nc-sa/3.0/us/
    or send a letter to Creative Commons, 171 Second
    Street, Suite 300, San Francisco, California, 94105, USA.


About
=====

Fabric is a Python (2.5 or higher) library and command-line tool for
streamlining the use of SSH for application deployment or systems
administration tasks.


Some more
=========

It provides a basic suite of operations for executing local or remote shell
commands (normally or via sudo) and uploading/downloading files, as well as
auxiliary functionality such as prompting the running user for input, or
aborting execution.


Interacting with the CLI
========================

To actually start leveraging the shell accesses and ssh ability, there are a 
number of operations that are given by that Fabric library::

    local - shell out to the local machine
    run - run commands on current remote machine
    sudo - same as run but sudo's to root or given user
    get/put - uses scp to place or take files from remote servers


Context Managers
================

There are also a number of functions that one can use in conjunction with the
with_statement and have a temporary change in  state::

    cd - changes directory state when calling operations.
    lcd - same as cd but acts locally only
    hide - setting the given output groups to False.
    show - setting the given output groups to True.
    prefix - like cd, but parameter is prepended to operation calls
    settings - Nests contexts and overrides env variables


Other parts to know
===================

There are any number of other parts to fabric that warrant a in depth look, but
all I will do here is point out that they exist

    * env - state handler
    * contrib - files, django, color
    * use as a library
    * the execution model
    * internals for ssh behavior


Hello, ``fab``
==============

This wouldn't be a proper tutorial without "the usual"

.. code-block:: python

    def hello():
        print("Hello world!")

Placed in a Python module file named ``fabfile.py``, that function can be
executed with the ``fab`` tool (installed as part of Fabric) and does just what
you'd expect

.. code-block:: bash

    $ fab hello
    Hello world!

    Done.

That's all there is to it. This functionality allows Fabric to be used as a
(very) basic build tool even without importing any of its API.

Note
====

The ``fab`` tool simply imports your fabfile and executes the function or
functions you instruct it to. There's nothing magic about it -- anything
you can do in a normal Python script can be done in a fabfile!


Task arguments
==============

It's often useful to pass runtime parameters into your tasks, just as you might
during regular Python programming. Fabric has basic support for this using a
shell-compatible notation: ``<task name>:<arg>,<kwarg>=<value>,...``. It's
contrived, but let's extend the above example to say hello to you personally

.. code-block:: python

    def hello(name="world"):
        print("Hello %s!" % name)

By default, calling ``fab hello`` will still behave as it did before; but now
we can personalize it

.. code-block:: bash

    $ fab hello:name=Jeff
    Hello Jeff!

    Done.

Continued
=========

Those already used to programming in Python might have guessed that this
invocation behaves exactly the same way

.. code-block:: bash

    $ fab hello:Jeff
    Hello Jeff!

    Done.

For the time being, your argument values will always show up in Python as
strings and may require a bit of string manipulation for complex types such
as lists. Future versions may add a typecasting system to make this easier.


Show and tell
=============

So now I have a bunch of fabfiles that show different uses