Add autofix that adds `from __future__ import annotations` only when it would be useful

[AlexWaygood]

Summary

Several of Ruff's rules will be more aggressive in the diagnostics and autofixes they emit if from __future__ import annotations is enabled in the file:

• UP035
• UP045
• TC001
• TC002
• TC003
• (There may be others)

For this reason, it's often useful to have from __future__ import annotations at the top of your Python file if you're running Ruff. Ruff knows that it can do a lot more with your code in these situations!

Ruff provides a lint rule FA100 that detects situations where UP035 or UP045 would make autofix edits if from __future__ import annotations was present, and complains that you should probably add that import. But this rule has two problems:

• It does not have an autofix
• It doesn't tackle situations where other rules such as the TC ones might make edits to your code if from __future__ import annotations were present in the module

Ruff provides a way to ensure that from __future__ import annotations is imported in every file in your project: you can use I002 in combination with the required-imports setting. But applying this to a large existing codebase might cause a huge diff with many unnecessary edits in it, which is probably undesirable.

I propose that we:

• Add a configuration option to make FA100 more expansive, so that it also triggers in situations where the TC rules might make changes to your code if from __future__ import annotations was present.
  • I think this should be behind a configuration option, as the TC rules are very opinionated: not all users will want FA100 to also apply to these situations. Alternatively, we could add a new FA* rule that sits alongside FA100 and flags these situations -- this comment argues in favour of doing that instead.
• Check to see if there are other rules where Ruff would be more aggressive if from __future__ import annotations were present. Should we have FA100 also flag modules where these other rules would make edits if from __future__ import annotations were present in the file?
• Add an autofix to FA100 that auto-adds from __future__ import annotations

[MichaReiser]

Is the reason for adding a new option and not making this the default behavior because we think this behavior shouldn't be the default or is it mainly for backwards compatibility?

I'm asking because I'm wondering what the behavior would be if we recategorize our rules. I feel like, nudging users towards adding the import is probably the right default behavior. Although I'm not sure where to put this rule if we recategorize the rules: Maybe a style rule?

[MichaReiser]

What's a bit awkward about FA100 is that the behavior is only useful when the other rules are enabled too. Should FA100 not flag adding a from __future__ import annotations if e.g. the TC rules are disabled and adding the future import is only useful to a TC rule?

A third option is to have a global option that TC and the few UP rules check so that they would add the future import as part of their fixes.

To make a decision here, I'd find it useful to have a full list of rules that change behavior based on the presence of a future import with a short description what they use it for.

[AlexWaygood]

Is the reason for adding a new option and not making this the default behavior because we think this behavior shouldn't be the default or is it mainly for backwards compatibility?

The whole reason why we received a request for improved autofixes here was that users didn't want to use I002 to ensure that the import was added to every module. They found that too noisy as it made lots of unnecessary edits; they wanted something more targeted that would only add the import in situations where it would be useful.

It's pretty subjective whether adding from __future__ import annotations to a particular module is going to be useful or not. The TC rules are very opinionated; I would guess many fewer users have those enabled than the UP rules. If you don't have the TC rules enabled and you only want from __future__ import annotations added where it would be useful, you'll probably be annoyed if FA100 starts adding the import to files on the basis that it would enable different behaviour from the TC rules.

So I don't think this new behaviour should be the default. Since writing this issue up, I've started leaning towards adding a separate FA rule rather than introducing a new configuration option to FA100.

I think your third option could also make a lot of sense. Though it might mean that we'd end up deprecating FA100, since it would essentially become redundant if its behaviour was just incorporated into the UP rules' autofix

[AlexWaygood]

Although I'm not sure where to put this rule if we recategorize the rules: Maybe a style rule?

Definitely stylistic IMO. There can be some minor performance and memory gains from adding the import, but it's rarely noticeable. The main reason for adding it is so that you don't have to quote annotations so often in order to use forward references, and so that you can use newer typing features on older Python versions. They're all primarily stylistic concerns.

[ntBre]

Do you think there are cases where users have the TC rules enabled but still don't want this behavior? That was the main reason I thought we could leave out the config option (though I added one in my PR): enabling the TC rules kind of serves as a proxy for the config option. I think you also have to have lint.flake8-type-checking.strict = true in many cases, so to opt in to this new behavior you already need to enable both rules and possibly configure strict. Maybe that's just an implementation detail of my current approach, though.

I do like the idea of a global option, it feels kind of awkward adding these FA100 calls everywhere.

Similarly, I didn't really like the idea of another rule because FA100 is already quite limited in scope. It made sense to me to expand its scope rather than add another narrowly-scoped rule, but maybe that's preferable. I guess it gives users the same kind of flexibility as the config option and could be more intuitive. FA100's name also doesn't really make sense when applied to the TC rules, anyway. That definitely supports adding a separate rule.

The rules that currently use FA100 are:

• UP007 and UP045 (PEP 604 annotations)
• UP006 (PEP 585 annotations)

I believe these all use the __future__ import to backport their changes to earlier Python versions. For example, the PEP 604 | annotations are only allowed on 3.10 but can be used earlier with a __future__ import.

(UP035 is mentioned in the issue body, but I didn't see any FA100 integration unless I overlooked it. I'm guessing @AlexWaygood meant UP007 since it's tied closely to UP045 but I could also just be wrong.)

I can work on a list of potential new uses today.

[AlexWaygood]

(UP035 is mentioned in the issue body, but I didn't see any FA100 integration unless I overlooked it. I'm guessing @AlexWaygood meant UP007 since it's tied closely to UP045 but I could also just be wrong.)

UP035 only suggests switching from typing.Dict to dict here if the target-version is set to Python 3.9+ or from __future__ import annotations is present: https://play.ruff.rs/e7718e04-9bbd-4156-bc71-103634b01f36.

And if you're on Python <=3.8 and you don't have from __future__ import annotations there, FA100 tells you to add it: https://play.ruff.rs/4ee281fb-34b8-4f99-adf9-6633ea76ee69

[ntBre]

I'm seeing an UP006 diagnostic in your first playground link, not deprecated-import (UP035).