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 = "7.7.0.dev0"
description = "🌈 Drop-in replacement for Click to make user-friendly and colorful CLI"
readme = "readme.md"
keywords = [
  "ansi-colors",
  "cli",
  "cloup",
  "colorization",
  "configuration",
  "console",
  "hjson",
  "ini",
  "json",
  "json5",
  "jsonc",
  "logging",
  "multiplatform",
  "pygments",
  "pytest",
  "python",
  "python-tabulate",
  "sphinx",
  "terminal",
  "toml",
  "xml",
  "yaml",
]
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",
  "License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)",
  "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 25.0.0 is the first version to support Python 3.13.
  # XXX boltons.ecoutils breaks PDB interactive sessions in pytest. Investigation of the root cause is being
  # discussed upstream at: https://github.com/mahmoud/boltons/issues/334
  "boltons>=25",
  # Click 8.3.1 fix an issue with parameters sharing same name.
  "click>=8.3.1",
  # Cloup 3.0.7 fix issues with metavars: https://github.com/kdeldycke/click-extra/pull/1281
  "cloup>=3.0.7",
  # deepmerge 2.0 is the first version used in Click Extra.
  "deepmerge>=2",
  # We depends on some internals changed in extra-platforms 8.0.0.
  "extra-platforms>=8",
  # requests 2.32.5 adds support for Python 3.14.
  "requests>=2.32.5",
  # tabulate 0.10 adds the `colon_grid` format.
  "tabulate[widechars]>=0.10",
  # tomllib is not part of the standard library before Python 3.11. Version 2.3.0 is the first to support Python 3.14.
  "tomli>=2.3; python_version<'3.11'",
  # wcmatch 10.0 fix some inconsistencies in globbing and symlinks.
  "wcmatch>=10",
]

[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-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"

[project.optional-dependencies]
yaml = [
  # PyYAML 6.0.3 is the first version to support Python 3.14.
  "pyyaml>=6.0.3",
]
json5 = [
  # json5 0.12.1 is the first version we used in Click Extra.
  "json5>=0.12.1",
]
jsonc = [
  # json-with-comments 1.2.10 is the first version we used in Click Extra.
  "json-with-comments>=1.2.10",
]
hjson = [
  # hjson 3.1.0 is the first version we used in Click Extra.
  "hjson>=3.1",
]
xml = [
  # xmltodict 1.0.0 is just the first major release.
  "xmltodict>=1",
]
pygments = [
  # Pygments 2.14.0 is the first version with lexers.algebra.GAPConsoleLexer that is referenced in our code.
  "pygments>=2.14",
  # pygments-ansi-color 0.3.0 is the first version to set the default theme of ANSI colors.
  "pygments-ansi-color>=0.3",
]
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",
  # pygments-ansi-color 0.3.0 is the first version to set the default theme of ANSI colors.
  "pygments-ansi-color>=0.3",
  # Sphinx  8.0.0 is the first version to drop Python 3.9, like us.
  "sphinx>=8",
]
pytest = [
  # pytest 9.0.0 is the first supporting native TOML configuration files.
  "pytest>=9",
]

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

[project.urls]
"Homepage" = "https://github.com/kdeldycke/click-extra"
"Download" = "https://github.com/kdeldycke/click-extra/releases/tag/v7.7.0.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[toml]>=7.12",
  # extra-platforms 5.0.0 is the first version to re-introduce support for Python 3.10.
  "extra-platforms[pytest]>=5",
  "myst-parser>=4",
  "pytest",
  "pytest-cov>=7",
  "pytest-github-actions-annotate-failures>=0.3",
  "pytest-httpserver>=1.1",
  "pytest-randomly>=4.0.1",
  "sphinx",
  "tomli>=2.3; python_version<'3.11'",
]
docs = [
  "furo>=2025.9.25",
  "myst-parser>=4",
  # pygments-ansi-color is required by docs/docs_update.py to generate the lexer table.
  "pygments-ansi-color>=0.3",
  "sphinx",
  # 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",
  "sphinx-design>=0.6",
  "sphinx-issues>=5",
  "sphinxcontrib-mermaid>=1.2.3",
  "sphinxext-opengraph>=0.13",
  "tomli>=2.3; python_version<'3.11'",
]
typing = [
  "types-boltons>=25.0.0.20250919",
  "types-docutils>=0.22.3.20251115",
  "types-pygments>=2.19.0.20251121",
  "types-pyyaml>=6.0.12.9",
  "types-requests>=2.32.4.20250611",
  "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"
# Exclude tabulate from the cooldown period.
exclude-newer-package = { "tabulate" = "0 day" }
# Package is at root level, not in "./src/".
build-backend.module-root = ""

[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
# 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
lint.ignore = [ "D400", "ERA001" ]
# 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-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",
]

[tool.pytest]
# https://docs.pytest.org/en/latest/customize.html#pyproject-toml
markers = [
  "once: Tests that only need to run once, not across the full CI matrix.",
]
addopts = [
  "--durations=10",
  "--cov",
  "--cov-report=term",
  "--cov-report=xml",
  # Codecov.io's test analytics requires a JUnit XML file:
  # https://docs.codecov.com/docs/test-analytics#1-output-a-junit-xml-file-in-your-ci
  "--junitxml=junit.xml",
  "--override-ini=junit_family=legacy",
]
# 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

[tool.bumpversion]
current_version = "7.7.0.dev0"
allow_dirty = true
ignore_missing_files = true
# 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}",
]
# 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" ]
parts.dev.optional_value = "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.
filename = "./pyproject.toml"
search = '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]]
# Update the version in standard 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.mypy]
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" ] },
  # 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.repomatic]

[tool.gha-utils]
workflow-sync-exclude = [ "debug.yaml" ]
dependency-graph-all-groups = false
dependency-graph-all-extras = true