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)