Add allow-unused-imports setting for unused-import rule (F401) (#13601)

## Summary
Resolves https://github.com/astral-sh/ruff/issues/9962 by allowing a
configuration setting `allowed-unused-imports`

TODO:
- [x] Figure out the correct name and place for the setting; currently,
I have added it top level.
- [x] The comparison is pretty naive. I tried using `glob::Pattern` but
couldn't get it to work in the configuration.
- [x] Add tests
- [x] Update documentations

## Test Plan

`cargo test`

crates/ruff_linter/resources/test/fixtures/pyflakes/F401_31.py

@@ -0,0 +1,12 @@
+"""
+Test: allowed-unused-imports
+"""
+
+# OK
+import hvplot.pandas
+import hvplot.pandas.plots
+from hvplot.pandas import scatter_matrix
+from hvplot.pandas.plots import scatter_matrix
+
+# Errors
+from hvplot.pandas_alias import scatter_matrix

crates/ruff_linter/src/rules/pyflakes/mod.rs

@@ -327,6 +327,21 @@ mod tests {
         assert_messages!(snapshot, diagnostics);
         Ok(())
     }
+    #[test_case(Rule::UnusedImport, Path::new("F401_31.py"))]
+    fn f401_allowed_unused_imports_option(rule_code: Rule, path: &Path) -> Result<()> {
+        let diagnostics = test_path(
+            Path::new("pyflakes").join(path).as_path(),
+            &LinterSettings {
+                pyflakes: pyflakes::settings::Settings {
+                    allowed_unused_imports: vec!["hvplot.pandas".to_string()],
+                    ..pyflakes::settings::Settings::default()
+                },
+                ..LinterSettings::for_rule(rule_code)
+            },
+        )?;
+        assert_messages!(diagnostics);
+        Ok(())
+    }
 
     #[test]
     fn f841_dummy_variable_rgx() -> Result<()> {
@@ -427,7 +442,7 @@ mod tests {
             Path::new("pyflakes/project/foo/bar.py"),
             &LinterSettings {
                 typing_modules: vec!["foo.typical".to_string()],
-                ..LinterSettings::for_rules(vec![Rule::UndefinedName])
+                ..LinterSettings::for_rule(Rule::UndefinedName)
             },
         )?;
         assert_messages!(diagnostics);
@@ -440,7 +455,7 @@ mod tests {
             Path::new("pyflakes/project/foo/bop/baz.py"),
             &LinterSettings {
                 typing_modules: vec!["foo.typical".to_string()],
-                ..LinterSettings::for_rules(vec![Rule::UndefinedName])
+                ..LinterSettings::for_rule(Rule::UndefinedName)
             },
         )?;
         assert_messages!(diagnostics);
@@ -455,8 +470,9 @@ mod tests {
             &LinterSettings {
                 pyflakes: pyflakes::settings::Settings {
                     extend_generics: vec!["django.db.models.ForeignKey".to_string()],
+                    ..pyflakes::settings::Settings::default()
                 },
-                ..LinterSettings::for_rules(vec![Rule::UnusedImport])
+                ..LinterSettings::for_rule(Rule::UnusedImport)
             },
         )?;
         assert_messages!(snapshot, diagnostics);

crates/ruff_linter/src/rules/pyflakes/rules/unused_import.rs

@@ -6,6 +6,7 @@ use std::collections::BTreeMap;
 
 use ruff_diagnostics::{Applicability, Diagnostic, Fix, FixAvailability, Violation};
 use ruff_macros::{derive_message_formats, violation};
+use ruff_python_ast::name::QualifiedName;
 use ruff_python_ast::{self as ast, Stmt};
 use ruff_python_semantic::{
     AnyImport, BindingKind, Exceptions, Imported, NodeId, Scope, SemanticModel, SubmoduleImport,
@@ -308,6 +309,20 @@ pub(crate) fn unused_import(checker: &Checker, scope: &Scope, diagnostics: &mut
             continue;
         }
 
+        // If an import was marked as allowed, avoid treating it as unused.
+        if checker
+            .settings
+            .pyflakes
+            .allowed_unused_imports
+            .iter()
+            .any(|allowed_unused_import| {
+                let allowed_unused_import = QualifiedName::from_dotted_name(allowed_unused_import);
+                import.qualified_name().starts_with(&allowed_unused_import)
+            })
+        {
+            continue;
+        }
+
         let import = ImportBinding {
             name,
             import,

crates/ruff_linter/src/rules/pyflakes/settings.rs

@@ -7,6 +7,7 @@ use std::fmt;
 #[derive(Debug, Clone, Default, CacheKey)]
 pub struct Settings {
     pub extend_generics: Vec<String>,
+    pub allowed_unused_imports: Vec<String>,
 }
 
 impl fmt::Display for Settings {
@@ -15,7 +16,8 @@ impl fmt::Display for Settings {
             formatter = f,
             namespace = "linter.pyflakes",
             fields = [
-                self.extend_generics | debug
+                self.extend_generics | debug,
+                self.allowed_unused_imports | debug
             ]
         }
         Ok(())

crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__f401_allowed_unused_imports_option.snap

@@ -0,0 +1,16 @@
+---
+source: crates/ruff_linter/src/rules/pyflakes/mod.rs
+---
+F401_31.py:12:33: F401 [*] `hvplot.pandas_alias.scatter_matrix` imported but unused
+   |
+11 | # Errors
+12 | from hvplot.pandas_alias import scatter_matrix
+   |                                 ^^^^^^^^^^^^^^ F401
+   |
+   = help: Remove unused import: `hvplot.pandas_alias.scatter_matrix`
+
+ℹ Safe fix
+9  9  | from hvplot.pandas.plots import scatter_matrix
+10 10 | 
+11 11 | # Errors
+12    |-from hvplot.pandas_alias import scatter_matrix