GV

GeezerVison

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

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-148766: Add colour to Python help by hugovk · Pull Request #148767 · python/cpython

Conversation

@hugovk

@hugovk hugovk commented Apr 19, 2026 •
edited by github-actions Bot
Loading

Uh oh!

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

Copy link
Copy Markdown
Member

python --help (and especially --help-all) is a monochrome wall of text. Similar to argparse help, let's add some colour to add structure and improve readability.

Here's real screenshots of --help and termshot capture of --help-all:

Before After 
--help
--help
--help-all
--help-all
  • Issue: Add colour to Python help #148766

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@hugovk
Add colour to Python help
cd43345
@hugovk
hugovk requested review from AA-Turner, FFY00 and ericsnowcurrently as code owners April 19, 2026 19:37
@bedevere-app bedevere-app Bot added the awaiting core review label Apr 19, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Apr 19, 2026
Add colour to Python help #148766
Closed
@hugovk hugovk added the interpreter-core (Objects, Python, Grammar, and Parser dirs) label Apr 19, 2026
StanFromIreland
StanFromIreland reviewed Apr 20, 2026
View reviewed changes
Comment thread Python/initconfig.c Resolved

Uh oh!

There was an error while loading. Please reload this page.
StanFromIreland
StanFromIreland reviewed Apr 20, 2026
View reviewed changes
Comment thread Python/initconfig.c Outdated
#if defined(MS_WINDOWS) && defined(HAVE_WINDOWS_CONSOLE_IO)
{
DWORD mode = 0;
HANDLE handle = GetStdHandle(STD_OUTPUT_HANDLE);

@StanFromIreland StanFromIreland Apr 20, 2026

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.

Shouldn't this also consider stderr (or maybe it does? I don't know Windows quirks).

Sorry, something went wrong.

Uh oh!

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

@hugovk hugovk Apr 21, 2026

Copy link
Copy Markdown
Member Author

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.

Something like 294d008?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
PyMem_RawFree(buf);
}
else {
fprintf(f, usage_line, program);

@StanFromIreland StanFromIreland Apr 20, 2026

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.

If PyMem_RawMalloc fails we will get the raw tags, no?

Sorry, something went wrong.

Uh oh!

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

@hugovk hugovk Apr 22, 2026

Copy link
Copy Markdown
Member Author

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.

This now falls back to no tags.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
return;
}
}
fprint_tagged(stdout, usage_envvars, 0);

@StanFromIreland StanFromIreland Apr 20, 2026

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.

We still need formatting here?

Sorry, something went wrong.

Uh oh!

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

@hugovk hugovk Apr 22, 2026

Copy link
Copy Markdown
Member Author

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.

Yes, updated to use colour if available.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
serhiy-storchaka
serhiy-storchaka reviewed Apr 21, 2026
View reviewed changes

@serhiy-storchaka serhiy-storchaka 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.

What if the program path by accident contains {E}?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@hugovk
Strip colour when not needed
e17d697
@hugovk

hugovk commented Apr 21, 2026

Copy link
Copy Markdown
Member Author

Updated to flip it: colour codes are now included in the help text (via macros to keep it tidier), and stripped out when not needed.

So {E} in the path is not an issue.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk
hugovk marked this pull request as draft April 21, 2026 15:25
@bedevere-app bedevere-app Bot removed the awaiting core review label Apr 21, 2026
hugovk added 3 commits April 21, 2026 18:29
@hugovk
Check if Windows is using stdout/stderr
294d008
@hugovk
Use colour in fallback if available
4dddbb2
@hugovk
More colour in help text
b0837af
@hugovk
hugovk marked this pull request as ready for review April 22, 2026 18:17
@bedevere-app bedevere-app Bot added the awaiting core review label Apr 22, 2026
@hugovk

hugovk commented Apr 22, 2026

Copy link
Copy Markdown
Member Author
  • There are references to options and environment variables in descriptions. I would highlight them too.

Here we go:

image
All reactions

Sorry, something went wrong.

Uh oh!

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

hugovk commented May 3, 2026

Copy link
Copy Markdown
Member Author

Thanks for the reviews, any further comments?
All reactions

Sorry, something went wrong.

Uh oh!

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

encukou commented May 5, 2026

Copy link
Copy Markdown
Member

Would something like this be more maintainable?

#define RESET "\x1b[0m"
#define ENVVAR(STR)  "\x1b[1;36m" STR RESET
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk
Use function-like macros
e937914
@hugovk

hugovk commented May 5, 2026

Copy link
Copy Markdown
Member Author

Nice idea, updated :)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@read-the-docs-community

read-the-docs-community Bot commented May 5, 2026 •
edited
Loading

Uh oh!

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

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #32560311 | 📁 Comparing 0a8ab45 against main (a8c9aa9)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

  • library/difflib.html
  • library/functions.html
  • library/tkinter.messagebox.html
  • whatsnew/3.15.html
  • whatsnew/changelog.html
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@serhiy-storchaka

serhiy-storchaka commented May 5, 2026

Copy link
Copy Markdown
Member

This version is barely readable. What if return to the previous version with substitutions and use some of substitution codes to substitute the program name, the default PYTHONHOME, the path separator instead of just color sequences?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
encukou
encukou reviewed May 5, 2026
View reviewed changes
Comment thread Python/initconfig.c Outdated
SHORTOPT("-d") " : turn on parser debugging output (for experts only, only works on\n"
" debug builds); also " ENVVAR_REF("PYTHONDEBUG") SUMMARY_LABEL("=x") "\n"
SHORTOPT("-E") " : ignore " ENVVAR_REF("PYTHON*") " environment variables (such as " ENVVAR_REF("PYTHONPATH") ")\n"
SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " ENVVAR_REF("--help") ")\n"

@encukou encukou May 5, 2026

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.

Suggested change
SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " ENVVAR_REF("--help") ")\n"
SHORTOPT("-h") " : print this help message and exit (also " SHORTOPT_SUMMARY("-?") " or " LONGOPT("--help") ")\n"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
" this option has no effect on stdin; also " ENVVAR_REF("PYTHONUNBUFFERED") SUMMARY_LABEL("=x") "\n"
SHORTOPT("-v") " : verbose (trace import statements); also " ENVVAR_REF("PYTHONVERBOSE") SUMMARY_LABEL("=x") "\n"
" can be supplied multiple times to increase verbosity\n"
SHORTOPT("-V") " : print the Python version number and exit (also " ENVVAR_REF("--version") ")\n"

@encukou encukou May 5, 2026

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.

Suggested change
SHORTOPT("-V") " : print the Python version number and exit (also " ENVVAR_REF("--version") ")\n"
SHORTOPT("-V") " : print the Python version number and exit (also " LONGOPT("--version") ")\n"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
"PYTHON_FROZEN_MODULES: whether to use frozen modules; the default is \"on\"\n"
" for installed Python and \"off\" for a local build\n"
" (-X frozen_modules)\n"
HEADING("These variables have equivalent command-line options (see ") ENVVAR_REF("--help") " for details):" "\n"

@encukou encukou May 5, 2026

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.

Suggested change
HEADING("These variables have equivalent command-line options (see ") ENVVAR_REF("--help") " for details):" "\n"
HEADING("These variables have equivalent command-line options") "(see " ENVVAR_REF("--help") " for details):" "\n"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
"PYTHONPERFSUPPORT: support the Linux \"perf\" profiler (-X perf)\n"
ENVVAR("PYTHONINSPECT") " : inspect interactively after running script (" SHORTOPT_SUMMARY("-i") ")\n"
ENVVAR("PYTHONINTMAXSTRDIGITS") ": limit the size of int<->str conversions;\n"
" 0 disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"

@encukou encukou May 5, 2026

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.

Suggested change
" 0 disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"
" " SUMMARY_LABEL("0") " disables the limit (" SHORTOPT_SUMMARY("-X") " " ENVVAR_REF("int_max_str_digits") SUMMARY_LABEL("=N") ")\n"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
ENVVAR("PYTHONEXECUTABLE") ": set sys.argv[0] to this value (macOS only)\n"
#endif
"PYTHONHASHSEED : if this variable is set to 'random', a random value is used\n"
ENVVAR("PYTHONHASHSEED") " : if this variable is set to 'random', a random value is used\n"

@encukou encukou May 5, 2026

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.

Suggested change
ENVVAR("PYTHONHASHSEED") " : if this variable is set to 'random', a random value is used\n"
ENVVAR("PYTHONHASHSEED") " : if this variable is set to '" SUMMARY_LABEL("random") "', a random value is used\n"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Python/initconfig.c Outdated
"PYTHONMALLOCSTATS: print memory allocator statistics\n"
"PYTHONPATH : '%lc'-separated list of directories prefixed to the\n"
ENVVAR("PYTHONMALLOCSTATS") ": print memory allocator statistics\n"
ENVVAR("PYTHONPATH") " : '%lc'-separated list of directories prefixed to the\n"

@encukou encukou May 5, 2026

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.

Suggested change
ENVVAR("PYTHONPATH") " : '%lc'-separated list of directories prefixed to the\n"
ENVVAR("PYTHONPATH") " : '" SUMMARY_LABEL(%lc) "'-separated list of directories prefixed to the\n"

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@serhiy-storchaka

serhiy-storchaka commented May 5, 2026

Copy link
Copy Markdown
Member

My previous comment was related to the version prior to the latest change, but I still thing that substitution-based approach would be clearer than macros-based.
All reactions

Sorry, something went wrong.

Uh oh!

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

hugovk commented May 5, 2026

Copy link
Copy Markdown
Member Author

@serhiy-storchaka Could you give a short example of what you're thinking of?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@serhiy-storchaka

serhiy-storchaka commented May 5, 2026

Copy link
Copy Markdown
Member

Simple example:

"{E}PYTHONHOME{r}      : alternate <prefix> directory (or <prefix>{b}{D}{r}<exec_prefix>).\n"
"                  The default module search path uses {b}{H}{r}.\n"

{E}, {b} and {r} substitute color sequences, {D} substitutes the DELIM character, {H} substitutes PYTHONHOMEHELP.

To avoid repeated {r} we can also change the syntax, for example:

"#E{PYTHONHOME}      : alternate <prefix> directory (or <prefix>#b{#D}<exec_prefix>).\n"
"                  The default module search path uses #b{#H}.\n"

This is simpler than it looks. #E{ and #b{ change the color, } resets it to default. We do not need to support arbitrary nesting.
hugovk reacted with eyes emoji
All reactions
  • 👀 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk
Change to substitution-based
0a8ab45
@hugovk

hugovk commented May 6, 2026

Copy link
Copy Markdown
Member Author

Thanks, updated! How does this look?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
serhiy-storchaka
serhiy-storchaka approved these changes May 6, 2026
View reviewed changes

@serhiy-storchaka serhiy-storchaka 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.

LGTM. 👍

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels May 6, 2026
@hugovk
hugovk merged commit e7613f2 into python:main May 6, 2026
59 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@hugovk
hugovk deleted the 3.15-help-colour branch May 6, 2026 13:48
@bedevere-app bedevere-app Bot removed the awaiting merge label May 6, 2026
@hugovk

hugovk commented May 6, 2026

Copy link
Copy Markdown
Member Author

Thanks all for the reviews!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@encukou encukou encukou left review comments
@StanFromIreland StanFromIreland StanFromIreland left review comments
@serhiy-storchaka serhiy-storchaka serhiy-storchaka approved these changes
@ericsnowcurrently ericsnowcurrently Awaiting requested review from ericsnowcurrently ericsnowcurrently is a code owner
@FFY00 FFY00 Awaiting requested review from FFY00 FFY00 is a code owner
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Uh oh!

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

Assignees

No one assigned

Labels

interpreter-core (Objects, Python, Grammar, and Parser dirs)

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.

4 participants

@hugovk @encukou @serhiy-storchaka @StanFromIreland
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.