// Create and publish distributable scientific Python packages following Scientific Python community best practices. Covers pyproject.toml, src layout, Hatchling, metadata, CLI entry points, and PyPI publishing.
| name | python-packaging |
| description | Create and publish distributable scientific Python packages following Scientific Python community best practices. Covers pyproject.toml, src layout, Hatchling, metadata, CLI entry points, and PyPI publishing. |
| metadata | {"assets":["assets/pyproject-minimal.toml","assets/pyproject-full-featured.toml","assets/readme-template.md","assets/github-actions-publish.yml","assets/sphinx-conf.py","assets/.gitignore"],"references":["references/common-issues.md","references/docstrings.md","references/metadata.md","references/patterns.md"],"scripts":["scripts/cli-example.py"]} |
A comprehensive guide to creating, structuring, and distributing Python packages for scientific computing, following the Scientific Python Community guidelines. This skill focuses on modern packaging standards using pyproject.toml, PEP 621 metadata, and the Hatchling build backend.
Package Structure Selection:
START
├─ Pure Python scientific package (most common) → Pattern 1 (src/ layout)
├─ Need data files with package → Pattern 2 (data/ subdirectory)
├─ CLI tool → Pattern 5 (add [project.scripts])
└─ Complex multi-feature package → Pattern 3 (full-featured)
Build Backend Choice:
START → Use Hatchling (recommended for scientific Python)
├─ Need VCS versioning? → Add hatch-vcs plugin
├─ Simple manual versioning? → version = "X.Y.Z" in pyproject.toml
└─ Dynamic from __init__.py? → [tool.hatch.version] path
Dependency Management:
START
├─ Runtime dependencies → [project] dependencies
├─ Optional features → [project.optional-dependencies]
├─ Development tools → [dependency-groups] (PEP 735)
└─ Version constraints → Use >= for minimum, avoid upper caps
Publishing Workflow:
1. Build: python -m build
2. Check: twine check dist/*
3. Test: twine upload --repository testpypi dist/*
4. Verify: pip install --index-url https://test.pypi.org/simple/ pkg
5. Publish: twine upload dist/*
Common Task Quick Reference:
# Setup new package
mkdir -p my-pkg/src/my_pkg && cd my-pkg
# Create pyproject.toml with [build-system] and [project] sections
# Development install
pip install -e . --group dev
# Build distributions
python -m build
# Test installation
pip install dist/*.whl
# Publish
twine upload dist/*
Python packages now use standardized build systems instead of classic setup.py:
pyproject.tomlsetup.py, setup.cfg, or MANIFEST.insrc/ layoutsrc/my-sci-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│ └── my_sci_package/
│ ├── __init__.py
│ ├── analysis.py
│ └── utils.py
├── tests/
│ ├── test_analysis.py
│ └── test_utils.py
└── docs/
└── index.md
See assets/pyproject-minimal.toml for a complete minimal pyproject.toml template.
See references/patterns.md for detailed package structure patterns including:
See references/metadata.md for detailed information on:
For CLI tool implementation, see scripts/cli-example.py for a complete example using Click.
Register in pyproject.toml:
[project.scripts]
sci-analyze = "my_sci_package.cli:main"
Ready-to-use templates are available in the assets/ directory:
.gitignore for scientific Python packagespyproject.toml templatepyproject.toml with all optionsSee references/docstrings.md for examples of NumPy-style docstrings and documentation best practices.
python -m build)tar -tvf dist/*.tar.gz)See references/common-issues.md for solutions to:
Encodes symusic's engineering taste across C++ core, nanobind bindings, and Python-facing APIs. Use when implementing or reviewing features to preserve performance-first architecture and ergonomic, predictable interfaces.
Decision framework for selecting and evolving third-party dependencies in symusic across C++, Python packaging, bindings, testing, and docs.
Configure and use automated code quality tools (ruff, mypy, pre-commit) for scientific Python projects. Covers linting rules, type checking configuration, formatting, and CI integration.
Write and organize tests for scientific Python packages using pytest. Covers fixtures, parametrization, numerical testing with NumPy utilities, property-based testing with Hypothesis, and CI integration.