refactor: improve ak.to_cudf errors and documentation (#3850)

* improve cudf highlevel functions errors and docstring

* some consistent docstrings regarding array-like with the rest of the highlevel functions

* this is actually a series

* perhaps notimplementederror is better here

Author: ikrommyd

docs/reference/gpu-backend.md

@@ -56,6 +56,11 @@
 
     generated/ak.to_dataframe
 
+.. toctree::
+    :caption: Converting to cuDF Series
+
+    generated/ak.to_cudf
+
 .. toctree::
     :caption: Converting ROOT RDataFrames
 

docs/reference/toctree.txt

@@ -8,17 +8,52 @@
 
 
 @high_level_function()
-def to_cudf(
-    array: ak.Array,
-):
-    """Create a cuDF.Series out of the given ak array
+def to_cudf(array):
+    """
+    Args:
+        array: Array-like data (anything #ak.to_layout recognizes).
+
+    Converts an Awkward Array into a cuDF Series.
 
     Buffers that are not already in GPU memory will be transferred, and some
     structural reformatting may happen to account for differences in architecture.
+
+    This function requires the `cudf` library (< 25.12.00) and a compatible GPU.
+    cuDF versions 25.12.00 and later are not currently supported due to
+    incompatible changes in cuDF internals.
+
+    See also #ak.to_cupy, #ak.from_cupy, #ak.to_dataframe.
     """
-    import cudf
+    # Dispatch
+    yield (array,)
+
+    # Implementation
+    return _impl(array)
+
+
+def _impl(array):
+    try:
+        import cudf
+    except ImportError as err:
+        raise ImportError(
+            """to use ak.to_cudf, you must install the 'cudf' package with:
+
+    pip install cudf-cu13
+or
+    conda install -c rapidsai cudf cuda-version=13"""
+        ) from err
+
+    from packaging.version import parse as parse_version
+
+    if parse_version(cudf.__version__) >= parse_version("25.12.00"):
+        raise NotImplementedError(
+            f"ak.to_cudf is not supported for cudf >= 25.12.00 (you have {cudf.__version__}). "
+            "cudf internals changed in ways that are incompatible with the current implementation"
+        )
+
+    layout = ak.to_layout(array, allow_record=False)
 
     if hasattr(cudf.Series, "_from_column"):
-        return cudf.Series._from_column(array.layout._to_cudf(cudf, None, len(array)))
+        return cudf.Series._from_column(layout._to_cudf(cudf, None, len(layout)))
     # older Series invocation
-    return cudf.Series(array.layout._to_cudf(cudf, None, len(array)))
+    return cudf.Series(layout._to_cudf(cudf, None, len(layout)))

src/awkward/operations/ak_to_cudf.py

@@ -15,9 +15,7 @@
 def to_raggedtensor(array):
     """
     Args:
-        array: Array-like data. May be a high level #ak.Array,
-            or low-level #ak.contents.ListOffsetArray, #ak.contents.ListArray,
-            #ak.contents.RegularArray, #ak.contents.NumpyArray
+        array: Array-like data (anything #ak.to_layout recognizes).
 
     Converts `array` (only ListOffsetArray, ListArray, RegularArray and NumpyArray data types supported)
     into a ragged tensor, if possible.

src/awkward/operations/ak_to_raggedtensor.py

@@ -27,7 +27,7 @@ def to_safetensors(
 ):
     """
     Args:
-        array: An Awkward Array or array-like object to serialize.
+        array: Array-like data (anything #ak.to_layout recognizes).
         destination (path-like): Name of the output file, file path, or
             remote URL passed to [fsspec.core.url_to_fs](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.core.url_to_fs)
             for remote writing.

src/awkward/operations/ak_to_safetensors.py

@@ -15,9 +15,7 @@
 def to_tensorflow(array):
     """
     Args:
-        array: Array-like data. May be a high level #ak.Array,
-            or low-level #ak.contents.ListOffsetArray, #ak.contents.ListArray,
-            #ak.contents.RegularArray, #ak.contents.NumpyArray
+        array: Array-like data (anything #ak.to_layout recognizes).
 
     Converts `array` (only ListOffsetArray, ListArray, RegularArray and NumpyArray data types supported)
     into a TensorFlow Tensor, if possible.

src/awkward/operations/ak_to_tensorflow.py

@@ -15,9 +15,7 @@
 def to_torch(array):
     """
     Args:
-        array: Array-like data. May be a high level #ak.Array,
-            or low-level #ak.contents.ListOffsetArray, #ak.contents.ListArray,
-            #ak.contents.RegularArray, #ak.contents.NumpyArray
+        array: Array-like data (anything #ak.to_layout recognizes).
 
     Converts `array` (only ListOffsetArray, ListArray, RegularArray and NumpyArray data types supported)
     into a PyTorch Tensor, if possible.

src/awkward/operations/ak_to_torch.py

@@ -36,6 +36,10 @@ def test_nested():
     ]
 
 
+@pytest.mark.xfail(
+    parse_version(cudf.__version__) >= parse_version("25.12.00"),
+    reason="cudf internals changed since v25.12.00",
+)
 def test_null():
     arr = ak.Array([12, None, 21, 12])
     # calls ByteMaskedArray._to_cudf not NumpyArray