Modules and Packages

Sooner or later a project outgrows a single file. You split code across modules, pull in third-party libraries, and maybe publish something of your own. This chapter covers how modules and packages are organized, the different forms of import, managing dependencies with pip and requirements files, describing a project in pyproject.toml, and the basics of publishing to PyPI.

Modules and packages

Every .py file is a module, and its file name without the extension is the module name. A package is a directory of modules, usually containing an __init__.py file. That file can be empty, or it can run setup code and choose which names the package exposes.

myapp/
    pyproject.toml
    src/
        myapp/
            __init__.py
            cli.py
            text/
                __init__.py
                slug.py
    tests/
        test_slug.py

Placing the package under src/ is known as the src layout. It prevents tests from accidentally importing your working copy instead of the installed package, which is why many library authors prefer it.

Importing

import comes in a few flavors. A module's top-level code runs only the first time it is imported; later imports reuse the cached module object.

import json                          # the whole module
import datetime as dt                # with an alias
from pathlib import Path             # a single name
from collections import Counter, defaultdict

data = json.loads('{"a": 1}')
today = dt.date.today()
config = Path("config") / "app.toml"

Inside a package, modules can refer to their siblings with relative imports. A single dot means the current package and two dots mean its parent.

# src/myapp/text/slug.py
import re


def slugify(title: str) -> str:
    return re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")


# src/myapp/cli.py
from .text.slug import slugify


def main() -> None:
    print(slugify("Hello Python World"))  # hello-python-world

Avoid from module import *: it hides where names come from and can silently shadow your own. If two modules import each other, you may hit circular import errors; the usual cure is moving the shared code into a third module.

pip and requirements files

To reproduce an application on another machine, you need a list of its dependencies. The simplest format is a requirements.txt file.

# record every installed package with its exact version
python -m pip freeze > requirements.txt

# recreate the same set somewhere else
python -m pip install -r requirements.txt

pip freeze pins everything, including indirect dependencies. Exact pins suit deployed applications; libraries should declare looser ranges so they play well with other packages. Tools such as pip-tools, Poetry and uv automate this pinning and keep lock files up to date.