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,26 @@ 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 `is_cudf_pandas_obj` 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 is_cudf_pandas_obj
+
+obj = ...  # Your object here
+if is_cudf_pandas_obj(obj):
+    print("The object is a cudf.pandas proxy object.")
+else:
+    print("The object is not a cudf.pandas proxy object.")
+```
+
+There are various APIs to detect `Series`, `DataFrame`, `Index` and `ndarray`'s separately:
+
+* `is_cudf_pandas_series`: Detects if the object is a `cudf.pandas` proxy `Series`.
+* `is_cudf_pandas_dataframe`: Detects if the object is a `cudf.pandas` proxy `DataFrame`.
+* `is_cudf_pandas_index`: Detects if the object is a `cudf.pandas` proxy `Index`.
+* `is_cudf_pandas_nd_array`: Detects if the object is a `cudf.pandas` proxy `ndarray`.
 
 ## How can I access the underlying GPU or CPU objects?
 
@@ -154,6 +174,8 @@ The following methods can be used to retrieve the actual `cudf` or `pandas` obje
 - `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

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,13 @@
 import pylibcudf
 import rmm.mr
 
+from ._wrappers.numpy import is_cudf_pandas_nd_array
+from ._wrappers.pandas import (
+    is_cudf_pandas_dataframe,
+    is_cudf_pandas_index,
+    is_cudf_pandas_obj,
+    is_cudf_pandas_series,
+)
 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_nd_array(obj):
+    return is_proxy_object(obj) and isinstance(obj, ndarray)

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

@@ -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,
@@ -269,7 +271,7 @@ def custom_repr_html(obj):
 def _Series_dtype(self):
     # Fast-path to extract dtype from the current
     # object without round-tripping through the slow<->fast
-    return self._fsproxy_wrapped.dtype
+    return _maybe_wrap_result(self._fsproxy_wrapped.dtype, None)
 
 
 Series = make_final_proxy_type(
@@ -1711,6 +1713,22 @@ def holiday_calendar_factory_wrapper(*args, **kwargs):
     )
 
 
+def is_cudf_pandas_obj(obj):
+    return is_proxy_object(obj)
+
+
+def is_cudf_pandas_dataframe(obj):
+    return is_proxy_object(obj) and isinstance(obj, DataFrame)
+
+
+def is_cudf_pandas_series(obj):
+    return is_proxy_object(obj) and isinstance(obj, Series)
+
+
+def is_cudf_pandas_index(obj):
+    return is_proxy_object(obj) and isinstance(obj, Index)
+
+
 # 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/utils/utils.py

@@ -453,7 +453,7 @@ def _datetime_timedelta_find_and_replace(
     return result_col  # type: ignore
 
 
-def _extract_from_proxy(proxy, fast=True):
+def _extract_from_proxy(proxy: Any, fast: bool = True) -> tuple[Any, bool]:
     """
     Extract the object from a proxy object.
     """

python/cudf/cudf_pandas_tests/test_cudf_pandas.py

@@ -65,6 +65,14 @@
     get_calendar,
 )
 
+from cudf.pandas import (
+    is_cudf_pandas_dataframe,
+    is_cudf_pandas_index,
+    is_cudf_pandas_nd_array,
+    is_cudf_pandas_obj,
+    is_cudf_pandas_series,
+)
+
 # Accelerated pandas has the real pandas and cudf modules as attributes
 pd = xpd._fsproxy_slow
 cudf = xpd._fsproxy_fast
@@ -1891,3 +1899,34 @@ 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 is_cudf_pandas_obj(s)
+    assert is_cudf_pandas_obj(df)
+    assert is_cudf_pandas_obj(index)
+    assert is_cudf_pandas_obj(index.values)
+
+    assert is_cudf_pandas_series(s)
+    assert is_cudf_pandas_dataframe(df)
+    assert is_cudf_pandas_index(index)
+    assert is_cudf_pandas_nd_array(index.values)
+
+    for obj in [s, df, index, index.values]:
+        assert not is_cudf_pandas_obj(obj._fsproxy_slow)
+        assert not is_cudf_pandas_obj(obj._fsproxy_fast)
+
+        assert not is_cudf_pandas_series(obj._fsproxy_slow)
+        assert not is_cudf_pandas_series(obj._fsproxy_fast)
+
+        assert not is_cudf_pandas_dataframe(obj._fsproxy_slow)
+        assert not is_cudf_pandas_dataframe(obj._fsproxy_fast)
+
+        assert not is_cudf_pandas_index(obj._fsproxy_slow)
+        assert not is_cudf_pandas_index(obj._fsproxy_fast)
+
+        assert not is_cudf_pandas_nd_array(obj._fsproxy_slow)
+        assert not is_cudf_pandas_nd_array(obj._fsproxy_fast)