[ty] Preserve deprecations on decorated callables (#28256)

## Summary

We now report deprecations when `@deprecated` wraps a `Callable`
returned by another decorator. Previously, we preserved the deprecation
only while the decorated value remained a function literal:

```python
from collections.abc import Callable
from typing_extensions import deprecated

def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
    return function

@deprecated("Use current instead")
@PassThrough
def old() -> None:
    pass

old()  # Now reports the deprecation.
```

We retain the deprecated declaration on `CallableType`, independently of
its binding kind, and preserve it when binding methods or specializing
signatures. This also covers implicit constructor calls and deprecated
overload implementations, while explicit references and calls report
only once.

Addresses [the callable-decorator case raised in
#28251](#28251 (comment)).

Author: charliermarsh

crates/ty_python_semantic/resources/mdtest/deprecated.md

@@ -91,10 +91,147 @@ class StaticMethodReplacement:
 StaticMethodReplacement.old()  # error: [deprecated] "use replacement directly"
 ```
 
+## Callable replacements
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+An outer `@deprecated` decorator also applies when an inner decorator returns a `Callable` type.
+Both references and calls report the deprecation, and the decorated signature is preserved.
+
+```py
+from collections.abc import Callable
+from typing_extensions import deprecated
+
+def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
+    return function
+
+@deprecated("use current instead")
+@passthrough
+def old(value: int) -> str:
+    return str(value)
+
+old  # error: [deprecated] "use current instead"
+# error: [deprecated] "use current instead"
+reveal_type(old(1))  # revealed: str
+# error: [invalid-argument-type]
+old("wrong")  # error: [deprecated] "use current instead"
+```
+
+Replacing the callable with a different function discards the original deprecation. If an outer
+`@deprecated` wraps the replacement, its message is used instead.
+
+```py
+def replace(function: Callable[[int], str]) -> Callable[[int], str]:
+    return lambda value: str(value)
+
+@replace
+@deprecated("discarded deprecation")
+@passthrough
+def replaced(value: int) -> str:
+    return str(value)
+
+replaced(1)
+
+@deprecated("outer deprecation")
+@replace
+@deprecated("inner deprecation")
+@passthrough
+def replaced_again(value: int) -> str:
+    return str(value)
+
+replaced_again(1)  # error: [deprecated] "outer deprecation"
+```
+
+## Callable method replacements
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+Changing a method's descriptor kind or specializing its class preserves the deprecation.
+
+```py
+from collections.abc import Callable
+from typing_extensions import deprecated
+
+def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
+    return function
+
+class C[T]:
+    @deprecated("old initializer")
+    @passthrough
+    def __init__(self) -> None: ...
+    @deprecated("old method")
+    @passthrough
+    def method(self, value: T) -> T:
+        return value
+
+    @staticmethod
+    @deprecated("old static method")
+    @passthrough
+    def static(value: int) -> int:
+        return value
+
+    @classmethod
+    @deprecated("old class method")
+    @passthrough
+    def class_method(cls, value: int) -> int:
+        return value
+
+c = C[int]()  # error: [deprecated] "old initializer"
+c.__init__  # error: [deprecated] "old initializer"
+# error: [deprecated] "old method"
+reveal_type(c.method(1))  # revealed: int
+# error: [invalid-argument-type]
+c.method("wrong")  # error: [deprecated] "old method"
+C.static(1)  # error: [deprecated] "old static method"
+c.static(1)  # error: [deprecated] "old static method"
+C.class_method(1)  # error: [deprecated] "old class method"
+c.class_method(1)  # error: [deprecated] "old class method"
+```
+
+## Overloaded callable replacements
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+Deprecating a callable replacement for an overload implementation deprecates the whole function,
+while calls still use the declared overload signatures.
+
+```py
+from collections.abc import Callable
+from typing import overload
+from typing_extensions import deprecated
+
+def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
+    return function
+
+@overload
+def overloaded(value: int) -> int: ...
+@overload
+def overloaded(value: str) -> str: ...
+@deprecated("old implementation")
+@passthrough
+def overloaded(value: int | str) -> int | str:
+    return value
+
+overloaded  # error: [deprecated] "old implementation"
+# error: [deprecated] "old implementation"
+reveal_type(overloaded(1))  # revealed: int
+# error: [deprecated] "old implementation"
+reveal_type(overloaded("one"))  # revealed: str
+```
+
 ## Callable-object replacements
 
-`@deprecated` can also wrap other callable objects at runtime, but we currently only preserve the
-deprecation when an inner decorator returns a function literal.
+`@deprecated` can also wrap callable instances at runtime, but we do not yet preserve the
+deprecation when an inner decorator returns an instance type.
 
 ```py
 from collections.abc import Callable

crates/ty_python_semantic/src/types.rs

@@ -2398,6 +2398,7 @@ impl<'db> Type<'db> {
     pub fn is_deprecated(&self, db: &'db dyn Db) -> bool {
         match self {
             Type::FunctionLiteral(f) => f.implementation_deprecated(db).is_some(),
+            Type::Callable(callable) => callable.deprecated(db).is_some(),
             Type::ClassLiteral(c) => c.deprecated(db).is_some(),
             _ => false,
         }

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

@@ -4538,6 +4538,9 @@ impl<'db> CallableBinding<'db> {
         &self,
         db: &'db dyn Db,
     ) -> impl Iterator<Item = OverloadLiteral<'db>> + Clone {
+        if let Type::Callable(callable) = self.signature_type {
+            return Either::Left(callable.deprecated(db).into_iter());
+        }
         let function = match self.signature_type {
             Type::FunctionLiteral(function) => Some(function),
             Type::BoundMethod(bound) => Some(bound.function(db)),
@@ -4549,7 +4552,7 @@ impl<'db> CallableBinding<'db> {
         if let Some(implementation) =
             implementation.filter(|function| function.deprecated(db).is_some())
         {
-            return Either::Left(std::iter::once(implementation));
+            return Either::Left(Some(implementation).into_iter());
         }
 
         Either::Right(self.selected_overloads().filter_map(move |(_, binding)| {

crates/ty_python_semantic/src/types/callable.rs

@@ -11,6 +11,7 @@ use crate::{
         LiteralValueTypeKind, MemberLookupPolicy, Parameter, Parameters, Signature,
         SubclassOfInner, Type, TypeContext, TypeMapping, TypeVarBoundOrConstraints, UnionType,
         constraints::{ConstraintSet, IteratorConstraintsExtension},
+        function::OverloadLiteral,
         known_instance::FunctoolsPartialInstance,
         relation::{TypeRelation, TypeRelationChecker},
         signatures::{CallableSignature, PartialSignatureApplication},
@@ -186,10 +187,9 @@ impl<'db> Type<'db> {
                                     .signatures(db)
                                     .into_iter()
                                     .map(|sig| sig.clone().with_return_type(Type::TypeVar(tvar)));
-                                CallableType::new(
+                                callable.with_signatures(
                                     db,
                                     CallableSignature::from_overloads(signatures),
-                                    callable.kind(db),
                                 )
                             }))
                         }
@@ -206,10 +206,9 @@ impl<'db> Type<'db> {
                                         callable.signatures(db).into_iter().map(|sig| {
                                             sig.clone().with_return_type(Type::TypeVar(tvar))
                                         });
-                                    callables.push(CallableType::new(
+                                    callables.push(callable.with_signatures(
                                         db,
                                         CallableSignature::from_overloads(signatures),
-                                        callable.kind(db),
                                     ));
                                 }
                             }
@@ -400,13 +399,18 @@ impl From<TypeRelation> for UpcastPolicy {
 /// It can be written in type expressions using `typing.Callable`. `lambda` expressions are
 /// inferred directly as `CallableType`s; all function-literal types are subtypes of a
 /// `CallableType`.
-#[salsa::interned(debug, heap_size=ruff_memory_usage::heap_size)]
+#[salsa::interned(debug, constructor=new_internal, heap_size=ruff_memory_usage::heap_size)]
 pub struct CallableType<'db> {
     #[returns(ref)]
     pub(crate) signatures: CallableSignature<'db>,
 
     #[returns(copy)]
     pub(super) kind: CallableTypeKind,
+
+    /// The declaration on which `@deprecated` wrapped this callable. Retain the declaration
+    /// for diagnostic names, source annotations, and deduplication, independently of binding kind.
+    #[returns(copy)]
+    pub(crate) deprecated: Option<OverloadLiteral<'db>>,
 }
 
 pub(super) fn walk_callable_type<'db, V: visitor::TypeVisitor<'db> + ?Sized>(
@@ -423,6 +427,31 @@ pub(super) fn walk_callable_type<'db, V: visitor::TypeVisitor<'db> + ?Sized>(
 impl get_size2::GetSize for CallableType<'_> {}
 
 impl<'db> CallableType<'db> {
+    pub(crate) fn new<S>(db: &'db dyn Db, signatures: S, kind: CallableTypeKind) -> Self
+    where
+        S: salsa::Lookup<CallableSignature<'db>> + std::hash::Hash,
+        CallableSignature<'db>: salsa::HashEqLike<S>,
+    {
+        Self::new_internal(db, signatures, kind, None)
+    }
+
+    pub(crate) fn with_deprecated(self, db: &'db dyn Db, deprecated: OverloadLiteral<'db>) -> Self {
+        Self::new_internal(db, self.signatures(db), self.kind(db), Some(deprecated))
+    }
+
+    /// Replace the signatures without losing binding behavior or deprecation metadata.
+    pub(crate) fn with_signatures<S>(self, db: &'db dyn Db, signatures: S) -> Self
+    where
+        S: salsa::Lookup<CallableSignature<'db>> + std::hash::Hash,
+        CallableSignature<'db>: salsa::HashEqLike<S>,
+    {
+        Self::new_internal(db, signatures, self.kind(db), self.deprecated(db))
+    }
+
+    pub(crate) fn with_kind(self, db: &'db dyn Db, kind: CallableTypeKind) -> Self {
+        Self::new_internal(db, self.signatures(db), kind, self.deprecated(db))
+    }
+
     pub(crate) fn single(db: &'db dyn Db, signature: Signature<'db>) -> CallableType<'db> {
         CallableType::new(
             db,
@@ -483,7 +512,7 @@ impl<'db> CallableType<'db> {
     }
 
     pub(crate) fn into_regular(self, db: &'db dyn Db) -> CallableType<'db> {
-        CallableType::new(db, self.signatures(db), CallableTypeKind::Regular)
+        self.with_kind(db, CallableTypeKind::Regular)
     }
 
     /// Retain every parameter signature and its generic context, but erase return types
@@ -545,19 +574,15 @@ impl<'db> CallableType<'db> {
             return self.into_regular(db);
         }
 
-        CallableType::new(
-            db,
-            self.signatures(db).bind_self(db, env, self_type),
-            self.kind(db),
-        )
+        self.with_signatures(db, self.signatures(db).bind_self(db, env, self_type))
     }
 
     pub(crate) fn into_function_like(self, db: &'db dyn Db) -> CallableType<'db> {
-        CallableType::new(db, self.signatures(db), CallableTypeKind::FunctionLike)
+        self.with_kind(db, CallableTypeKind::FunctionLike)
     }
 
     pub(crate) fn into_dunder_paramspec(self, db: &'db dyn Db) -> CallableType<'db> {
-        CallableType::new(db, self.signatures(db), CallableTypeKind::DunderParamSpec)
+        self.with_kind(db, CallableTypeKind::DunderParamSpec)
     }
 
     pub(crate) fn apply_self(
@@ -576,11 +601,10 @@ impl<'db> CallableType<'db> {
         receiver_type: Type<'db>,
         self_type: Type<'db>,
     ) -> CallableType<'db> {
-        CallableType::new(
+        self.with_signatures(
             db,
             self.signatures(db)
                 .apply_self_with_receiver(db, env, receiver_type, self_type),
-            self.kind(db),
         )
     }
 
@@ -599,12 +623,13 @@ impl<'db> CallableType<'db> {
         div: Type<'db>,
         nested: bool,
     ) -> Option<Self> {
-        Some(CallableType::new(
-            db,
-            self.signatures(db)
-                .recursive_type_normalized_impl(db, env, div, nested)?,
-            self.kind(db),
-        ))
+        Some(
+            self.with_signatures(
+                db,
+                self.signatures(db)
+                    .recursive_type_normalized_impl(db, env, div, nested)?,
+            ),
+        )
     }
 
     pub(super) fn apply_type_mapping_impl<'a>(
@@ -618,11 +643,10 @@ impl<'db> CallableType<'db> {
             return replacements.get(&self).copied().unwrap_or(self);
         }
 
-        CallableType::new(
+        self.with_signatures(
             db,
             self.signatures(db)
                 .apply_type_mapping_impl(db, type_mapping, tcx, visitor),
-            self.kind(db),
         )
     }
 

crates/ty_python_semantic/src/types/function.rs

@@ -297,7 +297,11 @@ impl get_size2::GetSize for OverloadLiteral<'_> {}
 
 #[salsa::tracked]
 impl<'db> OverloadLiteral<'db> {
-    fn with_deprecated(self, db: &'db dyn Db, deprecated: DeprecatedInstance<'db>) -> Self {
+    pub(super) fn with_deprecated(
+        self,
+        db: &'db dyn Db,
+        deprecated: DeprecatedInstance<'db>,
+    ) -> Self {
         Self::new(
             db,
             self.name(db),
@@ -1228,12 +1232,11 @@ impl<'db> FunctionType<'db> {
             self.implementation_callables(db)
                 .iter()
                 .map(|callable| {
-                    CallableType::new(
+                    callable.with_signatures(
                         db,
                         callable
                             .signatures(db)
                             .with_inherited_generic_context(db, inherited_generic_context),
-                        callable.kind(db),
                     )
                 })
                 .collect()

crates/ty_python_semantic/src/types/generics.rs

@@ -729,7 +729,7 @@ impl<'db> GenericContext<'db> {
                         );
                         let signatures =
                             signatures.with_inherited_generic_context(db, generic_context);
-                        let replacement = CallableType::new(db, signatures, callable.kind(db));
+                        let replacement = callable.with_signatures(db, signatures);
 
                         Some((callable, replacement))
                     })