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.contains(path, text, xquery='/', exact=False)

Return True if filename contains text in XML element values.

Note

As a comparison, fabric.contrib.file.contains matches whole file contents, whereas fabric.contrib.xfiles.contains matches only with XML element values.

By default, this function will consider a partial line match (i.e. where the given text only makes up part of the line it’s on). Specify exact=True to change this behavior so that only a line containing exactly text results in a True return value.

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):

New in version 0.2.

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 as 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

Example:

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()

You may find following object parameters useful:

etree

ElementTree object of the opened XML document

rpath

Path to (possibly remote) file

lpath

Local path where the remote XML document is temporarily stored. Even in a case of local XML documents, this is a temporary copy of the file.

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