BUG: Fix 58807 (#59243)

* throw when frame apply is given invalid axis+func

* test that frame_apply throws on invalid func+axis

* add a note on unsupported func+axis combination for frame_apply

* add bug fix to release notes

* fix based on review comments

* test also with named axis

* Update doc/source/whatsnew/v3.0.0.rst

Co-authored-by: Matthew Roeschke <[email protected]>

* fix rst

---------

Co-authored-by: Matthew Roeschke <[email protected]>

Author: matiaslindgren

doc/source/whatsnew/v3.0.0.rst

@@ -32,6 +32,7 @@ Other enhancements
 - :class:`pandas.api.typing.SASReader` is available for typing the output of :func:`read_sas` (:issue:`55689`)
 - :func:`DataFrame.to_excel` now raises an ``UserWarning`` when the character count in a cell exceeds Excel's limitation of 32767 characters (:issue:`56954`)
 - :func:`read_stata` now returns ``datetime64`` resolutions better matching those natively stored in the stata format (:issue:`55642`)
+- :meth:`DataFrame.agg` called with ``axis=1`` and a ``func`` which relabels the result index now raises a ``NotImplementedError`` (:issue:`58807`).
 - :meth:`Styler.set_tooltips` provides alternative method to storing tooltips by using title attribute of td elements. (:issue:`56981`)
 - Allow dictionaries to be passed to :meth:`pandas.Series.str.replace` via ``pat`` parameter (:issue:`51748`)
 - Support passing a :class:`Series` input to :func:`json_normalize` that retains the :class:`Series` :class:`Index` (:issue:`51452`)

pandas/core/apply.py

@@ -90,16 +90,19 @@ def frame_apply(
     kwargs=None,
 ) -> FrameApply:
     """construct and return a row or column based frame apply object"""
+    _, func, columns, _ = reconstruct_func(func, **kwargs)
+
     axis = obj._get_axis_number(axis)
     klass: type[FrameApply]
     if axis == 0:
         klass = FrameRowApply
     elif axis == 1:
+        if columns:
+            raise NotImplementedError(
+                f"Named aggregation is not supported when {axis=}."
+            )
         klass = FrameColumnApply
 
-    _, func, _, _ = reconstruct_func(func, **kwargs)
-    assert func is not None
-
     return klass(
         obj,
         func,

pandas/core/shared_docs.py

@@ -49,6 +49,8 @@
 for more details.
 
 A passed user-defined-function will be passed a Series for evaluation.
+
+If ``func`` defines an index relabeling, ``axis`` must be ``0`` or ``index``.
 {examples}"""
 
 _shared_docs["compare"] = """

pandas/tests/apply/test_frame_apply.py

@@ -1330,6 +1330,14 @@ def test_agg_reduce(axis, float_frame):
     tm.assert_frame_equal(result, expected)
 
 
+def test_named_agg_reduce_axis1_raises(float_frame):
+    name1, name2 = float_frame.axes[0].unique()[:2].sort_values()
+    msg = "Named aggregation is not supported when axis=1."
+    for axis in [1, "columns"]:
+        with pytest.raises(NotImplementedError, match=msg):
+            float_frame.agg(row1=(name1, "sum"), row2=(name2, "max"), axis=axis)
+
+
 def test_nuiscance_columns():
     # GH 15015
     df = DataFrame(