I'm not sure we want to call out pandas data frames here. How do we do this elsewhere? I'd just state "object" and then below, state that
"""
IfcellText is not a list of texts, we attempt to accesscellText.columns.to_numpy() for the column headers,
andcellText.to_numpy() for the table's cells.
"""

We don't have any other functions explicitly take DataFrames. Typically, DataFrame is covered by what we callarray-like (and internally runs viato_numpy(). It's different here because we take the column headers as well. Due to this particular usage, we've chosen to explicitly check for DataFrames (_is_pandas_dataframe()). I believe that duck-typing would be a bit too vague here: An object withobj.columns.to_numpy() andobj.to_numpy() is very particular. I'm not sure if this matches anything but pandas.DataFrame - and if there exists other such objects, I'm not clear that accepting them is appropriate. If the need for similar objects should arise, we can always revisit. For now, the explicit type is the simplest documentation and matches implementation:

I linked an example of another very popular package, polars, that has the same form of data frame. I'm sure there are others out there. I don't think we should be special casing pandas here.

Polars is logically equivalent, but it does not have the same API. See#28830 (comment).

There are several other dataframes out their (https://data-apis.org/dataframe-api/draft/purpose_and_scope.html#history-and-dataframe-implementations), but the problem is that their API is currently not consistent. IMHO we therefore would have to special case to support multiple of them.

While I appreciate the attempt to duck-type instead of explicitly relying on types, I believe the current dataframe APIs are to inhomogeneous to support reasonable duck-typing. Any object that supportsobj.columns.to_numpy() andobj.to_numpy() is too technical - i suspect that at least half of the pandas users would not know whether that holds forpandas.DataFrame or not. Duck-typing would work ifdataframe-like was well-defined, but it is currently not (see the draft dataframe API standard).

I thinknp.asanyarray(df.columns) works on both pandas and polars, and is pretty straightforward.

If you really want to push for duck-typing, go for it. But I'd require reasonable type stubs (acceptingAny is not good enough) and type documentation (users should at least easily see that pandas.DataFrame as the most common dataframe type is supported).

Ideally, that claimed behavior would also be tested. (It's easy for pandas, because it's a test dependency. For others, you'd likely need a mock similar totest_unpack_to_numpy_from_torch.)

I personally believe it's not worth the added effort and would advise against requiring this from a first-time contribution. When accepting the limited scope of pandas, this PR is almost ready apart from minor documentation issues and the type stub. I therefore suggest to take this PR as a limited but well scoped improvement. We don't paint us in any corner with that. You can generalize in a followup PR.

But I'd require reasonable type stubs

OK, but I dont' think you will get pandas dataframes in a typestub from this PR either, will you? I'm personally pretty 👎 on losing functionality because of type stubbing issues.

I'd actually make this more generic, and check ifcellText has a columns attribute and ato_numpy method. That lets non-pandas objects also work; for instance polars is a pandas competitor, and there is no reason its dataframes could not be passed in here:https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.columns.html
https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.to_numpy.html

Note thatpolars.DataFrame.columns is of typelist[str], so the current implementation usingcellText.columns.to_numpy() would fail. These are exactly the subtleties I did not want to go into as part of this first-time contributor PR. Let's start with pandas, which is a clean addition. We can always generalize later, which should likely conform to thedataframe API standard (note that this is still draft)

As a side-remark: The table implementation has lots of design problems. If one was serious about tables, the wholeTable would need to be rewritten/replaced. Therefore, I wouldn't spend too much effort on trying to improve implementation.

Having anif TYPE_CHECKING: in a pyi is kind of redundant, as pyi isonly used for type checking.

This does introduce a type-check time requirement onpandas, which I don't fully love, but is notthat bad. The if/else here does not protect against not having Pandas (and not even sure a try/except would work in apyi... it would at least be unusual)

I'll reiterate that I don't think we should be special casing pandas at all, and we should not have a pandas dataframe as a type annotation. Is there anywhere else in the library that we do this?

Should I import the DataFrame method directly?