Since __import__ is not designed for general use, have its docstring point

people towards importlib.import_module().

Closes issue #7397.

diff --git a/Misc/NEWS b/Misc/NEWS
index 4bfd534b01550383ab578199d7cfc15f968275d1..1ed5172a168257acc08d6693c65ddc506ee47d4b 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -10,6 +10,9 @@ What's New in Python 3.2 Alpha 3?
 Core and Builtins
 -----------------
 
+- Issue #7397: Mention that importlib.import_module() is probably what someone
+  really wants to be using in __import__'s docstring.
+
 - Issue #8521: Allow CreateKeyEx, OpenKeyEx, and DeleteKeyEx functions
   of winreg to use named arguments.
 

diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index 60bceb758165dae3e85ba419837ab425091565d7..2e8d6e21b3fbb389127667962a90ab03058ce1ac 100644 (file)
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -173,8 +173,12 @@ builtin___import__(PyObject *self, PyObject *args, PyObject *kwds)
 PyDoc_STRVAR(import_doc,
 "__import__(name, globals={}, locals={}, fromlist=[], level=-1) -> module\n\
 \n\
-Import a module.  The globals are only used to determine the context;\n\
-they are not modified.  The locals are currently unused.  The fromlist\n\
+Import a module. Because this function is meant for use by the Python\n\
+interpreter and not for general use it is better to use\n\
+importlib.import_module() to programmatically import a module.\n\
+\n\
+The globals argument is only used to determine the context;\n\
+they are not modified.  The locals argument is unused.  The fromlist\n\
 should be a list of names to emulate ``from name import ...'', or an\n\
 empty list to emulate ``import name''.\n\
 When importing a module from a package, note that __import__('A.B', ...)\n\