changeset:   95777:6295f207dfaa
parent:      95774:2e93da3d9f1e
parent:      95776:351ad8c4f3a6
user:        Barry Warsaw <barry@python.org>
date:        Wed Apr 22 18:38:26 2015 -0400
files:       Doc/reference/import.rst Misc/NEWS
description:
Issue #24029: Document the name binding behavior for submodule imports.


diff -r 2e93da3d9f1e -r 6295f207dfaa Doc/reference/import.rst
--- a/Doc/reference/import.rst	Wed Apr 22 23:55:29 2015 +0200
+++ b/Doc/reference/import.rst	Wed Apr 22 18:38:26 2015 -0400
@@ -468,6 +468,41 @@
    ``create_module()`` is not. Starting in Python 3.6 it will be an error to not
    define ``create_module()`` on a loader attached to a ModuleSpec.
 
+Submodules
+----------
+
+When a submodule is loaded using any mechanism (e.g. ``importlib`` APIs, the
+``import`` or ``import-from`` statements, or built-in ``__import__()``) a
+binding is placed in the parent module's namespace to the submodule object.
+For example, if package ``spam`` has a submodule ``foo``, after importing
+``spam.foo``, ``spam`` will have an attribute ``foo`` which is bound to the
+submodule.  Let's say you have the following directory structure::
+
+    spam/
+        __init__.py
+        foo.py
+        bar.py
+
+and ``spam/__init__.py`` has the following lines in it::
+
+    from .foo import Foo
+    from .bar import Bar
+
+then executing the following puts a name binding to ``foo`` and ``bar`` in the
+``spam`` module::
+
+    >>> import spam
+    >>> spam.foo
+    <module 'spam.foo' from '/tmp/imports/spam/foo.py'>
+    >>> spam.bar
+    <module 'spam.bar' from '/tmp/imports/spam/bar.py'>
+
+Given Python's familiar name binding rules this might seem surprising, but
+it's actually a fundamental feature of the import system.  The invariant
+holding is that if you have ``sys.modules['spam']`` and
+``sys.modules['spam.foo']`` (as you would after the above import), the latter
+must appear as the ``foo`` attribute of the former.
+
 Module spec
 -----------
 
diff -r 2e93da3d9f1e -r 6295f207dfaa Misc/NEWS
--- a/Misc/NEWS	Wed Apr 22 23:55:29 2015 +0200
+++ b/Misc/NEWS	Wed Apr 22 18:38:26 2015 -0400
@@ -36,6 +36,11 @@
 - Issue #23887: urllib.error.HTTPError now has a proper repr() representation. 
   Patch by Berker Peksag.
 
+Documentation
+-------------
+
+- Issue #24029: Document the name binding behavior for submodule imports.
+
 
 What's New in Python 3.5.0 alpha 4?
 ===================================