Where can I read about import _{module name} in Python?

Question

I've notice this. Example:

create an empty text file called for example ast.py

$ touch ast.py

run Python

$ python
>>> from ast import *
>>> dir()
['__builtins__', '__doc__', '__name__', '__package__']
>>> from _ast import *
>>> dir()
['AST', 'Add', 'And', 'Assert', 'Assign', ...]

ast is a python module. So... what's happening here? I tried with an empty os.py and didn't work.

Answer 1

There's nothing special with _xxx modules except they are private (e.g. _abcoll) or low-level (e.g. _thread) and not intended to be used in general.

The _ast module is special, e.g.

$ touch _ast.py
$ python -c 'from _ast import *; print(dir())'
['AST', 'Add', 'And', 'Assert', 'Assign', 'Attribute ...

But this is not because of the leading _, but that _ast is a built-in module. Similar thing happens with the sys module.

$ touch sys.py
$ python -c 'from sys import *; print(dir())'
['__builtins__', '__doc__', '__name__', '__package__', 'api_version', 'argv', ...

---

In Python _ast and ast are two separate modules. There is a line

from _ast import *

in the built-in ast.py, so importing ast will also bring everything from the _ast module in. This gives you the illusion that _ast and ast have the same content, but actually _ast is a lower level module of ast.

Answer 2

This is because _ast is also a module. There is no magic here. Also, _ast is a builtin module (i.e. a module that doesn't exist as a separate file, but is compiled in the interpreter itself), so it is always loaded and creating a file of the same same won't get rid of it.

And the reason why _ast will not be overloaded by a file, is that once a module is loaded, python will not look again at the files. You can find the list of all the modules currently loaded in sys.modules. And if you want a complete documentation about modules, look at the python documentation. Everything is specified, like here: http://docs.python.org/tutorial/modules.html or here: http://docs.python.org/reference/simple_stmts.html#the-import-statement