Standardise newlines after module-level docstrings (#3932)

Co-authored-by: jpy-git <josephyoung.jpy@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

CHANGES.md

@@ -19,6 +19,7 @@
 - Long type hints are now wrapped in parentheses and properly indented when split across
   multiple lines (#3899)
 - Magic trailing commas are now respected in return types. (#3916)
+- Require one empty line after module-level docstrings. (#3932)
 
 ### Configuration
 

scripts/make_width_table.py

@@ -15,6 +15,7 @@
     pip install -U wcwidth
 
 """
+
 import sys
 from os.path import basename, dirname, join
 from typing import Iterable, Tuple

src/black/cache.py

@@ -1,4 +1,5 @@
 """Caching of formatted files with feature-based invalidation."""
+
 import hashlib
 import os
 import pickle

src/black/linegen.py

@@ -1,6 +1,7 @@
 """
 Generating lines of code.
 """
+
 import sys
 from dataclasses import replace
 from enum import Enum, auto

src/black/lines.py

@@ -550,6 +550,15 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
             if self.previous_line is None
             else before - previous_after
         )
+        if (
+            Preview.module_docstring_newlines in current_line.mode
+            and self.previous_block
+            and self.previous_block.previous_block is None
+            and len(self.previous_block.original_line.leaves) == 1
+            and self.previous_block.original_line.is_triple_quoted_string
+        ):
+            before = 1
+
         block = LinesBlock(
             mode=self.mode,
             previous_block=self.previous_block,

src/black/mode.py

@@ -187,6 +187,7 @@ class Preview(Enum):
     wrap_multiple_context_managers_in_parens = auto()
     dummy_implementations = auto()
     walrus_subscript = auto()
+    module_docstring_newlines = auto()
 
 
 class Deprecated(UserWarning):

src/black/numerics.py

@@ -1,6 +1,7 @@
 """
 Formatting numeric literals.
 """
+
 from blib2to3.pytree import Leaf
 
 

src/black/parsing.py

@@ -1,6 +1,7 @@
 """
 Parse Python code and perform AST validation.
 """
+
 import ast
 import sys
 from typing import Iterable, Iterator, List, Set, Tuple

src/black/report.py

@@ -1,6 +1,7 @@
 """
 Summarize Black runs to users.
 """
+
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path

src/black/rusty.py

@@ -2,6 +2,7 @@
 
 See https://doc.rust-lang.org/book/ch09-00-error-handling.html.
 """
+
 from typing import Generic, TypeVar, Union
 
 T = TypeVar("T")

src/black/trans.py

@@ -1,6 +1,7 @@
 """
 String transformers that can split and merge strings.
 """
+
 import re
 from abc import ABC, abstractmethod
 from collections import defaultdict

tests/data/cases/module_docstring_1.py

@@ -0,0 +1,26 @@
+# flags: --preview
+"""Single line module-level docstring should be followed by single newline."""
+
+
+
+
+a = 1
+
+
+"""I'm just a string so should be followed by 2 newlines."""
+
+
+
+
+b = 2
+
+# output
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1
+
+
+"""I'm just a string so should be followed by 2 newlines."""
+
+
+b = 2

tests/data/cases/module_docstring_2.py

@@ -0,0 +1,68 @@
+# flags: --preview
+"""I am a very helpful module docstring.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris
+nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate
+velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident,
+sunt in culpa qui officia deserunt mollit anim id est laborum.
+"""
+
+
+
+
+a = 1
+
+
+"""Look at me I'm a docstring...
+
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+........................................................NOT!
+"""
+
+
+
+
+b = 2
+
+# output
+"""I am a very helpful module docstring.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris
+nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate
+velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident,
+sunt in culpa qui officia deserunt mollit anim id est laborum.
+"""
+
+a = 1
+
+
+"""Look at me I'm a docstring...
+
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+........................................................NOT!
+"""
+
+
+b = 2

tests/data/cases/module_docstring_3.py

@@ -0,0 +1,8 @@
+# flags: --preview
+"""Single line module-level docstring should be followed by single newline."""
+a = 1
+
+# output
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1

tests/data/cases/module_docstring_4.py

@@ -0,0 +1,9 @@
+# flags: --preview
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1
+
+# output
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1

tests/data/miscellaneous/string_quotes.py

@@ -1,4 +1,5 @@
 ''''''
+
 '\''
 '"'
 "'"
@@ -59,6 +60,7 @@
 # output
 
 """"""
+
 "'"
 '"'
 "'"