Forbid use of super in NamedTuple subclasses

Author: charliermarsh

crates/ty_python_semantic/resources/mdtest/named_tuple.md

@@ -408,3 +408,67 @@ class Vec2(NamedTuple):
 
 Vec2(0.0, 0.0)
 ```
+
+## `super()` is not supported in NamedTuple methods
+
+Using `super()` in a method of a `NamedTuple` subclass will raise an exception at runtime. In Python
+3.14+, a `TypeError` is raised; in earlier versions, a confusing `RuntimeError` about `__classcell__`
+is raised.
+
+```py
+from typing import NamedTuple
+
+class F(NamedTuple):
+    x: int
+
+    def method(self):
+        # error: [super-call-in-named-tuple-method] "Cannot use `super()` in a method of NamedTuple subclass `F`"
+        super()
+
+    def method_with_args(self):
+        # error: [super-call-in-named-tuple-method] "Cannot use `super()` in a method of NamedTuple subclass `F`"
+        super(F, self)
+
+    def method_with_different_pivot(self):
+        # Even passing a different pivot class fails - the error happens at class definition
+        # time when the compiler sees the name `super`, regardless of arguments
+        # error: [super-call-in-named-tuple-method] "Cannot use `super()` in a method of NamedTuple subclass `F`"
+        super(tuple, self)
+
+    @classmethod
+    def class_method(cls):
+        # error: [super-call-in-named-tuple-method] "Cannot use `super()` in a method of NamedTuple subclass `F`"
+        super()
+
+    @staticmethod
+    def static_method():
+        # error: [super-call-in-named-tuple-method] "Cannot use `super()` in a method of NamedTuple subclass `F`"
+        super()
+
+    @property
+    def prop(self):
+        # error: [super-call-in-named-tuple-method] "Cannot use `super()` in a method of NamedTuple subclass `F`"
+        return super()
+```
+
+However, classes that **inherit from** a `NamedTuple` subclass (but don't directly inherit from
+`NamedTuple`) can use `super()` normally:
+
+```py
+from typing import NamedTuple
+
+class Base(NamedTuple):
+    x: int
+
+class Child(Base):
+    def method(self):
+        super()
+```
+
+And regular classes that don't inherit from `NamedTuple` at all can use `super()` as normal:
+
+```py
+class Regular:
+    def method(self):
+        super()  # fine
+```

crates/ty_python_semantic/src/types/class.rs

@@ -19,7 +19,7 @@ use crate::semantic_index::{
 use crate::types::bound_super::BoundSuperError;
 use crate::types::constraints::{ConstraintSet, IteratorConstraintsExtension};
 use crate::types::context::InferContext;
-use crate::types::diagnostic::INVALID_TYPE_ALIAS_TYPE;
+use crate::types::diagnostic::{INVALID_TYPE_ALIAS_TYPE, SUPER_CALL_IN_NAMED_TUPLE_METHOD};
 use crate::types::enums::enum_metadata;
 use crate::types::function::{DataclassTransformerParams, KnownFunction};
 use crate::types::generics::{
@@ -5546,6 +5546,20 @@ impl KnownClass {
                             return;
                         };
 
+                        // Check if the enclosing class is a `NamedTuple`, which forbids the use of `super()`.
+                        if CodeGeneratorKind::NamedTuple.matches(db, enclosing_class, None) {
+                            if let Some(builder) = context
+                                .report_lint(&SUPER_CALL_IN_NAMED_TUPLE_METHOD, call_expression)
+                            {
+                                builder.into_diagnostic(format_args!(
+                                    "Cannot use `super()` in a method of NamedTuple subclass `{}`",
+                                    enclosing_class.name(db)
+                                ));
+                            }
+                            overload.set_return_type(Type::unknown());
+                            return;
+                        }
+
                         // The type of the first parameter if the given scope is function-like (i.e. function or lambda).
                         // `None` if the scope is not function-like, or has no parameters.
                         let first_param = match scope.node(db) {
@@ -5585,6 +5599,22 @@ impl KnownClass {
                         overload.set_return_type(bound_super);
                     }
                     [Some(pivot_class_type), Some(owner_type)] => {
+                        // Check if the enclosing class is a `NamedTuple`, which forbids the use of `super()`.
+                        if let Some(enclosing_class) = nearest_enclosing_class(db, index, scope) {
+                            if CodeGeneratorKind::NamedTuple.matches(db, enclosing_class, None) {
+                                if let Some(builder) = context
+                                    .report_lint(&SUPER_CALL_IN_NAMED_TUPLE_METHOD, call_expression)
+                                {
+                                    builder.into_diagnostic(format_args!(
+                                        "Cannot use `super()` in a method of NamedTuple subclass `{}`",
+                                        enclosing_class.name(db)
+                                    ));
+                                }
+                                overload.set_return_type(Type::unknown());
+                                return;
+                            }
+                        }
+
                         let bound_super = BoundSuperType::build(db, *pivot_class_type, *owner_type)
                             .unwrap_or_else(|err| {
                                 err.report_diagnostic(context, call_expression.into());

crates/ty_python_semantic/src/types/diagnostic.rs

@@ -101,6 +101,7 @@ pub(crate) fn register_lints(registry: &mut LintRegistryBuilder) {
     registry.register_lint(&POSSIBLY_MISSING_IMPORT);
     registry.register_lint(&POSSIBLY_UNRESOLVED_REFERENCE);
     registry.register_lint(&SUBCLASS_OF_FINAL_CLASS);
+    registry.register_lint(&SUPER_CALL_IN_NAMED_TUPLE_METHOD);
     registry.register_lint(&OVERRIDE_OF_FINAL_METHOD);
     registry.register_lint(&TYPE_ASSERTION_FAILURE);
     registry.register_lint(&TOO_MANY_POSITIONAL_ARGUMENTS);
@@ -1760,6 +1761,33 @@ declare_lint! {
     }
 }
 
+declare_lint! {
+    /// ## What it does
+    /// Checks for calls to `super()` inside methods of `NamedTuple` subclasses.
+    ///
+    /// ## Why is this bad?
+    /// Using `super()` in a method of a `NamedTuple` subclass will raise an exception at runtime.
+    ///
+    /// ## Examples
+    /// ```python
+    /// from typing import NamedTuple
+    ///
+    /// class F(NamedTuple):
+    ///     x: int
+    ///
+    ///     def method(self):
+    ///         super()  # error: super() is not supported in methods of NamedTuple subclasses
+    /// ```
+    ///
+    /// ## References
+    /// - [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)
+    pub(crate) static SUPER_CALL_IN_NAMED_TUPLE_METHOD = {
+        summary: "detects `super()` calls in methods of `NamedTuple` subclasses",
+        status: LintStatus::preview("1.0.0"),
+        default_level: Level::Error,
+    }
+}
+
 declare_lint! {
     /// ## What it does
     /// Checks for calls to `reveal_type` without importing it.