Amara XML Toolkit 1.1.9 (released 15 September 2006)
====================================================

by Uche Ogbuji

http://uche.ogbuji.net/tech/4suite/amara


A collection of Python tools for XML processing.  Not just tools
that happen to be written in Python, but tools built from the ground
up to use Python idioms and take advantage of the many advantages
of Python over other programming languages.

Amara builds on 4Suite, but whereas 4Suite focuses more on literal
implementation of XML standards in Python, Amara adds a much more
Pythonic face to these capabilities.

Amara provides tools you can trust to conform with XML standards
without losing the power and expressiveness characteristic of Python.

The components of Amara are:

* Bindery: a data binding tool (fancy way of saying it's a very Pythonic XML API)
* Scimitar: an implementation of the ISO Schematron schema language for XML, which converts Schematron files to Python scripts
* domtools: A set of tools to augment Python DOMs
* saxtools: A set of tools to make SAX easier to use in Python

There's a lot in Amara, but here are highlights:

Amara Bindery: XML as easy as py
--------------------------------

Based on the retired project Anobind, but updated to use SAX to create bindings.
Bindery reads an XML document and it returns a data structure of
Python objects corresponding to the vocabulary used in the XML document,
for maximum clarity.

Bindery turns the document

<monty>
  <python spam="eggs">What do you mean "bleh"</python>
  <python ministry="abuse">But I was looking for argument</python>
</monty>

Would become a set of objects so that you could write

binding.monty.python.spam

In order to get the value "eggs" or

binding.monty.python[1]

In order to get the value "But I was looking for argument".

There are other such tools for Python, and what makes Bindery unique is
that it's driven by a very declarative rules-based system for binding
XML to the Python data.  You can register rules that are triggered by
XPattern expressions specialized binding behavior.  It includes XPath
support and is very efficient, using SAX to generate bindings.

See the user documentation, manual.html, for more details.

Scimitar: exceptional schema language for an exceptional programming language
-----------------------------------------------------------------------------

Merged in from a separate project, Scimitar is an implementation of ISO
Schematron that compiles a Schematron schema into a Python validator script.

You typically use scimitar in two phases.  Say you have a schematron
schema schema1.stron and you want to validate multiple XML files
against it, instance1.xml, instance2.xml, instance3.xml.

First you run schema1.stron through the scimitar compiler script,
scimitar.py:

scimitar.py schema1.stron

A file, schema1.py (same file stem with the "py" extension sunstituted),
is generated in the current working directory.  If you'd prefer a
different location or file name, use the "-o" option. The generated file
is a validator script in Python.  It checks the schematron rules
specified in schema1.stron.

You now run the generated validator script on each XML file you wish to
validate:

python schema1.py instance1.xml

The validation report is generated on standard output by default, or you
can use the "-o" option to redirect it to a file.

The validation report is an XML external parsed entity, in other words
a file that is much like a well-formed XML document, but with some
restrictions loosened so that it's effectively text with possible
embedded tags.

Amara DOM Tools: giving DOM a more Pythonic face
------------------------------------------------

DOM came from the Java world, hardly the most Pythonic API possible.
Some DOM-like implementations such as 4Suite's Domlettes mix in some
Pythonic idiom. Amara DOM Tools goes even further.

Amara DOM Tools features pushdom, similar to xml.dom.pulldom, but
easier to use.  It also includes Python generators-based tools for
DOM processing.  And a function to return an XPath location for
any DOM node.

Amara SAX Tools: SAX without the brain explosion
------------------------------------------------

Tenorsax (amara.saxtools.tenorsax) is a framework for "linerarizing" SAX logic
so that it flows a bit more naturally, and needs a lot less state machine wizardry.

Flextyper: user-defined datatypes in Python for XML processing
--------------------------------------------------------------

Flextyper is an implementation of Jeni Tennison's Data Type Library Language (DTLL)

http://www.jenitennison.com/datatypes

You can use Flextyper to generate Python modules containing data types classes
that can be used with 4Suite's RELAX NG library.  Flextyper is currently experimental.
It won't come into its full usefulness until the next release of 4Suite,
although you can use it with current CVS releases of 4Suite.

Flextyper compiles a DTLL file into a collection of Python modules implementing
the contained data types.

License
-------

Amara is open source, provided under the 4Suite variant of the Apache
license.  See the file COPYING for details.

Installation
------------

Amara requires Python 2.3 or more recent and 4Suite-XML 1.0rc4 or more
recent.  Amara 1.1.9 added support for setuptools and easy_install, so you
can just do the following:

easy_install amara

If this does not work you are probably not set up for easy_install and I
suggest you follow the simple instructions at

http://peak.telecommunity.com/DevCenter/EasyInstall

easy_install will automatically take care of installing dependencies for
you.  If you prefer not to use easy_install, then grab a 4Suite-XML package more
recent than 1.0rc4 and install that, then install the Amara package
using the usual:

python setup.py install

Or a Windows installer, or other method.

