From 2a082add9d26f280a889fb5043910bf56df84a6a Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sat, 14 Apr 2012 21:58:33 -0400 Subject: [PATCH] Clarify that one should not use __import__() directly. Also mention PEP 328 in explaining how 'index' works. --- Doc/library/functions.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 2674ef9050c..9287bfb656b 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1447,8 +1447,9 @@ are always available. They are listed here in alphabetical order. 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`). Direct use of :func:`__import__` is rare, except in - cases where you want to import a module whose name is only known at runtime. + hooks (see :pep:`302`) to attain the same goals. Direct use of + :func:`__import__` is entirely 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. @@ -1460,7 +1461,8 @@ are always available. They are listed here in alphabetical order. *level* specifies whether to use absolute or relative imports. ``0`` (the default) means only perform absolute imports. Positive values for *level* indicate the number of parent directories to search relative to the - directory of the module calling :func:`__import__`. + directory of the module calling :func:`__import__` (see :pep:`328` for the + details). When the *name* variable is of the form ``package.module``, normally, the top-level package (the name up till the first dot) is returned, *not* the