Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""A collection of modules for building different kinds of trees from HTML
2documents.
4To create a treebuilder for a new type of tree, you need to do
5implement several things:
71. A set of classes for various types of elements: Document, Doctype, Comment,
8 Element. These must implement the interface of ``base.treebuilders.Node``
9 (although comment nodes have a different signature for their constructor,
10 see ``treebuilders.etree.Comment``) Textual content may also be implemented
11 as another node type, or not, as your tree implementation requires.
132. A treebuilder object (called ``TreeBuilder`` by convention) that inherits
14 from ``treebuilders.base.TreeBuilder``. This has 4 required attributes:
16 * ``documentClass`` - the class to use for the bottommost node of a document
17 * ``elementClass`` - the class to use for HTML Elements
18 * ``commentClass`` - the class to use for comments
19 * ``doctypeClass`` - the class to use for doctypes
21 It also has one required method:
23 * ``getDocument`` - Returns the root node of the complete document tree
253. If you wish to run the unit tests, you must also create a ``testSerializer``
26 method on your treebuilder which accepts a node and returns a string
27 containing Node and its children serialized according to the format used in
28 the unittests
30"""
32from __future__ import absolute_import, division, unicode_literals
34from .._utils import default_etree
36treeBuilderCache = {}
39def getTreeBuilder(treeType, implementation=None, **kwargs):
40 """Get a TreeBuilder class for various types of trees with built-in support
42 :arg treeType: the name of the tree type required (case-insensitive). Supported
43 values are:
45 * "dom" - A generic builder for DOM implementations, defaulting to a
46 xml.dom.minidom based implementation.
47 * "etree" - A generic builder for tree implementations exposing an
48 ElementTree-like interface, defaulting to xml.etree.cElementTree if
49 available and xml.etree.ElementTree if not.
50 * "lxml" - A etree-based builder for lxml.etree, handling limitations
51 of lxml's implementation.
53 :arg implementation: (Currently applies to the "etree" and "dom" tree
54 types). A module implementing the tree type e.g. xml.etree.ElementTree
55 or xml.etree.cElementTree.
57 :arg kwargs: Any additional options to pass to the TreeBuilder when
58 creating it.
60 Example:
62 >>> from html5lib.treebuilders import getTreeBuilder
63 >>> builder = getTreeBuilder('etree')
65 """
67 treeType = treeType.lower()
68 if treeType not in treeBuilderCache:
69 if treeType == "dom":
70 from . import dom
71 # Come up with a sane default (pref. from the stdlib)
72 if implementation is None:
73 from xml.dom import minidom
74 implementation = minidom
75 # NEVER cache here, caching is done in the dom submodule
76 return dom.getDomModule(implementation, **kwargs).TreeBuilder
77 elif treeType == "lxml":
78 from . import etree_lxml
79 treeBuilderCache[treeType] = etree_lxml.TreeBuilder
80 elif treeType == "etree":
81 from . import etree
82 if implementation is None:
83 implementation = default_etree
84 # NEVER cache here, caching is done in the etree submodule
85 return etree.getETreeModule(implementation, **kwargs).TreeBuilder
86 else:
87 raise ValueError("""Unrecognised treebuilder "%s" """ % treeType)
88 return treeBuilderCache.get(treeType)