Commit Graph
14 Commits
Author SHA1 Message Date
apathydevil f1edf755c2 Fix the multiline string example in Known Deviations from Black (#30447)
## Summary

The documentation had an incorrect formatting example for multiline
strings when using ruff and black. Found under
`docs/formatter/black.md`. Changed the examples to match what I found on
my own testing environment with Black 26.10.1 and Ruff 0.17.5. Changed
the `# Input`, `# Black` and `# Ruff` blocks accordingly.

My comment on issue #28930:
https://github.com/astral-sh/ruff/issues/28930#issuecomment-6894925305

Fixes #28930

## Notes to reviewers

I changed the `""""` to the more common `"""` since the extra `"` would
get wrapped into the string. I didn't change the paragraph below the
examples, because I wasn't sure if that's still accurate, since Black 26
does move the `"""` onto the `call(` line.
This is my first pull request. I'm happy about any feedback and will
change anything accordingly. I'm excited to contribute to a project I
use.
2026-11-18 10:24:15 -05:00
zaniebotandZanie Blue c23d6967c9 Clarify documentation and correct stale guidance (#29374)
The documentation has stale configuration guidance and a few examples
that do not work as written. Clarify the prose and correct editor
configuration precedence, user-level configuration discovery, rule
descriptions, and the tutorial and configuration examples.

---------

Co-authored-by: Zanie Blue <zanie@openai.com>
2026-10-15 13:36:53 -05:00
Brent Westbrook 3f5a91cecf Stabilize pragma comment width handling (#28795)
Summary
--

I wasn't really planning to do a full stabilization pass, but I quickly skimmed through `preview.rs`
and remembered that the isort pragma change was kind a bug fix but technically breaking and thought
we might want to stabilize it.

This PR stabilizes the isort pragma comment width handling introduced in #27313, along with the
related pragma handling for `E501` and `W505` from #24071. There was a comment about also
stabilizing the related formatter preview feature on the function from #24071, so that is stabilized
here too.

I'm fine holding off on this, especially if the formatter change is a better fit for the 2027 style
guide. Like I said above, I mostly wanted to stabilize the isort change, but that snowballed a bit
since the helpers were shared.

Test Plan
--

Updated existing snapshots
2026-10-09 12:26:57 -04:00
DylanandBrent Westbrook b53460799b 2026 Ruff Formatter Style (#22735)
Styles stabilized:

-
[`avoid_parens_for_long_as_captures`](https://github.com/astral-sh/ruff/pull/22743)
-
[`remove_parens_around_except_types`](https://github.com/astral-sh/ruff/pull/22741)
-
[`allow_newline_after_block_open`](https://github.com/astral-sh/ruff/pull/22742)
- [`no_chaperone_for_escaped_quote_in_triple_quoted_docstring
`](https://github.com/astral-sh/ruff/pull/22739)
- [`blank_line_before_decorated_class_in_stub
`](https://github.com/astral-sh/ruff/pull/22740)
-
[`parenthesize_lambda_bodies`](https://github.com/astral-sh/ruff/pull/22744)

To-do:

- [x] Change target branch to 0.15 release branch
- [x] Update documentation
- [x] Remove empty commit

---------

Co-authored-by: Brent Westbrook <brentrwestbrook@gmail.com>
2026-02-03 10:01:37 -05:00
Brent Westbrook dec4154c8a Document known lambda formatting deviations from Black (#21954)
Summary
--

Following #8179, we now format long lambda expressions a bit more like
Black, preferring to keep long parameter lists on a single line, but we
go one step further to break the body itself across multiple lines and
parenthesize it if it's still too long. This PR documents both the
stable deviation that breaks parameters across multiple lines, and the
new preview deviation that breaks the body instead.

I also fixed a couple of typos in the section immediately above my
addition.

Test Plan
--

I tested all of the snippets here against `main` for the preview
behavior, our playground for the stable behavior, and Black's playground
for their behavior
2025-12-12 12:57:09 -05:00
Micha Reiser ff87ea8d42 Update black deviations (#15928) 2025-02-04 14:04:24 +00:00
Dhruv Manilawala f706c3fdf2 Add f-string formatting to the docs (#15367)
Revive https://github.com/astral-sh/ruff/pull/15341 as it got removed
from the latest rebase in https://github.com/astral-sh/ruff/pull/15238.
2025-01-09 10:20:06 +01:00
Micha Reiser 7821206b7b Update Black deviations to reflect 2025 style changes (#15127) 2025-01-09 10:20:06 +01:00
Micha Reiser 110193af57 Fix tuple expansion example in formatter compatibility document (#13313) 2024-09-10 17:47:12 +00:00
Micha Reiser adfd78e05a Correct parenthesized long nested-expressions example to match Ruff's output (#12153) 2024-07-03 10:03:08 +02:00
Micha Reiser 12486315fb Move deviations from formatter README to documentation (#10444)
## Summary

#10151 documented the deviations between Ruff and Black with the new
2024 style guide in the `ruff-python-formatter/README.md`. However,
that's not the documentation shown
on the website when navigating to [intentional
deviations](https://docs.astral.sh/ruff/formatter/black/).

This PR streamlines the `ruff-python-formatter/README.md` and links to
the documentation on the website instead of repeating the same content.
The PR also makes the 2024 style guide deviations available on the
website documentation.

## Test Plan

I built the documentation locally and verified that the 2024 style guide
known deviations are now shown on the website.
2024-03-18 08:22:28 +00:00
Charlie Marsh 036b6bc0bd Document context manager breaking deviation vs. Black (#8597)
Closes https://github.com/astral-sh/ruff/issues/8180.
Closes https://github.com/astral-sh/ruff/issues/8580.
Closes https://github.com/astral-sh/ruff/issues/7441.
2023-11-10 04:32:29 +00:00
Charlie Marsh 88c8b47326 Avoid introducing new parentheses in annotated assignments (#8233)
## Summary

We decided to avoid changing this in
https://github.com/astral-sh/ruff/issues/7315, but it's been reported
multiple times (e.g., in https://github.com/astral-sh/ruff/issues/8226,
also on Discord). I suggest we change it to improve compatibility. In
general, it also seems to lend itself to better code style.

Closes #8188 
Closes #8226

## Test Plan

Shows improvements for CPython, home-assistant, Poetry, and typeshed.

Before:

| project | similarity index | total files | changed files |

|----------------|------------------:|------------------:|------------------:|
| cpython | 0.75803 | 1799 | 1647 |
| django | 0.99983 | 2772 | 34 |
| home-assistant | 0.99953 | 10596 | 186 |
| poetry | 0.99891 | 317 | 17 |
| transformers | 0.99966 | 2657 | 330 |
| twine | 1.00000 | 33 | 0 |
| typeshed | 0.99978 | 3669 | 20 |
| warehouse | 0.99977 | 654 | 13 |
| zulip | 0.99970 | 1459 | 22 |

After:

| project | similarity index | total files | changed files |

|----------------|------------------:|------------------:|------------------:|
| cpython | 0.75804 | 1799 | 1647 |
| django | 0.99983 | 2772 | 34 |
| home-assistant | 0.99960 | 10596 | 156 |
| poetry | 0.99897 | 317 | 17 |
| transformers | 0.99966 | 2657 | 330 |
| twine | 1.00000 | 33 | 0 |
| typeshed | 0.99980 | 3669 | 18 |
| warehouse | 0.99977 | 654 | 13 |
| zulip | 0.99970 | 1459 | 22 |
2023-10-25 22:51:50 -04:00
Charlie Marsh f6d6200aae Rework the documentation to incorporate the Ruff formatter (#7732)
## Summary

This PR updates our documentation for the upcoming formatter release.

Broadly, the documentation is now structured as follows:

- Overview
- Tutorial
- Installing Ruff
- The Ruff Linter
    - Overview
    - `ruff check`
    - Rule selection
    - Error suppression
    - Exit codes
- The Ruff Formatter
    - Overview
    - `ruff format`
    - Philosophy
    - Configuration
    - Format suppression
    - Exit codes
    - Black compatibility
        - Known deviations
- Configuring Ruff
    - pyproject.toml
    - File discovery
    - Configuration discovery
    - CLI
    - Shell autocompletion
- Preview
- Rules
- Settings
- Integrations
    - `pre-commit`
    - VS Code
    - LSP
    - PyCharm
    - GitHub Actions
- FAQ
- Contributing

The major changes include:

- Removing the "Usage" section from the docs, and instead folding that
information into "Integrations" and the new Linter and Formatter
sections.
- Breaking up "Configuration" into "Configuring Ruff" (for generic
configuration), and new Linter- and Formatter-specific sections.
- Updating all example configurations to use `[tool.ruff.lint]` and
`[tool.ruff.format]`.

My suggestion is to pull and build the docs locally, and review by
reading them in the browser rather than trying to parse all the code
changes.

Closes https://github.com/astral-sh/ruff/issues/7235.

Closes https://github.com/astral-sh/ruff/issues/7647.
2023-10-20 23:08:26 +00:00