[Python-Dev] Sneaky 'super' instances

[Phillip J. Eby]

At 10:55 AM 6/11/03 -0400, Guido van Rossum wrote:
>[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.

Fair enough.


>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.

I agree with you; my goal is to have tools that can do either, but share a 
common framework.  Right now, the tools are split into mutually exclusive 
camps.


> > * 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...

Is there anything that you could suggest as to how I could improve 
that?  In our previous discussions regarding the subject matter, you said 
that I made things sound too magical and easy, and I needed to document 
various things such as the requirements for protocol objects.  So, I wrote 
the PyProtocols docs *very* specifically, in order to address your previous 
concern.  That is, to show the "non-magicalness" of it.  It sounds like 
perhaps I went too far to the other extreme.  :)

Anyway, it would be helpful if you (or anyone) could suggest ways to 
improve it.  As I said, I'm seeking feedback, and that definitely includes 
constructive criticism.


>   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.

I understand; you mentioned previously that you didn't want to take an 
approach that would exclude other approaches, so I made sure that 
PyProtocols interoperates "out of the box" with Twisted and Zope, to 
demonstrate that the approach doesn't require a single kind of 
interface.  The docs also include examples of extending the provided 
protocol types to do other things.

Thanks for the feedback and explaining your position.  Now I can make more 
appropriate decisions about where and when to put my efforts.