Add support for colorizing code examples in argparse description/epilog

[savannahostrowski]

Today, 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

• GH-142389: Add [cmd]...[/cmd] markup to colorize examples in argparse description/epilog #142390

[savannahostrowski]

cc: @hugovk as well for his thoughts

[picnixz]

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

[savannahostrowski]

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]

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]

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]

• 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)