[ty] Refine Callable class-decorator fallback for unknown results (#25250)

## Summary

This PR addresses a TODO from #25091 whereby we preserved the class
binding for every `Callable`
decorator. We now respect explicit return annotations on `Callable`.

For example, this now remains a replacement rather than being treated as
class-preserving:

```python
from typing import Callable, TypeVar

T = TypeVar("T")

def decorator_factory() -> Callable[[type[object]], T]:
    raise NotImplementedError

@decorator_factory()
class Decorated: ...

reveal_type(Decorated)  # Unknown
```

Author: charliermarsh

crates/ty_python_semantic/resources/mdtest/decorators.md

@@ -535,6 +535,26 @@ specialized_explicit_return_decorator = ExplicitReturnDecorator[int]()
 class SpecializedExplicitReturnCallableInstanceDecorated: ...
 
 reveal_type(SpecializedExplicitReturnCallableInstanceDecorated)  # revealed: int
+
+def function_decorator(func: Callable[..., T]) -> Callable[..., T]:
+    return func
+
+@function_decorator
+def explicit_return_callable_decorator(cls) -> T:
+    raise NotImplementedError
+
+@explicit_return_callable_decorator
+class ExplicitReturnCallableDecorated: ...
+
+reveal_type(ExplicitReturnCallableDecorated)  # revealed: Unknown
+
+def regular_callable_replacement_factory() -> Callable[[type[object]], T]:
+    raise NotImplementedError
+
+@regular_callable_replacement_factory()
+class RegularCallableReplacementDecorated: ...
+
+reveal_type(RegularCallableReplacementDecorated)  # revealed: Unknown
 ```
 
 An unknown class decorator still makes the class binding unknown:

crates/ty_python_semantic/src/types/call/bind.rs

@@ -28,7 +28,7 @@ use crate::dunder_all::dunder_all_names;
 use crate::place::{DefinedPlace, Definedness, Place, known_module_symbol};
 use crate::subscript::PyIndex;
 use crate::types::call::arguments::{CallArgumentTypes, Expansion, is_expandable_type};
-use crate::types::callable::CallableTypeKind;
+use crate::types::callable::{CallableFunctionProvenance, CallableTypeKind};
 use crate::types::constraints::{ConstraintSet, ConstraintSetBuilder, PathBounds, Solutions};
 use crate::types::diagnostic::{
     CALL_NON_CALLABLE, CALL_TOP_CALLABLE, CONFLICTING_ARGUMENT_FORMS, INVALID_ARGUMENT_TYPE,
@@ -7483,6 +7483,7 @@ fn asynccontextmanager_return_type<'db>(db: &'db dyn Db, func_ty: Type<'db>) ->
         db,
         CallableSignature::single(new_signature),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     )))
 }
 

crates/ty_python_semantic/src/types/callable.rs

@@ -163,6 +163,7 @@ impl<'db> Type<'db> {
                                 db,
                                 CallableSignature::from_overloads(signatures),
                                 callable.kind(db),
+                                callable.provenance(db),
                             )
                         }))
                     }
@@ -183,6 +184,7 @@ impl<'db> Type<'db> {
                                     db,
                                     CallableSignature::from_overloads(signatures),
                                     callable.kind(db),
+                                    callable.provenance(db),
                                 ));
                             }
                         }
@@ -230,13 +232,15 @@ impl<'db> Type<'db> {
                 db,
                 CallableSignature::from_overloads(method.signatures(db)),
                 CallableTypeKind::Regular,
+                CallableFunctionProvenance::None,
             ))),
 
             Type::WrapperDescriptor(wrapper_descriptor) => {
                 Some(CallableTypes::one(CallableType::new(
                     db,
                     CallableSignature::from_overloads(wrapper_descriptor.signatures(db)),
                     CallableTypeKind::Regular,
+                    CallableFunctionProvenance::None,
                 )))
             }
 
@@ -324,6 +328,33 @@ pub enum CallableTypeKind {
     ParamSpecValue,
 }
 
+/// Source-function provenance retained by a callable signature.
+///
+/// A [`CallableType`] can describe a bare callable shape, such as one from `Callable[...]`. For
+/// function-like sources, such as a [`FunctionType`] upcast to a [`CallableType`] or a lambda, this
+/// records whether the source function has an explicit return annotation.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, get_size2::GetSize)]
+pub enum CallableFunctionProvenance {
+    /// The callable does not retain source-function provenance.
+    None,
+
+    /// The callable came from a function without an explicit return annotation.
+    ImplicitReturn,
+
+    /// The callable came from a function with an explicit return annotation.
+    ExplicitReturn,
+}
+
+impl CallableFunctionProvenance {
+    pub(crate) fn from_function_return_annotation(has_explicit_return_annotation: bool) -> Self {
+        if has_explicit_return_annotation {
+            Self::ExplicitReturn
+        } else {
+            Self::ImplicitReturn
+        }
+    }
+}
+
 /// A "policy" enum that describes how `type[]` types should be upcast
 /// to `Callable` types.
 ///
@@ -380,6 +411,20 @@ pub struct CallableType<'db> {
     pub(crate) signatures: CallableSignature<'db>,
 
     pub(super) kind: CallableTypeKind,
+
+    /// Source-function return-annotation provenance retained by this callable.
+    ///
+    /// Function-like values can retain their source-function provenance when converted to a
+    /// callable signature:
+    /// ```python
+    /// def decorator(cls) -> object: ...
+    /// ```
+    ///
+    /// Callables that are only known from a callable shape do not retain that provenance:
+    /// ```python
+    /// def decorator_factory() -> Callable[[type[object]], object]: ...
+    /// ```
+    pub(crate) provenance: CallableFunctionProvenance,
 }
 
 pub(super) fn walk_callable_type<'db, V: visitor::TypeVisitor<'db> + ?Sized>(
@@ -401,6 +446,7 @@ impl<'db> CallableType<'db> {
             db,
             CallableSignature::single(signature),
             CallableTypeKind::Regular,
+            CallableFunctionProvenance::None,
         )
     }
 
@@ -409,6 +455,7 @@ impl<'db> CallableType<'db> {
             db,
             CallableSignature::single(signature),
             CallableTypeKind::FunctionLike,
+            CallableFunctionProvenance::None,
         )
     }
 
@@ -420,6 +467,7 @@ impl<'db> CallableType<'db> {
             db,
             CallableSignature::single(Signature::new(parameters, Type::unknown())),
             CallableTypeKind::ParamSpecValue,
+            CallableFunctionProvenance::None,
         )
     }
 
@@ -441,7 +489,12 @@ impl<'db> CallableType<'db> {
     }
 
     pub(crate) fn into_regular(self, db: &'db dyn Db) -> CallableType<'db> {
-        CallableType::new(db, self.signatures(db), CallableTypeKind::Regular)
+        CallableType::new(
+            db,
+            self.signatures(db),
+            CallableTypeKind::Regular,
+            self.provenance(db),
+        )
     }
 
     /// Returns the reduced callable produced by partially applying selected overloads.
@@ -453,6 +506,7 @@ impl<'db> CallableType<'db> {
             db,
             CallableSignature::partially_apply(db, overloads)?,
             CallableTypeKind::Regular,
+            CallableFunctionProvenance::None,
         ))
     }
 
@@ -482,6 +536,7 @@ impl<'db> CallableType<'db> {
             db,
             self.signatures(db).bind_self(db, self_type),
             self.kind(db),
+            self.provenance(db),
         )
     }
 
@@ -490,6 +545,7 @@ impl<'db> CallableType<'db> {
             db,
             self.signatures(db).apply_self(db, self_type),
             self.kind(db),
+            self.provenance(db),
         )
     }
 
@@ -498,7 +554,12 @@ impl<'db> CallableType<'db> {
     /// Specifically, this represents a callable type with a single signature:
     /// `(*args: object, **kwargs: object) -> Never`.
     pub(crate) fn bottom(db: &'db dyn Db) -> CallableType<'db> {
-        Self::new(db, CallableSignature::bottom(), CallableTypeKind::Regular)
+        Self::new(
+            db,
+            CallableSignature::bottom(),
+            CallableTypeKind::Regular,
+            CallableFunctionProvenance::None,
+        )
     }
 
     pub(super) fn recursive_type_normalized_impl(
@@ -512,6 +573,7 @@ impl<'db> CallableType<'db> {
             self.signatures(db)
                 .recursive_type_normalized_impl(db, div, nested)?,
             self.kind(db),
+            self.provenance(db),
         ))
     }
 
@@ -531,6 +593,7 @@ impl<'db> CallableType<'db> {
             self.signatures(db)
                 .apply_type_mapping_impl(db, type_mapping, tcx, visitor),
             self.kind(db),
+            self.provenance(db),
         )
     }
 
@@ -625,6 +688,7 @@ impl<'db> CallableTypes<'db> {
             db,
             CallableSignature::from_overloads(overloads),
             CallableTypeKind::Regular,
+            CallableFunctionProvenance::None,
         )
         .into_precise_functools_partial_instance(db, wrapped)
     }

crates/ty_python_semantic/src/types/class.rs

@@ -19,7 +19,7 @@ use super::{
 };
 use super::{TypeVarVariance, display};
 use crate::place::{DefinedPlace, TypeOrigin};
-use crate::types::callable::CallableTypeKind;
+use crate::types::callable::{CallableFunctionProvenance, CallableTypeKind};
 use crate::types::constraints::{
     ConstraintSet, ConstraintSetBuilder, IteratorConstraintsExtension,
 };
@@ -1587,6 +1587,7 @@ impl<'db> ClassType<'db> {
                             db,
                             getitem_signature,
                             CallableTypeKind::FunctionLike,
+                            CallableFunctionProvenance::None,
                         ));
                         Member::definitely_declared(getitem_type)
                     })
@@ -1828,6 +1829,7 @@ impl<'db> ClassType<'db> {
                 db,
                 dunder_new_signature.bind_self(db, Some(instance_ty)),
                 CallableTypeKind::Regular,
+                CallableFunctionProvenance::None,
             );
 
             if returns_non_subclass {
@@ -1898,6 +1900,7 @@ impl<'db> ClassType<'db> {
                     db,
                     synthesized_dunder_init_signature,
                     CallableTypeKind::Regular,
+                    CallableFunctionProvenance::None,
                 ))
             } else {
                 None

crates/ty_python_semantic/src/types/class/static_literal.rs

@@ -24,7 +24,7 @@ use crate::{
         Signature, SpecialFormType, StaticMroError, SubclassOfType, Truthiness, Type, TypeContext,
         TypeMapping, TypeVarVariance, UnionBuilder, UnionType,
         call::{CallError, CallErrorKind},
-        callable::CallableTypeKind,
+        callable::{CallableFunctionProvenance, CallableTypeKind},
         class::{
             ClassMemberResult, CodeGeneratorKind, DisjointBase, DynamicTypedDictLiteral, Field,
             FieldKind, InstanceMemberResult, MetaclassError, MetaclassErrorKind, MethodDecorator,
@@ -966,6 +966,7 @@ impl<'db> StaticClassLiteral<'db> {
                     db,
                     callable_ty.signatures(db),
                     CallableTypeKind::FunctionLike,
+                    callable_ty.provenance(db),
                 )),
                 Type::Union(union) => {
                     union.map(db, |element| into_function_like_callable(db, *element))
@@ -1191,7 +1192,12 @@ impl<'db> StaticClassLiteral<'db> {
                         )
                     }),
                 );
-                CallableType::new(db, signatures, CallableTypeKind::FunctionLike)
+                CallableType::new(
+                    db,
+                    signatures,
+                    CallableTypeKind::FunctionLike,
+                    CallableFunctionProvenance::None,
+                )
             });
 
             return Some(synthesized_callables.into_type(db));
@@ -1601,6 +1607,7 @@ impl<'db> StaticClassLiteral<'db> {
             db,
             CallableSignature::from_overloads(overloads),
             CallableTypeKind::FunctionLike,
+            CallableFunctionProvenance::None,
         )))
     }
 

crates/ty_python_semantic/src/types/class/typed_dict.rs

@@ -10,7 +10,7 @@ use ruff_python_stdlib::identifiers::is_identifier;
 use ruff_text_size::{Ranged, TextRange};
 
 use crate::place::PlaceAndQualifiers;
-use crate::types::callable::CallableTypeKind;
+use crate::types::callable::{CallableFunctionProvenance, CallableTypeKind};
 use crate::types::generics::GenericContext;
 use crate::types::member::Member;
 use crate::types::mro::Mro;
@@ -153,6 +153,7 @@ fn synthesize_typed_dict_init<'db>(
         db,
         CallableSignature::from_overloads([map_overload, keyword_overload]),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -176,6 +177,7 @@ fn synthesize_typed_dict_getitem<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -219,6 +221,7 @@ fn synthesize_typed_dict_setitem<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -258,6 +261,7 @@ fn synthesize_typed_dict_delitem<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -377,6 +381,7 @@ fn synthesize_typed_dict_get<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -490,6 +495,7 @@ fn synthesize_typed_dict_pop<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -516,6 +522,7 @@ fn synthesize_typed_dict_setdefault<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }
 
@@ -583,6 +590,7 @@ fn synthesize_typed_dict_merge<'db>(
         db,
         CallableSignature::from_overloads(overloads),
         CallableTypeKind::FunctionLike,
+        CallableFunctionProvenance::None,
     ))
 }