Fix error message

Author: Samson Gebre

src/PowerPlatform/Dataverse/utils/_pandas.py

@@ -41,11 +41,12 @@ def dataframe_to_records(df: pd.DataFrame, na_as_null: bool = False) -> List[Dic
         When True, missing values are included as None (sends null to Dataverse, clearing the field).
     :raises ValueError: If ``df`` has ``MultiIndex`` columns. Tuple column keys
         do not round-trip through Dataverse's JSON encoder and produce a
-        confusing error far from the call site. Flatten first.
+        confusing error far from the call site. Flatten to string column namesfirst.
     """
     if isinstance(df.columns, pd.MultiIndex):
         raise ValueError(
-            "MultiIndex columns are not supported. Flatten via " "df.columns = df.columns.to_flat_index() first."
+            "MultiIndex columns are not supported. Flatten to string column names first, "
+            "for example: df.columns = ['_'.join(map(str, col)) for col in df.columns.to_flat_index()]."
         )
     records = []
     for row in df.to_dict(orient="records"):

tests/unit/test_pandas_helpers.py

@@ -198,8 +198,19 @@ def test_multiindex_columns_raises(self):
         df = pd.DataFrame([["x", "y"]], columns=cols)
         with self.assertRaises(ValueError) as ctx:
             dataframe_to_records(df)
-        self.assertIn("MultiIndex", str(ctx.exception))
-        self.assertIn("to_flat_index", str(ctx.exception))
+        msg = str(ctx.exception)
+        self.assertIn("MultiIndex", msg)
+        # The remediation must produce string column names, not tuples.
+        self.assertIn("'_'.join(map(str, col)) for col in df.columns.to_flat_index()", msg)
+
+    def test_multiindex_remediation_actually_works(self):
+        """The exact remediation in the error message must produce a
+        DataFrame that dataframe_to_records can serialize."""
+        cols = pd.MultiIndex.from_tuples([("a", "firstname"), ("a", "lastname")])
+        df = pd.DataFrame([["x", "y"]], columns=cols)
+        df.columns = ["_".join(map(str, col)) for col in df.columns.to_flat_index()]
+        records = dataframe_to_records(df)
+        self.assertEqual(records, [{"a_firstname": "x", "a_lastname": "y"}])
 
     def test_mixed_types(self):
         """DataFrame with mixed types (str, int, float, None, Timestamp) converts correctly."""