Lesson 15 · Real programs

Modules and packages

Real programs are split across many files. A module is one .py file, and a package is a folder of modules. Step through a five-line main.py that imports greet.py and shapes/square.py. Watch Python search sys.path, run each module once, save it in sys.modules, and reuse it on the next import. Then see what __name__ == "__main__" is for, and what a misspelt import does.

14 min11 steps5 questionsBeginner

Fig 15 · Interactive

Loading figure…

or ← →

Check yourself

5 quick questions

Pick an answer to see why. Your score saves with your progress.

01greet.py starts with print("greet loaded"). main.py has the line import greet twice. How many times is greet loaded printed?

The first import runs greet.py and saves the module in sys.modules. The second import finds it there and reuses it, so the module's code does not run again.

02After from shapes import square, which new name can main.py use?

from ... import binds only the names after import. Python still loads the package shapes and puts it in sys.modules, but the name shapes is not added to your file.

03Where does Python look first when it runs import greet in a script?

sys.path starts with the folder of the script. After that come the folders in PYTHONPATH, if you set it, then the standard library and the installed packages.

04greet.py ends with if name == "main": hello("test"). When does hello("test") run?

The file you run is named '__main__'. When greet.py is imported, its __name__ is 'greet', so the test code is skipped.

05You run a file whose first line is import gret and there is no gret.py anywhere. What happens?

The search through sys.path finds nothing, so import raises ModuleNotFoundError, a subclass of ImportError. You can catch it with try/except like any other exception.

Key terms

Glossary

Module: A file of Python code, such as greet.py. Its name is the file name without .py.
import: A statement that finds a module, runs it the first time, and binds a name to it in your file.
sys.path: The list of folders Python searches for modules. It starts with the folder of the script you ran.
sys.modules: A dictionary of every module loaded so far. Python checks it first, so each module runs only once.
Package: A folder of modules. A regular package holds an __init__.py file, and its modules have dotted names such as shapes.square.
__init__.py: The file that marks a folder as a regular package. It runs when the package is first imported and may be empty.
__name__: A module's name: the module's own name when it is imported, and '__main__' for the file you run.
ModuleNotFoundError: The ImportError that import raises when no module with that name is found on sys.path.

Fine print

Notes and sources

sys.path starts with the folder of the script you ran (or the current folder at the >>> prompt), then any folders listed in the PYTHONPATH environment variable, then the standard library and site-packages, where pip installs packages.
sys.modules also holds many modules Python loads for itself at start-up (sys, builtins and others); the figure shows only the ones main.py adds.
Real programs import each module once, at the top of the file; main.py imports greet twice only to show that the second import reuses the cached module.
A regular package has an __init__.py, which runs when the package is first imported and may be empty. Since Python 3.3 a folder without one can also be imported as a namespace package, but __init__.py is the usual way.
When a module is imported, Python also saves its compiled bytecode in a __pycache__ folder so the next import starts faster. You can ignore or delete that folder.
In the real traceback the ... is the full path to main.py.

Quiz Unlocks after the last step.