pallets / pallets/click

`HelpFormatter.write_usage` breaks options at a hyphen

Open Beginner friendly
#3,362 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help output
Dominant language
Python
Stars
17.7k
Forks
2.3k
Avg merge
1d 30m
Merged PRs (30d)
18

Description

If an option containing a hyphen in its name is printed at the line break limit, it’s broken at the hyphen.

Reproduction
import click

options = [
    "--enable-verbose-logging",
    "--output-file-path",
    "--max-retry-count",
    "--disable-cache-mode",
    "--config-file-location",
    "--user-auth-token",
    "--auto-update-interval",
    "--force-overwrite-existing",
    "--network-timeout-seconds",
    "--debug-trace-enabled",
]

f = click.HelpFormatter(width=65)
f.write_usage("program", " ".join(options))
print(f.getvalue())
Expected output
Usage: program --enable-verbose-logging --output-file-path
               --max-retry-count --disable-cache-mode
               --config-file-location --user-auth-token
               --auto-update-interval --force-overwrite-existing
               --network-timeout-seconds --debug-trace-enabled
Actual output
Usage: program --enable-verbose-logging --output-file-path --max-
               retry-count --disable-cache-mode --config-file-
               location --user-auth-token --auto-update-interval
               --force-overwrite-existing --network-timeout-
               seconds --debug-trace-enabled
Environment
  • Python version: 3.12.3
  • Click version: 8.3.1
Additional information
width option

This also happens without specifying width. The width option is altered in the example to make the issue more frequent.

Relevance to other use cases

This may likely only affect:

  • direct users of click.HelpFormatter,
  • users of click.argument with custom metavar containing hyphens.

On the other hand, click prints [OPTIONS] instead of listing individual options on the usage line and uses underscores instead of hyphens in argument names (unless specifying metavar).

Cause

I looked into the code and found that textwrap.TextWrapper is used under the hood, which has the break_on_hyphens option. However, there is no option for the click user to influence this, apart from reimplementing HelpFormatter.write_usage (in a subclass) and wrap_text.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at click.HelpFormatter.write_usage and its wrap_text path, then run the supplied Python reproduction with width 65. Verify the output against the expected usage text and add coverage showing that hyphenated options remain whole at line boundaries while wrapping still respects the configured width.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.