Repository: pandas-dev/pandas
Pull request: #53718 Added copy_on_write effects on pd.Dataframe.copy() method
- [x] closes #53718  
- [x] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).



Problem statement:
DOC: Update the DataFrame.copy docstring to note different behaviour with Copy-on-Write
Currently the `copy()` method docstring shows several examples how mutations are propagated for shallow copies (*"Any changes to the data of the original will be reflected in the shallow copy (and vice versa)."* in the main description, *"Updates to the data shared by shallow copy and original is reflected in both; deep copy remains unchanged."* in the examples section)

While is this of course still correct with the default behaviour, given that this is completely incorrect when CoW is enabled, I would at least start with adding a note about this (and for example referring to the Copy-on-Write documentation).

Hints from issue discussion:
Hi! I can take this up if it is not already being worked on.
Hi @jorisvandenbossche  ,

I would love to take up this issue. May I have the link to the file that we need to update?

Commit message: iloc

Patch to review:
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 8a3a105749800..a1e9b9e93ea90 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -6584,6 +6584,13 @@ def copy(self, deep: bool_t | None = True) -> Self:
         :ref:`gotchas <gotchas.thread-safety>` when copying in a threading
         environment.
 
+        When ``copy_on_write`` in pandas global config is set to ``True``, the
+        ``copy_on_write`` global config take effect even when ``deep=False``.
+        This means that any changes to the copied data would make a new copy
+        of the data upon write (and vice versa). o changes would not be reflected
+        in the original copy. See
+        :ref:`Copy_on_Write <copy_on_write>` for more information.
+
         Examples
         --------
         >>> s = pd.Series([1, 2], index=["a", "b"])
@@ -6651,6 +6658,21 @@ def copy(self, deep: bool_t | None = True) -> Self:
         0    [10, 2]
         1     [3, 4]
         dtype: object
+
+        ** Copy-on-Write is set to true: **
+
+        >>> pd.set_option("mode.copy_on_write", True)
+        >>> s = pd.Series([1, 2], index=["a", "b"])
+        >>> copy = s.copy(deep=False)
+        >>> s.iloc[0] = 100
+        >>> s
+        a    100
+        b      2
+        dtype: int64
+        >>> copy
+        a    1
+        b    2
+        dtype: int64
         """
         data = self._mgr.copy(deep=deep)
         self._clear_item_cache()


Code review comments:
diff_hunk: @@ -6651,6 +6658,21 @@ def copy(self, deep: bool_t | None = True) -> Self:
         0    [10, 2]
         1     [3, 4]
         dtype: object
+
+        ** Copy-on-Write is set to true: **
+
+        >>> pd.set_option("mode.copy_on_write", True)
path: pandas/core/generic.py
text: @user1:
This will set the option to True for all following tests as well, this has to be wrapped in with(pd.options_context...)