Python
/
ruff
mirror of https://github.com/astral-sh/ruff
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document range suppressions, reorganize suppression docs (#21884) 

- **Reorganize suppression documentation, document range suppressions**
- **Note preview mode requirement**

Issue #21874, #3711
This commit is contained in:
Amethyst Reese 2025-12-11 11:16:36 -08:00 committed by GitHub
parent 7a578ce833
commit c055d665ef
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 113 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
docs/linter.md
View File

@ -279,10 +279,22 @@ Conversely, the following configuration would only enable fixes for `F401`:
Ruff supports several mechanisms for suppressing lint errors, be they false positives or
permissible violations.
To omit a lint rule entirely, add it to the "ignore" list via the [`lint.ignore`](settings.md#lint_ignore)
### Configuration
To omit a lint rule everywhere, add it to the "ignore" list via the [`lint.ignore`](settings.md#lint_ignore)
setting, either on the command-line or in your `pyproject.toml` or `ruff.toml` file.
To suppress a violation inline, Ruff uses a `noqa` system similar to [Flake8](https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html).
To omit a lint rule within specific files based on file path prefixes or patterns,
see the [`lint.per-file-ignores`](settings.md#lint_per-file-ignores) setting.
### Comments
Ruff supports multiple forms of suppression comments, including inline and file-level `noqa`
comments, and range suppressions.
#### Line-level
Ruff supports a `noqa` system similar to [Flake8](https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html).
To ignore an individual violation, add `# noqa: {code}` to the end of the line, like so:
```python
@ -314,6 +326,84 @@ import os # noqa: I001
import abc
```
The full inline comment specification is as follows:
- An inline blanket `noqa` comment is given by a case-insensitive match for
`#noqa` with optional whitespace after the `#` symbol, followed by either: the
end of the comment, the beginning of a new comment (`#`), or whitespace
followed by any character other than `:`.
- An inline rule suppression is given by first finding a case-insensitive match
for `#noqa` with optional whitespace after the `#` symbol, optional whitespace
after `noqa`, and followed by the symbol `:`. After this we are expected to
have a list of rule codes which is given by sequences of uppercase ASCII
characters followed by ASCII digits, separated by whitespace or commas. The
list ends at the last valid code. We will attempt to interpret rules with a
missing delimiter (e.g. `F401F841`), though a warning will be emitted in this
case.
#### Block-level
*Range suppressions are currently only available in [preview mode](preview.md#preview).*
To ignore one or more violations within a range or block of code, a "disable" comment
followed by a matching "enable" comment can be used, like so:
```python
# ruff: disable[E501]
VALUE_1 = "Lorem ipsum dolor sit amet ..."
VALUE_2 = "Lorem ipsum dolor sit amet ..."
VALUE_3 = "Lorem ipsum dolor sit amet ..."
# ruff: enable[E501]
```
To define a range, both the "disable" and "enable" comments must have matching codes,
in the same order, as well as matching indentation levels within a logical block of code:
```python
def foo():
# ruff: disable[E741, F841]
i = 1
# ruff: enable[E741, F841]
```
If no matching "enable" comment is found, Ruff will also treat this as an "implicit" range.
The implicit range is defined from the starting "disable" comment, until reaching
a logical scope indented less than the starting comment:
```python
def foo():
# ruff: disable[E741, F841]
i = 1
if True:
O = 1
l = 1
# implicit end of range
foo()
```
It is strongly suggested to use explicit range suppressions, in order to prevent
accidental suppressions of violations, especially at global module scope.
Range suppressions cannot be used to enable or select rules that aren't already
selected by the project configuration or runtime flags. An "enable" comment can only
be used to terminate a preceding "disable" comment with identical codes.
Unlike `noqa` suppressions, range suppressions do not support "blanket" suppression
of all violations. At least one violation code must be listed.
The full range suppression comment specification is as follows:
- An own-line comment starting with case sensitive `#ruff:`, with optional whitespace
after the `#` symbol and `:` symbol, followed by either `disable` or `enable`
to start or end a range respectively, immediately followed by `[`, any codes to
be suppressed, and ending with `]`.
- Codes to be suppressed must be separated by commas, with optional whitespace
before or after each code, and may be followed by an optional trailing comma
after the last code.
#### File-level
To ignore all violations across an entire file, add the line `# ruff: noqa` anywhere in the file,
preferably towards the top, like so:
@ -328,51 +418,46 @@ file, preferably towards the top, like so:
# ruff: noqa: F841
```
Or see the [`lint.per-file-ignores`](settings.md#lint_per-file-ignores) setting, which enables the same
functionality from within your `pyproject.toml` or `ruff.toml` file.
Global `noqa` comments must be on their own line to disambiguate from comments which ignore
violations on a single line.
Note that Ruff will also respect Flake8's `# flake8: noqa` directive, and will treat it as
equivalent to `# ruff: noqa`.
### Full suppression comment specification
The file-level suppression comment specification is as follows:
The full specification is as follows:
- An inline blanket `noqa` comment is given by a case-insensitive match for
`#noqa` with optional whitespace after the `#` symbol, followed by either: the
end of the comment, the beginning of a new comment (`#`), or whitespace
followed by any character other than `:`.
- An inline rule suppression is given by first finding a case-insensitive match
for `#noqa` with optional whitespace after the `#` symbol, optional whitespace
after `noqa`, and followed by the symbol `:`. After this we are expected to
have a list of rule codes which is given by sequences of uppercase ASCII
characters followed by ASCII digits, separated by whitespace or commas. The
list ends at the last valid code. We will attempt to interpret rules with a
missing delimiter (e.g. `F401F841`), though a warning will be emitted in this
case.
- A file-level exemption comment is given by a case-sensitive match for `#ruff:`
or `#flake8:`, with optional whitespace after `#` and before `:`, followed by
optional whitespace and a case-insensitive match for `noqa`. After this, the
specification is as in the inline case.
specification is as in the inline `noqa` suppressions above.
### Detecting unused suppression comments
### Detecting unused suppressions
Ruff implements a special rule, [`unused-noqa`](https://docs.astral.sh/ruff/rules/unused-noqa/),
under the `RUF100` code, to enforce that your `noqa` directives are "valid", in that the violations
they _say_ they ignore are actually being triggered on that line (and thus suppressed). To flag
unused `noqa` directives, run: `ruff check /path/to/file.py --extend-select RUF100`.
under the `RUF100` code, to enforce that your suppressions are "valid", in that the violations
they _say_ they ignore are actually being triggered and suppressed. To flag
unused suppression comments, run Ruff with `--extend-select RUF100`, like so:
Ruff can also _remove_ any unused `noqa` directives via its fix functionality. To remove any
unused `noqa` directives, run: `ruff check /path/to/file.py --extend-select RUF100 --fix`.
```shell-session
$ ruff check /path/to/file.py --extend-select RUF100
```
Ruff can also _remove_ any unused suppression comments via its fix functionality.
To remove any unused suppressions, run Ruff with `--fix`, like so:
```shell-session
$ ruff check /path/to/file.py --extend-select RUF100 --fix
```
### Inserting necessary suppression comments
Ruff can _automatically add_ `noqa` directives to all lines that contain violations, which is
useful when migrating a new codebase to Ruff. To automatically add `noqa` directives to all
relevant lines (with the appropriate rule codes), run: `ruff check /path/to/file.py --add-noqa`.
relevant lines (with the appropriate rule codes), run Ruff with `--add-noqa`, like so:
```shell-session
$ ruff check /path/to/file.py --add-noqa
```
### Action comments