mirror of
https://github.com/astral-sh/ruff.git
synced 2025-11-03 05:13:00 +00:00
376d3caf47
## Summary
This PR modifies our between-statement comment handling such that
comments that are not separated by a statement by any newlines continue
to be treated as leading comments on the statement, but comments that
_are_ separated are instead formatted as trailing comments on the
preceding statement.
See, e.g., the originating snippet:
```python
DEFAULT_TEMPLATE = "flatpages/default.html"
# This view is called from FlatpageFallbackMiddleware.process_response
# when a 404 is raised, which often means CsrfViewMiddleware.process_view
# has not been called even if CsrfViewMiddleware is installed. So we need
# to use @csrf_protect, in case the template needs {% csrf_token %}.
# However, we can't just wrap this view; if no matching flatpage exists,
# or a redirect is required for authentication, the 404 needs to be returned
# without any CSRF checks. Therefore, we only
# CSRF protect the internal implementation.
def flatpage(request, url):
pass
```
Here, we need to ensure that the `def flatpage` is precede by two empty
lines. However, we want those two empty lines to be enforced from the
_end_ of the comment block, _unless_ the comments are directly atop the
`def flatpage`.
I played with this a bit, and I think the simplest conceptual model and
implementation is to instead treat those as trailing comments on the
preceding node. The main difficulty with this approach is that, in order
to be fully compatible with Black, we'd sometimes need to insert
newlines _between_ the preceding node and its trailing comments. See,
e.g.:
```python
def func():
...
# comment
x = 1
```
In this case, we'd need to insert two blank lines between `def func():
...` and `# comment`, but `# comment` is trailing comment on `def
func(): ...`. So, we'd need to take this case into account in the
various nodes that _require_ newlines after them: functions, classes,
and imports. After some discussion, we've opted _not_ to support this,
and just treat these as trailing comments -- so we won't insert newlines
there. This means our handling is still identical to Black's on
Black-formatted code, but avoids moving such trailing comments on
unformatted code.
I dislike that the empty handling is so complex, and that it's split
between so many different nodes, but this is really tricky. Continuing
to treat these as leading comments is very difficult too, since we'd
need to do similar tricks for the leading comment handling in those
nodes, and influencing leading comments is even harder, since they're
all formatted _before_ the node itself.
Closes https://github.com/astral-sh/ruff/issues/6761.
## Test Plan
`cargo test`
Surprisingly, it doesn't change the similarity at all (apart from a
0.00001 change in CPython), but I manually confirmed that it did fix the
originating issue in Django.
Before:
| project | similarity index |
|--------------|------------------|
| cpython | 0.76082 |
| django | 0.99921 |
| transformers | 0.99854 |
| twine | 0.99982 |
| typeshed | 0.99953 |
| warehouse | 0.99648 |
| zulip | 0.99928 |
After:
| project | similarity index |
|--------------|------------------|
| cpython | 0.76081 |
| django | 0.99921 |
| transformers | 0.99854 |
| twine | 0.99982 |
| typeshed | 0.99953 |
| warehouse | 0.99648 |
| zulip | 0.99928 |
|
||
|---|---|---|
| .. | ||
| black_compatibility@conditional_expression.py.snap | ||
| black_compatibility@miscellaneous__blackd_diff.py.snap | ||
| black_compatibility@miscellaneous__debug_visitor.py.snap | ||
| black_compatibility@miscellaneous__decorators.py.snap | ||
| black_compatibility@miscellaneous__docstring_no_string_normalization.py.snap | ||
| black_compatibility@miscellaneous__docstring_preview_no_string_normalization.py.snap | ||
| black_compatibility@miscellaneous__force_pyi.py.snap | ||
| black_compatibility@miscellaneous__long_strings_flag_disabled.py.snap | ||
| black_compatibility@miscellaneous__power_op_newline.py.snap | ||
| black_compatibility@miscellaneous__string_quotes.py.snap | ||
| black_compatibility@py_38__pep_572_remove_parens.py.snap | ||
| black_compatibility@py_39__python39.py.snap | ||
| black_compatibility@py_310__pattern_matching_extras.py.snap | ||
| black_compatibility@py_310__pattern_matching_style.py.snap | ||
| black_compatibility@py_310__pep_572_py310.py.snap | ||
| black_compatibility@simple_cases__attribute_access_on_number_literals.py.snap | ||
| black_compatibility@simple_cases__comment_after_escaped_newline.py.snap | ||
| black_compatibility@simple_cases__comments2.py.snap | ||
| black_compatibility@simple_cases__comments6.py.snap | ||
| black_compatibility@simple_cases__comments9.py.snap | ||
| black_compatibility@simple_cases__composition.py.snap | ||
| black_compatibility@simple_cases__composition_no_trailing_comma.py.snap | ||
| black_compatibility@simple_cases__docstring_preview.py.snap | ||
| black_compatibility@simple_cases__expression.py.snap | ||
| black_compatibility@simple_cases__fmtonoff.py.snap | ||
| black_compatibility@simple_cases__fmtonoff4.py.snap | ||
| black_compatibility@simple_cases__fmtonoff5.py.snap | ||
| black_compatibility@simple_cases__fmtpass_imports.py.snap | ||
| black_compatibility@simple_cases__fmtskip5.py.snap | ||
| black_compatibility@simple_cases__function.py.snap | ||
| black_compatibility@simple_cases__function2.py.snap | ||
| black_compatibility@simple_cases__ignore_pyi.py.snap | ||
| black_compatibility@simple_cases__multiline_consecutive_open_parentheses_ignore.py.snap | ||
| black_compatibility@simple_cases__power_op_spacing.py.snap | ||
| black_compatibility@simple_cases__remove_await_parens.py.snap | ||
| black_compatibility@simple_cases__remove_except_parens.py.snap | ||
| black_compatibility@simple_cases__remove_for_brackets.py.snap | ||
| black_compatibility@simple_cases__return_annotation_brackets.py.snap | ||
| black_compatibility@simple_cases__torture.py.snap | ||
| black_compatibility@simple_cases__trailing_comma_optional_parens3.py.snap | ||
| black_compatibility@simple_cases__trailing_commas_in_leading_parts.py.snap | ||
| black_compatibility@simple_cases__tupleassign.py.snap | ||
| black_compatibility@simple_cases__whitespace.py.snap | ||
| format@carriage_return__string.py.snap | ||
| format@docstring.py.snap | ||
| format@expression__annotated_assign.py.snap | ||
| format@expression__attribute.py.snap | ||
| format@expression__binary.py.snap | ||
| format@expression__binary_implicit_string.py.snap | ||
| format@expression__boolean_operation.py.snap | ||
| format@expression__bytes.py.snap | ||
| format@expression__call.py.snap | ||
| format@expression__compare.py.snap | ||
| format@expression__dict.py.snap | ||
| format@expression__dict_comp.py.snap | ||
| format@expression__fstring.py.snap | ||
| format@expression__generator_exp.py.snap | ||
| format@expression__if.py.snap | ||
| format@expression__lambda.py.snap | ||
| format@expression__list.py.snap | ||
| format@expression__list_comp.py.snap | ||
| format@expression__named_expr.py.snap | ||
| format@expression__set_comp.py.snap | ||
| format@expression__slice.py.snap | ||
| format@expression__split_empty_brackets.py.snap | ||
| format@expression__starred.py.snap | ||
| format@expression__string.py.snap | ||
| format@expression__tuple.py.snap | ||
| format@expression__unary.py.snap | ||
| format@expression__unsplittable.py.snap | ||
| format@expression__yield.py.snap | ||
| format@expression__yield_from.py.snap | ||
| format@fmt_on_off__comments.py.snap | ||
| format@fmt_on_off__empty_file.py.snap | ||
| format@fmt_on_off__fmt_off_docstring.py.snap | ||
| format@fmt_on_off__form_feed.py.snap | ||
| format@fmt_on_off__indent.py.snap | ||
| format@fmt_on_off__last_statement.py.snap | ||
| format@fmt_on_off__mixed_space_and_tab.py.snap | ||
| format@fmt_on_off__newlines.py.snap | ||
| format@fmt_on_off__no_fmt_on.py.snap | ||
| format@fmt_on_off__off_on_off_on.py.snap | ||
| format@fmt_on_off__simple.py.snap | ||
| format@fmt_on_off__trailing_comments.py.snap | ||
| format@fmt_on_off__yapf.py.snap | ||
| format@fmt_skip__decorators.py.snap | ||
| format@fmt_skip__docstrings.py.snap | ||
| format@fmt_skip__match.py.snap | ||
| format@fmt_skip__or_else.py.snap | ||
| format@fmt_skip__parentheses.py.snap | ||
| format@fmt_skip__type_params.py.snap | ||
| format@newlines.py.snap | ||
| format@parentheses__call_chains.py.snap | ||
| format@parentheses__nested.py.snap | ||
| format@parentheses__opening_parentheses_comment_empty.py.snap | ||
| format@parentheses__opening_parentheses_comment_value.py.snap | ||
| format@skip_magic_trailing_comma.py.snap | ||
| format@statement__ann_assign.py.snap | ||
| format@statement__assert.py.snap | ||
| format@statement__assign.py.snap | ||
| format@statement__aug_assign.py.snap | ||
| format@statement__break.py.snap | ||
| format@statement__class_definition.py.snap | ||
| format@statement__delete.py.snap | ||
| format@statement__ellipsis.pyi.snap | ||
| format@statement__for.py.snap | ||
| format@statement__function.py.snap | ||
| format@statement__global.py.snap | ||
| format@statement__if.py.snap | ||
| format@statement__import.py.snap | ||
| format@statement__import_from.py.snap | ||
| format@statement__match.py.snap | ||
| format@statement__nonlocal.py.snap | ||
| format@statement__raise.py.snap | ||
| format@statement__return.py.snap | ||
| format@statement__return_annotation.py.snap | ||
| format@statement__top_level.py.snap | ||
| format@statement__top_level.pyi.snap | ||
| format@statement__try.py.snap | ||
| format@statement__type_alias.py.snap | ||
| format@statement__while.py.snap | ||
| format@statement__with.py.snap | ||
| format@tab_width.py.snap | ||
| format@trailing_comments.py.snap | ||
| format@trivia.py.snap | ||