Packages & Project Layout

Introduction

A production Python project uses src/ layout + pyproject.toml — the modern standard since PEP 621.

Understanding the topic

Core concepts to understand:

• pyproject.toml replaces setup.py.
• src/ layout prevents import shadowing.
• tests/ mirrors package tree.
• pip install -e . for editable installs.

Syntax reference

Visual flow / code:

myproj/
├── pyproject.toml
├── README.md
├── src/
│   └── myproj/
│       ├── __init__.py
│       └── core.py
└── tests/
    └── test_core.py

# pyproject.toml (excerpt)
[project]
name = "myproj"
version = "0.1.0"
dependencies = ["requests>=2.31"]

Execution workflow

Real-world use

src/ layout + pyproject.toml is what Poetry, Hatch, uv, and PyPA recommend. It's the foundation for shipping pip-installable libraries.

Best practices

• Use src/ layout always.
• pyproject.toml + uv/poetry for modern projects.
• Editable install for dev.

Hands-on exercise

Interview preparation — practice these questions:

• Why src/ layout?
• What replaces setup.py today?
• Editable install — what does it do?

Summary

In summary: src/ + pyproject.toml = modern. Editable installs for active dev.