mirrors/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-09-26 20:10:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Implement Black's rules around newlines before and after class docstrings (#6209)

Browse source 
## Summary

Black allows up to one blank line _before_ a class docstring, and
enforces one blank line _after_ a class docstring. This PR implements
that handling. The cases in
`crates/ruff_python_formatter/resources/test/fixtures/ruff/statement/class_definition.py`
match Black identically.
This commit is contained in:
Charlie Marsh 2023-08-01 13:33:01 -04:00 • committed by GitHub
parent 5e41f2fc7d
commit a82eb9544c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 224 additions and 503 deletions
Download patch file Download diff file Expand all files Collapse all files

49
crates/ruff_python_formatter/resources/test/fixtures/ruff/statement/class_definition.py vendored
View file

@ -43,3 +43,52 @@ class TestTrailingComment2: # trailing comment
pass pass
class Test:
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
"""Docstring"""
x = 1
class Test:
"""Docstring"""
# comment
x = 1
class Test:
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
"""Docstring"""
x = 1
class Test:
"""Docstring"""
# comment
x = 1

72
crates/ruff_python_formatter/src/statement/suite.rs
View file

@ -1,6 +1,6 @@
use ruff_formatter::{write, FormatOwnedWithRule, FormatRefWithRule, FormatRuleWithOptions}; use ruff_formatter::{write, FormatOwnedWithRule, FormatRefWithRule, FormatRuleWithOptions};
use ruff_python_ast::helpers::is_compound_statement; use ruff_python_ast::helpers::is_compound_statement;
use ruff_python_ast::{Ranged, Stmt, Suite}; use ruff_python_ast::{self as ast, Constant, Expr, Ranged, Stmt, Suite};
use ruff_python_trivia::{lines_after, lines_before, skip_trailing_trivia}; use ruff_python_trivia::{lines_after, lines_before, skip_trailing_trivia};
use crate::context::{NodeLevel, WithNodeLevel}; use crate::context::{NodeLevel, WithNodeLevel};
@ -54,12 +54,13 @@ impl FormatRule<Suite, PyFormatContext<'_>> for FormatSuite {
let mut f = WithNodeLevel::new(node_level, f); let mut f = WithNodeLevel::new(node_level, f);
if matches!(self.kind, SuiteKind::Other) // Format the first statement in the body, which often has special formatting rules.
&& is_class_or_function_definition(first) let mut last = first;
&& !comments.has_leading_comments(first) match self.kind {
{ SuiteKind::Other => {
// Add an empty line for any nested functions or classes defined within non-function if is_class_or_function_definition(first) && !comments.has_leading_comments(first) {
// or class compound statements, e.g., this is stable formatting: // Add an empty line for any nested functions or classes defined within
// non-function or class compound statements, e.g., this is stable formatting:
// ```python // ```python
// if True: // if True:
// //
@ -68,10 +69,49 @@ impl FormatRule<Suite, PyFormatContext<'_>> for FormatSuite {
// ``` // ```
write!(f, [empty_line()])?; write!(f, [empty_line()])?;
} }
write!(f, [first.format()])?;
}
SuiteKind::Class if is_docstring(first) => {
if !comments.has_leading_comments(first) && lines_before(first.start(), source) > 1
{
// Allow up to one empty line before a class docstring, e.g., this is
// stable formatting:
// ```python
// class Test:
//
// """Docstring"""
// ```
write!(f, [empty_line()])?;
}
write!(f, [first.format()])?; write!(f, [first.format()])?;
let mut last = first; // Enforce an empty line after a class docstring, e.g., these are both stable
// formatting:
// ```python
// class Test:
// """Docstring"""
//
// ...
//
//
// class Test:
//
// """Docstring"""
//
// ...
// ```
if let Some(second) = iter.next() {
// Format the subsequent statement immediately. This rule takes precedence
// over the rules in the loop below (and most of them won't apply anyway,
// e.g., we know the first statement isn't an import).
write!(f, [empty_line(), second.format()])?;
last = second;
}
}
_ => {
write!(f, [first.format()])?;
}
}
for statement in iter { for statement in iter {
if is_class_or_function_definition(last) || is_class_or_function_definition(statement) { if is_class_or_function_definition(last) || is_class_or_function_definition(statement) {
@ -182,6 +222,20 @@ const fn is_import_definition(stmt: &Stmt) -> bool {
matches!(stmt, Stmt::Import(_) | Stmt::ImportFrom(_)) matches!(stmt, Stmt::Import(_) | Stmt::ImportFrom(_))
} }
fn is_docstring(stmt: &Stmt) -> bool {
let Stmt::Expr(ast::StmtExpr { value, .. }) = stmt else {
return false;
};
matches!(
value.as_ref(),
Expr::Constant(ast::ExprConstant {
value: Constant::Str(..),
..
})
)
}
impl FormatRuleWithOptions<Suite, PyFormatContext<'_>> for FormatSuite { impl FormatRuleWithOptions<Suite, PyFormatContext<'_>> for FormatSuite {
type Options = SuiteKind; type Options = SuiteKind;

485
crates/ruff_python_formatter/tests/snapshots/black_compatibility@simple_cases__class_methods_new_line.py.snap
View file

@ -1,485 +0,0 @@
---
source: crates/ruff_python_formatter/tests/fixtures.rs
input_file: crates/ruff_python_formatter/resources/test/fixtures/black/simple_cases/class_methods_new_line.py
---
## Input
```py
class ClassSimplest:
pass
class ClassWithSingleField:
a = 1
class ClassWithJustTheDocstring:
"""Just a docstring."""
class ClassWithInit:
def __init__(self):
pass
class ClassWithTheDocstringAndInit:
"""Just a docstring."""
def __init__(self):
pass
class ClassWithInitAndVars:
cls_var = 100
def __init__(self):
pass
class ClassWithInitAndVarsAndDocstring:
"""Test class"""
cls_var = 100
def __init__(self):
pass
class ClassWithDecoInit:
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVars:
cls_var = 100
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstring:
"""Test class"""
cls_var = 100
@deco
def __init__(self):
pass
class ClassSimplestWithInner:
class Inner:
pass
class ClassSimplestWithInnerWithDocstring:
class Inner:
"""Just a docstring."""
def __init__(self):
pass
class ClassWithSingleFieldWithInner:
a = 1
class Inner:
pass
class ClassWithJustTheDocstringWithInner:
"""Just a docstring."""
class Inner:
pass
class ClassWithInitWithInner:
class Inner:
pass
def __init__(self):
pass
class ClassWithInitAndVarsWithInner:
cls_var = 100
class Inner:
pass
def __init__(self):
pass
class ClassWithInitAndVarsAndDocstringWithInner:
"""Test class"""
cls_var = 100
class Inner:
pass
def __init__(self):
pass
class ClassWithDecoInitWithInner:
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsWithInner:
cls_var = 100
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstringWithInner:
"""Test class"""
cls_var = 100
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstringWithInner2:
"""Test class"""
class Inner:
pass
cls_var = 100
@deco
def __init__(self):
pass
```
## Black Differences
```diff
--- Black
+++ Ruff
@@ -31,7 +31,6 @@
class ClassWithInitAndVarsAndDocstring:
"""Test class"""
-
cls_var = 100
def __init__(self):
@@ -54,7 +53,6 @@
class ClassWithDecoInitAndVarsAndDocstring:
"""Test class"""
-
cls_var = 100
@deco
@@ -109,7 +107,6 @@
class ClassWithInitAndVarsAndDocstringWithInner:
"""Test class"""
-
cls_var = 100
class Inner:
@@ -141,7 +138,6 @@
class ClassWithDecoInitAndVarsAndDocstringWithInner:
"""Test class"""
-
cls_var = 100
class Inner:
```
## Ruff Output
```py
class ClassSimplest:
pass
class ClassWithSingleField:
a = 1
class ClassWithJustTheDocstring:
"""Just a docstring."""
class ClassWithInit:
def __init__(self):
pass
class ClassWithTheDocstringAndInit:
"""Just a docstring."""
def __init__(self):
pass
class ClassWithInitAndVars:
cls_var = 100
def __init__(self):
pass
class ClassWithInitAndVarsAndDocstring:
"""Test class"""
cls_var = 100
def __init__(self):
pass
class ClassWithDecoInit:
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVars:
cls_var = 100
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstring:
"""Test class"""
cls_var = 100
@deco
def __init__(self):
pass
class ClassSimplestWithInner:
class Inner:
pass
class ClassSimplestWithInnerWithDocstring:
class Inner:
"""Just a docstring."""
def __init__(self):
pass
class ClassWithSingleFieldWithInner:
a = 1
class Inner:
pass
class ClassWithJustTheDocstringWithInner:
"""Just a docstring."""
class Inner:
pass
class ClassWithInitWithInner:
class Inner:
pass
def __init__(self):
pass
class ClassWithInitAndVarsWithInner:
cls_var = 100
class Inner:
pass
def __init__(self):
pass
class ClassWithInitAndVarsAndDocstringWithInner:
"""Test class"""
cls_var = 100
class Inner:
pass
def __init__(self):
pass
class ClassWithDecoInitWithInner:
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsWithInner:
cls_var = 100
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstringWithInner:
"""Test class"""
cls_var = 100
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstringWithInner2:
"""Test class"""
class Inner:
pass
cls_var = 100
@deco
def __init__(self):
pass
```
## Black Output
```py
class ClassSimplest:
pass
class ClassWithSingleField:
a = 1
class ClassWithJustTheDocstring:
"""Just a docstring."""
class ClassWithInit:
def __init__(self):
pass
class ClassWithTheDocstringAndInit:
"""Just a docstring."""
def __init__(self):
pass
class ClassWithInitAndVars:
cls_var = 100
def __init__(self):
pass
class ClassWithInitAndVarsAndDocstring:
"""Test class"""
cls_var = 100
def __init__(self):
pass
class ClassWithDecoInit:
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVars:
cls_var = 100
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstring:
"""Test class"""
cls_var = 100
@deco
def __init__(self):
pass
class ClassSimplestWithInner:
class Inner:
pass
class ClassSimplestWithInnerWithDocstring:
class Inner:
"""Just a docstring."""
def __init__(self):
pass
class ClassWithSingleFieldWithInner:
a = 1
class Inner:
pass
class ClassWithJustTheDocstringWithInner:
"""Just a docstring."""
class Inner:
pass
class ClassWithInitWithInner:
class Inner:
pass
def __init__(self):
pass
class ClassWithInitAndVarsWithInner:
cls_var = 100
class Inner:
pass
def __init__(self):
pass
class ClassWithInitAndVarsAndDocstringWithInner:
"""Test class"""
cls_var = 100
class Inner:
pass
def __init__(self):
pass
class ClassWithDecoInitWithInner:
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsWithInner:
cls_var = 100
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstringWithInner:
"""Test class"""
cls_var = 100
class Inner:
pass
@deco
def __init__(self):
pass
class ClassWithDecoInitAndVarsAndDocstringWithInner2:
"""Test class"""
class Inner:
pass
cls_var = 100
@deco
def __init__(self):
pass
```

103
crates/ruff_python_formatter/tests/snapshots/format@statement__class_definition.py.snap
View file

@ -49,6 +49,55 @@ class TestTrailingComment2: # trailing comment
pass pass
class Test:
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
"""Docstring"""
x = 1
class Test:
"""Docstring"""
# comment
x = 1
class Test:
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
"""Docstring"""
x = 1
class Test:
"""Docstring"""
# comment
x = 1
``` ```
## Output ## Output
@ -114,6 +163,60 @@ class TestTrailingComment1(Aaaa): # trailing comment
class TestTrailingComment2: # trailing comment class TestTrailingComment2: # trailing comment
pass pass
class Test:
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
"""Docstring"""
x = 1
class Test:
"""Docstring"""
# comment
x = 1
class Test:
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
# comment
"""Docstring"""
class Test:
"""Docstring"""
x = 1
class Test:
"""Docstring"""
# comment
x = 1
``` ```