[Python-checkins] r67583 - python/trunk/Doc/library/functions.rst

[georg.brandl]

Author: georg.brandl
Date: Fri Dec  5 16:52:20 2008
New Revision: 67583

Log:
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.


Modified:
   python/trunk/Doc/library/functions.rst

Modified: python/trunk/Doc/library/functions.rst
==============================================================================
--- python/trunk/Doc/library/functions.rst	(original)
+++ python/trunk/Doc/library/functions.rst	Fri Dec  5 16:52:20 2008
@@ -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.
+
 ..  ---------------------------------------------------------------------------