GeezerVison is showing github.com — Add support for colorizing code examples in argparse description/epilog · Issue #142389 · python/cpython
Add support for colorizing code examples in argparse description/epilog #142389DescriptionToday, argparse does not support any native way to colorize code snippets in help descriptions. Example commands blend in with surrounding text, making help output harder to scan:
Allowing users to specify that they want to colorize an example in help text is a common UX pattern in modern CLI frameworks. Both Typer and rich-click support markup in help text via Rich's console markup (e.g., [green]text[/green]). Now that argparse supports colorization, it would be nice to add similar functionality. I think this is perhaps the last remaining gap in argparse's colorization support. I'm proposing a limited semantic markup approach:
epilog="""Examples:
[cmd]python -m myapp --verbose run[/cmd]
"""
After:
This support could potentially be expanded out later to support more sophisticated syntax highlighting (e.g. [python]...[/python]), since we already have a lot of this tokenization logic in place in _colorize.py. However, I'd like to start here before boiling the ocean.
Linked PRs
Activitysavannahostrowski commented on Dec 7, 2025 cc: @hugovk as well for his thoughts changed the title [-]Add markup support for colorizing code examples in argparse help text[/-] [+]Add support for colorizing code examples in argparse help text[/+] on Dec 7, 2025changed the title [-]Add support for colorizing code examples in argparse help text[/-] [+]Add support for colorizing code examples in argparse description/epilog[/+] on Dec 7, 2025picnixz commented on Dec 7, 2025 Can we have a separate formatter class to avoid supporting this markup? or a way to disable this (how do we type a literal [cmd]<text>[/cmd]; do we need backslashes?) A general markup=False option would be great to disable any interpreted markup I think (the same way we disable colors). Reacted by Serhiy Storchaka savannahostrowski commented on Dec 7, 2025 I think the intent of this feature is a bit different than the other Formatters we support today (which support the layout of help). Another option would be to not transform the input when color=False, which would be fairly straightforward to handle. I'm not super concerned about users literally typing [cmd]...[/cmd] though. I did check on GitHub search and found no instances of that. Ideally this would also be pretty lightweight for users to opt into as well. serhiy-storchaka commented on Dec 8, 2025 I think that today it may be more practical to support a subset of Markdown (*italic*, **bold**, `code`, ```other code```, rewrapped paragraphs, enumeration lists, etc) in argparse and pydoc. But it should not be enabled by default. We can support also other bb-codes ([i]italic[/i], [b]bold[/b], [code]code[/code]) and html (<i>italic</i>, <b>bold</b>, <code>code</code>) in other formatters. This is a large issue. picnixz commented on Dec 8, 2025 I believe that BB code would be awesome. We could also support a more generic [color=...][/color] because it would really give more customization power to users. I also agree that I would rather have it disabled by default because I personally won't be using everywhere. mpkocher commented on Dec 9, 2025
- I think that users can currently do this
epilog=f"{t.prog} my-tool -m alpha{t.reset}" (See example below). It's unclear if the cmd= layer of indirection is providing enough value.
- The
[cmd] style might be better as subset of Markdown (as someone else mentioned)
- If you add
epilog= this will immediately motivate description= and friends for consistency. This creates a large potential of feature creep with non-trivial unexpected complexity (See example below)
- If you want to support multiple versions of Python, all of these API changes are going to require
if sys.version_info >= (3, 15) and /or if sys.version_info >= (3, 14) sprinkled around in your code.
People will probably figure that you can manually put escape sequences in fields and it sort of works. Maybe It's a good idea to be proactive to either discourage or enable this?
import sys
from argparse import ArgumentParser
from _colorize import get_theme
t = get_theme().argparse
def get_parser() -> ArgumentParser:
p = ArgumentParser(description=f"Example {t.usage}Color Tool{t.reset}",
epilog=f"Example {t.heading}Color Tool{t.reset}")
p.add_argument('-i', '--input', help=f"Input {t.usage}file{t.reset}", metavar="FILE")
return p
if __name__ == "__main__":
p = get_parser()
pa = p.parse_args()
print(pa)
sys.exit(0)hugovk commented on Dec 12, 2025 I think something like this would be good. Quick demo:
But then these plaintext [cmd]s are a bit annoying with NO_COLOR:
I first thought, for NO_COLOR we could replace them with backticks. But my CLI currently does use backticks in those positions and I'd modified them to [cmd] for this demo, so triggering on backticks would be useful -- colour when supported, and understandable backticks for NO_COLOR:
One downside of a generic code formatting is we're losing the semantic meaning: [cmd] is a command with the same magenta of the prog in the usage line. If I add something like * and `--help` for help to the description it's also shown in magenta when we might prefer it in cyan:
But maybe this is overthinking things, and a subset of Markdown would be best. Keep the subset small to begin with. I'd skip BBCode, as Markdown is more familiar and looks okay in plaintext as well. So it could be on by default, and actually doesn't need a toggle beyond NO_COLOR and friends. Reacted by Savannah Ostrowski and M. Kocher savannahostrowski commented on Dec 12, 2025 Yeah, my intention here was to keep things minimal. I don't want to go down the rabbit hole of implementing a full Markdown parser to solve a pretty simple, contained, and common issue.
If someone wants to scope a larger proposal for something more robust, I think that's fine but beyond the scope of what I'm after. Reacted by Hugo van Kemenade hugovk commented on May 3, 2026 Using this to add some colour to regrtest and pdb's help descriptions: #149332. added 3 commits that reference this issue on May 4, 2026gh-142389: Add backticks to stdlib argparse help to display in colour (… gh-142389: Add support for backtick colorisation in argparse help text (
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|
