Black reformats docstrings

[berislavlopac]

Describe the bug

Black unexpectedly changes the indentation of docstrings.

To Reproduce Steps to reproduce the behavior:

1. Take this file:

def something(foo, bar):
    """ My docstring.

        Some more docstring.

        Args:
            foo: something something
            bar: bla bla
    """
    print(foo, bar)

2. Run Black on it with no arguments.

3. The file now looks like this:

def something(foo, bar):
    """My docstring.

    Some more docstring.

    Args:
        foo: something something
        bar: bla bla
    """
    print(foo, bar)

Expected behavior

The file should not change.

Environment (please complete the following information):

• Version: black, version 20.8b1
• OS and Python version: Linux, Python 3.8.6

Does this bug also happen on master?

Yes: https://black.now.sh/?version=master&state=_Td6WFoAAATm1rRGAgAhARYAAAB0L-Wj4AERAI9dAD2IimZxl1N_WlbvK5V_r8p8R-QE02W0lfkJhkx4HULNTeXtLhBSpJmQpwGtlUvdJejSQJkMO6dLzygF-JFcvh-GgHC_wXD7PkS9n_u3ZNIEjx21NLS3PZDa8hVIXSPbpnHxFjE9s9CpuDGtiWTGVnMmoNBDg1cWmglrQAzN90l7lG5DkXLLpb9UER5YwF4AAADqLgMjoNolCwABqwGSAgAAAeEjmbHEZ_sCAAAAAARZWg==

Additional context

I understand that Black is opinionated and is trying to enforce PEP 257 verbatim, but there should at least be a switch to disable docstring formatting.

[ichard26]

A few relevant comments in a closed issue about docstrings

Could we please have a switch to disable the docstring reformatting altogether? Removing the leading whitespace may break docstrings containing tabular text. For instance this PLY/Yacc grammar rule:

    def p_flow_stmt(self, p):
        """flow_stmt : break_stmt
                     | continue_stmt
                     | return_stmt
                     | raise_stmt
                     | yield_stmt
        """
        p[0] = p[1]

ends up like:

    def p_flow_stmt(self, p):
        """flow_stmt : break_stmt
        | continue_stmt
        | return_stmt
        | raise_stmt
        | yield_stmt
        """
        p[0] = p[1]

#1635 (comment)

laloch: I cannot reproduce this. Were the grammar rules using tab characters instead of spaces?

Nevermind, I was on the wrong branch. Yeah, we'll deal with this for the next release.

#1635 (comment)

@laloch In the mean time, a workaround for Black's behavior is starting your docstring text on a newline:

    def p_flow_stmt(self, p):
        """
        flow_stmt : break_stmt
                  | continue_stmt
                  | return_stmt
                  | raise_stmt
                  | yield_stmt
        """
        p[0] = p[1]

#1635 (comment)

[jeremyschulman]

I am having a similar issue. When I am using the Click package for CLI, and employ the use of "\b" and "\f" for controlled formatting per https://click.palletsprojects.com/en/8.0.x/documentation/#preventing-rewrapping, then black reformats this docstring and mangles the CLI help-text.

[JelleZijlstra]

@jeremyschulman could you report an issue for that? I'd be open to specifically preserving \b and \f.

[berislav-harbr]

@JelleZijlstra What is the problem with having an option to prevent formatting of docstrings completely?

[JelleZijlstra]

We prefer to minimize options that affect formatting. It's also a better user experience for Click users if Black doesn't mangle their docstring in the first place than if they have to hunt for an option.

[berislav-harbr]

Oh I totally agree - it's better for _everyone_ not to mangle their docstrings in the first place. 🙄

…

On Sat, 23 Oct 2021, 01:10 Jelle Zijlstra, ***@***.***> wrote: We prefer to minimize options that affect formatting. It's also a better user experience for Click users if Black doesn't mangle their docstring in the first place than if they have to hunt for an option. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1779 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AVG3A7NMTFRPLTV4HQ3FPTTUIH4PVANCNFSM4S3OTEPA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[jeremyschulman]

@JelleZijlstra - I have created issue #2565 per your request. Thank you for supporting black. I love it!

[mixmastamyk]

Black broke the RST in some of our docstrings.

Example::

    pre-formated example command

There are other constructs that need to be indented correctly as well.

[felix-hilden]

@mixmastamyk could you be more specific? It seems to work fine on the playground.

[mixmastamyk]

Probably an old version:

⏵ black --version
black, 22.1.0 (compiled: yes)
⏵ cat foo.py
def foo():
    '''Example::

        pre-formated example command
    '''
    pass
⏵ cat foo.py
def foo():
    """Example::

    pre-formated example command
    """
    pass

Nope, upgraded and this does the same:

⏵ black --version
black, 22.3.0 (compiled: yes)

If perhaps you are not familiar with RST, the indent on the second line is required to be indented to signify a preformated section. As RST is used heavily in Python projects I'm surprised this is the case. Maybe I've done something wrong. 🤔

[felix-hilden]

Oh, this is likely just a special case of the first line being involved. We leave it in but standardise the indentation in the general body, so the "block" is dedented. Is your style accepted by Sphinx?

[mixmastamyk]

No, RST treats the dedented text as regular body text. But, I think I know what you are saying now. Another line in there would fix it.

[mixmastamyk]

I guess this is tolerable, but think I'd prefer not having to outsmart the formatter.

[felix-hilden]

I tested it: Sphinx does not accept your format. It warns about "literal block expected; none found" and outputs ordinary text. So are you using some other tool?

[mixmastamyk]

Black is what broke the .rst formatting. I wish it didn't do this, and didn't ask for it. But, seems easy to work around.

[felix-hilden]

I meant that the unedited example you described was not accepted by Sphinx, producing the error I provided. I did not format with black before building.

[felix-hilden]

In #3087 we discussed docstring formatting, and decided that it will keep happening. The specific issue Richard brought up is being tracked in #1698. So I'll close this issue for housekeeping.