This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author barry
Recipients barry, brett.cannon, eric.araujo, eric.snow, georg.brandl, larry, ncoghlan, skrah
Date 2012-07-31.15:22:58
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <20120731112259.45e61497@limelight.wooz.org>
In-reply-to <1343542183.14.0.0311024413828.issue15295@psf.upfronthosting.co.za>
Content
On Jul 29, 2012, at 06:09 AM, Nick Coghlan wrote:

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

I've put an XXX in the import.rst file for this, but I probably won't get to
adding all the cross references.  Others can take that on once this lands.

>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).

While I've added a mention of import_module() in several places, I don't think
the above detail is appropriate for the introduction.  I don't want to
overload folks with all those details before they understand the basics of
Python's import model.

I would much rather add a section that goes into more detail about coarsely
overriding the import system, and there we can discuss replacing built-in
__import__() along with its implications and caveats, including any behavior
changes in Python 3.3 with the adoption of importlib.  I probably won't get to
that so feel free to add such a section later.

>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

I don't like the term "initialized package" (even with the Americanized
spelling :), because the term "initialized" means "set to the value or put in
the condition appropriate to the start of an operation", which clearly refers
to both types of packages.

What about "concrete package"?  In a sense, namespace packages are virtual, so
the opposite of that would be concrete.  OTOH, while "regular package" may
still not be the right term, it might be good enough.  The bike shed is
already looking pretty tie-died.

>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).

This is getting somewhere.  I like using the term "path importer" for the
thing that PathFinder is.  ("path finder" doesn't quite do it for me, but
maybe I'm clouded by same term used as a car model. ;)

What we have are several default finders, one that knows how to locate frozen
modules, one that knows how to locate built-in modules, and one that knows how
to search an "import path" (which consists of "path entries").  This latter
finder is the "path importer" and it has further extensibility so that new
types of path entries can be used.  A path entry is a location to search for
modules, and sequences of path entries exist on import paths.  When a search
occurs, typically the import path is taken from sys.path, but for subpackages,
it is taken from the __path__ attribute of its parent package.

This seems to make for much better reading, and while I've worded it
differently to fit better in the flow of the documentation, it's terminology
that feels more right to me.  Thanks!
History
Date User Action Args
2012-07-31 15:23:00barrysetrecipients: + barry, brett.cannon, georg.brandl, ncoghlan, larry, eric.araujo, skrah, eric.snow
2012-07-31 15:22:59barrylinkissue15295 messages
2012-07-31 15:22:58barrycreate