From 595024b9caeaf69df09f3450c07e5bac15cc01b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Sun, 8 Oct 2023 12:08:05 +0200 Subject: [PATCH 1/4] Standardise newlines after module-level docstrings Co-authored-by: jpy-git --- CHANGES.md | 1 + scripts/make_width_table.py | 1 + src/black/cache.py | 1 + src/black/linegen.py | 1 + src/black/lines.py | 9 +++ src/black/mode.py | 1 + src/black/numerics.py | 1 + src/black/parsing.py | 1 + src/black/report.py | 1 + src/black/rusty.py | 1 + src/black/trans.py | 1 + tests/data/miscellaneous/string_quotes.py | 2 + tests/data/module_docstring_1.py | 25 +++++++++ tests/data/module_docstring_2.py | 67 +++++++++++++++++++++++ 14 files changed, 113 insertions(+) create mode 100644 tests/data/module_docstring_1.py create mode 100644 tests/data/module_docstring_2.py diff --git a/CHANGES.md b/CHANGES.md index 062a195717d..c4d27cb706b 100644 --- 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) +- Require one empty line after module-level docstrings. (#3932) ### Configuration diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py index 30fd32c34b0..061fdc8d95d 100644 --- a/scripts/make_width_table.py +++ b/scripts/make_width_table.py @@ -15,6 +15,7 @@ pip install -U wcwidth """ + 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 77f66cc34a9..2a50cc18f79 100644 --- a/src/black/cache.py +++ b/src/black/cache.py @@ -1,4 +1,5 @@ """Caching of formatted files with feature-based invalidation.""" + import hashlib import os import pickle diff --git a/src/black/linegen.py b/src/black/linegen.py index bdc4ee54ab2..faeb3ba664c 100644 --- a/src/black/linegen.py +++ b/src/black/linegen.py @@ -1,6 +1,7 @@ """ Generating lines of code. """ + import sys from dataclasses import replace from enum import Enum, auto diff --git a/src/black/lines.py b/src/black/lines.py index 71b657a0654..14754d7532f 100644 --- a/src/black/lines.py +++ b/src/black/lines.py @@ -550,6 +550,15 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock: 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, diff --git a/src/black/mode.py b/src/black/mode.py index 30c5d2f1b2f..baf886abb7f 100644 --- 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() + module_docstring_newlines = auto() class Deprecated(UserWarning): diff --git a/src/black/numerics.py b/src/black/numerics.py index 879e5b2cf36..67ac8595fcc 100644 --- a/src/black/numerics.py +++ b/src/black/numerics.py @@ -1,6 +1,7 @@ """ Formatting numeric literals. """ + from blib2to3.pytree import Leaf diff --git a/src/black/parsing.py b/src/black/parsing.py index e98e019cac6..273cae5fa72 100644 --- a/src/black/parsing.py +++ b/src/black/parsing.py @@ -1,6 +1,7 @@ """ Parse Python code and perform AST validation. """ + import ast import sys from typing import Final, Iterable, Iterator, List, Set, Tuple diff --git a/src/black/report.py b/src/black/report.py index a507671e4c0..89899f2f389 100644 --- a/src/black/report.py +++ b/src/black/report.py @@ -1,6 +1,7 @@ """ Summarize Black runs to users. """ + 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 84a80b5a2c2..ebd4c052d1f 100644 --- 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. """ + from typing import Generic, TypeVar, Union T = TypeVar("T") diff --git a/src/black/trans.py b/src/black/trans.py index c0cc92613ac..a2bff7f227a 100644 --- a/src/black/trans.py +++ b/src/black/trans.py @@ -1,6 +1,7 @@ """ String transformers that can split and merge strings. """ + import re from abc import ABC, abstractmethod from collections import defaultdict diff --git a/tests/data/miscellaneous/string_quotes.py b/tests/data/miscellaneous/string_quotes.py index 3384241f4ad..6ec088ac79b 100644 --- a/tests/data/miscellaneous/string_quotes.py +++ b/tests/data/miscellaneous/string_quotes.py @@ -1,4 +1,5 @@ '''''' + '\'' '"' "'" @@ -59,6 +60,7 @@ # output """""" + "'" '"' "'" diff --git a/tests/data/module_docstring_1.py b/tests/data/module_docstring_1.py new file mode 100644 index 00000000000..5751154f7f0 --- /dev/null +++ b/tests/data/module_docstring_1.py @@ -0,0 +1,25 @@ +"""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/module_docstring_2.py b/tests/data/module_docstring_2.py new file mode 100644 index 00000000000..368e5ef90ad --- /dev/null +++ b/tests/data/module_docstring_2.py @@ -0,0 +1,67 @@ +"""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 From b519246d8c342fdb70d7ba7e62a285d90003c968 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Sun, 8 Oct 2023 17:06:15 +0200 Subject: [PATCH 2/4] Move tests to ``preview`` directory --- tests/data/{ => preview}/module_docstring_1.py | 0 tests/data/{ => preview}/module_docstring_2.py | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename tests/data/{ => preview}/module_docstring_1.py (100%) rename tests/data/{ => preview}/module_docstring_2.py (100%) diff --git a/tests/data/module_docstring_1.py b/tests/data/preview/module_docstring_1.py similarity index 100% rename from tests/data/module_docstring_1.py rename to tests/data/preview/module_docstring_1.py diff --git a/tests/data/module_docstring_2.py b/tests/data/preview/module_docstring_2.py similarity index 100% rename from tests/data/module_docstring_2.py rename to tests/data/preview/module_docstring_2.py From 5e049779856da9e1b2091cac6d3e33d0411975d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Sun, 8 Oct 2023 17:07:36 +0200 Subject: [PATCH 3/4] Add two more tests --- tests/data/preview/module_docstring_3.py | 7 +++++++ tests/data/preview/module_docstring_4.py | 8 ++++++++ 2 files changed, 15 insertions(+) create mode 100644 tests/data/preview/module_docstring_3.py create mode 100644 tests/data/preview/module_docstring_4.py diff --git a/tests/data/preview/module_docstring_3.py b/tests/data/preview/module_docstring_3.py new file mode 100644 index 00000000000..3d0058dd554 --- /dev/null +++ b/tests/data/preview/module_docstring_3.py @@ -0,0 +1,7 @@ +"""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/preview/module_docstring_4.py b/tests/data/preview/module_docstring_4.py new file mode 100644 index 00000000000..b1720078f71 --- /dev/null +++ b/tests/data/preview/module_docstring_4.py @@ -0,0 +1,8 @@ +"""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 From 03b72813dc761185774d53a561a131cec80387ae Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Mon, 9 Oct 2023 18:56:18 -0700 Subject: [PATCH 4/4] Move tests --- tests/data/{preview => cases}/module_docstring_1.py | 1 + tests/data/{preview => cases}/module_docstring_2.py | 1 + tests/data/{preview => cases}/module_docstring_3.py | 1 + tests/data/{preview => cases}/module_docstring_4.py | 1 + 4 files changed, 4 insertions(+) rename tests/data/{preview => cases}/module_docstring_1.py (94%) rename tests/data/{preview => cases}/module_docstring_2.py (99%) rename tests/data/{preview => cases}/module_docstring_3.py (90%) rename tests/data/{preview => cases}/module_docstring_4.py (90%) diff --git a/tests/data/preview/module_docstring_1.py b/tests/data/cases/module_docstring_1.py similarity index 94% rename from tests/data/preview/module_docstring_1.py rename to tests/data/cases/module_docstring_1.py index 5751154f7f0..d5897b4db60 100644 --- a/tests/data/preview/module_docstring_1.py +++ b/tests/data/cases/module_docstring_1.py @@ -1,3 +1,4 @@ +# flags: --preview """Single line module-level docstring should be followed by single newline.""" diff --git a/tests/data/preview/module_docstring_2.py b/tests/data/cases/module_docstring_2.py similarity index 99% rename from tests/data/preview/module_docstring_2.py rename to tests/data/cases/module_docstring_2.py index 368e5ef90ad..e1f81b4d76b 100644 --- a/tests/data/preview/module_docstring_2.py +++ b/tests/data/cases/module_docstring_2.py @@ -1,3 +1,4 @@ +# flags: --preview """I am a very helpful module docstring. Lorem ipsum dolor sit amet, consectetur adipiscing elit, diff --git a/tests/data/preview/module_docstring_3.py b/tests/data/cases/module_docstring_3.py similarity index 90% rename from tests/data/preview/module_docstring_3.py rename to tests/data/cases/module_docstring_3.py index 3d0058dd554..0631e136a3d 100644 --- a/tests/data/preview/module_docstring_3.py +++ b/tests/data/cases/module_docstring_3.py @@ -1,3 +1,4 @@ +# flags: --preview """Single line module-level docstring should be followed by single newline.""" a = 1 diff --git a/tests/data/preview/module_docstring_4.py b/tests/data/cases/module_docstring_4.py similarity index 90% rename from tests/data/preview/module_docstring_4.py rename to tests/data/cases/module_docstring_4.py index b1720078f71..515174dcc04 100644 --- a/tests/data/preview/module_docstring_4.py +++ b/tests/data/cases/module_docstring_4.py @@ -1,3 +1,4 @@ +# flags: --preview """Single line module-level docstring should be followed by single newline.""" a = 1