problematic formatting: indentation change in docstring

[kaddkaka]

black might destroy ascii art in dosctring when re-indenting docstring lines.

Example code:

def dosctring_ascii_alignment():
    """Ascii art: [____,aaaa,bbbb]
                   ^         ^
    """
    pass

result after 'black`:

def dosctring_ascii_alignment():
    """Ascii art: [____,aaaa,bbbb]
    ^         ^
    """
    pass

as seen, the carets ^ are now misaligned. This can in problematic cases destroy information and be very confusing, misleading and lead to future mistakes.

In my mind it would be better to not touch docstrings - but I guess there might be some reason for it?

(original PR on ruff: astral-sh/ruff#10396)

[JelleZijlstra]

This is essentially a duplicate of #2150. We re-indent docstrings because it is sometimes necessary in cases where we re-indent the code itself, and we have previously rejected requests to make this configurable. I proposed a framework towards making this configurable (#3087), but for better or worse it was rejected.

[bryevdv]

I would just re-iterate that docstring are data, not code, and as such should never be modified by a code formatter for any reason, whatsoever. This is certainly and by far the biggest mistake black has ever made, and also a main reason we abandoned it on our projects.

[kaddkaka]

@bryevdv have you found some other usable formatter? I'm leaning towards autopep8 currently. (made a comparison tool for my own sake: https://github.com/kaddkaka/python-formatting-examples)

[bryevdv]

@kaddkaka No, we simply do not use a formatter at this time.

[hauntsaninja]

In case it's useful, it appears Black uses this logic https://peps.python.org/pep-0257/#handling-docstring-indentation when handling docstring whitespace. This means that if you have some other text in your docstring that's at the minimum indentation, Black will not destroy your ASCII art. The easiest way to do this would be to put a new line:

def docstring_ascii_alignment():
    """
    Ascii art: [____,aaaa,bbbb]
                ^         ^
    """
    pass

[bryevdv]

Tools are supposed to work for you, not the other way around. 🙂

[kaddkaka]

In case it's useful, it appears Black uses this logic https://peps.python.org/pep-0257/#handling-docstring-indentation when handling docstring whitespace. This means that if you have some other text in your docstring that's at the minimum indentation, Black will not destroy your ASCII art. The easiest way to do this would be to put a new line:

def docstring_ascii_alignment():
    """
    Ascii art: [____,aaaa,bbbb]
                ^         ^
    """
    pass

It's good to know, but it's no help since it doesn't magically fix all existing code.