[Python-bugs-list] [ python-Bugs-427060 ] pydoc: inconsistent behavior for imports

[noreply@sourceforge.net]

Bugs item #427060, was updated on 2001-05-24 13:34
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=427060&group_id=5470

Category: Python Library
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Bryan Nollett (nollett)
Assigned to: Nobody/Anonymous (nobody)
Summary: pydoc: inconsistent behavior for imports

Initial Comment:
Consider a module mymod.py containing the following two
import statements:

from md5 import new
from base64 import decode

Running "pydoc mymod" yields a helpfile containing a
description of function new from md5 but not function
decode from base64.  The distinction seems to be that
new is a built-in function while decode is a "plain"
function.  From a user's perspective however, this
seems to be very inconsistent.

>From a very brief glance at pydoc.py, this distinction
appears to be an intentional one, but it is not clear
to me why this behavior would be desirable, at least in
this (very typical?) example.

As a further example, consider mymod.py containing a
different import statement:

from Numeric import array, arange, resize, zeros

Some functions in Numeric are built-ins and others
"plain" functions. So here "pydoc mymod" would include
documentation for array and zeros (since they happen to
be implemented as built-ins) and not arange or resize.

I think pydoc follows a rule something like this:

imported classes -- not documented
imported functions -- documented only if built-in
imported "data" -- documented (with obvious exceptions)

Perhaps the default behavior should be that *none* of
the imported symbols be documented?  (If all are
documented, this makes pydoc much less usable with
Numeric or Tkinter where the "from Tkinter import *"
idiom is often a necessary evil.)  I can see cases
where one would like imported symbols to be documented
but do not see a mechanism currently in place to
distinguish between the two uses.

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=427060&group_id=5470