Skip to content

Commit be08de8

Browse files
authored
DOC: Add note to user guide that SettingWithCopyWarning won't be necessary anymore (#56032)
1 parent e7fa8bb commit be08de8

File tree

2 files changed

+58
-0
lines changed

2 files changed

+58
-0
lines changed

doc/source/user_guide/copy_on_write.rst

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

9+
.. note::
10+
11+
Copy-on-Write will become the default in pandas 3.0. We recommend
12+
:ref:`turning it on now <copy_on_write_enabling>`
13+
to benefit from all improvements.
14+
915
Copy-on-Write was first introduced in version 1.5.0. Starting from version 2.0 most of the
1016
optimizations that become possible through CoW are implemented and supported. All possible
1117
optimizations are supported starting from pandas 2.1.
@@ -123,6 +129,8 @@ CoW triggers a copy when ``df`` is changed to avoid mutating ``view`` as well:
123129
df
124130
view
125131
132+
.. _copy_on_write_chained_assignment:
133+
126134
Chained Assignment
127135
------------------
128136

@@ -238,6 +246,8 @@ and :meth:`DataFrame.rename`.
238246
These methods return views when Copy-on-Write is enabled, which provides a significant
239247
performance improvement compared to the regular execution.
240248

249+
.. _copy_on_write_enabling:
250+
241251
How to enable CoW
242252
-----------------
243253

doc/source/user_guide/indexing.rst

+48
Original file line numberDiff line numberDiff line change
@@ -1727,6 +1727,22 @@ You can assign a custom index to the ``index`` attribute:
17271727
Returning a view versus a copy
17281728
------------------------------
17291729

1730+
.. warning::
1731+
1732+
:ref:`Copy-on-Write <copy_on_write>`
1733+
will become the new default in pandas 3.0. This means than chained indexing will
1734+
never work. As a consequence, the ``SettingWithCopyWarning`` won't be necessary
1735+
anymore.
1736+
See :ref:`this section <copy_on_write_chained_assignment>`
1737+
for more context.
1738+
We recommend turning Copy-on-Write on to leverage the improvements with
1739+
1740+
```
1741+
pd.options.mode.copy_on_write = True
1742+
```
1743+
1744+
even before pandas 3.0 is available.
1745+
17301746
When setting values in a pandas object, care must be taken to avoid what is called
17311747
``chained indexing``. Here is an example.
17321748

@@ -1765,6 +1781,22 @@ faster, and allows one to index *both* axes if so desired.
17651781
Why does assignment fail when using chained indexing?
17661782
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17671783

1784+
.. warning::
1785+
1786+
:ref:`Copy-on-Write <copy_on_write>`
1787+
will become the new default in pandas 3.0. This means than chained indexing will
1788+
never work. As a consequence, the ``SettingWithCopyWarning`` won't be necessary
1789+
anymore.
1790+
See :ref:`this section <copy_on_write_chained_assignment>`
1791+
for more context.
1792+
We recommend turning Copy-on-Write on to leverage the improvements with
1793+
1794+
```
1795+
pd.options.mode.copy_on_write = True
1796+
```
1797+
1798+
even before pandas 3.0 is available.
1799+
17681800
The problem in the previous section is just a performance issue. What's up with
17691801
the ``SettingWithCopy`` warning? We don't **usually** throw warnings around when
17701802
you do something that might cost a few extra milliseconds!
@@ -1821,6 +1853,22 @@ Yikes!
18211853
Evaluation order matters
18221854
~~~~~~~~~~~~~~~~~~~~~~~~
18231855

1856+
.. warning::
1857+
1858+
:ref:`Copy-on-Write <copy_on_write>`
1859+
will become the new default in pandas 3.0. This means than chained indexing will
1860+
never work. As a consequence, the ``SettingWithCopyWarning`` won't be necessary
1861+
anymore.
1862+
See :ref:`this section <copy_on_write_chained_assignment>`
1863+
for more context.
1864+
We recommend turning Copy-on-Write on to leverage the improvements with
1865+
1866+
```
1867+
pd.options.mode.copy_on_write = True
1868+
```
1869+
1870+
even before pandas 3.0 is available.
1871+
18241872
When you use chained indexing, the order and type of the indexing operation
18251873
partially determine whether the result is a slice into the original object, or
18261874
a copy of the slice.

0 commit comments

Comments
 (0)