Can anyone help elaborate on this paragraph in Python tutorial?

Question

I'm new to Python. Recently I'm reading Python Tutorial and I've got a question regarding "import *". Here's what the tutorial says:

If __all__ is not defined, the statement from sound.effects import * does not import all submodules from the package sound.effects into the current namespace; it only ensures that the package sound.effects has been imported (possibly running any initialization code in __init__.py) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by __init__.py.

From my understanding, shouldn't from sound.effects import * mean "import all under sound.effects"? What does "it only ensures that the package sound.effects" has been imported" mean? Can someone give an explanation for this paragraph as I'm really confused now? Thanks a lot.

Answer 1

What does "it only ensures that the package sound.effects" has been imported" mean?

Importing a module means executing all the statements at the top indent level inside the file. Most of those statements will be def or class statements which create a function or class and give it a name; but if there are other statements they'll be executed too.

james@Brindle:/tmp$ cat sound/effects/utils.py
mystring = "hello world"

def myfunc():
    print mystring

myfunc()
james@Brindle:/tmp$ python
Python 2.7.5 (default, Jun 14 2013, 22:12:26)
[GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.0.60)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sound.effects.utils
hello world
>>> dir(sound.effects.utils)
['__builtins__', '__doc__', '__file__', '__name__', '__package__', 'myfunc', 'mystring']
>>>

In this example, you can see that importing the module sound.effects.utils has defined the names "mystring" and "myfunc" inside the module, and also the call to "myfunc" on the last line of the file.

"importing the package sound.effects" means "importing (ie, executing) the module in the file named sound/effects/init.py".

When the description says

and then imports whatever names are defined in the package

it's (confusingly) using a different meaning for the word "import". In this case it means that the names defined in the package (ie, those defined in init.py) are copied into the package's namespace.

If we rename sounds/effects/utils.py from earlier to sounds/effects/__init__.py, this is what happens:

>>> import sound.effects
hello world
>>> dir(sound.effects)
['__builtins__', '__doc__', '__file__', '__name__', '__package__', '__path__', 'myfunc', 'mystring']
>>> locals()
{'__builtins__': <module '__builtin__' (built-in)>, '__name__': '__main__', 'sound': <module 'sound' from 'sound/__init__.pyc'>, '__doc__': None, '__package__': None}

As before, myfunc and mystring are created, and now they're in the sounds.effects namespace.

The from x import y syntax loads things into the local namespace rather than their own namespace, so if we switch from import sound.effects to from sound.effects import * these names get loaded into the local namespace instead:

>>> locals()
{'__builtins__': <module '__builtin__' (built-in)>, '__name__': '__main__', '__doc__': None, '__package__': None}
>>> from sound.effects import *
hello world
>>> locals()
{'myfunc': <function myfunc at 0x109eb29b0>, '__builtins__': <module '__builtin__' (built-in)>, '__package__': None, 'mystring': 'hello world', '__name__': '__main__', '__doc__': None}
>>>

Answer 2

    import file

    v = file.Class(...)

Is what you have to do if you import it normally, but the 'from file import '* Means that you can use all the contents of the file without the keyword. Instead of the '*', you can specify specific classes etc...

Answer 3

Briefly:

From my understanding, shouldn't from sound.effects import * mean "import all under sound.effects"?

No, it should mean import sound.effects, then make all of its members available without qualification.

In other words, it's about the members of sound.effects, not any modules or packages underneath it.

If sound.effects is a package, a sub-module or sub-package sound.effects.foo is not automatically a member of sound.effects. And, if it's not a member, it won't become available in your module.

So, what's the deal with that "not necessarily" qualification? Well, once you import sound.effects.foo, it becomes a member of sound.effects. So, if you (or someone else—like, say, sound or sound.effects) has done that import, then sound.effects.foo will be copied into your module by from sound.effects import *.

And that's what the parenthetical bit in this last sentence is all about:

This includes any names defined (and submodules explicitly loaded) by __init__.py.