Issue #15482: Properly document the default 'level' parameter for

__import__().

To help explain why the -1 default value is typically not seen, a note
about how import statements only use values of >= 0 is also noted.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 72bc7cb909b25add74936ae45bd5bf1643b00d3b..5d6a5fed0aa74125a5ea3f188062060aecbaa881 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1410,7 +1410,7 @@ are always available.  They are listed here in alphabetical order.
       True
 
 
-.. function:: __import__(name, globals={}, locals={}, fromlist=[], level=0)
+.. function:: __import__(name, globals={}, locals={}, fromlist=[], level=-1)
 
    .. index::
       statement: import
@@ -1435,10 +1435,13 @@ are always available.  They are listed here in alphabetical order.
    not use its *locals* argument at all, and uses its *globals* only to
    determine the package context of the :keyword:`import` statement.
 
-   *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__`.
+   *level* specifies whether to use absolute or relative imports. ``0``
+   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__`.  Negative values attempt both an implicit
+   relative import and an absolute import (usage of negative values for *level*
+   are strongly discouraged as future versions of Python do not support such
+   values). Import statements only use values of 0 or greater.
 
    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

diff --git a/Misc/NEWS b/Misc/NEWS
index ed4fa871c6aed402c68b91832725efa36a6889fa..99812d29accef86efefc5d48f764c76c0bfe8599 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -465,6 +465,9 @@ Build
 Documentation
 -------------
 
+- Issue 15482: Properly document the default 'level' value for __import__()
+  while warning about using negative values.
+
 - Issue #15230: Clearly document some of the limitations of the runpy
   module and nudge readers towards importlib when appropriate.