Skip to content

Commit 50a4d7f

Browse files
ntBreMichaReiser
ntBre
and
MichaReiser
authored
Document the new category selectors (#27906)
Summary -- This includes the user-facing updates to our linter docs and selection settings to accompany #27666. Test Plan -- A few existing snapshot updates but mostly users reading this --------- Co-authored-by: Micha Reiser <micha@reiser.io>
1 parent ada8795 commit 50a4d7f

4 files changed

Lines changed: 141 additions & 9 deletions

File tree

‎crates/ruff/tests/config.rs‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,17 @@ fn lint_select() {
1313
exit_code: 0
1414
----- stdout -----
1515
A list of rule codes or prefixes to enable. Prefixes can specify exact
16-
rules (like `F841`), entire categories (like `F`), or anything in
16+
rules (like `F841`), entire groups (like `F`), or anything in
1717
between.
1818
1919
When breaking ties between enabled and disabled rules (via `select` and
2020
`ignore`, respectively), more specific prefixes override less
2121
specific prefixes. `ignore` takes precedence over `select` if the
2222
same prefix appears in both.
2323
24+
In preview, categories like `correctness` and `suspicious` can be used
25+
in addition to rule codes and linter group prefixes.
26+
2427
Default value: See https://docs.astral.sh/ruff/default-rules/ or run `ruff check --show-settings --isolated`
2528
Type: list[RuleSelector]
2629
Example usage:
@@ -42,7 +45,7 @@ fn lint_select_json() {
4245
exit_code: 0
4346
----- stdout -----
4447
{
45-
"doc": "A list of rule codes or prefixes to enable. Prefixes can specify exact\nrules (like `F841`), entire categories (like `F`), or anything in\nbetween.\n\nWhen breaking ties between enabled and disabled rules (via `select` and\n`ignore`, respectively), more specific prefixes override less\nspecific prefixes. `ignore` takes precedence over `select` if the\nsame prefix appears in both.",
48+
"doc": "A list of rule codes or prefixes to enable. Prefixes can specify exact\nrules (like `F841`), entire groups (like `F`), or anything in\nbetween.\n\nWhen breaking ties between enabled and disabled rules (via `select` and\n`ignore`, respectively), more specific prefixes override less\nspecific prefixes. `ignore` takes precedence over `select` if the\nsame prefix appears in both.\n\nIn preview, categories like `correctness` and `suspicious` can be used\nin addition to rule codes and linter group prefixes.",
4649
"default": "See https://docs.astral.sh/ruff/default-rules/ or run `ruff check --show-settings --isolated`",
4750
"value_type": "list[RuleSelector]",
4851
"scope": null,

‎crates/ruff_workspace/src/options.rs‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -819,13 +819,16 @@ pub struct LintCommonOptions {
819819
pub fixable: Option<Vec<UnresolvedRuleSelector>>,
820820

821821
/// A list of rule codes or prefixes to ignore. Prefixes can specify exact
822-
/// rules (like `F841`), entire categories (like `F`), or anything in
822+
/// rules (like `F841`), entire groups (like `F`), or anything in
823823
/// between.
824824
///
825825
/// When breaking ties between enabled and disabled rules (via `select` and
826826
/// `ignore`, respectively), more specific prefixes override less
827827
/// specific prefixes. `ignore` takes precedence over `select` if the same
828828
/// prefix appears in both.
829+
///
830+
/// In preview, categories like `correctness` and `suspicious` can be used
831+
/// in addition to rule codes and linter group prefixes.
829832
#[option(
830833
default = "[]",
831834
value_type = "list[RuleSelector]",
@@ -909,13 +912,16 @@ pub struct LintCommonOptions {
909912
pub logger_objects: Option<Vec<String>>,
910913

911914
/// A list of rule codes or prefixes to enable. Prefixes can specify exact
912-
/// rules (like `F841`), entire categories (like `F`), or anything in
915+
/// rules (like `F841`), entire groups (like `F`), or anything in
913916
/// between.
914917
///
915918
/// When breaking ties between enabled and disabled rules (via `select` and
916919
/// `ignore`, respectively), more specific prefixes override less
917920
/// specific prefixes. `ignore` takes precedence over `select` if the
918921
/// same prefix appears in both.
922+
///
923+
/// In preview, categories like `correctness` and `suspicious` can be used
924+
/// in addition to rule codes and linter group prefixes.
919925
#[option(
920926
default = r#"See https://docs.astral.sh/ruff/default-rules/ or run `ruff check --show-settings --isolated`"#,
921927
value_type = "list[RuleSelector]",

‎docs/linter.md‎

Lines changed: 124 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ If you're wondering how to configure Ruff, here are some **recommended guideline
6161

6262
- Prefer [`lint.select`](settings.md#lint_select) over [`lint.extend-select`](settings.md#lint_extend-select) to make your rule set explicit.
6363
- Use `ALL` with discretion. Enabling `ALL` will implicitly enable new rules whenever you upgrade.
64-
- Start with a small set of rules (`select = ["E", "F"]`) and add a category at-a-time. For example,
64+
- Start with a small set of rules (`select = ["E", "F"]`) and add a group at-a-time. For example,
6565
you might consider expanding to `select = ["E", "F", "B"]` to enable the popular flake8-bugbear
6666
extension.
6767

@@ -144,6 +144,129 @@ with the exception of `F401`.
144144
When [preview mode](preview.md) is enabled, rule selectors also accept the human-readable name of a
145145
rule (e.g., `unused-import`).
146146

147+
## Rule categories
148+
149+
In [preview](preview.md), Ruff supports rule categories in addition to the Flake8-style linter
150+
groups described above. These categories organize rules by the types of issues they detect and
151+
determine whether rules are enabled by default. These categories and their descriptions, in
152+
order of decreasing severity, are:
153+
154+
- **Correctness**: These rules flag code that is outright wrong as written. If you encounter a
155+
correctness issue, you should try to fix it rather than suppressing the error with `noqa` or
156+
`ruff: ignore`.
157+
- **Suspicious**: These rules are similar to `correctness` lints in that the code is likely wrong,
158+
but `suspicious` lints acknowledge that there are valid reasons for the code to be written in this
159+
way. You will still typically want to fix these issues, but using a suppression comment may
160+
occasionally be necessary. Deprecations generally also fit into this category.
161+
- **Complexity**: These rules detect code that can be written in a simpler or more readable way
162+
without changing its semantics.
163+
- **Performance**: These rules detect code that can be written in a more efficient way, without changing its semantics or significantly degrading readability.
164+
- **Style**: These rules flag code that could be written more idiomatically and where the relevant
165+
idiom has broad community acceptance.
166+
- **Security**: These rules flag issues that could lead to security vulnerabilities, and as such,
167+
bias heavily toward false positives to avoid false negatives.
168+
- **Formatting**: These rules flag formatting issues and are generally redundant with a code
169+
formatter.
170+
- **Pedantic**: These rules are generally stylistic, like those in the `style` or similar
171+
categories, but enforce styles that are too opinionated or are too prone to false positives to fit
172+
into another category.
173+
- **Restriction**: These rules restrict the usage of basic language features in arbitrary ways.
174+
175+
The first five categories compose the default rule set:
176+
177+
=== "pyproject.toml"
178+
179+
```toml
180+
[tool.ruff.lint]
181+
preview = true
182+
select = [
183+
"correctness",
184+
"suspicious",
185+
"complexity",
186+
"performance",
187+
"style",
188+
]
189+
```
190+
191+
=== "ruff.toml"
192+
193+
```toml
194+
[lint]
195+
preview = true
196+
select = [
197+
"correctness",
198+
"suspicious",
199+
"complexity",
200+
"performance",
201+
"style",
202+
]
203+
```
204+
205+
while the remaining four (`security`, `formatting`, `pedantic`, and `restriction`) are off by
206+
default. For certain projects, you may want to enable either `security` or `formatting` as entire
207+
categories, but `pedantic` and `restriction` contain a wider variety of opinionated lints, and you
208+
will typically only want to select individual rules from these categories directly.
209+
210+
### Interaction with other selectors
211+
212+
Categories can be freely mixed with linter groups, linter prefixes, rule codes, and rule names. In
213+
addition to the priority relationships described above for settings like `lint.select`,
214+
`lint.extend-select`, and `lint.ignore`, and those for various configuration sources like
215+
`pyproject.toml` files and the CLI, the various selectors also have precedence relationships with
216+
each other. In general, you can think of this precedence as increasing from the broadest selector
217+
(`ALL`) to the narrowest single-rule selectors (e.g. `F401` or `unused-import`):
218+
219+
```text
220+
ALL < category < linter group < linter prefix < rule
221+
```
222+
223+
As shown above, this means that configuration like:
224+
225+
=== "pyproject.toml"
226+
227+
```toml
228+
[tool.ruff.lint]
229+
preview = true
230+
select = ["E", "F"]
231+
ignore = ["F401"]
232+
```
233+
234+
=== "ruff.toml"
235+
236+
```toml
237+
[lint]
238+
preview = true
239+
select = ["E", "F"]
240+
ignore = ["F401"]
241+
```
242+
243+
will select all `E` and `F` rules, with the exception of `F401`. Analogously, a selection with the
244+
`suspicious` category like:
245+
246+
=== "pyproject.toml"
247+
248+
```toml
249+
[tool.ruff.lint]
250+
preview = true
251+
select = ["suspicious"]
252+
ignore = ["UP"]
253+
```
254+
255+
=== "ruff.toml"
256+
257+
```toml
258+
[lint]
259+
preview = true
260+
select = ["suspicious"]
261+
ignore = ["UP"]
262+
```
263+
264+
would select all `suspicious` rules, except for the `UP` rules in that category.
265+
266+
Note that we plan to deprecate and eventually remove the linter groups in the future. If you give
267+
the new categories a try and run into situations where you need to fall back on linter groups,
268+
please let us know on the [tracking issue](https://github.com/astral-sh/ruff/issues/27959).
269+
147270
## Fixes
148271

149272
Ruff supports automatic fixes for a variety of lint errors. For example, Ruff can remove unused

‎ruff.schema.json‎

Lines changed: 4 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)