Title: 19.6 xml.dom.pulldom doc: stub?
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
Status: closed Resolution: out of date
Dependencies: Superseder: The docs of xml.dom.pulldom are almost nonexistent
View: 14202
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl, loewis, mark.smith, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2010-01-05 00:34 by terry.reedy, last changed 2012-03-26 18:54 by eli.bendersky. This issue is now closed.

File name Uploaded Description Edit
7635_2.patch mark.smith, 2010-07-25 09:04 Replacement patch for these docs review
Messages (8)
msg97240 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-01-05 00:34
The short doc for 19.6. xml.dom.pulldom has lots of ...s that appear to indicate missing text. If so, this issue is a flag for a future project for someone who knows what to fill in.

If nothing is missing and the section is intended to be understood in its cryptic state, it should say so.
msg97390 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-01-08 00:08
The xml.dom.pulldom module doesn't have docstrings so I guess that when the doc page has been created only the names of the classes/method have been listed.
msg111459 - (view) Author: Mark Smith (mark.smith) * Date: 2010-07-24 11:39
I have a patch that provides full documentation for pulldom, and adds sensible docstrings to the pulldom module. I have unfortunately created the patch on the py3k branch -- please let me know what I should do regarding porting these changes to Python 2.7.
msg111473 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-07-24 12:55
Working off py3k is the thing to do. If the patch is trivial to apply to the other branches, the committer will probably use svnmerge to do it, else it may be useful to adapt your patch to 2.7. I’d recommend waiting for feedback before doing this.
msg111507 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-24 22:02
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.
msg111528 - (view) Author: Mark Smith (mark.smith) * Date: 2010-07-25 09:04
Terry, thanks for the feedback!

I have added a patch, replacing the previous one, which deals with your points 1 and 3 in the following ways:

1. I have used (an edited form of) your synopsis - I've removed the details of exactly what is returned from the iterator, as I thought it made the sentence structure slightly awkward - hope you don't mind. I've moved the old synopsis to the heading, which is where I intended it to be anyway.

3. I added the newline - I don't think this is really a problem, but neither is the fix :)

Regarding point 2: I agree with you - I struggled with whether to include references to these classes, eventually settling for what you see. I suppose they could be re-used for converting SAX events to DOM nodes, so it could be useful to know they are there.

SAX2DOM isn't even used internally, so is technically part of the module's public interface, but with such brittle behaviour that I think it should really be removed. It automatically adds children to their parent when they are parsed -- but the children will only be parsed if the buffer is large enough. If it isn't then you can get incorrectly empty or even partial subtrees.
msg156839 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-03-26 17:43
Looks like someone else noticed the problem, but did not notice that there was an existing issue with a patch :(.

Sorry about that, Mark.  Thanks very much for working on this, and I'm very sorry it got lost.  Hopefully Eli will review your patch and see if there is anything to adopt from it to add to the stuff he already checked in on issue 14202.
msg156855 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-26 18:54
Yes, sorry for missing this. I've placed a note in issue #14202 to review this. Mark, it would be great if you could prepare a fresh patch vs. 3.3 default with your additions. Let's continue discussion in #14202 - it's still open.
Date User Action Args
2012-03-26 18:54:05eli.benderskysetmessages: + msg156855
2012-03-26 17:43:18r.david.murraysetstatus: open -> closed

superseder: The docs of xml.dom.pulldom are almost nonexistent

nosy: + r.david.murray, eli.bendersky
messages: + msg156839
resolution: out of date
stage: patch review -> resolved
2010-07-25 09:06:26mark.smithsetfiles: - 7635.patch
2010-07-25 09:05:03mark.smithsetfiles: + 7635_2.patch

messages: + msg111528
2010-07-24 22:02:56terry.reedysettype: behavior
messages: + msg111507
stage: patch review
2010-07-24 12:55:28eric.araujosetassignee: georg.brandl -> docs@python

messages: + msg111473
nosy: + eric.araujo, docs@python
2010-07-24 11:39:48mark.smithsetfiles: + 7635.patch

nosy: + mark.smith
messages: + msg111459

keywords: + patch
2010-01-08 00:08:14ezio.melottisetpriority: normal
versions: + Python 2.6, Python 2.7
nosy: + loewis, ezio.melotti

messages: + msg97390
2010-01-05 00:34:06terry.reedycreate