From 15f3d8c8e08933e03cb6b84d63875d64f35cd799 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Wed, 27 Sep 2023 00:49:41 -0400 Subject: [PATCH] Improvement documentation around `ignore-names` globbing (#7674) ## Summary Improves the documentation on the setting itself, along with that on the relevant rules. Closes https://github.com/astral-sh/ruff/issues/7660. --- ...id_first_argument_name_for_class_method.rs | 6 ++++++ .../invalid_first_argument_name_for_method.rs | 6 ++++++ .../rules/invalid_function_name.rs | 6 ++++++ .../non_lowercase_variable_in_function.rs | 1 + crates/ruff_workspace/src/options.rs | 20 ++++++++++++++++--- ruff.schema.json | 8 ++++---- 6 files changed, 40 insertions(+), 7 deletions(-) diff --git a/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_class_method.rs b/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_class_method.rs index ff0846786d..cc7092c7f7 100644 --- a/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_class_method.rs +++ b/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_class_method.rs @@ -22,6 +22,11 @@ use crate::checkers::ast::Checker; /// > append a single trailing underscore rather than use an abbreviation or spelling corruption. /// > Thus `class_` is better than `clss`. (Perhaps better is to avoid such clashes by using a synonym.) /// +/// Names can be excluded from this rule using the [`pep8-naming.ignore-names`] +/// or [`pep8-naming.extend-ignore-names`] configuration options. For example, +/// to allow the use of `klass` as the first argument to class methods, set +/// the [`pep8-naming.extend-ignore-names`] option to `["klass"]`. +/// /// ## Example /// ```python /// class Example: @@ -42,6 +47,7 @@ use crate::checkers::ast::Checker; /// - `pep8-naming.classmethod-decorators` /// - `pep8-naming.staticmethod-decorators` /// - `pep8-naming.ignore-names` +/// - `pep8-naming.extend-ignore-names` /// /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments #[violation] diff --git a/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_method.rs b/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_method.rs index 4e18781e62..e2e83dcbf7 100644 --- a/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_method.rs +++ b/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_first_argument_name_for_method.rs @@ -22,6 +22,11 @@ use crate::checkers::ast::Checker; /// > append a single trailing underscore rather than use an abbreviation or spelling corruption. /// > Thus `class_` is better than `clss`. (Perhaps better is to avoid such clashes by using a synonym.) /// +/// Names can be excluded from this rule using the [`pep8-naming.ignore-names`] +/// or [`pep8-naming.extend-ignore-names`] configuration options. For example, +/// to allow the use of `this` as the first argument to instance methods, set +/// the [`pep8-naming.extend-ignore-names`] option to `["this"]`. +/// /// ## Example /// ```python /// class Example: @@ -40,6 +45,7 @@ use crate::checkers::ast::Checker; /// - `pep8-naming.classmethod-decorators` /// - `pep8-naming.staticmethod-decorators` /// - `pep8-naming.ignore-names` +/// - `pep8-naming.extend-ignore-names` /// /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments #[violation] diff --git a/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_function_name.rs b/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_function_name.rs index 468b29dc7a..f38222a790 100644 --- a/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_function_name.rs +++ b/crates/ruff_linter/src/rules/pep8_naming/rules/invalid_function_name.rs @@ -20,6 +20,11 @@ use crate::settings::types::IdentifierPattern; /// > improve readability. mixedCase is allowed only in contexts where that’s already the /// > prevailing style (e.g. threading.py), to retain backwards compatibility. /// +/// Names can be excluded from this rule using the [`pep8-naming.ignore-names`] +/// or [`pep8-naming.extend-ignore-names`] configuration options. For example, +/// to ignore all functions starting with `test_` from this rule, set the +/// [`pep8-naming.extend-ignore-names`] option to `["test_*"]`. +/// /// ## Example /// ```python /// def myFunction(): @@ -34,6 +39,7 @@ use crate::settings::types::IdentifierPattern; /// /// ## Options /// - `pep8-naming.ignore-names` +/// - `pep8-naming.extend-ignore-names` /// /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-variable-names #[violation] diff --git a/crates/ruff_linter/src/rules/pep8_naming/rules/non_lowercase_variable_in_function.rs b/crates/ruff_linter/src/rules/pep8_naming/rules/non_lowercase_variable_in_function.rs index e8bae1c0ee..59df8bf60e 100644 --- a/crates/ruff_linter/src/rules/pep8_naming/rules/non_lowercase_variable_in_function.rs +++ b/crates/ruff_linter/src/rules/pep8_naming/rules/non_lowercase_variable_in_function.rs @@ -35,6 +35,7 @@ use crate::rules::pep8_naming::helpers; /// /// ## Options /// - `pep8-naming.ignore-names` +/// - `pep8-naming.extend-ignore-names` /// /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-variable-names #[violation] diff --git a/crates/ruff_workspace/src/options.rs b/crates/ruff_workspace/src/options.rs index 7963ef48f2..7be946a7a7 100644 --- a/crates/ruff_workspace/src/options.rs +++ b/crates/ruff_workspace/src/options.rs @@ -2050,6 +2050,10 @@ impl McCabeOptions { #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] pub struct Pep8NamingOptions { /// A list of names (or patterns) to ignore when considering `pep8-naming` violations. + /// + /// Supports glob patterns. For example, to ignore all names starting with + /// or ending with `_test`, you could use `ignore-names = ["test_*", "*_test"]`. + /// For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax). #[option( default = r#"["setUp", "tearDown", "setUpClass", "tearDownClass", "setUpModule", "tearDownModule", "asyncSetUp", "asyncTearDown", "setUpTestData", "failureException", "longMessage", "maxDiff"]"#, value_type = "list[str]", @@ -2060,7 +2064,11 @@ pub struct Pep8NamingOptions { pub ignore_names: Option>, /// Additional names (or patterns) to ignore when considering `pep8-naming` violations, - /// in addition to those included in `ignore-names`. + /// in addition to those included in `ignore-names` + /// + /// Supports glob patterns. For example, to ignore all names starting with + /// or ending with `_test`, you could use `ignore-names = ["test_*", "*_test"]`. + /// For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).. #[option( default = r#"[]"#, value_type = "list[str]", @@ -2074,6 +2082,9 @@ pub struct Pep8NamingOptions { /// /// For example, Ruff will expect that any method decorated by a decorator /// in this list takes a `cls` argument as its first argument. + /// + /// Expects to receive a list of fully-qualified names (e.g., `pydantic.validator`, + /// rather than `validator`). #[option( default = r#"[]"#, value_type = "list[str]", @@ -2090,12 +2101,15 @@ pub struct Pep8NamingOptions { /// /// For example, Ruff will expect that any method decorated by a decorator /// in this list has no `self` or `cls` argument. + /// + /// Expects to receive a list of fully-qualified names (e.g., `belay.Device.teardown`, + /// rather than `teardown`). #[option( default = r#"[]"#, value_type = "list[str]", example = r#" - # Allow a shorthand alias, `@stcmthd`, to trigger static method treatment. - staticmethod-decorators = ["stcmthd"] + # Allow Belay's `@Device.teardown` decorator to trigger static method treatment. + staticmethod-decorators = ["belay.Device.teardown"] "# )] pub staticmethod_decorators: Option>, diff --git a/ruff.schema.json b/ruff.schema.json index 07d35210b2..2cef8d57b7 100644 --- a/ruff.schema.json +++ b/ruff.schema.json @@ -1576,7 +1576,7 @@ "type": "object", "properties": { "classmethod-decorators": { - "description": "A list of decorators that, when applied to a method, indicate that the method should be treated as a class method (in addition to the builtin `@classmethod`).\n\nFor example, Ruff will expect that any method decorated by a decorator in this list takes a `cls` argument as its first argument.", + "description": "A list of decorators that, when applied to a method, indicate that the method should be treated as a class method (in addition to the builtin `@classmethod`).\n\nFor example, Ruff will expect that any method decorated by a decorator in this list takes a `cls` argument as its first argument.\n\nExpects to receive a list of fully-qualified names (e.g., `pydantic.validator`, rather than `validator`).", "type": [ "array", "null" @@ -1586,7 +1586,7 @@ } }, "extend-ignore-names": { - "description": "Additional names (or patterns) to ignore when considering `pep8-naming` violations, in addition to those included in `ignore-names`.", + "description": "Additional names (or patterns) to ignore when considering `pep8-naming` violations, in addition to those included in `ignore-names`\n\nSupports glob patterns. For example, to ignore all names starting with or ending with `_test`, you could use `ignore-names = [\"test_*\", \"*_test\"]`. For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax)..", "type": [ "array", "null" @@ -1596,7 +1596,7 @@ } }, "ignore-names": { - "description": "A list of names (or patterns) to ignore when considering `pep8-naming` violations.", + "description": "A list of names (or patterns) to ignore when considering `pep8-naming` violations.\n\nSupports glob patterns. For example, to ignore all names starting with or ending with `_test`, you could use `ignore-names = [\"test_*\", \"*_test\"]`. For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).", "type": [ "array", "null" @@ -1606,7 +1606,7 @@ } }, "staticmethod-decorators": { - "description": "A list of decorators that, when applied to a method, indicate that the method should be treated as a static method (in addition to the builtin `@staticmethod`).\n\nFor example, Ruff will expect that any method decorated by a decorator in this list has no `self` or `cls` argument.", + "description": "A list of decorators that, when applied to a method, indicate that the method should be treated as a static method (in addition to the builtin `@staticmethod`).\n\nFor example, Ruff will expect that any method decorated by a decorator in this list has no `self` or `cls` argument.\n\nExpects to receive a list of fully-qualified names (e.g., `belay.Device.teardown`, rather than `teardown`).", "type": [ "array", "null"