fabric.contrib.xfiles

Convinience functions

This section contains some easy-to-use functions, to be used as is without too much hassle within fabfiles:

fabric.contrib.xfiles.pprint(path, xquery)

Prints the matching entries (whereas query() only returns elements)

# fabfile.py
from fabric.contrib import xfiles

def mycommand(rpath):
  """
  Lists the elements of remote document.
  """
  xfiles.pprint(rpath, 'items/item[attr=value]')

And to run fabfile:

fab mycommand:document.xml

fabric.contrib.xfiles.query(path, xquery, fail_on_error=True)

Makes query to remote XML file and returns the matching entries back

path

Path to remote XML document

xquery

XQuery -like selection for the elements/values in the XML document. Selection format:

path/to/elements            # <-- matches to elements -element
/root/path/to/elements      # <-- absolute selection example
path/to=value               # <-- matches with 'to' element when having text 'value' in it
path/to=val*                # <-- matches with 'to' element when having text starting with 'val'
path/to/elements[id]        # <-- matches to all elements having 'id' attribute
path/to/elements[@id]       # <-- same as above
path/to/elements[i?]        # <-- matches to all attributes with 'i'+something
path/to/elements[i*]        # <-- matches to all attributes with 'i'
path/to/elements[id=value]  # <-- matches to all elements having 'id' attribute with value 'value'
path/to/elements[@id=value] # <-- same as above
path/to/elements[id=val*]   # <-- matches to all elements having 'val'+something
path/to/elements[i?=val*]   # <-- combination from above
path/to[i?=val*]=val*       # <-- combination from all of the above

Note

Wildcard are not supported for paths - at least not yet. So, for example, following is not supported:

path/to/elem*

fail_on_error (default True)

If the document reading/parsing fails, an exception is raised. However, if this flag is set to False, and empty list is returned instead - silently.

returns

List of ElementTree -elements. Or empty list if silent fail flag is set

# fabfile.py
from fabric.contrib import xfiles

def mycommand():
  for elem in xfiles.query('path/to/remotedoc.xml', 'items/item'):
    print elem.text, elem.attrib

And to run fabfile:

fab mycommand

Complete API

For more advanced usage, this section lists the contents of the API:

class fabric.contrib.xfiles.reader.RXMLReader

XMLReader for remote files, using Fabric

from fabric.contrib.xfiles import reader
rxr = reader.RXMLReader()
rxr.open('/tmp/document.xml')
rxr.query('/root/path/items')
# do something with the result set
rxr.close()

close()

Closes the reader. Deletes the local, temporary XML document

open(rpath)

Reads the XML document from remote location and stores the parsed document into self.etree

rpath

Path in server, to remote XML file

returns

Object itself

query(query)

Makes a query to retrived XML file.

query

A simple XML query to the document.

returns

A list of xml.etree.ElementTree elements that matches with the query