ENH: Add sort_columns parameter to combine_first

Author: U-S-jun

doc/source/whatsnew/v3.0.0.rst

@@ -13,6 +13,10 @@ including other versions of pandas.
 
 Enhancements
 ~~~~~~~~~~~~
+- Added a ``sort_columns`` parameter to :meth:`DataFrame.combine_first` to allow
+  control over whether the result's column order should follow the original
+  DataFrame's order or be sorted lexicographically. ([#60427](https://github.com/pandas-dev/pandas/issues/60427))
+
 
 .. _whatsnew_300.enhancements.enhancement1:
 

pandas/core/frame.py

@@ -8712,7 +8712,9 @@ def combine(
         frame_result = self._constructor(result, index=new_index, columns=new_columns)
         return frame_result.__finalize__(self, method="combine")
 
-    def combine_first(self, other: DataFrame, sort_columns=True) -> DataFrame:
+    def combine_first(
+        self, other: DataFrame, *, sort_columns: bool = True
+    ) -> DataFrame:
         """
         Update null elements with value in the same location in `other`.
 
@@ -8789,7 +8791,7 @@ def combiner(x: Series, y: Series):
                 return y_values
 
             return expressions.where(mask, y_values, x_values)
-        
+
         all_columns = self.columns.union(other.columns)
 
         if len(other) == 0:
@@ -8808,13 +8810,11 @@ def combiner(x: Series, y: Series):
 
         if dtypes:
             combined = combined.astype(dtypes)
-        
+
         combined = combined.reindex(columns=all_columns, fill_value=None)
 
         if not sort_columns:
             combined = combined[self.columns]
-        
-
 
         return combined.__finalize__(self, method="combine_first")
 
@@ -10543,9 +10543,11 @@ def _append(
 
             index = Index(
                 [other.name],
-                name=self.index.names
-                if isinstance(self.index, MultiIndex)
-                else self.index.name,
+                name=(
+                    self.index.names
+                    if isinstance(self.index, MultiIndex)
+                    else self.index.name
+                ),
             )
             row_df = other.to_frame().T
             # infer_objects is needed for

pandas/tests/frame/methods/test_combine_first.py

@@ -561,10 +561,11 @@ def test_combine_first_empty_columns():
     expected = DataFrame(columns=["a", "b", "c"])
     tm.assert_frame_equal(result, expected)
 
+
 def test_combine_first_column_order():
-    df1 = pd.DataFrame({"B": [1, 2], "A": [3, 4]})
-    df2 = pd.DataFrame({"A": [5]}, index=[1])
+    df1 = DataFrame({"B": [1, 2], "A": [3, 4]})
+    df2 = DataFrame({"A": [5]}, index=[1])
 
-    result = df1.combine_first(df2,sort_columns=False)
-    expected = pd.DataFrame({"B": [1, 2], "A": [3, 4]})
-    pd.testing.assert_frame_equal(result, expected)
+    result = df1.combine_first(df2, sort_columns=False)
+    expected = DataFrame({"B": [1, 2], "A": [3, 4]})
+    tm.assert_frame_equal(result, expected)