Thanks for getting started with such a detailed review on this Graham. We've known the documentation in this area has been flawed for a long time, but actually *fixing* seemed like such a big task that it has tended to get pushed to the bottom of our respective to-do lists.

And so as things have been tweaked, the already flawed documentation has fallen even further out of date (as it wasn't always clear where updates should be included).

Simply breaking it down into a smaller list of easier to tackle problems is a big step towards getting something done about it.

A couple of specific notes:

__all__ only affects import *, and may also affect documentation tools (e.g. pydoc will respect __all__ when deciding what to display). It has no effect on attribute retrieval from modules.

pkgutil.extend_path() is used to modify pkg.__path__ attributes, *not* sys.path. It is used to allow a single package to span multiple directories, forming the basis for "namespace packages" (see http://www.python.org/dev/peps/pep-0382/#namespace-packages-today). 

Packages are technically a kind of module, but we're somewhat inconsistent in our use of the term "module". Sometimes it means all kinds of modules (frozen, builtin, extension, package, compiled, source), sometimes it means anything-but-a-package and occasionally it specifically means pure Python modules. In theory, context should make it clear which interpretation is intended. In practice, the boundaries between the first two meanings get a little blurry.