argparse-color-formatter

An ANSI-aware formatter_class for argparse. It calculates layout using the visible width of help text, without counting ANSI escape sequences as displayed characters.

Install

$ pip install argparse-color-formatter

What it does

This package does not decide which text to colour. Your application supplies the ANSI-coloured program names, metavars, descriptions, help strings, or epilogues. ColorHelpFormatter then:

• wraps descriptions, help strings, and usage text at their visible width;
• aligns option and positional argument labels correctly; and
• preserves ANSI sequences in the formatted output.

Without an ANSI-aware formatter, invisible escape sequences can make argparse wrap text too early or misalign help columns.

Do I need this on Python 3.14?

Python 3.14 added native colour support to argparse. If you only want the standard argparse colour theme, you do not need this package.

This package is still useful when your application embeds its own ANSI sequences in descriptions, help strings, program names, or metavars. Python 3.14 accounts for its own theme in some layout calculations, but still wraps arbitrary application-coloured descriptions and help strings using their encoded length. ColorHelpFormatter handles those sequences by their visible width and preserves the native Python 3.14 theme alongside them.

Python 3.9 to 3.13

These Python versions do not add colours to argparse help. Use a library such as ansicolors or generate ANSI sequences directly, then use ColorHelpFormatter to keep the resulting output aligned and wrapped correctly.

Usage

Pass ColorHelpFormatter to an argument parser as formatter_class. The example uses ansicolors, which is installed as a dependency of this package.

import argparse

from colors import bold

from argparse_color_formatter import ColorHelpFormatter

output = bold("FILE")
parser = argparse.ArgumentParser(
    description=f"Write the generated report to {output}.",
    formatter_class=ColorHelpFormatter,
)
parser.add_argument(
    "--output",
    metavar=output,
    help=f"save the report as {output}",
)

Development

Setup

pipenv install --dev
pre-commit install
pre-commit install --hook-type commit-msg

Build

pipenv run build

Test

pipenv run test

After and before

ANSI colour escapes using this library's ColorHelpFormatter:

ANSI colour escapes using the default HelpFormatter: