Recap — pyproject.toml, src Layout, and Modern Packaging

# pyproject.toml, src Layout, and Modern Packaging Python packaging was confusing for years (setup.py, setup.cfg, requirements.txt, MANIFEST.in...). In 2026, it's converging on `pyproject.toml` + `src/` layout + `uv`. ## The recommended project structure (2026) ``` my-package/ ├── pyproject.toml # single source of metadata + deps + tool config ├── README.md ├── LICENSE ├── .python-version # for pyenv / uv ├── src/ │ └── my_package/ # actual package code │ ├── __init__.py │ ├── __main__.py # if it's a runnable module │ ├── core.py │ └── utils.py ├── tests/ │ ├── conftest.py │ ├── test_core.py │ └── test_utils.py ├── docs/ └── .github/ └── workflows/ └── ci.yml ``` ## Why `src/` layout Without `src/`, your package directory is in the project root: ``` my-package/ ├── my_package/ │ └── ... └── tests/ ``` This causes a subtle bug: tests can import `my_package` even without installing it (because the cwd is on sys.path). You might be testing your local files instead of the installed package — bugs lurk. With `src/`: - Tests must use the installed version (forced by Python import rules). - Catches packaging bugs early. - Industry standard. Trade-off: slightly more verbose. Worth it. ## pyproject.toml — the single source of truth ```toml [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [project] name = "my-package" version = "0.1.0" description = "A short description" readme = "README.md" requires-python = ">=3.11" license = "MIT" authors = [ { name = "Your Name", email = "you@example.com" } ] dependencies = [ "requests>=2.31", "pydantic>=2.0", ] [project.optional-dependencies] dev = [ "pytest>=7.0", "pyright", "ruff", ] [project.scripts] my-cli = "my_package.cli:main" # creates `my-cli` command on install [project.urls] Homepage = "https://github.com/you/my-package" [tool.hatch.build.targets.wheel] packages = ["src/my_package"] [tool.pytest.ini_options] testpaths = ["tests"] [tool.pyright] include = ["src", "tests"] typeCheckingMode = "strict" [tool.ruff] line-length = 100 target-version = "py311" [tool.ruff.lint] select = ["E", "F", "I", "B", "UP"] ``` One file: project metadata + dependencies + tool configurations. Replaces `setup.py`, `setup.cfg`, `requirements.txt`, separate config files for ruff, pytest, etc. ## The build system `build-system` specifies how to build the package: - **hatchling** (modern, fast, recommended). - **setuptools** (legacy but works). - **poetry-core** (if using Poetry). - **flit-core** (minimal). For most new projects: hatchling. ## Installing for development ```bash # Editable install: changes in src/ reflect immediately pip install -e . # With dev dependencies pip install -e ".[dev]" ``` Editable install creates a link, not a copy. Edits to your source code take effect without reinstall. Standard for development. ## Dependency management tools (2026 landscape) ### uv (recommended in 2026) ```bash # Create project uv init my-package # Add dependency uv add requests # Add dev dependency uv add --dev pytest # Install everything uv sync # Run a script in the env uv run python script.py ``` Fast (Rust-based; 10-100x faster than pip), correct (PEP 621 + lockfile), and replaces virtualenv + pip + pip-tools. In 2026, uv is the modern default. Use it for new projects. ### Poetry ```bash poetry add requests poetry install poetry run python script.py ``` Mature, widely used. Slower than uv but feature-rich. Use if your team is already on it. ### pip + pip-tools (the simple stack) ```bash # requirements.in (you write this) requests>=2.31 pydantic>=2.0 # Compile to requirements.txt with pinned versions pip-compile requirements.in pip install -r requirements.txt ``` Works everywhere; minimal magic. Use for simple projects or CI environments. ### Conda (data science world) Conda is its own ecosystem; used heavily in DS/ML. Not really compatible with the pip world. Use if your team / domain depends on it (PyData stack). ## Lockfiles A lockfile pins exact versions of all dependencies (including transitive): - `uv.lock` (uv) - `poetry.lock` (poetry) - `requirements.txt` from pip-compile (pip-tools) Why: reproducible builds. Same code on different machines = same dependencies. Commit lockfiles to git. They're not "human-edited"; tools update them. ## Versioning Use **semver** (Major.Minor.Patch): - Major: breaking changes. - Minor: new features, backward compatible. - Patch: bug fixes. ``` 0.x.y # pre-1.0; anything can change 1.0.0 # first stable release; commit to API 1.1.0 # new features 1.1.1 # bug fix 2.0.0 # breaking changes ``` In pyproject.toml: ```toml [project] version = "0.1.0" ``` For automated versioning: `hatch-vcs` reads version from git tags. ## Publishing to PyPI ```bash # Build wheel + sdist uv build # or: python -m build # Upload (need PyPI API token) uv publish # or: twine uploa