pyproject-toml

What this skill does

# pyproject.toml Configuration Skill

Master pyproject.toml for modern Python project configuration, build systems, tool settings, and dependency management.

## When to Use This Skill

Use pyproject.toml configuration when you need:
- **Project metadata** - Name, version, description, authors
- **Dependency management** - Core and optional dependencies
- **Build configuration** - Setuptools, hatch, flit, or poetry
- **Tool configuration** - pytest, ruff, mypy, black, isort
- **Entry points** - CLI scripts and plugins
- **Package discovery** - Source directory configuration

**Avoid when:**
- Legacy projects requiring setup.py (rare, migrate instead)
- Non-Python projects

## Core Structure

### Complete pyproject.toml Template

```toml
# ============================================================
# BUILD SYSTEM
# ============================================================
[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

# ============================================================
# PROJECT METADATA
# ============================================================
[project]
name = "my-project"
version = "0.1.0"
description = "A comprehensive Python project template"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "[email protected]"}
]
maintainers = [
    {name = "Your Name", email = "[email protected]"}
]
keywords = ["python", "template", "project"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

# Core dependencies
dependencies = [
    "pandas>=2.0.0",
    "numpy>=1.24.0",
    "pyyaml>=6.0",
    "click>=8.0.0",
]

# ============================================================
# OPTIONAL DEPENDENCIES
# ============================================================
[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
    "ruff>=0.1.0",
    "mypy>=1.4.0",
    "black>=23.0.0",
    "isort>=5.12.0",
]
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.0.0",
]
viz = [
    "plotly>=5.15.0",
    "matplotlib>=3.7.0",
]
all = [
    "my-project[dev,docs,viz]",
]

# ============================================================
# ENTRY POINTS (CLI & PLUGINS)
# ============================================================
[project.scripts]
my-cli = "my_project.cli:main"
my-tool = "my_project.tools:run"

[project.gui-scripts]
my-gui = "my_project.gui:main"

[project.entry-points."my_project.plugins"]
plugin1 = "my_project.plugins.plugin1:Plugin1"
plugin2 = "my_project.plugins.plugin2:Plugin2"

# ============================================================
# URLS
# ============================================================
[project.urls]
Homepage = "https://github.com/username/my-project"
Documentation = "https://my-project.readthedocs.io"
Repository = "https://github.com/username/my-project.git"
Issues = "https://github.com/username/my-project/issues"
Changelog = "https://github.com/username/my-project/blob/main/CHANGELOG.md"

# ============================================================
# PACKAGE DISCOVERY
# ============================================================
[tool.setuptools]
package-dir = {"" = "src"}
include-package-data = true

[tool.setuptools.packages.find]
where = ["src"]
include = ["my_project*"]
exclude = ["tests*"]

[tool.setuptools.package-data]
my_project = ["*.yaml", "*.json", "data/*"]

# ============================================================
# UV CONFIGURATION
# ============================================================
[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
    "ruff>=0.1.0",
    "mypy>=1.4.0",
]

# ============================================================
# PYTEST CONFIGURATION
# ============================================================
[tool.pytest.ini_options]
minversion = "7.0"
testpaths = ["tests"]
python_files = ["test_*.py", "*_test.py"]
python_functions = ["test_*"]
python_classes = ["Test*"]
addopts = [
    "-v",
    "--tb=short",
    "--strict-markers",
    "-ra",
]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "integration: marks tests as integration tests",
    "unit: marks tests as unit tests",
]
filterwarnings = [
    "ignore::DeprecationWarning",
    "ignore::PendingDeprecationWarning",
]

# ============================================================
# COVERAGE CONFIGURATION
# ============================================================
[tool.coverage.run]
source = ["src"]
branch = true
parallel = true
omit = [
    "*/tests/*",
    "*/__pycache__/*",
    "*/conftest.py",
]

[tool.coverage.paths]
source = ["src"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise NotImplementedError",
    "if TYPE_CHECKING:",
    "if __name__ == .__main__.:",
    "@abstractmethod",
]
show_missing = true
precision = 2
fail_under = 80

[tool.coverage.html]
directory = "htmlcov"

# ============================================================
# RUFF CONFIGURATION (Linting & Formatting)
# ============================================================
[tool.ruff]
target-version = "py310"
line-length = 88
indent-width = 4
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
    "*.egg-info",
]

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # Pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
    "ARG",    # flake8-unused-arguments
    "SIM",    # flake8-simplify
]
ignore = [
    "E501",   # line too long (handled by formatter)
    "B008",   # function call in default argument
    "B905",   # zip strict
]
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["ARG001", "S101"]
"__init__.py" = ["F401"]

[tool.ruff.lint.isort]
known-first-party = ["my_project"]
force-single-line = false
lines-after-imports = 2

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

# ============================================================
# MYPY CONFIGURATION
# ============================================================
[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
show_error_codes = true
show_column_numbers = true
pretty = true
exclude = [
    "tests/",
    "build/",
    "dist/",
]

[[tool.mypy.overrides]]
module = [
    "pandas.*",
    "numpy.*",
    "plotly.*",
    "yaml.*",
]
ignore_missing_imports = true

# ============================================================
# BLACK CONFIGURATION (if not using ruff format)
# ============================================================
[tool.black]
line-length = 88
target-version = ["py310", "py311", "py312"]
include = '\.pyi?$'
exclude = '''
/(
    \.git
    | \.venv
    | __pycache__
    | build
    | dist
)/
'''

# ============================================================
# ISORT CONFIGURATION (if not using ruff)
# ============================================================
[tool.isort]
profile = "black"
line_length = 88
known_first_party = ["my_project"]
skip = [".venv", "build", "dist"]
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true

# ====================================