pyproject.toml

# cspell: ignore FURB xunit
#:tombi schema.strict = false

[project]
name = "ansible-lint"
description = "Checks playbooks for practices and behavior that could potentially be improved"
readme = "README.md"
# https://peps.python.org/pep-0621/#readme
requires-python = ">=3.10"
license = "GPL-3.0-or-later"
authors = [{ "name" = "Will Thames", "email" = "will@thames.id.au" }]
maintainers = [{ "name" = "Ansible by Red Hat", "email" = "info@ansible.com" }]
keywords = ["ansible", "lint"]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Environment :: Console",
  "Intended Audience :: Developers",
  "Intended Audience :: Information Technology",
  "Intended Audience :: System Administrators",
  "Operating System :: MacOS",
  "Operating System :: POSIX",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3 :: Only",
  "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",
  "Topic :: Software Development :: Quality Assurance",
  "Topic :: Software Development :: Testing",
  "Topic :: System :: Systems Administration",
  "Topic :: Utilities",
]
dependencies = [
  "ansible-compat>=26.3.0",
  "ansible-core>=2.16.14",
  "black>=24.3.0",
  "cffi>=1.15.1",  # indirect dependency of ruamel-yaml
  "cryptography>=37",
  "distro>=1.9.0",
  "filelock>=3.8.2",
  "jsonschema>=4.10.0",
  "packaging>=22.0",
  "pathspec>=1.0.3,<1.1.0",
  "pyyaml>=6.0.1 ; python_version < '3.14'",
  "pyyaml>=6.0.1 ; python_version >= '3.14'",  # py314 support
  "referencing>=0.36.2",
  "ruamel-yaml>=0.18.11",
  "ruamel-yaml-clib>=0.2.12 ; python_version < '3.14'",
  "subprocess-tee>=0.4.1",
  "wcmatch>=8.1.2 ; python_version < '3.12'",
  "wcmatch>=8.5.0 ; python_version >= '3.12'",
  "yamllint>=1.38.0",
]
dynamic = ["version"]

[project.urls]
changelog = "https://github.com/ansible/ansible-lint/releases"
documentation = "https://docs.ansible.com/projects/lint/"
homepage = "https://github.com/ansible/ansible-lint"
repository = "https://github.com/ansible/ansible-lint"

[project.scripts]
ansible-lint = "ansiblelint.__main__:_run_cli_entrypoint"

[dependency-groups]
dev = [
  "ansible-creator>=25.8.0",  # indirect dependency of ipython
  "black>=25.1.0",  # indirect dependency of ipython
  "coverage-enable-subprocess>=1.0",  # indirect dependency
  "coverage[toml]>=7.2.0",
  "decorator>=5.1.1",
  "ipdb>=0.13.13",
  "ipython>=8.37.0",
  "jmespath>=1.0.1",
  "license-expression>=30.3.0",
  "matplotlib-inline>=0.1.6",
  "mypy>=1.17.1",
  "netaddr>=1.3.0",
  "pip>=25.2",
  "psutil>=7.0.0",
  "pyright>=1.1.408",
  "pyrsistent>=0.20.0",
  "pytest>=9",
  "pytest-instafail>=0.5.0",
  "pytest-mock>=3.15.0",
  "pytest-xdist[psutil]>=2.1.0",  # do not add setproctitle here due to build issues
  "pyyaml>=6.0.1",
  "ruamel-yaml>=0.18.11",
  "ruamel-yaml-clib>=0.2.12 ; python_full_version < '3.14'",
  "tombi>=0.7.26",
  "tox>=4.24.2",
  "tox-extra>=2.1",
  "tox-uv>=1.25",
  "types-jsonschema>=4.25.1.20250822",
  "types-pyyaml>=6.0.12.20250822",
  "uv>=0.8",
]
docs = ["markdown-exec[ansi]>=1.11.0", "mkdocs-ansible>=25.5.0", "six>=1.16.0"]
lint = [
  "codespell>=2.4.2",
  "pip>=25.2",
  "prek>=0.3.1",
  "pytest>=9",
  "ruff>=0.14.10",
  "setuptools>=51.1.1",
  "tomli>=2.4.0",
]
pkg = [
  "build>=0.9",
  "pip>=25.2",
  "pipx>=1.7.1",
  "setuptools-scm>=9.2.0",
  "twine>=4.0.1",
]
schemas = ["check-jsonschema>=0.26.3"]

[build-system]
requires = [
  "setuptools_scm[toml] >= 7.0.5",  # required for "no-local-version" scheme
  "setuptools >= 65.3.0",
]
build-backend = "setuptools.build_meta"

[tool.codespell]
# indention is a typo in ruamel.yaml's API
ignore-words-list = ["indention", "assertIn"]
skip = [
  "./examples/playbooks/collections",
  "./test/examples/broken",
  "./test/schemas/node_modules",
  "./test/schemas/package-lock.json",
  "./test/schemas/test/.*",
  ".cache",
  ".eggs",
  ".git",
  ".mypy_cache",
  ".tox",
  ".venv",
  "_readthedocs",
  "build",
  "pip-wheel-metadata",
  "site",
  "uv.lock",
  "venv",
]

# Keep this default because xml/report do not know to use load it from config file:
# data_file = ".coverage"
[tool.coverage.paths]
source = ["src", ".tox/*/site-packages"]

[tool.coverage.report]
exclude_also = ["pragma: no cover", "if TYPE_CHECKING:"]
# Increase it just so it would pass on any single-python run
fail_under = 92
# During development we might remove code (files) with coverage data, and we dont want to fail:
ignore_errors = true
omit = ["test/*"]
partial_branches = ["pragma: no cover", "if TYPE_CHECKING:"]
show_missing = true
skip_covered = true
skip_empty = true

[tool.coverage.run]
# branch is more reliable than lines, protects against false positives
branch = true
concurrency = ["multiprocessing", "thread"]
parallel = true
relative_files = true
source = ["src"]

[tool.mypy]
check_untyped_defs = true
color_output = true
disallow_any_generics = true
disallow_any_unimported = true
disallow_untyped_calls = true
disallow_untyped_defs = true
error_summary = true
# site-packages is here to help vscode mypy integration getting confused
exclude = "(.config|test/local-content|site-packages|~/.pyenv|examples|plugins/modules).*"
exclude_gitignore = true
# https://github.com/python/mypy/issues/12664
follow_untyped_imports = true
incremental = false
no_implicit_optional = true
python_version = "3.12"
show_error_code_links = true
strict = true
warn_redundant_casts = true
warn_return_any = true
warn_unused_configs = true

[[tool.mypy.overrides]]
ignore_errors = true
ignore_missing_imports = true
module = [
  "ansible.parsing.yaml.constructor",
  "ruamel.yaml",
]

[[tool.mypy.overrides]]
implicit_reexport = true
module = ["ansible.*", "yamllint.*"]

[tool.pyright]
exclude = [
  ".ansible",
  ".cache",
  ".config",
  ".direnv",
  ".eggs",
  ".tox",
  ".venv",
  "ansible_collections",
  "build",
  "dist",
  "site",
  "venv",
  "examples/playbooks/collections",
]
include = ["src"]
# https://github.com/microsoft/pyright/blob/main/docs/configuration.md#sample-pyprojecttoml-file
# pythonVersion = "3.10"
# reportMissingImports = false
# https://github.com/microsoft/pyright/issues/9494
reportPossiblyUnboundVariable = false
# Introduced in v1.1.398 but already covered by ruff
reportPrivateImportUsage = false

# spell-checker:ignore filterwarnings norecursedirs optionflags
[tool.pytest]
# do not add options here as this will likely break either console runs or IDE
# integration like vscode or pycharm
addopts = ["--durations=10", "--failed-first", "-p no:pytest_cov"]
doctest_optionflags = ["ALLOW_UNICODE", "ELLIPSIS"]
filterwarnings = [
  # We raise one non critical warning from our own conftest.py:
  "always::pytest.PytestWarning",
  "error",
  # py312 ansible-core
  # https://github.com/ansible/ansible/issues/81906
  "ignore:'importlib.abc.TraversableResources' is deprecated and slated for removal in Python 3.14:DeprecationWarning",
  # https://github.com/ansible/ansible/pull/80968
  "ignore:Attribute s is deprecated and will be removed in Python 3.14; use value instead:DeprecationWarning",
]
junit_family = "xunit2"
markers = ["libyaml: tests that will pass only with pyyaml libyaml is present."]
minversion = "9.0"  # toml config changes
# https://code.visualstudio.com/docs/python/testing
# coverage is re-enabled in `tox.ini`. That approach is safer than
# `--no-cov` which prevents activation from tox.ini and which also fails
# when plugin is effectively missing.
norecursedirs = [
  "*.egg",
  ".cache",
  ".config",
  ".eggs",
  ".eggs",
  ".git",
  ".github",
  ".mypy_cache",
  ".projects",
  ".tox",
  "__pycache__",
  "ansible_collections",
  "build",
  "collections",
  "dist",
  "docs",
  "examples",
  "plugins",
  "site",
  "src/ansible_lint.egg-info",
  "test/schemas",
]
python_files = [
  # Ref: https://docs.pytest.org/en/latest/reference.html#confval-python_files
  # Needed to discover legacy nose test modules:
  "Test*.py",
  # Needed to discover embedded Rule tests
  "rules/*.py",
  "test_*.py",
]
# Using --pyargs instead of testpath as we embed some tests
# See: https://github.com/pytest-dev/pytest/issues/6451#issuecomment-687043537
# testpaths =
strict_xfail = true

[tool.ruff]
cache-dir = "./.cache/.ruff"
exclude = [".config"]
fix = true
# Same as Black.
line-length = 88
preview = true
target-version = "py310"

[tool.ruff.lint]
ignore = [
  "COM812",  # conflicts with ISC001 on format
  "CPY001",  # missing-copyright-notice
  "D203",  # incompatible with D211
  "D213",  # incompatible with D212
  "E501",  # we use black
  "ERA001",  # auto-removal of commented out code affects development and vscode integration
  "INP001",  # "is part of an implicit namespace package", all false positives
  "ISC001",  # conflicts with COM812 on format
  "PLW2901",  # PLW2901: Redefined loop variable
  "RET504",  # Unnecessary variable assignment before `return` statement
  # temporary disabled until we fix them:
  "ANN",
  "ARG002",  # Unused method argument (currently in too many places)
  "D102",  # Missing docstring in public method (currently in too many places)
  "FBT001",
  "FBT003",
  "FURB189",  # Subclassing `dict` can be error prone, use `collections.UserDict` instead
  "PD011",  # We are not using pandas, any .values attributes are unrelated
  "PERF203",
  "PLR",
  "PLW0603",  # global lock file in cache dir
  "RUF012",  # Mutable class attributes should be annotated with `typing.ClassVar`
  "RUF045",  # Assignment without annotation found in dataclass body
  # part of preview rules:
  "B909",  # raise-missing-from
  "DOC201",  # docstring-missing-returns
  "DOC402",  # docstring-missing-summary
  "DOC501",  # docstring-missing-exception
  "FURB101",
  "FURB103",
  "FURB110",
  "FURB113",
  "FURB118",
  "PLC0207",  # maxsplit with [-1] preview rule
  "PLC0415",
  "PLC2701",
  "PLW1641",
  "RUF067",
  "S404",
]
select = ["ALL"]

[tool.ruff.lint.flake8-pytest-style]
parametrize-values-type = "tuple"

[tool.ruff.lint.isort]
known-first-party = ["src"]

[tool.ruff.lint.mccabe]
# Implicit 10 is too low for our codebase, even black uses 18 as default.
max-complexity = 20

[tool.ruff.lint.per-file-ignores]
"src/ansiblelint/rules/*.py" = ["S"]
"src/ansiblelint/testing/*.py" = ["S"]
# Temporary disabled until we fix them:
"src/ansiblelint/{utils,file_utils,runner,loaders,constants,config,cli,_mockings}.py" = [
  "PTH",
]
"test/**/*.py" = ["DOC201", "DOC501", "PLC2701", "S"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.setuptools_scm]
# To prevent accidental pick of mobile version tags such 'v6'
git_describe_command = [
  "git",
  "describe",
  "--dirty",
  "--long",
  "--tags",
  "--match",
  "v*.*",
]
local_scheme = "no-local-version"
tag_regex = "^(?P<prefix>v)?(?P<version>\\d+[^\\+]*)(?P<suffix>.*)?$"
version_file = "src/ansiblelint/_version.py"

[tool.tomlsort]
in_place = true
sort_inline_tables = true
sort_table_keys = true

[tool.tox]
env_list = [
  "py",
  "devel",
  "lint",
  "pkg",
  "hook",
  "docs",
  "schemas",
  "lower",
  "eco",
]
requires = [
  "tox>=4.47.3",
  "tox-extra>=2.2",
  "tox-uv>=1.32.0",
]
skip_missing_interpreters = false

[tool.tox.env.clean]
commands = [
  "find . -type d \\( -name __pycache__ -o -name .mypy_cache \\) -delete",
  "find . -type f \\( -name '*.py[co]' -o -name \".coverage*\" -o -name coverage.xml \\) -delete",
]
commands_post = []
commands_pre = []
description = "Remove temporary files"
skip_install = true

[tool.tox.env.deps]
commands = [
  [
    "prek",
    "run",
    "--all-files",
    "--show-diff-on-failure",
    "--hook-stage",
    "manual",
    "deps",
  ],
  ["prek", "autoupdate"],
  ["sh", "-c", "cd test/schemas && npm run deps"],
  ["tox", "-e", "lint"],
]
commands_pre = []
description = "Bump all test dependencies"
dependency_groups = ["lint"]
env_dir = "{work_dir}/lint"
skip_install = true

[tool.tox.env.devel]
dependency_groups = ["dev"]
deps = [
  "ansible-compat @ git+https://github.com/ansible/ansible-compat.git",
  "ansible-core @ git+https://github.com/ansible/ansible.git",
]
description = "Run the tests with newest dependencies (no lock and allowing prereleases)"
runner = "uv-venv-runner"
uv_sync_flags = ["--upgrade", "--prerelease=allow"]
uv_sync_locked = false

[tool.tox.env.docs]
commands = [
  [
    "mkdocs",
    { default = ["build", "--strict", "--site-dir=_readthedocs/html/"], extend = true, replace = "posargs" },
  ],
]
commands_post = []
commands_pre = []
dependency_groups = ["docs"]
description = "Builds docs"
skip_install = false
set_env.DYLD_FALLBACK_LIBRARY_PATH = "/opt/homebrew/lib:{env:LD_LIBRARY_PATH}"
set_env.NO_COLOR = "1"
set_env.TERM = "dump"
set_env.NO_MKDOCS_2_WARNING = "1"

[tool.tox.env.eco]
commands = [
  ["sh", "-c", "tools/test-eco.sh"],
]
commands_post = []
commands_pre = []
description = "Perform ecosystem impact (downstream testing) https://github.com/ansible/ansible-lint/discussions/1403"

[tool.tox.env.hook]
commands = [["{tox_root}/tools/test-hook.sh"]]
commands_post = []
commands_pre = []
dependency_groups = ["lint"]
description = "Validate prek hook definition"

[tool.tox.env.lint]
commands = [["prek", "run", "--all-files", "--show-diff-on-failure"]]
commands_post = []
commands_pre = []
dependency_groups = ["lint"]
description = "Run all linters"
skip_install = true

[tool.tox.env.lower]
dependency_groups = ["dev"]
description = "Install using lowest constraints possible."
runner = "uv-venv-runner"
uv_resolution = "lowest"

[tool.tox.env.pkg]
commands = [
  ["rm", "-rf", "{tox_root}/dist/"],
  [
    "python",
    "-m",
    "build",
    "--outdir",
    "{tox_root}/dist/",
    "{tox_root}",
  ],
  ["bash", "-c", "python -m twine check --strict {tox_root}/dist/*"],
  ["bash", "./tools/test-pkg.sh"],
]
commands_post = []
commands_pre = []
dependency_groups = ["pkg"]
description = """
Build package, verify metadata, install package and assert behavior when ansible is missing.
"""
skip_install = true

[tool.tox.env.py310-lower]
dependency_groups = ["dev"]
description = "Install using lowest constraints possible."
runner = "uv-venv-runner"
uv_resolution = "lowest"

[tool.tox.env.py312-devel]
dependency_groups = ["dev"]
deps = [
  "ansible-compat @ git+https://github.com/ansible/ansible-compat.git  # GPLv3+",
  "ansible-core @ git+https://github.com/ansible/ansible.git  # GPLv3+",
]
description = "Run the tests with newest dependencies (no lock and allowing prereleases)"
runner = "uv-venv-runner"
uv_sync_flags = ["--upgrade", "--prerelease=allow"]
uv_sync_locked = false

[tool.tox.env.py312-lower]
dependency_groups = ["dev"]
description = "Install using lowest constraints possible."
runner = "uv-venv-runner"
uv_resolution = "lowest"

[tool.tox.env.py313-devel]
dependency_groups = ["dev"]
deps = [
  "ansible-compat @ git+https://github.com/ansible/ansible-compat.git  # GPLv3+",
  "ansible-core @ git+https://github.com/ansible/ansible.git  # GPLv3+",
]
description = "Run the tests with newest dependencies (no lock and allowing prereleases)"
runner = "uv-venv-runner"
uv_sync_flags = ["--upgrade", "--prerelease=allow"]
uv_sync_locked = false

[tool.tox.env.py314-devel]
dependency_groups = ["dev"]
deps = [
  "ansible-compat @ git+https://github.com/ansible/ansible-compat.git",
  "ansible-core @ git+https://github.com/ansible/ansible.git",
]
description = "Run the tests with newest dependencies (no lock and allowing prereleases)"
runner = "uv-venv-runner"
uv_sync_flags = ["--upgrade", "--prerelease=allow"]
uv_sync_locked = false

[tool.tox.env.redirects]
commands = [
  [
    "rtd",
    "projects",
    "ansible-lint",
    "redirects",
    "sync",
    "-f",
    "docs/redirects.yml",
    "--wet-run",
  ],
]
commands_post = []
commands_pre = []
deps = ["readthedocs-cli"]
description = "Update documentation redirections for readthedocs"

[tool.tox.env.schemas]
change_dir = "test/schemas"
commands = [["npm", "test"]]
commands_pre = [["check-jsonschema", "--version"], ["npm", "install"]]
dependency_groups = ["schemas"]
description = "Rebuild and test JSON Schemas"
skip_install = true

[tool.tox.env_run_base]
allowlist_externals = [
  "bash",
  "find",
  "git",
  "npm",
  "pwd",
  "rm",
  "sh",
  "tox",
  "{tox_root}/tools/report-coverage",
  "{tox_root}/tools/test-hook.sh",
  "{work_dir}/.pipx/bin/ansible-lint",
]
commands = [
  [
    "python",
    "-c",
    "import pathlib; pathlib.Path(\"{env_site_packages_dir}/cov.pth\").write_text(\"import coverage; coverage.process_startup()\")"
  ],
  [
    "coverage",
    "run",
    "-m",
    "pytest",
    { default = [
      "-ra",
      "--showlocals",
      "--doctest-modules",
      "--durations=10",
      "--junitxml=./junit.xml"
    ], extend = true, replace = "posargs" }
  ],
  ["coverage", "combine", "-q"],
  ["coverage", "xml", "-o", "{env_dir}/coverage.xml", "--fail-under=0"],
  ["coverage", "lcov", "-q", "--fail-under=0"],
  ["coverage", "report"]
]
commands_pre = [
  ["coverage", "erase"],
  ["bash", "./tools/install-reqs.sh"],
  ["ansible", "--version"],
]
description = """Run the tests: py{py_dot_ver}"""
package = "editable"
pass_env = [
  "CI",
  "CURL_CA_BUNDLE",
  "FORCE_COLOR",
  "HOME",
  "LANG",
  "LC_*",
  "NO_COLOR",
  "PRE_COMMIT_HOME",
  "PYTEST_*",
  "PYTHON*",
  "PYTHONBREAKPOINT",
  "PYTHONIOENCODING",
  "PYTHONPYCACHEPREFIX",
  "PY_COLORS",
  "REQUESTS_CA_BUNDLE",
  "RTD_TOKEN",
  "SETUPTOOLS_SCM_DEBUG",
  "SSH_AUTH_SOCK",
  "SSL_CERT_FILE",
  "UV_*",
]
runner = "uv-venv-lock-runner"

[tool.tox.env_run_base.set_env]
COVERAGE_COMBINED = "{env_dir}/.coverage"
COVERAGE_FILE = "{env:COVERAGE_FILE:{env_dir}/.coverage.{env_name}}"
COVERAGE_PROCESS_START = "{tox_root}/pyproject.toml"
FORCE_COLOR = "1"
PIP_DISABLE_PIP_VERSION_CHECK = "1"
PRE_COMMIT_COLOR = "always"

[tool.uv]
package = true
default-groups = "all"

[tool.vulture]
exclude = [
  ".eggs",
  ".tox",
  "build",
  "collections",
  "examples",
  "plugins",
  "test/local-content",
  "venv",
  "src/ansiblelint/_version.py",
]
ignore_names = [
  "_ANSIBLE_ARGS",
  "__line__",
  "fixture_*",
  "pytest_addoption",
  "pytest_collection_modifyitems",
  "pytest_configure",
  "side_effect",
  "test_*",
]
paths = ["src", "test", ".config/vulture_whitelist.py"]