DOC: pandas.DataFrame.aggregate return value

[sa42bme]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.aggregate.html#pandas.DataFrame.aggregate

Documentation problem

The documentation of pandas.DataFrame.aggregate() method says:

The return can be:

* scalar : when Series.agg is called with single function
* Series : when DataFrame.agg is called with a single function
* DataFrame : when DataFrame.agg is called with several functions

But
df = pd.DataFrame([[1]]) ; type(df.agg(lambda x: 3*x))
returns pandas.core.frame.DataFrame even though .agg() was called with a single function

Suggested fix for documentation

I'd love to offer a fix, but the reason I was looking up the docs was that I'd like to know what .agg() does exactly...

[rhshadrach]

Thanks for the report. This is #35725.

Ideally users would only pass aggregating functions to .agg. I think the current result here is incorrect, and it should be Series([Series([3])]) instead. Unfortunately it is not so easy to fix because the implementation is intertwined with apply. We made some progress on it in the 2.x development, but need to wait until 3.x to make more.

We could document this in the meantime, but I don't think we should document buggy behavior.