[Python-checkins] cpython (merge 3.4 -> 3.4): Issue #24029: Document the name binding behavior for submodule imports.

[barry.warsaw]

https://hg.python.org/cpython/rev/351ad8c4f3a6
changeset:   95776:351ad8c4f3a6
branch:      3.4
parent:      95773:09d5bbf0f01d
parent:      95775:3968e7a9614c
user:        Barry Warsaw <barry at python.org>
date:        Wed Apr 22 18:36:44 2015 -0400
summary:
  Issue #24029: Document the name binding behavior for submodule imports.

files:
  Doc/reference/import.rst |  35 ++++++++++++++++++++++++++++
  Misc/NEWS                |   5 ++++
  2 files changed, 40 insertions(+), 0 deletions(-)


diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -461,6 +461,41 @@
       into :data:`sys.modules`, but it must remove **only** the failing
       module, and only if the loader itself has loaded it explicitly.
 
+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 --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -220,6 +220,11 @@
 
 - Issue #23998: PyImport_ReInitLock() now checks for lock allocation error
 
+Documentation
+-------------
+
+- Issue #24029: Document the name binding behavior for submodule imports.
+
 
 What's New in Python 3.4.3?
 ===========================

-- 
Repository URL: https://hg.python.org/cpython