This skill should be used when the user asks to "create a Python package", "set up pyproject.toml", "publish to PyPI", "configure Hatchling", "use src layout", "add package metadata", "create CLI tool", "set up package structure", "configure build backend", "add optional dependencies", or needs guidance on Python packaging best practices, pyproject.toml configuration, src layout structure, Hatchling build backend, PyPI publishing workflows, or Scientific Python packaging standards.
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:
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer