Thank you for the patch. I can now imagine using the module. Comments:

"+   :synopsis: Iterative XML parsing with DOM nodes."
seem a bit too terse and confusing. Would

"+   :synopsis: Iterative parsing of XML to event, DOM node pairs, with option subtree creation."

be accurate?

-.. class:: PullDOM(documentFactory=None)
-   :class:`xml.sax.handler.ContentHandler` implementation that ...

I was expecting this to be filled out with the methods of PullDOM. But you new docstring
"+    """A ContentHandler that is used internally by :class:`DOMEventStream` to
+    provide an iterator over the nodes in an XML stream. This class would not
+    normally be used directly - its main responsibility is to produce DOM
+    nodes from SAX events."

suggests that it is sufficiently private that it should not be documented at all, and that anyone who wanted to use it directly should either try help(pullDom) or read the code. Correct?

I am not sure of the standard for when to document or not helper classes, so I will leave this question to a doc person.

"\ No newline at end of file"
Is this a message from diff to add one?
--------------

The py3k branch is now trunk. Most applicable patches should be developed on that branch and then possibly backported. The current pullDOM page is useless, so this should be backported. Since the docs appear to have been untouched since the beginning, the manual page, at least, should apply directly.

To go into 2.6.6, the final 2.6 bugfix release, a patch needs be applied by the end of July. So consider my first and third comments first and a possible minor update. I would recommend that for commit/review for at least 2.6.