Python Packages

From Modules to Packages

A single module works fine for small scripts, but real projects need many files organised into folders. A package is just a directory containing Python modules plus a special file called __init__.py that tells Python "this folder is importable".

A Simple Package Structure

Imagine a folder named shapes with two modules inside it, circle.py and square.py, plus an __init__.py. That folder is now a package named shapes.

shapes/
    __init__.py
    circle.py
    square.py
main.py

def area(radius):
    return 3.14159 * radius ** 2

The Role of __init__.py

This file can be completely empty — its presence alone marks the folder as a package. You can also use it to run setup code or to control exactly what gets exposed when someone imports the package.

Importing From a Package

Use dot notation to reach into a package and pick a module, then call its functions just like with any other import.

from shapes import circle
from shapes.square import area as square_area

print(circle.area(5))
print(square_area(4))

Sub-packages

Packages can contain other packages, called sub-packages, letting you build a deep, logical folder tree for very large applications — this is exactly how popular libraries and frameworks organise thousands of files.

shapes/
    __init__.py
    two_d/
        __init__.py
        circle.py
    three_d/
        __init__.py
        sphere.py

from shapes.two_d import circle
from shapes.three_d.sphere import volume