homepage

The documentation for __import__ says that it primarily exists "so that
you can replace it with another function that has a compatible
interface, in order to change the semantics of the import statement".
http://docs.python.org/library/functions.html
That is no longer the case. The recommended way to do that is with the
new import hooks, and the docs should reflect that.
A common use for __import__ is for when you don't know the module name
until runtime. That too should be mentioned.

Also, the examples that clarify __import__ behaviour by Nick Coghlan
should be added:
http://mail.python.org/pipermail/python-dev/2008-November/083735.html
---
"from foo.bar import baz" ---->
<stack top> = __import__('foo.bar', globals(), locals(), ['baz'], -1)
baz = <stack top>.baz
When there are multiple names being imported or an 'as' clause is
involved, I hope the reasons for doing it this way become more obvious:
"from foo.bar import baz, bob" ---->
<stack top> = __import__('foo.bar', globals(), locals(), ['baz', 'bob'], -1)
baz = <stack top>.baz
bob = <stack top>.bob
"from foo.bar import baz as bob" ---->
<stack top> = __import__('foo.bar', globals(), locals(), ['baz', 'bob'], -1)
bob = <stack top>.baz
---
And the "winning idiom" by Hrvoje Niksic for accessing module 'z', given
name hierarchy 'x.y.z' should be documented as well:
>>> import sys
>>> __import__('x.y.z')
>>> mod = sys.modules['x.y.z']

Attached is a proposed rewrite of the __import__ documentation.

Brett, don't you think the 
>>> import sys
>>> __import__('x.y.z')
>>> mod = sys.modules['x.y.z']
idiom should be recommended instead of/additionally to the lengthy
getattr() one?

Yes, the simple __import__/sys.modules idiom should be the suggested
idiom until a proper function is provided in the standard library.

Changed patch to document sys.modules trick and applied in r67654.