Closes #9254: backport __import__ docstring/doc mentions of importlib.
Patch by Éric Araujo.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index a324e51..dc8ee9a 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1558,7 +1558,7 @@
.. note::
This is an advanced function that is not needed in everyday Python
- programming.
+ programming, unlike :func:`importlib.import_module`.
This function is invoked by the :keyword:`import` statement. It can be
replaced (by importing the :mod:`__builtin__` module and assigning to
@@ -1609,15 +1609,8 @@
names.
If you simply want to import a module (potentially within a package) by name,
- you can call :func:`__import__` and then look it up in :data:`sys.modules`::
+ use :func:`importlib.import_module`.
- >>> import sys
- >>> name = 'foo.bar.baz'
- >>> __import__(name)
- <module 'foo' from ...>
- >>> baz = sys.modules[name]
- >>> baz
- <module 'foo.bar.baz' from ...>
.. versionchanged:: 2.5
The level parameter was added.
diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index 373f870..3def080 100644
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -53,8 +53,12 @@
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\