[Twisted-Python] Refactoring Documentation

[Glyph Lefkowitz]

On Jan 20, 2011, at 7:43 PM, Kevin Horn wrote:

> It could even use Lore's parser, twisted.lore.tree.parseFileAndReport ;)
> 
> Jean-Paul
> 
>  
> Yes, but:
> 
> - The docs (well, docstrings) aren't very clear about exactly what that does, or what quirks it might or might not have. 

The source is pretty short, and has some very useful comments:

<http://twistedmatrix.com/trac/browser/trunk/twisted/lore/tree.py#L1021>

It is a thin wrapper around xml.sax.make_parser().parse() which uses a fixed set of DTDs, never downloads them, and remembers the file name and line number of errors so that the exceptions are actually useful to someone editing the XML.

> - Is the DOM document it returns a typical XHTML DOM document?  Is there anything special/different about it since it's a Lore XHTML doc?

Yep, it's plain vanilla XML objects.

> - Consider the number of tickets open involving Lore's parser (or at least there were several when I started this whole business).

This isn't the soupy mess of Lore's tag munging. It's just the thing it uses to get the DOM loaded in the first place.

> - The whole point of this project is to stop using (and by extension supporting/maintaining) Lore, so it seems kind of backwards to me to depend on it.

parseFileAndReport is actually useful enough that I'd like to see it move somewhere else - maybe somewhere in twisted.python, because this is useful knowledge.

> - I'd rather deal with an etree-a-like, than a straight DOM document (admittedly, personal preference)

Isn't there a function to do the conversion somewhere?

> - I certainly don't want to rewrite everything at this point ;)


If you can't use this function, the methods that it calls should be simple enough that you can just crib them :).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110121/cb9bf5e2/attachment.html>