setuptools

setuptools Best Practices

setuptools is the de-facto standard for Python packaging. This guide outlines the definitive, modern approach to configuring your Python projects, prioritizing declarative pyproject.toml files, automated versioning, and clear dependency management. Adhere to these rules for consistent, maintainable, and standards-compliant package distributions.

1. Code Organization and Structure

Always use the src/ layout for your package source code. This clearly separates your package's importable code from project-level files (like pyproject.toml, README.md, tests/).

❌ BAD: Flat layout

my_package/
├── __init__.py
├── module.py
├── pyproject.toml
└── tests/

✅ GOOD: src/ layout

my_package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
├── pyproject.toml
├── README.md
└── tests/

2. Declarative Configuration in pyproject.toml

Configure all project metadata and build settings declaratively in pyproject.toml. This aligns with PEP 517/518, enables isolated builds, and makes your package metadata machine-readable without executing code. Avoid setup.py for metadata.

Always include [build-system] and [project] tables.

[build-system]
requires = ["setuptools>=61", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"

[project]
name = "my-awesome-package"
dynamic = ["version"] # Managed by setuptools-scm
description = "A short description of my awesome package."
readme = "README.md"
requires-python = ">=3.8"
license = { file = "LICENSE" }
authors = [
    { name = "Your Name", email = "[email protected]" },
]
keywords = ["python", "utility", "example"]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/yourusername/my-awesome-package"
Documentation = "https://my-awesome-package.readthedocs.io/"
Repository = "https://github.com/yourusername/my-awesome-package"

[tool.setuptools]
package-dir = {"" = "src"} # Essential for src/ layout

[tool.setuptools_scm]
write_to = "src/my_package/_version.py" # Optional: writes version to a file