Python Packages

A single module works well for a few functions, but real projects have dozens of files. Python packages solve this by grouping related modules into folders, the same way you'd group documents into folders on your computer. In this lesson, you'll build a small online store project as a package, learn what __init__.py does, and see the difference between absolute and relative imports.

What is a package in Python?

A package is a folder that contains Python modules (and possibly other packages). You mark a folder as a regular package by putting a file called __init__.py in it. Then you import modules from it using dots: package.module.

Python package structure: an online store

Here's the project you'll build. main.py is the program you run; everything inside store/ is the package.

As plain text, the layout looks like this:

online_store/
├── main.py
└── store/
    ├── __init__.py
    ├── products.py
    ├── cart.py
    └── payments/
        ├── __init__.py
        └── cards.py

How do you create a package in Python?

Create the folders, then add the files one at a time. First, the product catalog:

# store/products.py
CATALOG = {"T-shirt": 18.00, "Mug": 9.50, "Cap": 14.00}


def get_price(name):
    return CATALOG[name]

Next, the cart. It needs get_price from its neighbor products.py:

# store/cart.py
from .products import get_price


def cart_total(items):
    total = 0
    for item in items:
        total += get_price(item)
    return total

The dot in from .products means "the products module in this same package". That's a relative import, explained below.

Then a sub-package for payments. Its store/payments/__init__.py can be completely empty. The module inside it looks like this:

# store/payments/cards.py
from ..products import CATALOG


def mask_card(number):
    return "**** **** **** " + number[-4:]


def items_for_sale():
    return len(CATALOG)

Two dots (..) mean "go up one package", from payments to store.

What does __init__.py do?

__init__.py tells Python "this folder is a package". It runs automatically the first time anything in the package is imported, so it's a good place for package-wide setup or shared values. Here's ours:

# store/__init__.py
"""The store package: products, cart and payments."""
print("Setting up the store package...")

VERSION = "1.0"

Anything defined in __init__.py can be imported straight from the package name, like from store import VERSION.

Importing from a package

Now main.py, which sits next to the store/ folder, can use everything:

# main.py
import store.products
from store.cart import cart_total
from store.payments.cards import mask_card
from store import VERSION

print("Store version:", VERSION)
print("Mug costs:", store.products.get_price("Mug"))
print("Cart total:", cart_total(["T-shirt", "Cap", "Mug"]))
print("Paid with:", mask_card("4111222233334444"))

Run main.py from the online_store folder and you'll see:

Setting up the store package...
Store version: 1.0
Mug costs: 9.5
Cart total: 41.5
Paid with: **** **** **** 4444

The setup message prints only once, even though main.py imports from the package four times. Just like modules, a package is loaded once and then reused.

Absolute vs relative imports

There are two ways to point to a module inside your package:

• An absolute import spells out the full path from the top of the project: from store.products import get_price.
• A relative import starts with dots and is measured from the current file's package: from .products import get_price.

Importing a sub-package module

You can also import a module from a sub-package and keep its name as a short prefix:

# main.py
from store.payments import cards

print(cards.items_for_sale())

Output:

Setting up the store package...
3

Notice the setup message again: importing store.payments first imports its parent package store, which runs store/__init__.py.

Common mistakes with packages

1. Running a module inside the package directly

If you open store/cart.py and run it on its own, the relative import fails:

ImportError: attempted relative import with no known parent package

A file run directly has no package around it, so .products means nothing. Run your program from the project folder (python main.py), or run the module as part of its package with the -m flag from the online_store folder: python -m store.cart.

2. Running main.py from the wrong folder

Python looks for store next to the script you run. If main.py and store/ are in different places, you get ModuleNotFoundError: No module named 'store'.

3. Using slashes instead of dots

import store/cart is a syntax error. Import paths always use dots: import store.cart.

4. Expecting import store to load every module

import store runs only store/__init__.py. It does not automatically load store.cart. Import the modules you need by name, or import them inside __init__.py.

Practice exercise

playlist_app/
├── app.py
└── music/
    ├── __init__.py    # empty
    └── playlist.py

# music/playlist.py
def total_minutes(songs):
    total = 0
    for length in songs:
        total += length
    return total

# app.py
from music.playlist import total_minutes

print("Playlist length:", total_minutes([3.5, 4.0, 2.5]), "minutes")

Playlist length: 10.0 minutes

What's next?

Your own packages live in your project folder. But thousands of packages written by other developers are a single command away. Next, learn to install them safely with pip and virtual environments.