GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — gh-130645: Add colour to `argparse` help by hugovk · Pull Request #132323 · python/cpython

Conversation

hugovk commented Apr 9, 2025 •

edited by github-actions Bot

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Member

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/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

barneygale, adamchainz, edgarrmondragon, and mattwang44 reacted with hooray emoji

edgarrmondragon and hartwork reacted with heart emoji

All reactions

🎉 4 reactions
❤️ 2 reactions


          Add colour to argparse help

d97415a

bedevere-app Bot mentioned this pull request

Apr 9, 2025

Add colour to argparse help #130645

Closed


          Add news

3d174b7

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

Apr 9, 2025

bedevere-bot commented Apr 9, 2025

Copy link

Copy Markdown

🤖 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.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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 Standard Library Python modules in the Lib/ directory 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

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

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

All commit authors signed the Contributor License Agreement.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

savannahostrowski requested changes

Apr 21, 2025

View reviewed changes

Comment thread

Lib/argparse.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread

Lib/argparse.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

bedevere-app Bot added awaiting changes and removed awaiting core review labels

Apr 21, 2025

bedevere-app Bot commented Apr 21, 2025

Copy link

Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

savannahostrowski previously requested changes

Apr 21, 2025

View reviewed changes

savannahostrowski left a comment

Copy link

Copy Markdown

Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

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

hugovk commented Apr 30, 2025

Copy link

Copy Markdown

Member Author

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?

ambv reacted with thumbs up emoji

All reactions

👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

ambv dismissed savannahostrowski’s stale review

May 2, 2025 13:03

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

ambv added awaiting merge and removed awaiting changes labels

May 2, 2025

ambv merged commit 4701ff9 into python:main

May 2, 2025

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

hauntsaninja pushed a commit to python/mypy that referenced this pull request

May 3, 2025


          Fix argparse for Python 3.14 (#19020)

d68ea35

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 commented May 3, 2025 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Contributor

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

cdce8p commented May 4, 2025

Copy link

Copy Markdown

Contributor

this patch breaks virtualenv by the way

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

cdce8p mentioned this pull request

May 4, 2025

Fix HelpFormatter for Python 3.14 pypa/virtualenv#2878

Merged

2 of 5 tasks

edgarrmondragon mentioned this pull request

May 6, 2025

Add new Python 3.14 argparse.ArgumentParser constructor parameters python/typeshed#13947

Merged

The-Compiler mentioned this pull request

May 8, 2025

Python 3.14: TypeError: HelpFormatter.__init__() got an unexpected keyword argument 'prefix_chars' tox-dev/tox#3523

Closed

The-Compiler commented May 8, 2025

Copy link

Copy Markdown

Contributor

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

edgarrmondragon reacted with thumbs up emoji

All reactions

👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

The-Compiler added a commit to The-Compiler/tox that referenced this pull request

May 8, 2025


          Fix custom HelpFormatter for Python 3.14

3b70f72

python/cpython#132323 passes prefix_chars=
(and other arguments) to the formatter_class, but the custom HelpFormatter only
accepted prog=.

Accept any keyword arguments and pass them on to the parent class.

Fixes tox-dev#3523

The-Compiler mentioned this pull request

May 8, 2025

Fix custom HelpFormatter for Python 3.14 tox-dev/tox#3524

Merged

5 tasks done

The-Compiler added a commit to The-Compiler/tox that referenced this pull request

May 8, 2025


          Fix custom HelpFormatter for Python 3.14

3c5d56b

python/cpython#132323 passes prefix_chars=
(and other arguments) to the formatter_class, but the custom HelpFormatter only
accepted prog=.

Accept any keyword arguments and pass them on to the parent class.

Fixes tox-dev#3523

iritkatriel mentioned this pull request

May 8, 2025

argparse.HelpFormatter subclasses may be broken by 3.14 changes #133653

Closed

hugovk commented May 8, 2025

Copy link

Copy Markdown

Member Author

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

edgarrmondragon reacted with thumbs up emoji

All reactions

👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

JelleZijlstra added a commit to python/typeshed that referenced this pull request

May 12, 2025


          Add new Python 3.14 argparse.ArgumentParser constructor parameters (#…

3f8a48f

…13947)

These are

- `suggest_on_error`, added by python/cpython#124456, made keyword-only by python/cpython#133302
- `color`, added by python/cpython#132323

Co-authored-by: Sebastian Rittau <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>

mmingyu pushed a commit to mmingyu/typeshed that referenced this pull request

May 16, 2025


          Add new Python 3.14 argparse.ArgumentParser constructor parameters (p…

fc6a13f

…ython#13947)

These are

- `suggest_on_error`, added by python/cpython#124456, made keyword-only by python/cpython#133302
- `color`, added by python/cpython#132323

Co-authored-by: Sebastian Rittau <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>

Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request

Jul 12, 2025


          pythongh-130645: Add color to argparse help (pythonGH-132323)

aead660

This was referenced Oct 9, 2025

GH-139809: Fix argparse subcommand prog not respecting color environment variables #139818

Merged

3.14+ argparse colorization makes sub-commands prog always colored if colored at creation time #139809

Closed

hugovk mentioned this pull request

Oct 28, 2025

gh-139946: distinguish stdout or stderr when colorizing output in argparse #140495

Merged

This was referenced Apr 19, 2026

Add colour to Python help #148766

Closed

gh-148766: Add colour to Python help #148767

Merged

Reviewers

savannahostrowski

savannahostrowski left review comments

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

stdlib

Standard Library Python modules in the Lib/ directory

type-feature

A feature request or enhancement

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

7 participants

Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

GeezerVison

Conversation

hugovk commented Apr 9, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Example output

Performance

Uh oh!

bedevere-bot commented Apr 9, 2025

Uh oh!

python-cla-bot Bot commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-app Bot commented Apr 21, 2025

Uh oh!

savannahostrowski left a comment

Choose a reason for hiding this comment

Uh oh!

hugovk commented Apr 30, 2025

Uh oh!

asottile commented May 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cdce8p commented May 4, 2025

Uh oh!

The-Compiler commented May 8, 2025

Uh oh!

hugovk commented May 8, 2025

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

hugovk commented Apr 9, 2025 •

edited by github-actions Bot

Loading

Uh oh!

There was an error while loading. Please reload this page.

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

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

asottile commented May 3, 2025 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.