Modules and Packages

Each Python file is a module that you can use inside another Python file by importing it. If the file is in the same directory, you can simply use an import statement:

# module.py

def useful_function():
    return "Use this elsewhere!"

# use_module.py
import module

print("'module' imported")

if __name__ == "__main__":
    print(module.useful_function())

When you import a module, it creates a namespace within the importing file. This automatically prevents name clashes between the names in the imported module and the local names. To call useful_function(), you must qualify it with the name of the module: module.useful_function().

The code at the end of the file starts with an if clause which checks to see if something called __name__ is equivalent to __main__. In Python, any identifier that begins and ends with double underscores is special in some way. The reason for the if is that any file can also be used as a library module within another program. In that case, you just want the classes defined, but you don’t want the code at the bottom of the file to be executed. This particular if statement is only true when you are running this file directly. That is, __name__ is __main__ when you use the command line:

python use_module.py

However, if use_module.py is imported as a module into another program, __name__ will not be __main__, so its __main__ code is not executed. Here is such a program, which does nothing but import it:

# import_module.py
import use_module

If you run python import_module.py, you should only see 'module' imported as the result. Importing use_module runs its top-level code, including that print(), but not its __main__ block.

If you want to bring a name into the current namespace, you can do so using the from keyword:

# using_from.py
from module import useful_function

if __name__ == "__main__":
    print(useful_function())

You can change the namespace of a module during an import using the as keyword:

# using_as.py
import module as m

if __name__ == "__main__":
    print(m.useful_function())

Packages

As your programs get larger you’ll want to further organize your code into packages. A package is a directory (and its own namespace, which has the name of that directory) that can contain multiple modules.

To make something a package, you put a special file named __init__.py in that directory. Except in special cases, this file is empty; it is only there to flag the directory as a package.¹

To demonstrate, we’ll create a directory called a_package and give it an __init__.py containing nothing but a comment:

# a_package/__init__.py

Now we’ll add two modules to the package:

# a_package/module1.py

def function1():
    return "function1 in module1 in a_package"

# a_package/module2.py

def function2():
    return "function2 in module2 in a_package"

To import a module from a package, you must qualify it with the package name:

# using_packages.py
import a_package.module1
import a_package.module2

print(a_package.module1.function1())
print(a_package.module2.function2())

You can also name the package with from:

# from_packages.py
from a_package import module1, module2

print(module1.function1())
print(module2.function2())

Here you no longer need to qualify the module with the package name.

Finally, you can bring specific functions into the namespace by naming both the package and the module:

# no_qualification.py
from a_package.module1 import function1
from a_package.module2 import function2

print(function1())
print(function2())

We can even put a second package underneath the first one:

# a_package/b_package/__init__.py

# a_package/b_package/module3.py

def function3():
    return "function3 in module3 in b_package"

To import module3 we must specify both packages:

# two_levels.py
from a_package.b_package import module3

print(module3.function3())

PYTHONPATH

What if your module or package isn’t placed in the same directory as the Python file that’s doing the importing? The original (and now semi-deprecated) solution to this was to set an environment variable called PYTHONPATH which tells Python where to look for modules and packages. PYTHONPATH can take multiple paths, and Python will keep searching through those paths until it finds your module or package (or doesn’t, and reports an error).

PYTHONPATH still works, but has been effectively superseded by the virtual environment, which solves much more than just “where are the modules and packages.”