Add improved docstring processing

CHANGES.md

@@ -10,6 +10,8 @@
 
 <!-- Changes that affect Black's style -->
 
+- Format docstrings to have consistent quote placement (#2885)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->

docs/the_black_code_style/future_style.md

@@ -49,3 +49,9 @@ plain strings. User-made splits are respected when they do not exceed the line l
 limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
+
+### Improved docstring processing
+
+_Black_ will ensure docstrings are formatted consistently, by removing extra blank lines
+at the beginning and end of docstrings, ensuring the opening and closing quotes are on
+their own lines and collapsing docstrings with a single line of text down to one line.

src/black/linegen.py

@@ -273,7 +273,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
 
             if is_multiline_string(leaf):
                 indent = " " * 4 * self.current_line.depth
-                docstring = fix_docstring(docstring, indent)
+                docstring = fix_docstring(docstring, indent, self.mode.preview)
             else:
                 docstring = docstring.strip()
 

src/black/strings.py

@@ -60,7 +60,7 @@ def lines_with_leading_tabs_expanded(s: str) -> List[str]:
     return lines
 
 
-def fix_docstring(docstring: str, prefix: str) -> str:
+def fix_docstring(docstring: str, prefix: str, preview: bool) -> str:
     # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
     if not docstring:
         return ""
@@ -81,7 +81,19 @@ def fix_docstring(docstring: str, prefix: str) -> str:
                 trimmed.append(prefix + stripped_line)
             else:
                 trimmed.append("")
-    return "\n".join(trimmed)
+    if not preview:
+        return "\n".join(trimmed)
+    # Remove extra blank lines at the ends
+    if all(not line or line.isspace() for line in trimmed):
+        return ""
+    for end in (0, -1):
+        while not trimmed[end] or trimmed[end].isspace():
+            trimmed.pop(end)
+    trimmed[0] = prefix + trimmed[0].strip()
+    # Make single-line docstring single-lined
+    if len(trimmed) == 1:
+        return trimmed[0]
+    return "\n".join(("", *trimmed, prefix))
 
 
 def get_string_prefix(string: str) -> str:

tests/data/comments.py

@@ -4,7 +4,8 @@
 #
 # Has many lines. Many, many lines.
 # Many, many, many lines.
-"""Module docstring.
+"""
+Module docstring.
 
 Possibly also many, many lines.
 """
@@ -30,7 +31,8 @@
 
 
 def function(default=None):
-    """Docstring comes first.
+    """
+    Docstring comes first.
 
     Possibly many lines.
     """

tests/data/comments_non_breaking_space.py

@@ -10,9 +10,10 @@
 square = Square(4) # type: Optional[Square]
 
 def function(a:int=42):
-    """ This docstring is already formatted
-       a
-       b
+    """
+    This docstring is already formatted
+    a
+    b
     """
     #    There's a NBSP + 3 spaces before
     #    And 4 spaces on the next line
@@ -35,7 +36,8 @@ def function(a:int=42):
 
 
 def function(a: int = 42):
-    """This docstring is already formatted
+    """
+    This docstring is already formatted
     a
     b
     """

tests/data/docstring_no_string_normalization_preview.py

@@ -0,0 +1,241 @@
+class ALonelyClass:
+    '''
+    A multiline class docstring.
+    '''
+    def AnEquallyLonelyMethod(self):
+        '''
+        A multiline method docstring'''
+        pass
+
+
+def one_function():
+    '''This is a docstring with a single line of text.'''
+    pass
+
+
+def shockingly_the_quotes_are_normalized():
+    '''This is a multiline docstring.
+    This is a multiline docstring.
+    This is a multiline docstring.
+    '''
+    pass
+
+
+def foo():
+  """This is a docstring with             
+  some lines of text here
+  """
+  return
+
+
+def baz():
+  '''"This" is a string with some
+  embedded "quotes"'''
+  return
+
+
+def poit():
+  """
+  Lorem ipsum dolor sit amet.       
+
+  Consectetur adipiscing elit:
+   - sed do eiusmod tempor incididunt ut labore
+   - dolore magna aliqua
+     - enim ad minim veniam
+     - quis nostrud exercitation ullamco laboris nisi
+   - aliquip ex ea commodo consequat
+  """
+  pass
+
+
+def under_indent():
+  """
+  These lines are indented in a way that does not
+make sense.
+  """
+  pass
+
+
+def over_indent():
+  """
+  This has a shallow indent
+    - But some lines are deeper
+    - And the closing quote is too deep
+    """
+  pass
+
+
+def single_line():
+    """But with a newline after it!
+
+    """
+    pass
+
+
+def this():
+    r"""
+    'hey ho'
+    """
+
+
+def that():
+  """ "hey yah" """
+
+
+def and_that():
+  """
+  "hey yah" """
+
+
+def and_this():
+  ''' 
+  "hey yah"'''
+
+
+def believe_it_or_not_this_is_in_the_py_stdlib(): ''' 
+"hey yah"'''
+
+
+def shockingly_the_quotes_are_normalized_v2():
+    '''
+    Docstring Docstring Docstring
+    '''
+    pass
+
+
+def backslash_space():
+    '\ '
+
+
+def multiline_backslash_1():
+  '''
+  hey\there\
+  \ '''
+
+
+def multiline_backslash_2():
+  '''
+  hey there \ '''
+
+
+def multiline_backslash_3():
+  '''
+  already escaped \\ '''
+
+# output
+
+class ALonelyClass:
+    '''A multiline class docstring.'''
+
+    def AnEquallyLonelyMethod(self):
+        '''A multiline method docstring'''
+        pass
+
+
+def one_function():
+    '''This is a docstring with a single line of text.'''
+    pass
+
+
+def shockingly_the_quotes_are_normalized():
+    '''
+    This is a multiline docstring.
+    This is a multiline docstring.
+    This is a multiline docstring.
+    '''
+    pass
+
+
+def foo():
+    """
+    This is a docstring with
+    some lines of text here
+    """
+    return
+
+
+def baz():
+    '''
+    "This" is a string with some
+    embedded "quotes"
+    '''
+    return
+
+
+def poit():
+    """
+    Lorem ipsum dolor sit amet.
+
+    Consectetur adipiscing elit:
+     - sed do eiusmod tempor incididunt ut labore
+     - dolore magna aliqua
+       - enim ad minim veniam
+       - quis nostrud exercitation ullamco laboris nisi
+     - aliquip ex ea commodo consequat
+    """
+    pass
+
+
+def under_indent():
+    """
+    These lines are indented in a way that does not
+    make sense.
+    """
+    pass
+
+
+def over_indent():
+    """
+    This has a shallow indent
+      - But some lines are deeper
+      - And the closing quote is too deep
+    """
+    pass
+
+
+def single_line():
+    """But with a newline after it!"""
+    pass
+
+
+def this():
+    r"""'hey ho'"""
+
+
+def that():
+    """ "hey yah" """
+
+
+def and_that():
+    """ "hey yah" """
+
+
+def and_this():
+    '''"hey yah"'''
+
+
+def believe_it_or_not_this_is_in_the_py_stdlib():
+    '''"hey yah"'''
+
+
+def shockingly_the_quotes_are_normalized_v2():
+    '''Docstring Docstring Docstring'''
+    pass
+
+
+def backslash_space():
+    '\ '
+
+
+def multiline_backslash_1():
+    '''
+  hey\there\
+  \ '''
+
+
+def multiline_backslash_2():
+    '''hey there \ '''
+
+
+def multiline_backslash_3():
+    '''already escaped \\'''