gh-130645: Add colour to `argparse` help #132323

hugovk · 2025-04-09T16:05:48Z

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:

import argparse

parser = argparse.ArgumentParser(
    description="calculate X to the power of Y",
    formatter_class=argparse.ArgumentDefaultsHelpFormatter,
    prefix_chars="-+",
    prog="PROG",
)
parser.color = True
group = 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.sh
for i in $(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 · 2025-04-09T16:36:34Z

🤖 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 · 2025-04-18T09:25:52Z

All commit authors signed the Contributor License Agreement.

Lib/argparse.py

bedevere-app · 2025-04-21T03:10:10Z

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 · 2025-04-30T13:35:10Z

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.

python/cpython#132323 added an optional `color` argument to ArgumentParser. As a side effect the help formatters are now called with two new keyword arguments `prefix_chars` and `color`. Add `**kwargs` to the custom `AugmentedHelpFormatter` and pass it through to the super class.

asottile · 2025-05-03T15:23:03Z

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 venvvvv
Traceback (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

Add colour to argparse help

d97415a

bedevere-app bot mentioned this pull request Apr 9, 2025

Add colour to argparse help #130645

Open

Add news

3d174b7

hugovk added the 🔨 test-with-buildbots Test PR w/ buildbots; report in status section label Apr 9, 2025

bedevere-bot removed the 🔨 test-with-buildbots Test PR w/ buildbots; report in status section label Apr 9, 2025

hugovk added type-feature A feature request or enhancement stdlib Python modules in the Lib dir labels Apr 9, 2025

hugovk marked this pull request as ready for review April 9, 2025 18:12

hugovk requested a review from savannahostrowski as a code owner April 9, 2025 18:12

bedevere-app bot added the awaiting core review label Apr 9, 2025

savannahostrowski requested changes Apr 21, 2025

View reviewed changes

Lib/argparse.py Show resolved Hide resolved

Lib/argparse.py Show resolved Hide resolved

bedevere-app bot added awaiting changes and removed awaiting core review labels Apr 21, 2025

savannahostrowski previously requested changes Apr 21, 2025

View reviewed changes

hugovk added 3 commits April 22, 2025 17:20

Only replace when action and header on same line

c0a0688

Merge branch 'main' into 3.14-argparse-colour-help

11b2c6d

Make new color parameter keyword-only

4524881

ambv added awaiting merge and removed awaiting changes labels May 2, 2025

ambv merged commit 4701ff9 into python:main May 2, 2025
51 of 52 checks passed

bedevere-app bot removed the awaiting merge label May 2, 2025

hugovk deleted the 3.14-argparse-colour-help branch May 2, 2025 13:31

cdce8p mentioned this pull request May 3, 2025

Fix argparse for Python 3.14 python/mypy#19020

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-130645: Add colour to `argparse` help #132323

gh-130645: Add colour to `argparse` help #132323

hugovk commented Apr 9, 2025 •

edited by github-actions bot

Loading

bedevere-bot commented Apr 9, 2025

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading

bedevere-app bot commented Apr 21, 2025

savannahostrowski left a comment

hugovk commented Apr 30, 2025

asottile commented May 3, 2025 •

edited

Loading

gh-130645: Add colour to argparse help #132323

gh-130645: Add colour to argparse help #132323

Conversation

hugovk commented Apr 9, 2025 • edited by github-actions bot Loading

Example output

Performance

bedevere-bot commented Apr 9, 2025

python-cla-bot bot commented Apr 18, 2025 • edited Loading

bedevere-app bot commented Apr 21, 2025

savannahostrowski left a comment

Choose a reason for hiding this comment

hugovk commented Apr 30, 2025

asottile commented May 3, 2025 • edited Loading

gh-130645: Add colour to `argparse` help #132323

gh-130645: Add colour to `argparse` help #132323

hugovk commented Apr 9, 2025 •

edited by github-actions bot

Loading

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading

asottile commented May 3, 2025 •

edited

Loading