diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index dec5f8f14bc..50e46884a2e 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -468,6 +468,41 @@ import machinery will create the new module itself. ``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 + + >>> spam.bar + + +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 index e50fe648419..c295816b9a5 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -36,6 +36,11 @@ Library - 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? ===================================