.. include:: ../../README.rst

This website covers project information for Fabric such as the changelog,
contribution guidelines, and so forth. Detailed usage and API documentation can
be found at our code documentation site, `docs.fabfile.org
<https://docs.fabfile.org>`_.

Please see below for a high level intro, or the navigation on the left for the
rest of the site content.

What is Fabric?
---------------

Fabric is a high level Python (2.7, 3.4+) library designed to execute shell
commands remotely over SSH, yielding useful Python objects in return:

.. testsetup:: opener

    mock = MockRemote()
    # NOTE: hard to get trailing whitespace in a doctest/snippet block, so we
    # just leave the 'real' newline off here too. Whatever.
    mock.expect(out=b"Linux")

.. testcleanup:: opener

    mock.stop()

.. doctest:: opener

    >>> from fabric import Connection
    >>> result = Connection('web1.example.com').run('uname -s', hide=True)
    >>> msg = "Ran {0.command!r} on {0.connection.host}, got stdout:\n{0.stdout}"
    >>> print(msg.format(result))
    Ran 'uname -s' on web1.example.com, got stdout:
    Linux

It builds on top of `Invoke <https://pyinvoke.org>`_ (subprocess command
execution and command-line features) and `Paramiko <https://paramiko.org>`_ (SSH
protocol implementation), extending their APIs to complement one another and
provide additional functionality.

.. note::
    Fabric users may also be interested in two *strictly optional* libraries
    which implement best-practice user-level code: `Invocations
    <https://invocations.readthedocs.io>`_ (Invoke-only, locally-focused CLI
    tasks) and `Patchwork <https://fabric-patchwork.readthedocs.io>`_
    (remote-friendly, typically shell-command-focused, utility functions).

How is it used?
---------------

Core use cases for Fabric include (but are not limited to):

* Single commands on individual hosts:

  .. testsetup:: single-command
  
      from fabric import Connection
      mock = MockRemote()
      mock.expect(out=b"web1")
  
  .. testcleanup:: single-command
  
      mock.stop()
  
  .. doctest:: single-command

      >>> result = Connection('web1').run('hostname')
      web1
      >>> result
      <Result cmd='hostname' exited=0>

* Single commands across multiple hosts (via varying methodologies: serial,
  parallel, etc):

  .. testsetup:: multiple-hosts
  
      from fabric import Connection
      mock = MockRemote()
      mock.expect_sessions(
          Session(host='web1', cmd='hostname', out=b'web1\n'),
          Session(host='web2', cmd='hostname', out=b'web2\n'),
      )
  
  .. testcleanup:: multiple-hosts
  
      mock.stop()
  
  .. doctest:: multiple-hosts

      >>> from fabric import SerialGroup     
      >>> result = SerialGroup('web1', 'web2').run('hostname')
      web1
      web2
      >>> # Sorting for consistency...it's a dict!
      >>> sorted(result.items())
      [(<Connection host=web1>, <Result cmd='hostname' exited=0>), ...]

* Python code blocks (functions/methods) targeted at individual connections:

  .. testsetup:: tasks
  
      from fabric import Connection
      mock = MockRemote()
      mock.expect(commands=[
          Command("uname -s", out=b"Linux\n"),
          Command("df -h / | tail -n1 | awk '{print $5}'", out=b'33%\n'),
      ])
  
  .. testcleanup:: tasks
  
      mock.stop()
  
  .. doctest:: tasks

      >>> def disk_free(c):
      ...     uname = c.run('uname -s', hide=True)
      ...     if 'Linux' in uname.stdout:
      ...         command = "df -h / | tail -n1 | awk '{print $5}'"
      ...         return c.run(command, hide=True).stdout.strip()
      ...     err = "No idea how to get disk space on {}!".format(uname)
      ...     raise Exit(err)
      ...
      >>> print(disk_free(Connection('web1')))
      33%

* Python code blocks on multiple hosts:

  .. testsetup:: tasks-on-multiple-hosts
  
      from fabric import Connection, SerialGroup
      mock = MockRemote()
      mock.expect_sessions(
        Session(host='web1', commands=[
          Command("uname -s", out=b"Linux\n"),
          Command("df -h / | tail -n1 | awk '{print $5}'", out=b'33%\n'),
        ]),
        Session(host='web2', commands=[
          Command("uname -s", out=b"Linux\n"),
          Command("df -h / | tail -n1 | awk '{print $5}'", out=b'17%\n'),
        ]),
        Session(host='db1', commands=[
          Command("uname -s", out=b"Linux\n"),
          Command("df -h / | tail -n1 | awk '{print $5}'", out=b'2%\n'),
        ]),
      )
  
  .. testcleanup:: tasks-on-multiple-hosts
  
      mock.stop()
  
  .. doctest:: tasks-on-multiple-hosts

      >>> # NOTE: Same code as above!
      >>> def disk_free(c):
      ...     uname = c.run('uname -s', hide=True)
      ...     if 'Linux' in uname.stdout:
      ...         command = "df -h / | tail -n1 | awk '{print $5}'"
      ...         return c.run(command, hide=True).stdout.strip()
      ...     err = "No idea how to get disk space on {}!".format(uname)
      ...     raise Exit(err)
      ...
      >>> for cxn in SerialGroup('web1', 'web2', 'db1'):
      ...    print("{}: {}".format(cxn, disk_free(cxn)))
      <Connection host=web1>: 33%
      <Connection host=web2>: 17%
      <Connection host=db1>: 2%

In addition to these library-oriented use cases, Fabric makes it easy to
integrate with Invoke's command-line task functionality, invoking via a ``fab``
binary stub:

* Python functions, methods or entire objects can be used as CLI-addressable
  tasks, e.g. ``fab deploy``;
* Tasks may indicate other tasks to be run before or after they themselves
  execute (pre- or post-tasks);
* Tasks are parameterized via regular GNU-style arguments, e.g. ``fab deploy
  --env=prod -d``;
* Multiple tasks may be given in a single CLI session, e.g. ``fab build
  deploy``;
* Much more - all other Invoke functionality is supported - see `its
  documentation <https://docs.pyinvoke.org>`_ for details.

I'm a user of Fabric 1, how do I upgrade?
-----------------------------------------

We've packaged modern Fabric in a manner that allows installation alongside
Fabric 1, so you can upgrade at whatever pace your use case requires. There are
multiple possible approaches -- see our :ref:`detailed upgrade documentation
<upgrading>` for details.

What is this website?
---------------------

``www.fabfile.org`` provides project information for Fabric such as the
changelog, contribution guidelines, development roadmap, news/blog, and so
forth.

Detailed conceptual and API documentation can be found at our code
documentation site, `docs.fabfile.org <https://docs.fabfile.org>`_.


.. toctree::
    :hidden:

    changelog
    changelog-v1
    FAQs <faq>
    installing
    installing-1.x
    upgrading
    development
    troubleshooting
    Roadmap <roadmap>
    contact