improve error message

docs/api/utils.rst

@@ -15,7 +15,7 @@ Utilities to implement array behaviors for dask-awkward arrays.
 .. autosummary::
    :toctree: generated/
 
-   utils.TracerConversionError
+   utils.ConcretizationTypeError
 
 .. raw:: html
 

src/dask_awkward/lib/core.py

@@ -48,9 +48,9 @@
 from dask_awkward.layers import AwkwardBlockwiseLayer, AwkwardMaterializedLayer
 from dask_awkward.lib.optimize import all_optimizations
 from dask_awkward.utils import (
+    ConcretizationTypeError,
     DaskAwkwardNotImplemented,
     IncompatiblePartitions,
-    TracerConversionError,
     field_access_to_front,
     first,
     hyphenize,
@@ -923,19 +923,21 @@ def __dask_postpersist__(self):
     __dask_scheduler__ = staticmethod(threaded_get)
 
     def __bool__(self):
-        raise TracerConversionError(bool, self)
+        raise ConcretizationTypeError(f"The __bool__() method was called on {self!r}.")
 
     def __int__(self):
-        raise TracerConversionError(int, self)
+        raise ConcretizationTypeError(f"The __int__() method was called on {self!r}.")
 
     def __float__(self):
-        raise TracerConversionError(float, self)
+        raise ConcretizationTypeError(f"The __float__() method was called on {self!r}.")
 
     def __complex__(self):
-        raise TracerConversionError(complex, self)
+        raise ConcretizationTypeError(
+            f"The __complex__() method was called on {self!r}."
+        )
 
     def __index__(self):
-        raise TracerConversionError(operator.index, self)
+        raise ConcretizationTypeError(f"The __index__() method was called on {self!r}.")
 
     def __setitem__(self, where: Any, what: Any) -> None:
         if not (

src/dask_awkward/utils.py

@@ -8,7 +8,6 @@
 if TYPE_CHECKING:
     from dask_awkward.lib.core import Array
 
-
 T = TypeVar("T")
 P = ParamSpec("P")
 
@@ -38,9 +37,9 @@ def divisions_msg(name: str, *args: Array) -> str:
         return msg
 
 
-class TracerConversionError(TypeError):
+class ConcretizationTypeError(TypeError):
     """
-    This error occurs when a tracer is used in a context that requires a concrete
+    This error occurs when a ``dask_awkward.Array`` is used in a context that requires a concrete
     value.
 
 
@@ -49,35 +48,37 @@ class TracerConversionError(TypeError):
     Examples
     --------
 
-    - When a tracer is used in a conditional statement:
+    - When a ``dask_awkward.Array`` is used in a conditional statement:
 
     >>> import dask_awkward as dak
-    >>> tracer = dak.from_awkward(ak.Array([1]), npartitions=1)
-    >>> bool(dask_arr)
+    >>> import awkward as ak
+    >>> dask_arr = dak.from_awkward(ak.Array([1]), npartitions=1)
+    >>> if dask_arr > 2:
+    >>>     dask_arr += 1
     Traceback (most recent call last): ...
-    TracerConversionError: Attempted to convert (``bool(dask.awkward<from-awkward, npartitions=1>)``) a Dask tracer to a concrete value. If you intend to convert the tracer to a concrete value, use the `.compute()` method.
-
+    dask_awkward.utils.ConcretizationTypeError: A dask_awkward.Array is encountered in a computation where a concrete value is expected. If you intend to convert the dask_awkward.Array to a concrete value, use the `.compute()` method. The __bool__() method was called on dask.awkward<greater, npartitions=1>.
 
-    - When a tracer is cast to a Python type:
+    - When a ``dask_awkward.Array`` is cast to a Python type:
 
     >>> import dask_awkward as dak
-    >>> tracer = dak.from_awkward(ak.Array([1]), npartitions=1)
+    >>> import awkward as ak
+    >>> dask_arr = dak.from_awkward(ak.Array([1]), npartitions=1)
     >>> int(dask_arr)
     Traceback (most recent call last): ...
-    TracerConversionError: Attempted to convert (``int(dask.awkward<from-awkward, npartitions=1>)``) a Dask tracer to a concrete value. If you intend to convert the tracer to a concrete value, use the `.compute()` method.
-
+    dask_awkward.utils.ConcretizationTypeError: A dask_awkward.Array is encountered in a computation where a concrete value is expected. If you intend to convert the dask_awkward.Array to a concrete value, use the `.compute()` method. The __int__() method was called on dask.awkward<from-awkward, npartitions=1>.
 
     These errors can be resolved by explicitely converting the tracer to a concrete value:
 
     >>> import dask_awkward as dak
-    >>> tracer = dak.from_awkward(ak.Array([1]), npartitions=1)
-    >>> bool(tracer.compute())
-    >>> int(tracer.compute())
+    >>> dask_arr = dak.from_awkward(ak.Array([1]), npartitions=1)
+    >>> bool(dask_arr.compute())
+    True
     """
 
-    def __init__(self, func: Callable, array: Array):
-        self.message = f"Attempted to convert (`{func.__name__}({array!r})`) a Dask tracer to a concrete value. "
-        self.message += "If you intend to convert the tracer to a concrete value, use the `.compute()` method."
+    def __init__(self, msg: str):
+        self.message = "A dask_awkward.Array is encountered in a computation where a concrete value is expected. "
+        self.message += "If you intend to convert the dask_awkward.Array to a concrete value, use the `.compute()` method. "
+        self.message += msg
         super().__init__(self.message)
 
 

tests/test_core.py

@@ -34,7 +34,7 @@
     typetracer_array,
 )
 from dask_awkward.lib.testutils import assert_eq
-from dask_awkward.utils import IncompatiblePartitions, TracerConversionError
+from dask_awkward.utils import ConcretizationTypeError, IncompatiblePartitions
 
 if TYPE_CHECKING:
     from dask_awkward.lib.core import Array
@@ -973,11 +973,11 @@ def test_map_partitions_bad_arguments():
 def test_array__bool_nonzero_long_int_float_complex_index():
     import operator
 
-    tracer = dak.from_awkward(ak.Array([1]), npartitions=1)
+    dask_arr = dak.from_awkward(ak.Array([1]), npartitions=1)
 
     for fun in bool, int, float, complex, operator.index:
         with pytest.raises(
-            TracerConversionError,
-            match=r"Attempted to convert \(.+\) a Dask tracer to a concrete value. If you intend to convert the tracer to a concrete value, use the `.compute\(\)` method.",
+            ConcretizationTypeError,
+            match=r"A dask_awkward.Array is encountered in a computation where a concrete value is expected. If you intend to convert the dask_awkward.Array to a concrete value, use the `.compute\(\)` method. The .+ method was called on .+.",
         ):
-            fun(tracer)
+            fun(dask_arr)