Documentation improvements and a reset method on the treebuiler so calling a single parser multiple times doesn't do funky things

jgraham · jgraham · commit 06aac662d451 · 2007-01-04T20:18:46.000Z
--HG--
extra : convert_revision : svn%3Aacbfec75-9323-0410-a652-858a13e371e0/trunk%40414
diff --git a/src/__init__.py b/src/__init__.py
@@ -1 +1,34 @@
+""" 
+HTML parsing library based on the WHATWG "HTML5"
+specification. The parser is designed to be compatible with existing
+HTML found in the wild and implements well-defined error recovery that
+is largely compatible with modern desktop web browsers.
+
+Example usage:
+
+import html5lib
+f = open("my_document.html")
+p = html5lib.HTMLParser()
+tree = p.parse(f)
+
+By default the returned treeformat is a custom "simpletree", similar
+to a DOM tree; each element has attributes childNodes and parent
+holding the parents and children respectively, a name attribute
+holding the Element name, a data attribute holding the element data
+(for text and comment nodes) and an attributes dictionary holding the
+element's attributes (for Element nodes).
+
+To get output in ElementTree format:
+
+import html5lib
+from html5lib.treebuilders import etree
+p = html5lib.HTMLParser(tree=etree.TreeBuilder)
+elementtree = p.parse(f)
+
+Note: Because HTML documents support various features not in the
+default ElementTree (e.g. doctypes), we suppy our own simple
+serializer; html5lib.treebuilders.etree.write At present this does not
+have the encoding support offered by the elementtree serializer.
+
+"""
 from parser import HTMLParser
diff --git a/src/parser.py b/src/parser.py
@@ -32,14 +32,17 @@
 from constants import headingElements, tableInsertModeElements
 
 class HTMLParser(object):
-    """Main parser class"""
+    """HTML parser. Generates a tree structure from a stream of (possibly
+        malformed) HTML"""
 
     def __init__(self, strict = False, tree=simpletree.TreeBuilder):
-        """HTML parser. Generates a tree structure from a stream of (possibly
-        malformed) HTML.  
+        """
         strict - raise an exception when a parse error is encountered 
+        
         tree - a treebuilder class controlling the type of tree that will be 
-        returned (default - html5lib.simpletree.TreeBuilder)"""
+        returned. This class is almost always a subclass of 
+        html5lib.treebuilders._base.TreeBuilder
+        """
 
         # Raise an exception on the first error encountered
         self.strict = strict
@@ -72,11 +75,15 @@ def __init__(self, strict = False, tree=simpletree.TreeBuilder):
         self.lastPhase = None
 
     def parse(self, stream, innerHTML=False):
-        """Stream should be a stream of unicode bytes. Character encoding
-        issues have not yet been dealt with."""
-
-        # XXX - need to ensure the tree is reset here
+        """Parse a HTML document into a well-formed tree
         
+        stream - a filelike object or string containing the HTML to be parsed
+        
+        innerHTML - Are we parsing in innerHTML mode (note innerHTML=True 
+        is not yet supported)
+        """
+
+        self.tree.reset()
 
         # We don't actually support innerHTML yet but this should allow
         # assertations
diff --git a/src/treebuilders/_base.py b/src/treebuilders/_base.py
@@ -112,6 +112,9 @@ class TreeBuilder(object):
     doctypeClass = None
 
     def __init__(self):
+        self.reset()
+    
+    def reset(self):
         self.openElements = []
         self.activeFormattingElements = []
 
