refactor: add coerce_to_expr helpers and replace inline coercion patterns

Introduce coerce_to_expr() and coerce_to_expr_or_none() in expr.py as the
complement to ensure_expr() — where ensure_expr rejects non-Expr values,
these helpers wrap them via Expr.literal(). Replaces ~60 inline isinstance
checks in functions.py with single-line helper calls, and updates the
make-pythonic skill to document the new pattern.

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

Author: timsaucer

.ai/skills/make-pythonic/SKILL.md

@@ -261,28 +261,46 @@ python -m pytest --doctest-modules python/datafusion/functions.py -v
 
 ## Coercion Helper Pattern
 
-When adding coercion to a function, use this inline pattern:
+Use the coercion helpers from `datafusion.expr` to convert native Python values to `Expr`. These are the complement of `ensure_expr()` — where `ensure_expr` *rejects* non-`Expr` values, the coercion helpers *wrap* them via `Expr.literal()`.
+
+**For required parameters** use `coerce_to_expr`:
 
 ```python
-if not isinstance(arg, Expr):
-    arg = Expr.literal(arg)
+from datafusion.expr import coerce_to_expr
+
+def left(string: Expr, n: Expr | int) -> Expr:
+    n = coerce_to_expr(n)
+    return Expr(f.left(string.expr, n.expr))
 ```
 
-Do NOT create a new helper function for this — the inline check is clear and explicit. The project intentionally uses `ensure_expr()` to reject non-Expr values in contexts where coercion is not wanted; the pythonic coercion is the opposite pattern and should be visually distinct.
+**For optional nullable parameters** use `coerce_to_expr_or_none`:
+
+```python
+from datafusion.expr import coerce_to_expr, coerce_to_expr_or_none
+
+def regexp_count(
+    string: Expr,
+    pattern: Expr | str,
+    start: Expr | int | None = None,
+    flags: Expr | str | None = None,
+) -> Expr:
+    pattern = coerce_to_expr(pattern)
+    start = coerce_to_expr_or_none(start)
+    flags = coerce_to_expr_or_none(flags)
+    return Expr(
+        f.regexp_count(
+            string.expr,
+            pattern.expr,
+            start.expr if start is not None else None,
+            flags.expr if flags is not None else None,
+        )
+    )
+```
 
-**Functions with many optional nullable parameters:** For parameters typed as `Expr | <type> | None`, combine the `None` check with the `isinstance` check inline. Repeat this for each parameter — do not factor it into a local helper function, even if the repetition feels verbose. Consistency across the file is more important than DRY within a single function.
+Both helpers are defined in `python/datafusion/expr.py` alongside `ensure_expr`. Import them in `functions.py` via:
 
 ```python
-# For each optional parameter:
-if start is not None and not isinstance(start, Expr):
-    start = Expr.literal(start)
-
-# When passing to the Rust binding, extract .expr or pass None:
-f.some_func(
-    values.expr,
-    start.expr if start is not None else None,
-    n.expr if n is not None else None,
-)
+from datafusion.expr import coerce_to_expr, coerce_to_expr_or_none
 ```
 
 ## What NOT to Change

python/datafusion/expr.py

@@ -221,6 +221,8 @@
     "WindowExpr",
     "WindowFrame",
     "WindowFrameBound",
+    "coerce_to_expr",
+    "coerce_to_expr_or_none",
     "ensure_expr",
     "ensure_expr_list",
 ]
@@ -233,6 +235,10 @@ def ensure_expr(value: Expr | Any) -> expr_internal.Expr:
     higher level APIs consistently require explicit :func:`~datafusion.col` or
     :func:`~datafusion.lit` expressions.
 
+    See Also:
+        :func:`coerce_to_expr` — the opposite behavior: *wraps* non-``Expr``
+        values as literals instead of rejecting them.
+
     Args:
         value: Candidate expression or other object.
 
@@ -277,6 +283,41 @@ def _iter(
     return list(_iter(exprs))
 
 
+def coerce_to_expr(value: Any) -> Expr:
+    """Coerce a native Python value to an ``Expr`` literal, passing ``Expr`` through.
+
+    This is the complement of :func:`ensure_expr`: where ``ensure_expr``
+    *rejects* non-``Expr`` values, ``coerce_to_expr`` *wraps* them via
+    :meth:`Expr.literal` so that functions can accept native Python types
+    (``int``, ``float``, ``str``, ``bool``, etc.) alongside ``Expr``.
+
+    Args:
+        value: An ``Expr`` instance (returned as-is) or a Python literal to wrap.
+
+    Returns:
+        An ``Expr`` representing the value.
+    """
+    if isinstance(value, Expr):
+        return value
+    return Expr.literal(value)
+
+
+def coerce_to_expr_or_none(value: Any | None) -> Expr | None:
+    """Coerce a value to ``Expr`` or pass ``None`` through unchanged.
+
+    Same as :func:`coerce_to_expr` but accepts ``None`` for optional parameters.
+
+    Args:
+        value: An ``Expr`` instance, a Python literal to wrap, or ``None``.
+
+    Returns:
+        An ``Expr`` representing the value, or ``None``.
+    """
+    if value is None:
+        return None
+    return coerce_to_expr(value)
+
+
 def _to_raw_expr(value: Expr | str) -> expr_internal.Expr:
     """Convert a Python expression or column name to its raw variant.