E530 Implement new rule D219. by larsgeb · Pull Request #22912 · astral-sh/ruff · GitHub
[go: up one dir, main page]
Skip to content

Implement new rule D219. #22912

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.

Sign up for GitHub

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

Jump to bottom
Open
larsgeb wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Implement new rule D219. #22912

larsgeb wants to merge 1 commit into from
+439 −6

Conversation

@larsgeb
Copy link
@larsgeb larsgeb commented Jan 28, 2026

Hi all,

I was looking for a way to format single-line docstrings with ruff according to some projects internal guidelines, and found this isn't possible at the moment. The issue was raised before in ruff, so I decided it'd be worth it to see if I could get it in. Disclaimer: This MR contains LLM generated code, so treat with caution. It still is reviewed and tested by me, both inside the ruff container and in our codebase. Since it has already reformatted our codebase appropriately, I am happy with not merging it, but would like to give anyone the chance, if the code is up to par.

What happens in this MR:

  • add a preview pydocstyle rule (D219) that flags one-line docstrings and enforces a multi-line layout;
  • provide an unsafe fix that expands docstrings in a D212- (default) or D213-compatible format;
  • add fixtures and snapshots for module, class, function, same-line docstrings, and whitespace preservation;
  • mark D219 as incompatible with D200 to prevent collapse/expand ping-pong.

I (and my project) actually prefer D213-style fixes, but by the lower number D212 takes precedence. Happy to flip it around.

The issue #4174 describes the use case well: some projects prefer multi-line docstrings everywhere to reduce churn when docstrings expand over time. This implements the inverse of D200 as a preview rule. The motivation in my personal projects was that it simply looks more homogeneous scanning through large files, and I find it more legible if all docstrings are formatted the same.

To achieve the behaviour, we now have:

  • new violation: OneLineDocstringShouldBeMultiLine (D219, preview)
  • fix respects original opener/closer and indentation
  • fix format:
    • with D213: """\nSummary.\n"""
    • with D212: """Summary.\n"""

Tested by:

  • INSTA_UPDATE=always cargo test -p ruff_linter pydocstyle::tests::rules -- D219
  • INSTA_UPDATE=always cargo test -p ruff_linter pydocstyle::tests::multi_line_docstring_with_summary_on_second_line

The fix is marked unsafe because it changes docstring formatting, which can affect docstring-parsing tools. The rule is added as preview and should require --preview to enable

@ntBre
Copy link
Contributor
ntBre commented Jan 28, 2026

Thanks for working on this and for the thorough writeup! I think we'll need to make some decisions here before reviewing the rule. For example, if I understand correctly, this rule directly conflicts with D200, so we'll need some plan for managing the conflict or to consider a different approach such as making D200 itself configurable. I see that you updated the list of incompatible rules, but I think we'd prefer to avoid adding more incompatible rules if possible.

I'd also be curious to hear if others would find this rule useful. #4174 doesn't seem to have collected much support over the years, but maybe that's because it was closed.

@ntBre ntBre added rule Implementing or modifying a lint rule needs-decision Awaiting a decision from a maintainer labels Jan 28, 2026
@larsgeb
Copy link
Author
larsgeb commented Jan 28, 2026

Thanks for the quick check on the viability of the PR, @ntBre. It indeed conflicts with D200 (as it is the inverse) and I see how you might want to avoid incompatibles.

Happy to rework if there's consensus.

@larsgeb
Copy link
Author
larsgeb commented Jan 28, 2026

Looking at how configuration is passed through ruff, I can add something that flips the D200 style:

lint.pydocstyle.one-line-docstring-style = "single" | "multi"

Interpreting your D200 rule, I guess this would be the preferred way!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

needs-decision Awaiting a decision from a maintainer rule Implementing or modifying a lint rule

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@larsgeb @ntBre
0