rusty.xmltable – XMLTable directive

Platforms: Unix, Windows

New in version 0.2.0.

Note

The module depends on BeautifulSoup -module. Install it using setuptools:

sudo easy_install BeautifulSoup

Features

XMLTable directive generates the table based on XML document and query, defined in the document. The usage is simple, but should cover most of the cases.

Iteration

The given query iterates all the items that matches with document.

Values

XML element values can be listed in a table cells. The selector is relative to iteration query, but can be also the parent and child elemnt of it. The text between elements is automatically taken, but it can be noted with @value -notation as well.

Attributes

XML element attributes can be shown as a value. The attribute is noted with @attribute-name -notation.

Header

Header columns can be defined for the table. Separate the values with comma.

Usage

Define xmltable -directive into your document. The path to document is given with file option, and it is relative to document path. The directive argument is reserved for the optional table caption.

This is an example rst-document

.. xmltable:: caption
   :file: path/to/document.xml
   :header: Name, Name, Name, Name
   :query: /xml/query

   element-name
   element-name@attrib
   self
   @attrib


* list
* item

And so on..

As it can be seen from the example, there are few options and content defined for the element. The description for each:

file (required)

Relative path (based on document) to XML file. Compulsory option.

header (optional)

Optional column fields for the header. If not defined, no table header is created. Separate the column names with comma (,). Quotes are not needed and they are actually shown as is.

If the header is not defined, the generated table won’t have either. If the number of header entries does not match with the rows (columns) of the directive content area, an error is raised.

query

XML query, or more like a path, defines the name of elements that will be iterated from the XML document. Each element will create a new row to table. For example, if XML document contains multiple <animal> elements (within <zoo> element), each entry is shown as a new row with the definition:

/zoo/animal

Then, the content area defines from which sub-elements the string value is taken from:

.. xmltable::
   :file: animals.xml
   :query: /zoo/animal

   column1
   column2

The query consists only from the strings and slashes. The first slash is ignored as the path always starts from the beginning of the XML document. Example:

/world/countries/country

See advanced example

widths

Optional parameter for defining the size of the column widths. The expected values are integers, separated with comma (the number of values must match) with number of columns.

content

Each row on the xmltable -directive content area defines the path to the sub-element which string value is taken into table cell. To continue with the animal-example, let’s consider following document:

<zoo>
  <animal id="L353">
    <name>Leo</name>
    <species>Lion</species>
  </animal>
  <animal id="C665">
    <name>Carl</name>
    <species>Camel</species>
  </animal>
</zoo>

Following directive iterates each animal and prints some info about it into table. Notice the matching header definition:

.. xmltable:: Animal table caption
   :file: example/animals.xml
   :header: Name, Species, ID
   :query: /zoo/animal

   name
   species
   self@id

Producing following table:

Animal table caption

Name	Species	ID
Leo	Lion	L353
Carl	Camel	C665

If the selected element does not have string value, all the string values from the sub-elements are taken. Example:

.. xmltable:: List of countries
   :file: document.xml
   :header: Description
   :query: countries/country

   self

.. xmltable:: List of countries
   :file: example/document.xml
   :header: Description
   :query: countries/country

   self

Example

Sometimes the example is the best way to learn. Consider this example:

XML document

First we have a XML document:

<?xml version="1.0" encoding="UTF-8"?>
<countries>
  <country id="finland">
    <name>Finland</name>
    <time>UTC+2</time>
    <currency>euro</currency>
  </country>
  <country id="england">
    <name>England</name>
    <currency>pound</currency>
    <time>UTC</time>
  </country>
</countries>

RST document

Now the text document could have something like:

.. xmltable:: List of countries
   :file: document.xml
   :header: ID, Name, Time, Currency, All
   :widths: 60, 10, 10, 10
   :query: /countries/country

   name
   self@id
   time
   currency
   self

Note

Note the special self -keyword: it references to the last element defined with the query. In the case of example, the self references to country element and self@id to id attribute element.

If the selected element has no string value, it retrievs the string from the subelements recursively.

Output

Once generated, the output shows the contents of the XML in table format.

List of countries

ID	Name	Time	Currency	All
Finland	finland	UTC+2	euro	Finland UTC+2 euro
England	england	UTC	pound	England pound UTC

Development

Known issues or development ideas for directive. May be fixed/implemented in the future.

• File path cannot contain quotes (are spaces supported?)
• Multiple entries per field
• Support for remote resources

Module in detail

XMLTableDirective implements the xmltable -directive. The implementation is based on two existing solutions:

• ListTable, from the docutils module
• BeautifulStoneSoup, from the BeautifulSoup module

The module introduces simple yet effective query language, that is used to select and generate the RST-table from the XML-document.

class rusty.xmltable.XMLTableDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

XMLTableDirective implements the new restructured text directive. It’s purpose is to provide an easy-to-use XML into RST table transition - in a form of docutils directive.

class rusty.xmltable.BeautifulTable(fobj)

Class generates the list based table from the given document, suitable for the directive.

Class also implements the custom query format, is to use for the directive. Examples:

/root-elem/sub-elem/elem   <- text value
/root-elem/sub-elem@attr   <- attr value

Internally, the BeautifulTable uses the BeautifulStoneSoup, from BeautifulSoup.