python-packaging

name	python-packaging
description	Use when creating a new Python package, adding pyproject.toml to an existing project, choosing a build backend, setting up src layout, configuring VCS-based versioning, or managing a development environment with pixi or uv for a HEP Python project.

Python Packaging

Overview

Modern Python packages declare all metadata in pyproject.toml and use a dedicated build backend (hatchling, flit, uv_build, etc.). The src layout (src/<package>/) is the community standard. Environment management for HEP projects should use pixi (preferred) or uv.

The Scientific Python community maintains a template ( scientific-python/cookie) and checker (sp-repo-review) that encode these recommendations. Use them as a reference for new projects.

When to Use

• Starting a new Python package for a HEP analysis tool or library
• Migrating an existing setup.py / setup.cfg project to pyproject.toml
• Choosing between build backends or environment managers
• Setting up automatic versioning from git tags
• Adding a pixi.toml for reproducible developer environments

Key Concepts

Concept	Details
pyproject.toml	Single config file; replaces setup.py, setup.cfg, MANIFEST.in
Build backend	Hatchling is recommended; flit-core and uv_build also work well
src layout	src/<package>/ prevents accidental local-import bugs
requires-python	Set minimum; never set an upper cap
VCS versioning	hatch-vcs reads git tags; no manual version bumps
pixi	Preferred for lockfile-based reproducible environments

pyproject.toml metadata ([project])

[project]
name = "my-hep-tool"
description = "Short description"
readme = "README.md"
license = "MIT"
requires-python = ">=3.11"
dynamic = ["version"]
dependencies = [
  "awkward>=2",
  "uproot>=5",
  "hist>=2.7",
]

# Optional extras ship with the package (installed via `pip install pkg[plot]`
# or `uv sync --extra plot`):
[project.optional-dependencies]
plot = ["matplotlib", "mplhep"]

# Local-only dev tools (PEP 735 dependency groups, installed via
# `uv sync --group dev`); these are NOT published to PyPI:
[dependency-groups]
dev = ["pytest", "pytest-cov"]

dynamic = ["version"] lets the backend compute the version; omit it only if you pin the version manually.

Directory layout

my-hep-tool/
  pyproject.toml
  pixi.toml          # or uv.lock / environment.yaml
  src/
    my_hep_tool/
      __init__.py
      analysis.py
  tests/
    test_analysis.py

Canonical Patterns

Hatchling backend with VCS versioning

[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "vcs"

Add these two files so git archive (GitHub downloads) also get the version:

.git_archival.txt:

node: $Format:%H$
node-date: $Format:%cI$
describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

.gitattributes (append):

.git_archival.txt  export-subst

pixi environment

# pixi.toml
# The manifest table is [workspace]; older pixi used [project] (now renamed).
[workspace]
name = "my-hep-tool"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
python = ">=3.11"
awkward = ">=2"
uproot = ">=5"
hist = ">=2.7"

[feature.dev.dependencies]
pytest = "*"
pre-commit = "*"

[feature.dev.tasks]
test = "pytest"
pre-commit = "pre-commit run --all-files"

[environments]
dev = { features = ["dev"], solve-group = "default" }

uv alternative (no pixi)

# In pyproject.toml, uv_build backend
[build-system]
requires = ["uv_build>=0.7.19"]
build-backend = "uv_build"

Run with uv run pytest or uv sync --group dev.

Gotchas

• Never use setup.py or setup.cfg for new projects — those are setuptools-specific legacy files. Modern backends don't use them.
• No upper cap on requires-python: >=3.11 is correct; >=3.11,<4 is not — upper caps break installation for future Python versions.
• src layout is required to avoid testing the local source instead of the installed package; without it, import my_hep_tool silently picks up the un-installed tree.
• Flit needs license.file set explicitly in [project]; hatchling and uv_build detect it automatically.
• dynamic = ["version"] must be set when using hatch-vcs; otherwise hatchling expects a static version string.

Interop

• pixi: preferred environment manager — handles both Python and non-Python (e.g., ROOT) dependencies via conda-forge
• uv: lightweight alternative to pixi for pure-Python projects
• nox: task runner for CI matrix tests; see scikit-hep/hist noxfile.py for a HEP example
• scientific-python/cookie: template with all conventions pre-configured; see https://github.com/scientific-python/cookie
• sp-repo-review: audit an existing repo against the guidelines; see https://github.com/scientific-python/sp-repo-review

Docs

• Scientific Python packaging guide: https://learn.scientific-python.org/development/pages/guides/packaging-simple/
• PyPA packaging tutorial: https://packaging.python.org/tutorials/packaging-projects/
• Hatchling: https://hatch.pypa.io/latest/
• pixi: https://pixi.sh/