libxml2dom

Annotated README.txt

311:62677a2566f0
2007-10-01 paulb [project @ 2007-10-01 23:27:18 by paulb] Changed the tests to work with the updated API.
paulb@108 1
Introduction
paulb@108 2
------------
paulb@108 3
paulb@20 4
See docs/index.html for the libxml2dom documentation.
paulb@35 5
paulb@245 6
Compatibility Warnings
paulb@245 7
----------------------
paulb@245 8
paulb@245 9
From libxml2dom 0.4, nodeValue now returns different results in some cases.
paulb@245 10
Previously, it was possible to get the textual contents of an element using
paulb@245 11
the nodeValue property, although this is incompatible with the DOM
paulb@245 12
specifications. Instead, you should now use the textContent property to get
paulb@245 13
such data.
paulb@245 14
paulb@108 15
Contact, Copyright and Licence Information
paulb@108 16
------------------------------------------
paulb@108 17
paulb@108 18
The current Web page for libxml2dom at the time of release is:
paulb@108 19
paulb@108 20
http://www.boddie.org.uk/python/libxml2dom.html
paulb@108 21
paulb@108 22
Copyright and licence information can be found in the docs directory - see
paulb@292 23
docs/COPYING.txt, docs/lgpl-3.0.txt and docs/gpl-3.0.txt for more information.
paulb@108 24
paulb@108 25
Dependencies
paulb@108 26
------------
paulb@108 27
paulb@108 28
libxml2     Tested with libxml2 2.6.17.
paulb@108 29
            Use --with-python=<path to python executable> if building from
paulb@108 30
            source. Previous releases of libxml2 in the 2.6 series may work,
paulb@108 31
            but releases before 2.6.16 are not recommended.
paulb@222 32
paulb@222 33
            For Windows users, see also the packages for libxml2, available
paulb@222 34
            from the following site:
paulb@222 35
paulb@222 36
            http://users.skynet.be/sbi/libxml-python/
paulb@222 37
paulb@108 38
Python      Tested with Python 2.4.
paulb@108 39
            Python releases from 2.2 onwards should be compatible with
paulb@108 40
            libxml2dom. The principal requirement from such releases is the
paulb@108 41
            new-style class support which permits the use of properties in
paulb@108 42
            the libxml2dom implementation.
paulb@108 43
paulb@64 44
Testing
paulb@64 45
-------
paulb@64 46
paulb@64 47
Some of the tests require libxml2macro.py to be run on the test source code
paulb@64 48
first. Read the docstrings for the various test files before attempting to run
paulb@145 49
any of them. See also docs/NOTES_libxml2macro.txt for more information. Note
paulb@145 50
that such tests are retained for historical purposes and/or curiosity since
paulb@145 51
libxml2macro.py is no longer supported.
paulb@64 52
paulb@35 53
Issues
paulb@35 54
------
paulb@35 55
paulb@178 56
The presence of xmlns attributes in serialised documents was called into
paulb@191 57
question, and the tests/namespace*.py files attempt to show the current
paulb@191 58
behaviour of libxml2dom.
paulb@178 59
paulb@35 60
Use of importNode seems to cause some kind of memory issue, probably related
paulb@41 61
to nodes being shared across documents. This was observed in libxml2 2.6.0 but
paulb@41 62
appears to be fixed in libxml2 2.6.16.
paulb@50 63
paulb@78 64
Even compared to minidom, importNode may seem very slow (even the
paulb@50 65
libxml2dom.macrolib implementation, too). A way is needed to get libxml2 to do
paulb@50 66
the node copying itself.
paulb@50 67
paulb@303 68
New in libxml2dom 0.4.5 (Changes since libxml2dom 0.4.4)
paulb@303 69
--------------------------------------------------------
paulb@303 70
paulb@303 71
  * Fixed operations involving the standard XML_NAMESPACE value, particularly
paulb@303 72
    setAttributeNS.
paulb@303 73
  * Introduced deletion of conflicting attributes in setAttributeNS.
paulb@303 74
  * Added slightly nicer errors for parsing and serialising.
paulb@306 75
  * Added some support for SOAP and XML-RPC message processing.
paulb@303 76
paulb@288 77
New in libxml2dom 0.4.4 (Changes since libxml2dom 0.4.3)
paulb@288 78
--------------------------------------------------------
paulb@288 79
paulb@292 80
  * Relicensed under the LGPL version 3 or later (fixing PKG-INFO file).
paulb@288 81
  * Improved XMPP support for messages, presence and events.
paulb@297 82
  * Added Ubuntu Feisty (7.04) package support.
paulb@288 83
paulb@261 84
New in libxml2dom 0.4.3 (Changes since libxml2dom 0.4.2)
paulb@261 85
--------------------------------------------------------
paulb@261 86
paulb@267 87
  * Enforced well-formedness in parse operations unless otherwise requested.
paulb@275 88
  * Fixed access to null doctype properties.
paulb@275 89
  * Added getElementById, firstChild and lastChild to the Node class.
paulb@261 90
  * Added a __hash__ method to the Node class.
paulb@275 91
  * Moved document checking into the Node class.
paulb@275 92
  * Added an iterator for the NamedNodeMap class.
paulb@261 93
  * Expanded the svg and events modules, including a test of SVG events.
paulb@279 94
  * Split the debian-stable packages into debian-sarge and debian-etch.
paulb@261 95
paulb@255 96
New in libxml2dom 0.4.2 (Changes since libxml2dom 0.4.1)
paulb@255 97
--------------------------------------------------------
paulb@255 98
paulb@255 99
  * Added missing impl attribute to NamedNodeMap, fixing attribute retrieval.
paulb@255 100
  * Added documentElement to Document.
paulb@255 101
  * Fixed and expanded the events module.
paulb@255 102
  * Added lots of functionality to the svg module.
paulb@255 103
paulb@250 104
New in libxml2dom 0.4.1 (Changes since libxml2dom 0.4)
paulb@250 105
------------------------------------------------------
paulb@250 106
paulb@250 107
  * Fixed the absence of CDATA node creation and importing.
paulb@250 108
paulb@217 109
New in libxml2dom 0.4 (Changes since libxml2dom 0.3.6)
paulb@217 110
------------------------------------------------------
paulb@217 111
paulb@222 112
  * Changed the nodeValue property to return None for various node types, as
paulb@222 113
    specified in the DOM specification (Level 3).
paulb@226 114
  * Fixed various "not supported" exceptions and added tests which can raise
paulb@226 115
    "wrong document" exceptions.
paulb@217 116
  * Introduced an Implementation class, permitting specialised node creation.
paulb@217 117
  * Added SVG-specific document support.
paulb@231 118
  * Made parseURI work for HTML documents.
paulb@231 119
  * Fixed getElementsByTagName(NS), as reported by Christian Seiler.
paulb@239 120
  * Fixed previousSibling, nextSibling and parentNode crashes using
paulb@239 121
    suggestions from Christian Seiler.
paulb@239 122
  * Reintroduced node comparisons using suggestions from Christian Seiler.
paulb@242 123
  * Fixed the absence of the CDATA node type.
paulb@234 124
  * Added the textContent property to nodes.
paulb@239 125
  * Added a getDOMImplementation function.
paulb@234 126
  * Added an experimental events module.
paulb@245 127
  * Added an htmlencoding parameter to the parse functions, as requested by
paulb@245 128
    Iliyan Peychev.
paulb@217 129
paulb@207 130
New in libxml2dom 0.3.6 (Changes since libxml2dom 0.3.5)
paulb@207 131
--------------------------------------------------------
paulb@207 132
paulb@207 133
  * Added cloneNode almost as a synonym for importNode (which, unlike in the
paulb@207 134
    DOM specification, is present on all nodes).
paulb@210 135
  * Introduced Debian stable package details - suggested by Robert Siemer.
paulb@213 136
  * Changed libxml2mod import details to try libxmlmods - suggested by Lucian
paulb@213 137
    Wischik.
paulb@207 138
paulb@201 139
New in libxml2dom 0.3.5 (Changes since libxml2dom 0.3.4)
paulb@201 140
--------------------------------------------------------
paulb@201 141
paulb@201 142
  * Fixed nodeType for HTML document elements - reported by Robert Siemer.
paulb@201 143
  * Fixed string results from XPath expressions - reported by Robert Siemer.
paulb@201 144
paulb@191 145
New in libxml2dom 0.3.4 (Changes since libxml2dom 0.3.3)
paulb@191 146
--------------------------------------------------------
paulb@191 147
paulb@191 148
  * Attempted to introduce generated prefixes for attributes having namespaces
paulb@191 149
    but whose names are unprefixed.
paulb@195 150
  * Added support for xmlns attribute retrieval (getAttributeNS) and detection
paulb@195 151
    (hasAttributeNS).
paulb@197 152
  * Added the length attribute to NamedNodeMap; renamed the length method on
paulb@197 153
    NodeList, adding a length attribute.
paulb@191 154
paulb@187 155
New in libxml2dom 0.3.3 (Changes since libxml2dom 0.3.2)
paulb@187 156
--------------------------------------------------------
paulb@187 157
paulb@187 158
  * Removed redundant weakref usage.
paulb@187 159
  * Added explicit copyright and licensing information to source files.
paulb@187 160
paulb@183 161
New in libxml2dom 0.3.2 (Changes since libxml2dom 0.3.1)
paulb@183 162
--------------------------------------------------------
paulb@183 163
paulb@183 164
  * Improved the xmlns attribute creation controls.
paulb@183 165
paulb@165 166
New in libxml2dom 0.3.1 (Changes since libxml2dom 0.3)
paulb@165 167
------------------------------------------------------
paulb@165 168
paulb@165 169
  * Fixed empty namespace declarations on elements created with namespaceURI
paulb@165 170
    set to None. Previously, such declarations were missing.
paulb@178 171
  * Fixed attribute creation and introduced stricter controls over the
paulb@178 172
    construction of xmlns attributes.
paulb@165 173
paulb@158 174
New in libxml2dom 0.3 (Changes since libxml2dom 0.2.4)
paulb@158 175
------------------------------------------------------
paulb@153 176
paulb@158 177
  * Imposed much stricter tests on strings used with the libxml2dom API.
paulb@158 178
    Strings given as arguments to methods and functions must now only contain
paulb@158 179
    ASCII characters; any other character data must be provided as Unicode
paulb@158 180
    objects. This change fixes various issues with XPath expressions, and
paulb@158 181
    quite probably various other things.
paulb@153 182
  * Fixed parentNode on Document objects (which caused xml.dom.ext.PrettyPrint
paulb@153 183
    to crash).
paulb@153 184
  * Added some support for the doctype attribute and related information.
paulb@158 185
  * libxml2dom is now licensed under the LGPL - see docs/COPYING.txt for
paulb@158 186
    details.
paulb@153 187
paulb@148 188
New in libxml2dom 0.2.4 (Changes since libxml2dom 0.2.3)
paulb@148 189
--------------------------------------------------------
paulb@148 190
paulb@148 191
  * Fixed Unicode conversions in the Node's xpath method.
paulb@148 192
paulb@135 193
New in libxml2dom 0.2.3 (Changes since libxml2dom 0.2.2)
paulb@135 194
--------------------------------------------------------
paulb@135 195
paulb@135 196
  * Fixed the parse function's docstring.
paulb@139 197
  * Added the owner element to obtained attribute nodes.
paulb@142 198
  * Fixed Debian package changelog distribution identifiers.
paulb@135 199
paulb@129 200
New in libxml2dom 0.2.2 (Changes since libxml2dom 0.2.1)
paulb@129 201
--------------------------------------------------------
paulb@129 202
paulb@129 203
  * Fixed exception raising in parseURI, adding a docstring to explain the
paulb@129 204
    current limitations around HTML parsing.
paulb@129 205
paulb@108 206
New in libxml2dom 0.2.1 (Changes since libxml2dom 0.2)
paulb@108 207
------------------------------------------------------
paulb@108 208
paulb@118 209
  * Moved libxml2macro script to the tools directory.
paulb@118 210
  * Added getElementsByTagNameNS.
paulb@123 211
  * Added a normalize implementation.
paulb@118 212
  * Added HTML parsing support.
paulb@120 213
  * Added prettyprinting support.
paulb@118 214
  * Fixed parseURI.
paulb@118 215
  * Introduced better testing for Unicode objects, especially since things
paulb@118 216
    like rdflib like to subclass the unicode type, and it might be more
paulb@118 217
    convenient to detect such subclasses and convert their values
paulb@118 218
    automatically.
paulb@118 219
  * Improved some of the API documentation.
paulb@118 220
  * Introduced better suppression of warnings, network access, and other
paulb@118 221
    potentially intrusive libxml2 features.
paulb@118 222
  * Reorganised the documentation, expanding the README.txt file at the
paulb@118 223
    expense of the HTML documentation, but removing older, less relevant
paulb@118 224
    information.
paulb@118 225
  * Added Debian package support.
paulb@50 226
paulb@108 227
New in libxml2dom 0.2 (Changes since libxml2dom 0.1.3)
paulb@108 228
------------------------------------------------------
paulb@108 229
paulb@118 230
  * Adopted libxml2macro code within the libxml2dom classes, removing any
paulb@118 231
    dependencies on the libxml2 module - this makes everything much faster
paulb@118 232
    and virtually removes any necessity to use libxml2macro.
paulb@118 233
  * Improved attribute and document node handling.
paulb@118 234
  * Introduced document reference management.
paulb@118 235
  * Introduced NodeList wrapper objects.
paulb@59 236
paulb@108 237
New in libxml2dom 0.1.3 (Changes since libxml2dom 0.1.2)
paulb@108 238
--------------------------------------------------------
paulb@108 239
paulb@118 240
  * Fixed createElement.
paulb@118 241
  * Introduced experimental libxml2macro tools, tests and libraries.
paulb@108 242
paulb@108 243
New in libxml2dom 0.1.2 (Changes since libxml2dom 0.1.1)
paulb@108 244
--------------------------------------------------------
paulb@59 245
paulb@118 246
  * Fixed getAttributeNode and getAttributeNodeNS.
paulb@118 247
  * Added comment node creation.
paulb@118 248
  * Fixed empty namespace usage with elements and attributes.
paulb@118 249
  * Introduced usage of the libxml2 file and memory parsing features.
paulb@118 250
  * Introduced suppression of DTD retrieval and validation as the default
paulb@118 251
    behaviour.
paulb@118 252
  * Added experimental XPath method support.
paulb@59 253
paulb@108 254
New in libxml2dom 0.1.1
paulb@108 255
-----------------------
paulb@59 256
paulb@118 257
  * Fixed text node creation.
paulb@118 258
  * Fixed setAttributeNS.
paulb@118 259
  * Added encoding parameters to convenience methods.
paulb@118 260
  * Added the missing previousSibling property.
paulb@118 261
  * Added release number to the package.
paulb@59 262
paulb@108 263
Release Procedures
paulb@108 264
------------------
paulb@59 265
paulb@108 266
Update the libxml2dom/__init__.py and libxml2dom/macrolib/__init__.py
paulb@108 267
__version__ attributes.
paulb@108 268
Change the version number and package filename/directory in the documentation.
paulb@108 269
Change code examples in the documentation if appropriate.
paulb@108 270
Update the release notes (see above).
paulb@108 271
Update the package release notes (in the packages directory).
paulb@108 272
Check the setup.py file and ensure that all package directories are mentioned.
paulb@183 273
Check the release information in the PKG-INFO file.
paulb@108 274
Tag, export.
paulb@108 275
Archive, upload.
paulb@108 276
Make packages (see below).
paulb@108 277
Update PyPI, PythonInfo Wiki, Vaults of Parnassus entries.
paulb@59 278
paulb@108 279
Making Packages
paulb@108 280
---------------
paulb@59 281
paulb@125 282
To make Debian-based packages:
paulb@59 283
paulb@125 284
  1. Create new package directories under packages if necessary.
paulb@118 285
  2. Make a symbolic link in the distribution's root directory to keep the
paulb@210 286
     Debian tools happy; choose one of the following:
paulb@59 287
paulb@125 288
     ln -s packages/ubuntu-hoary/python2.4-libxml2dom/debian/
paulb@285 289
     ln -s packages/debian-sarge/python2.3-libxml2dom/debian/
paulb@285 290
     ln -s packages/debian-etch/python-libxml2dom/debian/
paulb@108 291
paulb@118 292
  3. Run the package builder:
paulb@108 293
paulb@118 294
     dpkg-buildpackage -rfakeroot
paulb@108 295
paulb@118 296
  4. Locate and tidy up the packages in the parent directory of the
paulb@118 297
     distribution's root directory.