DOC: Add a FAQ item regarding a guaranteed in-place mutation

[OfirD1]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/pandas-docs/stable/user_guide/gotchas.html

Documentation problem

As a pandas beginner, I couldn't find a documentation telling me what's the guaranteed way to perform an in-place mutation.

For example, consider a toy mutate function:

def mutate(items, colToSet, val):
  items[colToSet] = val

Using it in pandas wouldn't mutate the original passed-in object:

dict = {'col1': [1,2,3], 'col2': [4,5,6]}
df = pd.DataFrame(dict, index=['row1', 'row2', 'row3'])

mutate(items=df['col1'], colToSet='col2', val=99)
print(df) # whoops! df hasn't changed!

But coming from native Python or many other languages, the original object would change:

dict = {'col1': [1,2,3], 'col2': [4,5,6]}
mutate(dict['col1'], colToSet=2, val=99)
print(dict) # dict['col1'][2] is now 99, not 3

It would be helpful to have a documentation making it clear that pandas mutation doesn't work this way, and that only a setting indexer (e.g. items.loc[filter, colToSet] = val) guarantees mutation.

Suggested fix for documentation

Although the CoW documentation page touches upon this subject, it doesn't make clear what guarantees a mutation, and in general this page only refers to a future change.

[rhshadrach]

Do you mean to do mutate(items=df, colToSet='col2', val=99)? This does mutate df.

[OfirD1]

@rhshadrach I do mean passing a subset of df the way I showed in my example. I guess that's why the CoW page says:

Mutating subset [...] is hard to predict.

The example I used is one I immediately encountered playing with pandas which manifests the "hard to predict" behavior, and I guess there are other ones.

[phofl]

That will get simple with CoW. mutating a subset will never mutate the parent object too.

I am closing this here, I don't want to add new docs now since this behaviour will change very very soon anyway and CoW will be the only relevant behaviour then