ENH: add inplace-kwarg to df.update

Author: h-vetinari

doc/source/whatsnew/v0.24.0.txt

@@ -468,6 +468,7 @@ Other API Changes
 - :meth:`PeriodIndex.tz_convert` and :meth:`PeriodIndex.tz_localize` have been removed (:issue:`21781`)
 - :class:`Index` subtraction will attempt to operate element-wise instead of raising ``TypeError`` (:issue:`19369`)
 - :class:`pandas.io.formats.style.Styler` supports a ``number-format`` property when using :meth:`~pandas.io.formats.style.Styler.to_excel` (:issue:`22015`)
+- :meth:~DataFrame.update has gained an ``inplace``-kwarg, which defaults to True (same behavior as before).
 
 .. _whatsnew_0240.deprecations:
 

pandas/core/frame.py

@@ -5184,7 +5184,7 @@ def combiner(x, y, needs_i8_conversion=False):
         return self.combine(other, combiner, overwrite=False)
 
     def update(self, other, join='left', overwrite=True, filter_func=None,
-               raise_conflict=False):
+               raise_conflict=False, inplace=True):
         """
         Modify in place using non-NA values from another DataFrame.
 
@@ -5214,6 +5214,9 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
         raise_conflict : bool, default False
             If True, will raise a ValueError if the DataFrame and `other`
             both contain non-NA data in the same place.
+        inplace : bool, default True
+            If True, follows the convention by ``dict`` of updating inplace. If
+            False, returns a new object.
 
         Raises
         ------
@@ -5295,8 +5298,13 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
 
         other = other.reindex_like(self)
 
-        for col in self.columns:
-            this = self[col].values
+        if inplace:
+            frame = self
+        else:
+            frame = self.copy()
+
+        for col in frame.columns:
+            this = frame[col].values
             that = other[col].values
             if filter_func is not None:
                 with np.errstate(all='ignore'):
@@ -5317,7 +5325,10 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
             if mask.all():
                 continue
 
-            self[col] = expressions.where(mask, this, that)
+            frame[col] = expressions.where(mask, this, that)
+
+        if not inplace:
+            return frame
 
     # ----------------------------------------------------------------------
     # Data reshaping

pandas/tests/frame/test_combine_concat.py

@@ -4,6 +4,8 @@
 
 from datetime import datetime
 
+import pytest
+
 import numpy as np
 from numpy import nan
 
@@ -198,7 +200,8 @@ def test_append_dtypes(self):
         expected = DataFrame({'bar': Series([Timestamp('20130101'), 1])})
         assert_frame_equal(result, expected)
 
-    def test_update(self):
+    @pytest.mark.parametrize('inplace', [True, False])
+    def test_update(self, inplace):
         df = DataFrame([[1.5, nan, 3.],
                         [1.5, nan, 3.],
                         [1.5, nan, 3],
@@ -207,7 +210,10 @@ def test_update(self):
         other = DataFrame([[3.6, 2., np.nan],
                            [np.nan, np.nan, 7]], index=[1, 3])
 
-        df.update(other)
+        if inplace:
+            df.update(other, inplace=inplace)
+        else:
+            df = df.update(other, inplace=inplace)
 
         expected = DataFrame([[1.5, nan, 3],
                               [3.6, 2, 3],