Add improved docstring processing

CHANGES.md

@@ -16,6 +16,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Format docstrings to have consistent quote placement (#2885)
 - `if` guards in `case` blocks are now wrapped in parentheses when the line is too long.
   (#4269)
 - Stop moving multiline strings to a new line unless inside brackets (#4289)

docs/the_black_code_style/future_style.md

@@ -323,4 +323,10 @@ with contextlib.ExitStack() as exit_stack:
     ...
 ```
 
+### 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.
+
 (labels/preview-style)=

src/black/__init__.py

@@ -130,7 +130,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.
@@ -211,7 +212,8 @@ def spellcheck_pyproject_toml_keys(
 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.
@@ -227,7 +229,8 @@ def enable_unstable_feature_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.
     """
@@ -823,9 +826,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)
@@ -874,7 +875,8 @@ def reformat_one(
     *,
     lines: Collection[Tuple[int, int]] = (),
 ) -> 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`.
@@ -930,7 +932,8 @@ def format_file_in_place(
     *,
     lines: Collection[Tuple[int, int]] = (),
 ) -> 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.
@@ -997,7 +1000,8 @@ def format_stdin_to_stdout(
     mode: Mode,
     lines: Collection[Tuple[int, int]] = (),
 ) -> 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.
 
@@ -1048,7 +1052,8 @@ def check_stability_and_equivalence(
     mode: Mode,
     lines: Collection[Tuple[int, int]] = (),
 ) -> 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
@@ -1065,7 +1070,8 @@ def format_file_contents(
     mode: Mode,
     lines: Collection[Tuple[int, int]] = (),
 ) -> 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.
@@ -1087,7 +1093,8 @@ def format_file_contents(
 
 
 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.
 
@@ -1113,7 +1120,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:
 
@@ -1150,7 +1158,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
@@ -1162,7 +1171,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.
@@ -1196,7 +1206,8 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
 def format_str(
     src_contents: str, *, mode: Mode, lines: Collection[Tuple[int, int]] = ()
 ) -> 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:
@@ -1223,7 +1234,6 @@ def f(
         arg: str = '',
     ) -> None:
         hey
-
     """
     if lines:
         lines = sanitized_lines(lines, src_contents)
@@ -1292,7 +1302,8 @@ def _format_str_once(
 
 
 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).
@@ -1311,7 +1322,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;
@@ -1583,7 +1595,8 @@ def assert_stable(
 
 @contextmanager
 def nullcontext() -> Iterator[None]:
-    """Return an empty context manager.
+    """
+    Return an empty context manager.
 
     To be used like `nullcontext` in Python 3.7.
     """

src/black/brackets.py

@@ -68,7 +68,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
@@ -139,15 +140,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.
         """
@@ -158,7 +161,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`.
@@ -185,7 +189,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 `:`.
@@ -216,7 +221,8 @@ def get_open_lsqb(self) -> Optional[Leaf]:
 
 
 def is_split_after_delimiter(leaf: Leaf) -> 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.
@@ -230,7 +236,8 @@ def is_split_after_delimiter(leaf: Leaf) -> Priority:
 
 
 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.
@@ -326,7 +333,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.
@@ -354,7 +362,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

@@ -28,7 +28,8 @@ class FileData(NamedTuple):
 
 
 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
@@ -59,7 +60,8 @@ class Cache:
 
     @classmethod
     def read(cls, mode: Mode) -> Self:
-        """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 later should
         resolve the issue.

src/black/comments.py

@@ -31,7 +31,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:
 
@@ -50,7 +51,8 @@ class ProtoComment:
 
 
 def generate_comments(leaf: LN) -> 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
@@ -140,7 +142,8 @@ def normalize_trailing_prefix(leaf: LN, total_consumed: int) -> None:
 
 
 def make_comment(content: str) -> 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.
@@ -177,7 +180,8 @@ def normalize_fmt_off(
 def convert_one_fmt_off_pair(
     node: Node, mode: Mode, lines: Collection[Tuple[int, int]]
 ) -> 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.
     """
@@ -267,7 +271,8 @@ def convert_one_fmt_off_pair(
 def generate_ignored_nodes(
     leaf: Leaf, comment: ProtoComment, mode: Mode
 ) -> 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.
@@ -354,7 +359,9 @@ def _generate_ignored_nodes_from_fmt_skip(
 
 
 def is_fmt_on(container: LN) -> 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

src/black/concurrency.py

@@ -25,7 +25,8 @@
 
 
 def maybe_install_uvloop() -> None:
-    """If our environment has uvloop installed we use it.
+    """
+    If our environment has uvloop installed we use it.
 
     This is called only from command-line entry points to avoid
     interfering with the parent process if Black is used as a library.
@@ -127,7 +128,8 @@ async def schedule_formatting(
     loop: asyncio.AbstractEventLoop,
     executor: "Executor",
 ) -> None:
-    """Run formatting of `sources` in parallel using the provided `executor`.
+    """
+    Run formatting of `sources` in parallel using the provided `executor`.
 
     (Use ProcessPoolExecutors for actual parallelism.)
 

src/black/debug.py

@@ -44,7 +44,8 @@ def visit_default(self, node: LN) -> Iterator[T]:
 
     @classmethod
     def show(cls, code: Union[str, Leaf, Node]) -> None:
-        """Pretty-print the lib2to3 AST of a given string of `code`.
+        """
+        Pretty-print the lib2to3 AST of a given string of `code`.
 
         Convenience method for debugging.
         """