Skip to content

fix: keep two blank lines between a module docstring and a following definition - #370

Merged
weibullguy merged 3 commits into
PyCQA:masterfrom
Eljees:fix/350-module-docstring-blank-lines
Aug 10, 2026
Merged

fix: keep two blank lines between a module docstring and a following definition#370
weibullguy merged 3 commits into
PyCQA:masterfrom
Eljees:fix/350-module-docstring-blank-lines

Conversation

@Eljees

@Eljees Eljees commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Closes #350.

A module docstring followed directly by a class or a def gets one blank line,
where PEP 8 asks for two. _get_module_docstring_newlines() in format.py takes
no arguments and returns a hard-coded 1.

Its neighbour _get_class_docstring_newlines() already handles the same situation:
it scans forward and returns 2 when it finds is_definition_line(tokens[j]).
This change gives the module function the same shape -- skip NL/NEWLINE/INDENT/
DEDENT, return 2 for a decorator or a definition line, 1 otherwise.

The project agrees with PEP 8 everywhere else. Put anything between the docstring
and the class and the two blank lines survive untouched:

"""Doc."""

import os


class Foo:  # docformatter leaves this alone
    pass

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.2 is written as "One blank
line 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 an expected but no source,
and test_module_docstring_newlines called the function with no arguments and
compared 1 == 1, so they were not exercising anything. They now carry real
sources, and the test builds tokens and calls (tokens, index) -- the same shape
as test_get_docstring_newlines next to it. Three new cases cover def, class and
decorated def.

Verification

On e154acb, Python 3.10.12: tests/formatter/test_format_functions.py goes from
35 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.py on current
master 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.

Eljees and others added 3 commits August 8, 2026 23:56
…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>
@weibullguy
weibullguy merged commit 29230b5 into PyCQA:master Aug 10, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The docformatter removes blank line against PEP8 (conflicts with Ruff (Black))

2 participants