[ python-Bugs-1694833 ] Bad documentation for existing imp methods

[SourceForge.net]

Bugs item #1694833, was opened at 2007-04-05 10:11
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1694833&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.5
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Christoph Zwerschke (cito)
Assigned to: Nobody/Anonymous (nobody)
Summary: Bad documentation for existing imp methods

Initial Comment:
The documentation of find_module() and load_module() in the Standard Libary Reference (see http://docs.python.org/lib/module-imp.html) is incomplete/wrong.

Docu for find_module():
    
"Try to find the module "name" on the search path "path". ... If search is successful, the return value is a triple (file, pathname, description) where "file" is an open file ..."

First, the docu leaves it open whether it works only for ordinary modules or packages. It should be made clearer that it works for packages as well. In the last paragraph, the docu indirectly indicates that it works for packages, but this should be explained already in the first sentence.

Second, if "name" is a package, then "file" will not be an open file, but None, and pathname will be the path for the package (not None). The docu does not mention this case but claims that if file is None, then pathname will also be None which is wrong for a package.

Third, the docu switches arbitrarily between the "filename" and "pathname" though it always refers to the same object. This should be made consistent in the docu of find_module() itself, but also between find_module() and load_module(), since the latter takes the return values of the former as input.

Similarly, the documentation for load_modules() does not mention that it allows "file" to be None and "filename" to be the directory of a package.

Some code showing this behavior of find_module() and load_module() when they are used on a package:

from imp import find_module, load_module
package = 'imp'
args = find_module(package)
print args
print load_module(package, *args)


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

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