psf
Black should not change leading white space in doc strings
Black 20 is now changing this:
def p_col(p):
"""col : scalar_col
| scalar_step_col
| attr_col
| flag_col
"""
to:
def p_col(p):
"""col : scalar_col
| scalar_step_col
| attr_col
| flag_col
"""
Doc strings can be used for formatted text including, well, anything you want. In this case the doc strings are used by PLY to define a parsing grammar. This issue will effect anything that uses leading white space such as Markdown. It's bad form to start mucking with prose. You have no idea what's in there. White space that starts and ends the comment is fair game but not the content in between.
I don't agree. If you want formatting like that, i would advice on using a dot or backslash on the "zeroth" space, so it doesn't indent
Can you or someone offer an explanation of why Black disregards PEP 257?
Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.
Emphasis is mine.
In the case of my example, the doc string is a grammar. I don't have the luxury of making up a syntax to workaround Black's decision to reformat the doc string. Similarly, someone using reStructuredText, a standard use of doc string, does not have the luxury of making up a new syntax based on your workaround suggestion. Leading white space is meaningful in both cases. It's meaningful for Markdown. Black is not only violating Python standards here it's breaking common use of doc string.
Do you disagree with that?