[Python-checkins] cpython (3.2): Issue #15482: Properly document the default 'level' parameter for

[brett.cannon]

http://hg.python.org/cpython/rev/3fe01f7520e2
changeset:   78449:3fe01f7520e2
branch:      3.2
parent:      78443:ee0ac9a0461f
user:        Brett Cannon <brett at python.org>
date:        Sun Aug 05 20:46:25 2012 -0400
summary:
  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.

files:
  Doc/library/functions.rst |  13 ++++++++-----
  Misc/NEWS                 |   3 +++
  2 files changed, 11 insertions(+), 5 deletions(-)


diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1410,7 +1410,7 @@
       True
 
 
-.. function:: __import__(name, globals={}, locals={}, fromlist=[], level=0)
+.. function:: __import__(name, globals={}, locals={}, fromlist=[], level=-1)
 
    .. index::
       statement: import
@@ -1435,10 +1435,13 @@
    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
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -465,6 +465,9 @@
 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.
 

-- 
Repository URL: http://hg.python.org/cpython