Master Python Imports: From Simple Modules to Full Packages

Module basics

When a Python file is executed directly, the global variable __name__ is set to "__main__". When the same file is imported, __name__ becomes the module’s filename without the .py extension.

Example pizza.py defines a Pizza class and prints the module name and a message when run as a script:

if __name__ == '__main__':
    invoke_the_real_code()
print('pizza.py module name is %s' % __name__)
if __name__ == '__main__':
    print('Carbonara is the most awesome pizza.')

Running python3 pizza.py shows __name__ as __main__. Importing the file from another module does not execute the top‑level code again.

Package creation

To group related modules, create a directory with an empty __init__.py. For the pizza example:

pizzapy/
├── __init__.py
├── pizza.py
└── menu.py

The package can be imported with import pizzapy.pizza. Adding an __main__.py makes the package executable via python3 -m pizzapy:

# pizzapy/__main__.py
from pizzapy.menu import MENU
print('Awesomeness of pizzas:')
for pizza in MENU:
    print(pizza.name, pizza.awesomeness())

Absolute vs. relative imports

Since Python 3, imports are absolute by default, meaning the interpreter looks for standard library modules before local ones. To import a sibling module within the same package, use a relative import such as from .pizza import * or from . import menu.

Importing sibling packages

If two packages reside side‑by‑side (e.g., pizzapy and pizzashop), running a script inside one package adds only that package’s directory to sys.path, causing ModuleNotFoundError for the sibling. Executing the script with -m adds the current directory ("") to sys.path, allowing both packages to be found.

Module search path

The interpreter’s search path is available as sys.path. When a file is run directly, its containing directory is inserted; when a module is executed with -m, the current working directory is inserted as the first entry.

Understanding these mechanics helps you split large scripts into reusable modules and packages, avoid import errors, and create executable packages.

Original English article: https://alex.dzyoba.com/blog/python-import/ (translated by javylee)