pyproject.toml

[project]
name            = "poethepoet"
version         = "0.48.0"
description     = "A task runner that works well with poetry and uv."
authors         = [{ name = "Nat Noordanus", email = "n@noordan.us" }]
requires-python = ">=3.10"
readme          = "README.md"
license         = "MIT"
keywords        = ["automation", "tasks", "task-runner", "plugin", "poetry", "poe"]
classifiers     = [
  "Development Status :: 5 - Production/Stable",
  "Environment :: Console",
  "Intended Audience :: Developers",
  "Operating System :: OS Independent",
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Programming Language :: Python :: 3 :: Only",
  "Topic :: Software Development :: Build Tools",
  "Topic :: Software Development :: Libraries",
  "Topic :: Software Development :: Quality Assurance",
  "Topic :: Software Development :: Testing"
]

dependencies = [
  "pastel (>=0.2.1,<0.3.0)",
  "tomli  (>=1.3.0) ; python_version < '3.11'",
  "pyyaml (>=6.0.3,<7.0)"
]

[project.urls]
Homepage      = "https://poethepoet.natn.io/"
Documentation = "https://poethepoet.natn.io/"
Repository    = "https://github.com/nat-n/poethepoet"
Issues        = "https://github.com/nat-n/poethepoet/issues"
Releases      = "https://github.com/nat-n/poethepoet/releases"

[project.optional-dependencies]
poetry_plugin = ["poetry (>=1.2.0,<3.0.0) ; python_version < '4.0'"]

[project.entry-points."poetry.application.plugin"]
poethepoet = "poethepoet.plugin:PoetryPlugin"

[project.scripts]
poe = "poethepoet:main"


[tool.poetry.group.ci.dependencies]
black                = "^25.11.0"
mypy                 = "^1.18.2"
rstcheck             = { version = "^6.2.4", python = "<4" }
ruff                 = "^0.14.5"
types-pyyaml         = "^6.0.12.20250915"

[tool.poetry.group.test.dependencies]
jsonschema           = "^4.0"
poe_test_helpers     = { path = "./tests/fixtures/packages/poe_test_helpers" }
pytest               = "^9.0.1"
pytest-asyncio       = "^1.3.0"
pytest-cov           = "^7.0.0"
pytest-rerunfailures = "^16.1"
virtualenv           = "^20.35.4"

[tool.poetry.group.docs.dependencies]
furo                = "^2023.3.27"
livereload          = "^2.6.3"
sphinx              = "^7.4.7"
sphinx-copybutton   = "^0.5.1"
sphinxext-opengraph = "^0.9.0"

[tool.poe.tasks]
_clean_docs.script = "shutil:rmtree('docs/_build', ignore_errors=1)"

[tool.poe.tasks.format]
help     = "Run all formatting tools on the code base"
sequence = ["format-ruff", "format-black"]

[tool.poe.tasks.format-ruff]
help = "Run ruff fixer on code base"
cmd  = "ruff check . --fix-only"

[tool.poe.tasks.format-black]
help = "Run black on the code base"
cmd  = "black ."

[tool.poe.tasks.docs]
help = "Build the docs using Sphinx"
cmd  = "sphinx-build docs docs/_build"
deps = ["_clean_docs"]

[tool.poe.tasks.docs-serve]
help   = "Serves the docs locally with livereload"
script = "docs:serve"
cwd    = "./docs"
deps   = ["docs"]

[tool.poe.tasks.docs-check]
help = "Validate rst syntax in the docs"
sequence = [
  { cmd  = "rstcheck -r docs --ignore-roles bash,toml,sh,python --ignore-substitutions V --ignore-directives autofunction,include" },
  "docs -b linkcheck"
]

[tool.poe.tasks.clean]
help   = "Remove generated files"
script = """
  poethepoet.scripts:rm(
    ".coverage",
    ".ruff_cache",
    ".mypy_cache",
    ".pytest_cache",
    "./**/__pycache__",
    "dist",
    "htmlcov",
    "./docs/_build",
    "./tests/fixtures/**/.venv",
    "./tests/fixtures/simple_project/venv",
    "./tests/fixtures/venv_project/myvenv",
    "./tests/fixtures/venv_project/my_other_venv",
    "./tests/temp",
    verbosity=environ.get('POE_VERBOSITY'),
    dry_run=_dry_run
  )
"""

[tool.poe.tasks.test]
help = "Run unit and feature tests"
cmd  = "pytest -m 'not schema'"

[tool.poe.tasks.test-quick]
help = "Run unit and feature tests, excluding slow ones"
cmd  = "pytest -m 'not (slow or flaky or schema)'"

[tool.poe.tasks.test-schema]
help = "Run the schema parity test suite"
cmd  = "pytest -m schema tests/schema/"

[tool.poe.tasks.types]
help = "Run the type checker"
cmd  = "mypy poethepoet --ignore-missing-imports"

[tool.poe.tasks.lint]
help = "Run linting tools on the code base"
cmd  = "ruff check ."

[tool.poe.tasks.style]
help = "Validate black code style"
cmd  = "black . --check --diff"

[tool.poe.tasks.schema-build]
help     = "Regenerate partial-poe.json from PoeOptions definitions"
args     = [{ name = "_output", positional = true, default = "docs/_static/partial-poe.json", help = "Where to write the schema file" }]
sequence = [
  { script = "poethepoet.schema:write_schema(_output)" },
  "_schema-format ${_output}",
]

[tool.poe.tasks._schema-format]
help  = "Apply SchemaStore-compatible prettier formatting to a generated JSON Schema"
args  = [{ name = "schema_path", positional = true, default = "docs/_static/partial-poe.json", help = "Path of the schema file to format in place" }]
shell = '''
npx --yes \
  --package "prettier@${PRETTIER_VERSION}" \
  --package "prettier-plugin-sort-json@${SORT_PLUGIN_VERSION}" \
  -- bash -c 'prettier \
    --plugin "$(dirname "$(dirname "$(which prettier)")")/prettier-plugin-sort-json/dist/index.js" \
    --ignore-path /dev/null \
    --object-wrap collapse \
    --json-recursive-sort \
    --json-sort-order "$SCHEMA_SORT_ORDER" \
    --write "'"${schema_path}"'"'
'''
[tool.poe.tasks._schema-format.env]
PRETTIER_VERSION  = "3.8.3"
SORT_PLUGIN_VERSION = "4.2.0"
SCHEMA_SORT_ORDER = '{"$schema":null,"$id":null,"$comment":null,"$ref":null,"/^\\\\$.*/":null,"/^[^\\\\d+]/":"none","/^\\\\d+/":"none","if":null,"then":null,"else":null}'

# Regenerates the schema to a gitignored side-channel path and diffs it
# against the committed file. Doesn't touch the real partial-poe.json,
# so it can be safely run with uncommitted local changes.
[tool.poe.tasks.schema-check-drift]
help     = "Verify generated JSON Schema is up to date with PoeOptions"
env      = { _comparison_path = "docs/_static/partial-poe-comparison.json", GIT_PAGER = "cat" }
sequence = [
  "schema-build ${_comparison_path}",
  { cmd = "git diff --no-index docs/_static/partial-poe.json ${_comparison_path}" },
]

[tool.poe.tasks.check]
help     = "Run all checks on the code base"
sequence = ["docs-check", "style", "types", "lint", "schema-check-drift", "test", "test-schema"]

[tool.poe.tasks.install-poetry-plugin]
help = "Install or update this project as a plugin in poetry"
sequence = [
  { cmd = "poetry --no-plugins self remove poethepoet"},
  { cmd = "poetry self add \"${POE_ROOT}[poetry_plugin]\""}
]
ignore_fail = true

[tool.poe.tasks.bump-version]
help   = "Bump the package version across all source files before a release"
script = "bump_version:main(version)"
env.PYTHONPATH = "${POE_ROOT}/scripts"
args = [
  { name = "version", positional = true, help = "minor, tiny, or an explicit version string (e.g. 1.2.3)" },
]

[tool.poe.tasks.poe]
help   = "Execute poe from this repo (useful for testing)"
script = "poethepoet:main"

[tool.poe.tasks.zsh-harness]
help   = "Run zsh completion script through test harness for debugging"
script = "harness:task_zsh_harness(path)"
env.PYTHONPATH = "tests/completion"
args = [{name="path", positional = true, help = "Path to script to test, or - for stdin"}]

[tool.poe.tasks.bash-harness]
help   = "Run bash completion script through test harness for debugging"
script = "bash_harness:task_bash_harness(path)"
env.PYTHONPATH = "tests/completion"
args = [{name="path", positional = true, help = "Path to script to test, or - for stdin"}]

[tool.poe.tasks.eval-skill]
help   = "Run poethepoet skill evals"
script = "run_evals:main(evals, replicas, no_baseline, model, verbose)"
env.PYTHONPATH = "${POE_ROOT}/tests/skills"
args = [
  { name = "evals", options = ["-e", "--eval"], multiple = true, type = "integer", help = "Eval IDs to run (default: all)" },
  { name = "replicas", options = ["-r", "--replicas"], type = "integer", default = 1, help = "Number of runs per eval" },
  { name = "no_baseline", options = ["--no-baseline"], type = "boolean", help = "Skip without-skill baseline runs" },
  { name = "model", options = ["-m", "--model"], help = "Claude model to use" },
  { name = "verbose", options = ["-v", "--verbose"], type = "boolean", help = "Print per-expectation results with evidence" },
]

[tool.rstcheck]
ignore_messages  = [
  "Unknown directive type \"autoclass\"",
  "Hyperlink target \"shell-completion\" is not referenced.",
  "Hyperlink target \"envfile-option\" is not referenced.",
  "Hyperlink target \"ref-env-vars\" is not referenced.",
  "Hyperlink target \"sequence-composition\" is not referenced.",
  "Hyperlink target \"graph-composition\" is not referenced.",
  "Hyperlink target \"forwarding-free-arguments-via-poe-extra-args\" is not referenced.",
  "Hyperlink target \"parameter-expansion-operators\" is not referenced.",
  "No directive entry for \"autoclass\" in module \"docutils.parsers.rst.languages.en\""
]
ignore_directives = [
  "include"
]


[tool.coverage.report]
omit = ["**/site-packages/**", "poethepoet/completion/*", "poethepoet/plugin.py"]


[tool.pytest.ini_options]
markers = [
  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
  "schema: schema validation tests (slow; require jsonschema; auto-applied to parity tests in tests/schema/)",
]


[tool.ruff.lint]
select  = [
  "E",     # error
  "F",     # pyflakes
  "I",     # isort
  "W",     # warning
  "N",     # pep8-naming
  "B",     # flake8-bugbear
  "UP",    # pyupgrade
  "ERA",   # eradicate
  "YTT",   # flake8-2020
  "ASYNC", # flake8-async
  "C4",    # flake8-comprehensions
  "T10",   # flake8-debugger
  "G",     # flake8-logging-format
  "PIE",   # flake8-pie
  "PYI",   # flake8-pyi
  "PT",    # flake8-pytest-style
  "Q",     # flake8-quotes
  "SIM",   # flake8-simplify
  "TCH",   # flake8-type-checking
  "PTH",   # flake8-use-pathlib
  "PGH",   # pygrep-hooks
  "PERF",  # perflint
  "RUF",   # ruff-specific rules
]
ignore  = [
  "C408",   # unnecessary-collection-call
  "PT015",  # pytest-assert-always-false
  "SIM118", # in-dict-keys
  "PTH109", # os-getcwd
  "PTH123", # builtin-open
  "RUF012", # mutable-class-default
  "B904",   # raise-without-from-inside-except
]
fixable = ["E", "F", "I"]

[tool.uv.workspace]
members = ["tests/fixtures/task_package"]


[build-system]
requires      = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"