Standardise newlines after module-level docstrings (#3932)

Co-authored-by: jpy-git <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>

Author: 3 people

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")