[ty] synthesize __replace__ for >=3.13

Author: thejchap

crates/ty_python_semantic/resources/mdtest/replace.md

@@ -0,0 +1,64 @@
+# Replace
+
+The replace function and protocol added in Python 3.13:
+<https://docs.python.org/3/whatsnew/3.13.html#copy>
+
+## `replace()` function
+
+It is present in the `copy` module.
+
+```toml
+[environment]
+python-version = "3.13"
+```
+
+```py
+from copy import replace
+```
+
+## `__replace__` protocol
+
+```toml
+[environment]
+python-version = "3.13"
+```
+
+### Dataclasses
+
+```py
+from dataclasses import dataclass
+from copy import replace
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+a = Point(1, 2)
+
+# It accepts keyword arguments
+reveal_type(a.__replace__)  # revealed: (*, x: int = int, y: int = int) -> Point
+b = a.__replace__(x=3, y=4)
+reveal_type(b)  # revealed: Point
+b = replace(a, x=3, y=4)
+reveal_type(b)  # revealed: Point
+
+# It does not require all keyword arguments
+c = a.__replace__(x=3)
+reveal_type(c)  # revealed: Point
+d = replace(a, x=3)
+reveal_type(d)  # revealed: Point
+```
+
+## Version support check
+
+It is not present in Python < 3.13
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+```py
+from copy import replace  # error: [unresolved-import]
+```

crates/ty_python_semantic/src/types/class.rs

@@ -1592,7 +1592,9 @@ impl<'db> ClassLiteral<'db> {
 
         let field_policy = CodeGeneratorKind::from_class(db, self)?;
 
-        let signature_from_fields = |mut parameters: Vec<_>| {
+        let signature_from_fields = |mut parameters: Vec<_>,
+                                     return_ty: Option<Type<'db>>,
+                                     for_replace: bool| {
             let mut kw_only_field_seen = false;
             for (
                 field_name,
@@ -1659,21 +1661,27 @@ impl<'db> ClassLiteral<'db> {
                     }
                 }
 
-                let mut parameter = if kw_only_field_seen {
+                // For the `__replace__` signature, force to kw only
+                let mut parameter = if kw_only_field_seen || for_replace {
                     Parameter::keyword_only(field_name)
                 } else {
                     Parameter::positional_or_keyword(field_name)
                 }
                 .with_annotated_type(field_ty);
 
-                if let Some(default_ty) = default_ty {
+                // When replacing, we know there is a default value for the field
+                // (the value that is currently assigned to the field)
+                // assume this to be the declared type of the field
+                if for_replace {
+                    parameter = parameter.with_default_type(field_ty);
+                } else if let Some(default_ty) = default_ty {
                     parameter = parameter.with_default_type(default_ty);
                 }
 
                 parameters.push(parameter);
             }
 
-            let mut signature = Signature::new(Parameters::new(parameters), Some(Type::none(db)));
+            let mut signature = Signature::new(Parameters::new(parameters), return_ty);
             signature.inherited_generic_context = self.generic_context(db);
             Some(CallableType::function_like(db, signature))
         };
@@ -1695,12 +1703,12 @@ impl<'db> ClassLiteral<'db> {
                         db,
                         self.apply_optional_specialization(db, specialization),
                     ));
-                signature_from_fields(vec![self_parameter])
+                signature_from_fields(vec![self_parameter], Some(Type::none(db)), false)
             }
             (CodeGeneratorKind::NamedTuple, "__new__") => {
                 let cls_parameter = Parameter::positional_or_keyword(Name::new_static("cls"))
                     .with_annotated_type(KnownClass::Type.to_instance(db));
-                signature_from_fields(vec![cls_parameter])
+                signature_from_fields(vec![cls_parameter], Some(Type::none(db)), false)
             }
             (CodeGeneratorKind::DataclassLike, "__lt__" | "__le__" | "__gt__" | "__ge__") => {
                 if !has_dataclass_param(DataclassParams::ORDER) {
@@ -1735,6 +1743,20 @@ impl<'db> ClassLiteral<'db> {
                     .place
                     .ignore_possibly_unbound()
             }
+            (CodeGeneratorKind::DataclassLike, "__replace__") => {
+                if Program::get(db).python_version(db) < PythonVersion::PY313 {
+                    return None;
+                }
+
+                let self_parameter =
+                    Parameter::positional_or_keyword(Name::new_static("self")).with_annotated_type(
+                        Type::instance(db, self.apply_optional_specialization(db, specialization)),
+                    );
+                let instance_ty =
+                    Type::instance(db, self.apply_optional_specialization(db, specialization));
+
+                signature_from_fields(vec![self_parameter], Some(instance_ty), true)
+            }
             (CodeGeneratorKind::DataclassLike, "__setattr__") => {
                 if has_dataclass_param(DataclassParams::FROZEN) {
                     let signature = Signature::new(