Clean up PEP 257 support

I documented the new behavior, added it to the change log, greatly expanded
tests, added support for inner defs and classes, and added Luka to ACKS.

Fixes #196

diff --git a/README.md b/README.md
index 41ad465359e3ecb3c6c0d866eac1e433f2ca2b95..17c67f71c85dd689fb42db5c1e61684d0a3e351f 100644 (file)
--- a/README.md
+++ b/README.md
@@ -275,9 +275,17 @@ are always reformatted to fit minimal space, this whitespace is lost.
 
 It will also insert proper spacing before and after function definitions.
 It's one line before and after inner functions and two lines before and
 
 It will also insert proper spacing before and after function definitions.
 It's one line before and after inner functions and two lines before and

-after module-level functions.  *Black* will not put empty lines between
-function/class definitions and standalone comments that immediately precede
-the given function/class.
+after module-level functions and classes.  *Black* will not put empty
+lines between function/class definitions and standalone comments that
+immediately precede the given function/class.
+
+*Black* will enforce single empty lines between a class-level docstring
+and the first following field or method.  This conforms to
+[PEP 257](https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings).
+
+*Black* won't insert empty lines after function docstrings unless that
+empty line is required due to an inner function starting immediately
+after.

 
 
 ### Trailing commas
 
 
 ### Trailing commas


@@ -689,6 +697,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * Python grammar pickle caches are stored with the formatting caches, making
   *Black* work in environments where site-packages is not user-writable (#192)
 
 * Python grammar pickle caches are stored with the formatting caches, making
   *Black* work in environments where site-packages is not user-writable (#192)
 

+* *Black* now enforces a PEP 257 empty line after a class-level docstring
+  (and/or fields) and the first method
+

 * fixed invalid code produced when standalone comments were present in a trailer
   that was omitted from line splitting on a large expression (#237)
 
 * fixed invalid code produced when standalone comments were present in a trailer
   that was omitted from line splitting on a large expression (#237)
 


@@ -701,6 +712,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
   a trailer that was omitted from line splitting on a large expression
   (#238)
 
   a trailer that was omitted from line splitting on a large expression
   (#238)
 

+* fixed extra empty line between a class declaration and the first
+  method if no class docstring or fields are present (#219)
+

 
 ### 18.5b0
 
 
 ### 18.5b0
 


@@ -959,6 +973,7 @@ Multiple contributions by:
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
 * [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
 * [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)

+* [Luka Sterbic](mailto:luka.sterbic@gmail.com)

 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)

diff --git a/black.py b/black.py
index 7dc6ef86c1d4b12a4a46bc2c1cd6fe080a12af01..dc67991f2c94d3f1444a56179409eb8c65cfbd9a 100644 (file)
--- a/black.py
+++ b/black.py
@@ -989,14 +989,11 @@ class Line:
 
     @property
     def is_triple_quoted_string(self) -> bool:
 
     @property
     def is_triple_quoted_string(self) -> bool:

-        """Is the line a triple quoted docstring?"""
+        """Is the line a triple quoted string?"""

         return (
             bool(self)
             and self.leaves[0].type == token.STRING
         return (
             bool(self)
             and self.leaves[0].type == token.STRING

-            and (
-                self.leaves[0].value.startswith('"""')
-                or self.leaves[0].value.startswith("'''")
-            )
+            and self.leaves[0].value.startswith(('"""', "'''"))

         )
 
     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
         )
 
     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:


@@ -1257,9 +1254,8 @@ class EmptyLineTracker:
             if self.previous_line.is_decorator:
                 return 0, 0
 
             if self.previous_line.is_decorator:
                 return 0, 0
 

-            if (
-                self.previous_line.is_class
-                and self.previous_line.depth != current_line.depth
+            if self.previous_line.depth < current_line.depth and (
+                self.previous_line.is_class or self.previous_line.is_def

             ):
                 return 0, 0
 
             ):
                 return 0, 0
 

diff --git a/tests/class_blank_parentheses.py b/tests/class_blank_parentheses.py
index d586cacdf31cb93fb862b93fc25fc5a08fbc5ef6..1a5721a288955d3c0b1a284ee675b97d84c15f07 100644 (file)
--- a/tests/class_blank_parentheses.py
+++ b/tests/class_blank_parentheses.py
@@ -48,7 +48,6 @@ def public_func_with_blank_parentheses():
 
 
 def class_under_the_func_with_blank_parentheses():
 
 
 def class_under_the_func_with_blank_parentheses():

-

     class InsideFunc:
         pass
 
     class InsideFunc:
         pass
 

diff --git a/tests/class_methods_new_line.py b/tests/class_methods_new_line.py
index b0982719cc8f3e69ae2d10a0f5855143d3052ee4..9a96ffe49d4695b57d1ce6cd91f7da95923f91ef 100644 (file)
--- a/tests/class_methods_new_line.py
+++ b/tests/class_methods_new_line.py
@@ -1,8 +1,16 @@
 class ClassSimplest:
     pass
 class ClassSimplest:
     pass

+class ClassWithSingleField:
+    a = 1
+class ClassWithJustTheDocstring:
+    """Just a docstring."""

 class ClassWithInit:
     def __init__(self):
         pass
 class ClassWithInit:
     def __init__(self):
         pass

+class ClassWithTheDocstringAndInit:
+    """Just a docstring."""
+    def __init__(self):
+        pass

 class ClassWithInitAndVars:
     cls_var = 100
     def __init__(self):
 class ClassWithInitAndVars:
     cls_var = 100
     def __init__(self):


@@ -12,6 +20,84 @@ class ClassWithInitAndVarsAndDocstring:
     cls_var = 100
     def __init__(self):
         pass
     cls_var = 100
     def __init__(self):
         pass

+class ClassWithDecoInit:
+    @deco
+    def __init__(self):
+        pass
+class ClassWithDecoInitAndVars:
+    cls_var = 100
+    @deco
+    def __init__(self):
+        pass
+class ClassWithDecoInitAndVarsAndDocstring:
+    """Test class"""
+    cls_var = 100
+    @deco
+    def __init__(self):
+        pass
+class ClassSimplestWithInner:
+    class Inner:
+        pass
+class ClassSimplestWithInnerWithDocstring:
+    class Inner:
+        """Just a docstring."""
+        def __init__(self):
+            pass
+class ClassWithSingleFieldWithInner:
+    a = 1
+    class Inner:
+        pass
+class ClassWithJustTheDocstringWithInner:
+    """Just a docstring."""
+    class Inner:
+        pass
+class ClassWithInitWithInner:
+    class Inner:
+        pass
+    def __init__(self):
+        pass
+class ClassWithInitAndVarsWithInner:
+    cls_var = 100
+    class Inner:
+        pass
+    def __init__(self):
+        pass
+class ClassWithInitAndVarsAndDocstringWithInner:
+    """Test class"""
+    cls_var = 100
+    class Inner:
+        pass
+    def __init__(self):
+        pass
+class ClassWithDecoInitWithInner:
+    class Inner:
+        pass
+    @deco
+    def __init__(self):
+        pass
+class ClassWithDecoInitAndVarsWithInner:
+    cls_var = 100
+    class Inner:
+        pass
+    @deco
+    def __init__(self):
+        pass
+class ClassWithDecoInitAndVarsAndDocstringWithInner:
+    """Test class"""
+    cls_var = 100
+    class Inner:
+        pass
+    @deco
+    def __init__(self):
+        pass
+class ClassWithDecoInitAndVarsAndDocstringWithInner2:
+    """Test class"""
+    class Inner:
+        pass
+    cls_var = 100
+    @deco
+    def __init__(self):
+        pass

 
 
 # output
 
 
 # output


@@ -21,11 +107,26 @@ class ClassSimplest:
     pass
 
 
     pass
 
 

+class ClassWithSingleField:
+    a = 1
+
+
+class ClassWithJustTheDocstring:
+    """Just a docstring."""
+
+

 class ClassWithInit:
     def __init__(self):
         pass
 
 
 class ClassWithInit:
     def __init__(self):
         pass
 
 

+class ClassWithTheDocstringAndInit:
+    """Just a docstring."""
+
+    def __init__(self):
+        pass
+
+

 class ClassWithInitAndVars:
     cls_var = 100
 
 class ClassWithInitAndVars:
     cls_var = 100
 


@@ -40,3 +141,130 @@ class ClassWithInitAndVarsAndDocstring:
 
     def __init__(self):
         pass
 
     def __init__(self):
         pass

+
+
+class ClassWithDecoInit:
+    @deco
+    def __init__(self):
+        pass
+
+
+class ClassWithDecoInitAndVars:
+    cls_var = 100
+
+    @deco
+    def __init__(self):
+        pass
+
+
+class ClassWithDecoInitAndVarsAndDocstring:
+    """Test class"""
+
+    cls_var = 100
+
+    @deco
+    def __init__(self):
+        pass
+
+
+class ClassSimplestWithInner:
+    class Inner:
+        pass
+
+
+class ClassSimplestWithInnerWithDocstring:
+    class Inner:
+        """Just a docstring."""
+
+        def __init__(self):
+            pass
+
+
+class ClassWithSingleFieldWithInner:
+    a = 1
+
+    class Inner:
+        pass
+
+
+class ClassWithJustTheDocstringWithInner:
+    """Just a docstring."""
+
+    class Inner:
+        pass
+
+
+class ClassWithInitWithInner:
+    class Inner:
+        pass
+
+    def __init__(self):
+        pass
+
+
+class ClassWithInitAndVarsWithInner:
+    cls_var = 100
+
+    class Inner:
+        pass
+
+    def __init__(self):
+        pass
+
+
+class ClassWithInitAndVarsAndDocstringWithInner:
+    """Test class"""
+
+    cls_var = 100
+
+    class Inner:
+        pass
+
+    def __init__(self):
+        pass
+
+
+class ClassWithDecoInitWithInner:
+    class Inner:
+        pass
+
+    @deco
+    def __init__(self):
+        pass
+
+
+class ClassWithDecoInitAndVarsWithInner:
+    cls_var = 100
+
+    class Inner:
+        pass
+
+    @deco
+    def __init__(self):
+        pass
+
+
+class ClassWithDecoInitAndVarsAndDocstringWithInner:
+    """Test class"""
+
+    cls_var = 100
+
+    class Inner:
+        pass
+
+    @deco
+    def __init__(self):
+        pass
+
+
+class ClassWithDecoInitAndVarsAndDocstringWithInner2:
+    """Test class"""
+
+    class Inner:
+        pass
+
+    cls_var = 100
+
+    @deco
+    def __init__(self):
+        pass

diff --git a/tests/function2.py b/tests/function2.py
index e262e0588c8373e4cbab50f389e4c2c5d6c48db9..0c9da12c38845c529287d05492e3b8a8546483e6 100644 (file)
--- a/tests/function2.py
+++ b/tests/function2.py
@@ -12,6 +12,15 @@ def f(
         very_long_argument_name2=very_long_value_for_the_argument,
         **kwargs,
     )
         very_long_argument_name2=very_long_value_for_the_argument,
         **kwargs,
     )

+def g():
+    "Docstring."
+    def inner():
+        pass
+    print("Inner defs should breathe a little.")
+def h():
+    def inner():
+        pass
+    print("Inner defs should breathe a little.")

 
 # output
 
 
 # output
 


@@ -26,3 +35,19 @@ def f(a, **kwargs) -> A:
         very_long_argument_name2=very_long_value_for_the_argument,
         **kwargs,
     )
         very_long_argument_name2=very_long_value_for_the_argument,
         **kwargs,
     )

+
+
+def g():
+    "Docstring."
+
+    def inner():
+        pass
+
+    print("Inner defs should breathe a little.")
+
+
+def h():
+    def inner():
+        pass
+
+    print("Inner defs should breathe a little.")