CoW: better chained assignment warning message for update() method (#63500)

Author: jorisvandenbossche

pandas/_testing/contexts.py

@@ -140,7 +140,7 @@ def raises_chained_assignment_error(extra_warnings=(), extra_match=()):
     else:
         warning = ChainedAssignmentError
         match = (
-            "A value is trying to be set on a copy of a DataFrame or Series "
+            "A value is being set on a copy of a DataFrame or Series "
             "through chained assignment"
         )
         if extra_warnings:

pandas/core/frame.py

@@ -62,7 +62,7 @@
     Pandas4Warning,
 )
 from pandas.errors.cow import (
-    _chained_assignment_method_msg,
+    _chained_assignment_method_update_msg,
     _chained_assignment_msg,
 )
 from pandas.util._decorators import (
@@ -10540,7 +10540,7 @@ def update(
                 self
             ) <= REF_COUNT_METHOD and not com.is_local_in_caller_frame(self):
                 warnings.warn(
-                    _chained_assignment_method_msg,
+                    _chained_assignment_method_update_msg,
                     ChainedAssignmentError,
                     stacklevel=2,
                 )

pandas/core/series.py

@@ -47,7 +47,7 @@
     Pandas4Warning,
 )
 from pandas.errors.cow import (
-    _chained_assignment_method_msg,
+    _chained_assignment_method_update_msg,
     _chained_assignment_msg,
 )
 from pandas.util._decorators import (
@@ -3521,7 +3521,7 @@ def update(self, other: Series | Sequence | Mapping) -> None:
                 self
             ) <= REF_COUNT_METHOD and not com.is_local_in_caller_frame(self):
                 warnings.warn(
-                    _chained_assignment_method_msg,
+                    _chained_assignment_method_update_msg,
                     ChainedAssignmentError,
                     stacklevel=2,
                 )

pandas/errors/cow.py

@@ -1,5 +1,5 @@
 _chained_assignment_msg = (
-    "A value is trying to be set on a copy of a DataFrame or Series "
+    "A value is being set on a copy of a DataFrame or Series "
     "through chained assignment.\n"
     "Such chained assignment never works to update the original DataFrame or "
     "Series, because the intermediate object on which we are setting values "
@@ -13,7 +13,7 @@
 
 
 _chained_assignment_method_msg = (
-    "A value is trying to be set on a copy of a DataFrame or Series "
+    "A value is being set on a copy of a DataFrame or Series "
     "through chained assignment using an inplace method.\n"
     "Such inplace method never works to update the original DataFrame or Series, "
     "because the intermediate object on which we are setting values always "
@@ -26,3 +26,18 @@
     "https://pandas.pydata.org/pandas-docs/stable/user_guide/"
     "copy_on_write.html"
 )
+
+
+_chained_assignment_method_update_msg = (
+    "A value is being set on a copy of a DataFrame or Series "
+    "through chained assignment using an inplace method.\n"
+    "Such inplace method never works to update the original DataFrame or Series, "
+    "because the intermediate object on which we are setting values always "
+    "behaves as a copy (due to Copy-on-Write).\n\n"
+    "For example, when doing 'df[col].update(other)', try "
+    "using 'df.update({col: other})' instead, to perform "
+    "the operation inplace on the original object.\n\n"
+    "See the documentation for a more detailed explanation: "
+    "https://pandas.pydata.org/pandas-docs/stable/user_guide/"
+    "copy_on_write.html"
+)

pandas/tests/indexing/test_chaining_and_caching.py

@@ -14,8 +14,6 @@
 )
 import pandas._testing as tm
 
-msg = "A value is trying to be set on a copy of a slice from a DataFrame"
-
 
 class TestCaching:
     @pytest.mark.parametrize("do_ref", [True, False])

scripts/validate_unwanted_patterns.py

@@ -50,6 +50,7 @@
     "_global_config",
     "_chained_assignment_msg",
     "_chained_assignment_method_msg",
+    "_chained_assignment_method_update_msg",
     "_version_meson",
     # The numba extensions need this to mock the iloc object
     "_iLocIndexer",