File: README

package info (click to toggle)
amara 1.2a2-1
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 796 kB
  • ctags: 876
  • sloc: python: 8,650; xml: 1,450; makefile: 8; sh: 4
file content (152 lines) | stat: -rw-r--r-- 5,365 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
Amara XML Toolkit 1.2a2 (released 29 October 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-stron.py, 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.

Run this validator 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, a format much like
a well-formed XML document, but with some restrictions relaxed.

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

Amara DOM Tools features pushdom, similar to xml.dom.pulldom, but easier
to use, 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 it flows a bit more naturally, needing much less state machine wizardry.

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.0.1 or more
recent.  It supports 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, grab a 4Suite-XML package more
recent than 1.0.1 and install that, then install the Amara package
using the usual:

python setup.py install

Or a Windows installer, or other method.

Building documentation
----------------------

Most distributions/binary packages have documentation built in, but
If you want to build the documentation yourself, then as long as you do
not have setuptools installed, you can just do:

python setup.py -s config install

If you do have setuptools installed, set AMARA_FTSETUP=1 in the environment
before running the above.  If you do not want to use the default install paths
You can use the --prefix argument, for example:

python setup.py -s install --prefix=$WHERE_YOU_WANT_STUFF

Or just use the usual Python distutils config files:

http://docs.python.org/inst/config-syntax.html