Flag, but don't fix, unused imports in ModuleNotFoundError blocks

[charliermarsh]

Summary

This PR acts on the resolved solution from #3378. In #3288, we changed Ruff to avoid flagging unused import in ModuleNotFoundError blocks, like:

try:
    import orjson

    return True
except ModuleNotFoundError:
    return False

This is a common pattern used to detect module availability, and removing those imports tends to break code.

However, these imports are unused, and it's confusing that Ruff doesn't flag them. Further, this isn't the recommended way to test for module availability -- we have importlib APIs for that.

So this PR modifies the logic to (1) flag unused imports in blocks like the above, but (2) avoid autofixing them, and (3) using a dedicated message to point the user to those importlib APIs.

Closes #3378.

[charliermarsh]

\cc @henryiii

[github-actions]

PR Check Results

Benchmark

Linux

group                                      main                                   pr
-----                                      ----                                   --
linter/all-rules/large/dataset.py          1.00     16.2±0.06ms     2.5 MB/sec    1.00     16.2±0.05ms     2.5 MB/sec
linter/all-rules/numpy/ctypeslib.py        1.01      4.3±0.01ms     3.9 MB/sec    1.00      4.2±0.01ms     3.9 MB/sec
linter/all-rules/numpy/globals.py          1.01    596.3±1.49µs     4.9 MB/sec    1.00    589.1±1.19µs     5.0 MB/sec
linter/all-rules/pydantic/types.py         1.00      7.2±0.02ms     3.6 MB/sec    1.00      7.2±0.02ms     3.6 MB/sec
linter/default-rules/large/dataset.py      1.01      8.7±0.02ms     4.7 MB/sec    1.00      8.6±0.03ms     4.7 MB/sec
linter/default-rules/numpy/ctypeslib.py    1.03   1972.9±4.29µs     8.4 MB/sec    1.00   1924.5±3.27µs     8.7 MB/sec
linter/default-rules/numpy/globals.py      1.08   230.9±15.13µs    12.8 MB/sec    1.00    214.1±0.46µs    13.8 MB/sec
linter/default-rules/pydantic/types.py     1.00      4.1±0.02ms     6.3 MB/sec    1.00      4.1±0.02ms     6.3 MB/sec

Windows

group                                      main                                   pr
-----                                      ----                                   --
linter/all-rules/large/dataset.py          1.02     17.3±0.68ms     2.4 MB/sec    1.00     16.9±0.47ms     2.4 MB/sec
linter/all-rules/numpy/ctypeslib.py        1.01      4.6±0.19ms     3.6 MB/sec    1.00      4.6±0.18ms     3.6 MB/sec
linter/all-rules/numpy/globals.py          1.00   604.6±25.37µs     4.9 MB/sec    1.00   602.9±64.18µs     4.9 MB/sec
linter/all-rules/pydantic/types.py         1.01      7.7±0.50ms     3.3 MB/sec    1.00      7.6±0.24ms     3.3 MB/sec
linter/default-rules/large/dataset.py      1.02      9.4±0.32ms     4.3 MB/sec    1.00      9.2±0.26ms     4.4 MB/sec
linter/default-rules/numpy/ctypeslib.py    1.02      2.1±0.21ms     8.0 MB/sec    1.00      2.0±0.08ms     8.2 MB/sec
linter/default-rules/numpy/globals.py      1.00    223.5±8.62µs    13.2 MB/sec    1.02   228.1±13.03µs    12.9 MB/sec
linter/default-rules/pydantic/types.py     1.01      4.4±0.15ms     5.8 MB/sec    1.00      4.3±0.20ms     5.9 MB/sec

[MichaReiser]

Not sure if I'm blind but where do we initialize in_except_handler?

Is it possible for both ignore_init and in_except_handler to be true? If not, how about we create an enum instead UnusedImportKind

[charliermarsh]

It's in ast/mod.rs, which GitHub collapsed 🙈

[konstin]

i've definitely written that kind that of check and not realized that importlib.util.find_spec is a thing

[MichaReiser]

Nit: Can we add some documentation about the different tuple fields or maybe it's best to create a struct at this point with named fields to improve readability

[charliermarsh]

Shoot, this got auto-merged. Yes I'll do a pass on this.