From a9aa96b24f3f784eaed765689f177e922f907acf Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Tue, 7 Feb 2023 21:20:24 -0500 Subject: [PATCH] Add documentation for flake8-quotes rules (#2650) --- README.md | 8 +- crates/ruff/src/rules/flake8_quotes/rules.rs | 78 +++++++++++++++++++ .../pylint/rules/comparison_of_constant.rs | 2 +- .../pylint/rules/magic_value_comparison.rs | 2 +- crates/ruff_dev/src/generate_docs.rs | 6 +- docs/rules/assert-raises-exception.md | 2 + docs/rules/avoid-quote-escape.md | 23 ++++++ docs/rules/bad-quotes-docstring.md | 27 +++++++ docs/rules/bad-quotes-inline-string.md | 24 ++++++ docs/rules/bad-quotes-multiline-string.md | 28 +++++++ 10 files changed, 192 insertions(+), 8 deletions(-) create mode 100644 docs/rules/avoid-quote-escape.md create mode 100644 docs/rules/bad-quotes-docstring.md create mode 100644 docs/rules/bad-quotes-inline-string.md create mode 100644 docs/rules/bad-quotes-multiline-string.md diff --git a/README.md b/README.md index 89632309cf..fe5dc28192 100644 --- a/README.md +++ b/README.md @@ -1162,10 +1162,10 @@ For more, see [flake8-quotes](https://pypi.org/project/flake8-quotes/) on PyPI. | Code | Name | Message | Fix | | ---- | ---- | ------- | --- | -| Q000 | bad-quotes-inline-string | Double quotes found but single quotes preferred | 🛠 | -| Q001 | bad-quotes-multiline-string | Double quote multiline found but single quotes preferred | 🛠 | -| Q002 | bad-quotes-docstring | Double quote docstring found but single quotes preferred | 🛠 | -| Q003 | avoid-quote-escape | Change outer quotes to avoid escaping inner quotes | 🛠 | +| [Q000](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-inline-string.md) | [bad-quotes-inline-string](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-inline-string.md) | Double quotes found but single quotes preferred | 🛠 | +| [Q001](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-multiline-string.md) | [bad-quotes-multiline-string](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-multiline-string.md) | Double quote multiline found but single quotes preferred | 🛠 | +| [Q002](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-docstring.md) | [bad-quotes-docstring](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-docstring.md) | Double quote docstring found but single quotes preferred | 🛠 | +| [Q003](https://github.com/charliermarsh/ruff/blob/main/docs/rules/avoid-quote-escape.md) | [avoid-quote-escape](https://github.com/charliermarsh/ruff/blob/main/docs/rules/avoid-quote-escape.md) | Change outer quotes to avoid escaping inner quotes | 🛠 | ### flake8-return (RET) diff --git a/crates/ruff/src/rules/flake8_quotes/rules.rs b/crates/ruff/src/rules/flake8_quotes/rules.rs index 5898cd3dc2..9c6a5dde36 100644 --- a/crates/ruff/src/rules/flake8_quotes/rules.rs +++ b/crates/ruff/src/rules/flake8_quotes/rules.rs @@ -12,6 +12,24 @@ use crate::source_code::Locator; use crate::violation::AlwaysAutofixableViolation; define_violation!( + /// ### What it does + /// Checks for inline strings that use single quotes or double quotes, + /// depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes) + /// setting. + /// + /// ### Why is this bad? + /// Consistency is good. Use either single or double quotes for inline + /// strings, but be consistent. + /// + /// ### Example + /// ```python + /// foo = 'bar' + /// ``` + /// + /// Assuming `inline-quotes` is set to `double`, use instead: + /// ```python + /// foo = "bar" + /// ``` pub struct BadQuotesInlineString { pub quote: Quote, } @@ -36,6 +54,28 @@ impl AlwaysAutofixableViolation for BadQuotesInlineString { } define_violation!( + /// ### What it does + /// Checks for multiline strings that use single quotes or double quotes, + /// depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes) + /// setting. + /// + /// ### Why is this bad? + /// Consistency is good. Use either single or double quotes for multiline + /// strings, but be consistent. + /// + /// ### Example + /// ```python + /// foo = ''' + /// bar + /// ''' + /// ``` + /// + /// Assuming `multiline-quotes` is set to `double`, use instead: + /// ```python + /// foo = """ + /// bar + /// """ + /// ``` pub struct BadQuotesMultilineString { pub quote: Quote, } @@ -60,6 +100,27 @@ impl AlwaysAutofixableViolation for BadQuotesMultilineString { } define_violation!( + /// ### What it does + /// Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes) + /// setting. + /// + /// ### Why is this bad? + /// Consistency is good. Use either single or double quotes for docstring + /// strings, but be consistent. + /// + /// ### Example + /// ```python + /// ''' + /// bar + /// ''' + /// ``` + /// + /// Assuming `docstring-quotes` is set to `double`, use instead: + /// ```python + /// """ + /// bar + /// """ + /// ``` pub struct BadQuotesDocstring { pub quote: Quote, } @@ -84,6 +145,23 @@ impl AlwaysAutofixableViolation for BadQuotesDocstring { } define_violation!( + /// ### What it does + /// Checks for strings that include escaped quotes, and suggests changing + /// the quote style to avoid the need to escape them. + /// + /// ### Why is this bad? + /// It's preferable to avoid escaped quotes in strings. By changing the + /// outer quote style, you can avoid escaping inner quotes. + /// + /// ### Example + /// ```python + /// foo = 'bar\'s' + /// ``` + /// + /// Use instead: + /// ```python + /// foo = "bar's" + /// ``` pub struct AvoidQuoteEscape; ); impl AlwaysAutofixableViolation for AvoidQuoteEscape { diff --git a/crates/ruff/src/rules/pylint/rules/comparison_of_constant.rs b/crates/ruff/src/rules/pylint/rules/comparison_of_constant.rs index dce3dce492..91789c764d 100644 --- a/crates/ruff/src/rules/pylint/rules/comparison_of_constant.rs +++ b/crates/ruff/src/rules/pylint/rules/comparison_of_constant.rs @@ -1,11 +1,11 @@ use std::fmt; -use crate::ast::helpers::unparse_constant; use itertools::Itertools; use ruff_macros::{define_violation, derive_message_formats}; use rustpython_parser::ast::{Cmpop, Expr, ExprKind, Located}; use serde::{Deserialize, Serialize}; +use crate::ast::helpers::unparse_constant; use crate::ast::types::Range; use crate::checkers::ast::Checker; use crate::registry::Diagnostic; diff --git a/crates/ruff/src/rules/pylint/rules/magic_value_comparison.rs b/crates/ruff/src/rules/pylint/rules/magic_value_comparison.rs index 165829a914..0245e2cab7 100644 --- a/crates/ruff/src/rules/pylint/rules/magic_value_comparison.rs +++ b/crates/ruff/src/rules/pylint/rules/magic_value_comparison.rs @@ -1,8 +1,8 @@ -use crate::ast::helpers::unparse_constant; use itertools::Itertools; use ruff_macros::{define_violation, derive_message_formats}; use rustpython_parser::ast::{Constant, Expr, ExprKind}; +use crate::ast::helpers::unparse_constant; use crate::ast::types::Range; use crate::checkers::ast::Checker; use crate::registry::Diagnostic; diff --git a/crates/ruff_dev/src/generate_docs.rs b/crates/ruff_dev/src/generate_docs.rs index c1c35b815a..7273f2efd2 100644 --- a/crates/ruff_dev/src/generate_docs.rs +++ b/crates/ruff_dev/src/generate_docs.rs @@ -4,11 +4,10 @@ use std::fs; use anyhow::Result; +use ruff::registry::{Linter, Rule, RuleNamespace}; use ruff::AutofixAvailability; use strum::IntoEnumIterator; -use ruff::registry::{Linter, Rule, RuleNamespace}; - #[derive(clap::Args)] pub struct Args { /// Write the generated docs to stdout (rather than to the filesystem). @@ -22,10 +21,12 @@ pub fn main(args: &Args) -> Result<()> { let mut output = String::new(); output.push_str(&format!("# {} ({})", rule.as_ref(), rule.code())); output.push('\n'); + output.push('\n'); let (linter, _) = Linter::parse_code(rule.code()).unwrap(); output.push_str(&format!("Derived from the **{}** linter.", linter.name())); output.push('\n'); + output.push('\n'); if let Some(autofix) = rule.autofixable() { output.push_str(match autofix.available { @@ -33,6 +34,7 @@ pub fn main(args: &Args) -> Result<()> { AutofixAvailability::Always => "Autofix is always available.", }); output.push('\n'); + output.push('\n'); } output.push_str(explanation.trim()); diff --git a/docs/rules/assert-raises-exception.md b/docs/rules/assert-raises-exception.md index ecddf347a2..304d583b61 100644 --- a/docs/rules/assert-raises-exception.md +++ b/docs/rules/assert-raises-exception.md @@ -1,5 +1,7 @@ # assert-raises-exception (B017) + Derived from the **flake8-bugbear** linter. + ### What it does Checks for `self.assertRaises(Exception)`. diff --git a/docs/rules/avoid-quote-escape.md b/docs/rules/avoid-quote-escape.md new file mode 100644 index 0000000000..b93804a46a --- /dev/null +++ b/docs/rules/avoid-quote-escape.md @@ -0,0 +1,23 @@ +# avoid-quote-escape (Q003) + +Derived from the **flake8-quotes** linter. + +Autofix is always available. + +### What it does +Checks for strings that include escaped quotes, and suggests changing +the quote style to avoid the need to escape them. + +### Why is this bad? +It's preferable to avoid escaped quotes in strings. By changing the +outer quote style, you can avoid escaping inner quotes. + +### Example +```python +foo = 'bar\'s' +``` + +Use instead: +```python +foo = "bar's" +``` \ No newline at end of file diff --git a/docs/rules/bad-quotes-docstring.md b/docs/rules/bad-quotes-docstring.md new file mode 100644 index 0000000000..3f1f5355be --- /dev/null +++ b/docs/rules/bad-quotes-docstring.md @@ -0,0 +1,27 @@ +# bad-quotes-docstring (Q002) + +Derived from the **flake8-quotes** linter. + +Autofix is always available. + +### What it does +Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes) +setting. + +### Why is this bad? +Consistency is good. Use either single or double quotes for docstring +strings, but be consistent. + +### Example +```python +''' +bar +''' +``` + +Assuming `docstring-quotes` is set to `double`, use instead: +```python +""" +bar +""" +``` \ No newline at end of file diff --git a/docs/rules/bad-quotes-inline-string.md b/docs/rules/bad-quotes-inline-string.md new file mode 100644 index 0000000000..be7908d6d9 --- /dev/null +++ b/docs/rules/bad-quotes-inline-string.md @@ -0,0 +1,24 @@ +# bad-quotes-inline-string (Q000) + +Derived from the **flake8-quotes** linter. + +Autofix is always available. + +### What it does +Checks for inline strings that use single quotes or double quotes, +depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes) +setting. + +### Why is this bad? +Consistency is good. Use either single or double quotes for inline +strings, but be consistent. + +### Example +```python +foo = 'bar' +``` + +Assuming `inline-quotes` is set to `double`, use instead: +```python +foo = "bar" +``` \ No newline at end of file diff --git a/docs/rules/bad-quotes-multiline-string.md b/docs/rules/bad-quotes-multiline-string.md new file mode 100644 index 0000000000..d2a1fed50b --- /dev/null +++ b/docs/rules/bad-quotes-multiline-string.md @@ -0,0 +1,28 @@ +# bad-quotes-multiline-string (Q001) + +Derived from the **flake8-quotes** linter. + +Autofix is always available. + +### What it does +Checks for multiline strings that use single quotes or double quotes, +depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes) +setting. + +### Why is this bad? +Consistency is good. Use either single or double quotes for multiline +strings, but be consistent. + +### Example +```python +foo = ''' +bar +''' +``` + +Assuming `multiline-quotes` is set to `double`, use instead: +```python +foo = """ +bar +""" +``` \ No newline at end of file