[Python-Dev] Sneaky 'super' instances

[Guido van Rossum]

[Phillip Eby]
> So, what I want to know is:
> 
> * Do other people find pydoc inadequate?

That's way too strong.  It still does very well for the intended
purpose, which is to extracts docs out of typical library modules.  It
may do poorly on funny things like descriptors and metaclasses, but
esoterica is not its primary goal.

Of course, it's annoying when pydoc raises an exception -- it would be
much better if it simply showed that some info was missing.

In any case, in general I am in favor of a doc tool that scans source
code rather than doing introspection.  There are cases where this
isn't right (e.g. when asking for help about a given object) but when
the object or module isn't already loaded, I think it's wrong to
import the module just to be able to extract its docs.

> * Does it seem likely that PyProtocols would be considered as an addition 
> to the standard library (and by implication, used to document the 
> interfaces of "standard" Python objects)?

I have to admit that every time I try to read your docs, I glaze
over...  Assuming it's yet another way of doing interfaces, I'm wary
of adopting *any* kind of standard approach until I've had much more
time to think over all the issues.

> * Is there anything specific that anybody would want in an overhauled 
> pydoc, that I should know about?

Don't raise exceptions when confronted with objects that violate its
assumptions is my first issue.  A major refactoring to make the code
more understandable and more "obviously correct" would be the second.

--Guido van Rossum (home page: http://www.python.org/~guido/)