Add public APIs to Access Underlying cudf and pandas Objects from cudf.pandas Proxy Objects

docs/cudf/source/cudf_pandas/faq.md

@@ -142,6 +142,52 @@ cuDF (learn more in [this
 blog](https://medium.com/rapids-ai/easy-cpu-gpu-arrays-and-dataframes-run-your-dask-code-where-youd-like-e349d92351d)) and the [RAPIDS Accelerator for Apache Spark](https://nvidia.github.io/spark-rapids/)
 provides a similar configuration-based plugin for Spark.
 
+## How do I know if an object is a `cudf.pandas` proxy object?
+
+To determine if an object is a `cudf.pandas` proxy object, you can use the `isinstance_cudf_pandas` API. This function checks if the given object is a proxy object that wraps either a `cudf` or `pandas` object. Here is an example of how to use this API:
+
+```python
+from cudf.pandas import isinstance_cudf_pandas
+
+obj = ...  # Your object here
+if isinstance_cudf_pandas(obj, "Series"):
+    print("The object is a cudf.pandas proxy Series object.")
+else:
+    print("The object is not a cudf.pandas proxy Series object.")
+```
+
+To detect `Series`, `DataFrame`, `Index`, and `ndarray` objects separately, you can pass the type names as the second parameter:
+
+* `isinstance_cudf_pandas(obj, "Series")`: Detects if the object is a `cudf.pandas` proxy `Series`.
+* `isinstance_cudf_pandas(obj, "DataFrame")`: Detects if the object is a `cudf.pandas` proxy `DataFrame`.
+* `isinstance_cudf_pandas(obj, "Index")`: Detects if the object is a `cudf.pandas` proxy `Index`.
+* `isinstance_cudf_pandas(obj, "ndarray")`: Detects if the object is a `cudf.pandas` proxy `ndarray`.
+
+## How can I access the underlying GPU or CPU objects?
+
+When working with `cudf.pandas` proxy objects, it is sometimes necessary to get true `cudf` or `pandas` objects that reside on GPU or CPU.
+For example, this can be used to ensure that GPU-aware libraries that support both `cudf` and `pandas` can use the `cudf`-optimized code paths that keep data on GPU when processing `cudf.pandas` objects.
+Otherwise, the library might use less-optimized CPU code because it thinks that the `cudf.pandas` object is a plain `pandas` dataframe.
+
+The following methods can be used to retrieve the actual `cudf` or `pandas` objects:
+
+- `as_gpu_object()`: This method returns the `cudf` object from the proxy.
+- `as_cpu_object()`: This method returns the `pandas` object from the proxy.
+
+If `as_gpu_object()` is called on a proxy array, it will return a `cupy` array and `as_cpu_object` will return a `numpy` array.
+
+Here is an example of how to use these methods:
+
+```python
+# Assuming `proxy_obj` is a cudf.pandas proxy object
+cudf_obj = proxy_obj.as_gpu_object()
+pandas_obj = proxy_obj.as_cpu_object()
+
+# Now you can use `cudf_obj` and `pandas_obj` with libraries that are cudf or pandas aware
+```
+
+Be aware that if `cudf.pandas` objects are converted to their underlying `cudf` or `pandas` types, the `cudf.pandas` proxy no longer controls them. This means that automatic conversion between GPU and CPU types and automatic fallback from GPU to CPU functionality will not occur.
+
 (are-there-any-known-limitations)=
 ## Are there any known limitations?
 

python/cudf/cudf/core/column/column.py

@@ -1251,7 +1251,7 @@ def as_categorical_column(self, dtype) -> ColumnBase:
             )
 
         # Categories must be unique and sorted in ascending order.
-        cats = self.unique().sort_values().astype(self.dtype)
+        cats = self.unique().sort_values()
         label_dtype = min_unsigned_type(len(cats))
         labels = self._label_encoding(
             cats=cats, dtype=label_dtype, na_sentinel=cudf.Scalar(1)

python/cudf/cudf/core/dataframe.py

@@ -707,6 +707,7 @@ def __init__(
         if copy is not None:
             raise NotImplementedError("copy is not currently implemented.")
         super().__init__({}, index=cudf.Index([]))
+
         if nan_as_null is no_default:
             nan_as_null = not cudf.get_option("mode.pandas_compatible")
 

python/cudf/cudf/core/index.py

@@ -57,7 +57,10 @@
     is_mixed_with_object_dtype,
 )
 from cudf.utils.performance_tracking import _performance_tracking
-from cudf.utils.utils import _warn_no_dask_cudf, search_range
+from cudf.utils.utils import (
+    _warn_no_dask_cudf,
+    search_range,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Generator, Iterable
@@ -1067,6 +1070,7 @@ class Index(SingleColumnFrame, BaseIndex, metaclass=IndexMeta):
     @_performance_tracking
     def __init__(self, data, **kwargs):
         name = _getdefault_name(data, name=kwargs.get("name"))
+
         super().__init__({name: data})
 
     @_performance_tracking

python/cudf/cudf/core/series.py

@@ -625,6 +625,7 @@ def __init__(
     ):
         if nan_as_null is no_default:
             nan_as_null = not cudf.get_option("mode.pandas_compatible")
+
         index_from_data = None
         name_from_data = None
         if data is None:

python/cudf/cudf/pandas/__init__.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION & AFFILIATES.
 # All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
@@ -8,6 +8,9 @@
 import pylibcudf
 import rmm.mr
 
+from ._wrappers.pandas import (
+    isinstance_cudf_pandas,
+)
 from .fast_slow_proxy import is_proxy_object
 from .magics import load_ipython_extension
 from .profiler import Profiler

python/cudf/cudf/pandas/_wrappers/numpy.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION & AFFILIATES.
 # All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
@@ -176,3 +176,7 @@ def ndarray__array_ufunc__(self, ufunc, method, *inputs, **kwargs):
     cupy._core.flags.Flags,
     _numpy_flagsobj,
 )
+
+
+def is_cudf_pandas_ndarray(obj):
+    return is_proxy_object(obj) and isinstance(obj, ndarray)

python/cudf/cudf/pandas/_wrappers/pandas.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION & AFFILIATES.
 # All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 import abc
@@ -35,7 +35,9 @@
     _fast_slow_function_call,
     _FastSlowAttribute,
     _FunctionProxy,
+    _maybe_wrap_result,
     _Unusable,
+    is_proxy_object,
     make_final_proxy_type as _make_final_proxy_type,
     make_intermediate_proxy_type as _make_intermediate_proxy_type,
     register_proxy_func,
@@ -266,6 +268,12 @@ def custom_repr_html(obj):
     html_formatter.for_type(DataFrame, custom_repr_html)
 
 
+def _Series_dtype(self):
+    # Fast-path to extract dtype from the current
+    # object without round-tripping through the slow<->fast
+    return _maybe_wrap_result(self._fsproxy_wrapped.dtype, None)
+
+
 Series = make_final_proxy_type(
     "Series",
     cudf.Series,
@@ -285,6 +293,7 @@ def custom_repr_html(obj):
         "_constructor": _FastSlowAttribute("_constructor"),
         "_constructor_expanddim": _FastSlowAttribute("_constructor_expanddim"),
         "_accessors": set(),
+        "dtype": _Series_dtype,
     },
 )
 
@@ -1704,6 +1713,10 @@ def holiday_calendar_factory_wrapper(*args, **kwargs):
     )
 
 
+def isinstance_cudf_pandas(obj, type_name):
+    return is_proxy_object(obj) and obj.__class__.__name__ == type_name
+
+
 # timestamps and timedeltas are not proxied, but non-proxied
 # pandas types are currently not picklable. Thus, we define
 # custom reducer/unpicker functions for these types:

python/cudf/cudf/pandas/fast_slow_proxy.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION & AFFILIATES.
 # All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
@@ -204,6 +204,12 @@ def _fsproxy_fast_to_slow(self):
             return fast_to_slow(self._fsproxy_wrapped)
         return self._fsproxy_wrapped
 
+    def as_gpu_object(self):
+        return self._fsproxy_slow_to_fast()
+
+    def as_cpu_object(self):
+        return self._fsproxy_fast_to_slow()
+
     @property  # type: ignore
     def _fsproxy_state(self) -> _State:
         return (
@@ -221,6 +227,8 @@ def _fsproxy_state(self) -> _State:
         "_fsproxy_slow_type": slow_type,
         "_fsproxy_slow_to_fast": _fsproxy_slow_to_fast,
         "_fsproxy_fast_to_slow": _fsproxy_fast_to_slow,
+        "as_gpu_object": as_gpu_object,
+        "as_cpu_object": as_cpu_object,
         "_fsproxy_state": _fsproxy_state,
     }
 

python/cudf/cudf/utils/utils.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2024, NVIDIA CORPORATION.
+# Copyright (c) 2020-2025, NVIDIA CORPORATION.
 from __future__ import annotations
 
 import decimal
@@ -451,3 +451,17 @@ def _datetime_timedelta_find_and_replace(
     except TypeError:
         result_col = original_column.copy(deep=True)
     return result_col  # type: ignore
+
+
+def _extract_from_proxy(proxy: Any, fast: bool = True) -> tuple[Any, bool]:
+    """
+    Extract the object from a proxy object.
+    """
+    try:
+        return (
+            (proxy.as_gpu_object(), True)
+            if fast
+            else (proxy.as_cpu_object(), True)
+        )
+    except AttributeError:
+        return (proxy, False)

python/cudf/cudf_pandas_tests/test_cudf_pandas.py

@@ -65,6 +65,10 @@
     get_calendar,
 )
 
+from cudf.pandas import (
+    isinstance_cudf_pandas,
+)
+
 # Accelerated pandas has the real pandas and cudf modules as attributes
 pd = xpd._fsproxy_slow
 cudf = xpd._fsproxy_fast
@@ -1885,3 +1889,33 @@ def test_dataframe_setitem():
     new_df = df + 1
     df[df.columns] = new_df
     tm.assert_equal(df, new_df)
+
+
+def test_dataframe_get_fast_slow_methods():
+    df = xpd.DataFrame({"a": [1, 2, 3], "b": [1, 2, 3]})
+    assert isinstance(df.as_gpu_object(), cudf.DataFrame)
+    assert isinstance(df.as_cpu_object(), pd.DataFrame)
+
+
+def test_is_cudf_pandas():
+    s = xpd.Series([1, 2, 3])
+    df = xpd.DataFrame({"a": [1, 2, 3], "b": [1, 2, 3]})
+    index = xpd.Index([1, 2, 3])
+
+    assert isinstance_cudf_pandas(s, "Series")
+    assert isinstance_cudf_pandas(df, "DataFrame")
+    assert isinstance_cudf_pandas(index, "Index")
+    assert isinstance_cudf_pandas(index.values, "ndarray")
+
+    for obj in [s, df, index, index.values]:
+        assert not isinstance_cudf_pandas(obj._fsproxy_slow, "Series")
+        assert not isinstance_cudf_pandas(obj._fsproxy_fast, "Series")
+
+        assert not isinstance_cudf_pandas(obj._fsproxy_slow, "DataFrame")
+        assert not isinstance_cudf_pandas(obj._fsproxy_fast, "DataFrame")
+
+        assert not isinstance_cudf_pandas(obj._fsproxy_slow, "Index")
+        assert not isinstance_cudf_pandas(obj._fsproxy_fast, "Index")
+
+        assert not isinstance_cudf_pandas(obj._fsproxy_slow, "ndarray")
+        assert not isinstance_cudf_pandas(obj._fsproxy_fast, "ndarray")