Back to files

jaxml v3.01 - June 26th 2003
(C) Jerome Alet <alet@librelogiciel.com> 2000-2003 You're welcome to redistribute this software under the terms of the GNU General Public Licence version 2.0 or, at your option, any higher version.

You can read the complete GNU GPL in the file COPYING which should come along with this software, or visit the Free Software Foundation's WEB site http://www.fsf.org

I was recently asked if the GPL meant that if you just import this module then you should license your software under the GPL, here's the answer:

You've written a software which uses (import) my GPLed module.

If you don't plan to redistribute your software (e.g. internal use only), then you can do whatever you want, and hide your software's sources from your co-workers if you want (but not my software's sources).
BUT, if you want to redistribute your software to a third party, then your software MUST be GPLed too, and distributed with all its sources.

Please consider this module just like a GPLed C library, not a LGPLed one.

I hope this is clearer now. Just refer to the GPL (the file COPYING) for details.

FYI I've choosen to GPL this module because I strongly believe in the Free Software movement, and want to discourage the creation of proprietary software.

This python module defines a class named XML_document which will allow you to generate XML documents (yeah !) more easily than using print or similar functions.

Here's a list of available methods:

        __init__(version, encoding)
                The instance constructor, automatically called
                when you create a new instance of XML_document.
                you can optionnally pass a version and encoding
                string, the defaults are "1.0" and "iso-8859-1".

        _indentstring(istr)
                istr is the new indentation string used
                to nicely present your XML documents. By
                default istr is equal to 4 space characters.

        _output(filearg)
                use it to save the XML document to a file.
                The optionnal filearg argument may be:
                    None, "", or "-" which stands for sys.stdout.
                    a file name.
                    any file object.

        _text(sometext)
                use it to insert plain text at the current position
                in the document.

        _push()
                saves the current position in the XML document.
                use it if you're going to create a bunch of nested
                XML tags and want to escape from them later to continue
                your document at the same indentation level.
                you can pass an optional 'name' argument, to mark
                a position by its name.

        _pop()
                restores the latest saved position.
                use it to escape from nested tags and continue
                your XML document at the same indentation level than
                the latest time you called _push().
                you can pass an optional 'name' argument, to continue
                at the same indentation level as when you called _push()
                with the same 'name' argument.

        _template(file, **vars)
                loads a template file and insert it as plain text at the current
                position in the document, replacing #varname# variables
                in the template file with their corresponding value passed
                in vars[varname]

        _updatemapping(newmap)
                updates the internal mapping used for replacing some strings with
                others when rendering. This can be used as an easy way to
                do templating without the need of an external file.
                Pass None or no argument to reset the mapping to an empty one.
                This method returns the new mapping's content.

        Some more methods are available but not meant to be used directly, they

are: __nonzero__, __getitem__, __setitem__, __delitem__, __coerce__, __add__, __radd__, __mul__, __rmul__, and __copy__. They are used automatically when doing special things, read the source for details.

ANY and ALL other method you may call will be treated as an XML tag, unless it already exists as a method in XML_document or a subclass of it, or its name begins with "__". I suggest you to only add methods whose names begin with '_' to keep things simple and clear: "__" is reserved for future use.

The file test/test.py is an example program which generates some documents, just play with it (use and modify) and you'll learn quickly how to use jaxml. Its source code is documented and attempts at describing and trying all jaxml's possibilities, so reading it is probably the best way to become powerful with jaxml in less than 10 minutes.

Really, PLEASE READ the file test/test.py to learn all possibilities, newer possibilities are at the end of the file.

Since version 2.00, jaxml integrates the full functionnalities of the old jahtml module via the HTML_document and CGI_document classes, however the API for these two classes has changed to be cleaner and don't use any predefined set of tags.

The HTML_document() and CGI_document() classes both inherit from XML_document() and all its methods (see above), but also feature some useful helper methods.

Please read the jaxml module sources and the test/test.py program to learn how to use them.

The only difficult things are:

you have to use the _push() and _pop() methods if you need to get out of a bunch of nested tags.
if you call a method (tag) with a string as the first unnamed parameter, you won't need _push() or _pop() because your tag will be automatically closed immediately.
if you call a method (tag) with a python mapping as the first or second unamed parameter, this mapping is used to correctly handle XML namespaces or attributes which are python reserved words (e.g. class), please look at test/test.py to see an example.

INSTALLATION

If you don't have Distutils installed (e.g. python version <= 1.5.2) then first download it from:

http://www.python.org/sigs/distutils-sig/

then follow the installation instructions for Distutils and install it on your system.

Download the latest jaxml version from:

http://www.librelogiciel.com/software/

Extract it:

gzip -d jaxml-x.xx.tar.gz | tar -xf -

where x.xx is jaxml's latest version number.

Go to jaxml directory:

cd jaxml-x.xx

Just type:

python setup.py install

You may need to be logged in with sufficient privileges (e.g. root)

You can optionnaly go to the test subdirectory and run test.py, this should produce some XML output both on the screen and in a file named sampleXML.xml

If you've got the old jahtml module, then you can remove it from your disk, after having modified your programs to use the new jaxml API.

Voilà !

You're very welcome to send me any idea or patch about this module.

See the CREDITS file for credits.

Always remember that the test/test.py program and the jaxml.py module's source code are your best friends.

I hope this will be helpful to someone else.

Feedback is very welcome.

Jerome Alet - <alet@librelogiciel.com>