On Jul 29, 2012 2:09 AM, "Nick Coghlan" <report@bugs.python.org> wrote:
>
>
> Nick Coghlan added the comment:
>
> 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.
>

Just so this doesn't get lost and in case it is important enough to block
on: it might be worth having separate ABCs for meta path finders and the
finders pathfinder uses since they have different APIs now (if one ignores
find_module for pathfinder finders). Just need to come up with names.

-brett

> 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__)
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue15295>
> _______________________________________