Merge #15230 doc updates from 3.2

Doc/library/runpy.rst

@@ -14,6 +14,15 @@ importing them first. Its main use is to implement the :option:`-m` command
 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 @@ The :mod:`runpy` module provides two functions:
       PEP written and implemented by Nick Coghlan.
 
    :ref:`using-on-general` - CPython command line details
+
+   The :func:`importlib.import_module` function

Misc/NEWS

@@ -122,6 +122,9 @@ Tools/Demos
 Documentation
 -------------
 
+- Issue #15230: Clearly document some of the limitations of the runpy
+  module and nudge readers towards importlib when appropriate.
+
 - Issue #15053: Copy Python 3.3 import lock change notice to all relevant
   functions in imp instead of just at the top of the relevant section.
 
@@ -1184,12 +1187,12 @@ Build
   Based on patch from Hervé Coatanhay.
 
 - Issue #14321: Do not run pgen during the build if files are up to date.
+
 Documentation
 -------------
 
 - Issue #14034: added the argparse tutorial.
 
-
 - Issue #14324: Fix configure tests for cross builds.
 
 - Issue #14327: Call AC_CANONICAL_HOST in configure.ac and check in