Add improved docstring processing

CHANGES.md

@@ -14,6 +14,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Format docstrings to have consistent quote placement (#2885)
 - Enforce empty lines before classes and functions with sticky leading comments (#3302)
 - Implicitly concatenated strings used as function args are now wrapped inside
   parentheses (#3307)

docs/the_black_code_style/future_style.md

@@ -63,6 +63,12 @@ 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.
+
 ### Improved empty line management
 
 1.  _Black_ will remove newlines in the beginning of new code blocks, i.e. when the

src/black/__init__.py

@@ -121,7 +121,8 @@ def from_configuration(
 def read_pyproject_toml(
     ctx: click.Context, param: click.Parameter, value: Optional[str]
 ) -> Optional[str]:
-    """Inject Black configuration from "pyproject.toml" into defaults in `ctx`.
+    """
+    Inject Black configuration from "pyproject.toml" into defaults in `ctx`.
 
     Returns the path to a successfully found and read configuration file, None
     otherwise.
@@ -167,7 +168,8 @@ def read_pyproject_toml(
 def target_version_option_callback(
     c: click.Context, p: Union[click.Option, click.Parameter], v: Tuple[str, ...]
 ) -> List[TargetVersion]:
-    """Compute the target versions from a --target-version flag.
+    """
+    Compute the target versions from a --target-version flag.
 
     This is its own function because mypy couldn't infer the type correctly
     when it was a lambda, causing mypyc trouble.
@@ -176,7 +178,8 @@ def target_version_option_callback(
 
 
 def re_compile_maybe_verbose(regex: str) -> Pattern[str]:
-    """Compile a regular expression string in `regex`.
+    """
+    Compile a regular expression string in `regex`.
 
     If it contains newlines, use verbose mode.
     """
@@ -695,9 +698,7 @@ def get_sources(
 def path_empty(
     src: Sized, msg: str, quiet: bool, verbose: bool, ctx: click.Context
 ) -> None:
-    """
-    Exit if there is no `src` provided for formatting
-    """
+    """Exit if there is no `src` provided for formatting"""
     if not src:
         if verbose or not quiet:
             out(msg)
@@ -734,7 +735,8 @@ def reformat_code(
 def reformat_one(
     src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
 ) -> None:
-    """Reformat a single file under `src` without spawning child processes.
+    """
+    Reformat a single file under `src` without spawning child processes.
 
     `fast`, `write_back`, and `mode` options are passed to
     :func:`format_file_in_place` or :func:`format_stdin_to_stdout`.
@@ -789,7 +791,8 @@ def format_file_in_place(
     write_back: WriteBack = WriteBack.NO,
     lock: Any = None,  # multiprocessing.Manager().Lock() is some crazy proxy
 ) -> bool:
-    """Format file under `src` path. Return True if changed.
+    """
+    Format file under `src` path. Return True if changed.
 
     If `write_back` is DIFF, write a diff to stdout. If it is YES, write reformatted
     code to the file.
@@ -853,7 +856,8 @@ def format_stdin_to_stdout(
     write_back: WriteBack = WriteBack.NO,
     mode: Mode,
 ) -> bool:
-    """Format file on stdin. Return True if changed.
+    """
+    Format file on stdin. Return True if changed.
 
     If content is None, it's read from sys.stdin.
 
@@ -900,7 +904,8 @@ def format_stdin_to_stdout(
 def check_stability_and_equivalence(
     src_contents: str, dst_contents: str, *, mode: Mode
 ) -> None:
-    """Perform stability and equivalence checks.
+    """
+    Perform stability and equivalence checks.
 
     Raise AssertionError if source and destination contents are not
     equivalent, or if a second pass of the formatter would format the
@@ -911,7 +916,8 @@ def check_stability_and_equivalence(
 
 
 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
-    """Reformat contents of a file and return new contents.
+    """
+    Reformat contents of a file and return new contents.
 
     If `fast` is False, additionally confirm that the reformatted code is
     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
@@ -934,7 +940,8 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
 
 
 def validate_cell(src: str, mode: Mode) -> None:
-    """Check that cell does not already contain TransformerManager transformations,
+    """
+    Check that cell does not already contain TransformerManager transformations,
     or non-Python cell magics, which might cause tokenizer_rt to break because of
     indentations.
 
@@ -960,7 +967,8 @@ def validate_cell(src: str, mode: Mode) -> None:
 
 
 def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
-    """Format code in given cell of Jupyter notebook.
+    """
+    Format code in given cell of Jupyter notebook.
 
     General idea is:
 
@@ -997,7 +1005,8 @@ def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
 
 
 def validate_metadata(nb: MutableMapping[str, Any]) -> None:
-    """If notebook is marked as non-Python, don't format it.
+    """
+    If notebook is marked as non-Python, don't format it.
 
     All notebook metadata fields are optional, see
     https://nbformat.readthedocs.io/en/latest/format_description.html. So
@@ -1009,7 +1018,8 @@ def validate_metadata(nb: MutableMapping[str, Any]) -> None:
 
 
 def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
-    """Format Jupyter notebook.
+    """
+    Format Jupyter notebook.
 
     Operate cell-by-cell, only on code cells, only for Python notebooks.
     If the ``.ipynb`` originally had a trailing newline, it'll be preserved.
@@ -1038,7 +1048,8 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
 
 
 def format_str(src_contents: str, *, mode: Mode) -> str:
-    """Reformat a string and return new contents.
+    """
+    Reformat a string and return new contents.
 
     `mode` determines formatting options, such as how many characters per line are
     allowed.  Example:
@@ -1065,7 +1076,6 @@ def f(
         arg: str = '',
     ) -> None:
         hey
-
     """
     dst_contents = _format_str_once(src_contents, mode=mode)
     # Forced second pass to work around optional trailing commas (becoming
@@ -1110,7 +1120,8 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
 
 
 def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
-    """Return a tuple of (decoded_contents, encoding, newline).
+    """
+    Return a tuple of (decoded_contents, encoding, newline).
 
     `newline` is either CRLF or LF but `decoded_contents` is decoded with
     universal newlines (i.e. only contains LF).
@@ -1129,7 +1140,8 @@ def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
 def get_features_used(  # noqa: C901
     node: Node, *, future_imports: Optional[Set[str]] = None
 ) -> Set[Feature]:
-    """Return a set of (relatively) new Python features used in this file.
+    """
+    Return a set of (relatively) new Python features used in this file.
 
     Currently looking for:
     - f-strings;
@@ -1352,15 +1364,17 @@ def assert_stable(src: str, dst: str, mode: Mode) -> None:
 
 @contextmanager
 def nullcontext() -> Iterator[None]:
-    """Return an empty context manager.
+    """
+    Return an empty context manager.
 
     To be used like `nullcontext` in Python 3.7.
     """
     yield
 
 
 def patch_click() -> None:
-    """Make Click not crash on Python 3.6 with LANG=C.
+    """
+    Make Click not crash on Python 3.6 with LANG=C.
 
     On certain misconfigured environments, Python 3 selects the ASCII encoding as the
     default which restricts paths that it can access during the lifetime of the

src/black/brackets.py

@@ -74,7 +74,8 @@ class BracketTracker:
     invisible: List[Leaf] = field(default_factory=list)
 
     def mark(self, leaf: Leaf) -> None:
-        """Mark `leaf` with bracket-related metadata. Keep track of delimiters.
+        """
+        Mark `leaf` with bracket-related metadata. Keep track of delimiters.
 
         All leaves receive an int `bracket_depth` field that stores how deep
         within brackets a given leaf is. 0 means there are no enclosing brackets
@@ -128,15 +129,17 @@ def any_open_brackets(self) -> bool:
         return bool(self.bracket_match)
 
     def max_delimiter_priority(self, exclude: Iterable[LeafID] = ()) -> Priority:
-        """Return the highest priority of a delimiter found on the line.
+        """
+        Return the highest priority of a delimiter found on the line.
 
         Values are consistent with what `is_split_*_delimiter()` return.
         Raises ValueError on no delimiters.
         """
         return max(v for k, v in self.delimiters.items() if k not in exclude)
 
     def delimiter_count_with_priority(self, priority: Priority = 0) -> int:
-        """Return the number of delimiters with the given `priority`.
+        """
+        Return the number of delimiters with the given `priority`.
 
         If no `priority` is passed, defaults to max priority on the line.
         """
@@ -147,7 +150,8 @@ def delimiter_count_with_priority(self, priority: Priority = 0) -> int:
         return sum(1 for p in self.delimiters.values() if p == priority)
 
     def maybe_increment_for_loop_variable(self, leaf: Leaf) -> bool:
-        """In a for loop, or comprehension, the variables are often unpacks.
+        """
+        In a for loop, or comprehension, the variables are often unpacks.
 
         To avoid splitting on the comma in this situation, increase the depth of
         tokens between `for` and `in`.
@@ -174,7 +178,8 @@ def maybe_decrement_after_for_loop_variable(self, leaf: Leaf) -> bool:
         return False
 
     def maybe_increment_lambda_arguments(self, leaf: Leaf) -> bool:
-        """In a lambda expression, there might be more than one argument.
+        """
+        In a lambda expression, there might be more than one argument.
 
         To avoid splitting on the comma in this situation, increase the depth of
         tokens between `lambda` and `:`.
@@ -205,7 +210,8 @@ def get_open_lsqb(self) -> Optional[Leaf]:
 
 
 def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
-    """Return the priority of the `leaf` delimiter, given a line break after it.
+    """
+    Return the priority of the `leaf` delimiter, given a line break after it.
 
     The delimiter priorities returned here are from those delimiters that would
     cause a line break after themselves.
@@ -219,7 +225,8 @@ def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Pri
 
 
 def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
-    """Return the priority of the `leaf` delimiter, given a line break before it.
+    """
+    Return the priority of the `leaf` delimiter, given a line break before it.
 
     The delimiter priorities returned here are from those delimiters that would
     cause a line break before themselves.
@@ -315,7 +322,8 @@ def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Pr
 
 
 def max_delimiter_priority_in_atom(node: LN) -> Priority:
-    """Return maximum delimiter priority inside `node`.
+    """
+    Return maximum delimiter priority inside `node`.
 
     This is specific to atoms with contents contained in a pair of parentheses.
     If `node` isn't an atom or there are no enclosing parentheses, returns 0.
@@ -343,7 +351,8 @@ def max_delimiter_priority_in_atom(node: LN) -> Priority:
 
 
 def get_leaves_inside_matching_brackets(leaves: Sequence[Leaf]) -> Set[LeafID]:
-    """Return leaves that are inside matching brackets.
+    """
+    Return leaves that are inside matching brackets.
 
     The input `leaves` can have non-matching brackets at the head or tail parts.
     Matching brackets are included.

src/black/cache.py

@@ -19,7 +19,8 @@
 
 
 def get_cache_dir() -> Path:
-    """Get the cache directory used by black.
+    """
+    Get the cache directory used by black.
 
     Users can customize this directory on all systems using `BLACK_CACHE_DIR`
     environment variable. By default, the cache directory is the user cache directory
@@ -38,7 +39,8 @@ def get_cache_dir() -> Path:
 
 
 def read_cache(mode: Mode) -> Cache:
-    """Read the cache if it exists and is well formed.
+    """
+    Read the cache if it exists and is well formed.
 
     If it is not well formed, the call to write_cache later should resolve the issue.
     """
@@ -66,7 +68,8 @@ def get_cache_info(path: Path) -> CacheInfo:
 
 
 def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
-    """Split an iterable of paths in `sources` into two sets.
+    """
+    Split an iterable of paths in `sources` into two sets.
 
     The first contains paths of files that modified on disk or are not in the
     cache. The other contains paths to non-modified files.

src/black/comments.py

@@ -34,7 +34,8 @@
 
 @dataclass
 class ProtoComment:
-    """Describes a piece of syntax that is a comment.
+    """
+    Describes a piece of syntax that is a comment.
 
     It's not a :class:`blib2to3.pytree.Leaf` so that:
 
@@ -51,7 +52,8 @@ class ProtoComment:
 
 
 def generate_comments(leaf: LN, *, preview: bool) -> Iterator[Leaf]:
-    """Clean the prefix of the `leaf` and generate comments from it, if any.
+    """
+    Clean the prefix of the `leaf` and generate comments from it, if any.
 
     Comments in lib2to3 are shoved into the whitespace prefix.  This happens
     in `pgen2/driver.py:Driver.parse_tokens()`.  This was a brilliant implementation
@@ -115,7 +117,8 @@ def list_comments(
 
 
 def make_comment(content: str, *, preview: bool) -> str:
-    """Return a consistently formatted comment from the given `content` string.
+    """
+    Return a consistently formatted comment from the given `content` string.
 
     All comments (except for "##", "#!", "#:", '#'") should have a single
     space between the hash sign and the content.
@@ -148,7 +151,8 @@ def normalize_fmt_off(node: Node, *, preview: bool) -> None:
 
 
 def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
-    """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
+    """
+    Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
 
     Returns True if a pair was converted.
     """
@@ -217,7 +221,8 @@ def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
 def generate_ignored_nodes(
     leaf: Leaf, comment: ProtoComment, *, preview: bool
 ) -> Iterator[LN]:
-    """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
+    """
+    Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 
     If comment is skip, returns leaf only.
     Stops at the end of the block.
@@ -296,7 +301,8 @@ def _generate_ignored_nodes_from_fmt_skip(
 
 
 def is_fmt_on(container: LN, preview: bool) -> bool:
-    """Determine whether formatting is switched on within a container.
+    """
+    Determine whether formatting is switched on within a container.
     Determined by whether the last `# fmt:` comment is `on` or `off`.
     """
     fmt_on = False