PyCQA / PyCQA/docformatter

Unexpected interaction with click rewrapping

Open
#291 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C: stakeholder P: enhancement U: low
Dominant language
Python
Stars
598
Forks
93
PR merge metrics
No merged PRs in 30d

Description

Thank you for this project.
I am trying to get it to work with a CLI I maintain which uses Click.

Click generates help text for CLI commands from method docstrings.
Click rewraps text based on the width of the terminal, to a maximum of 80 characters.
In my case, this is not suitable as I have a long URL in a help text.

I therefore use Click's functionality to prevent rewrapping.

This involves using a \b escape marker.

If we take the example in the Click documentation:

@click.command()
def cli():
    """First paragraph.

    This is a very long second paragraph and as you
    can see wrapped very early in the source text
    but will be rewrapped to the terminal width in
    the final output.

    \b
    This is
    a paragraph
    without rewrapping.

    And this is a paragraph
    that will be rewrapped again.
    """

This renders as:

Usage: example.py [OPTIONS]

  First paragraph.

  This is a very long second paragraph and as you can see wrapped very early
  in the source text but will be rewrapped to the terminal width in the final
  output.

  This is
  a paragraph
  without rewrapping.

  And this is a paragraph that will be rewrapped again.

Options:
  --help  Show this message and exit.

However, docformatter moves the \b escape marker, so that the docstring is as so:

@click.command()
def cli():
    """First paragraph.

    This is a very long second paragraph and as you can see wrapped very
    early in the source text but will be rewrapped to the terminal width
    in the final output.

    \b This is a paragraph without rewrapping.

    And this is a paragraph that will be rewrapped again.
    """

This changes the rewrapping, so the help output is not as desired:

Usage: example.py [OPTIONS]

  First paragraph.

  This is a very long second paragraph and as you can see wrapped very early
  in the source text but will be rewrapped to the terminal width in the final
  output.

  This is a paragraph without rewrapping.

  And this is a paragraph that will be rewrapped again.

Options:
  --help  Show this message and exit.

In my case, this breaks a link.

I have a workaround - to tell Click not to interpret the help text from the docstring. However, I hope that this can be resolved in docformatter.

Contributor guide

No contributing guide indexed for this repository

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

Reproduce the Click example from the issue and compare its help output before and after docformatter runs. Trace how the standalone \b marker is handled, then verify that formatting preserves it as a separate paragraph and keeps the following text unrewrapped.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.