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>

diff --git a/CHANGES.md b/CHANGES.md
index 6ad6308945c6f203937e2d0c29d55c207dd21fcb..a608551815f396cf631d8ca5435b3c946007cc34 100644 (file)
--- a/CHANGES.md
+++ b/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)
 - 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
 
 
 ### Configuration
 

diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
index 30fd32c34b0b35c0d1320f607573ae1d853d7881..061fdc8d95da77d16fbc1617e84a1ccf370fb229 100644 (file)
--- a/scripts/make_width_table.py
+++ b/scripts/make_width_table.py
@@ -15,6 +15,7 @@ You can do this by running:
     pip install -U wcwidth
 
 """
     pip install -U wcwidth
 
 """

+

 import sys
 from os.path import basename, dirname, join
 from typing import Iterable, Tuple
 import sys
 from os.path import basename, dirname, join
 from typing import Iterable, Tuple

diff --git a/src/black/cache.py b/src/black/cache.py
index f7dc64c0bca925e8969f4d97daed47040f98790a..6baa096bacafccc22f66eecb2bbaee9ad3862b25 100644 (file)
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -1,4 +1,5 @@
 """Caching of formatted files with feature-based invalidation."""
 """Caching of formatted files with feature-based invalidation."""

+

 import hashlib
 import os
 import pickle
 import hashlib
 import os
 import pickle

diff --git a/src/black/linegen.py b/src/black/linegen.py
index bdc4ee54ab285351588659f458f804aa212573c2..faeb3ba664c3f8714b3770d6e6e29d125d3263d1 100644 (file)
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1,6 +1,7 @@
 """
 Generating lines of code.
 """
 """
 Generating lines of code.
 """

+

 import sys
 from dataclasses import replace
 from enum import Enum, auto
 import sys
 from dataclasses import replace
 from enum import Enum, auto

diff --git a/src/black/lines.py b/src/black/lines.py
index 71b657a0654802ef0cc80772981c37907ac9c5d0..14754d7532ff4827d2773ae023953a15f8722a07 100644 (file)
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -550,6 +550,15 @@ class EmptyLineTracker:
             if self.previous_line is None
             else before - previous_after
         )
             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,
         block = LinesBlock(
             mode=self.mode,
             previous_block=self.previous_block,

diff --git a/src/black/mode.py b/src/black/mode.py
index 30c5d2f1b2f1577a95606220973bffb628ccffed..baf886abb7f045704ed8ac54611d20c24c9a512e 100644 (file)
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -187,6 +187,7 @@ class Preview(Enum):
     wrap_multiple_context_managers_in_parens = auto()
     dummy_implementations = auto()
     walrus_subscript = auto()
     wrap_multiple_context_managers_in_parens = auto()
     dummy_implementations = auto()
     walrus_subscript = auto()

+    module_docstring_newlines = auto()

 
 
 class Deprecated(UserWarning):
 
 
 class Deprecated(UserWarning):

diff --git a/src/black/numerics.py b/src/black/numerics.py
index 879e5b2cf36a5d37904354668ca965b0ff0d7470..67ac8595fcc6783ea2c6bf9de96d0013044ae496 100644 (file)
--- a/src/black/numerics.py
+++ b/src/black/numerics.py
@@ -1,6 +1,7 @@
 """
 Formatting numeric literals.
 """
 """
 Formatting numeric literals.
 """

+

 from blib2to3.pytree import Leaf
 
 
 from blib2to3.pytree import Leaf
 
 

diff --git a/src/black/parsing.py b/src/black/parsing.py
index 03e767a333beee311a63c05e7cbdb60e69fbc3af..ea282d1805cfea68ccf406e7e92e676de16f5fca 100644 (file)
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -1,6 +1,7 @@
 """
 Parse Python code and perform AST validation.
 """
 """
 Parse Python code and perform AST validation.
 """

+

 import ast
 import sys
 from typing import Iterable, Iterator, List, Set, Tuple
 import ast
 import sys
 from typing import Iterable, Iterator, List, Set, Tuple

diff --git a/src/black/report.py b/src/black/report.py
index a507671e4c0286d9ae0c7b41f86ce802da02c63c..89899f2f38996f309f79dc1225e24bfa8c69767a 100644 (file)
--- a/src/black/report.py
+++ b/src/black/report.py
@@ -1,6 +1,7 @@
 """
 Summarize Black runs to users.
 """
 """
 Summarize Black runs to users.
 """

+

 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path

diff --git a/src/black/rusty.py b/src/black/rusty.py
index 84a80b5a2c223c188b94633d6298e6208441cf5b..ebd4c052d1f37b9eed01d329143c15bfbe0f0e74 100644 (file)
--- a/src/black/rusty.py
+++ b/src/black/rusty.py
@@ -2,6 +2,7 @@
 
 See https://doc.rust-lang.org/book/ch09-00-error-handling.html.
 """
 
 See https://doc.rust-lang.org/book/ch09-00-error-handling.html.
 """

+

 from typing import Generic, TypeVar, Union
 
 T = TypeVar("T")
 from typing import Generic, TypeVar, Union
 
 T = TypeVar("T")

diff --git a/src/black/trans.py b/src/black/trans.py
index c0cc92613acba59996d25dba09701f2137a10985..a2bff7f227adb51bf1afa96242393384041374ed 100644 (file)
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1,6 +1,7 @@
 """
 String transformers that can split and merge strings.
 """
 """
 String transformers that can split and merge strings.
 """

+

 import re
 from abc import ABC, abstractmethod
 from collections import defaultdict
 import re
 from abc import ABC, abstractmethod
 from collections import defaultdict

diff --git a/tests/data/cases/module_docstring_1.py b/tests/data/cases/module_docstring_1.py
new file mode 100644 (file)
index 0000000..d5897b4
--- /dev/null
+++ b/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

diff --git a/tests/data/cases/module_docstring_2.py b/tests/data/cases/module_docstring_2.py
new file mode 100644 (file)
index 0000000..e1f81b4
--- /dev/null
+++ b/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

diff --git a/tests/data/cases/module_docstring_3.py b/tests/data/cases/module_docstring_3.py
new file mode 100644 (file)
index 0000000..0631e13
--- /dev/null
+++ b/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

diff --git a/tests/data/cases/module_docstring_4.py b/tests/data/cases/module_docstring_4.py
new file mode 100644 (file)
index 0000000..515174d
--- /dev/null
+++ b/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

diff --git a/tests/data/miscellaneous/string_quotes.py b/tests/data/miscellaneous/string_quotes.py
index 3384241f4adaf7ad8e1dbff5be6da70e32a40558..6ec088ac79b79a6f135ee53dcd575ac1e608e0c6 100644 (file)
--- a/tests/data/miscellaneous/string_quotes.py
+++ b/tests/data/miscellaneous/string_quotes.py
@@ -1,4 +1,5 @@
 ''''''
 ''''''

+

 '\''
 '"'
 "'"
 '\''
 '"'
 "'"


@@ -59,6 +60,7 @@ f"\"{a}\"{'hello' * b}\"{c}\""
 # output
 
 """"""
 # output
 
 """"""

+

 "'"
 '"'
 "'"
 "'"
 '"'
 "'"