Impossible to get single newlines in help text

The expected format is:

  --annotations [disabled|comment]
                                  Specify the type of annotations to include in the XML output.
                                  'Disabled' - no annotations.
                                  'Comment' - annotations as comments.

The actual format is either:

  --annotations [disabled|comment]
                                  Specify the type of annotations to include in the XML output.

                                  'Disabled' - no annotations.
                                  'Comment' - annotations as comments.

or:

  --annotations [disabled|comment]
                                  Specify the type of annotations to include in the XML output. 'Disabled' - no annotations. 'Comment' - annotations as comments.

However the text either has no newlines, or it has double newlines.
I expected this to work:

@click.option(
    "--annotations",
    type=click.Choice(Annotations, case_sensitive=False),
    default=Annotations.Comment,
    help="""Specify the type of annotations to include in the XML output.
    \b
    'Disabled' - no annotations.
    'Comment' - annotations as comments.""",
)

But that ends up without any newlines.
Adding an extra blank line before the \b does work, but that also results in an extra blank line in the output (as seen above):

@click.option(
    "--annotations",
    type=click.Choice(Annotations, case_sensitive=False),
    default=Annotations.Comment,
    help="""Specify the type of annotations to include in the XML output.

    \b
    'Disabled' - no annotations.
    'Comment' - annotations as comments.""",
)

Environment:

Python version: 3.10.11
Click version: 8.2.1

I'm not clear what you're trying to report. The text you showed has single newlines, I don't see any squashed lines or blank lines.

I'm not clear what you're trying to report. The text you showed has single newlines, I don't see any squashed lines or blank lines.

I tried rewording it to make it a bit more clear

See #561, we plan to have a more customizable formatter system in general so users can control exactly how wrapping/breaking/etc works.

See #561, we plan to have a more customizable formatter system in general so users can control exactly how wrapping/breaking/etc works.

Considering this ticket is from 2016, would it be an option to add a new escape (for example \b\b) that preserves newlines, but handles wrapping if the console becomes too small?

Or maybe an option to parse docstrings from the type behind click.Choice and add those as entries in the help text?

I don't plan to add a new escape in the meantime. If you or someone else identifies why the current formatter isn't producing the expected result, we can adjust it, but I don't want to add more markup that we'd need to support going forward.

There is no intention of supporting formatting help strings so specifically. When the help string for an option in taken in, then it is cleaned here Feel free to take a look at the code as see if you can get it do do what you want, but it depends on a standard lib function so it could break at any time.

There is no intention of supporting formatting help strings so specifically. When the help string for an option in taken in, then it is cleaned here Feel free to take a look at the code as see if you can get it do do what you want, but it depends on a standard lib function so it could break at any time.

That is not the part that slams the newlines, that is this part and this part specifically.

I will take a look.

I will take a look.

I created a suggestion how to fix it:
#3016

The change for that should be fairly simple, as long as there is consensus on the behavior.

Navigation Menu

Repository navigation

Impossible to get single newlines in help text #3010

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Impossible to get single newlines in help text #3010

Description

Activity

davidism commented on Jul 22, 2025

learn-more commented on Jul 22, 2025

davidism commented on Jul 22, 2025

learn-more commented on Jul 23, 2025

davidism commented on Jul 23, 2025

Rowlando13 commented on Jul 25, 2025

learn-more commented on Jul 25, 2025

Rowlando13 commented on Jul 26, 2025

learn-more commented on Jul 28, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions