[Python-checkins] cpython (3.2): Issue #15230: Update runpy docs to clarify a couple of points that came up in

[nick.coghlan]

http://hg.python.org/cpython/rev/4880aac5c665
changeset:   78096:4880aac5c665
branch:      3.2
parent:      78094:3b05cf877124
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Jul 15 00:36:39 2012 +1000
summary:
  Issue #15230: Update runpy docs to clarify a couple of points that came up in this issue

files:
  Doc/library/runpy.rst |  11 +++++++++++
  Misc/NEWS             |   3 +++
  2 files changed, 14 insertions(+), 0 deletions(-)


diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -14,6 +14,15 @@
 line switch that allows scripts to be located using the Python module
 namespace rather than the filesystem.
 
+Note that this is *not* a sandbox module - all code is executed in the
+current process, and any side effects (such as cached imports of other
+modules) will remain in place after the functions have returned.
+
+Furthermore, any functions and classes defined by the executed code are not
+guaranteed to work correctly after a :mod:`runpy` function has returned.
+If that limitation is not acceptable for a given use case, :mod:`importlib`
+is likely to be a more suitable choice than this module.
+
 The :mod:`runpy` module provides two functions:
 
 
@@ -141,3 +150,5 @@
       PEP written and implemented by Nick Coghlan.
 
    :ref:`using-on-general` - CPython command line details
+
+   The :func:`importlib.import_module` function
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -384,6 +384,9 @@
 Documentation
 -------------
 
+- Issue #15230: Clearly document some of the limitations of the runpy
+  module and nudge readers towards importlib when appropriate.
+
 - Issue #13557: Clarify effect of giving two different namespaces to exec or
   execfile().
 

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