pyproject.toml

[build-system]
build-backend = "uv_build"
requires = [ "uv-build>=0.9" ]

[project]
# Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
name = "click-extra"
version = "8.1.4.dev0"
description = "🌈 Drop-in replacement for Click to make user-friendly and colorful CLI"
readme = "readme.md"
keywords = [
  "ansi-colors",
  "ansi-escape-codes",
  "cli-framework",
  "click",
  "click-extension",
  "click-plugin",
  "cloup",
  "colorization",
  "config-file",
  "configuration-file",
  "hjson",
  "ini",
  "json5",
  "pygments",
  "pytest-plugin",
  "python-cli",
  "python-tabulate",
  "sphinx-extension",
  "tabulate",
  "toml-parser",
]
license = "GPL-2.0-or-later"
license-files = [ "license" ]
authors = [ { name = "Kevin Deldycke", email = "kevin@deldycke.com" } ]
# Python versions and their status: https://devguide.python.org/versions/
requires-python = ">=3.10"
classifiers = [
  # See: https://pypi.org/pypi?%3Aaction=list_classifiers
  "Development Status :: 5 - Production/Stable",
  "Environment :: Console",
  "Environment :: Plugins",
  "Framework :: Pytest",
  "Framework :: Sphinx",
  "Framework :: Sphinx :: Extension",
  "Framework :: Sphinx :: Theme",
  "Intended Audience :: Developers",
  "Operating System :: MacOS :: MacOS X",
  "Operating System :: Microsoft :: Windows",
  "Operating System :: POSIX :: BSD :: FreeBSD",
  "Operating System :: POSIX :: BSD :: NetBSD",
  "Operating System :: POSIX :: BSD :: OpenBSD",
  "Operating System :: POSIX :: Linux",
  "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",
  "Programming Language :: Python :: Implementation :: CPython",
  "Topic :: Documentation :: Sphinx",
  "Topic :: Software Development :: Libraries :: Python Modules",
  "Topic :: Software Development :: User Interfaces",
  "Topic :: System :: Logging",
  "Topic :: System :: Shells",
  "Topic :: Terminals",
  "Topic :: Text Processing :: Filters",
  "Topic :: Text Processing :: Markup :: HTML",
  "Topic :: Text Processing :: Markup :: Markdown",
  "Topic :: Text Processing :: Markup :: reStructuredText",
  "Topic :: Text Processing :: Markup :: XML",
  "Topic :: Utilities",
  "Typing :: Typed",
]
# Semantic versioning works in theory. In practice, it is hard to guarantee.
# That's why we rely on >= specifier instead of ~= to relax constraints. This gives more freedom to packagers to
# release hotfixes for security vulnerabilities in the future.
# See also discussion about upper limits at: https://iscinumpy.dev/post/bound-version-constraints/#tldr
# All minimal version choice are documented. Reasons to bump a minimal version are:
# - bug fixes,
# - security fixes,
# - new code path we depends on,
# - aligns minimal Python requirements to ours,
# - adds new explicit support Python version.
dependencies = [
  # boltons 20.0.0 added shrinkuser(); our config.py uses it for path display.
  "boltons>=20",
  # click-extra targets Click >= 8.3.1, carrying small compatibility shims for the
  # APIs that landed in Click 8.4.0 (see ExtraOption.handle_parse_result, the
  # conditional NoSuchCommand/get_pager_file imports, NoConfigOption's explicit
  # UNPROCESSED type, and HelpExtraFormatter.write_usage).
  "click>=8.3.1",
  # Cloup 3.0.7 fix issues with metavars: https://github.com/kdeldycke/click-extra/pull/1281
  "cloup>=3.0.7",
  # always_merger (recursive dict merge) available since deepmerge 1.0.1.
  "deepmerge>=1.0.1",
  # _recursive_update and _remove_blanks moved to extra_platforms._utils in 8.0.0.
  "extra-platforms>=8",
  # tabulate 0.9 is widely packaged; the `colon_grid` format added in 0.10 is
  # backported in table.py by aliasing it to `grid` when missing.
  "tabulate[widechars]>=0.9",
  # tomli 2.0 aligned API with stdlib tomllib; only installed on Python 3.10.
  "tomli>=2; python_version<'3.11'",
  # wcmatch 10.0 fix some inconsistencies in globbing and symlinks.
  "wcmatch>=10",
  # wcwidth (already pulled in by tabulate[widechars]) is used directly to size
  # the spinner-catalog preview by terminal cell width.
  "wcwidth>=0.2",
]

[project.entry-points]
# Make additional fixtures available to pytest.
# See: https://docs.pytest.org/en/latest/how-to/writing_plugins.html#making-your-plugin-installable-by-others
pytest11.click-extra = "click_extra.pytest"
# The name of the entrypoint value doesn’t really matter, Pygments extracts required metadata from the class definition.
# Source: https://pygments.org/docs/plugins/#defining-plugins-through-entrypoints
"pygments.filters".ansi-filter = "click_extra.pygments:AnsiFilter"
"pygments.formatters".ansi-html-formatter = "click_extra.pygments:AnsiHtmlFormatter"
"pygments.lexers".ansi-color = "click_extra.pygments:AnsiColorLexer"
"pygments.lexers".ansi-bash-session = "click_extra.pygments:AnsiBashSessionLexer"
"pygments.lexers".ansi-dylan-console = "click_extra.pygments:AnsiDylanConsoleLexer"
"pygments.lexers".ansi-elixir-console = "click_extra.pygments:AnsiElixirConsoleLexer"
"pygments.lexers".ansi-erlang-shell = "click_extra.pygments:AnsiErlangShellLexer"
"pygments.lexers".ansi-gap-console = "click_extra.pygments:AnsiGAPConsoleLexer"
"pygments.lexers".ansi-julia-console = "click_extra.pygments:AnsiJuliaConsoleLexer"
"pygments.lexers".ansi-matlab-session = "click_extra.pygments:AnsiMatlabSessionLexer"
"pygments.lexers".ansi-msdos-session = "click_extra.pygments:AnsiMSDOSSessionLexer"
"pygments.lexers".ansi-output = "click_extra.pygments:AnsiOutputLexer"
"pygments.lexers".ansi-postgres-console = "click_extra.pygments:AnsiPostgresConsoleLexer"
"pygments.lexers".ansi-power-shell-session = "click_extra.pygments:AnsiPowerShellSessionLexer"
"pygments.lexers".ansi-psysh-console = "click_extra.pygments:AnsiPsyshConsoleLexer"
"pygments.lexers".ansi-python-console = "click_extra.pygments:AnsiPythonConsoleLexer"
"pygments.lexers".ansi-r-console = "click_extra.pygments:AnsiRConsoleLexer"
"pygments.lexers".ansi-ruby-console = "click_extra.pygments:AnsiRubyConsoleLexer"
"pygments.lexers".ansi-sqlite-console = "click_extra.pygments:AnsiSqliteConsoleLexer"
"pygments.lexers".ansi-tcsh-session = "click_extra.pygments:AnsiTcshSessionLexer"
# MkDocs plugin for ANSI color rendering in code blocks.
"mkdocs.plugins".click-extra = "click_extra.mkdocs:AnsiColorPlugin"

[project.optional-dependencies]
all = [
  # Aggregate extra: pulls in every optional feature at once. Self-references the
  # package so the version pins stay defined once, in the extras below.
  "click-extra[carapace,hjson,json5,jsonc,mkdocs,pygments,pytest,sphinx,toml,xml,yaml]",
]
carapace = [
  # PyYAML serializes the Carapace completion spec (carapace.dump_carapace_spec).
  # Pinned like the yaml extra: < 6.0.2 fails to build on Python 3.14.
  "pyyaml>=6.0.3",
]
hjson = [
  # hjson.loads() and hjson.dumps() for Hjson config parsing and table rendering.
  "hjson>=3.1",
]
json5 = [
  # json5.loads() for JSON5 config parsing.
  "json5>=0.12.1",
]
jsonc = [
  # jsonc.loads() for JSONC config parsing.
  "json-with-comments>=1.2.10",
]
mkdocs = [
  # MkDocs 1.4.0 is the first version with the on_startup plugin event.
  "mkdocs>=1.4",
  # Pygments 2.14.0 is the first version with lexers.algebra.GAPConsoleLexer that is referenced in our code.
  "pygments>=2.14",
  # pymdown-extensions 10.0 is the first version with stable highlight extension API.
  "pymdown-extensions>=10",
]
pygments = [
  # Pygments 2.14.0 is the first version with lexers.algebra.GAPConsoleLexer that is referenced in our code.
  "pygments>=2.14",
]
pytest = [
  # pytest 9.0.0 is the first supporting native TOML configuration files.
  "pytest>=9",
]
sphinx = [
  # docutils 0.20 is the minimal version for Sphinx 8.0.0.
  "docutils>=0.20",
  # Pygments 2.14.0 is the first version with lexers.algebra.GAPConsoleLexer that is referenced in our code.
  "pygments>=2.14",
  # Sphinx 8.0.0 is the first version to drop Python 3.9, like us.
  "sphinx>=8",
]
toml = [
  # tomlkit.document(), tomlkit.dumps() for TOML config and table rendering.
  "tomlkit>=0.13",
]
xml = [
  # xmltodict.unparse() for XML table rendering; first major release.
  "xmltodict>=1",
]
yaml = [
  # PyYAML < 6.0.2 uses Cython extensions that fail to compile on Python 3.14,
  # and old releases lack requires-python metadata to prevent selection on 3.14.
  "pyyaml>=6.0.3",
]

[project.scripts]
click-extra = "click_extra.__main__:main"

[project.urls]
"Homepage" = "https://github.com/kdeldycke/click-extra"
"Download" = "https://github.com/kdeldycke/click-extra/releases/tag/v8.1.4.dev0"
"Changelog" = "https://github.com/kdeldycke/click-extra/blob/main/changelog.md"
"Issues" = "https://github.com/kdeldycke/click-extra/issues"
"Repository" = "https://github.com/kdeldycke/click-extra"
"Funding" = "https://github.com/sponsors/kdeldycke"

[dependency-groups]
test = [
  # backports.strenum 1.3.0 is required to support enum.StrEnum in Python 3.10.
  "backports-strenum>=1.3; python_version<'3.11'",
  # coverage 7.11.0 dropped Python 3.9, matching our requires-python >= 3.10.
  "coverage[toml]>=7.11",
  # Matches the runtime extra-platforms>=8 floor; the [pytest] extra adds fixtures.
  "extra-platforms[pytest]>=8",
  # jsonschema validates the generated Carapace spec against the vendored
  # carapace-spec schema in test_carapace; 4.18 added the 2020-12 dialect.
  "jsonschema>=4.18",
  # MkDocs 1.4.0 is the first version with the on_startup plugin event.
  "mkdocs>=1.4",
  # mkdocs-click 0.8.0 stabilized the _make_usage/_make_plain_options API.
  "mkdocs-click>=0.8",
  # myst-parser 4.0 added colon_fence extension for GitHub-style alert syntax.
  # Pinned to >=4 (not >=5) because myst-parser 5 requires Python 3.11+ and tests run on 3.10+.
  "myst-parser>=4",
  # pymdown-extensions 10.0 is the first version with stable highlight extension API.
  "pymdown-extensions>=10",
  # pytest 9.0.0 is the first supporting native TOML configuration files.
  "pytest>=9",
  # pytest-cov 4.0 stabilized the modern pytest plugin interface.
  "pytest-cov>=4",
  # pytest-github-actions-annotate-failures CI annotation interface is stable across 0.x.
  "pytest-github-actions-annotate-failures>=0.2",
  # pytest-httpserver 1.1 added ordered request handlers used in config URL tests.
  "pytest-httpserver>=1.1",
  # pytest-randomly 3.x introduced the current seed-management plugin interface.
  "pytest-randomly>=3",
  # requests is used only by the test suite to fetch fixtures and PyPI metadata
  # (test_pygments, test_pyproject); the runtime config-URL loader uses urllib.
  # 2.34 ships inline types, removing the need for the types-requests stub.
  "requests>=2.34",
  # Sphinx 8.0.0 is the first version to drop Python 3.9, like us.
  "sphinx>=8",
  # tomli 2.0 aligned API with stdlib tomllib; only installed on Python 3.10.
  "tomli>=2; python_version<'3.11'",
]
docs = [
  # Flask is used as a real-world example in docs {click:run} blocks.
  "flask>=3",
  # furo 2024.8.6+ supports Sphinx 8; pinned to recent CalVer release.
  "furo>=2025.9.25",
  # All optional config format dependencies are needed for {click:run} blocks in config.md.
  "hjson>=3.1",
  "json-with-comments>=1.2.10",
  "json5>=0.12.1",
  # MkDocs is needed for automodule/autoclasstree of click_extra.mkdocs.
  "mkdocs>=1.4",
  # myst-parser 5.1 ships the native "alert" syntax extension for GitHub-style
  # callouts, used by docs/conf.py's myst_enable_extensions.
  "myst-parser>=5.1",
  # Pygments is needed for automodule/autoclasstree of click_extra.pygments.
  "pygments>=2.14",
  # pymdown-extensions is needed by the mkdocs plugin module.
  "pymdown-extensions>=10",
  # pytest is needed for automodule/autoclasstree of click_extra.pytest.
  "pytest>=9",
  # PyYAML renders the Carapace spec in carapace.md {click:run} blocks.
  "pyyaml>=6.0.3",
  # Sphinx 8.0.0 is the first version to drop Python 3.9, like us.
  "sphinx>=8",
  # sphinx-autodoc-typehints 2.4.0 is the first version that is aligned to our Python >= 3.10 requirement.
  "sphinx-autodoc-typehints>=2.4",
  # sphinx-copybutton 0.5.2 stabilized the copy button behavior for code blocks.
  "sphinx-copybutton>=0.5.2",
  # sphinx-design 0.6 introduced the current directive syntax for cards, grids, and tabs.
  "sphinx-design>=0.6",
  # sphinx-issues 5.0 added support for GitHub issue linking in Sphinx 7+.
  "sphinx-issues>=5",
  # sphinxcontrib-mermaid 1.2.3 fixed mermaid_d3_zoom configuration support.
  "sphinxcontrib-mermaid>=1.2.3",
  # sphinxext-opengraph 0.13 stabilized OpenGraph metadata generation for Sphinx 8+.
  "sphinxext-opengraph>=0.13",
  "xmltodict>=1",
]
typing = [
  "types-boltons>=25.0.0.20250919",
  "types-docutils>=0.22.3.20251115",
  "types-jsonschema>=4.18",
  "types-pygments>=2.19.0.20251121",
  "types-pyyaml>=6.0.12.9",
  "types-tabulate>=0.9.0.2",
  "types-xmltodict>=1.0.1.20250920",
]

[tool.uv]
# We rely on recent Python features in some of our {click:run} directives.
dependency-groups.docs = { requires-python = ">= 3.14" }
# Cooldown period: 7-day buffer before using newly released packages.
# Relative dates are fine here because the Renovate lock-maintenance job
# (sync-uv-lock) reverts uv.lock when the only diff is timestamp noise.
exclude-newer = "1 week"
# Package is at root level, not in "./src/".
build-backend.module-root = ""
required-version = ">=0.11.23,<0.12"

[tool.nuitka]
# Bundle the package's data files (themes.toml) into the standalone binary.
# Nuitka's import analysis only follows `import` statements, so data files
# read at runtime through importlib.resources are invisible to it and must be
# listed explicitly. Without this, the onefile binary aborts at startup when
# click_extra.theme loads themes.toml. repomatic translates this key into the
# --include-package-data CLI flag.
include-package-data = "click_extra"

[tool.ruff]
preview = true
fix = true
unsafe-fixes = true
show-fixes = true
# Enable reformatting of code snippets in docstrings.
# https://docs.astral.sh/ruff/formatter/#docstring-formatting
format.docstring-code-format = true
# B008: Do not perform function call in argument defaults.
#   Click's API requires function calls in defaults (e.g. `_()` for i18n,
#   `EnumChoice()`, `Style()`, `ClickPath()`). This is intentional.
# D400: First line should end with a period.
#   Allows docstrings to end up with any punctuation, not just a period.
#   See: https://github.com/astral-sh/ruff/issues/1858#issuecomment-1382640623
# ERA001: Found commented-out code.
#   Do not remove commented code, as it might be used for documentation.
#   See: https://docs.astral.sh/ruff/rules/#eradicate-era
# LOG015: Root logger call.
#   Tests intentionally call root logger methods to verify capture behavior.
#   Utility functions also use root logger as a convenience.
lint.ignore = [ "B008", "D400", "ERA001", "LOG015" ]
lint.isort.combine-as-imports = true
# Allow rules to add `from __future__ import annotations` in cases where
# this would simplify a fix or enable a new diagnostic.
# https://docs.astral.sh/ruff/settings/#lint_future-annotations
lint.future-annotations = true

[tool.typos]
default.extend-identifiers = { Github = "GitHub", IOS = "iOS", Javascript = "JavaScript", MacOS = "macOS", PyPi = "PyPI", Typescript = "TypeScript" }
# Skip content between <!-- typos:off --> and <!-- typos:on --> markers.
# chalk.ist is a legitimate domain name; `ist` is its TLD, not a typo.
default.extend-ignore-re = [
  "(?s)<!-- typos:off -->.*?<!-- typos:on -->",
  "chalk\\.ist",
]
default.extend-ignore-identifiers-re = [
  # error: `valu` should be `value`
  #     ╭▸ ./tests/test_types.py:127:11
  #     │
  # 127 │         ("valuE", ("first-value", "second-value")),
  #     ╰╴          ━━━━
  "valuE",
  # error: `Nd` should be `And`
  #     ╭▸ ./tests/test_types.py:196:41
  #     │
  # 196 │         assert enum_choice.convert("SeCoNd-VaLuE", None, None) == MyEnum.SECOND_VALUE
  #     ╰╴                                        ━━
  "SeCoNd",
  # error: `Uper` should be `Super`, `Upper`
  #     ╭▸ ./tests/test_envvar.py:113:19
  #     │
  # 113 │                 "sUper",
  #     ╰╴                  ━━━━
  "sUper",
  # error: `Als` should be `Also`
  #     ╭▸ ./tests/test_envvar.py:179:11
  #     │
  # 179 │         "fAlsE": False,
  #     ╰╴          ━━━
  "fAlsE",
  # error: `nd` should be `and`
  #     ╭▸ ./tests/test_sphinx.py:262:29
  #     │
  # 262 │             + '<span class="nd">@command</span>\n'
  #     ╰╴                            ━━
  "nd",
  # error: `mey` should be `may`
  #     ╭▸ ./tests/test_colorize.py:890:22
  #     │
  # 890 │             "H\x1b[32mey\x1b[0m-xx-xxx-\x1b[32mhe\x1b[0mY-xXxXxxxxx-\x1b[32mhey\x1b[0m",
  #     ╰╴                     ━━━
  "mey",
  # error: `certifi` should be `certify`, `certifies`, `certified`
  #     ╭▸ ./docs/assets/dependencies.mmd:5:5
  #     │
  # 5   │     certifi["certifi\n2025.11.12"]
  #     ╰╴    ━━━━━━━
  "certifi",
  # error: `optoin` should be `option`
  #     ╭▸ ./docs/theme.md:112:54
  #     │
  # 112 │ ...all keyword arguments match a known field, so typos like `optoin=...` raise immediately.
  #     ╰╴                                                             ━━━━━━
  "optoin",
]

[tool.pytest]
# https://docs.pytest.org/en/latest/customize.html#pyproject-toml
markers = [
  "network: Tests that require network access (excluded with -m 'not network').",
  "once: Tests that only need to run once, not across the full CI matrix.",
]
addopts = [
  "--durations=10",
  # Import test modules via importlib instead of prepending their root dir to
  # sys.path. Avoids "import file mismatch" collection errors when an installed
  # copy of the package coexists with the source tree, as in distro builds.
  "--import-mode=importlib",
]
# Restrict collection to the test suite. Otherwise pytest descends into the
# click_extra package and imports test_suite.py (its basename matches the
# test_*.py glob), which fails in dual-copy builds where an installed copy
# shadows the source tree.
testpaths = [ "tests" ]
# Make sure tests that are expected to fail do not resurect and start working all of a sudden.
xfail_strict = true

[tool.coverage]
# https://coverage.readthedocs.io/en/latest/config.html
run.branch = true
run.source = [ "click_extra" ]
report.precision = 2

# Dogfood click-extra's own configuration: the test-suite subcommand reads its
# settings from this section (see tests.yaml's "Self-test the CLI" step).
[tool.click-extra.test-suite]
file = "tests/cli-test-suite.toml"

[tool.bumpversion]
current_version = "8.1.4.dev0"
# Parse versions with an optional .devN suffix (PEP 440).
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
serialize = [
  "{major}.{minor}.{patch}.dev{dev}",
  "{major}.{minor}.{patch}",
]
ignore_missing_files = true
allow_dirty = true
parts.dev.optional_value = "release"
# When dev is "release" (its optional value), the .devN suffix is omitted.
# Bumping patch/minor/major resets dev to "0", producing X.Y.Z.dev0.
# Bumping dev goes from "0" to "release", stripping the suffix for release.
parts.dev.values = [ "0", "release" ]

[[tool.bumpversion.files]]
# Update Python package version in any __init__.py file.
glob = "./**/__init__.py"
ignore_missing_version = true

[[tool.bumpversion.files]]
# Update version in [project] section. Anchored to a line start (regex) so it
# does not also match version-suffixed keys like file-version/product-version
# under [tool.nuitka], which contain `version = "X"` as a substring (their
# values collide with the package version on release commits, where the .devN
# suffix is absent).
filename = "./pyproject.toml"
regex = true
search = '(?m)^version = "{current_version}"'
replace = 'version = "{new_version}"'

[[tool.bumpversion.files]]
# Update version in download URL.
filename = "./pyproject.toml"
search = "releases/tag/v{current_version}"
replace = "releases/tag/v{new_version}"

[[tool.bumpversion.files]]
# Keep the numeric file-version/product-version under [tool.nuitka] in sync,
# when present. Nuitka rejects PEP 440 .devN suffixes, so the file-specific
# serialize strips them; the `-version = "` prefix matches both keys at once.
# ignore_missing_version makes this a no-op in projects without [tool.nuitka].
filename = "./pyproject.toml"
ignore_missing_version = true
serialize = [ "{major}.{minor}.{patch}" ]
search = '-version = "{current_version}"'
replace = '-version = "{new_version}"'

[[tool.bumpversion.files]]
# Update the version in Markdown changelog.
filename = "./changelog.md"
search = "## [`{current_version}` (unreleased)]("
replace = "## [`{new_version}` (unreleased)]("

[[tool.bumpversion.files]]
# Update the version in the citation file.
filename = "./citation.cff"
search = "version: {current_version}"
replace = "version: {new_version}"

[[tool.bumpversion.files]]
# Update the release date in the citation file.
filename = "./citation.cff"
regex = true
search = "date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}"
replace = "date-released: {utcnow:%Y-%m-%d}"

[[tool.bumpversion.files]]
filename = "./readme.md"
ignore_missing_version = true
include_bumps = [ "dev" ]
search = "raw.githubusercontent.com/kdeldycke/click-extra/main/"
replace = "raw.githubusercontent.com/kdeldycke/click-extra/v{new_version}/"

[[tool.bumpversion.files]]
filename = "./docs/tutorial.md"
ignore_missing_version = true
include_bumps = [ "dev" ]
search = "raw.githubusercontent.com/kdeldycke/click-extra/main/"
replace = "raw.githubusercontent.com/kdeldycke/click-extra/v{new_version}/"

# Restore image URLs from the release tag back to main (only during next dev cycle).
[[tool.bumpversion.files]]
filename = "./readme.md"
ignore_missing_version = true
exclude_bumps = [ "dev" ]
search = "raw.githubusercontent.com/kdeldycke/click-extra/v{current_version}/"
replace = "raw.githubusercontent.com/kdeldycke/click-extra/main/"

[[tool.bumpversion.files]]
filename = "./docs/tutorial.md"
ignore_missing_version = true
exclude_bumps = [ "dev" ]
search = "raw.githubusercontent.com/kdeldycke/click-extra/v{current_version}/"
replace = "raw.githubusercontent.com/kdeldycke/click-extra/main/"

[tool.mypy]
check_untyped_defs = true
warn_unused_configs = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_return_any = true
warn_unreachable = true
pretty = true
overrides = [
  { ignore_missing_imports = true, module = [ "hjson", "jsonc", "pymdownx", "pymdownx.*" ] },
  # Sphinx uses Python 3.12+ type statement syntax (PEP 695), which causes
  # mypy to fail with syntax errors when checking against older Python versions.
  # XXX This is a temporary workaround until we drop support for Python 3.10 and 3.11 for Click Extra.
  { ignore_missing_imports = true, module = [ "sphinx.*" ], follow_imports = "skip" },
]

[tool.lychee]
# https://lychee.cli.rs/guides/config/
exclude = [
  # GitHub issue comment fragments are dynamically loaded and can't be verified.
  "^https://github.com/.+/issues/[0-9]+#issuecomment-.*$",
  # GitHub blob line-number fragments (#L123) are rendered client-side.
  "^https://github.com/.+/blob/.+#L[0-9]+",
  # Release binary download URLs redirect to the GitHub CDN (objects.githubusercontent.com).
  "^https://github.com/.+/releases/.+/download/.*$",
  # Allow redirects of generic DOI URLs to their specific Zenodo release page.
  "^https://doi.org/.+/zenodo.*$",
  # star-history uses client-side hash routing; fragments are not real HTML anchors.
  "^https://star-history.com/#.*$",
  # crates.io blocks automated link checkers.
  "^https://crates.io/crates/.*$",
  # asciinema.org and no-color.org are valid but intermittently fail DNS
  # resolution or time out from CI runners. Also excluded from the Sphinx
  # linkcheck run (see linkcheck_ignore in docs/conf.py).
  "^https://asciinema.org.*$",
  "^https://no-color.org.*$",
  # The theme palette anchors (#dark, #light, …) sit under the "Palettes"
  # section of docs/theme.md, where a {python:render} loop over BUILTIN_THEMES
  # emits one heading per theme at Sphinx build time. Lychee only scans the raw
  # Markdown, so it never sees these build-time anchors (they resolve fine in
  # the built HTML). Add new built-in theme names here when they ship.
  "theme.md#(dark|dracula|light|manpage|monokai|nord|solarized-dark)$",
]

[tool.repomatic]
dependency-graph.all-extras = true
dependency-graph.all-groups = false
exclude = [ "skills", "workflows/debug.yaml" ]
# Render the Click command tree as roff `.1` files and attach a
# `click-extra-manpages.tar.gz` asset to every GitHub release. The script
# target mirrors `click_extra_manpages` in `docs/conf.py`, so the release
# tarball and the HTML docs site stay in lockstep. Requires repomatic
# >= 6.25.0 in the release engine.
manpages.script = "click_extra.cli:demo"
# Full test matrix (28 jobs; runs on push-to-main and the monthly schedule,
# never on PRs). It composes from two parts: a shipped cross-product for
# cross-platform coverage, and explicit `full-include` rows for forward-looking
# dependency coverage. Everything forward-looking runs on the single fastest
# runner (ubuntu-24.04-arm, measured in CI). The slices:
#   - released click × released cloup: {3.10, 3.14, 3.14t} on the 4 retained
#     OSes (ubuntu-24.04-arm, ubuntu-slim, macos-26, windows-2025), plus the
#     ubuntu-24.04-arm × 3.15 early-warning probe. 13 jobs, from the base
#     cross-product (`remove.os` + `include` + the 3.15 `exclude` rows below).
#   - {8.3.1, 8.3.2, 8.3.3, 8.4.0, 8.4.1} click × released cloup: ubuntu-24.04-arm ×
#     3.10 (the floor corner). Every Click release from the floor through 8.4.1,
#     past the 8.4.0 param-source regression, verifying the whole >=8.3.1 range. 5 jobs.
#   - {stable, main} click × released cloup: ubuntu-24.04-arm × {3.14, 3.14t}.
#     4 jobs.
#   - {released, stable, main} click × master cloup: ubuntu-24.04-arm ×
#     {3.14, 3.14t}. 6 jobs.
# The last three slices (15 jobs) are the `full-include` rows below.
# Runner selection favors measured speed over architecture: ubuntu-24.04-arm
# (ARM) beats ubuntu-slim (x86) by ~2x on Linux. Per OS the fastest are
# ubuntu-24.04-arm, macos-26 (ARM), and windows-2025 (x86, faster than
# windows-11-arm on recent Pythons); the slower-arch twins (macos-26-intel,
# windows-11-arm) are dropped entirely.
test-matrix.remove.os = [ "macos-26-intel", "windows-11-arm" ]
# Defaults applied to every job. The PR matrix runs only these (released Click
# on released Cloup); the forward-looking rows below are full-matrix only.
test-matrix.include = [
  { "click-version" = "released" },
  { "cloup-version" = "released" },
]
# Keep the prerelease Python 3.15 probe to a single early-warning cell
# (ubuntu-24.04-arm, released Click/Cloup); hold it off every other runner. This
# carves the 3.15 row out of the base cross-product. Applies to both matrices,
# but the PR matrix has no 3.15 cell, so it is a no-op there.
test-matrix.exclude = [
  { "os" = "ubuntu-slim", "python-version" = "3.15" },
  { "os" = "macos-26", "python-version" = "3.15" },
  { "os" = "windows-2025", "python-version" = "3.15" },
]
# Forward-looking dependency coverage, appended to the full matrix only (the PR
# matrix stays a fast released-on-released set). Each row is a standalone job;
# unspecified keys inherit the `include` defaults (released Click, released
# Cloup) and stable state. All pinned to ubuntu-24.04-arm, the fastest runner,
# since they probe dependency behavior rather than cross-platform support.
test-matrix.full-include = [
  # Every Click release from the >=8.3.1 floor through 8.4.1 (8.4.2 ships as
  # `released`), each on the floor Python 3.10.
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.10", "click-version" = "8.3.1", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.10", "click-version" = "8.3.2", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.10", "click-version" = "8.3.3", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.10", "click-version" = "8.4.0", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.10", "click-version" = "8.4.1", "cloup-version" = "released" },
  # Click's stable and main dev branches on released Cloup, latest Pythons.
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14", "click-version" = "stable", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14t", "click-version" = "stable", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14", "click-version" = "main", "cloup-version" = "released" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14t", "click-version" = "main", "cloup-version" = "released" },
  # Cloup's master branch on released, stable, and main Click, latest Pythons.
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14", "click-version" = "released", "cloup-version" = "master" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14t", "click-version" = "released", "cloup-version" = "master" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14", "click-version" = "stable", "cloup-version" = "master" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14t", "click-version" = "stable", "cloup-version" = "master" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14", "click-version" = "main", "cloup-version" = "master" },
  { "os" = "ubuntu-24.04-arm", "python-version" = "3.14t", "click-version" = "main", "cloup-version" = "master" },
]