Emphasize that people should not override __import__.

With importlib getting used more and more, changing __import__ will
not work as well as people used to hope as it will potentially bypass
importers, etc. It also will not work with importlib.import_module()
as it uses "importlib.__import__" (i.e. importlib's implementation of
import) directly and not builtins.__import__.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index b94c434118aad1b5ff0a2abbadbd45b8d7af23b2..c3fff311650ca392ce8914edba21dc2a685f57b4 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1451,10 +1451,11 @@ are always available.  They are listed here in alphabetical order.
    This function is invoked by the :keyword:`import` statement.  It can be
    replaced (by importing the :mod:`builtins` module and assigning to
    ``builtins.__import__``) in order to change semantics of the
-   :keyword:`import` statement, but nowadays it is usually simpler to use import
-   hooks (see :pep:`302`) to attain the same goals.  Direct use of
-   :func:`__import__` is entirely discouraged in favor of
-   :func:`importlib.import_module`.
+   :keyword:`import` statement, but doing so is **strongly** discouraged as it
+   is usually simpler to use import hooks (see :pep:`302`) to attain the same
+   goals and does not cause issues with code which assumes the default import
+   implementation is in use.  Direct use of :func:`__import__` is also
+   discouraged in favor of :func:`importlib.import_module`.
 
    The function imports the module *name*, potentially using the given *globals*
    and *locals* to determine how to interpret the name in a package context.