From: Barry Warsaw <barry@python.org>
Date: Wed, 22 Apr 2015 22:38:26 +0000 (-0400)
Subject: Issue #24029: Document the name binding behavior for submodule imports.
X-Git-Tag: v3.5.0b1~301
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b5a3d9bebb3c0019ef8464a6a0962e09b9b4b82d;p=thirdparty%2FPython%2Fcpython.git

Issue #24029: Document the name binding behavior for submodule imports.
---

b5a3d9bebb3c0019ef8464a6a0962e09b9b4b82d
diff --cc Doc/reference/import.rst
index dec5f8f14bca,7966bc513337..50e46884a2e2
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@@ -460,14 -459,43 +460,49 @@@ import machinery will create the new mo
  
      * If loading fails, the loader must remove any modules it has inserted
        into :data:`sys.modules`, but it must remove **only** the failing
 -      module, and only if the loader itself has loaded it explicitly.
 +      module(s), and only if the loader itself has loaded the module(s)
 +      explicitly.
 +
 +.. versionchanged:: 3.5
 +   A :exc:`DeprecationWarning` is raised when ``exec_module()`` is defined but
 +   ``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 --cc Misc/NEWS
index e50fe6484197,24b515f1b2d0..c295816b9a57
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@@ -12,52 -12,6 +12,57 @@@ Core and Builtin
  
  - Issue #24022: Fix tokenizer crash when processing undecodable source code.
  
 +Library
 +-------
 +
 +- Issue #17445: add difflib.diff_bytes() to support comparison of
 +  byte strings (fixes a regression from Python 2).
 +
 +- Issue #23917: Fall back to sequential compilation when ProcessPoolExecutor
 +  doesn't exist.  Patch by Claudiu Popa.
 +
 +- Issue #23008: Fixed resolving attributes with boolean value is False in pydoc.
 +
 +- Fix asyncio issue 235: LifoQueue and PriorityQueue's put didn't
 +  increment unfinished tasks (this bug was introduced when
 +  JoinableQueue was merged with Queue).
 +
 +- Issue #23908: os functions now reject paths with embedded null character
 +  on Windows instead of silently truncate them.
 +
 +- Issue #23728: binascii.crc_hqx() could return an integer outside of the range
 +  0-0xffff for empty data.
 +
 +- 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?
 +===================================
 +
 +Release date: 2015-04-19
 +
 +Core and Builtins
 +-----------------
 +
 +- Issue #22980: Under Linux, GNU/KFreeBSD and the Hurd, C extensions now include
 +  the architecture triplet in the extension name, to make it easy to test builds
 +  for different ABIs in the same working tree.  Under OS X, the extension name
 +  now includes PEP 3149-style information.
 +
 +- Issue #22631: Added Linux-specific socket constant CAN_RAW_FD_FRAMES.
 +  Patch courtesy of Joe Jevnik.
 +
 +- Issue #23731: Implement PEP 488: removal of .pyo files.
 +
 +- Issue #23726: Don't enable GC for user subclasses of non-GC types that
 +  don't add any new fields.  Patch by Eugene Toder.
 +
  - Issue #23309: Avoid a deadlock at shutdown if a daemon thread is aborted
    while it is holding a lock to a buffered I/O object, and the main thread
    tries to use the same I/O object (typically stdout or stderr).  A fatal