From 9b000e7a6835e8f1899276be1d2dfebb651ce42b Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 5 Aug 2012 20:46:25 -0400 Subject: 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. --- 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 index 72bc7cb..5d6a5fe 100644 --- 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 ed4fa87..99812d2 100644 --- 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. -- cgit v0.12