Move DOMlite to simpletree and add some more treebuilder documentation

jgraham · jgraham · commit baf166bfe942 · 2007-01-02T22:28:37.000Z
--HG--
rename : src/treebuilders/DOMlite.py =&gt; src/treebuilders/simpletree.py
extra : convert_revision : svn%3Aacbfec75-9323-0410-a652-858a13e371e0/trunk%40403
diff --git a/parse.py b/parse.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 """usage: %prog [options] filename
 
-Parse a document to a DOMlite tree, with optional profiling
+Parse a document to a simpletree tree, with optional profiling
 """
 
 import sys
@@ -40,10 +40,10 @@ def parse():
             print "Treebuilder %s not found"%opts.treebuilder 
             raise
         except:
-            treebuilder = treebuilders.DOMlite.TreeBuilder
+            treebuilder = treebuilders.simpletree.TreeBuilder
     else:
-        import treebuilders.DOMlite
-        treebuilder = treebuilders.DOMlite
+        import treebuilders.simpletree
+        treebuilder = treebuilders.simpletree
 
     p = parser.HTMLParser(tree=treebuilder)
 
diff --git a/src/treebuilders/__init__.py b/src/treebuilders/__init__.py
@@ -1 +1,31 @@
-# This file is intentionally left blank
+"""A collection of modules for building different kinds of tree from
+HTML documents.
+
+To create a treebuilder for a new type of tree, you need to do
+implement several things:
+
+1) A set of classes for various types of elements: Document, Doctype,
+Comment, Element. These must implement the interface of
+_base.treebuilders.Node (although comment nodes have a different
+signature for their constructor, see treebuilders.simpletree.Comment)
+Textual content may also be implemented as another node type, or not, as
+your tree implementation requires.
+
+2) A treebuilder object (called TreeBuilder by convention) that
+inherits from treebuilders._base.TreeBuilder. This has 4 required attributes:
+documentClass - the class to use for the bottommost node of a document
+elementClass - the class to use for HTML Elements
+commentClass - the class to use for comments
+doctypeClass - the class to use for doctypes
+It also has one required method:
+getDocument - Returns the root node of the complete document tree
+
+3) If you wish to run the unit tests, you must also create a
+testSerializer method on your treebuilder which accepts a node and
+returns a string containing Node and its children serialized according
+to the format used in the unittests
+
+The supplied simpletree module provides a python-only implementation
+of a full treebuilder and is a useful reference for the semantics of
+the various methods.
+"""
diff --git a/src/treebuilders/_base.py b/src/treebuilders/_base.py
@@ -20,8 +20,84 @@
 #XXX - TODO; make the default interface more ElementTree-like
 #            rather than DOM-like
 
+class Node(object):
+    def __init__(self, name):
+        """Node representing an item in the tree.
+        name - The tag name associated with the node
+        parent - The parent of the current node (or None for the root node)
+        value - The value of the current node (applies to text nodes and 
+        comments
+        attributes - a dict holding name, value pairs for attributes of the node
+        childNodes - a list of child nodes of the current node. This must 
+        include all elements but not necessarily other node types
+        _flags - A list of miscellaneous flags that can be set on the node
+        """
+        self.name = name
+        self.parent = None
+        self.value = None
+        self.attributes = {}
+        self.childNodes = []
+        self._flags = []
+
+    def __str__(self):
+        attributesStr =  " ".join(["%s=\"%s\""%(name, value) 
+                                   for name, value in 
+                                   self.attributes.iteritems()])
+        if attributesStr:
+            return "<%s %s>"%(self.name,attributesStr)
+        else:
+            return "<%s>"%(self.name)
+
+    def __repr__(self):
+        return "<%s %s>" % (self.__class__, self.name)
+
+    def appendChild(self, node):
+        """Insert node as a child of the current node"""
+        raise NotImplementedError
+
+    def insertText(self, data, insertBefore=None):
+        """Insert data as text in the current node, positioned before the 
+        start of node insertBefore or to the end of the node's text.
+        """
+        raise NotImplementedError
+
+    def insertBefore(self, node, refNode):
+        """Insert node as a child of the current node, before refNode in the 
+        list of child nodes. Raises ValueError if refNode is not a child of 
+        the current node"""
+        raise NotImplementedError
+
+    def removeChild(self, node):
+        """Remove node from the children of the current node"""
+        raise NotImplementedError
+
+    def reparentChildren(self, newParent):
+        """Move all the children of the current node to newParent. 
+        This is needed so that trees that don't store text as nodes move the 
+        text in the correct way"""
+        #XXX - should this method be made more general?
+        for child in self.childNodes:
+            newParent.appendChild(child)
+        self.childNodes = []
+
+    def cloneNode(self):
+        """Return a shallow copy of the current node i.e. a node with the same
+        name and attributes but with no parent or child nodes"""
+        raise NotImplementedError
+
+
+    def hasContent(self):
+        """Return true if the node has children or text, false otherwise
+        """
+        raise NotImplementedError
+
 class TreeBuilder(object):
-    """Base treebuilder implementation"""
+    """Base treebuilder implementation
+    documentClass - the class to use for the bottommost node of a document
+    elementClass - the class to use for HTML Elements
+    commentClass - the class to use for comments
+    doctypeClass - the class to use for doctypes
+    """
 
     #Document class
     documentClass = None
@@ -231,15 +307,11 @@ def generateImpliedEndTags(self, exclude=None):
             # self.processEndTag(name)
             self.generateImpliedEndTags(exclude)
 
-    def reparentChildren(self, oldParent, newParent):
-        """Move all the children of oldParent to newParent. This is needed do 
-        that trees that don't store text as nodes move the text in the correct 
-        way"""
-        #XXX - should this method be made more general?
-        for child in oldParent.childNodes:
-            newParent.appendChild(child)
-        oldParent.childNodes = []
-
     def getDocument(self):
         "Return the final tree"
         return self.document
+
+    def testSerializer(self, node):
+        """Serialize the subtree of node in the format required by unit tests
+        node - the node from which to start serializing"""
+        raise NotImplementedError
diff --git a/src/treebuilders/simpletree.py b/src/treebuilders/simpletree.py
diff --git a/tests/test_parser.py b/tests/test_parser.py
@@ -12,9 +12,9 @@
 import parser
 #Run tests over all treebuilders
 #XXX - it would be nice to automate finding all treebuilders or to allow running just one
-from treebuilders import DOMlite, etree
+from treebuilders import simpletree, etree
 
-treetypes = {"DOMlite":DOMlite.TreeBuilder, 
+treetypes = {"simpletree":simpletree.TreeBuilder, 
              "ElementTree":etree.TreeBuilder}
 
 def parseTestcase(testString):
