From 53e810ed3eb18cb3d157a0aa02cb3c7bc84d2725 Mon Sep 17 00:00:00 2001 From: Sawbez <63512091+Sawbez@users.noreply.github.com> Date: Mon, 13 Feb 2023 20:30:30 -0800 Subject: [PATCH] [docs] Add docs for the entirety of `flake8-builtins` (#2840) --- README.md | 6 +- .../ruff/src/rules/flake8_builtins/rules.rs | 121 ++++++++++++++++++ 2 files changed, 124 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8e1d106dd0..a7c4dead91 100644 --- a/README.md +++ b/README.md @@ -1044,9 +1044,9 @@ For more, see [flake8-builtins](https://pypi.org/project/flake8-builtins/) on Py | Code | Name | Message | Fix | | ---- | ---- | ------- | --- | -| A001 | builtin-variable-shadowing | Variable `{name}` is shadowing a python builtin | | -| A002 | builtin-argument-shadowing | Argument `{name}` is shadowing a python builtin | | -| A003 | builtin-attribute-shadowing | Class attribute `{name}` is shadowing a python builtin | | +| A001 | [builtin-variable-shadowing](https://beta.ruff.rs/docs/rules/builtin-variable-shadowing/) | Variable `{name}` is shadowing a python builtin | | +| A002 | [builtin-argument-shadowing](https://beta.ruff.rs/docs/rules/builtin-argument-shadowing/) | Argument `{name}` is shadowing a python builtin | | +| A003 | [builtin-attribute-shadowing](https://beta.ruff.rs/docs/rules/builtin-attribute-shadowing/) | Class attribute `{name}` is shadowing a python builtin | | ### flake8-commas (COM) diff --git a/crates/ruff/src/rules/flake8_builtins/rules.rs b/crates/ruff/src/rules/flake8_builtins/rules.rs index c162d8f065..9f84f97c2e 100644 --- a/crates/ruff/src/rules/flake8_builtins/rules.rs +++ b/crates/ruff/src/rules/flake8_builtins/rules.rs @@ -8,6 +8,44 @@ use crate::registry::{Diagnostic, DiagnosticKind}; use crate::violation::Violation; define_violation!( + /// ## What it does + /// Checks for variable (and function) assignments that use the same name + /// as a builtin. + /// + /// ## Why is this bad? + /// Reusing a builtin name for the name of a variable increases the + /// difficulty of reading and maintaining the code, and can cause + /// non-obvious errors, as readers may mistake the variable for the + /// builtin and vice versa. + /// + /// Builtins can be marked as exceptions to this rule via the + /// [`flake8-builtins.builtins-ignorelist`] configuration option. + /// + /// ## Options + /// + /// * `flake8-builtins.builtins-ignorelist` + /// + /// ## Example + /// ```python + /// def find_max(list_of_lists): + /// max = 0 + /// for flat_list in list_of_lists: + /// for value in flat_list: + /// max = max(max, value) # TypeError: 'int' object is not callable + /// return max + /// ``` + /// + /// Use instead: + /// ```python + /// def find_max(list_of_lists): + /// result = 0 + /// for flat_list in list_of_lists: + /// for value in flat_list: + /// result = max(result, value) + /// return result + /// ``` + /// + /// * [Why is it a bad idea to name a variable `id` in Python?_](https://stackoverflow.com/questions/77552/id-is-a-bad-variable-name-in-python) pub struct BuiltinVariableShadowing { pub name: String, } @@ -21,6 +59,47 @@ impl Violation for BuiltinVariableShadowing { } define_violation!( + /// ## What it does + /// Checks for any function arguments that use the same name as a builtin. + /// + /// ## Why is this bad? + /// Reusing a builtin name for the name of an argument increases the + /// difficulty of reading and maintaining the code, and can cause + /// non-obvious errors, as readers may mistake the argument for the + /// builtin and vice versa. + /// + /// Builtins can be marked as exceptions to this rule via the + /// [`flake8-builtins.builtins-ignorelist`] configuration option. + /// + /// ## Options + /// + /// * `flake8-builtins.builtins-ignorelist` + /// + /// ## Example + /// ```python + /// def remove_duplicates(list, list2): + /// result = set() + /// for value in list: + /// result.add(value) + /// for value in list2: + /// result.add(value) + /// return list(result) # TypeError: 'list' object is not callable + /// ``` + /// + /// Use instead: + /// ```python + /// def remove_duplicates(list1, list2): + /// result = set() + /// for value in list1: + /// result.add(value) + /// for value in list2: + /// result.add(value) + /// return list(result) + /// ``` + /// + /// ## References + /// - [_Is it bad practice to use a built-in function name as an attribute or method identifier?_](https://stackoverflow.com/questions/9109333/is-it-bad-practice-to-use-a-built-in-function-name-as-an-attribute-or-method-ide) + /// - [_Why is it a bad idea to name a variable `id` in Python?_](https://stackoverflow.com/questions/77552/id-is-a-bad-variable-name-in-python) pub struct BuiltinArgumentShadowing { pub name: String, } @@ -34,6 +113,48 @@ impl Violation for BuiltinArgumentShadowing { } define_violation!( + /// ## What it does + /// Checks for any class attributes that use the same name as a builtin. + /// + /// ## Why is this bad? + /// Reusing a builtin name for the name of an attribute increases the + /// difficulty of reading and maintaining the code, and can cause + /// non-obvious errors, as readers may mistake the attribute for the + /// builtin and vice versa. + /// + /// Builtins can be marked as exceptions to this rule via the + /// [`flake8-builtins.builtins-ignorelist`] configuration option, or + /// converted to the appropriate dunder method. + /// + /// ## Options + /// + /// * `flake8-builtins.builtins-ignorelist` + /// + /// ## Example + /// ```python + /// class Shadow: + /// def int(): + /// return 0 + /// ``` + /// + /// Use instead: + /// ```python + /// class Shadow: + /// def to_int(): + /// return 0 + /// ``` + /// + /// Or: + /// ```python + /// class Shadow: + /// # Callable as `int(shadow)` + /// def __int__(): + /// return 0 + /// ``` + /// + /// ## References + /// - [_Is it bad practice to use a built-in function name as an attribute or method identifier?_](https://stackoverflow.com/questions/9109333/is-it-bad-practice-to-use-a-built-in-function-name-as-an-attribute-or-method-ide) + /// - [_Why is it a bad idea to name a variable `id` in Python?_](https://stackoverflow.com/questions/77552/id-is-a-bad-variable-name-in-python) pub struct BuiltinAttributeShadowing { pub name: String, }