General comment:

runpy, pkgutil, et al should all get "See Also" links at the top pointing to the new import system section.

Import system intro:

As noted above, I suggest changing the name :)

Opening section should refer to importlib.import_module(). Any mentions of __import__ should point out that its API is designed for the convenience of the interpreter, and thus it's a pain to use directly. However, we should also document explicitly that, unlike the import statement and calling __import__ directly, importlib.import_module will ignore any module level replacements of __import__.

Replacing builtins.__import__ won't reliably override the entire import system (due to module level __import__ definitions, most notably importlib.__import__) and other tools that work with the process global import state directly (e.g. pkgutil, runpy).

5.1 Packages:

Don't tease readers, just tell them: the defining characteristic of a package is that it is a module object with a __path__ attribute.

Since we have the privilege of defining *the* standard terminology for old-style packages, I suggest we use the term "initialised" packages (since having an __init__.py is what makes them special). We should also note explicitly that an initialised package can also behave as a namespace package, by setting __path__ appropriately in __init__.py

Also, I suggest adding a 5.1.3 Package Example subheading - currently you define an initialised package under the namespace package heading

Finally, I think this section needs to explicitly define the terms *import path* and *path entry*. The meta path docs later refer to find_module() accepting a module name and path, and the reader could be forgiven for thinking that meant a filesystem path, when it is actually an import path (which is a sequence of path entries, which may themselves by filesystem paths).

5.2.2 Finders and loaders:

The term "sys path finder" is incorrect as registered path hooks are invoked for both sys.path entries *and* package __path__ entries. I suggest "path entry finder". (I agree a longer name is needed to better distinguish them from metapath finders)

5.2.3 Import hooks:

While it does get cleared up in 5.2.4, this section could be clearer that the hooks *cannot* override the initial check of the module cache.

5.3.4 Metapath:

See above comment about clarifying that an import path is passed to find_module() rather than a filesystem path.

The description of the path importer is incorrect. It only knows how to scan an import path and interrogate the path hooks. It's the individual path entry finders that know how to do things like load modules from the filesystem or zip files.


5.2.5 Meta path loaders

I don't like the title here. There's no such thing as a meta path loader. there are only module loaders. Once they're created, it doesn't matter how you found them.

Clarify that the loader only has to remove the modules it inserted itself. Other modules that were loaded *successfully* as a side effect of the code execution will remain in the cache.

5.3 The Path Importer

As noted above, the path importer is *NOT* restricted to filesystem imports. All it cares about is arbitrary text sequences and path hooks. With the right path hook, you could use URLs or database connection strings as path entries.

5.5 References

I'd also point to PEP 328 (absolute imports by default and explicit relative import syntax) and PEP 338 (using the import system to find __main__)