From fec3e34c1c721f1495d1c8f2be857e016e6384fd Mon Sep 17 00:00:00 2001 From: Loic Diridollou Date: Mon, 20 Feb 2023 13:37:09 -0800 Subject: [PATCH] Backport PR #51328: DOC: clarify "inplace"-ness of DataFrame.setitem --- pandas/core/frame.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 2520f54ae3d99..4a6b95f9a2e11 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -3870,23 +3870,27 @@ def _get_value(self, index, col, takeable: bool = False) -> Scalar: def isetitem(self, loc, value) -> None: """ - Set the given value in the column with position 'loc'. + Set the given value in the column with position `loc`. - This is a positional analogue to __setitem__. + This is a positional analogue to ``__setitem__``. Parameters ---------- loc : int or sequence of ints + Index position for the column. value : scalar or arraylike + Value(s) for the column. Notes ----- - Unlike `frame.iloc[:, i] = value`, `frame.isetitem(loc, value)` will - _never_ try to set the values in place, but will always insert a new - array. - - In cases where `frame.columns` is unique, this is equivalent to - `frame[frame.columns[i]] = value`. + ``frame.isetitem(loc, value)`` is an in-place method as it will + modify the DataFrame in place (not returning a new object). In contrast to + ``frame.iloc[:, i] = value`` which will try to update the existing values in + place, ``frame.isetitem(loc, value)`` will not update the values of the column + itself in place, it will instead insert a new array. + + In cases where ``frame.columns`` is unique, this is equivalent to + ``frame[frame.columns[i]] = value``. """ if isinstance(value, DataFrame): if is_scalar(loc):