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

Example usage:

# 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

fabric.contrib.xfiles.validate(path, dtd=None, xmlschema=None, relaxng=None, fail_on_error=True)

Validates the given XML document, based on provided schema (if at all):

dtd

Path to local DTD schema file. If provided, the XML document will be validated against it.

xmlschema

Path to local XMLSchema file. If provided, the XML document will be validated against it.

relaxng

Path to local RelaxNG file. If provided, the XML document will be validated against it.

If none of these schema files are provided, the basic XML document parsing is done to ensure the validity of the document.

If the validation fails, the exception is thrown, hopefully with descriptive message why the validation did not pass. If fail_on_error is set False, the function returns False on failure. Otherwise True.

Example

from fabric.contrib import xfiles

def check():
  #Checks the setup config validity
  dtd = 'server-config.dtd'
  xsd = 'config.xsd'

  try:
    xfiles.validate('/etc/appx/server.xml', dtd=dtd)
    xfiles.validate('/etc/appx/application.xml', xmlschema=xsd)
  except Exception e:
    print 'Validation FAILED: %s' % e

Note

Schema validations requires lxml module to be installed on local environment.

http://codespeak.net/lxml/validation.html#xmlschema

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