1"""A collection of modules for building different kinds of tree from
2HTML documents.
3
4To create a treebuilder for a new type of tree, you need to do
5implement several things:
6
71) A set of classes for various types of elements: Document, Doctype,
8Comment, Element. These must implement the interface of
9_base.treebuilders.Node (although comment nodes have a different
10signature for their constructor, see treebuilders.etree.Comment)
11Textual content may also be implemented as another node type, or not, as
12your tree implementation requires.
13
142) A treebuilder object (called TreeBuilder by convention) that
15inherits from treebuilders._base.TreeBuilder. This has 4 required attributes:
16documentClass - the class to use for the bottommost node of a document
17elementClass - the class to use for HTML Elements
18commentClass - the class to use for comments
19doctypeClass - the class to use for doctypes
20It also has one required method:
21getDocument - Returns the root node of the complete document tree
22
233) If you wish to run the unit tests, you must also create a
24testSerializer method on your treebuilder which accepts a node and
25returns a string containing Node and its children serialized according
26to the format used in the unittests
27"""
28
29from __future__ import absolute_import, division, unicode_literals
30
31from ..utils import default_etree
32
33treeBuilderCache = {}
34
35
36def getTreeBuilder(treeType, implementation=None, **kwargs):
37    """Get a TreeBuilder class for various types of tree with built-in support
38
39    treeType - the name of the tree type required (case-insensitive). Supported
40               values are:
41
42               "dom" - A generic builder for DOM implementations, defaulting to
43                       a xml.dom.minidom based implementation.
44               "etree" - A generic builder for tree implementations exposing an
45                         ElementTree-like interface, defaulting to
46                         xml.etree.cElementTree if available and
47                         xml.etree.ElementTree if not.
48               "lxml" - A etree-based builder for lxml.etree, handling
49                        limitations of lxml's implementation.
50
51    implementation - (Currently applies to the "etree" and "dom" tree types). A
52                      module implementing the tree type e.g.
53                      xml.etree.ElementTree or xml.etree.cElementTree."""
54
55    treeType = treeType.lower()
56    if treeType not in treeBuilderCache:
57        if treeType == "dom":
58            from . import dom
59            # Come up with a sane default (pref. from the stdlib)
60            if implementation is None:
61                from xml.dom import minidom
62                implementation = minidom
63            # NEVER cache here, caching is done in the dom submodule
64            return dom.getDomModule(implementation, **kwargs).TreeBuilder
65        elif treeType == "lxml":
66            from . import etree_lxml
67            treeBuilderCache[treeType] = etree_lxml.TreeBuilder
68        elif treeType == "etree":
69            from . import etree
70            if implementation is None:
71                implementation = default_etree
72            # NEVER cache here, caching is done in the etree submodule
73            return etree.getETreeModule(implementation, **kwargs).TreeBuilder
74        else:
75            raise ValueError("""Unrecognised treebuilder "%s" """ % treeType)
76    return treeBuilderCache.get(treeType)
77