Re-indent the contents of docstrings #1053
Conversation
|
Can you help me understand why this change is needed? I don't understand it either from the description of this PR, or the referenced commit, or the test cases (which by the way pass even on master). I'd rather not reverse-engineer the new code. |
|
This change is needed to preserve the docstring indent when formatting codebases with 2 spaces indentation to 4 spaces. Source file: class MyClass:
"""Multiline
class docstring
"""
def method(self):
"""Multiline
method docstring
"""
passAfter running black: class MyClass:
"""Multiline
class docstring
"""
def method(self):
"""Multiline
method docstring
"""
passExpected: class MyClass:
"""Multiline
class docstring
"""
def method(self):
"""Multiline
method docstring
"""
pass |
|
Nice! @alexmv can we include that example in the test cases, please? And maybe another one that tests the conversion from overindented (more than 4 spaces) docstrings. |
|
@alexmv can you split that into two commits so that my original commits stays as is (for contribution)? |
|
I'm going to squash it anyway when merging, though |
alexmv
force-pushed
the
docstring-indent
branch
from
3c9f709
to
982d92d
Compare
|
Whoops -- sorry for not wording the commit more carefully to make its need clear. Tests all fail for me on I've added an explicit |
|
Any other comments on this? |
|
Can you point me at an issue where this was agreed on? |
|
I wasn't aware that a separate issue needed to be created for what seemed like a reasonable bugfix with code provided. There seems to be reasonable agreement here on the PR. What sort of agreement are you looking for in a separate issue? |
|
It might be good to have a testcase that includes lines in the docstring with extra leading whitespace, e.g.: |
Keeping the contents of docstrings completely unchanged when
re-indenting (from 2-space intents to 4, for example) can cause
incorrect docstring indentation:
```
class MyClass:
"""Multiline
class docstring
"""
def method(self):
"""Multiline
method docstring
"""
pass
```
...becomes:
```
class MyClass:
"""Multiline
class docstring
"""
def method(self):
"""Multiline
method docstring
"""
pass
```
This uses the PEP 257 algorithm for determining docstring indentation,
and adjusts the contents of docstrings to match their new indentation
after `black` is applied.
A small normalization is necessary to `assert_equivalent` because the
trees are technically no longer precisely equivalent -- some constant
strings have changed. When comparing two ASTs, whitespace after
newlines within constant strings is thus folded into a single space.
Co-authored-by: Luka Zakrajšek <luka@bancek.net>
This reduces the cyclomatic complexity to a level that makes flake8 happy.
alexmv
force-pushed
the
docstring-indent
branch
from
b96f9ca
to
93d6b8f
Compare
|
Thanks for that suggestion, @jboning -- I've added that test, along with one for a too-deep closing Rebased atop latest |
|
Let's merge this. Don't forget to add it to changelog. |
|
Please see #1452. |
The PEP 257 algorithm used in psf#1053 results in trimming trailing whitespace in docstrings -- see psf#1415 and fixes in psf#1417. Removing trailing whitespace may result in four quotes in a row: def foo(): """"Some content and more "here" """ pass When closing the docstring, escape any trailing quote characters that it matches, if they are not already escaped. Fixes psf#1446.
The PEP 257 algorithm used in psf#1053 results in trimming trailing whitespace in docstrings -- see psf#1415 and fixes in psf#1417. Removing trailing whitespace may result in four quotes in a row: def foo(): """"Some content and more "here" """ pass When closing the docstring, escape any trailing quote characters that it matches, if they are not already escaped. Fixes psf#1446.
0;95;0c The PEP 257 algorithm used in psf#1053 results in trimming trailing whitespace in docstrings -- see psf#1415 and fixes in psf#1417. Removing trailing whitespace may result in four quotes in a row: def foo(): """"Some content and more "here" """ pass When closing the docstring, escape any trailing quote characters that it matches, if they are not already escaped. Fixes psf#1452.
The PEP 257 algorithm used in psf#1053 results in trimming trailing whitespace in docstrings -- see psf#1415 and fixes in psf#1417. Removing trailing whitespace may result in four quotes in a row: def foo(): """"Some content and more "here" """ pass When closing the docstring, escape any trailing quote characters that it matches, if they are not already escaped. Fixes psf#1452.
The PEP 257 algorithm used in psf#1053 results in trimming trailing whitespace in docstrings -- see psf#1415. Adjust the algorithm to preserve leading and trailing whitespace; this reverts the changes in psf#1417. This diverges from PEP 257, but better retains the contents of the docstring. Fixes psf#1452 because we no longer can end up with four trailing quotes.
This cleans up bancek@0889797 by @bancek based on the feedback there.