Point the "unexpected keyword" error at the kernel(**df) fix

Unpacking a frame that carries more columns than the kernel has
parameters is the expected way to get here, and the fix -- subset the
frame -- was only findable in the guide:

    TypeError: traced() got an unexpected keyword argument 'note'
    If you are calling traced(**df), subset the frame to the kernel's
    parameters: traced(**df[['a', 'b']])

Extra keywords stay an error rather than being filtered to the kernel's
parameters: the wrapper cannot tell "wide frame, take what you need"
from "this keyword was meant to do something", and silently dropping the
latter turns a typo or a stale argument name into wrong numbers.

Both jit routes gain the hint, and the DSL route also gains the function
name that sig.bind's message never carried. Missing operands are a
different mistake and keep their own message.

Also replace lazyudf's arity mismatch, which surfaced as a bare "zip()
argument 2 is longer than argument 1", with one naming the kernel, its
parameters and both counts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: FrancescAlted

doc/guides/pandas_engine.md

@@ -110,8 +110,9 @@ orbits["E"] = kepler(**orbits)
 ```
 
 No `apply`, no `engine=`. The parameter names match the column names, so `**`
-does the wiring; each column arrives as a pandas Series, which the kernel
-accepts like any array (zero-copy for ordinary numeric dtypes). `**df` passes
+does the wiring — by name, so the column order in the frame is irrelevant.
+Each column arrives as a pandas Series, which the kernel accepts like any
+array (zero-copy for ordinary numeric dtypes). `**df` passes
 *every* column, so subset first if the frame has more:
 `kepler(**orbits[["mean_anomaly", "eccentricity"]])`.
 

src/blosc2/lazyexpr.py

@@ -4665,7 +4665,16 @@ def __init__(
             # DSL kernels are using input names that are extracted from params as a list,
             # and we need to use them for matching variables in miniexpr
             # (instead of the 'o{%d}' notation).
-            self.inputs_dict = dict(zip(self.func.input_names, self.inputs, strict=True))
+            names = self.func.input_names
+            if len(names) != len(self.inputs):
+                # Otherwise this surfaces as a bare "zip() argument 2 is longer
+                # than argument 1", which names neither the kernel nor the counts.
+                udf_name = getattr(self.func.func, "__name__", self.func.__name__)
+                raise ValueError(
+                    f"DSL kernel {udf_name!r} takes {len(names)} operand(s) "
+                    f"({', '.join(names)}), but {len(self.inputs)} were passed."
+                )
+            self.inputs_dict = dict(zip(names, self.inputs, strict=True))
         else:
             self.inputs_dict = {f"o{i}": obj for i, obj in enumerate(self.inputs)}
 

src/blosc2/proxy.py

@@ -876,6 +876,34 @@ def _has_control_flow(source: str | None) -> bool:
     return any(isinstance(node, ast.If | ast.For | ast.While) for node in ast.walk(tree))
 
 
+def _wide_frame_hint(err: BaseException, func_name: str, params) -> str | None:
+    """Guidance to append when a call gets a keyword the function doesn't take.
+
+    The usual cause is the `kernel(**df)` idiom (see doc/guides/pandas_engine.md)
+    against a frame carrying more columns than the kernel has parameters. Extra
+    keywords are rejected rather than dropped, so that a keyword meant to do
+    something -- a typo, a stale argument name -- never goes silently unused.
+    """
+    if not isinstance(err, TypeError) or "unexpected keyword argument" not in str(err):
+        return None
+    params = list(params)
+    if not params:
+        return None
+    cols = ", ".join(repr(p) for p in params)
+    return (
+        f"If you are calling {func_name}(**df), subset the frame to the "
+        f"kernel's parameters: {func_name}(**df[[{cols}]])"
+    )
+
+
+def _signature_params(func) -> list:
+    """Parameter names of *func*, or an empty list if it cannot be introspected."""
+    try:
+        return list(inspect.signature(func).parameters)
+    except (TypeError, ValueError):
+        return []
+
+
 def _jit_dsl_wrapper(kernel: DSLKernel, out, decorator_kwargs: dict):
     """Build the call wrapper for the DSL (control-flow) dispatch route of `jit`.
 
@@ -889,7 +917,13 @@ def dsl_wrapper(*args, **func_kwargs):
         sig = kernel._sig
         if sig is None:
             raise TypeError(f"@blosc2.jit: cannot introspect the signature of {kernel.__name__!r}")
-        bound = sig.bind(*args, **func_kwargs)
+        try:
+            bound = sig.bind(*args, **func_kwargs)
+        except TypeError as e:
+            # sig.bind's message names no function; prefix it, and point at the
+            # subsetting fix when a wide DataFrame was unpacked into the call.
+            hint = _wide_frame_hint(e, kernel.__name__, kernel.input_names or sig.parameters)
+            raise TypeError(f"{kernel.__name__}() {e}" + (f"\n{hint}" if hint else "")) from None
         bound.apply_defaults()
         values = tuple(bound.arguments[name] for name in kernel.input_names)
         # Accept array-protocol operands (pandas Series, polars Series, ...) the
@@ -1137,8 +1171,18 @@ def wrapper(*args, **func_kwargs):
             try:
                 retval = func(*new_args, **func_kwargs)
             except Exception as e:
-                if _trace_hint is not None:
-                    raise type(e)(f"{e}\n{_trace_hint}") from e
+                hints = [
+                    hint
+                    for hint in (
+                        _wide_frame_hint(
+                            e, getattr(func, "__name__", "the function"), _signature_params(func)
+                        ),
+                        _trace_hint,
+                    )
+                    if hint is not None
+                ]
+                if hints:
+                    raise type(e)("\n".join([str(e), *hints])) from e
                 raise
 
             # Treat return value

tests/test_pandas_udf_engine.py

@@ -325,10 +325,35 @@ def not_dsl(col):
     def test_columns_by_keyword_unpacking(self):
         # doc/guides/pandas_engine.md's row-wise pattern: a DataFrame is a
         # mapping of column name to Series, so `kernel(**df)` passes each
-        # column as a keyword argument. Both jit routes must accept that.
+        # column as a keyword argument. Both jit routes must accept that, and
+        # bind by name: the columns below are in neither the parameter order
+        # nor alphabetical order, and the operations are asymmetric, so a
+        # positional binding would give a different (wrong) answer.
         @blosc2.jit
         def traced(a, b):
-            return np.sqrt(a * a + b * b)
+            return b - a * 2.0
+
+        @blosc2.jit
+        def dsl(a, b):
+            if a > b:
+                out = a - b
+            else:
+                out = b - a * 2.0
+            return out
+
+        df = pd.DataFrame({"b": [4.0, -5.0, 6.0], "a": [-2.0, 1.0, 3.0]})
+        assert list(df.columns) == ["b", "a"]
+
+        np.testing.assert_allclose(np.asarray(traced(**df)), np.asarray(traced(df["a"], df["b"])))
+        np.testing.assert_allclose(np.asarray(traced(**df)), df["b"] - df["a"] * 2.0)
+        np.testing.assert_allclose(np.asarray(dsl(**df)), np.asarray(dsl(df["a"], df["b"])))
+
+    def test_wide_frame_kwargs_error_names_the_fix(self):
+        # Extra columns are rejected, not dropped: a keyword that goes nowhere
+        # would otherwise fail silently. The message must name the subsetting fix.
+        @blosc2.jit
+        def traced(a, b):
+            return a + b
 
         @blosc2.jit
         def dsl(a, b):
@@ -338,7 +363,17 @@ def dsl(a, b):
                 out = b - a
             return out
 
-        df = pd.DataFrame({"a": [-2.0, 1.0, 3.0], "b": [4.0, -5.0, 6.0]})
+        df = pd.DataFrame({"a": [1.0, 2.0], "b": [4.0, 5.0], "note": [7.0, 8.0]})
+
+        # (`func.__name__` is the jit wrapper's; the message uses the kernel's)
+        for name, func in (("traced", traced), ("dsl", dsl)):
+            with pytest.raises(TypeError) as excinfo:
+                func(**df)
+            message = str(excinfo.value)
+            assert name in message
+            assert "'note'" in message
+            assert "**df[['a', 'b']]" in message
 
-        np.testing.assert_allclose(np.asarray(traced(**df)), np.hypot(df["a"], df["b"]))
-        np.testing.assert_allclose(np.asarray(dsl(**df)), np.abs(df["a"] - df["b"]))
+        # A missing operand is a different mistake and keeps its own message
+        with pytest.raises(TypeError, match="missing a required argument"):
+            dsl(a=df["a"])