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

[galipremsagar]

Description

Fixes: #17524

This PR introduces methods to access the real underlying cudf and pandas objects from cudf.pandas proxy objects. These methods ensure compatibility with libraries that are cudf or pandas aware.

Changes:

• Added get_cudf_pandas_fast_object() and get_cudf_pandas_slow_object() methods.
• Updated faq.md with a section explaining how to use these methods.

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[Matt711]

Overall, this looks good to me. But I think we should add a bullet to the "Are there any limitations?" section of this faq.md . And it should describe the implications for users of cudf.pandas and third-party libraries that are "cudf aware." For example, they could get a cupy array (not a numpy array) when working with xgboost. What do you think?

[bdice]

I would recommend that we avoid fast/slow names in the public API. I think get_cudf_object() is sufficient. Or possibly as_cudf()?

[bdice]

Or should we use reserved names like __as_cudf__() to make it more obvious that this is a protocol for library developers and not intended for users?

[galipremsagar]

We proxy numpy objects too, we will also have to keep that in mind to name these API. How about these names:

1. __as_fast_object__()
2. __as_gpu_object__()

[bdice]

I like (2). Are there any other public APIs involving words like fast/slow or GPU/CPU?

[vyasr]

I don't think a dunder name is appropriate. Those are typically for protocols that may be implemented across libraries as a standard, not something that single library decides on for itself. I do agree with avoiding fast/slow names, although we may eventually have to rework this if we rip the proxy out of cudf to make it easier for libraries like cuml to reuse. For now as_gpu_object seems good to me.

[bdice]

The dunder idea was that maybe this should be reserved for other libraries as a documented “protocol” and not presented as a user API. Closer to what IPython does with fancy reprs than the Array API.

[vyasr]

If you're thinking of IPython's _repr_html_, note that that is not a dunder but rather uses single underscores on either side (e.g. HTML._repr_html_). Conversely, the __html__ protocol is cross-library and implemented by other libraries (although I don't know exactly how wide the adoption is, I have seen it in a few other places)

[bdice]

Good catch! Thanks for the correction.