From 144063e27d780d16b52921c6d6d151de94399576 Mon Sep 17 00:00:00 2001 From: Zanie Date: Tue, 10 Oct 2023 13:37:09 -0500 Subject: [PATCH 1/8] Add documentation for fixes --- docs/configuration.md | 63 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index e963c310e6000..c646df4b9ff4a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -375,6 +375,69 @@ Running `ruff check --select F401` would result in Ruff enforcing `F401`, and no Running `ruff check --extend-select B` would result in Ruff enforcing the `E`, `F`, and `B` rules, with the exception of `F401`. +## Fixes + +Ruff supports automatic fixes for a variety of lint errors. For example, Ruff can remove unused +imports, reformat docstrings, rewrite type annotations to use the latest PEP syntax, and more. + +To enable fixes, pass the `--fix` flag to `ruff check`: + +```shell +ruff check . --fix +``` + +By default, Ruff will fix all violations for which safe fixes are available To determine +whether a rule supports fixing, see [_Rules_](rules.md). + +### Fix safety + +Ruff labels fixes as "safe" and "unsafe". Safe fixes are very unlikely to change the intent of your code; in contrast, unsafe fixes may change the meaning of your code. + +Ruff only uses safe fixes by default. Unsafe fixes can be enabled by passing the `--unsafe-fixes` flag to `ruff check` or by enabling [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file. + +```shell +# Show unsafe fixes +ruff check . --unsafe-fixes + +# Apply unsafe fixes +ruff check . --fix --unsafe-fixes +``` + +The safety of fixes can be adjusted per rule using the [`extend-safe-fixes`](settings.md#extend-safe-fixes) and [`extend-unsafe-fixes`](settings.md#extend-unsafe-fixes) settings. + +For example, the following configuration would promote unsafe fixes for `F601` to safe fixes and demote safe fixes for `UP034` to unsafe fixes. + +```toml +[tool.ruff.lint] +extend-safe-fixes = ["F601"] +extend-unsafe-fixes = ["UP034"] +``` + +You may use prefixes to select rules as well, e.g. `F` can be used to promote fixes for all rules in pyflakes to safe. + +Note that all fixes will always be displayed by Ruff when using the `json` output format. The safety of the fix is available under the `applicability` field. + +### Toggling fixes per rule + +To limit the set of rules that Ruff should fix, use the [`fixable`](settings.md#fixable) and [`unfixable`](settings.md#unfixable) settings, along with their [`extend-fixable`](settings.md#extend-fixable) and [`extend-unfixable`](settings.md#extend-unfixable) +variants. + +For example, the following configuration would enable fixes for all rules except +[`unused-imports`](rules/unused-import.md) (`F401`): + +```toml +[tool.ruff.lint] +fixable = ["ALL"] +unfixable = ["F401"] +``` + +Conversely, the following configuration would only enable fixes for `F401`: + +```toml +[tool.ruff.lint] +fixable = ["F401"] +``` + ## Error suppression To omit a lint rule entirely, add it to the "ignore" list via [`ignore`](settings.md#ignore) From a75a4fedd3ad2945f1eebddf678da15858cae3de Mon Sep 17 00:00:00 2001 From: Zanie Date: Tue, 10 Oct 2023 13:50:19 -0500 Subject: [PATCH 2/8] Copy edits --- docs/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index c646df4b9ff4a..08477c7ac8429 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -386,14 +386,14 @@ To enable fixes, pass the `--fix` flag to `ruff check`: ruff check . --fix ``` -By default, Ruff will fix all violations for which safe fixes are available To determine +By default, Ruff will fix all violations for which safe fixes are available; to determine whether a rule supports fixing, see [_Rules_](rules.md). ### Fix safety -Ruff labels fixes as "safe" and "unsafe". Safe fixes are very unlikely to change the intent of your code; in contrast, unsafe fixes may change the meaning of your code. +Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code should be retained by safe fixes, but may be changed by unsafe fixes. -Ruff only uses safe fixes by default. Unsafe fixes can be enabled by passing the `--unsafe-fixes` flag to `ruff check` or by enabling [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file. +Ruff only enables safe fixes by default. Unsafe fixes can be enabled by passing the `--unsafe-fixes` flag to `ruff check` or by enabling [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file. ```shell # Show unsafe fixes From e1b19b8799e13008581d8304db55dbb90aa879fb Mon Sep 17 00:00:00 2001 From: Zanie Date: Tue, 10 Oct 2023 13:54:12 -0500 Subject: [PATCH 3/8] Enable admonitions in docs --- docs/configuration.md | 4 +++- mkdocs.template.yml | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 08477c7ac8429..14e16409d3932 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -415,7 +415,9 @@ extend-unsafe-fixes = ["UP034"] You may use prefixes to select rules as well, e.g. `F` can be used to promote fixes for all rules in pyflakes to safe. -Note that all fixes will always be displayed by Ruff when using the `json` output format. The safety of the fix is available under the `applicability` field. +!!! note + + All fixes will always be displayed by Ruff when using the `json` output format. The safety of each fix is available under the `applicability` field. ### Toggling fixes per rule diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 171578868d1a0..7eeed400e8e22 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -37,6 +37,8 @@ site_author: charliermarsh site_url: https://docs.astral.sh/ruff/ site_dir: site/ruff markdown_extensions: + - admonition + - pymdownx.details - toc: permalink: "#" - pymdownx.snippets: From a224817d323253dbd8acbc5c5fb7b76b49208722 Mon Sep 17 00:00:00 2001 From: Zanie Date: Tue, 10 Oct 2023 13:58:14 -0500 Subject: [PATCH 4/8] Additional copy edits --- docs/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 14e16409d3932..04146c0b114eb 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -393,7 +393,7 @@ whether a rule supports fixing, see [_Rules_](rules.md). Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code should be retained by safe fixes, but may be changed by unsafe fixes. -Ruff only enables safe fixes by default. Unsafe fixes can be enabled by passing the `--unsafe-fixes` flag to `ruff check` or by enabling [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file. +Ruff only enables safe fixes by default. Unsafe fixes can be enabled by settings [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file or passing the `--unsafe-fixes` flag to `ruff check`: ```shell # Show unsafe fixes @@ -405,7 +405,7 @@ ruff check . --fix --unsafe-fixes The safety of fixes can be adjusted per rule using the [`extend-safe-fixes`](settings.md#extend-safe-fixes) and [`extend-unsafe-fixes`](settings.md#extend-unsafe-fixes) settings. -For example, the following configuration would promote unsafe fixes for `F601` to safe fixes and demote safe fixes for `UP034` to unsafe fixes. +For example, the following configuration would promote unsafe fixes for `F601` to safe fixes and demote safe fixes for `UP034` to unsafe fixes: ```toml [tool.ruff.lint] @@ -419,7 +419,7 @@ You may use prefixes to select rules as well, e.g. `F` can be used to promote fi All fixes will always be displayed by Ruff when using the `json` output format. The safety of each fix is available under the `applicability` field. -### Toggling fixes per rule +### Disabling fixes To limit the set of rules that Ruff should fix, use the [`fixable`](settings.md#fixable) and [`unfixable`](settings.md#unfixable) settings, along with their [`extend-fixable`](settings.md#extend-fixable) and [`extend-unfixable`](settings.md#extend-unfixable) variants. From 87a0f8694b5f5bf44d0e0a9a4deb309090b94beb Mon Sep 17 00:00:00 2001 From: Zanie Date: Tue, 10 Oct 2023 14:49:46 -0500 Subject: [PATCH 5/8] Add admonition support for mdformat --- .pre-commit-config.yaml | 1 + docs/configuration.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5da5eb203726a..3008412e55a5a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -23,6 +23,7 @@ repos: - id: mdformat additional_dependencies: - mdformat-mkdocs + - mdformat-admon - repo: https://github.com/igorshubovych/markdownlint-cli rev: v0.33.0 diff --git a/docs/configuration.md b/docs/configuration.md index 04146c0b114eb..bad60be4023b4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -416,7 +416,6 @@ extend-unsafe-fixes = ["UP034"] You may use prefixes to select rules as well, e.g. `F` can be used to promote fixes for all rules in pyflakes to safe. !!! note - All fixes will always be displayed by Ruff when using the `json` output format. The safety of each fix is available under the `applicability` field. ### Disabling fixes From 8f51a4ae2b1b939d6fc4efd388f4f29f3f249f0a Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 10 Oct 2023 18:48:39 -0500 Subject: [PATCH 6/8] Update docs/configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index bad60be4023b4..1cf74f44eafb9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -413,7 +413,7 @@ extend-safe-fixes = ["F601"] extend-unsafe-fixes = ["UP034"] ``` -You may use prefixes to select rules as well, e.g. `F` can be used to promote fixes for all rules in pyflakes to safe. +You may use prefixes to select rules as well, e.g., `F` can be used to promote fixes for all rules in Pyflakes to safe. !!! note All fixes will always be displayed by Ruff when using the `json` output format. The safety of each fix is available under the `applicability` field. From 4501ca8e1ca8b93c161a0b3bc3964977ce3a404a Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 10 Oct 2023 18:50:39 -0500 Subject: [PATCH 7/8] Update docs/configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 1cf74f44eafb9..ca077e0d56f26 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -391,7 +391,7 @@ whether a rule supports fixing, see [_Rules_](rules.md). ### Fix safety -Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code should be retained by safe fixes, but may be changed by unsafe fixes. +Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code will be retained when applying safe fixes, but the meaning could be changed when applying unsafe fixes. Ruff only enables safe fixes by default. Unsafe fixes can be enabled by settings [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file or passing the `--unsafe-fixes` flag to `ruff check`: From cfd84f1b3f72748f73af6db57db4312951399fcd Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Wed, 11 Oct 2023 11:30:58 -0500 Subject: [PATCH 8/8] Update docs/configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index ca077e0d56f26..0e728313ee237 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -378,7 +378,7 @@ with the exception of `F401`. ## Fixes Ruff supports automatic fixes for a variety of lint errors. For example, Ruff can remove unused -imports, reformat docstrings, rewrite type annotations to use the latest PEP syntax, and more. +imports, reformat docstrings, rewrite type annotations to use newer Python syntax, and more. To enable fixes, pass the `--fix` flag to `ruff check`: