From example-skills
Structures Python projects for distribution using pyproject.toml, src/flat layouts, dependency management, entry points, and tools like Hatchling, setuptools, Flit, Poetry.
How this skill is triggered — by the user, by Claude, or both
Slash command
/example-skills:python-packaging-patternsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Structure Python projects for reliable distribution and dependency management.
Structure Python projects for reliable distribution and dependency management.
src Layout (Recommended)my-project/
├── pyproject.toml
├── src/
│ └── my_package/
│ ├── __init__.py
│ ├── core.py
│ └── cli.py
├── tests/
│ ├── conftest.py
│ └── test_core.py
└── README.md
Why src layout: Prevents accidental imports from the working directory. Forces installation before testing, catching packaging errors early.
my-project/
├── pyproject.toml
├── my_package/
│ ├── __init__.py
│ └── core.py
└── tests/
Acceptable for internal tools and single-organ repos where distribution is not a concern.
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-package"
version = "0.1.0"
description = "A concise description"
requires-python = ">=3.11"
license = "MIT"
dependencies = [
"httpx>=0.27",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0",
"ruff>=0.5",
"mypy>=1.10",
]
| Backend | When to Use |
|---|---|
| hatchling | Default choice. Fast, minimal config, good monorepo support |
| setuptools | Legacy projects, C extensions, complex build needs |
| flit | Pure Python, minimal config, simple projects |
| poetry-core | When using Poetry for dependency management |
Organize optional dependencies by use case:
[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff>=0.5", "mypy>=1.10"]
docs = ["sphinx>=7.0", "myst-parser"]
dashboard = ["fastapi>=0.110", "uvicorn"]
metrics = ["prometheus-client"]
Install specific groups: pip install -e ".[dev,dashboard]"
[project.scripts]
my-cli = "my_package.cli:main"
[project.entry-points."my_app.plugins"]
csv = "my_package.plugins.csv:CsvPlugin"
json = "my_package.plugins.json:JsonPlugin"
# In pyproject.toml
[project]
dynamic = ["version"]
[tool.hatch.version]
path = "src/my_package/__init__.py"
# In __init__.py
__version__ = "0.1.0"
For infrastructure packages where semantic versioning adds little value:
__version__ = "2026.03.1" # YYYY.MM.patch
| Context | Strategy | Tool |
|---|---|---|
| Library | Loose bounds (>=1.0,<2.0) | pyproject.toml |
| Application | Exact pins | pip-compile / uv lock |
| CI | Lockfile | uv.lock / requirements.txt |
# Using uv (recommended)
uv pip compile pyproject.toml -o requirements.txt
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt
# Using pip-tools
pip-compile pyproject.toml -o requirements.txt
# Standard editable install
pip install -e .
# With dev dependencies
pip install -e ".[dev]"
# In a fresh venv
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]
[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
pythonpath = ["."]
[tool.mypy]
strict = true
python_version = "3.11"
# Build
python -m build
# Upload (use trusted publishing when possible)
python -m twine upload dist/*
- uses: pypa/gh-action-pypi-publish@release/v1
with:
password: ${{ secrets.PYPI_API_TOKEN }}
For multi-repo packages sharing a namespace:
# Repo A
src/organvm/engine/__init__.py
# Repo B
src/organvm/dashboard/__init__.py
Use implicit namespace packages (no __init__.py at namespace level).
dependencies = [
"tomli>=2.0; python_version < '3.11'",
"typing-extensions>=4.0; python_version < '3.12'",
]
[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]
[tool.hatch.build.targets.wheel.force-include]
"assets" = "my_package/assets"
npx claudepluginhub a-organvm/a-i--skills --plugin document-skillsProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.