# YAXL #
## Yet Another (Pythonic) XML Library v0.0.15 ##

<img src="../osi-certified.png" align="right" border="0" hspace="5" />
[YAXL](http://www.ilowe.net/software/yaxl) is a library for reading, writing and manipulating [XML](http://www.w3.org/TR/REC-xml/) in [Python](http://www.python.org/).

YAXL is **OSI Certified Open Source Software** released under the MIT License. This means you are free to download it and do (almost) whatever you want with it.

### Requirements

	* [Python](http://www.python.org) version 2.4 or higher

### Features

Here's the list of things I really wanted:

	* Requires only Python 2.4+
	* Learnable in 15 minutes
    * Simplest interface possible - minimal number of functions and objects exported
	* [XML Namespace](http://www.w3.org/TR/REC-xml-names) aware
	* [XPath](http://www.w3.org/TR/xpath) support
	* Easy to create [XML](http://www.w3.org/TR/REC-xml/) documents and fragments
	* Easy to read in and manipulate [XML](http://www.w3.org/TR/REC-xml/) documents and fragments
	
Let me know at [ilowe@cryogen.com](mailto:ilowe@cryogen.com) whether or not I'm succeeding.

### Download

The latest version of YAXL is available in the following formats:
	
	* [Python Egg](dist/yaxl-0.0.15-py2.4.egg) for use with [setuptools](http://peak.telecommunity.com/DevCenter/setuptools)
	* [Windows installer](dist/yaxl-0.0.15.win32.exe) for use on Windows
	* [Source distribution](dist/yaxl-0.0.15.zip) if you want to hack around
	
You can download previous versions from the [distribution archive](dist).

### Usage

Check out [Developing with YAXL](developing-with-yaxl.html) for more details. YAXL also comes with extensive online documentation. Use code like the following to access the module's built-in help:

	>>> import yaxl
	>>> help(yaxl)

### Future Enhancements

	* XPath support needs to be improved (add `following`, `following-sibling`, `preceding`, `preceding-sibling` and `namespace` axes; handle functions)
	* Re-organize module to embed test suite so it can be run from the Python Egg distro
    * allow setting attributes via keyword arguments to append and to the Element constructor
	* allow you to call window=Element(); window.head().title(text='fdgdg');	
	* add stylesheet to asdoc
	
### Changes
    
    * (2005-11-16) Maintenance release 0.0.15 has more test cases passing and fixes a bug with `help(yaxl)` where the help file was not found
    * (2005-10-24) Added `*`, `text()` and `node()` predicates for `child` and `attribute` axes
    * (2005-10-19) Added `detach` method to elements
    * (2005-10-19) Added support for `append`ing an element to another
    * (2005-10-16) Split string/XML representation of elements per Damian Cugley's suggestion
    * (2005-10-10) Added `=`, `!=`, `>=`, `<=`, `<`, `>` and existance predicates for XPath	
    * (2005-10-10) Added automated testing of documentation examples
	* (2005-10-09) Basic encoding support added (read/write)
    * (2005-10-09) Modified internal module structure
	* (2005-10-08) Plays nice with default namespaces now
	* (2005-10-08) Unit test refactoring
	* (2005-10-08) Added sequence-style access for child nodes
	* (2005-10-08) Added modification-safe iterator support over children
	* (2005-10-08) Added namespace "re-mapping" - now handles the case where a namespace mapped in an ancestor is deleted properly
	* (2005-10-08) Tightened up constraints for `Element` equality
    * (2005-10-08) Cleanup in `find_ns`
    * (2005-10-08) Fixed `feature_namespace_prefixes` not handled by expat bug, 
    * (2005-10-06) Fixed a bug when QName is `None` when the SAX parser calls `startElementNS` - now the `feature_namespace_prefixes` feature is explicitly enabled and the XML builder has some fallback code that parses the QName properly from the namespace and the element name by searching current namespace mappings
	* (2005-10-06) Added abbreviated syntax for all supported axes, added existance predicate (select this node if it has a child named such-and-such or an attribute named such-and-such)
	* (2005-10-05) Added support for unabbreviated XPath location steps for `child`, `descendant`, `parent`, `self`, `ancestor`, `attribute`, `descendant-or-self`, `ancestor-or-self`	

### Aknowledgements

The following people have submitted bug reports or enhancement suggestions: Marc, "Crest", Marcus Gna and [Damian Cugley](http://www.blogger.com/profile/3448376). Thank you all for your contribution!

### Why another XML library? Especially for Python?

I looked around (even spent some time sifting through Uche Ogbuji's
[State of Python-XML in 2004](http://www.xml.com/pub/a/2004/10/13/py-xml.html) with its 74 projects)
and couldn't find anything I liked. The existing modules were all "un-Pythonic" (for some value of "Pythonic") or just didn't have the exact flavour I wanted. Whatever.

I know that most Pythonistas look down on XML a bit but you really
need to use it to get by in most web projects, especially those involving data formats.
So unless you want to spend hours hand-coding XML you are stuck painstakingly
struggling with SAX and DOM interfaces. This is also highlighted by the
over-abundance of XML processing/parsing/binding/etc. frameworks available for Python.

I opted for the time-honoured tradition of re-inventing the wheel. I built this library
mostly for use with [my Atom library](http://www.ilowe.net/software/atom/).

### Inspiration

I shamelessly spent hours poring over the following projects and ripping out all the
coolest features to create this one:

	* Frederik Lundh's [ElementTree](http://effbot.org/zone/element-index.htm) is what I consider to be the best all-around XML library out there
	* Aaron Swartz's [xmltramp](http://www.aaronsw.com/2002/xmltramp/) is the inspiration for the extreme simplicity of the YAXL interface
	* Philippe Normand's [EaseXML](http://easexml.base-art.net/) is more of a Python/XML mapping library than a pure XML manipulation library
	* Fourthought Inc's [4suite](http://4suite.org) is probably the most complete in terms of standards-compliant support for XML and XML-related technologies (DOM, RDF, XSLT, XInclude, XPointer, XLink, XPath, XUpdate, RELAX NG, and XML/SGML Catalogs)
	* [lxml](http://codespeak.net/lxml/) provides a Pythonic binding for the [libxml2](http://xmlsoft.org/) and [libxslt](http://xmlsoft.org/XSLT) libraries which were written in C for the [Gnome](http://www.gnome.org) project

### References

	* Henri Sivonen's paper on [HOWTO Avoid Being Called a Bozo When Producing XML](http://hsivonen.iki.fi/producing-xml/)

### Contact

You can reach me at [ilowe@cryogen.com](mailto:ilowe@cryogen.com) with feedback.

***

<div class="copyright">Copyright (C) 2005 by Iain Lowe</div>