ploy-fabric 2.0.0
Plugin to integrate Fabric with ploy.
License: BSD 3-Clause License
Requires Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*

Overview
========

The ploy_fabric plugin provides integration of `Fabric`_ with `ploy`_.

.. _Fabric: http://fabfile.org
.. _ploy: https://github.com/ployground/


Installation
============

ploy_fabric is best installed with easy_install, pip or with zc.recipe.egg in a buildout.

Once installed, it's functionality is immediately usable with ploy.


Commands
========

The plugin adds the following commands to ploy.

``do``
  Runs a Fabric task with simplified syntax for arguments.
  You can just put positional arguments on the command line behind the task name.
  For keyword arguments user the ``name=value`` syntax.
  For example::

    ploy do something arg key=value

``fab``
  Runs a Fabric task and passes on command line options to Fabric.
  This basically reflects the ``fab`` script of Fabric.


Options
=======

Instances only get the new ``fabfile`` option to specify which file to look in for tasks.
The location is relative to ``ploy.conf``.

Instance methods
================

For the Python side, each instance gains the ``do(task, *args, **kwargs)`` method.
The ``task`` argument is the name of a task from the Fabric script which should be run. The remaining arguments are passed on to that task.

Another helper added to each instance is a context manager accessible via the ``fabric`` attribute on instances.
With that you can switch to a new ssh connection with a different user in your Fabric tasks:

.. code-block:: python

    from fabric.api import env, run


    def sometask():
        run("whoami")  # prints the default user (root)
        with env.instance.fabric(user='foo'):
          run("whoami")  # prints 'foo' if the connection worked
        run("whoami")  # prints the default user (root)

All changes to the Fabric environment are reverted when the context manager exits.

Fabric task decorator
=====================

With ``ploy_fabric.context`` you can decorate a task to use a specific user with a separate connection.
All changes to the Fabric environment are reverted when the context manager exits.
This is useful if you want to run a task from inside another task.

.. code-block:: python

    from fabric.api import env, run
    from ploy_fabric import context


    @context  # always run with the default user
    def sometask():
        run("whoami")  # prints the default user (root)


    @context(user=None)  # always run with the default user (alternate syntax)
    def someothertask():
        env.forward_agent = True
        run("whoami")  # prints the default user (root)


    @context(user='foo')  # always run as foo user
    def anothertask():
        env.forward_agent = False
        run("whoami")  # prints the default user (user)
        someothertask()
        assert env.forward_agent == False


Fabric environment
==================

The Fabric environment has the following settings by default.

``reject_unknown_hosts``
  Always set to ``True``, ssh connections are handled by this plugin and ploy.

``disable_known_hosts``
  Always set to ``True``, handled by ploy.

``host_string``
  The **unique id** of the current instance, only manipulate if you know what you do!

``known_hosts``
  Path to the ``known_hosts`` file managed by ploy.

``instances``
  Dictionary allowing access to the other instances to get variables or call methods on.

``instance``
  The current instance to access variables from the ``config`` attribute or other things and methods.

``config_base``
  The directory of ``ploy.conf``.

Any option of the instance starting with ``fabric-`` is stripped of the ``fabric-`` prefix and overwrites settings in the environment with that name.


Changelog
=========

2.0.0 - 2022-08-17
------------------

* Dropped support for Python < 3.7.
  [fschulze]

* Added support up to Python 3.10.
  [fschulze]


2.0.0b2 - 2019-06-09
--------------------

* Pin to Fabric < 2dev.
  [fschulze]

* Drop Python 3.4 support.
  [fschulze]


2.0.0b1 - 2018-02-07
--------------------

* Support Python 3.x via Fabric3.
  [fschulze]

* Support for ploy 2.0.0.
  [fschulze]


1.1.1 - 2018-06-07
------------------

* Update requirements to block Fabric >= 2 as it isn't compatible.
  [fschulze]


1.1.0 - 2014-10-27
------------------

* Require Fabric >= 1.4.0 and vastly simplify the necessary patching.
  [fschulze]

* Close all newly opened connections after a Fabric call.
  [fschulze]

* Add context manager and decorator to easily switch fabric connections.
  [fschulze]


1.0.0 - 2014-07-19
------------------

* Added documentation.
  [fschulze]


1.0b6 - 2014-07-15
------------------

* Allow overwriting of fabric env from config with options prefixed by
  ``fabric-``, i.e. ``fabric-shell = /bin/sh -c``.
  [fschulze]


1.0b5 - 2014-07-08
------------------

* Packaging and test fixes.
  [fschulze]

* Fix task listing for ``do`` command.
  [fschulze]


1.0b4 - 2014-07-04
------------------

* Use unique id for host string to avoid issues.
  [fschulze]

* Added ``fab`` command which is just a wrapper for Fabric with all it's options
  and reworked ``do`` command into a simple version to just run a task.
  [fschulze]

* Renamed mr.awsome to ploy and mr.awsome.fabric to ploy_fabric.
  [fschulze]


1.0b3 - 2014-06-09
------------------

* When depending on Fabric, skip 1.8.3 which added a version pin on paramiko.
  [fschulze]

* Only add Fabric to install_requires if it can't be imported. That way we
  don't get problems if it's already installed as a system packages or in a
  virtualenv.
  [fschulze]


1.0b2 - 2014-05-15
------------------

* Register ``fabfile`` massager for all instances.
  [fschulze]

* Use context manager for output filtering and filter in ``do`` helper.
  [fschulze]

* Moved setuptools-git from setup.py to .travis.yml, it's only needed for
  releases and testing.
  [fschulze]


1.0b1 - 2014-03-24
------------------

* Initial release
  [fschulze]