gh-130645: Add colour to argparse help

[hugovk]

Add color parameter to argparse.ArgumentParser, which by default is False. When set to True, the help text is in colour if allowed (for example, we're not piping, NO_COLOR=1 is not set).

Example output

Using this script:

importargparseparser=argparse.ArgumentParser(
description="calculate X to the power of Y",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
prefix_chars="-+",
prog="PROG",
)
parser.color=Truegroup=parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true", help="more spam")
group.add_argument("-q", "--quiet", action="store_true", help="less spam")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent", deprecated=True)
parser.add_argument(
"this_indeed_is_a_very_long_action_name", type=int, help="the exponent"
)
parser.add_argument("-o", "--optional1", action="store_true", deprecated=True)
parser.add_argument("--optional2", help="pick one")
parser.add_argument("--optional3", choices=("X", "Y", "Z"))
parser.add_argument("--optional4", choices=("X", "Y", "Z"), help="pick one")
parser.add_argument("--optional5", choices=("X", "Y", "Z"), help="pick one")
parser.add_argument("--optional6", choices=("X", "Y", "Z"), help="pick one")
parser.add_argument(
"-p", "--optional7", choices=("Aaaaa", "Bbbbb", "Ccccc", "Ddddd"), help="pick one"
)
parser.add_argument("+f")
parser.add_argument("++bar")
parser.add_argument("-+baz")
parser.add_argument("-c", "--count")
subparsers=parser.add_subparsers(
title="subcommands", description="valid subcommands", help="additional help"
)
subparsers.add_parser("sub1", deprecated=True, help="sub1 help")
sub2=subparsers.add_parser("sub2", deprecated=True, help="sub2 help")
sub2.add_argument("--baz", choices=("X", "Y", "Z"), help="baz help")
args=parser.parse_args()

Performance

With the same script and PGO+LTO on macOS, running it once (time ./python.exe argparse-cli.py --help) and 100 times (time ./100.sh):

# 100.shforiin$(seq 1 100);do
./python.exe argparse-cli.py -h
done

main (3feac7a):

./python.exe argparse-cli.py --help 0.03s user 0.01s system 88% cpu 0.046 total
./100.sh 1.51s user 0.39s system 93% cpu 2.041 total

PR and colour not enabled:

./python.exe argparse-cli.py --help 0.02s user 0.02s system 58% cpu 0.072 total
./100.sh 1.52s user 0.40s system 92% cpu 2.070 total

PR and colour enabled:

./python.exe argparse-cli.py --help 0.04s user 0.02s system 70% cpu 0.080 total
./100.sh 1.57s user 0.40s system 93% cpu 2.106 total

Something like 0.65 ms difference per run between before and after, averaging from 100.sh.

• Issue: Add colour to argparse help #130645

---

📚 Documentation preview 📚: https://cpython-previews--132323.org.readthedocs.build/

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @hugovk for commit 3d174b7 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F132323%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

[savannahostrowski]

A comment about the approach and whether we can simplify a bit.

[hugovk]

ArgumentParser() has a lot of parameters, color is its 16th.

Many argparse CLIs I see already use keywords for most parameters, but I think we should make these new ones keyword-only, especially for new bools, as a long list of (..., True, False, True, ...) is best avoided.

suggest_on_error was added in 3.14, I suggest we also make that keyword-only (in another PR).

What do you think?

Commandeering this to make the beta 1 cut. Code owner's feedback can be addressed in follow-up PRs.

[asottile]

this patch breaks virtualenv by the way: (yay deadsnakes nightly builds catching this: https://github.com/deadsnakes/py3.14/actions/runs/14809355288/job/41582164772 )

$ ./prefix/bin/python3 virtualenv.pyz venvvvvTraceback (most recent call last): File "<frozen runpy>", line 198, in _run_module_as_main File "<frozen runpy>", line 88, in _run_code File "/home/asottile/workspace/cpython/virtualenv.pyz/__main__.py", line 178, in <module> run() ~~~^^ File "/home/asottile/workspace/cpython/virtualenv.pyz/__main__.py", line 174, in run run_virtualenv() ~~~~~~~~~~~~~~^^ File "/home/asottile/workspace/cpython/virtualenv.pyz/virtualenv/__main__.py", line 20, in run session = cli_run(args, options, env) File "/home/asottile/workspace/cpython/virtualenv.pyz/virtualenv/run/__init__.py", line 31, in cli_run of_session = session_via_cli(args, options, setup_logging, env) File "/home/asottile/workspace/cpython/virtualenv.pyz/virtualenv/run/__init__.py", line 49, in session_via_cli parser, elements = build_parser(args, options, setup_logging, env) ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/asottile/workspace/cpython/virtualenv.pyz/virtualenv/run/__init__.py", line 64, in build_parser add_version_flag(parser) ~~~~~~~~~~~~~~~~^^^^^^^^ File "/home/asottile/workspace/cpython/virtualenv.pyz/virtualenv/run/__init__.py", line 138, in add_version_flag parser.add_argument( ~~~~~~~~~~~~~~~~~~~^ "--version", ^^^^^^^^^^^^ ...<2 lines>... help="display the version of the virtualenv package and its location, then exit", ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ) ^ File "/home/asottile/workspace/cpython/prefix/lib/python3.14/argparse.py", line 1566, in add_argument formatter = self._get_formatter() File "/home/asottile/workspace/cpython/prefix/lib/python3.14/argparse.py", line 2733, in _get_formatter return self.formatter_class( ~~~~~~~~~~~~~~~~~~~~^ prog=self.prog, ^^^^^^^^^^^^^^^ prefix_chars=self.prefix_chars, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ color=self.color, ^^^^^^^^^^^^^^^^^ ) ^TypeError: HelpFormatter.__init__() got an unexpected keyword argument 'prefix_chars'

it looks like adding the parameters to the help formatter here breaks the subclass there

cc @gaborbernat

[cdce8p]

this patch breaks virtualenv by the way

It broke mypy as well. The fix was trivial though: python/mypy#19020

[The-Compiler]

This breaks tox as well: tox-dev/tox#3523

[hugovk]

We'll fix it for beta 2: #133653. Fixes (temporary or not) is helpful in other tools to enable testing beta 1, thanks!