[Lxml-checkins] r52115 - in lxml/trunk: . doc doc/html
scoder at codespeak.net
scoder at codespeak.net
Mon Mar 3 19:43:16 CET 2008
Author: scoder
Date: Mon Mar 3 19:43:14 2008
New Revision: 52115
Modified:
lxml/trunk/ (props changed)
lxml/trunk/CHANGES.txt
lxml/trunk/doc/FAQ.txt
lxml/trunk/doc/api.txt
lxml/trunk/doc/capi.txt
lxml/trunk/doc/compatibility.txt
lxml/trunk/doc/cssselect.txt
lxml/trunk/doc/element_classes.txt
lxml/trunk/doc/elementsoup.txt
lxml/trunk/doc/extensions.txt
lxml/trunk/doc/html/style.css
lxml/trunk/doc/lxml2.txt
lxml/trunk/doc/lxmlhtml.txt
lxml/trunk/doc/mkhtml.py
lxml/trunk/doc/objectify.txt
lxml/trunk/doc/parsing.txt
lxml/trunk/doc/performance.txt
lxml/trunk/doc/resolvers.txt
lxml/trunk/doc/rest2html.py
lxml/trunk/doc/sax.txt
lxml/trunk/doc/tutorial.txt
lxml/trunk/doc/validation.txt
lxml/trunk/doc/xpathxslt.txt
Log:
r3706 at delle: sbehnel | 2008-03-03 15:53:29 +0100
use Pygments to enable syntax highlighting in docs
Modified: lxml/trunk/CHANGES.txt
==============================================================================
--- lxml/trunk/CHANGES.txt (original)
+++ lxml/trunk/CHANGES.txt Mon Mar 3 19:43:14 2008
@@ -24,6 +24,11 @@
Other changes
-------------
+* Generating the HTML documentation now requires Pygments_, which is
+ used to enable syntax highlighting for the doctest examples.
+
+.. _Pygments: http://pygments.org/
+
Most long-time deprecated functions and methods were removed:
- ``etree.clearErrorLog()``, use ``etree.clear_error_log()``
Modified: lxml/trunk/doc/FAQ.txt
==============================================================================
--- lxml/trunk/doc/FAQ.txt (original)
+++ lxml/trunk/doc/FAQ.txt Mon Mar 3 19:43:14 2008
@@ -227,7 +227,9 @@
The ElementTree tree model defines an Element as a container with a tag name,
contained text, child Elements and a tail text. This means that whenever you
-serialise an Element, you will get all parts of that Element::
+serialise an Element, you will get all parts of that Element:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> root = etree.XML("<root><tag>text<child/></tag>tail</root>")
@@ -235,7 +237,9 @@
<tag>text<child/></tag>tail
Here is an example that shows why not serialising the tail would be
-even more surprising from an object point of view::
+even more surprising from an object point of view:
+
+.. sourcecode:: pycon
>>> root = etree.Element("test")
@@ -484,7 +488,9 @@
You should always try to reproduce the problem with the latest
versions of libxml2 and libxslt - and make sure they are used.
-``lxml.etree`` can tell you what it runs with::
+``lxml.etree`` can tell you what it runs with:
+
+.. sourcecode:: python
from lxml import etree
print "lxml.etree: ", etree.LXML_VERSION
@@ -705,7 +711,9 @@
only added between nodes that do not contain data. This is always the case
for trees constructed element-by-element, so no problems should be expected
here. For parsed trees, a good way to assure that no conflicting whitespace
-is left in the tree is the ``remove_blank_text`` option::
+is left in the tree is the ``remove_blank_text`` option:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(remove_blank_text=True)
>>> tree = etree.parse(file, parser)
Modified: lxml/trunk/doc/api.txt
==============================================================================
--- lxml/trunk/doc/api.txt (original)
+++ lxml/trunk/doc/api.txt Mon Mar 3 19:43:14 2008
@@ -57,7 +57,9 @@
AttributeError in older versions. The versions of libxml2 and libxslt are
available through the attributes ``LIBXML_VERSION`` and ``LIBXSLT_VERSION``.
-The following examples usually assume this to be executed first::
+The following examples usually assume this to be executed first:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> from StringIO import StringIO
@@ -85,7 +87,9 @@
-------------------
Compared to the original ElementTree API, lxml.etree has an extended tree
-model. It knows about parents and siblings of elements::
+model. It knows about parents and siblings of elements:
+
+.. sourcecode:: pycon
>>> root = etree.Element("root")
>>> a = etree.SubElement(root, "a")
@@ -102,14 +106,18 @@
Elements always live within a document context in lxml. This implies that
there is also a notion of an absolute document root. You can retrieve an
-ElementTree for the root node of a document from any of its elements::
+ElementTree for the root node of a document from any of its elements.
+
+.. sourcecode:: pycon
>>> tree = d.getroottree()
>>> print tree.getroot().tag
root
Note that this is different from wrapping an Element in an ElementTree. You
-can use ElementTrees to create XML trees with an explicit root node::
+can use ElementTrees to create XML trees with an explicit root node:
+
+.. sourcecode:: pycon
>>> tree = etree.ElementTree(d)
>>> print tree.getroot().tag
@@ -123,7 +131,9 @@
All operations that you run on such an ElementTree (like XPath, XSLT, etc.)
will understand the explicitly chosen root as root node of a document. They
will not see any elements outside the ElementTree. However, ElementTrees do
-not modify their Elements::
+not modify their Elements:
+
+.. sourcecode:: pycon
>>> element = tree.getroot()
>>> print element.tag
@@ -143,7 +153,9 @@
---------
The ElementTree API makes Elements iterable to supports iteration over their
-children. Using the tree defined above, we get::
+children. Using the tree defined above, we get:
+
+.. sourcecode:: pycon
>>> [ child.tag for child in root ]
['a', 'b', 'c', 'd']
@@ -151,14 +163,18 @@
To iterate in the opposite direction, use the ``reversed()`` function
that exists in Python 2.4 and later.
-Tree traversal should use the ``element.iter()`` method::
+Tree traversal should use the ``element.iter()`` method:
+
+.. sourcecode:: pycon
>>> [ el.tag for el in root.iter() ]
['root', 'a', 'b', 'c', 'd', 'e']
lxml.etree also supports this, but additionally features an extended API for
iteration over the children, following/preceding siblings, ancestors and
-descendants of an element, as defined by the respective XPath axis::
+descendants of an element, as defined by the respective XPath axis:
+
+.. sourcecode:: pycon
>>> [ child.tag for child in root.iterchildren() ]
['a', 'b', 'c', 'd']
@@ -178,7 +194,9 @@
implements the 'descendant-or-self' axis in XPath.
All of these iterators support an additional ``tag`` keyword argument that
-filters the generated elements by tag name::
+filters the generated elements by tag name:
+
+.. sourcecode:: pycon
>>> [ child.tag for child in root.iterchildren(tag='a') ]
['a']
@@ -206,7 +224,9 @@
However, lxml also keeps a global error log of all errors that occurred at the
application level. Whenever an exception is raised, you can retrieve the
errors that occured and "might have" lead to the problem from the error log
-copy attached to the exception::
+copy attached to the exception:
+
+.. sourcecode:: pycon
>>> etree.clear_error_log()
>>> broken_xml = '''
@@ -221,7 +241,9 @@
Once you have caught this exception, you can access its ``error_log`` property
to retrieve the log entries or filter them by a specific type, error domain or
-error level::
+error level:
+
+.. sourcecode:: pycon
>>> log = e.error_log.filter_from_level(etree.ErrorLevels.FATAL)
>>> print log
@@ -234,14 +256,18 @@
parsing (PARSER) lines 4, column 8 and line 5, column 1 of a string (<string>,
or the filename if available). Here, PARSER is the so-called error domain,
see ``lxml.etree.ErrorDomains`` for that. You can get it from a log entry
-like this::
+like this:
+
+.. sourcecode:: pycon
>>> entry = log[0]
>>> print entry.domain_name, entry.type_name, entry.filename
PARSER ERR_TAG_NAME_MISMATCH <string>
There is also a convenience attribute ``last_error`` that returns the last
-error or fatal error that occurred::
+error or fatal error that occurred:
+
+.. sourcecode:: pycon
>>> entry = e.error_log.last_error
>>> print entry.domain_name, entry.type_name, entry.filename
@@ -264,7 +290,9 @@
lxml.etree has direct support for pretty printing XML output. Functions like
``ElementTree.write()`` and ``tostring()`` support it through a keyword
-argument::
+argument:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root><test/></root>")
>>> print etree.tostring(root)
@@ -279,7 +307,9 @@
output. It was added in lxml 2.0.
By default, lxml (just as ElementTree) outputs the XML declaration only if it
-is required by the standard::
+is required by the standard:
+
+.. sourcecode:: pycon
>>> unicode_root = etree.Element(u"t\u3120st")
>>> unicode_root.text = u"t\u0A0Ast"
@@ -295,7 +325,9 @@
.. _`Unicode support`: parsing.html#python-unicode-strings
You can enable or disable the declaration explicitly by passing another
-keyword argument for the serialisation::
+keyword argument for the serialisation:
+
+.. sourcecode:: pycon
>>> print etree.tostring(root, xml_declaration=True)
<?xml version='1.0' encoding='ASCII'?>
@@ -308,7 +340,9 @@
Note that a standard compliant XML parser will not consider the last line
well-formed XML if the encoding is not explicitly provided somehow, e.g. in an
-underlying transport protocol::
+underlying transport protocol:
+
+.. sourcecode:: pycon
>>> notxml = etree.tostring(unicode_root, encoding="UTF-16LE",
... xml_declaration=False)
@@ -322,7 +356,9 @@
---------------------------
You can let lxml process xinclude statements in a document by calling the
-xinclude() method on a tree::
+xinclude() method on a tree:
+
+.. sourcecode:: pycon
>>> data = StringIO('''\
... <doc xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -353,7 +389,9 @@
The lxml.etree.ElementTree class has a method write_c14n, which takes a file
object as argument. This file object will receive an UTF-8 representation of
the canonicalized form of the XML, following the W3C C14N recommendation. For
-example::
+example:
+
+.. sourcecode:: pycon
>>> f = StringIO('<a><b/></a>')
>>> tree = etree.parse(f)
Modified: lxml/trunk/doc/capi.txt
==============================================================================
--- lxml/trunk/doc/capi.txt (original)
+++ lxml/trunk/doc/capi.txt Mon Mar 3 19:43:14 2008
@@ -61,7 +61,9 @@
If you really feel like it, you can also interface with lxml.etree straight
from C code. All you have to do is include the header file for the public
-API, import the ``lxml.etree`` module and then call the import function::
+API, import the ``lxml.etree`` module and then call the import function:
+
+.. sourcecode:: c
/* My C extension */
Modified: lxml/trunk/doc/compatibility.txt
==============================================================================
--- lxml/trunk/doc/compatibility.txt (original)
+++ lxml/trunk/doc/compatibility.txt Mon Mar 3 19:43:14 2008
@@ -7,7 +7,9 @@
* Importing etree is obviously different; etree uses a lower-case
package name, while ElementTree uses a combination of upper-case and
- lower case in imports::
+ lower case in imports:
+
+ .. sourcecode:: python
# etree
from lxml.etree import Element
@@ -19,7 +21,9 @@
from xml.etree.ElementTree import Element
When switching over code from ElementTree to lxml.etree, and you're using
- the package name prefix 'ElementTree', you can do the following::
+ the package name prefix 'ElementTree', you can do the following:
+
+ .. sourcecode:: python
# instead of
from elementtree import ElementTree
@@ -46,18 +50,24 @@
strings.
* ElementTree allows you to place an Element in two different trees at the
- same time. Thus, this::
+ same time. Thus, this:
+
+ .. sourcecode:: python
a = Element('a')
b = SubElement(a, 'b')
c = Element('c')
c.append(b)
- will result in the following tree a::
+ will result in the following tree a:
+
+ .. sourcecode:: xml
<a><b /></a>
- and the following tree c::
+ and the following tree c:
+
+ .. sourcecode:: xml
<c><b /></c>
@@ -66,11 +76,15 @@
an element can only exist in a single tree at the same time. Adding an
element in some tree to another tree will cause this element to be moved.
- So, for tree a we will get::
+ So, for tree a we will get:
+
+ .. sourcecode:: xml
<a></a>
- and for tree c we will get::
+ and for tree c we will get:
+
+ .. sourcecode:: xml
<c><b/></c>
Modified: lxml/trunk/doc/cssselect.txt
==============================================================================
--- lxml/trunk/doc/cssselect.txt (original)
+++ lxml/trunk/doc/cssselect.txt Mon Mar 3 19:43:14 2008
@@ -25,7 +25,9 @@
The most important class in the ``cssselect`` module is ``CSSSelector``. It
provides the same interface as the XPath_ class, but accepts a CSS selector
-expression as input::
+expression as input:
+
+.. sourcecode:: pycon
>>> from lxml.cssselect import CSSSelector
>>> sel = CSSSelector('div.content')
@@ -35,13 +37,17 @@
'div.content'
The selector actually compiles to XPath, and you can see the
-expression by inspecting the object::
+expression by inspecting the object:
+
+.. sourcecode:: pycon
>>> sel.path
"descendant-or-self::div[contains(concat(' ', normalize-space(@class), ' '), ' content ')]"
To use the selector, simply call it with a document or element
-object::
+object:
+
+.. sourcecode:: pycon
>>> from lxml.etree import fromstring
>>> h = fromstring('''<div id="outer">
Modified: lxml/trunk/doc/element_classes.txt
==============================================================================
--- lxml/trunk/doc/element_classes.txt (original)
+++ lxml/trunk/doc/element_classes.txt Mon Mar 3 19:43:14 2008
@@ -8,7 +8,9 @@
specific namespace or for an exact element at a specific position in the tree.
Custom Elements must inherit from the ``lxml.etree.ElementBase`` class, which
-provides the Element interface for subclasses::
+provides the Element interface for subclasses:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> class HonkElement(etree.ElementBase):
@@ -85,7 +87,9 @@
class.
For example, setting a different default element class for a parser works as
-follows::
+follows:
+
+.. sourcecode:: pycon
>>> parser_lookup = etree.ElementDefaultClassLookup(element=HonkElement)
>>> parser = etree.XMLParser()
@@ -93,7 +97,9 @@
There is one drawback of the parser based scheme: the ``Element()`` factory
does not know about your specialised parser and creates a new document that
-deploys the default parser::
+deploys the default parser:
+
+.. sourcecode:: pycon
>>> el = etree.Element("root")
>>> print isinstance(el, HonkElement)
@@ -101,20 +107,26 @@
You should therefore avoid using this function in code that uses custom
classes. The ``makeelement()`` method of parsers provides a simple
-replacement::
+replacement:
+
+.. sourcecode:: pycon
>>> el = parser.makeelement("root")
>>> print isinstance(el, HonkElement)
True
If you use a parser at the module level, you can easily redirect a module
-level ``Element()`` factory to the parser method by adding code like this::
+level ``Element()`` factory to the parser method by adding code like this:
+
+.. sourcecode:: pycon
>>> MODULE_PARSER = etree.XMLParser()
>>> Element = MODULE_PARSER.makeelement
While the ``XML()`` and ``HTML()`` factories also depend on the default
-parser, you can pass them a different parser as second argument::
+parser, you can pass them a different parser as second argument:
+
+.. sourcecode:: pycon
>>> element = etree.XML("<test/>")
>>> print isinstance(element, HonkElement)
@@ -126,7 +138,9 @@
Whenever you create a document with a parser, it will inherit the lookup
scheme and all subsequent element instantiations for this document will use
-it::
+it:
+
+.. sourcecode:: pycon
>>> element = etree.fromstring("<test/>", parser)
>>> print isinstance(element, HonkElement)
@@ -149,7 +163,9 @@
element class. Consequently, no further fallbacks are supported, but this
scheme is a good fallback for other custom lookup mechanisms.
-Usage::
+Usage:
+
+.. sourcecode:: pycon
>>> lookup = etree.ElementDefaultClassLookup()
>>> parser = etree.XMLParser()
@@ -160,7 +176,9 @@
To change the default element implementation, you can pass your new class to
the constructor. While it accepts classes for ``element``, ``comment`` and
-``pi`` nodes, most use cases will only override the element class::
+``pi`` nodes, most use cases will only override the element class:
+
+.. sourcecode:: pycon
>>> el = parser.makeelement("myelement")
>>> print isinstance(el, HonkElement)
@@ -185,7 +203,9 @@
----------------------
This is an advanced lookup mechanism that supports namespace/tag-name specific
-element classes. You can select it by calling::
+element classes. You can select it by calling:
+
+.. sourcecode:: pycon
>>> lookup = etree.ElementNamespaceClassLookup()
>>> parser = etree.XMLParser()
@@ -199,7 +219,9 @@
This scheme supports a fallback mechanism that is used in the case where the
namespace is not found or no class was registered for the element name.
Normally, the default class lookup is used here. To change it, pass the
-desired fallback lookup scheme to the constructor::
+desired fallback lookup scheme to the constructor:
+
+.. sourcecode:: pycon
>>> fallback = etree.ElementDefaultClassLookup(element=HonkElement)
>>> lookup = etree.ElementNamespaceClassLookup(fallback)
@@ -211,7 +233,9 @@
This scheme uses a mapping from attribute values to classes. An attribute
name is set at initialisation time and is then used to find the corresponding
-value. It is set up as follows::
+value. It is set up as follows:
+
+.. sourcecode:: pycon
>>> id_class_mapping = {} # maps attribute values to element classes
>>> lookup = etree.AttributeBasedElementClassLookup(
@@ -224,7 +248,9 @@
This class uses its fallback if the attribute is not found or its value is not
in the mapping. Normally, the default class lookup is used here. If you want
-to use the namespace lookup, for example, you can use this code::
+to use the namespace lookup, for example, you can use this code:
+
+.. sourcecode:: pycon
>>> fallback = etree.ElementNamespaceClassLookup()
>>> lookup = etree.AttributeBasedElementClassLookup(
@@ -237,7 +263,9 @@
---------------------------
This is the most customisable way of finding element classes on a per-element
-basis. It allows you to implement a custom lookup scheme in a subclass::
+basis. It allows you to implement a custom lookup scheme in a subclass:
+
+.. sourcecode:: pycon
>>> class MyLookup(etree.CustomElementClassLookup):
... def lookup(self, node_type, document, namespace, name):
@@ -263,7 +291,9 @@
elements in the tree have been instantiated as Python Element objects.
Luckily, there is a way to do this. The ``PythonElementClassLookup``
-works similar to the custom lookup scheme::
+works similar to the custom lookup scheme:
+
+.. sourcecode:: pycon
>>> class MyLookup(etree.PythonElementClassLookup):
... def lookup(self, document, element):
@@ -301,7 +331,9 @@
lxml allows you to implement namespaces, in a rather literal sense. After
setting up the namespace class lookup mechanism as described above, you can
build a new element namespace (or retrieve an existing one) by calling the
-``get_namespace(uri)`` method of the lookup::
+``get_namespace(uri)`` method of the lookup:
+
+.. sourcecode:: pycon
>>> lookup = etree.ElementNamespaceClassLookup()
>>> parser = etree.XMLParser()
@@ -310,19 +342,25 @@
>>> namespace = lookup.get_namespace('http://hui.de/honk')
and then register the new element type with that namespace, say, under the tag
-name ``honk``::
+name ``honk``:
+
+.. sourcecode:: pycon
>>> namespace['honk'] = HonkElement
After this, you create and use your XML elements through the normal API of
-lxml::
+lxml:
+
+.. sourcecode:: pycon
>>> xml = '<honk xmlns="http://hui.de/honk" honking="true"/>'
>>> honk_element = etree.XML(xml, parser)
>>> print honk_element.honking
True
-The same works when creating elements by hand::
+The same works when creating elements by hand:
+
+.. sourcecode:: pycon
>>> honk_element = parser.makeelement('{http://hui.de/honk}honk',
... honking='true')
@@ -339,7 +377,9 @@
In the setup example above, we associated the HonkElement class only with the
'honk' element. If an XML tree contains different elements in the same
-namespace, they do not pick up the same implementation::
+namespace, they do not pick up the same implementation:
+
+.. sourcecode:: pycon
>>> xml = '<honk xmlns="http://hui.de/honk" honking="true"><bla/></honk>'
>>> honk_element = etree.XML(xml, parser)
@@ -360,7 +400,9 @@
You may consider following an object oriented approach here. If you build a
class hierarchy of element classes, you can also implement a base class for a
namespace that is used if no specific element class is provided. Again, you
-can just pass None as an element name::
+can just pass None as an element name:
+
+.. sourcecode:: pycon
>>> class HonkNSElement(etree.ElementBase):
... def honk(self):
@@ -374,7 +416,9 @@
>>> namespace['honk'] = HonkElement
Now you can rely on lxml to always return objects of type HonkNSElement or its
-subclasses for elements of this namespace::
+subclasses for elements of this namespace:
+
+.. sourcecode:: pycon
>>> xml = '<honk xmlns="http://hui.de/honk" honking="true"><bla/></honk>'
>>> honk_element = etree.XML(xml, parser)
Modified: lxml/trunk/doc/elementsoup.txt
==============================================================================
--- lxml/trunk/doc/elementsoup.txt (original)
+++ lxml/trunk/doc/elementsoup.txt Mon Mar 3 19:43:14 2008
@@ -17,17 +17,23 @@
parse a file using BeautifulSoup, and `convert_tree()` to convert a
BeautifulSoup tree into a list of top-level Elements.
-Here is a document full of tag soup, similar to, but not quite like, HTML::
+Here is a document full of tag soup, similar to, but not quite like, HTML:
+
+.. sourcecode:: pycon
>>> tag_soup = '<meta><head><title>Hello</head<body onload=crash()>Hi all<p>'
-all you need to do is pass it to the `parse()` function::
+all you need to do is pass it to the `parse()` function:
+
+.. sourcecode:: pycon
>>> from lxml.html.ElementSoup import parse
>>> from StringIO import StringIO
>>> root = parse(StringIO(tag_soup))
-To see what we have here, you can serialise it::
+To see what we have here, you can serialise it:
+
+.. sourcecode:: pycon
>>> from lxml.etree import tostring
>>> print tostring(root, pretty_print=True),
Modified: lxml/trunk/doc/extensions.txt
==============================================================================
--- lxml/trunk/doc/extensions.txt (original)
+++ lxml/trunk/doc/extensions.txt Mon Mar 3 19:43:14 2008
@@ -2,14 +2,18 @@
======================================
This document describes how to use Python extension functions in XPath
-and XSLT like this::
+and XSLT like this:
+
+.. sourcecode:: xml
<xsl:value-of select="f:myPythonFunction(.//sometag)" />
Here is how an extension function looks like. As the first argument,
it always receives a context object (see below). The other arguments
are provided by the respective call in the XPath expression, one in
-the following examples. Any number of arguments is allowed::
+the following examples. Any number of arguments is allowed:
+
+.. sourcecode:: pycon
>>> def hello(dummy, a):
... return "Hello %s" % a
@@ -35,7 +39,9 @@
In order to use a function in XPath/XSLT, it needs to have a (namespaced) name
by which it can be called during evaluation. This is done using the
FunctionNamespace class. For simplicity, we choose the empty namespace
-(None)::
+(None):
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> ns = etree.FunctionNamespace(None)
@@ -45,7 +51,9 @@
This registers the function `hello` with the name `hello` in the default
namespace (None), and the function `loadsofargs` with the name `countargs`.
Now we're going to create a document that we can run XPath expressions
-against::
+against:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> from StringIO import StringIO
@@ -53,7 +61,9 @@
>>> doc = etree.parse(f)
>>> root = doc.getroot()
-Done. Now we can have XPath expressions call our new function::
+Done. Now we can have XPath expressions call our new function:
+
+.. sourcecode:: pycon
>>> print root.xpath("hello('world')")
Hello world
@@ -67,7 +77,9 @@
Note how we call both a Python function (`hello`) and an XPath built-in
function (`string`) in exactly the same way. Normally, however, you would
want to separate the two in different namespaces. The FunctionNamespace class
-allows you to do this::
+allows you to do this:
+
+.. sourcecode:: pycon
>>> ns = etree.FunctionNamespace('http://mydomain.org/myfunctions')
>>> ns['hello'] = hello
@@ -81,7 +93,9 @@
In the last example, you had to specify a prefix for the function namespace.
If you always use the same prefix for a function namespace, you can also
-register it with the namespace::
+register it with the namespace:
+
+.. sourcecode:: pycon
>>> ns = etree.FunctionNamespace('http://mydomain.org/myother/functions')
>>> ns.prefix = 'es'
@@ -106,7 +120,9 @@
Functions get a context object as first parameter. In lxml 1.x, this value
was None, but since lxml 2.0 it provides two properties: ``eval_context`` and
``context_node``. The context node is the Element where the current function
-is called::
+is called:
+
+.. sourcecode:: pycon
>>> def print_tag(context, nodes):
... print context.context_node.tag, [ n.tag for n in nodes ]
@@ -120,7 +136,9 @@
b []
The ``eval_context`` is a dictionary that is local to the evaluation. It
-allows functions to keep state::
+allows functions to keep state:
+
+.. sourcecode:: pycon
>>> def print_context(context):
... context.eval_context[context.context_node.tag] = "done"
@@ -138,7 +156,9 @@
-------------------
Extension functions work for all ways of evaluating XPath expressions and for
-XSL transformations::
+XSL transformations:
+
+.. sourcecode:: pycon
>>> e = etree.XPathEvaluator(doc)
>>> print e('es:hello(local-name(/a))')
@@ -164,7 +184,9 @@
It is also possible to register namespaces with a single evaluator after its
creation. While the following example involves no functions, the idea should
-still be clear::
+still be clear:
+
+.. sourcecode:: pycon
>>> f = StringIO('<a xmlns="http://mydomain.org/myfunctions" />')
>>> ns_doc = etree.parse(f)
@@ -174,14 +196,18 @@
This returns nothing, as we did not ask for the right namespace. When we
register the namespace with the evaluator, however, we can access it via a
-prefix::
+prefix:
+
+.. sourcecode:: pycon
>>> e.register_namespace('foo', 'http://mydomain.org/myfunctions')
>>> e('/foo:a')[0].tag
'{http://mydomain.org/myfunctions}a'
Note that this prefix mapping is only known to this evaluator, as opposed to
-the global mapping of the FunctionNamespace objects::
+the global mapping of the FunctionNamespace objects:
+
+.. sourcecode:: pycon
>>> e2 = etree.XPathEvaluator(ns_doc)
>>> e2('/foo:a')
@@ -196,7 +222,9 @@
Apart from the global registration of extension functions, there is also a way
of making extensions known to a single Evaluator or XSLT. All evaluators and
the XSLT object accept a keyword argument ``extensions`` in their constructor.
-The value is a dictionary mapping (namespace, name) tuples to functions::
+The value is a dictionary mapping (namespace, name) tuples to functions:
+
+.. sourcecode:: pycon
>>> extensions = {('local-ns', 'local-hello') : hello}
>>> namespaces = {'l' : 'local-ns'}
@@ -206,7 +234,9 @@
Hello Haegar
For larger numbers of extension functions, you can define classes or modules
-and use the ``Extension`` helper::
+and use the ``Extension`` helper:
+
+.. sourcecode:: pycon
>>> class MyExt:
... def function1(self, _, arg):
@@ -232,7 +262,9 @@
The additional ``ns`` keyword argument takes a namespace URI or
``None`` (also if left out) for the default namespace. The following
-examples will therefore all do the same thing::
+examples will therefore all do the same thing:
+
+.. sourcecode:: pycon
>>> functions = ('function1', 'function2', 'function3')
>>> extensions = etree.Extension( ext_module, functions )
@@ -260,7 +292,9 @@
>>> print e('function1(function2(function3(string(b))))')
123Haegar
-For convenience, you can also pass a sequence of extensions::
+For convenience, you can also pass a sequence of extensions:
+
+.. sourcecode:: pycon
>>> extensions1 = etree.Extension(ext_module)
>>> extensions2 = etree.Extension(ext_module, ns='local-ns')
@@ -278,7 +312,9 @@
Extension functions can return any data type for which there is an XPath
equivalent (see the documentation on `XPath return values`). This includes
numbers, boolean values, elements and lists of elements. Note that integers
-will also be returned as floats::
+will also be returned as floats:
+
+.. sourcecode:: pycon
>>> def returnsFloat(_):
... return 1.7
@@ -309,7 +345,9 @@
As the last example shows, you can pass the results of functions back into
the XPath expression. Elements and sequences of elements are treated as
-XPath node-sets::
+XPath node-sets:
+
+.. sourcecode:: pycon
>>> def returnsNodeSet(_):
... results1 = etree.Element('results1')
@@ -352,7 +390,9 @@
Only the elements and their children are passed on, no outlying parents or
tail texts will be available in the result. This also means that in the above
example, the `subresult` elements in `results2` and `results3` are no longer
-identical within the node-set, they belong to independent trees::
+identical within the node-set, they belong to independent trees:
+
+.. sourcecode:: pycon
>>> print r[1][-1].tag, r[2].tag
subresult subresult
Modified: lxml/trunk/doc/html/style.css
==============================================================================
--- lxml/trunk/doc/html/style.css (original)
+++ lxml/trunk/doc/html/style.css Mon Mar 3 19:43:14 2008
@@ -242,7 +242,7 @@
code {
color: Black;
- background-color: #cccccc;
+ background-color: #f0f0f0;
font-family: "Courier New", Courier, monospace;
}
@@ -250,6 +250,69 @@
padding: 0.5em;
border: 1px solid #8cacbb;
color: Black;
- background-color: #cccccc;
+ background-color: #f0f0f0;
font-family: "Courier New", Courier, monospace;
}
+
+/* Syntax highlighting */
+
+.syntax { background: #f0f0f0; }
+.syntax .c { color: #60a0b0; font-style: italic } /* Comment */
+.syntax .err { border: 1px solid #FF0000 } /* Error */
+.syntax .k { color: #007020; font-weight: bold } /* Keyword */
+.syntax .o { color: #666666 } /* Operator */
+.syntax .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
+.syntax .cp { color: #007020 } /* Comment.Preproc */
+.syntax .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
+.syntax .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
+.syntax .gd { color: #A00000 } /* Generic.Deleted */
+.syntax .ge { font-style: italic } /* Generic.Emph */
+.syntax .gr { color: #FF0000 } /* Generic.Error */
+.syntax .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.syntax .gi { color: #00A000 } /* Generic.Inserted */
+.syntax .go { color: #404040 } /* Generic.Output */
+.syntax .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.syntax .gs { font-weight: bold } /* Generic.Strong */
+.syntax .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.syntax .gt { color: #0040D0 } /* Generic.Traceback */
+.syntax .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
+.syntax .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
+.syntax .kp { color: #007020 } /* Keyword.Pseudo */
+.syntax .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
+.syntax .kt { color: #902000 } /* Keyword.Type */
+.syntax .m { color: #40a070 } /* Literal.Number */
+.syntax .s { color: #4070a0 } /* Literal.String */
+.syntax .na { color: #4070a0 } /* Name.Attribute */
+.syntax .nb { color: #007020 } /* Name.Builtin */
+.syntax .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
+.syntax .no { color: #60add5 } /* Name.Constant */
+.syntax .nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.syntax .ni { color: #d55537; font-weight: bold } /* Name.Entity */
+.syntax .ne { color: #007020 } /* Name.Exception */
+.syntax .nf { color: #06287e } /* Name.Function */
+.syntax .nl { color: #002070; font-weight: bold } /* Name.Label */
+.syntax .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.syntax .nt { color: #062873; font-weight: bold } /* Name.Tag */
+.syntax .nv { color: #bb60d5 } /* Name.Variable */
+.syntax .ow { color: #007020; font-weight: bold } /* Operator.Word */
+.syntax .w { color: #bbbbbb } /* Text.Whitespace */
+.syntax .mf { color: #40a070 } /* Literal.Number.Float */
+.syntax .mh { color: #40a070 } /* Literal.Number.Hex */
+.syntax .mi { color: #40a070 } /* Literal.Number.Integer */
+.syntax .mo { color: #40a070 } /* Literal.Number.Oct */
+.syntax .sb { color: #4070a0 } /* Literal.String.Backtick */
+.syntax .sc { color: #4070a0 } /* Literal.String.Char */
+.syntax .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
+.syntax .s2 { color: #4070a0 } /* Literal.String.Double */
+.syntax .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
+.syntax .sh { color: #4070a0 } /* Literal.String.Heredoc */
+.syntax .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
+.syntax .sx { color: #c65d09 } /* Literal.String.Other */
+.syntax .sr { color: #235388 } /* Literal.String.Regex */
+.syntax .s1 { color: #4070a0 } /* Literal.String.Single */
+.syntax .ss { color: #517918 } /* Literal.String.Symbol */
+.syntax .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.syntax .vc { color: #bb60d5 } /* Name.Variable.Class */
+.syntax .vg { color: #bb60d5 } /* Name.Variable.Global */
+.syntax .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.syntax .il { color: #40a070 } /* Literal.Number.Integer.Long */
\ No newline at end of file
Modified: lxml/trunk/doc/lxml2.txt
==============================================================================
--- lxml/trunk/doc/lxml2.txt (original)
+++ lxml/trunk/doc/lxml2.txt Mon Mar 3 19:43:14 2008
@@ -208,11 +208,15 @@
A very useful module for doctests based on XML or HTML is
``lxml.doctestcompare``. It provides a relaxed comparison mechanism
for XML and HTML in doctests. Using it for XML comparisons is as
-simple as::
+simple as:
+
+.. sourcecode:: pycon
>>> import lxml.usedoctest
-and for HTML comparisons::
+and for HTML comparisons:
+
+.. sourcecode:: pycon
>>> import lxml.html.usedoctest
Modified: lxml/trunk/doc/lxmlhtml.txt
==============================================================================
--- lxml/trunk/doc/lxmlhtml.txt (original)
+++ lxml/trunk/doc/lxmlhtml.txt Mon Mar 3 19:43:14 2008
@@ -150,12 +150,16 @@
Luckily, lxml provides the ``lxml.doctestcompare`` module that
supports relaxed comparison of XML and HTML pages and provides a
readable diff in the output when a test fails. The HTML comparison is
-most easily used by importing the ``usedoctest`` module in a doctest::
+most easily used by importing the ``usedoctest`` module in a doctest:
+
+.. sourcecode:: pycon
>>> import lxml.html.usedoctest
Now, if you have a HTML document and want to compare it to an expected result
-document in a doctest, you can do the following::
+document in a doctest, you can do the following:
+
+.. sourcecode:: pycon
>>> import lxml.html
>>> html = lxml.html.fromstring('''\
@@ -195,7 +199,9 @@
lxml.html comes with a predefined HTML vocabulary for the `E-factory`_,
originally written by Fredrik Lundh. This allows you to quickly generate HTML
-pages and fragments::
+pages and fragments:
+
+.. sourcecode:: pycon
>>> from lxml.html import builder as E
>>> from lxml.html import usedoctest
@@ -387,7 +393,9 @@
Note that you can change any of these attributes (values, method,
action, etc) and then serialize the form to see the updated values.
-You can, for instance, do::
+You can, for instance, do:
+
+.. sourcecode:: pycon
>>> from lxml.html import fromstring, tostring
>>> form_page = fromstring('''<html><body><form>
@@ -441,7 +449,9 @@
argument, which is a function with the signature ``open_http(method,
url, values)``.
-Example::
+Example:
+
+.. sourcecode:: pycon
>>> from lxml.html import parse, submit_form
>>> page = parse('http://tinyurl.com').getroot()
@@ -458,7 +468,9 @@
CSS style annotations and much more.
Say, you have an evil web page from an untrusted source that contains lots of
-content that upsets browsers and tries to run evil code on the client side::
+content that upsets browsers and tries to run evil code on the client side:
+
+.. sourcecode:: pycon
>>> html = '''\
... <html>
@@ -488,7 +500,9 @@
... </html>'''
To remove the all suspicious content from this unparsed document, use the
-``clean_html`` function::
+``clean_html`` function:
+
+.. sourcecode:: pycon
>>> from lxml.html.clean import clean_html
@@ -511,7 +525,9 @@
</html>
The ``Cleaner`` class supports several keyword arguments to control exactly
-which content is removed::
+which content is removed:
+
+.. sourcecode:: pycon
>>> from lxml.html.clean import Cleaner
@@ -637,6 +653,8 @@
Example of ``htmldiff``:
+.. sourcecode:: pycon
+
>>> from lxml.html.diff import htmldiff, html_annotate
>>> doc1 = '''<p>Here is some text.</p>'''
>>> doc2 = '''<p>Here is <b>a lot</b> of <i>text</i>.</p>'''
@@ -658,7 +676,9 @@
argument, ``markup``. This is a function like ``markup(text,
version)`` that returns the given text marked up with the given
version. The default version, the output of which you see in the
-example, looks like::
+example, looks like:
+
+.. sourcecode:: python
def default_markup(text, version):
return '<span title="%s">%s</span>' % (
@@ -673,7 +693,9 @@
This example parses the `hCard <http://microformats.org/wiki/hcard>`_
microformat.
-First we get the page::
+First we get the page:
+
+.. sourcecode:: pycon
>>> import urllib
>>> from lxml.html import fromstring
@@ -682,7 +704,9 @@
>>> doc = fromstring(content)
>>> doc.make_links_absolute(url)
-Then we create some objects to put the information in::
+Then we create some objects to put the information in:
+
+.. sourcecode:: pycon
>>> class Card(object):
... def __init__(self, **kw):
@@ -692,7 +716,9 @@
... def __init__(self, phone, types=()):
... self.phone, self.types = phone, types
-And some generally handy functions for microformats::
+And some generally handy functions for microformats:
+
+.. sourcecode:: pycon
>>> def get_text(el, class_name):
... els = el.find_class(class_name)
@@ -708,7 +734,9 @@
... # Ideally this would parse street, etc.
... return el.find_class('adr')
-Then the parsing::
+Then the parsing:
+
+.. sourcecode:: pycon
>>> for el in doc.find_class('hcard'):
... card = Card()
Modified: lxml/trunk/doc/mkhtml.py
==============================================================================
--- lxml/trunk/doc/mkhtml.py (original)
+++ lxml/trunk/doc/mkhtml.py Mon Mar 3 19:43:14 2008
@@ -84,7 +84,7 @@
tag = el.tag
if tag[0] != '{':
el.tag = "{http://www.w3.org/1999/xhtml}" + tag
- current_menu = find_menu(menu_root, name=replace_invalid('', name))
+ current_menu = find_menu(menu_root, name=replace_invalid(' ', name))
if current_menu:
for submenu in current_menu:
submenu.set("class", submenu.get("class", "").
@@ -137,11 +137,11 @@
build_menu(tree, basename, section_head)
- # also convert INSTALL.txt and CHANGES.txt
+ # also convert CHANGES.txt
rest2html(script,
os.path.join(lxml_path, 'CHANGES.txt'),
os.path.join(dirname, 'changes-%s.html' % release),
- stylesheet_url)
+ '')
# integrate menu
for tree, basename, outpath in trees.itervalues():
Modified: lxml/trunk/doc/objectify.txt
==============================================================================
--- lxml/trunk/doc/objectify.txt (original)
+++ lxml/trunk/doc/objectify.txt Mon Mar 3 19:43:14 2008
@@ -42,7 +42,9 @@
To set up and use ``objectify``, you need both the ``lxml.etree``
-module and ``lxml.objectify``::
+module and ``lxml.objectify``:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> from lxml import objectify
@@ -56,7 +58,9 @@
code using lxml.objectify.
To make the doctests in this document look a little nicer, we also use
-this::
+this:
+
+.. sourcecode:: pycon
>>> import lxml.usedoctest
@@ -77,7 +81,9 @@
As with ``lxml.etree``, you can either create an ``objectify`` tree by
parsing an XML document or by building one from scratch. To parse a
document, just use the ``parse()`` or ``fromstring()`` functions of
-the module::
+the module:
+
+.. sourcecode:: pycon
>>> from StringIO import StringIO
>>> fileobject = StringIO('<test/>')
@@ -91,14 +97,18 @@
True
To build a new tree in memory, ``objectify`` replicates the standard
-factory function ``Element()`` from ``lxml.etree``::
+factory function ``Element()`` from ``lxml.etree``:
+
+.. sourcecode:: pycon
>>> obj_el = objectify.Element("new")
>>> print isinstance(obj_el, objectify.ObjectifiedElement)
True
After creating such an Element, you can use the `usual API`_ of
-lxml.etree to add SubElements to the tree::
+lxml.etree to add SubElements to the tree:
+
+.. sourcecode:: pycon
>>> child = etree.SubElement(obj_el, "newchild", attr="value")
@@ -107,7 +117,9 @@
New subelements will automatically inherit the objectify behaviour
from their tree. However, all independent elements that you create
through the ``Element()`` factory of lxml.etree (instead of objectify)
-will not support the ``objectify`` API by themselves::
+will not support the ``objectify`` API by themselves:
+
+.. sourcecode:: pycon
>>> subel = etree.SubElement(obj_el, "sub")
>>> print isinstance(subel, objectify.ObjectifiedElement)
@@ -123,7 +135,9 @@
The main idea behind the ``objectify`` API is to hide XML element access
behind the usual object attribute access pattern. Asking an element for an
-attribute will return the sequence of children with corresponding tag names::
+attribute will return the sequence of children with corresponding tag names:
+
+.. sourcecode:: pycon
>>> root = objectify.Element("root")
>>> b = etree.SubElement(root, "b")
@@ -139,7 +153,9 @@
>>> root.index(root.b[1])
1
-For convenience, you can omit the index '0' to access the first child::
+For convenience, you can omit the index '0' to access the first child:
+
+.. sourcecode:: pycon
>>> print root.b.tag
b
@@ -147,7 +163,9 @@
0
>>> del root.b
-Iteration and slicing also obey the requested tag::
+Iteration and slicing also obey the requested tag:
+
+.. sourcecode:: pycon
>>> x1 = etree.SubElement(root, "x")
>>> x2 = etree.SubElement(root, "x")
@@ -168,7 +186,9 @@
If you want to iterate over all children or need to provide a specific
namespace for the tag, use the ``iterchildren()`` method. Like the other
-methods for iteration, it supports an optional tag keyword argument::
+methods for iteration, it supports an optional tag keyword argument:
+
+.. sourcecode:: pycon
>>> [ el.tag for el in root.iterchildren() ]
['b', 'x', 'x']
@@ -179,7 +199,9 @@
>>> [ el.tag for el in root.b ]
['b']
-XML attributes are accessed as in the normal ElementTree API::
+XML attributes are accessed as in the normal ElementTree API:
+
+.. sourcecode:: pycon
>>> c = etree.SubElement(root, "c", myattr="someval")
>>> print root.c.get("myattr")
@@ -192,7 +214,9 @@
In addition to the normal ElementTree API for appending elements to trees,
subtrees can also be added by assigning them to object attributes. In this
case, the subtree is automatically deep copied and the tag name of its root is
-updated to match the attribute name::
+updated to match the attribute name:
+
+.. sourcecode:: pycon
>>> el = objectify.Element("yet_another_child")
>>> root.new_child = el
@@ -205,13 +229,17 @@
>>> [ el.tag for el in root.y ]
['y', 'y']
-The latter is a short form for operations on the full slice::
+The latter is a short form for operations on the full slice:
+
+.. sourcecode:: pycon
>>> root.y[:] = [ objectify.Element("y") ]
>>> [ el.tag for el in root.y ]
['y']
-You can also replace children that way::
+You can also replace children that way:
+
+.. sourcecode:: pycon
>>> child1 = etree.SubElement(root, "child")
>>> child2 = etree.SubElement(root, "child")
@@ -228,7 +256,9 @@
>>> print root.child[2].sub.tag
sub
-Note that special care must be taken when changing the tag name of an element::
+Note that special care must be taken when changing the tag name of an element:
+
+.. sourcecode:: pycon
>>> print root.b.tag
b
@@ -244,7 +274,9 @@
Tree generation with the E-factory
----------------------------------
-To simplify the generation of trees even further, you can use the E-factory::
+To simplify the generation of trees even further, you can use the E-factory:
+
+.. sourcecode:: pycon
>>> E = objectify.E
>>> root = E.root(
@@ -262,7 +294,9 @@
<d py:pytype="str" tell="me">how</d>
</root>
-This allows you to write up a specific language in tags::
+This allows you to write up a specific language in tags:
+
+.. sourcecode:: pycon
>>> ROOT = objectify.E.root
>>> TITLE = objectify.E.title
@@ -282,7 +316,9 @@
``objectify.E`` is an instance of ``objectify.ElementMaker``. By default, it
creates pytype annotated Elements without a namespace. You can switch off the
pytype annotation by passing False to the ``annotate`` keyword argument of the
-constructor. You can also pass a default namespace and an ``nsmap``::
+constructor. You can also pass a default namespace and an ``nsmap``:
+
+.. sourcecode:: pycon
>>> myE = objectify.ElementMaker(annotate=False,
... namespace="http://my/ns", nsmap={None : "http://my/ns"})
@@ -300,7 +336,9 @@
Namespaces are handled mostly behind the scenes. If you access a child of an
Element without specifying a namespace, the lookup will use the namespace of
-the parent::
+the parent:
+
+.. sourcecode:: pycon
>>> root = objectify.Element("{ns}root")
>>> b = etree.SubElement(root, "{ns}b")
@@ -313,18 +351,24 @@
...
AttributeError: no such child: {ns}c
-You can access elements with different namespaces via ``getattr()``::
+You can access elements with different namespaces via ``getattr()``:
+
+.. sourcecode:: pycon
>>> print getattr(root, "{other}c").tag
{other}c
-For convenience, there is also a quick way through item access::
+For convenience, there is also a quick way through item access:
+
+.. sourcecode:: pycon
>>> print root["{other}c"].tag
{other}c
The same approach must be used to access children with tag names that are not
-valid Python identifiers::
+valid Python identifiers:
+
+.. sourcecode:: pycon
>>> el = etree.SubElement(root, "{ns}tag-name")
>>> print root["tag-name"].tag
@@ -348,7 +392,9 @@
>>> print root["tag-name"][1].child.tag
{ns}child
-or for names that have a special meaning in lxml.objectify::
+or for names that have a special meaning in lxml.objectify:
+
+.. sourcecode:: pycon
>>> root = objectify.XML("<root><text>TEXT</text></root>")
@@ -375,7 +421,9 @@
.. _`documentation on validation`: validation.html
First of all, we need a parser that knows our schema, so let's say we
-parse the schema from a file-like object (or file or filename)::
+parse the schema from a file-like object (or file or filename):
+
+.. sourcecode:: pycon
>>> from StringIO import StringIO
>>> f = StringIO('''\
@@ -392,13 +440,17 @@
When creating the validating parser, we must make sure it `returns
objectify trees`_. This is best done with the ``makeparser()``
-function::
+function:
+
+.. sourcecode:: pycon
>>> parser = objectify.makeparser(schema = schema)
.. _`returns objectify trees`: #advance-element-class-lookup
-Now we can use it to parse a valid document::
+Now we can use it to parse a valid document:
+
+.. sourcecode:: pycon
>>> xml = "<a><b>test</b></a>"
>>> a = objectify.fromstring(xml, parser)
@@ -406,7 +458,9 @@
>>> print a.b
test
-Or an invalid document::
+Or an invalid document:
+
+.. sourcecode:: pycon
>>> xml = "<a><b>test</b><c/></a>"
>>> a = objectify.fromstring(xml, parser)
@@ -421,7 +475,9 @@
==========
For both convenience and speed, objectify supports its own path language,
-represented by the ``ObjectPath`` class::
+represented by the ``ObjectPath`` class:
+
+.. sourcecode:: pycon
>>> root = objectify.Element("{ns}root")
>>> b1 = etree.SubElement(root, "{ns}b")
@@ -465,7 +521,9 @@
>>> print find(root).tag
{ns}b
-Apart from strings, ObjectPath also accepts lists of path segments::
+Apart from strings, ObjectPath also accepts lists of path segments:
+
+.. sourcecode:: pycon
>>> find = objectify.ObjectPath(['root', 'b', 'c'])
>>> print find(root).tag
@@ -476,7 +534,9 @@
{ns}b
You can also use relative paths starting with a '.' to ignore the actual root
-element and only inherit its namespace::
+element and only inherit its namespace:
+
+.. sourcecode:: pycon
>>> find = objectify.ObjectPath(".b[1]")
>>> print find(root).tag
@@ -498,13 +558,17 @@
...
AttributeError: no such child: {other}unknown
-For convenience, a single dot represents the empty ObjectPath (identity)::
+For convenience, a single dot represents the empty ObjectPath (identity):
+
+.. sourcecode:: pycon
>>> find = objectify.ObjectPath(".")
>>> print find(root).tag
{ns}root
-ObjectPath objects can be used to manipulate trees::
+ObjectPath objects can be used to manipulate trees:
+
+.. sourcecode:: pycon
>>> root = objectify.Element("{ns}root")
@@ -532,7 +596,9 @@
>>> [ el.text for el in path.find(root) ]
['my value', 'my new value']
-As with attribute assignment, ``setattr()`` accepts lists::
+As with attribute assignment, ``setattr()`` accepts lists:
+
+.. sourcecode:: pycon
>>> path.setattr(root, ["v1", "v2", "v3"])
>>> [ el.text for el in path.find(root) ]
@@ -541,7 +607,9 @@
Note, however, that indexing is only supported in this context if the children
exist. Indexing of non existing children will not extend or create a list of
-such children but raise an exception::
+such children but raise an exception:
+
+.. sourcecode:: pycon
>>> path = objectify.ObjectPath(".{non}existing[1]")
>>> path.setattr(root, "my value")
@@ -559,7 +627,9 @@
The objectify module knows about Python data types and tries its best to let
element content behave like them. For example, they support the normal math
-operators::
+operators:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring(
... "<root><a>5</a><b>11</b><c>true</c><d>hoi</d></root>")
@@ -591,7 +661,9 @@
However, data elements continue to provide the objectify API. This means that
sequence operations such as ``len()``, slicing and indexing (e.g. of strings)
cannot behave as the Python types. Like all other tree elements, they show
-the normal slicing behaviour of objectify elements::
+the normal slicing behaviour of objectify elements:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring("<root><a>test</a><b>toast</b></root>")
>>> print root.a + ' me' # behaves like a string, right?
@@ -611,7 +683,9 @@
If you need to run sequence operations on data types, you must ask the API for
the *real* Python value. The string value is always available through the
normal ElementTree ``.text`` attribute. Additionally, all data classes
-provide a ``.pyval`` attribute that returns the value as plain Python type::
+provide a ``.pyval`` attribute that returns the value as plain Python type:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring("<root><a>test</a><b>5</b></root>")
>>> root.a.text
@@ -625,7 +699,9 @@
5
Note, however, that both attributes are read-only in objectify. If you want
-to change values, just assign them directly to the attribute::
+to change values, just assign them directly to the attribute:
+
+.. sourcecode:: pycon
>>> root.a.text = "25"
Traceback (most recent call last):
@@ -652,7 +728,9 @@
To see the data types that are currently used, you can call the module level
``dump()`` function that returns a recursive string representation for
-elements::
+elements:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring("""
... <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
@@ -677,7 +755,9 @@
d = None [NoneElement]
* xsi:nil = 'true'
-You can freely switch between different types for the same child::
+You can freely switch between different types for the same child:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring("<root><a>5</a></root>")
>>> print objectify.dump(root)
@@ -722,7 +802,9 @@
Normally, elements use the standard string representation for str() that is
provided by lxml.etree. You can enable a pretty-print representation for
-objectify elements like this::
+objectify elements like this:
+
+.. sourcecode:: pycon
>>> objectify.enableRecursiveStr()
@@ -749,7 +831,9 @@
d = None [NoneElement]
* xsi:nil = 'true'
-This behaviour can be switched off in the same way::
+This behaviour can be switched off in the same way:
+
+.. sourcecode:: pycon
>>> objectify.enableRecursiveStr(False)
@@ -796,7 +880,9 @@
The "type hint" mechanism deploys an XML attribute defined as
``lxml.objectify.PYTYPE_ATTRIBUTE``. It may contain any of the following
-string values: int, long, float, str, unicode, NoneType::
+string values: int, long, float, str, unicode, NoneType:
+
+.. sourcecode:: pycon
>>> print objectify.PYTYPE_ATTRIBUTE
{http://codespeak.net/lxml/objectify/pytype}pytype
@@ -821,7 +907,9 @@
attribute through the ``set_pytype_attribute_tag(tag)`` module
function, in case your application ever needs to. There is also a
utility function ``annotate()`` that recursively generates this
-attribute for the elements of a tree::
+attribute for the elements of a tree:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring("<root><a>test</a><b>5</b></root>")
>>> print objectify.dump(root)
@@ -844,7 +932,9 @@
A second way of specifying data type information uses XML Schema types as
element annotations. Objectify knows those that can be mapped to normal
-Python types::
+Python types:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring('''\
... <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -864,7 +954,9 @@
* xsi:type = 'xsd:string'
Again, there is a utility function ``xsiannotate()`` that recursively
-generates the "xsi:type" attribute for the elements of a tree::
+generates the "xsi:type" attribute for the elements of a tree:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring('''\
... <root><a>test</a><b>5</b><c>true</c></root>
@@ -891,7 +983,9 @@
`Defining additional data classes`_.
The utility function ``deannotate()`` can be used to get rid of 'py:pytype'
-and/or 'xsi:type' information::
+and/or 'xsi:type' information:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring('''\
... <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -925,7 +1019,9 @@
For convenience, the ``DataElement()`` factory creates an Element with a
Python value in one step. You can pass the required Python type name or the
-XSI type name::
+XSI type name:
+
+.. sourcecode:: pycon
>>> root = objectify.Element("root")
>>> root.x = objectify.DataElement(5, _pytype="long")
@@ -949,7 +1045,9 @@
* xsi:type = 'xsd:integer'
XML Schema types reside in the XML schema namespace thus ``DataElement()``
-tries to correctly prefix the xsi:type attribute value for you::
+tries to correctly prefix the xsi:type attribute value for you:
+
+.. sourcecode:: pycon
>>> root = objectify.Element("root")
>>> root.s = objectify.DataElement(5, _xsi="string")
@@ -960,7 +1058,9 @@
<s xsi:type="xsd:string">5</s>
</root>
-``DataElement()`` uses a default nsmap to set these prefixes::
+``DataElement()`` uses a default nsmap to set these prefixes:
+
+.. sourcecode:: pycon
>>> el = objectify.DataElement('5', _xsi='string')
>>> for prefix, namespace in el.nsmap.items():
@@ -973,7 +1073,9 @@
xsd:string
While you can set custom namespace prefixes, it is necessary to provide valid
-namespace information if you choose to do so::
+namespace information if you choose to do so:
+
+.. sourcecode:: pycon
>>> el = objectify.DataElement('5', _xsi='foo:string',
... nsmap={'foo': 'http://www.w3.org/2001/XMLSchema'})
@@ -987,7 +1089,9 @@
foo:string
Note how lxml chose a default prefix for the XML Schema Instance
-namespace. We can override it as in the following example::
+namespace. We can override it as in the following example:
+
+.. sourcecode:: pycon
>>> el = objectify.DataElement('5', _xsi='foo:string',
... nsmap={'foo': 'http://www.w3.org/2001/XMLSchema',
@@ -1004,7 +1108,9 @@
Care must be taken if different namespace prefixes have been used for the same
namespace. Namespace information gets merged to avoid duplicate definitions
when adding a new sub-element to a tree, but this mechanism does not adapt the
-prefixes of attribute values::
+prefixes of attribute values:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring("""<root xmlns:schema="http://www.w3.org/2001/XMLSchema"/>""")
>>> print etree.tostring(root, pretty_print=True)
@@ -1022,7 +1128,9 @@
It is your responsibility to fix the prefixes of attribute values if you
choose to deviate from the standard prefixes. A convenient way to do this for
-xsi:type attributes is to use the ``xsiannotate()`` utility::
+xsi:type attributes is to use the ``xsiannotate()`` utility:
+
+.. sourcecode:: pycon
>>> objectify.xsiannotate(root)
>>> print etree.tostring(root, pretty_print=True)
@@ -1045,7 +1153,9 @@
to set their type conversion function (string -> numeric Python type). This
call should be placed into the element ``_init()`` method.
-The registration of data classes uses the ``PyType`` class::
+The registration of data classes uses the ``PyType`` class:
+
+.. sourcecode:: pycon
>>> class ChristmasDate(objectify.ObjectifiedDataElement):
... def call_santa(self):
@@ -1067,14 +1177,18 @@
does not raise a ValueError/TypeError exception when applied to the element
text.
-If you want, you can also register this type under an XML Schema type name::
+If you want, you can also register this type under an XML Schema type name:
+
+.. sourcecode:: pycon
>>> xmas_type.xmlSchemaTypes = ("date",)
XML Schema types will be considered if the element has an ``xsi:type``
attribute that specifies its data type. The line above binds the XSD type
``date`` to the newly defined Python type. Note that this must be done before
-the next step, which is to register the type. Then you can use it::
+the next step, which is to register the type. Then you can use it:
+
+.. sourcecode:: pycon
>>> xmas_type.register()
@@ -1096,7 +1210,9 @@
the dependencies of already registered types.
If you provide XML Schema type information, this will override the type check
-function defined above::
+function defined above:
+
+.. sourcecode:: pycon
>>> root = objectify.fromstring('''\
... <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
@@ -1108,7 +1224,9 @@
>>> root.a.call_santa()
Ho ho ho!
-To unregister a type, call its ``unregister()`` method::
+To unregister a type, call its ``unregister()`` method:
+
+.. sourcecode:: pycon
>>> root.a.call_santa()
Ho ho ho!
@@ -1142,11 +1260,15 @@
this alters the document infoset, so if you consider the removed
spaces as data in your specific use case, you should go with a normal
parser and just set the element class lookup. Most applications,
-however, will work fine with the following setup::
+however, will work fine with the following setup:
+
+.. sourcecode:: pycon
>>> parser = objectify.makeparser(remove_blank_text=True)
-What this does internally, is::
+What this does internally, is:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(remove_blank_text=True)
@@ -1159,7 +1281,9 @@
however, you have to take care that the namespace classes inherit from
``objectify.ObjectifiedElement``, not only from the normal
``lxml.etree.ElementBase``, so that they support the ``objectify``
-API. The above setup code then becomes::
+API. The above setup code then becomes:
+
+.. sourcecode:: pycon
>>> lookup = etree.ElementNamespaceClassLookup(
... objectify.ObjectifyElementClassLookup() )
Modified: lxml/trunk/doc/parsing.txt
==============================================================================
--- lxml/trunk/doc/parsing.txt (original)
+++ lxml/trunk/doc/parsing.txt Mon Mar 3 19:43:14 2008
@@ -21,7 +21,9 @@
4.1 Serialising to Unicode strings
-The usual setup procedure::
+The usual setup procedure:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> from StringIO import StringIO
@@ -33,7 +35,9 @@
Parsers are represented by parser objects. There is support for parsing both
XML and (broken) HTML. Note that XHTML is best parsed as XML, parsing it with
the HTML parser can lead to unexpected results. Here is a simple example for
-parsing XML from an in-memory string::
+parsing XML from an in-memory string:
+
+.. sourcecode:: pycon
>>> xml = '<a xmlns="test"><b xmlns="test"/></a>'
@@ -42,7 +46,9 @@
<a xmlns="test"><b xmlns="test"/></a>
To read from a file or file-like object, you can use the ``parse()`` function,
-which returns an ``ElementTree`` object::
+which returns an ``ElementTree`` object:
+
+.. sourcecode:: pycon
>>> tree = etree.parse(StringIO(xml))
>>> print etree.tostring(tree.getroot())
@@ -50,7 +56,9 @@
Note how the ``parse()`` function reads from a file-like object here. If
parsing is done from a real file, it is more common (and also somewhat more
-efficient) to pass a filename::
+efficient) to pass a filename:
+
+.. sourcecode:: pycon
>>> tree = etree.parse("doc/test.xml")
@@ -59,7 +67,9 @@
If you want to parse from memory and still provide a base URL for the document
(e.g. to support relative paths in an XInclude), you can pass the ``base_url``
-keyword argument::
+keyword argument:
+
+.. sourcecode:: pycon
>>> root = etree.fromstring(xml, base_url="http://where.it/is/from.xml")
@@ -68,7 +78,9 @@
--------------
The parsers accept a number of setup options as keyword arguments. The above
-example is easily extended to clean up namespaces during parsing::
+example is easily extended to clean up namespaces during parsing:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(ns_clean=True)
>>> tree = etree.parse(StringIO(xml), parser)
@@ -105,7 +117,9 @@
---------
Parsers have an ``error_log`` property that lists the errors of the
-last parser run::
+last parser run:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser()
>>> print len(parser.error_log)
@@ -132,7 +146,9 @@
HTML parsing is similarly simple. The parsers have a ``recover`` keyword
argument that the HTMLParser sets by default. It lets libxml2 try its best to
return something usable without raising an exception. You should use libxml2
-version 2.6.21 or newer to take advantage of this feature::
+version 2.6.21 or newer to take advantage of this feature:
+
+.. sourcecode:: pycon
>>> broken_html = "<html><head><title>test<body><h1>page title</h3>"
@@ -150,7 +166,9 @@
</html>
Lxml has an HTML function, similar to the XML shortcut known from
-ElementTree::
+ElementTree:
+
+.. sourcecode:: pycon
>>> html = etree.HTML(broken_html)
>>> print etree.tostring(html, pretty_print=True),
@@ -178,7 +196,9 @@
The use of the libxml2 parsers makes some additional information available at
the API level. Currently, ElementTree objects can access the DOCTYPE
information provided by a parsed document, as well as the XML version and the
-original encoding::
+original encoding:
+
+.. sourcecode:: pycon
>>> pub_id = "-//W3C//DTD XHTML 1.0 Transitional//EN"
>>> sys_url = "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
@@ -207,7 +227,9 @@
.. _`As in ElementTree`: http://effbot.org/elementtree/elementtree-xmlparser.htm
`As in ElementTree`_, and similar to a SAX event handler, you can pass
-a target object to the parser::
+a target object to the parser:
+
+.. sourcecode:: pycon
>>> class EchoTarget:
... def start(self, tag, attrib):
@@ -248,7 +270,9 @@
.. _`ElementTree parsers`: http://effbot.org/elementtree/elementtree-xmlparser.htm
-To start parsing with a feed parser, just call its ``feed()`` method::
+To start parsing with a feed parser, just call its ``feed()`` method:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser()
@@ -257,7 +281,9 @@
When you are done parsing, you **must** call the ``close()`` method to
retrieve the root Element of the parse result document, and to unlock the
-parser::
+parser:
+
+.. sourcecode:: pycon
>>> root = parser.close()
@@ -280,7 +306,9 @@
``feed_error_log``. Errors in the feed parser do not show up in the
normal ``error_log`` and vice versa.
-You can also combine the feed parser interface with the target parser::
+You can also combine the feed parser interface with the target parser:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(target = EchoTarget())
@@ -312,7 +340,9 @@
The 'start' and 'end' events represent opening and closing elements and are
accompanied by the respective element. By default, only 'end' events are
-generated::
+generated:
+
+.. sourcecode:: pycon
>>> xml = '''\
... <root>
@@ -330,12 +360,16 @@
end {testns}empty-element
end root
-The resulting tree is available through the ``root`` property of the iterator::
+The resulting tree is available through the ``root`` property of the iterator:
+
+.. sourcecode:: pycon
>>> context.root.tag
'root'
-The other event types can be activated with the ``events`` keyword argument::
+The other event types can be activated with the ``events`` keyword argument:
+
+.. sourcecode:: pycon
>>> events = ("start", "end")
>>> context = etree.iterparse(StringIO(xml), events=events)
@@ -356,7 +390,9 @@
As an extension over ElementTree, lxml.etree accepts a ``tag`` keyword
argument just like ``element.iter(tag)``. This restricts events to a
-specific tag or namespace::
+specific tag or namespace:
+
+.. sourcecode:: pycon
>>> context = etree.iterparse(StringIO(xml), tag="element")
>>> for action, elem in context:
@@ -378,7 +414,9 @@
You can modify the element and its descendants when handling the 'end' event.
To save memory, for example, you can remove subtrees that are no longer
-needed::
+needed:
+
+.. sourcecode:: pycon
>>> context = etree.iterparse(StringIO(xml))
>>> for action, elem in context:
@@ -398,7 +436,9 @@
If you have elements with a long list of children in your XML file and want to
save more memory during parsing, you can clean up the preceding siblings of
-the current element::
+the current element:
+
+.. sourcecode:: pycon
>>> for event, element in etree.iterparse(StringIO(xml)):
... # ... do something with the element
@@ -415,7 +455,9 @@
code.
The 'start-ns' and 'end-ns' events notify about namespace declarations and
-generate tuples ``(prefix, URI)``::
+generate tuples ``(prefix, URI)``:
+
+.. sourcecode:: pycon
>>> events = ("start-ns", "end-ns")
>>> context = etree.iterparse(StringIO(xml), events=events)
@@ -432,7 +474,9 @@
--------
A second extension over ElementTree is the ``iterwalk()`` function. It
-behaves exactly like ``iterparse()``, but works on Elements and ElementTrees::
+behaves exactly like ``iterparse()``, but works on Elements and ElementTrees:
+
+.. sourcecode:: pycon
>>> root = etree.XML(xml)
@@ -464,7 +508,9 @@
library. First of all, where ElementTree would raise an exception, the
parsers in lxml.etree can handle unicode strings straight away. This is most
helpful for XML snippets embedded in source code using the ``XML()``
-function::
+function:
+
+.. sourcecode:: pycon
>>> uxml = u'<test> \uf8d1 + \uf8d2 </test>'
>>> uxml
@@ -472,7 +518,9 @@
>>> root = etree.XML(uxml)
This requires, however, that unicode strings do not specify a conflicting
-encoding themselves and thus lie about their real encoding::
+encoding themselves and thus lie about their real encoding:
+
+.. sourcecode:: pycon
>>> etree.XML(u'<?xml version="1.0" encoding="ASCII"?>\n' + uxml)
Traceback (most recent call last):
@@ -490,7 +538,9 @@
To serialize the result, you would normally use the ``tostring()``
module function, which serializes to plain ASCII by default or a
-number of other byte encodings if asked for::
+number of other byte encodings if asked for:
+
+.. sourcecode:: pycon
>>> etree.tostring(root)
'<test>  +  </test>'
@@ -499,7 +549,9 @@
'<test> \xef\xa3\x91 + \xef\xa3\x92 </test>'
As an extension, lxml.etree recognises the unicode type as encoding to
-build a Python unicode representation of a tree::
+build a Python unicode representation of a tree:
+
+.. sourcecode:: pycon
>>> etree.tostring(root, encoding=unicode)
u'<test> \uf8d1 + \uf8d2 </test>'
Modified: lxml/trunk/doc/performance.txt
==============================================================================
--- lxml/trunk/doc/performance.txt (original)
+++ lxml/trunk/doc/performance.txt Mon Mar 3 19:43:14 2008
@@ -470,7 +470,9 @@
.. _`benchmark proposal`: http://www.onlamp.com/pub/wlg/6291
.. _`Old Testament`: http://www.ibiblio.org/bosak/xml/eg/religion.2.00.xml.zip
-Now, Uche's original proposal was more or less the following::
+Now, Uche's original proposal was more or less the following:
+
+.. sourcecode:: python
def bench_ET():
tree = ElementTree.parse("ot.xml")
@@ -482,7 +484,9 @@
return len(result)
which takes about one second on my machine today. The faster ``iterparse()``
-variant looks like this::
+variant looks like this:
+
+.. sourcecode:: python
def bench_ET_iterparse():
result = []
@@ -507,7 +511,9 @@
One of the many great tools in lxml is XPath, a swiss army knife for finding
things in XML documents. It is possible to move the whole thing to a pure
-XPath implementation, which looks like this::
+XPath implementation, which looks like this:
+
+.. sourcecode:: python
def bench_lxml_xpath_all():
tree = etree.parse("ot.xml")
@@ -518,7 +524,9 @@
implementation (in lines of Python code) that I could come up with. Now, this
is already a rather complex XPath expression compared to the simple "//v"
ElementPath expression we started with. Since this is also valid XPath, let's
-try this instead::
+try this instead:
+
+.. sourcecode:: python
def bench_lxml_xpath():
tree = etree.parse("ot.xml")
@@ -536,7 +544,9 @@
what we had in the beginning. Under lxml, this runs in the same 0.12 seconds.
But there is one thing left to try. We can replace the simple ElementPath
-expression with a native tree iterator::
+expression with a native tree iterator:
+
+.. sourcecode:: python
def bench_lxml_getiterator():
tree = etree.parse("ot.xml")
@@ -633,11 +643,15 @@
A way to improve the normal attribute access time is static instantiation of
the Python objects, thus trading memory for speed. Just create a cache
-dictionary and run::
+dictionary and run:
+
+.. sourcecode:: python
cache[root] = list(root.iter())
-after parsing and::
+after parsing and:
+
+.. sourcecode:: python
del cache[root]
Modified: lxml/trunk/doc/resolvers.txt
==============================================================================
--- lxml/trunk/doc/resolvers.txt (original)
+++ lxml/trunk/doc/resolvers.txt Mon Mar 3 19:43:14 2008
@@ -16,7 +16,9 @@
Resolvers
---------
-Here is an example of a custom resolver::
+Here is an example of a custom resolver:
+
+.. sourcecode:: pycon
>>> from lxml import etree
@@ -44,14 +46,18 @@
terminates if ``resolve()`` returns the result of any of the above
``resolve_*()`` methods.
-Resolvers are registered local to a parser::
+Resolvers are registered local to a parser:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(load_dtd=True)
>>> parser.resolvers.add( DTDResolver() )
Note that we instantiate a parser that loads the DTD. This is not done by the
default parser, which does no validation. When we use this parser to parse a
-document that requires resolving a URL, it will call our custom resolver::
+document that requires resolving a URL, it will call our custom resolver:
+
+.. sourcecode:: pycon
>>> xml = u'<!DOCTYPE doc SYSTEM "MissingDTD.dtd"><doc>&myentity;</doc>'
>>> from StringIO import StringIO
@@ -71,7 +77,9 @@
XML documents memorise their initial parser (and its resolvers) during their
life-time. This means that a lookup process related to a document will use
the resolvers of the document's parser. We can demonstrate this with a
-resolver that only responds to a specific prefix::
+resolver that only responds to a specific prefix:
+
+.. sourcecode:: pycon
>>> class PrefixResolver(etree.Resolver):
... def __init__(self, prefix):
@@ -87,7 +95,9 @@
... print "Resolved url %s as prefix %s" % (url, self.prefix)
... return self.resolve_string(self.result_xml, context)
-We demonstrate this in XSLT and use the following stylesheet as an example::
+We demonstrate this in XSLT and use the following stylesheet as an example:
+
+.. sourcecode:: pycon
>>> xml_text = """\
... <xsl:stylesheet version="1.0"
@@ -105,7 +115,9 @@
document (i.e. when resolving ``xsl:import`` and ``xsl:include`` elements) and
``hoi:test`` at transformation time, when calls to the ``document`` function
are resolved. If we now register different resolvers with two different
-parsers, we can parse our document twice in different resolver contexts::
+parsers, we can parse our document twice in different resolver contexts:
+
+.. sourcecode:: pycon
>>> hoi_parser = etree.XMLParser()
>>> normal_doc = etree.parse(StringIO(xml_text), hoi_parser)
@@ -121,44 +133,52 @@
memorise their original parser so that the correct set of resolvers is used in
subsequent lookups. To compile the stylesheet, XSLT must resolve the
``honk:test`` URI in the ``xsl:include`` element. The ``hoi`` resolver cannot
-do that::
+do that:
+
+.. sourcecode:: pycon
>>> transform = etree.XSLT(normal_doc)
Traceback (most recent call last):
- [...]
+ ...
XSLTParseError: Cannot resolve URI honk:test
>>> transform = etree.XSLT(hoi_doc)
Traceback (most recent call last):
- [...]
+ ...
XSLTParseError: Cannot resolve URI honk:test
However, if we use the ``honk`` resolver associated with the respective
-document, everything works fine::
+document, everything works fine:
+
+.. sourcecode:: pycon
>>> transform = etree.XSLT(honk_doc)
Resolved url honk:test as prefix honk
Running the transform accesses the same parser context again, but since it now
needs to resolve the ``hoi`` URI in the call to the document function, its
-``honk`` resolver will fail to do so::
+``honk`` resolver will fail to do so:
+
+.. sourcecode:: pycon
>>> result = transform(normal_doc)
Traceback (most recent call last):
- [...]
+ ...
XSLTApplyError: Cannot resolve URI hoi:test
>>> result = transform(hoi_doc)
Traceback (most recent call last):
- [...]
+ ...
XSLTApplyError: Cannot resolve URI hoi:test
>>> result = transform(honk_doc)
Traceback (most recent call last):
- [...]
+ ...
XSLTApplyError: Cannot resolve URI hoi:test
-This can only be solved by adding a ``hoi`` resolver to the original parser::
+This can only be solved by adding a ``hoi`` resolver to the original parser:
+
+.. sourcecode:: pycon
>>> honk_parser.resolvers.add( PrefixResolver("hoi") )
>>> result = transform(honk_doc)
@@ -170,7 +190,9 @@
We can see that the ``hoi`` resolver was called to generate a document that
was then inserted into the result document by the XSLT transformation. Note
that this is completely independent of the XML file you transform, as the URI
-is resolved from within the stylesheet context::
+is resolved from within the stylesheet context:
+
+.. sourcecode:: pycon
>>> result = transform(normal_doc)
Resolved url hoi:test as prefix hoi
@@ -200,7 +222,9 @@
Access control is configured using the ``XSLTAccessControl`` class. It can be
called with a number of keyword arguments that allow or deny specific
-operations::
+operations:
+
+.. sourcecode:: pycon
>>> transform = etree.XSLT(honk_doc)
Resolved url honk:test as prefix honk
@@ -212,7 +236,7 @@
Resolved url honk:test as prefix honk
>>> result = transform(normal_doc)
Traceback (most recent call last):
- [...]
+ ...
XSLTApplyError: xsltLoadDocument: read rights for hoi:test denied
There are a few things to keep in mind:
Modified: lxml/trunk/doc/rest2html.py
==============================================================================
--- lxml/trunk/doc/rest2html.py (original)
+++ lxml/trunk/doc/rest2html.py Mon Mar 3 19:43:14 2008
@@ -1,23 +1,61 @@
#!/usr/bin/python
-# Author: David Goodger
-# Contact: goodger at python.org
-# Revision: $Revision: 3901 $
-# Date: $Date: 2005-09-25 17:49:54 +0200 (Sun, 25 Sep 2005) $
-# Copyright: This module has been placed in the public domain.
-
"""
-A minimal front end to the Docutils Publisher, producing HTML.
+A minimal front end to the Docutils Publisher, producing HTML with
+Pygments syntax highlighting.
"""
+# Set to True if you want inline CSS styles instead of classes
+INLINESTYLES = False
+
+
try:
import locale
locale.setlocale(locale.LC_ALL, '')
except:
pass
-from docutils.core import publish_cmdline, default_description
+# set up Pygments
+
+from pygments.formatters import HtmlFormatter
+
+# The default formatter
+DEFAULT = HtmlFormatter(noclasses=INLINESTYLES, cssclass='syntax')
+
+# Add name -> formatter pairs for every variant you want to use
+VARIANTS = {
+ # 'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True),
+}
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name, TextLexer
+
+def pygments_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ try:
+ lexer = get_lexer_by_name(arguments[0])
+ except ValueError, e:
+ # no lexer found - use the text one instead of an exception
+ lexer = TextLexer()
+ # take an arbitrary option if more than one is given
+ formatter = options and VARIANTS[options.keys()[0]] or DEFAULT
+ parsed = highlight(u'\n'.join(content), lexer, formatter)
+ return [nodes.raw('', parsed, format='html')]
+
+pygments_directive.arguments = (1, 0, 1)
+pygments_directive.content = 1
+pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])
+
+directives.register_directive('sourcecode', pygments_directive)
+
+
+# run the generation
+
+from docutils.core import publish_cmdline, default_description
description = ('Generates (X)HTML documents from standalone reStructuredText '
'sources. ' + default_description)
Modified: lxml/trunk/doc/sax.txt
==============================================================================
--- lxml/trunk/doc/sax.txt (original)
+++ lxml/trunk/doc/sax.txt Mon Mar 3 19:43:14 2008
@@ -19,12 +19,16 @@
First of all, lxml has support for building a new tree given SAX events. To
do this, we use the special SAX content handler defined by lxml named
-``lxml.sax.ElementTreeContentHandler``::
+``lxml.sax.ElementTreeContentHandler``:
+
+.. sourcecode:: pycon
>>> import lxml.sax
>>> handler = lxml.sax.ElementTreeContentHandler()
-Now let's fire some SAX events at it::
+Now let's fire some SAX events at it:
+
+.. sourcecode:: pycon
>>> handler.startElementNS((None, 'a'), 'a', {})
>>> handler.startElementNS((None, 'b'), 'b', {(None, 'foo'): 'bar'})
@@ -33,7 +37,9 @@
>>> handler.endElementNS((None, 'a'), 'a')
This constructs an equivalent tree. You can access it through the ``etree``
-property of the handler::
+property of the handler:
+
+.. sourcecode:: pycon
>>> tree = handler.etree
>>> lxml.etree.tostring(tree.getroot())
@@ -47,14 +53,18 @@
Producing SAX events from an ElementTree or Element
---------------------------------------------------
-Let's make a tree we can generate SAX events for::
+Let's make a tree we can generate SAX events for:
+
+.. sourcecode:: pycon
>>> from StringIO import StringIO
>>> f = StringIO('<a><b>Text</b></a>')
>>> tree = lxml.etree.parse(f)
To see whether the correct SAX events are produced, we'll write a custom
-content handler.::
+content handler.:
+
+.. sourcecode:: pycon
>>> from xml.sax.handler import ContentHandler
>>> class MyContentHandler(ContentHandler):
@@ -77,12 +87,16 @@
The SAX event generator in lxml.sax currently only supports namespace-aware
processing.
-To test the content handler, we can produce SAX events from the tree::
+To test the content handler, we can produce SAX events from the tree:
+
+.. sourcecode:: pycon
>>> handler = MyContentHandler()
>>> lxml.sax.saxify(tree, handler)
-This is what we expect::
+This is what we expect:
+
+.. sourcecode:: pycon
>>> handler.a_amount
1
@@ -99,13 +113,17 @@
Python library. Note, however, that this is a one-way solution, as Python's
DOM implementation connot generate SAX events from a DOM tree.
-You can use xml.dom.pulldom to build a minidom from lxml::
+You can use xml.dom.pulldom to build a minidom from lxml:
+
+.. sourcecode:: pycon
>>> from xml.dom.pulldom import SAX2DOM
>>> handler = SAX2DOM()
>>> lxml.sax.saxify(tree, handler)
-PullDOM makes the result available through the ``document`` attribute::
+PullDOM makes the result available through the ``document`` attribute:
+
+.. sourcecode:: pycon
>>> dom = handler.document
>>> print dom.firstChild.localName
Modified: lxml/trunk/doc/tutorial.txt
==============================================================================
--- lxml/trunk/doc/tutorial.txt (original)
+++ lxml/trunk/doc/tutorial.txt Mon Mar 3 19:43:14 2008
@@ -37,13 +37,17 @@
6 ElementPath
-A common way to import ``lxml.etree`` is as follows::
+A common way to import ``lxml.etree`` is as follows:
+
+.. sourcecode:: pycon
>>> from lxml import etree
If your code only uses the ElementTree API and does not rely on any
functionality that is specific to ``lxml.etree``, you can also use (any part
-of) the following import chain as a fall-back to the original ElementTree::
+of) the following import chain as a fall-back to the original ElementTree:
+
+.. sourcecode:: python
try:
from lxml import etree
@@ -84,28 +88,38 @@
An ``Element`` is the main container object for the ElementTree API. Most of
the XML tree functionality is accessed through this class. Elements are
-easily created through the ``Element`` factory::
+easily created through the ``Element`` factory:
+
+.. sourcecode:: pycon
>>> root = etree.Element("root")
-The XML tag name of elements is accessed through the ``tag`` property::
+The XML tag name of elements is accessed through the ``tag`` property:
+
+.. sourcecode:: pycon
>>> print root.tag
root
Elements are organised in an XML tree structure. To create child elements and
-add them to a parent element, you can use the ``append()`` method::
+add them to a parent element, you can use the ``append()`` method:
+
+.. sourcecode:: pycon
>>> root.append( etree.Element("child1") )
However, this is so common that there is a shorter and much more efficient way
to do this: the ``SubElement`` factory. It accepts the same arguments as the
-``Element`` factory, but additionally requires the parent as first argument::
+``Element`` factory, but additionally requires the parent as first argument:
+
+.. sourcecode:: pycon
>>> child2 = etree.SubElement(root, "child2")
>>> child3 = etree.SubElement(root, "child3")
-To see that this is really XML, you can serialise the tree you have created::
+To see that this is really XML, you can serialise the tree you have created:
+
+.. sourcecode:: pycon
>>> print etree.tostring(root, pretty_print=True),
<root>
@@ -119,7 +133,9 @@
------------------
To make the access to these subelements as easy and straight forward as
-possible, elements behave like normal Python lists::
+possible, elements behave like normal Python lists:
+
+.. sourcecode:: pycon
>>> child = root[0]
>>> print child.tag
@@ -169,7 +185,9 @@
If you want to *copy* an element to a different position, consider creating an
independent *deep copy* using the ``copy`` module from Python's standard
-library::
+library:
+
+.. sourcecode:: pycon
>>> from copy import deepcopy
@@ -181,13 +199,17 @@
>>> print [ c.tag for c in root ]
['child3', 'child1', 'child2']
-The way up in the tree is provided through the ``getparent()`` method::
+The way up in the tree is provided through the ``getparent()`` method:
+
+.. sourcecode:: pycon
>>> root is root[0].getparent() # lxml.etree only!
True
The siblings (or neighbours) of an element are accessed as next and previous
-elements::
+elements:
+
+.. sourcecode:: pycon
>>> root[0] is root[1].getprevious() # lxml.etree only!
True
@@ -199,14 +221,18 @@
-------------------------
XML elements support attributes. You can create them directly in the Element
-factory::
+factory:
+
+.. sourcecode:: pycon
>>> root = etree.Element("root", interesting="totally")
>>> print etree.tostring(root)
<root interesting="totally"/>
Fast and direct access to these attributes is provided by the ``set()`` and
-``get()`` methods of elements::
+``get()`` methods of elements:
+
+.. sourcecode:: pycon
>>> print root.get("interesting")
totally
@@ -216,7 +242,9 @@
somewhat
However, a very convenient way of dealing with them is through the dictionary
-interface of the ``attrib`` property::
+interface of the ``attrib`` property:
+
+.. sourcecode:: pycon
>>> attributes = root.attrib
@@ -236,7 +264,9 @@
Elements contain text
---------------------
-Elements can contain text::
+Elements can contain text:
+
+.. sourcecode:: pycon
>>> root = etree.Element("root")
>>> root.text = "TEXT"
@@ -252,14 +282,18 @@
tree hierarchy.
However, if XML is used for tagged text documents such as (X)HTML, text can
-also appear between different elements, right in the middle of the tree::
+also appear between different elements, right in the middle of the tree:
+
+.. sourcecode:: html
<html><body>Hello<br/>World</body></html>
Here, the ``<br/>`` tag is surrounded by text. This is often referred to as
*document-style* or *mixed-content* XML. Elements support this through their
``tail`` property. It contains the text that directly follows the element, up
-to the next element in the XML tree::
+to the next element in the XML tree:
+
+.. sourcecode:: pycon
>>> html = etree.Element("html")
>>> body = etree.SubElement(html, "body")
@@ -286,7 +320,9 @@
For example, when you serialise an Element from within the tree, you
do not always want its tail text in the result (although you would
still want the tail text of its children). For this purpose, the
-``tostring()`` function accepts the keyword argument ``with_tail``::
+``tostring()`` function accepts the keyword argument ``with_tail``:
+
+.. sourcecode:: pycon
>>> print etree.tostring(br)
<br/>TAIL
@@ -299,7 +335,9 @@
If you want to read *only* the text, i.e. without any intermediate
tags, you have to recursively concatenate all ``text`` and ``tail``
attributes in the correct order. Again, the ``tostring()`` function
-comes to the rescue, this time using the ``method`` keyword::
+comes to the rescue, this time using the ``method`` keyword:
+
+.. sourcecode:: pycon
>>> print etree.tostring(html, method="text")
TEXTTAIL
@@ -311,14 +349,18 @@
.. _XPath: xpathxslt.html#xpath
Another way to extract the text content of a tree is XPath_, which
-also allows you to extract the separate text chunks into a list::
+also allows you to extract the separate text chunks into a list:
+
+.. sourcecode:: pycon
>>> print html.xpath("string()") # lxml.etree only!
TEXTTAIL
>>> print html.xpath("//text()") # lxml.etree only!
['TEXT', 'TAIL']
-If you want to use this more often, you can wrap it in a function::
+If you want to use this more often, you can wrap it in a function:
+
+.. sourcecode:: pycon
>>> build_text_list = etree.XPath("//text()") # lxml.etree only!
>>> print build_text_list(html)
@@ -327,7 +369,9 @@
Note that a string result returned by XPath is a special 'smart'
object that knows about its origins. You can ask it where it came
from through its ``getparent()`` method, just as you would with
-Elements::
+Elements:
+
+.. sourcecode:: pycon
>>> texts = build_text_list(html)
>>> print texts[0]
@@ -341,7 +385,9 @@
>>> print texts[1].getparent().tag
br
-You can also find out if it's normal text content or tail text::
+You can also find out if it's normal text content or tail text:
+
+.. sourcecode:: pycon
>>> print texts[0].is_text
True
@@ -352,7 +398,9 @@
While this works for the results of the ``text()`` function, lxml will
not to tell you the origin of a string value that was constructed by
-the XPath functions ``string()`` or ``concat()``::
+the XPath functions ``string()`` or ``concat()``:
+
+.. sourcecode:: pycon
>>> stringify = etree.XPath("string()")
>>> print stringify(html)
@@ -368,7 +416,9 @@
and do something with its elements, tree iteration is a very convenient
solution. Elements provide a tree iterator for this purpose. It yields
elements in *document order*, i.e. in the order their tags would appear if you
-serialised the tree to XML::
+serialised the tree to XML:
+
+.. sourcecode:: pycon
>>> root = etree.Element("root")
>>> etree.SubElement(root, "child").text = "Child 1"
@@ -390,7 +440,9 @@
another - Child 3
If you know you are only interested in a single tag, you can pass its name to
-``iter()`` to have it filter for you::
+``iter()`` to have it filter for you:
+
+.. sourcecode:: pycon
>>> for element in root.iter("child"):
... print element.tag, '-', element.text
@@ -400,7 +452,9 @@
By default, iteration yields all nodes in the tree, including
ProcessingInstructions, Comments and Entity instances. If you want to
make sure only Element objects are returned, you can pass the
-``Element`` factory as tag parameter::
+``Element`` factory as tag parameter:
+
+.. sourcecode:: pycon
>>> root.append(etree.Entity("#234"))
>>> root.append(etree.Comment("some comment"))
@@ -441,7 +495,9 @@
string, or the ``ElementTree.write()`` method that writes to a file or
file-like object. Both accept the same keyword arguments like
``pretty_print`` for formatted output or ``encoding`` to select a
-specific output encoding other than plain ASCII::
+specific output encoding other than plain ASCII:
+
+.. sourcecode:: pycon
>>> root = etree.XML('<root><a><b/></a></root>')
@@ -468,7 +524,9 @@
Since lxml 2.0 (and ElementTree 1.3), the serialisation functions can
do more than XML serialisation. You can serialise to HTML or extract
-the text content by passing the ``method`` keyword::
+the text content by passing the ``method`` keyword:
+
+.. sourcecode:: pycon
>>> root = etree.XML('<html><head/><body><p>Hello<br/>World</p></body></html>')
@@ -491,7 +549,9 @@
HelloWorld
For the plain text output, serialising to a Python unicode string
-might become handy. Just pass the ``unicode`` type as encoding::
+might become handy. Just pass the ``unicode`` type as encoding:
+
+.. sourcecode:: pycon
>>> etree.tostring(root, encoding=unicode, method='text')
u'HelloWorld'
@@ -505,7 +565,9 @@
and general document handling. One of the bigger differences is that
it serialises as a complete document, as opposed to a single
``Element``. This includes top-level processing instructions and
-comments, as well as a DOCTYPE and other DTD content in the document::
+comments, as well as a DOCTYPE and other DTD content in the document:
+
+.. sourcecode:: pycon
>>> from StringIO import StringIO
>>> tree = etree.parse(StringIO('''\
@@ -562,7 +624,9 @@
The fromstring() function
-------------------------
-The ``fromstring()`` function is the easiest way to parse a string::
+The ``fromstring()`` function is the easiest way to parse a string:
+
+.. sourcecode:: pycon
>>> some_xml_data = "<root>data</root>"
@@ -577,7 +641,9 @@
------------------
The ``XML()`` function behaves like the ``fromstring()`` function, but is
-commonly used to write XML literals right into the source::
+commonly used to write XML literals right into the source:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root>data</root>")
>>> print root.tag
@@ -589,7 +655,9 @@
The parse() function
--------------------
-The ``parse()`` function is used to parse from files and file-like objects::
+The ``parse()`` function is used to parse from files and file-like objects:
+
+.. sourcecode:: pycon
>>> some_file_like = StringIO("<root>data</root>")
@@ -599,7 +667,9 @@
<root>data</root>
Note that ``parse()`` returns an ElementTree object, not an Element object as
-the string parser functions::
+the string parser functions:
+
+.. sourcecode:: pycon
>>> root = tree.getroot()
>>> print root.tag
@@ -630,13 +700,17 @@
--------------
By default, ``lxml.etree`` uses a standard parser with a default setup. If
-you want to configure the parser, you can create a you instance::
+you want to configure the parser, you can create a you instance:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(remove_blank_text=True) # lxml.etree only!
This creates a parser that removes empty text between tags while parsing,
which can reduce the size of the tree and avoid dangling tail text if you know
-that whitespace-only content is not meaningful for your data. An example::
+that whitespace-only content is not meaningful for your data. An example:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root> <a/> <b> </b> </root>", parser)
@@ -645,7 +719,9 @@
Note that the whitespace content inside the ``<b>`` tag was not removed, as
content at leaf elements tends to be data content (even if blank). You can
-easily remove it in an additional step by traversing the tree::
+easily remove it in an additional step by traversing the tree:
+
+.. sourcecode:: pycon
>>> for element in root.iter("*"):
... if element.text is not None and not element.text.strip():
@@ -664,7 +740,9 @@
through file-like objects, where it calls the ``read()`` method repeatedly.
This is best used where the data arrives from a source like ``urllib`` or any
other file-like object that can provide data on request. Note that the parser
-will block and wait until data becomes available in this case::
+will block and wait until data becomes available in this case:
+
+.. sourcecode:: pycon
>>> class DataSource:
... data = iter(["<roo", "t><", "a/", "><", "/root>"])
@@ -680,7 +758,9 @@
<root><a/></root>
The second way is through a feed parser interface, given by the ``feed(data)``
-and ``close()`` methods::
+and ``close()`` methods:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser()
@@ -703,7 +783,9 @@
After calling the ``close()`` method (or when an exception was raised
by the parser), you can reuse the parser by calling its ``feed()``
-method again::
+method again:
+
+.. sourcecode:: pycon
>>> parser.feed("<root/>")
>>> root = parser.close()
@@ -722,7 +804,9 @@
at all, and instead calls feedback methods on a target object in a SAX-like
fashion.
-Here is a simple ``iterparse()`` example::
+Here is a simple ``iterparse()`` example:
+
+.. sourcecode:: pycon
>>> some_file_like = StringIO("<root><a>data</a></root>")
@@ -732,7 +816,9 @@
end, root, None
By default, ``iterparse()`` only generates events when it is done parsing an
-element, but you can control this through the ``events`` keyword argument::
+element, but you can control this through the ``events`` keyword argument:
+
+.. sourcecode:: pycon
>>> some_file_like = StringIO("<root><a>data</a></root>")
@@ -752,7 +838,9 @@
If memory is a real bottleneck, or if building the tree is not desired at all,
the target parser interface of ``lxml.etree`` can be used. It creates
SAX-like events by calling the methods of a target object. By implementing
-some or all of these methods, you can control which events are generated::
+some or all of these methods, you can control which events are generated:
+
+.. sourcecode:: pycon
>>> class ParserTarget:
... events = []
@@ -776,7 +864,9 @@
==========
The ElementTree API avoids `namespace prefixes`_ wherever possible and deploys
-the real namespaces instead::
+the real namespaces instead:
+
+.. sourcecode:: pycon
>>> xhtml = etree.Element("{http://www.w3.org/1999/xhtml}html")
>>> body = etree.SubElement(xhtml, "{http://www.w3.org/1999/xhtml}body")
@@ -794,7 +884,9 @@
names. And retyping or copying a string over and over again is error prone.
It is therefore common practice to store a namespace URI in a global variable.
To adapt the namespace prefixes for serialisation, you can also pass a mapping
-to the Element factory, e.g. to define the default namespace::
+to the Element factory, e.g. to define the default namespace:
+
+.. sourcecode:: pycon
>>> XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml"
>>> XHTML = "{%s}" % XHTML_NAMESPACE
@@ -810,7 +902,9 @@
<body>Hello World</body>
</html>
-Namespaces on attributes work alike::
+Namespaces on attributes work alike:
+
+.. sourcecode:: pycon
>>> body.set(XHTML + "bgcolor", "#CCFFAA")
@@ -824,7 +918,9 @@
>>> body.get(XHTML + "bgcolor")
'#CCFFAA'
-You can also use XPath in this way::
+You can also use XPath in this way:
+
+.. sourcecode:: pycon
>>> find_xhtml_body = etree.ETXPath( # lxml only !
... "//{%s}body" % XHTML_NAMESPACE)
@@ -838,7 +934,9 @@
=============
The ``E-factory`` provides a simple and compact syntax for generating XML and
-HTML::
+HTML:
+
+.. sourcecode:: pycon
>>> from lxml.builder import E
@@ -877,7 +975,9 @@
</html>
The Element creation based on attribute access makes it easy to build up a
-simple vocabulary for an XML language::
+simple vocabulary for an XML language:
+
+.. sourcecode:: pycon
>>> from lxml.builder import ElementMaker # lxml only !
@@ -946,25 +1046,33 @@
* ``findtext()`` returns the ``.text`` content of the first match
-Here are some examples::
+Here are some examples:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root><a x='123'>aText<b/><c/><b/></a></root>")
-Find a child of an Element::
+Find a child of an Element:
+
+.. sourcecode:: pycon
>>> print root.find("b")
None
>>> print root.find("a").tag
a
-Find an Element anywhere in the tree::
+Find an Element anywhere in the tree:
+
+.. sourcecode:: pycon
>>> print root.find(".//b").tag
b
>>> [ b.tag for b in root.iterfind(".//b") ]
['b', 'b']
-Find Elements with a certain attribute::
+Find Elements with a certain attribute:
+
+.. sourcecode:: pycon
>>> print root.findall(".//a[@x]")[0].tag
a
Modified: lxml/trunk/doc/validation.txt
==============================================================================
--- lxml/trunk/doc/validation.txt (original)
+++ lxml/trunk/doc/validation.txt Mon Mar 3 19:43:14 2008
@@ -25,7 +25,9 @@
4 XMLSchema
5 Schematron
-The usual setup procedure::
+The usual setup procedure:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> from StringIO import StringIO
@@ -37,7 +39,9 @@
The parser in lxml can do on-the-fly validation of a document against
a DTD or an XML schema. The DTD is retrieved automatically based on
the DOCTYPE of the parsed document. All you have to do is use a
-parser that has DTD validation enabled::
+parser that has DTD validation enabled:
+
+.. sourcecode:: pycon
>>> parser = etree.XMLParser(dtd_validation=True)
@@ -56,7 +60,9 @@
performed unless explicitly requested.
XML schema is supported in a similar way, but requires an explicit
-schema to be provided::
+schema to be provided:
+
+.. sourcecode:: pycon
>>> schema_root = etree.XML('''\
... <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
@@ -69,7 +75,9 @@
>>> root = etree.fromstring("<a>5</a>", parser)
If the validation fails (be it for a DTD or an XML schema), the parser
-will raise an exception::
+will raise an exception:
+
+.. sourcecode:: pycon
>>> root = etree.fromstring("<a>no int</a>", parser)
Traceback (most recent call last):
@@ -90,12 +98,16 @@
referenced by the document itself, you can use the ``DTD`` class.
To use the ``DTD`` class, you must first pass a filename or file-like object
-into the constructor to parse a DTD::
+into the constructor to parse a DTD:
+
+.. sourcecode:: pycon
>>> f = StringIO("<!ELEMENT b EMPTY>")
>>> dtd = etree.DTD(f)
-Now you can use it to validate documents::
+Now you can use it to validate documents:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<b/>")
>>> print dtd.validate(root)
@@ -105,7 +117,9 @@
>>> print dtd.validate(root)
False
-The reason for the validation failure can be found in the error log::
+The reason for the validation failure can be found in the error log:
+
+.. sourcecode:: pycon
>>> print dtd.error_log.filter_from_errors()[0]
<string>:1:0:ERROR:VALID:DTD_NOT_EMPTY: Element b was declared EMPTY this one has content
@@ -113,7 +127,9 @@
As an alternative to parsing from a file, you can use the
``external_id`` keyword argument to parse from a catalog. The
following example reads the DocBook DTD in version 4.2, if available
-in the system catalog::
+in the system catalog:
+
+.. sourcecode:: python
dtd = etree.DTD(external_id = "-//OASIS//DTD DocBook XML V4.2//EN")
@@ -122,7 +138,9 @@
-------
The ``RelaxNG`` class takes an ElementTree object to construct a Relax NG
-validator::
+validator:
+
+.. sourcecode:: pycon
>>> f = StringIO('''\
... <element name="a" xmlns="http://relaxng.org/ns/structure/1.0">
@@ -142,7 +160,9 @@
You can then validate some ElementTree document against the schema. You'll get
back True if the document is valid against the Relax NG schema, and False if
-not::
+not:
+
+.. sourcecode:: pycon
>>> valid = StringIO('<a><b></b></a>')
>>> doc = etree.parse(valid)
@@ -155,7 +175,9 @@
False
Calling the schema object has the same effect as calling its validate
-method. This is sometimes used in conditional statements::
+method. This is sometimes used in conditional statements:
+
+.. sourcecode:: pycon
>>> invalid = StringIO('<a><c></c></a>')
>>> doc2 = etree.parse(invalid)
@@ -164,21 +186,25 @@
invalid!
If you prefer getting an exception when validating, you can use the
-``assert_`` or ``assertValid`` methods::
+``assert_`` or ``assertValid`` methods:
+
+.. sourcecode:: pycon
>>> relaxng.assertValid(doc2)
Traceback (most recent call last):
- [...]
+ ...
DocumentInvalid: Did not expect element c there, line 1
>>> relaxng.assert_(doc2)
Traceback (most recent call last):
- [...]
+ ...
AssertionError: Did not expect element c there, line 1
If you want to find out why the validation failed in the second case, you can
look up the error log of the validation process and check it for relevant
-messages::
+messages:
+
+.. sourcecode:: pycon
>>> log = relaxng.error_log
>>> print log.last_error
@@ -186,7 +212,9 @@
You can see that the error (ERROR) happened during RelaxNG validation
(RELAXNGV). The message then tells you what went wrong. You can also
-look at the error domain and its type directly::
+look at the error domain and its type directly:
+
+.. sourcecode:: pycon
>>> error = log.last_error
>>> print error.domain_name
@@ -198,7 +226,9 @@
contain log entries that appeared during the validation.
Similar to XSLT, there's also a less efficient but easier shortcut method to
-do one-shot RelaxNG validation::
+do one-shot RelaxNG validation:
+
+.. sourcecode:: pycon
>>> doc.relaxng(relaxng_doc)
True
@@ -218,7 +248,9 @@
lxml.etree also has XML Schema (XSD) support, using the class
lxml.etree.XMLSchema. The API is very similar to the Relax NG and DTD
-classes. Pass an ElementTree object to construct a XMLSchema validator::
+classes. Pass an ElementTree object to construct a XMLSchema validator:
+
+.. sourcecode:: pycon
>>> f = StringIO('''\
... <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
@@ -235,7 +267,9 @@
You can then validate some ElementTree document with this. Like with RelaxNG,
you'll get back true if the document is valid against the XML schema, and
-false if not::
+false if not:
+
+.. sourcecode:: pycon
>>> valid = StringIO('<a><b></b></a>')
>>> doc = etree.parse(valid)
@@ -248,7 +282,9 @@
False
Calling the schema object has the same effect as calling its validate method.
-This is sometimes used in conditional statements::
+This is sometimes used in conditional statements:
+
+.. sourcecode:: pycon
>>> invalid = StringIO('<a><c></c></a>')
>>> doc2 = etree.parse(invalid)
@@ -257,19 +293,23 @@
invalid!
If you prefer getting an exception when validating, you can use the
-``assert_`` or ``assertValid`` methods::
+``assert_`` or ``assertValid`` methods:
+
+.. sourcecode:: pycon
>>> xmlschema.assertValid(doc2)
Traceback (most recent call last):
- [...]
+ ...
DocumentInvalid: Element 'c': This element is not expected. Expected is ( b )., line 1
>>> xmlschema.assert_(doc2)
Traceback (most recent call last):
- [...]
+ ...
AssertionError: Element 'c': This element is not expected. Expected is ( b )., line 1
-Error reporting works as for the RelaxNG class::
+Error reporting works as for the RelaxNG class:
+
+.. sourcecode:: pycon
>>> log = xmlschema.error_log
>>> error = log.last_error
@@ -285,7 +325,9 @@
<string>:1:ERROR::SCHEMAV_ELEMENT_CONTENT: Element 'c': This element is not expected. Expected is ( b ).
Similar to XSLT and RelaxNG, there's also a less efficient but easier shortcut
-method to do XML Schema validation::
+method to do XML Schema validation:
+
+.. sourcecode:: pycon
>>> doc.xmlschema(xmlschema_doc)
True
@@ -299,7 +341,9 @@
Since version 2.0, lxml.etree features Schematron_ support, using the
class lxml.etree.Schematron. It requires at least libxml2 2.6.21 to
work. The API is the same as for the other validators. Pass an
-ElementTree object to construct a Schematron validator::
+ElementTree object to construct a Schematron validator:
+
+.. sourcecode:: pycon
>>> f = StringIO('''\
... <schema xmlns="http://www.ascc.net/xml/schematron" >
@@ -316,7 +360,9 @@
You can then validate some ElementTree document with this. Like with RelaxNG,
you'll get back true if the document is valid against the schema, and false if
-not::
+not:
+
+.. sourcecode:: pycon
>>> valid = StringIO('''\
... <Total>
@@ -336,7 +382,9 @@
False
Calling the schema object has the same effect as calling its validate method.
-This is sometimes used in conditional statements::
+This is sometimes used in conditional statements:
+
+.. sourcecode:: pycon
>>> is_valid = etree.Schematron(sct_doc)
Modified: lxml/trunk/doc/xpathxslt.txt
==============================================================================
--- lxml/trunk/doc/xpathxslt.txt (original)
+++ lxml/trunk/doc/xpathxslt.txt Mon Mar 3 19:43:14 2008
@@ -23,7 +23,9 @@
2.5 Profiling
-The usual setup procedure::
+The usual setup procedure:
+
+.. sourcecode:: pycon
>>> from lxml import etree
>>> from StringIO import StringIO
@@ -55,7 +57,9 @@
----------------------
For ElementTree, the xpath method performs a global XPath query against the
-document (if absolute) or against the root node (if relative)::
+document (if absolute) or against the root node (if relative):
+
+.. sourcecode:: pycon
>>> f = StringIO('<foo><bar></bar></foo>')
>>> tree = etree.parse(f)
@@ -71,7 +75,9 @@
'bar'
When ``xpath()`` is used on an Element, the XPath expression is evaluated
-against the element (if relative) or against the root tree (if absolute)::
+against the element (if relative) or against the root tree (if absolute):
+
+.. sourcecode:: pycon
>>> root = tree.getroot()
>>> r = root.xpath('bar')
@@ -88,7 +94,9 @@
>>> r[0].tag
'bar'
-The ``xpath()`` method has support for XPath variables::
+The ``xpath()`` method has support for XPath variables:
+
+.. sourcecode:: pycon
>>> expr = "//*[local-name() = $name]"
@@ -103,7 +111,9 @@
Optionally, you can provide a ``namespaces`` keyword argument, which should be
a dictionary mapping the namespace prefixes used in the XPath expression to
-namespace URIs::
+namespace URIs:
+
+.. sourcecode:: pycon
>>> f = StringIO('''\
... <a:foo xmlns:a="http://codespeak.net/ns/test1"
@@ -169,7 +179,9 @@
----------------------------
ElementTree objects have a method ``getpath(element)``, which returns a
-structural, absolute XPath expression to find that element::
+structural, absolute XPath expression to find that element:
+
+.. sourcecode:: pycon
>>> a = etree.Element("a")
>>> b = etree.SubElement(a, "b")
@@ -187,7 +199,9 @@
The ``XPath`` class
-------------------
-The ``XPath`` class compiles an XPath expression into a callable function::
+The ``XPath`` class compiles an XPath expression into a callable function:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root><a><b/></a><b/></root>")
@@ -200,7 +214,9 @@
for repeated evaluation of the same XPath expression.
Just like the ``xpath()`` method, the ``XPath`` class supports XPath
-variables::
+variables:
+
+.. sourcecode:: pycon
>>> count_elements = etree.XPath("count(//*[local-name() = $name])")
@@ -212,7 +228,9 @@
This supports very efficient evaluation of modified versions of an XPath
expression, as compilation is still only required once.
-Prefix-to-namespace mappings can be passed as second parameter::
+Prefix-to-namespace mappings can be passed as second parameter:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root xmlns='NS'><a><b/></a><b/></root>")
@@ -220,7 +238,9 @@
>>> print find(root)[0].tag
{NS}b
-By default, ``XPath`` supports regular expressions in the EXSLT_ namespace::
+By default, ``XPath`` supports regular expressions in the EXSLT_ namespace:
+
+.. sourcecode:: pycon
>>> regexpNS = "http://exslt.org/regular-expressions"
>>> find = etree.XPath("//*[re:test(., '^abc$', 'i')]",
@@ -242,7 +262,9 @@
lxml.etree provides two other efficient XPath evaluators that work on
ElementTrees or Elements respectively: ``XPathDocumentEvaluator`` and
``XPathElementEvaluator``. They are automatically selected if you use the
-XPathEvaluator helper for instantiation::
+XPathEvaluator helper for instantiation:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root><a><b/></a><b/></root>")
>>> xpatheval = etree.XPathEvaluator(root)
@@ -274,7 +296,9 @@
lxml.etree bridges this gap through the class ``ETXPath``, which accepts XPath
expressions with namespaces in Clark notation. It is identical to the
``XPath`` class, except for the namespace notation. Normally, you would
-write::
+write:
+
+.. sourcecode:: pycon
>>> root = etree.XML("<root xmlns='ns'><a><b/></a><b/></root>")
@@ -282,7 +306,9 @@
>>> print find(root)[0].tag
{ns}b
-``ETXPath`` allows you to change this to::
+``ETXPath`` allows you to change this to:
+
+.. sourcecode:: pycon
>>> find = etree.ETXPath("//{ns}b")
>>> print find(root)[0].tag
@@ -293,7 +319,9 @@
--------------
lxml.etree raises exceptions when errors occur while parsing or evaluating an
-XPath expression::
+XPath expression:
+
+.. sourcecode:: pycon
>>> find = etree.XPath("\\")
Traceback (most recent call last):
@@ -301,14 +329,18 @@
XPathSyntaxError: Invalid expression
lxml will also try to give you a hint what went wrong, so if you pass a more
-complex expression, you may get a somewhat more specific error::
+complex expression, you may get a somewhat more specific error:
+
+.. sourcecode:: pycon
>>> find = etree.XPath("//*[1.1.1]")
Traceback (most recent call last):
...
XPathSyntaxError: Invalid predicate
-During evaluation, lxml will emit an XPathEvalError on errors::
+During evaluation, lxml will emit an XPathEvalError on errors:
+
+.. sourcecode:: pycon
>>> find = etree.XPath("//ns:a")
>>> find(root)
@@ -318,7 +350,9 @@
This works for the ``XPath`` class, however, the other evaluators (including
the ``xpath()`` method) are one-shot operations that do parsing and evaluation
-in one step. They therefore raise evaluation exceptions in all cases::
+in one step. They therefore raise evaluation exceptions in all cases:
+
+.. sourcecode:: pycon
>>> root = etree.Element("test")
>>> find = root.xpath("//*[1.1.1]")
@@ -345,7 +379,9 @@
====
lxml.etree introduces a new class, lxml.etree.XSLT. The class can be
-given an ElementTree object to construct an XSLT transformer::
+given an ElementTree object to construct an XSLT transformer:
+
+.. sourcecode:: pycon
>>> f = StringIO('''\
... <xsl:stylesheet version="1.0"
@@ -358,7 +394,9 @@
>>> transform = etree.XSLT(xslt_doc)
You can then run the transformation on an ElementTree document by simply
-calling it, and this results in another ElementTree object::
+calling it, and this results in another ElementTree object:
+
+.. sourcecode:: pycon
>>> f = StringIO('<a><b>Text</b></a>')
>>> doc = etree.parse(f)
@@ -379,7 +417,9 @@
-------------------
The result of an XSL transformation can be accessed like a normal ElementTree
-document::
+document:
+
+.. sourcecode:: pycon
>>> f = StringIO('<a><b>Text</b></a>')
>>> doc = etree.parse(f)
@@ -389,7 +429,9 @@
'Text'
but, as opposed to normal ElementTree objects, can also be turned into an (XML
-or text) string by applying the str() function::
+or text) string by applying the str() function:
+
+.. sourcecode:: pycon
>>> str(result)
'<?xml version="1.0"?>\n<foo>Text</foo>\n'
@@ -398,13 +440,17 @@
``xsl:output`` element in the stylesheet. If you want a Python unicode string
instead, you should set this encoding to ``UTF-8`` (unless the `ASCII` default
is sufficient). This allows you to call the builtin ``unicode()`` function on
-the result::
+the result:
+
+.. sourcecode:: pycon
>>> unicode(result)
u'<?xml version="1.0"?>\n<foo>Text</foo>\n'
You can use other encodings at the cost of multiple recoding. Encodings that
-are not supported by Python will result in an error::
+are not supported by Python will result in an error:
+
+.. sourcecode:: pycon
>>> xslt_tree = etree.XML('''\
... <xsl:stylesheet version="1.0"
@@ -419,7 +465,7 @@
>>> result = transform(doc)
>>> unicode(result)
Traceback (most recent call last):
- [...]
+ ...
LookupError: unknown encoding: UCS4
@@ -427,7 +473,9 @@
---------------------
It is possible to pass parameters, in the form of XPath expressions, to the
-XSLT template::
+XSLT template:
+
+.. sourcecode:: pycon
>>> xslt_tree = etree.XML('''\
... <xsl:stylesheet version="1.0"
@@ -441,13 +489,17 @@
>>> doc = etree.parse(f)
The parameters are passed as keyword parameters to the transform call. First
-let's try passing in a simple string expression::
+let's try passing in a simple string expression:
+
+.. sourcecode:: pycon
>>> result = transform(doc, a="'A'")
>>> str(result)
'<?xml version="1.0"?>\n<foo>A</foo>\n'
-Let's try a non-string XPath expression now::
+Let's try a non-string XPath expression now:
+
+.. sourcecode:: pycon
>>> result = transform(doc, a="/a/b/text()")
>>> str(result)
@@ -459,7 +511,9 @@
Just like `custom extension functions`_, lxml supports custom
extension *elements* in XSLT. This means, you can write XSLT code
-like this::
+like this:
+
+.. sourcecode:: xml
<xsl:templ