Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardise newlines after module-level docstrings #3932

Merged
merged 5 commits into from
Oct 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions scripts/make_width_table.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
pip install -U wcwidth

"""

import sys
from os.path import basename, dirname, join
from typing import Iterable, Tuple
Expand Down
1 change: 1 addition & 0 deletions src/black/cache.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
"""Caching of formatted files with feature-based invalidation."""

import hashlib
import os
import pickle
Expand Down
1 change: 1 addition & 0 deletions src/black/linegen.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""
Generating lines of code.
"""

import sys
from dataclasses import replace
from enum import Enum, auto
Expand Down
9 changes: 9 additions & 0 deletions src/black/lines.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions src/black/mode.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
1 change: 1 addition & 0 deletions src/black/numerics.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""
Formatting numeric literals.
"""

from blib2to3.pytree import Leaf


Expand Down
1 change: 1 addition & 0 deletions src/black/parsing.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""
Parse Python code and perform AST validation.
"""

import ast
import sys
from typing import Iterable, Iterator, List, Set, Tuple
Expand Down
1 change: 1 addition & 0 deletions src/black/report.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""
Summarize Black runs to users.
"""

from dataclasses import dataclass
from enum import Enum
from pathlib import Path
Expand Down
1 change: 1 addition & 0 deletions src/black/rusty.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
1 change: 1 addition & 0 deletions src/black/trans.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""
String transformers that can split and merge strings.
"""

import re
from abc import ABC, abstractmethod
from collections import defaultdict
Expand Down
26 changes: 26 additions & 0 deletions tests/data/cases/module_docstring_1.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# flags: --preview
"""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
68 changes: 68 additions & 0 deletions tests/data/cases/module_docstring_2.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# flags: --preview
"""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
8 changes: 8 additions & 0 deletions tests/data/cases/module_docstring_3.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# flags: --preview
"""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
9 changes: 9 additions & 0 deletions tests/data/cases/module_docstring_4.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# flags: --preview
"""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
2 changes: 2 additions & 0 deletions tests/data/miscellaneous/string_quotes.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
''''''

'\''
'"'
"'"
Expand Down Expand Up @@ -59,6 +60,7 @@
# output

""""""

"'"
'"'
"'"
Expand Down