refactor: split cast_to_type into cast_to_type and try_cast_to_type

Replace the try_cast bool flag with separate cast_to_type and
try_cast_to_type functions, matching upstream DataFusion and the
arrow_cast / arrow_try_cast pair. Also drop the redundant data_type
parametrization on test_arrow_try_cast_null_on_failure, since the
str-vs-pyarrow distinction is already covered by test_arrow_cast_variants.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: timsaucer

crates/core/src/functions.rs

@@ -609,15 +609,8 @@ expr_fn!(arrow_typeof, arg_1);
 expr_fn!(arrow_cast, arg_1 datatype);
 expr_fn!(arrow_try_cast, arg_1 datatype);
 expr_fn!(arrow_field, arg_1);
-#[pyfunction]
-#[pyo3(signature = (arg_1, reference, *, try_cast = false))]
-fn cast_to_type(arg_1: PyExpr, reference: PyExpr, try_cast: bool) -> PyExpr {
-    if try_cast {
-        functions::expr_fn::try_cast_to_type(arg_1.into(), reference.into()).into()
-    } else {
-        functions::expr_fn::cast_to_type(arg_1.into(), reference.into()).into()
-    }
-}
+expr_fn!(cast_to_type, arg_1 reference);
+expr_fn!(try_cast_to_type, arg_1 reference);
 expr_fn_vec!(arrow_metadata);
 expr_fn_vec!(with_metadata);
 expr_fn!(union_tag, arg1);
@@ -977,6 +970,7 @@ pub(crate) fn init_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(arrow_try_cast))?;
     m.add_wrapped(wrap_pyfunction!(arrow_field))?;
     m.add_wrapped(wrap_pyfunction!(cast_to_type))?;
+    m.add_wrapped(wrap_pyfunction!(try_cast_to_type))?;
     m.add_wrapped(wrap_pyfunction!(arrow_metadata))?;
     m.add_wrapped(wrap_pyfunction!(with_metadata))?;
     m.add_wrapped(wrap_pyfunction!(ascii))?;

python/datafusion/functions.py

@@ -360,6 +360,7 @@
     "translate",
     "trim",
     "trunc",
+    "try_cast_to_type",
     "union_extract",
     "union_tag",
     "upper",
@@ -2988,13 +2989,13 @@ def arrow_field(expr: Expr) -> Expr:
     return Expr(f.arrow_field(expr.expr))
 
 
-def cast_to_type(value: Expr, type_ref: Expr, *, try_cast: bool = False) -> Expr:
+def cast_to_type(value: Expr, type_ref: Expr) -> Expr:
     """Casts ``value`` to the data type of ``type_ref``.
 
     Only the *type* of ``type_ref`` is used; its value is ignored. This is
     useful when the target type comes from another column or expression
-    rather than being known up-front. When ``try_cast=True``, casts that
-    fail produce NULL instead of erroring.
+    rather than being known up-front. Casts that fail produce an error; use
+    :py:func:`try_cast_to_type` for the NULL-on-failure variant.
 
     If the target type is known statically, prefer :py:func:`arrow_cast`
     (or :py:func:`arrow_try_cast` for the NULL-on-failure variant) and
@@ -3010,17 +3011,32 @@ def cast_to_type(value: Expr, type_ref: Expr, *, try_cast: bool = False) -> Expr
         ... )
         >>> result.collect_column("c")[0].as_py()
         1.0
+    """
+    return Expr(f.cast_to_type(value.expr, type_ref.expr))
+
+
+def try_cast_to_type(value: Expr, type_ref: Expr) -> Expr:
+    """Casts ``value`` to the data type of ``type_ref``, NULL on failure.
+
+    Like :py:func:`cast_to_type`, but casts that fail produce NULL instead
+    of erroring. Only the *type* of ``type_ref`` is used; its value is
+    ignored.
+
+    If the target type is known statically, prefer :py:func:`arrow_try_cast`
+    and pass a type string or ``pyarrow.DataType`` directly.
 
+    Examples:
+        >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": ["oops"], "b": [1.0]})
         >>> result = df.select(
-        ...     dfn.functions.cast_to_type(
-        ...         dfn.col("a"), dfn.col("b"), try_cast=True
+        ...     dfn.functions.try_cast_to_type(
+        ...         dfn.col("a"), dfn.col("b")
         ...     ).alias("c")
         ... )
         >>> result.collect_column("c")[0].as_py() is None
         True
     """
-    return Expr(f.cast_to_type(value.expr, type_ref.expr, try_cast=try_cast))
+    return Expr(f.try_cast_to_type(value.expr, type_ref.expr))
 
 
 def arrow_metadata(expr: Expr, key: Expr | str | None = None) -> Expr:

python/tests/test_functions.py

@@ -1316,13 +1316,12 @@ def test_arrow_cast_variants(df, cast_fn, data_type, expected):
     assert result.column(0) == expected
 
 
-@pytest.mark.parametrize("data_type", ["Float64", pa.float64()])
-def test_arrow_try_cast_null_on_failure(data_type):
+def test_arrow_try_cast_null_on_failure():
     ctx = SessionContext()
     batch = pa.RecordBatch.from_arrays([pa.array(["1.5", "oops", "3"])], names=["s"])
     df = ctx.create_dataframe([[batch]])
 
-    result = df.select(f.arrow_try_cast(column("s"), data_type).alias("c")).collect()[0]
+    result = df.select(f.arrow_try_cast(column("s"), "Float64").alias("c")).collect()[0]
 
     assert result.column(0).to_pylist() == [1.5, None, 3.0]
 
@@ -1348,23 +1347,21 @@ def test_arrow_field():
 
 
 @pytest.mark.parametrize(
-    ("values", "try_cast", "expected"),
+    ("cast_fn", "values", "expected"),
     [
-        (pa.array([4, 5, 6]), False, [4.0, 5.0, 6.0]),
-        (pa.array(["oops", "2", "3"]), True, [None, 2.0, 3.0]),
+        (f.cast_to_type, pa.array([4, 5, 6]), [4.0, 5.0, 6.0]),
+        (f.try_cast_to_type, pa.array(["oops", "2", "3"]), [None, 2.0, 3.0]),
     ],
 )
-def test_cast_to_type(values, try_cast, expected):
-    """cast_to_type takes target type from ``type_ref``; try_cast nullifies failures."""
+def test_cast_to_type(cast_fn, values, expected):
+    """cast_to_type / try_cast_to_type take target type from ``type_ref``."""
     ctx = SessionContext()
     batch = pa.RecordBatch.from_arrays(
         [values, pa.array([1.0, 2.0, 3.0])], names=["v", "fl"]
     )
     df = ctx.create_dataframe([[batch]])
 
-    result = df.select(
-        f.cast_to_type(column("v"), column("fl"), try_cast=try_cast).alias("c")
-    ).collect()[0]
+    result = df.select(cast_fn(column("v"), column("fl")).alias("c")).collect()[0]
 
     assert result.column(0).to_pylist() == expected
     assert result.column(0).type == pa.float64()