from <module> import ... in __init__.py makes module name visible?

Question

Take the following code example:

File package1/__init__.py:

from moduleB import foo
print moduleB.__name__

File package1/moduleB.py:

def foo(): pass

Then from the current directory:

>>> import package1
package1.moduleB

This code works in CPython. What surprises me about it is that the from ... import in __init__.py statement makes the moduleB name visible. According to Python documentation, this should not be the case:

The from form does not bind the module name

Could someone please explain why CPython works that way? Is there any documentation describing this in detail?

Answer 1

The documentation misled you as it is written to describe the more common case of importing a module from outside of the parent package containing it.

For example, using "from example import submodule" in my own code, where "example" is some third party library completely unconnected to my own code, does not bind the name "example". It does still import both the example/__init__.py and example/submodule.py modules, create two module objects, and assign example.submodule to the second module object.

But, "from..import" of names from a submodule must set the submodule attribute on the parent package object. Consider if it didn't:

1. package/__init__.py executes when package is imported.

2. That __init__ does "from submodule import name".

3. At some point later, other completely different code does "import package.submodule".

At step 3, either sys.modules["package.submodule"] doesn't exist, in which case loading it again will give you two different module objects in different scopes; or sys.modules["package.submodule"] will exist but "submodule" won't be an attribute of the parent package object (sys.modules["package"]), and "import package.submodule" will do nothing. However, if it does nothing, the code using the import cannot access submodule as an attribute of package!

---

Theoretically, how importing a submodule works could be changed if the rest of the import machinery was changed to match.

If you just need to know what importing a submodule S from package P will do, then in a nutshell:

1. Ensure P is imported, or import it otherwise. (This step recurses to handle "import A.B.C.D".)
2. Execute S.py to get a module object. (Skipping details of .pyc files, etc.)
3. Store module object in sys.modules["P.S"].
4. setattr(sys.modules["P"], "S", sys.modules["P.S"])
5. If that import was of the form "import P.S", bind "P" in local scope.