[Python-Dev] Pydoc Improvements (original) (raw)

Robert Kern robert.kern at gmail.com
Sat Jan 6 09:41:04 CET 2007

Phillip J. Eby wrote:

At 12:16 AM 1/6/2007 -0500, Barry Warsaw wrote:

If you've already explained it, that's fine, but if not, could you outline what you have against epydoc? The last I tried to work with it, it had even more hardcoded typechecking than pydoc does, spread out over more of the code base. Also, over at OSAF, I've been repeatedly called upon to sort out some peculiarity in how it discovers things or how it handles types it doesn't recognize. My net impression has been that it's very brittle, even more so than pydoc. On the plus side, there are some very good ideas and a lot of good execution in there, but its extensibility has historically struck me as non-existent. To be fair, the last time I had to deal with any problems with it at OSAF was almost a year ago, if memory serves. I don't know if anything has improved in it since then.

FWIW, a 3.0a3 was released in August 2006, and according to the History, "Significant portions of epydoc were written for version 3.0." It seems a lot of that was to add parsing as a complementary means to extract documentation. I'm not particularly familiar with the introspection code of either 2.1 or 3.0a3, but a cursory examination shows that 3.0a3 has an introspecter registry that 2.1 doesn't:

In epydoc.docintrospecter:

def register_introspecter(applicability_test, introspecter, priority=10): """ Register an introspecter function. Introspecter functions take two arguments, a python value and a C{ValueDoc} object, and should add information about the given value to the the C{ValueDoc}. Usually, the first line of an inspecter function will specialize it to a sublass of C{ValueDoc}, using L{ValueDoc.specialize_to()}:

    >>> def typical_introspecter(value, value_doc):
    ...     value_doc.specialize_to(SomeSubclassOfValueDoc)
    ...     <add info to value_doc>

@param priority: The priority of this introspecter, which determines
the order in which introspecters are tried -- introspecters with lower
numbers are tried first.  The standard introspecters have priorities
ranging from 20 to 30.  The default priority (10) will place new
introspecters before standard introspecters.
"""

-- Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco

More information about the Python-Dev mailing list