ERR: Add NumbaUtilError (#33816)

Author: mroeschke

doc/source/reference/general_utility_functions.rst

@@ -35,9 +35,12 @@ Exceptions and warnings
 .. autosummary::
    :toctree: api/
 
+   errors.AccessorRegistrationWarning
    errors.DtypeWarning
    errors.EmptyDataError
    errors.OutOfBoundsDatetime
+   errors.MergeError
+   errors.NumbaUtilError
    errors.ParserError
    errors.ParserWarning
    errors.PerformanceWarning

pandas/core/groupby/generic.py

@@ -79,7 +79,6 @@
     NUMBA_FUNC_CACHE,
     check_kwargs_and_nopython,
     get_jit_arguments,
-    is_numba_util_related_error,
     jit_user_function,
     split_for_numba,
     validate_udf,
@@ -283,10 +282,8 @@ def aggregate(
                 return self._python_agg_general(
                     func, *args, engine=engine, engine_kwargs=engine_kwargs, **kwargs
                 )
-            except (ValueError, KeyError) as err:
+            except (ValueError, KeyError):
                 # Do not catch Numba errors here, we want to raise and not fall back.
-                if is_numba_util_related_error(str(err)):
-                    raise err
                 # TODO: KeyError is raised in _python_agg_general,
                 #  see see test_groupby.test_basic
                 result = self._aggregate_named(func, *args, **kwargs)

pandas/core/util/numba_.py

@@ -8,29 +8,11 @@
 
 from pandas._typing import FrameOrSeries
 from pandas.compat._optional import import_optional_dependency
+from pandas.errors import NumbaUtilError
 
 NUMBA_FUNC_CACHE: Dict[Tuple[Callable, str], Callable] = dict()
 
 
-def is_numba_util_related_error(err_message: str) -> bool:
-    """
-    Check if an error was raised from one of the numba utility functions
-
-    For cases where a try/except block has mistakenly caught the error
-    and we want to re-raise
-
-    Parameters
-    ----------
-    err_message : str,
-        exception error message
-
-    Returns
-    -------
-    bool
-    """
-    return "The first" in err_message or "numba does not" in err_message
-
-
 def check_kwargs_and_nopython(
     kwargs: Optional[Dict] = None, nopython: Optional[bool] = None
 ) -> None:
@@ -51,10 +33,10 @@ def check_kwargs_and_nopython(
 
     Raises
     ------
-    ValueError
+    NumbaUtilError
     """
     if kwargs and nopython:
-        raise ValueError(
+        raise NumbaUtilError(
             "numba does not support kwargs with nopython=True: "
             "https://github.com/numba/numba/issues/2916"
         )
@@ -169,6 +151,10 @@ def f(values, index, ...):
     Returns
     -------
     None
+
+    Raises
+    ------
+    NumbaUtilError
     """
     udf_signature = list(inspect.signature(func).parameters.keys())
     expected_args = ["values", "index"]
@@ -177,7 +163,7 @@ def f(values, index, ...):
         len(udf_signature) < min_number_args
         or udf_signature[:min_number_args] != expected_args
     ):
-        raise ValueError(
+        raise NumbaUtilError(
             f"The first {min_number_args} arguments to {func.__name__} must be "
             f"{expected_args}"
         )

pandas/errors/__init__.py

@@ -184,3 +184,9 @@ def __str__(self) -> str:
         else:
             name = type(self.class_instance).__name__
         return f"This {self.methodtype} must be defined in the concrete class {name}"
+
+
+class NumbaUtilError(Exception):
+    """
+    Error raised for unsupported Numba engine routines.
+    """

pandas/tests/groupby/aggregate/test_numba.py

@@ -1,6 +1,7 @@
 import numpy as np
 import pytest
 
+from pandas.errors import NumbaUtilError
 import pandas.util._test_decorators as td
 
 from pandas import DataFrame
@@ -17,10 +18,10 @@ def incorrect_function(x):
         {"key": ["a", "a", "b", "b", "a"], "data": [1.0, 2.0, 3.0, 4.0, 5.0]},
         columns=["key", "data"],
     )
-    with pytest.raises(ValueError, match=f"The first 2"):
+    with pytest.raises(NumbaUtilError, match=f"The first 2"):
         data.groupby("key").agg(incorrect_function, engine="numba")
 
-    with pytest.raises(ValueError, match=f"The first 2"):
+    with pytest.raises(NumbaUtilError, match=f"The first 2"):
         data.groupby("key")["data"].agg(incorrect_function, engine="numba")
 
 
@@ -33,10 +34,10 @@ def incorrect_function(x, **kwargs):
         {"key": ["a", "a", "b", "b", "a"], "data": [1.0, 2.0, 3.0, 4.0, 5.0]},
         columns=["key", "data"],
     )
-    with pytest.raises(ValueError, match="numba does not support"):
+    with pytest.raises(NumbaUtilError, match="numba does not support"):
         data.groupby("key").agg(incorrect_function, engine="numba", a=1)
 
-    with pytest.raises(ValueError, match="numba does not support"):
+    with pytest.raises(NumbaUtilError, match="numba does not support"):
         data.groupby("key")["data"].agg(incorrect_function, engine="numba", a=1)
 
 

pandas/tests/groupby/transform/test_numba.py

@@ -1,5 +1,6 @@
 import pytest
 
+from pandas.errors import NumbaUtilError
 import pandas.util._test_decorators as td
 
 from pandas import DataFrame
@@ -16,10 +17,10 @@ def incorrect_function(x):
         {"key": ["a", "a", "b", "b", "a"], "data": [1.0, 2.0, 3.0, 4.0, 5.0]},
         columns=["key", "data"],
     )
-    with pytest.raises(ValueError, match=f"The first 2"):
+    with pytest.raises(NumbaUtilError, match=f"The first 2"):
         data.groupby("key").transform(incorrect_function, engine="numba")
 
-    with pytest.raises(ValueError, match=f"The first 2"):
+    with pytest.raises(NumbaUtilError, match=f"The first 2"):
         data.groupby("key")["data"].transform(incorrect_function, engine="numba")
 
 
@@ -32,10 +33,10 @@ def incorrect_function(x, **kwargs):
         {"key": ["a", "a", "b", "b", "a"], "data": [1.0, 2.0, 3.0, 4.0, 5.0]},
         columns=["key", "data"],
     )
-    with pytest.raises(ValueError, match="numba does not support"):
+    with pytest.raises(NumbaUtilError, match="numba does not support"):
         data.groupby("key").transform(incorrect_function, engine="numba", a=1)
 
-    with pytest.raises(ValueError, match="numba does not support"):
+    with pytest.raises(NumbaUtilError, match="numba does not support"):
         data.groupby("key")["data"].transform(incorrect_function, engine="numba", a=1)
 
 

pandas/tests/test_errors.py

@@ -18,6 +18,7 @@
         "ParserWarning",
         "MergeError",
         "OptionError",
+        "NumbaUtilError",
     ],
 )
 def test_exception_importable(exc):

pandas/tests/window/test_apply.py

@@ -1,6 +1,7 @@
 import numpy as np
 import pytest
 
+from pandas.errors import NumbaUtilError
 import pandas.util._test_decorators as td
 
 from pandas import DataFrame, Series, Timestamp, date_range
@@ -134,7 +135,7 @@ def test_invalid_raw_numba():
 
 @td.skip_if_no("numba")
 def test_invalid_kwargs_nopython():
-    with pytest.raises(ValueError, match="numba does not support kwargs with"):
+    with pytest.raises(NumbaUtilError, match="numba does not support kwargs with"):
         Series(range(1)).rolling(1).apply(
             lambda x: x, kwargs={"a": 1}, engine="numba", raw=True
         )