=========================
XFiles - Fabric extension
=========================
XFiles is a Fabric_ extension that provides a support to read and write
XML files located on servers. Nowadays, there are a lot of XML files used
for configuration and other resources, and therefore having a method to work
with them is must have. See :doc:`changelog` to see the list of features
per version.

.. toctree::
   :hidden:

   changelog

.. contents::
   :local:

Introduction
============
Short introduction to the extension, covering the installation and usage
of the module.

**Prerequisites**
  The extension is dependent on following solutions:

  * Python 2.5 or higher (Fabric_ requires py2.5)
  * Fabric_ and its requirements

**Installation**
  Install the module by using following steps:

  #. Download and install Distribute::

      curl -O http://python-distribute.org/distribute_setup.py
      sudo python distribute_setup.py

  #. Install ``xfiles`` -module and Fabric (if not yet installed)::

      easy_install -U Fabric xfiles

**Usage**
  Simple usage example

  #. Create Fabric configuration file ``fabfile.py``, for example with following
     contents:

     .. code-block:: python

      from fabric.api import env, run
      from fabric.contrib import xfiles

      def test():
        for elem in xfiles.query('~/document.xml', '/root/item[id=test*]'):
          # List all the elements having the attribute 'id' 
          # and it with value 'test', or something that starts with it
          print elem.text

     In this example, it is expected you have XML -document in your home directory 
     (on ``remotehost`` -server), for example:
     
     .. code-block:: xml

        <root>
          <item id="foo">value1</item>
          <item id="testing">value2</item>
          <item id="test">value3</item>
        </root>

  #. To see the outcome, run the command::

      fab --username hostaccount -H remotehost test

     Unless you have SSH private key provided for the remotehost, it'll
     prompt for the password. After successful login, the XML file is read and text 
     from all ``/root/item`` -elements is listed.

     .. TIP::

        If the ``host`` parameter is not provided, or it is localhost, no SSH
        connection is needed/created and the file path is expected to be found
        from local filesystem. For example, following query reads the XML from 
        same directory where the ``fabfile.py`` is:

        .. code-block:: python

           for elem in xfiles.query('test.xml', '/root/sub'):
             print elem


Usage
=====
The example above shows only a one way how to use the extension. This shows additional and
more advanced examples.

.. automethod:: fabric.contrib.xfiles.query

.. automethod:: fabric.contrib.xfiles.pprint

Development
===========
The source and issue management is hosted in Bitbucket_ and mercurial repository.
With the addition of liberal MIT-license, the extension is free to use for both
commercial and personal usage.

For the development, following additional modules are needed:

* Nose_ - for unit testing
* Fudge_ - for test mockups
* Coverage_ - for test coverage measurement

.. jedit: :tabSize=2:indentSize=2:noTabs=true:mode=rest:
.. 
  vim: set ft=rst :
