As described here:http://news.gmane.org/find-root.php?message_id=20150422115959.1ff2ee58%40limelight.wooz.orgImporting a submodule binds the submodule's name in the parent module's namespace.  This is surprising, but it seems intentional and it's relied upon by existing code, e.g. asyncio/__init__.py in the stdlib.It's also not documented afaict.  It should be documented in the Language Reference's section on the import system.  After a little more discussion on import-sig, I plan on doing that.

From Guido:It's definitely intentional, and it's fundamental to the package importdesign. We've had many implementations of package import (remember "ni.py"?last seen as "knee.py") and it was always there, because this is done aspart of *submodule loading*. For better or for worse (and because I didn'tknow Java at the time :-) Python declares that if you write `importfoo.bar` then later in your code you can use `foo.bar` to reference to thebar submodule of package foo. And the way this is done is to make eachsubmodule an attribute of its parent package. This is done when thesubmodule is first loaded, and because of the strict separation betweenloading and importing, it is done no matter what form of import was used toload bar.I guess another thing to realize is that the globals of __init__.py arealso the attribute namespace of the package.I'm not surprised it's in the reference manual -- that hasn't been updatedthoroughly in ages, and I sometimes cry when I see it. :-) So please doclarify this for the benefit of future implementers.

More rationale from the thread:> The surprising part is that it also happens for explicit relative> imports.  I'm guessing that part was unintentional and simply not> noticed whenPEP 328 was implemented.>  No, that must also have been intentional, because even when you userelative import, the module you imported knows its full name, and that fullname is used as its key in sys.modules. If someone else uses absoluteimport for the same module they should still get the same module object.

Guido describes the global invariant for *all* the forms of importing a submodule, including explicit relative imports:> I just mean that for relative import> there is no need to bind the submodule to the parent, is there?But there *is* a reason. The submodule must still be an attribute of the parent package, because of the invariant that if you have sys.modules['foo'] and sys.modules['foo.bar'], the latter must appear as the 'bar' attribute of the former. This is an invariant of module loading, and (I feel I'm repeating myself) the form of import used does not affect loading.

Here's some new text for the Language Reference.

LGTM.  You've covered all the key points and the example is good.

Cool, thanks!  I'll commit it and we can always clean it up/add to it later if needed.

New changeset3968e7a9614c by Barry Warsaw in branch '3.4':Issue#24029: Document the name binding behavior for submodule imports.https://hg.python.org/cpython/rev/3968e7a9614cNew changeset351ad8c4f3a6 by Barry Warsaw in branch '3.4':Issue#24029: Document the name binding behavior for submodule imports.https://hg.python.org/cpython/rev/351ad8c4f3a6New changeset6295f207dfaa by Barry Warsaw in branch 'default':Issue#24029: Document the name binding behavior for submodule imports.https://hg.python.org/cpython/rev/6295f207dfaa