From e05bd1fd873862ce1c88474198a708eb73c3341e Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 4 Dec 2023 11:59:54 +0100 Subject: [PATCH] DOC: more explicit note about upcoming CoW changes in copy() method docstring --- pandas/core/generic.py | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index ace6323e84c77..db993714b4c80 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6681,6 +6681,21 @@ def copy(self, deep: bool_t | None = True) -> Self: and index are copied). Any changes to the data of the original will be reflected in the shallow copy (and vice versa). + .. note:: + The ``deep=False`` behaviour as described above will change + in pandas 3.0. `Copy-on-Write + `__ + will be enabled by default, which means that the "shallow" copy + is that is returned with ``deep=False`` will still avoid making + an eager copy, but changes to the data of the original will *no* + longer be reflected in the shallow copy (or vice versa). Instead, + it makes use of a lazy (deferred) copy mechanism that will copy + the data only when any changes to the original or shallow copy is + made. + + You can already get the future behavior and improvements through + enabling copy on write ``pd.options.mode.copy_on_write = True`` + Parameters ---------- deep : bool, default True @@ -6750,7 +6765,8 @@ def copy(self, deep: bool_t | None = True) -> Self: False Updates to the data shared by shallow copy and original is reflected - in both; deep copy remains unchanged. + in both (NOTE: this will no longer be true for pandas >= 3.0); + deep copy remains unchanged. >>> s.iloc[0] = 3 >>> shallow.iloc[1] = 4 @@ -6783,7 +6799,8 @@ def copy(self, deep: bool_t | None = True) -> Self: 1 [3, 4] dtype: object - ** Copy-on-Write is set to true: ** + **Copy-on-Write is set to true**, the shallow copy is not modified + when the original data is changed: >>> with pd.option_context("mode.copy_on_write", True): ... s = pd.Series([1, 2], index=["a", "b"])