From 77bf58087c522575ba6fd345e3f0d0b2726645c4 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 5 Aug 2024 22:02:56 +0100 Subject: [PATCH] Add more docs on fix safety --- .../src/rules/ruff/rules/sort_dunder_all.rs | 9 +++++++-- .../src/rules/ruff/rules/sort_dunder_slots.rs | 20 +++++++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_all.rs b/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_all.rs index 2e52956ed45c8..6b0ebbaaf4fc5 100644 --- a/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_all.rs +++ b/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_all.rs @@ -54,8 +54,13 @@ use crate::rules::ruff::rules::sequence_sorting::{ /// /// ## Fix safety /// This rule's fix is marked as always being safe, in that -/// it should never alter the semantics of any Python code. -/// However, note that for multiline `__all__` definitions +/// it should very rarely alter the semantics of any Python code. +/// However, note that (although it's rare) the value of `__all__` +/// could be read by code elsewhere that depends on the exact +/// iteration order of the items in `__all__`, in which case this +/// rule's fix could theoretically cause breakage. +/// +/// Note also that for multiline `__all__` definitions /// that include comments on their own line, it can be hard /// to tell where the comments should be moved to when sorting /// the contents of `__all__`. While this rule's fix will diff --git a/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_slots.rs b/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_slots.rs index 1e6da67a8b0f5..dbc40493b8520 100644 --- a/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_slots.rs +++ b/crates/ruff_linter/src/rules/ruff/rules/sort_dunder_slots.rs @@ -34,6 +34,26 @@ use itertools::izip; /// class Dog: /// __slots__ = "breed", "name" /// ``` +/// +/// ## Fix safety +/// This rule's fix is marked as unsafe whenever Ruff can detect that code +/// elsewhere in the same file reads the `__slots__` variable in some way. +/// This is because the order of the items in `__slots__` may have semantic +/// significance if the `__slots__` of a class is being iterated over, or +/// being assigned to another value. +/// +/// In the vast majority of other cases, this rule's fix is unlikely to +/// cause breakage; as such, Ruff will otherwise mark this rule's fix as +/// safe. However, note that (although it's rare) the value of `__slots__` +/// could still be read by code outside of the module in which the +/// `__slots__` definition occurs, in which case this rule's fix could +/// theoretically cause breakage. +/// +/// Additionally, note that for multiline `__slots__` definitions that +/// include comments on their own line, it can be hard to tell where the +/// comments should be moved to when sorting the contents of `__slots__`. +/// While this rule's fix will never delete a comment, it might *sometimes* +/// move a comment to an unexpected location. #[violation] pub struct UnsortedDunderSlots { class_name: ast::name::Name,