fix: keep two blank lines between a module docstring and a following definition - #370
Merged
weibullguy merged 3 commits intoAug 10, 2026
Merged
Conversation
…definition _get_module_docstring_newlines() returned a hard-coded 1. Give it the same forward scan _get_class_docstring_newlines() already uses, so a class, def or decorator directly after the module docstring gets the two blank lines PEP 8 asks for. Closes PyCQA#350. Signed-off-by: Eljees <3.14hell@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #350.
A module docstring followed directly by a
classor adefgets one blank line,where PEP 8 asks for two.
_get_module_docstring_newlines()informat.pytakesno arguments and returns a hard-coded
1.Its neighbour
_get_class_docstring_newlines()already handles the same situation:it scans forward and returns
2when it findsis_definition_line(tokens[j]).This change gives the module function the same shape -- skip NL/NEWLINE/INDENT/
DEDENT, return
2for a decorator or a definition line,1otherwise.The project agrees with PEP 8 everywhere else. Put anything between the docstring
and the class and the two blank lines survive untouched:
So the current behaviour reads as a gap in the scan rather than an expression of
rule 8.2. It is the same for
def, and it does not depend on--black.One thing to decide before merging:
docformatter_8.2is written as "One blankline after a module docstring", so this does change documented behaviour. I
extended the docstring of the function rather than rewriting the rule -- if you
would rather keep 8.2 literal, say so and I will close this.
On the tests
The five existing
module_docstring_*fixtures had anexpectedbut nosource,and
test_module_docstring_newlinescalled the function with no arguments andcompared
1 == 1, so they were not exercising anything. They now carry realsources, and the test builds tokens and calls
(tokens, index)-- the same shapeas
test_get_docstring_newlinesnext to it. Three new cases cover def, class anddecorated def.
Verification
On
e154acb, Python 3.10.12:tests/formatter/test_format_functions.pygoes from35 to 38 passed. Reverting only the body of the function turns exactly the three
new cases red and leaves the five old ones green.
The suite also shows 10 unrelated failures in
test_do_format_code.pyon currentmaster under 3.10 -- those are the #360 regression, which is not touched here; I
sent #369 for it. The set of failures is byte-for-byte the same before and
after this change.