Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
................
r67654 | georg.brandl | 2008-12-07 16:42:09 -0600 (Sun, 07 Dec 2008) | 2 lines
#4457: rewrite __import__() documentation.
................
r67676 | benjamin.peterson | 2008-12-08 20:03:03 -0600 (Mon, 08 Dec 2008) | 1 line
specify how things are copied
................
r67677 | benjamin.peterson | 2008-12-08 20:05:11 -0600 (Mon, 08 Dec 2008) | 1 line
revert unrelated change to installer script
................
r67681 | jeremy.hylton | 2008-12-09 15:03:10 -0600 (Tue, 09 Dec 2008) | 2 lines
Add simple unittests for Request
................
r67692 | amaury.forgeotdarc | 2008-12-10 18:03:42 -0600 (Wed, 10 Dec 2008) | 2 lines
#1030250: correctly pass the dry_run option to the mkpath() function.
................
r67725 | benjamin.peterson | 2008-12-12 22:02:20 -0600 (Fri, 12 Dec 2008) | 1 line
fix incorrect example
................
r67746 | antoine.pitrou | 2008-12-13 17:12:30 -0600 (Sat, 13 Dec 2008) | 3 lines
Issue #4163: Use unicode-friendly word splitting in the textwrap functions when given an unicode string.
................
r67748 | benjamin.peterson | 2008-12-13 19:46:11 -0600 (Sat, 13 Dec 2008) | 1 line
remove has_key usage
................
r67761 | benjamin.peterson | 2008-12-14 11:26:04 -0600 (Sun, 14 Dec 2008) | 1 line
fix missing bracket
................
r67784 | georg.brandl | 2008-12-15 02:33:58 -0600 (Mon, 15 Dec 2008) | 2 lines
#4446: document "platforms" argument for setup().
................
r67785 | georg.brandl | 2008-12-15 02:36:11 -0600 (Mon, 15 Dec 2008) | 2 lines
#4611: fix typo.
................
r67787 | georg.brandl | 2008-12-15 02:58:59 -0600 (Mon, 15 Dec 2008) | 2 lines
#4578: fix has_key() usage in compiler package.
................
r67788 | georg.brandl | 2008-12-15 03:07:39 -0600 (Mon, 15 Dec 2008) | 2 lines
#4568: remove limitation in varargs callback example.
................
r67802 | amaury.forgeotdarc | 2008-12-15 16:29:14 -0600 (Mon, 15 Dec 2008) | 4 lines
#3632: the "pyo" macro from gdbinit can now run when the GIL is released.
Patch by haypo.
................
r67832 | antoine.pitrou | 2008-12-17 16:46:54 -0600 (Wed, 17 Dec 2008) | 4 lines
Issue #2467: gc.DEBUG_STATS reports invalid elapsed times.
Patch by Neil Schemenauer, very slightly modified.
................
r67848 | benjamin.peterson | 2008-12-18 20:28:56 -0600 (Thu, 18 Dec 2008) | 1 line
fix typo
................
r67849 | benjamin.peterson | 2008-12-18 20:31:35 -0600 (Thu, 18 Dec 2008) | 1 line
_call_method -> _callmethod and _get_value to _getvalue
................
r67859 | amaury.forgeotdarc | 2008-12-19 16:56:48 -0600 (Fri, 19 Dec 2008) | 4 lines
#4700: crtlicense.txt is displayed by the license() command and should be kept ascii-only.
Will port to 3.0
................
r67862 | benjamin.peterson | 2008-12-19 20:48:02 -0600 (Fri, 19 Dec 2008) | 1 line
copy sentence from docstring
................
r67863 | benjamin.peterson | 2008-12-19 20:51:26 -0600 (Fri, 19 Dec 2008) | 1 line
add headings
................
r67864 | benjamin.peterson | 2008-12-19 20:57:19 -0600 (Fri, 19 Dec 2008) | 1 line
beef up docstring
................
r67880 | benjamin.peterson | 2008-12-20 16:49:24 -0600 (Sat, 20 Dec 2008) | 1 line
remove redundant sentence
................
r67882 | benjamin.peterson | 2008-12-20 16:59:49 -0600 (Sat, 20 Dec 2008) | 1 line
add some recent releases to the list
................
r67885 | benjamin.peterson | 2008-12-20 17:48:54 -0600 (Sat, 20 Dec 2008) | 1 line
silence annoying DeprecationWarning
................
r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line
sphinx.web is long gone
................
r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line
update readme
................
r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line
there are way too many places which need to have the current version added
................
r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines
Merged revisions 67809 via svnmerge from
svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3
........
r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line
fix logic error
........
................
r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines
Add Tarek for work on distutils.
................
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index d6c8d05..9b408dc 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1363,8 +1363,6 @@
.. index::
statement: import
- module: ihooks
- module: rexec
module: imp
.. note::
@@ -1372,46 +1370,64 @@
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.
+ This function is invoked by the :keyword:`import` statement. It can be
+ replaced (by importing the :mod:`builtins` module and assigning to
+ ``builtins.__import__``) in order to change semantics of the
+ :keyword:`import` statement, but nowadays it is usually simpler to use import
+ hooks (see :pep:`302`). Direct use of :func:`__import__` is rare, except in
+ cases where you want to import a module whose name is only known at runtime.
- 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.)
+ The function imports the module *name*, potentially using the given *globals*
+ and *locals* to determine how to interpret the name in a package context.
+ The *fromlist* gives the names of objects or submodules that should be
+ imported from the module given by *name*. 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.
+
+ *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__`.
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::
+ given, the module named by *name* is returned.
- def my_import(name):
- mod = __import__(name)
- components = name.split('.')
- for comp in components[1:]:
- mod = getattr(mod, comp)
- return mod
+ For example, the statement ``import spam`` results in bytecode resembling the
+ following code::
+
+ spam = __import__('spam', globals(), locals(), [], -1)
- *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__`.
+ The statement ``import spam.ham`` results in this call::
+
+ spam = __import__('spam.ham', globals(), locals(), [], -1)
+
+ Note how :func:`__import__` returns the toplevel module here because this is
+ the object that is bound to a name by the :keyword:`import` statement.
+
+ On the other hand, the statement ``from spam.ham import eggs, sausage as
+ saus`` results in ::
+
+ _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1)
+ eggs = _temp.eggs
+ saus = _temp.sausage
+
+ Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
+ object, the names to import are retrieved and assigned to their respective
+ names.
+
+ If you simply want to import a module (potentially within a package) by name,
+ you can get it from :data:`sys.modules`::
+
+ >>> import sys
+ >>> name = 'foo.bar.baz'
+ >>> __import__(name)
+ <module 'foo' from ...>
+ >>> baz = sys.modules[name]
+ >>> baz
+ <module 'foo.bar.baz' from ...>
.. versionchanged:: 2.5
The level parameter was added.