1.1 --- a/xmlread.py Fri Mar 30 00:26:13 2012 +0200
1.2 +++ b/xmlread.py Mon Apr 02 18:08:55 2012 +0200
1.3 @@ -1,5 +1,26 @@
1.4 #!/usr/bin/env python
1.5
1.6 +"""
1.7 +A SAX-based parser framework.
1.8 +
1.9 +Copyright (C) 2012 Paul Boddie <paul@boddie.org.uk>
1.10 +
1.11 +This program is free software; you can redistribute it and/or modify it under
1.12 +the terms of the GNU Lesser General Public License as published by the Free
1.13 +Software Foundation; either version 3 of the License, or (at your option) any
1.14 +later version.
1.15 +
1.16 +This program is distributed in the hope that it will be useful, but WITHOUT
1.17 +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 +FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
1.19 +details.
1.20 +
1.21 +You should have received a copy of the GNU Lesser General Public License along
1.22 +with this program. If not, see <http://www.gnu.org/licenses/>.
1.23 +"""
1.24 +
1.25 +__version__ = "0.1"
1.26 +
1.27 import xml.sax
1.28
1.29 class Parser(xml.sax.handler.ContentHandler):
1.30 @@ -26,9 +47,15 @@
1.31 self.text.pop()
1.32
1.33 def handleElement(self, name):
1.34 +
1.35 + "Handle a completed element having the given 'name'."
1.36 +
1.37 pass
1.38
1.39 def parse(self, f):
1.40 +
1.41 + "Parse content from the file object 'f' using reasonable defaults."
1.42 +
1.43 try:
1.44 parser = xml.sax.make_parser()
1.45 parser.setContentHandler(self)
1.46 @@ -53,6 +80,24 @@
1.47 self.handlers.update(handlers)
1.48
1.49 def handleElement(self, name):
1.50 +
1.51 + """
1.52 + Handle a completed element having the given 'name'. If a handler has
1.53 + been registered for the name on this object, the handler will be invoked
1.54 + with...
1.55 +
1.56 + * 'name' (the current element name)
1.57 + * the path to and including the current element (a list of names)
1.58 + * the attributes for elements in the path (a list of dictionaries, one
1.59 + for each element)
1.60 + * the text fragments for elements in the path (a list of lists, one
1.61 + list of fragments for each element)
1.62 + * the final textual content for the current element
1.63 +
1.64 + Where a handler has been registered for None, it will be called for any
1.65 + element without a specific handler.
1.66 + """
1.67 +
1.68 for n in (name, None):
1.69 handler = self.handlers.get(n)
1.70 if handler: