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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
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>
|
