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

[noreply@sourceforge.net]

Bugs item #427060, was opened at 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: Pending
>Resolution: Later
Priority: 5
Submitted By: Bryan Nollett (nollett)
Assigned to: Ka-Ping Yee (ping)
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.

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

>Comment By: Ka-Ping Yee (ping)
Date: 2001-11-21 19:42

Message:
Logged In: YES 
user_id=45338

The intent of pydoc was, exactly as you suggest, not to
document any of the symbols imported from other modules.

The current implementation does the best that it can to do
so.  The origin of a class can be determined from its
__module__ attribute, but unfortunately data objects and
built-in functions do not identify the module they come
from, so there's no way to tell.

A cleverer pydoc might deduce the origin of a symbol from
the existence of an import statement in the code, but then i
was afraid heuristics might get too tangled for that to be
worth it.

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

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