Add a ScopeKind for the __class__ cell

[ntBre]

Summary

This PR aims to resolve (or help to resolve) #18442 and #19357 by encoding the CPython semantics around the __class__ cell in our semantic model. Namely,

__class__ is an implicit closure reference created by the compiler if any methods in a class body refer to either __class__ or super.

from the Python docs.

As noted in the variant docs by @AlexWaygood, we don't fully model this behavior, opting always to create the __class__ cell binding in a new ScopeKind::DunderClassCell around each method definition, without checking if any method in the class body actually refers to __class__ or super.

As such, this PR fixes #18442 but not #19357.

Test Plan

Existing tests, plus the tests from #19783, which now pass without any rule-specific code.

Note that we opted not to alter the behavior of F841 here because flagging __class__ in these cases still seems helpful. See the discussion in #20048 (comment) and in the test comments for more information.

[github-actions]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

[ntBre]

I pulled in the tests from #19783 (and added @mikeleppane as a co-author, thank you!) and the issue with those rules is now resolved, with one additional change to the semantic model to reuse the cell binding for __class__ in add_binding (c1604dd).

I also tried the tests from #19424, but I think these still need some rule-specific code, so I decided to leave that as a separate PR. The changes here should still help, but they aren't sufficient on their own.

Finally, I applied our class_variables_visible change in a couple more places. Those were some of the last references to "__class__" that I found from grepping.

[AlexWaygood]

This is great!! Would you be up for trying to apply the same change to ty as well?

[AlexWaygood]

Looks great!

[dscorbett]

This comment is not true:

# The following three cases should technically be allowed because `__class__`
# is a nonlocal variable in the method scope. However, `__class__` isn't easily
# accessible in other methods, so setting it like this is still likely to be an
# error, and we still emit a diagnostic. See https://github.com/astral-sh/ruff/pull/20048#discussion_r2296252395
class A:
    def set_class(self, cls):
        __class__ = cls

__class__ is a local variable there because it is assigned. It would only be nonlocal with a nonlocal __class__ statement.

[ntBre]

Ah I see, thanks. For some reason I thought this should work even without the explicit nonlocal, but I think this resolves my confusion. This case is now fully resolved, not triggering PLE0117 or F841:

class A:
    def set_class(self, cls):
        nonlocal __class__
        __class__ = cls

and these cases are properly flagged because the local __class__ variable is unused:

class A:
    class B:
        def set_class(self, cls):
            __class__ = cls


class A:
    def foo():
        class B:
            print(__class__)
            def set_class(self, cls):
                __class__ = cls

I'll update the first test case with the actual nonlocal statement and also fix the comment.

[dscorbett]

In the following example, __class__ is a local variable, which breaks the zero-argument super.

class C:
    def __str__(self):
        if False:
            __class__ = C
        return super().__str__()
print(str(C()))

With this PR, will that be handled properly?

[AlexWaygood]

With this PR, will that be handled properly?

No, that issue will still be outstanding after this PR has merged. (That doesn't mean that we won't necessarily fix it in the future. But while it's a valid bug report, it's probably low priority for us to fix it since it seems unlikely that a human or LLM would ever write that in real code :-)

[ntBre]

I think #19424 will still be necessary to fix that, if that's the same issue. But the local variable should shadow the nonlocal binding from the cell after this PR, so I think it makes it slightly easier to resolve the other issue too, at least.