rusty.xmltable – XMLTable directive

Platforms: Unix, Windows

New in version 0.2.0.


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

sudo easy_install BeautifulSoup


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.

The given query iterates all the items that matches with document.
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.
XML element attributes can be shown as a value. The attribute is noted with @attribute-name -notation.
Header columns can be defined for the table. Separate the values with comma.


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


* 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.


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:


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

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


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:


See advanced example

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.

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:

  <animal id="L353">
  <animal id="C665">

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


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


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



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"?>
  <country id="finland">
  <country id="england">
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



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.


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


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.

Table Of Contents

Previous topic


Next topic

rusty.includesh – Include shell scripts in documentation

This Page