Author: scoder
Date: Mon Jun 18 10:49:07 2007
New Revision: 44328
Modified:
lxml/branch/lxml-1.3/INSTALL.txt
lxml/branch/lxml-1.3/doc/FAQ.txt
lxml/branch/lxml-1.3/doc/compatibility.txt
Log:
cleanup: install, compatibility, required libs (2.6.20/1.1.15)
Modified: lxml/branch/lxml-1.3/INSTALL.txt
==============================================================================
--- lxml/branch/lxml-1.3/INSTALL.txt (original)
+++ lxml/branch/lxml-1.3/INSTALL.txt Mon Jun 18 10:49:07 2007
@@ -8,10 +8,10 @@
You need libxml2 and libxslt, in particular:
-* libxml 2.6.16 or later. It can be found here:
+* libxml 2.6.20 or later. It can be found here:
http://xmlsoft.org/downloads.html
-* libxslt 1.1.12 or later. It can be found here:
+* libxslt 1.1.15 or later. It can be found here:
http://xmlsoft.org/XSLT/downloads.html
Newer versions generally contain less bugs and are therefore recommended. The
@@ -19,30 +19,31 @@
parsing horribly broken HTML. XML Schema support is also still worked on in
libxml2, so newer versions will give you better complience with the W3C spec.
-For Windows, there is a `binary distribution`_ of libxml2 and libxslt. Note
-that you need both libxml2 and libxslt, as well as iconv and zlib. You can
-then install the `binary egg distribution`_ of lxml (see below).
-.. _`binary distribution`: http://www.zlatkovic.com/libxml.en.html
-.. _`binary egg distribution`: http://cheeseshop.python.org/pypi/lxml
+Installation
+------------
-On MacOS-X 10.4, you can use the installed system libraries and the binary egg
-distribution of lxml. Note that the libxslt version on this system is older
-than the required version above. While there were not any bug reports so far,
-you may still encounter certain differences in behaviour in rare cases.
-
-If you want to build lxml from SVN, you also need Pyrex_. Please read `how to
-build lxml from source`_ in this case. If you are using a released version of
-lxml, it should come with the generated C file in the source distribution, so
-no Pyrex is needed in that case.
+If you have easy_install_, you can run the following as super-user (or
+administrator)::
-.. _Pyrex: http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/
-.. _`how to build lxml from source`: build.html
+ easy_install lxml
+
+.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
+
+This has been reported to work on Linux, MacOS-X 10.4 and Windows, as long as
+libxml2 and libxslt are properly installed (including development packages,
+i.e. header files etc.).
+
+
+Building lxml from sources
+--------------------------
-Note that Pyrex up to and including version 0.9.4 has known problems when
-compiling lxml with gcc 4.0 or Python 2.4. Do not use it. If you want to
-build lxml from non-release sources, please install Pyrex version 0.9.4.1 or
-later.
+If you want to build lxml from SVN you should read `how to build lxml from
+source`_ (or the file ``build.txt`` in the ``doc`` directory of the source
+tree). Both the subversion sources and the source distribution ship with an
+adapted version of Pyrex, so you do not need Pyrex installed.
+
+.. _`how to build lxml from source`: build.html
If you have read these instructions and still cannot manage to install lxml,
you can check the archives of the `mailing list`_ to see if your problem is
@@ -51,16 +52,30 @@
.. _`mailing list`: http://codespeak.net/mailman/listinfo/lxml-dev
-Installation
-------------
+MS Windows
+----------
-If you have easy_install_, you can run the following as super-user::
+For MS Windows, the `binary egg distribution of lxml`_ is statically built
+against the libraries, i.e. it already includes them. There is no need to
+install the external libraries if you use an official lxml build from
+cheeseshop.
+
+If you want to upgrade the libraries and/or compile lxml from sources, you
+should install a `binary distribution`_ of libxml2 and libxslt. You need both
+libxml2 and libxslt, as well as iconv and zlib.
- easy_install lxml
+.. _`binary distribution`: http://www.zlatkovic.com/libxml.en.html
+.. _`binary egg distribution of lxml`: http://cheeseshop.python.org/pypi/lxml
-.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
-This has been reported to work on Linux, MacOS-X 10.4 and Windows, as long as
-libxml2 and libxslt are properly installed. To compile and install lxml
-without easy_install, please read `how to build lxml from source`_ (or the
-file ``build.txt`` in the ``doc`` directory of the source tree).
+MacOS-X
+-------
+
+On MacOS-X 10.4, you can try to use the installed system libraries when you
+build lxml yourself. However, the library versions on this system are older
+than the required versions, so you may encounter certain differences in
+behaviour or even crashes. A number of users reported success with updated
+libraries (e.g. using fink_), but needed to set the environment variable
+``DYLD_LIBRARY_PATH`` to the directory where fink keeps the libraries.
+
+.. _fink: http://finkproject.org/
Modified: lxml/branch/lxml-1.3/doc/FAQ.txt
==============================================================================
--- lxml/branch/lxml-1.3/doc/FAQ.txt (original)
+++ lxml/branch/lxml-1.3/doc/FAQ.txt Mon Jun 18 10:49:07 2007
@@ -91,7 +91,7 @@
strictly compliant way. As of release 2.4.16, libxml2 passed all 1800+ tests
from the OASIS XML Tests Suite.
-lxml currently supports libxml2 2.6.16 or later, which has even better support
+lxml currently supports libxml2 2.6.20 or later, which has even better support
for various XML standards. Some of the more important ones are: HTML, XML
namespaces, XPath, XInclude, XSLT, XML catalogs, canonical XML, RelaxNG,
XML:ID. Support for XML Schema and Schematron is currently incomplete in
@@ -105,7 +105,8 @@
It really depends on your application, but the rule of thumb is: more recent
versions contain less bugs and provide more features.
-* Try to use versions of both libraries that were released together.
+* Try to use versions of both libraries that were released together. At least
+ the libxml2 version should not be older than the libxslt version.
* If you use XML Schema or Schematron which are still under development, the
most recent version of libxml2 is usually a good bet.
@@ -117,10 +118,10 @@
* For parsing and fixing broken HTML, lxml requires at least libxml2 2.6.21.
* For the normal tree handling, however, any libxml2 version starting with
- 2.6.16 should do.
+ 2.6.20 should do.
Read the `release notes of libxml2`_ and the `release notes of libxslt`_ to
-see if a specific bug has been fixed.
+see when (or if) a specific bug has been fixed.
.. _`release notes of libxml2`: http://xmlsoft.org/news.html
.. _`release notes of libxslt`: http://xmlsoft.org/XSLT/news.html
Modified: lxml/branch/lxml-1.3/doc/compatibility.txt
==============================================================================
--- lxml/branch/lxml-1.3/doc/compatibility.txt (original)
+++ lxml/branch/lxml-1.3/doc/compatibility.txt Mon Jun 18 10:49:07 2007
@@ -1,3 +1,4 @@
+=============================
lxml.etree versus ElementTree
=============================
@@ -25,12 +26,8 @@
# use
from lxml import etree as ElementTree
-* Some minor parts of the API of ElementTree have not yet been implemented and
- are thus missing in lxml.etree. Feel free to help out!
-
-* Then again, lxml.etree offers a lot more functionality, such as
- XPath, XSLT, Relax NG, and XML Schema support, which (c)ElementTree
- does not offer.
+* lxml.etree offers a lot more functionality, such as XPath, XSLT, Relax NG,
+ and XML Schema support, which (c)ElementTree does not offer.
* etree has a different idea about Python unicode strings than ElementTree.
In most parts of the API, ElementTree uses plain strings and unicode strings
@@ -77,32 +74,40 @@
<c><b/></c>
- Unfortunately this is a rather fundamental difference in behavior, which
- will be hard to solve. It won't affect some applications, but if you want
- to port code you must unfortunately make sure that it doesn't.
+ Unfortunately this is a rather fundamental difference in behavior, which is
+ hard to change. It won't affect some applications, but if you want to port
+ code you must unfortunately make sure that it doesn't affect yours.
+
+* etree allows navigation to the parent of a node by the ``getparent()``
+ method and to the siblings by calling ``getnext()`` and ``getprevious()``.
+ This is not possible in ElementTree as the underlying tree model does not
+ have this information.
* When trying to set a subelement using __setitem__ that is in fact not an
Element but some other object, etree raises a TypeError, and ElementTree
raises an AssertionError. This also applies to some other places of the
- API. In general, etree tries to avoid AssertionErrors in favour of being
+ API. In general, etree tries to avoid AssertionErrors in favour of being
more specific about the reason for the exception.
-* When parsing fails in ``iterparse()``, ElementTree raises an ExpatError
- instead of a SyntaxError. lxml.etree follows the other parts of the parser
- API and raises an (XML)SyntaxError.
+* When parsing fails in ``iterparse()``, ElementTree raises a low-level
+ ExpatError instead of a SyntaxError as the other parsers. lxml.etree
+ follows the other parts of the parser API and raises an (XML)SyntaxError.
* The ``iterparse()`` function in lxml is implemented based on the libxml2
- parser. This means that modifications of the document root or the ancestors
- of the current element during parsing can irritate the parser and even
- segfault. While this is not a problem in the Python object structure used
- by ElementTree, the C tree underlying lxml suffers from it. The golden rule
- for ``iterparse()`` on lxml therefore is: do not touch anything that will
- have to be touched again by the parser later on. See the lxml API
- documentation on this.
+ parser and tree generator. This means that modifications of the document
+ root or the ancestors of the current element during parsing can irritate the
+ parser and even segfault. While this is not a problem in the Python object
+ structure used by ElementTree, the C tree underlying lxml suffers from it.
+ The golden rule for ``iterparse()`` on lxml therefore is: do not touch
+ anything that will have to be touched again by the parser later on. See the
+ lxml parser documentation on this.
* ElementTree ignores comments and processing instructions when parsing XML,
while etree will read them in and treat them as Comment or
- ProcessingInstruction elements respectively.
+ ProcessingInstruction elements respectively. This is especially visible
+ where comments are found inside text content, which is then split by the
+ Comment element. You can disable this behaviour by passing the boolean
+ ``remove_comments`` keyword argument to the parser you use.
* ElementTree has a bug when serializing an empty Comment (no text argument
given) to XML, etree serializes this successfully.
@@ -113,18 +118,19 @@
* ElementTree merges the target of a processing instruction into ``PI.text``,
while lxml.etree puts it into the ``.target`` property and leaves it out of
- the ``.text`` property.
+ the ``.text`` property. The ``pi.text`` in ElementTree therefore
+ correspondents to ``pi.target + " " + pi.text`` in lxml.etree.
* Because etree is built on top of libxml2, which is namespace prefix aware,
etree preserves namespaces declarations and prefixes while ElementTree tends
to come up with its own prefixes (ns0, ns1, etc). When no namespace prefix
- is given however, etree creates ElementTree style prefixes as well.
+ is given, however, etree creates ElementTree style prefixes as well.
* etree has a 'prefix' attribute (read-only) on elements giving the Element's
prefix, if this is known, and None otherwise (in case of no namespace at
all, or default namespace).
- etree further allows passing an 'nsmap' dictionary to the Element and
+* etree further allows passing an 'nsmap' dictionary to the Element and
SubElement element factories to explicitly map namespace prefixes to
namespace URIs. These will be translated into namespace declarations on
that element. This means that in the probably rare case that you need to
@@ -132,13 +138,9 @@
ElementTree, you cannot pass it as a keyword argument to the Element and
SubElement factories directly.
-* etree elements can be copied using copy.deepcopy() and copy.copy(), just
- like ElementTree's. copy.copy() however does *not* create a shallow copy
- where elements are shared between trees, as this makes no sense in the
- context of libxml2 trees. Note that lxml can deep-copy trees considerably
- faster than ElementTree.
-
-* etree allows navigation to the parent of a node by the ``getparent()``
- method and to the siblings by calling ``getnext()`` and ``getprevious()``.
- This is not possible in ElementTree as the underlying tree model does not
- have this information.
+* etree elements can be copied using ``copy.deepcopy()`` and ``copy.copy()``,
+ just like ElementTree's. However, ``copy.copy()`` does *not* create a
+ shallow copy where elements are shared between trees, as this makes no sense
+ in the context of libxml2 trees. Note that lxml can deep-copy trees
+ considerably faster than ElementTree, so a deep copy might still be fast
+ enough to replace a shallow copy in your case.
|
