Packages and Modules

Modules

Any .py file is a module. Importing runs the file top-to-bottom once per process and caches it in sys.modules.

# math_utils.py
def square(n):
    return n * n

PI = 3.14159

# main.py
import math_utils
print(math_utils.square(5), math_utils.PI)

from math_utils import square, PI
from math_utils import square as sq      # alias

The if __name__ == "__main__" Idiom

# When run directly: __name__ is '__main__'
# When imported:     __name__ is the module name

def main():
    ...

if __name__ == "__main__":
    main()

Packages

A package is a directory containing an __init__.py file (even if empty). Sub-packages nest.

myapp/
├── __init__.py        # marks the directory as a package
├── core.py
├── cli.py
└── db/
    ├── __init__.py
    ├── models.py
    └── queries.py

# Absolute imports
from myapp.core import run
from myapp.db.models import User

# Relative imports — only allowed inside packages
from .core import run          # same package
from ..db import models         # parent package

What goes in __init__.py

# Common patterns:

# 1. Empty — just marks the package

# 2. Re-export public API
from .core import run, Pipeline
from .db.models import User
__all__ = ["run", "Pipeline", "User"]

# 3. Set package version
__version__ = "1.0.0"

The Import System

How Python Finds Modules

Python searches the directories in sys.path, in order. The first match wins.

import sys
print(sys.path)
# [ '',                              # current directory (script dir)
#   '/usr/lib/python3.12',          # standard library
#   '/usr/lib/python3.12/lib-dynload',
#   '/path/to/.venv/lib/python3.12/site-packages' ]

Common Import Pitfalls

• Circular imports: Module A imports B, B imports A. Restructure or move the import inside a function.
• from foo import *: Pollutes the namespace. Use only in REPLs. Use __all__ to control what gets exported.
• Mutable module-level state: Modules are cached — top-level mutables persist across importers.

pip and Virtual Environments

pip basics

$ pip install fastapi             # install latest
$ pip install "fastapi>=0.100"    # version constraint
$ pip install -r requirements.txt # from file
$ pip install -e .                 # editable install (for local packages)
$ pip list                         # show installed
$ pip show fastapi                 # show metadata
$ pip uninstall fastapi
$ pip freeze > requirements.txt    # snapshot exact versions

venv per project

$ python3 -m venv .venv
$ source .venv/bin/activate         # macOS/Linux
(.venv) $ pip install requests rich
(.venv) $ pip freeze > requirements.txt
(.venv) $ deactivate

Modern Alternative: uv

uv is a Rust-based pip+venv replacement that's 10-100× faster.

$ uv venv
$ uv pip install fastapi
$ uv pip sync requirements.txt

pyproject.toml — The Modern Standard

PEP 621 defines a unified format for project metadata, dependencies, and tool configuration. One file replaces setup.py, setup.cfg, and most tool config files.

[project]
name = "myapp"
version = "0.1.0"
description = "My awesome app"
requires-python = ">=3.10"
dependencies = [
    "fastapi>=0.100",
    "pydantic>=2",
]

[project.optional-dependencies]
dev = [
    "pytest",
    "ruff",
    "mypy",
]

[project.scripts]
myapp = "myapp.cli:main"           # installs a `myapp` shell command

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]

$ pip install -e ".[dev]"          # install package + dev extras

Publishing to PyPI

$ pip install build twine
$ python -m build                 # produces dist/*.whl and dist/*.tar.gz
$ twine upload --repository testpypi dist/*  # test first
$ twine upload dist/*              # publish to real PyPI