Merged revisions 67571,67574-67576,67579-67581,67583,67591,67597,67608,67631 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67571 | georg.brandl | 2008-12-05 10:13:45 +0100 (Fri, 05 Dec 2008) | 2 lines
Use markup.
........
r67574 | georg.brandl | 2008-12-05 10:25:32 +0100 (Fri, 05 Dec 2008) | 2 lines
#4441 followup: Add link to open() docs for Windows.
........
r67575 | georg.brandl | 2008-12-05 12:34:51 +0100 (Fri, 05 Dec 2008) | 2 lines
#4544: add `dedent` to textwrap.__all__.
........
r67576 | georg.brandl | 2008-12-05 13:09:41 +0100 (Fri, 05 Dec 2008) | 2 lines
#4529: fix parser's validation for try-except-finally statements.
........
r67579 | georg.brandl | 2008-12-05 16:29:39 +0100 (Fri, 05 Dec 2008) | 2 lines
#4517: add "special method" glossary entry and clarify when __getattribute__ is bypassed.
........
r67580 | georg.brandl | 2008-12-05 16:32:29 +0100 (Fri, 05 Dec 2008) | 2 lines
#4478: document that copyfile() can raise Error.
........
r67581 | georg.brandl | 2008-12-05 16:42:03 +0100 (Fri, 05 Dec 2008) | 2 lines
#3171: document that *slice are removed in 3k.
........
r67583 | georg.brandl | 2008-12-05 16:52:20 +0100 (Fri, 05 Dec 2008) | 4 lines
Move __import__ to the bottom of the functions list.
It doesn't make sense for such a fundamental document to have
the most obscure function listed at the top.
........
r67591 | georg.brandl | 2008-12-05 19:00:06 +0100 (Fri, 05 Dec 2008) | 2 lines
Followup to #4511: add link from decorator glossary entry to definition.
........
r67597 | georg.brandl | 2008-12-05 20:03:19 +0100 (Fri, 05 Dec 2008) | 2 lines
Remove confusing sentence part.
........
r67608 | georg.brandl | 2008-12-06 12:57:12 +0100 (Sat, 06 Dec 2008) | 2 lines
Follow-up to #4488: document PIPE and STDOUT properly.
........
r67631 | georg.brandl | 2008-12-07 12:54:07 +0100 (Sun, 07 Dec 2008) | 2 lines
Add link to the favicon to the docs.
........
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index daa2704..d6c8d05 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -8,67 +8,6 @@
available. They are listed here in alphabetical order.
-.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
-
- .. index::
- statement: import
- module: ihooks
- module: rexec
- module: imp
-
- .. note::
-
- This is an advanced function that is not needed in everyday Python
- programming.
-
- The function is invoked by the :keyword:`import` statement. It mainly exists
- so that you can replace it with another function that has a compatible
- interface, in order to change the semantics of the :keyword:`import` statement.
- See the built-in module :mod:`imp`, which defines some useful operations out
- of which you can build your own :func:`__import__` function.
-
- For example, the statement ``import spam`` results in the following call:
- ``__import__('spam', globals(), locals(), [], -1)``; the statement
- ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
- locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']``
- are passed in as arguments, the :func:`__import__` function does not set the
- local variable named ``eggs``; this is done by subsequent code that is generated
- for the import statement. (In fact, the standard implementation does not use
- its *locals* argument at all, and uses its *globals* only to determine the
- package context of the :keyword:`import` statement.)
-
- 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
- module named by *name*. However, when a non-empty *fromlist* argument is
- given, the module named by *name* is returned. This is done for
- compatibility with the :term:`bytecode` generated for the different kinds of import
- statement; when using ``import spam.ham.eggs``, the top-level package
- :mod:`spam` must be placed in the importing namespace, but when using ``from
- spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the
- ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to
- extract the desired components. For example, you could define the following
- helper::
-
- def my_import(name):
- mod = __import__(name)
- components = name.split('.')
- for comp in components[1:]:
- mod = getattr(mod, comp)
- return mod
-
- *level* specifies whether to use absolute or relative imports. The default is
- ``-1`` which indicates both absolute and relative imports will be attempted.
- ``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__`.
-
- .. versionchanged:: 2.5
- The level parameter was added.
-
- .. versionchanged:: 2.5
- Keyword support for parameters was added.
-
-
.. function:: abs(x)
Return the absolute value of a number. The argument may be a plain or long
@@ -1419,6 +1358,67 @@
Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
:exc:`TypeError` instead of returning an empty list.
+
+.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
+
+ .. index::
+ statement: import
+ module: ihooks
+ module: rexec
+ module: imp
+
+ .. note::
+
+ This is an advanced function that is not needed in everyday Python
+ programming.
+
+ The function is invoked by the :keyword:`import` statement. It mainly exists
+ so that you can replace it with another function that has a compatible
+ interface, in order to change the semantics of the :keyword:`import` statement.
+ See the built-in module :mod:`imp`, which defines some useful operations out
+ of which you can build your own :func:`__import__` function.
+
+ For example, the statement ``import spam`` results in the following call:
+ ``__import__('spam', globals(), locals(), [], -1)``; the statement
+ ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
+ locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']``
+ are passed in as arguments, the :func:`__import__` function does not set the
+ local variable named ``eggs``; this is done by subsequent code that is generated
+ for the import statement. (In fact, the standard implementation does not use
+ its *locals* argument at all, and uses its *globals* only to determine the
+ package context of the :keyword:`import` statement.)
+
+ 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
+ module named by *name*. However, when a non-empty *fromlist* argument is
+ given, the module named by *name* is returned. This is done for
+ compatibility with the :term:`bytecode` generated for the different kinds of import
+ statement; when using ``import spam.ham.eggs``, the top-level package
+ :mod:`spam` must be placed in the importing namespace, but when using ``from
+ spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the
+ ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to
+ extract the desired components. For example, you could define the following
+ helper::
+
+ def my_import(name):
+ mod = __import__(name)
+ components = name.split('.')
+ for comp in components[1:]:
+ mod = getattr(mod, comp)
+ return mod
+
+ *level* specifies whether to use absolute or relative imports. The default is
+ ``-1`` which indicates both absolute and relative imports will be attempted.
+ ``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__`.
+
+ .. versionchanged:: 2.5
+ The level parameter was added.
+
+ .. versionchanged:: 2.5
+ Keyword support for parameters was added.
+
.. ---------------------------------------------------------------------------