Python Packages and Project Structure

A package is a way of grouping related modules together under a common namespace, using the filesystem's directory structure. Where a module is a single .py file, a package is a directory containing multiple modules (and possibly sub-packages), which lets large projects stay organized as they grow beyond what a handful of flat files can manage.

Packages also give you dotted import paths, like import requests.adapters or from django.db import models, which make it immediately clear where functionality lives within a large codebase.

Why it matters

Once a project has more than a handful of files, they are grouped into folders, and those folders are packages. Every library you install is a package, and import lines such as from app.services.email import send describe a path through one. Understanding the layout is what lets you organise your own project and fix import errors in it.

The Role of __init__.py

Historically, any directory containing an __init__.py file was treated by Python as a regular package. That file can be completely empty — its mere presence used to be what told Python "treat this folder as a package, not just a random directory." Since Python 3.3, "namespace packages" allow directories without __init__.py to work as packages too, but including an explicit __init__.py is still the clearer, more common, and more predictable approach, especially for anything you intend to distribute. The file is also a natural place to run package-level setup code or to explicitly control what a from package import * exposes, using an __all__ list.

A Typical Package Layout

A simple package structure for a project called "shop" might look like this, with each subdirectory representing a sub-package.

• shop/__init__.py — marks shop as a package, may re-export commonly used names.
• shop/models.py — a module inside the package.
• shop/orders/__init__.py — a nested sub-package.
• shop/orders/checkout.py — a module inside the sub-package, imported as shop.orders.checkout.

Relative vs Absolute Imports

An absolute import spells out the full path from the project's top-level package, such as from shop.orders import checkout. A relative import instead uses leading dots to describe a module's location relative to the current one — a single dot (.) means "the current package," and two dots (..) mean "the parent package," as in from . import models or from ..utils import helpers. Absolute imports are generally preferred in application code because they are unambiguous and easy to search for, while relative imports are common inside packages that are meant to be self-contained and movable as a unit. Critically, relative imports only work inside a package that was itself imported — you cannot run a file containing relative imports directly as a script.

Example

# Project layout:
# shop/
#   __init__.py
#   models.py
#   orders/
#     __init__.py
#     checkout.py

# --- shop/models.py ---
class Product:
    def __init__(self, name, price):
        self.name = name
        self.price = price

# --- shop/orders/checkout.py ---
from ..models import Product   # relative import: go up one package to models

def total_price(products):
    return sum(p.price for p in products)

# --- run_shop.py at the project root ---
from shop.models import Product          # absolute import
from shop.orders.checkout import total_price

cart = [Product("Book", 15.0), Product("Pen", 2.5)]
print(total_price(cart))

17.5

Exercise

urllib is a package in the standard library and parse is a module inside it. Import urlparse from that module with an absolute import, parse the address below, and print its host and its path. Then print the full dotted name of the module that urlparse comes from.

Expected output: example.com, /docs, urllib.parse (one per line)

# TODO: import urlparse from the parse module of the urllib package

address = "https://example.com/docs?page=2"

# TODO: parse the address and print its netloc and its path
# TODO: print urlparse.__module__

from urllib.parse import urlparse

address = "https://example.com/docs?page=2"

parts = urlparse(address)
print(parts.netloc)
print(parts.path)
print(urlparse.__module__)

Quick quiz

Interview questions