Skip to content

Commit 3ce31eb

Browse files
authored
DOC: Add section about copy on write and mutating objects (#51788)
1 parent a083567 commit 3ce31eb

File tree

1 file changed

+30
-5
lines changed

1 file changed

+30
-5
lines changed

doc/source/user_guide/copy_on_write.rst

+30-5
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,6 @@
66
Copy-on-Write (CoW)
77
*******************
88

9-
.. ipython:: python
10-
:suppress:
11-
12-
pd.options.mode.copy_on_write = True
13-
149
Copy-on-Write was first introduced in version 1.5.0. Starting from version 2.0 most of the
1510
optimizations that become possible through CoW are implemented and supported. A complete list
1611
can be found at :ref:`Copy-on-Write optimizations <copy_on_write.optimizations>`.
@@ -21,6 +16,36 @@ CoW will lead to more predictable behavior since it is not possible to update mo
2116
one object with one statement, e.g. indexing operations or methods won't have side-effects. Additionally, through
2217
delaying copies as long as possible, the average performance and memory usage will improve.
2318

19+
Previous behavior
20+
-----------------
21+
22+
pandas indexing behavior is tricky to understand. Some operations return views while
23+
other return copies. Depending on the result of the operation, mutation one object
24+
might accidentally mutate another:
25+
26+
.. ipython:: python
27+
28+
df = pd.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
29+
subset = df["foo"]
30+
subset.iloc[0] = 100
31+
df
32+
33+
Mutating ``subset``, e.g. updating its values, also updates ``df``. The exact behavior is
34+
hard to predict. Copy-on-Write solves accidentally modifying more than one object,
35+
it explicitly disallows this. With CoW enabled, ``df`` is unchanged:
36+
37+
.. ipython:: python
38+
39+
pd.options.mode.copy_on_write = True
40+
41+
df = pd.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
42+
subset = df["foo"]
43+
subset.iloc[0] = 100
44+
df
45+
46+
The following sections will explain what this means and how it impacts existing
47+
applications.
48+
2449
Description
2550
-----------
2651

0 commit comments

Comments
 (0)