DOC: Clarify in pandas.DataFrame.drop that a copy is returned when inplace = False.

[marinomaria]

Clarify in pandas.DataFrame.drop that a copy is returned when inplace = False.

• closes DOC: Be explicit whether a view or copy is returned #33451
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[WillAyd]

lgtm. ping on green

[simonjayhawkins]

Thanks @marinomaria

[jreback]

we should actually audit all of the inplace doc-strings and make them consistent (maybe even have a rule)

[marinomaria]

I thought of this too but couldn’t figure out how to do it properly. I’m assuming there’s a better way besides searching for every method that takes an ‘inplace’ argument, checking if there’s any room for confusion and then make the adjustments.

[FSpanhel]

Hi, I am the author of #33451. Thank you for adressing this issue. In the issue I mention pandas.DataFrame.drop as an example but the scope is much broader.

In general, I might not know whether a pandas method returns a copy or a view, also if there is no 'inplace' argument.

According to https://stackoverflow.com/questions/23296282/what-rules-does-pandas-use-to-generate-a-view-vs-a-copy it appears that methods return a copy in general (assuming there is no 'inplace' argument and there is no indexing like https://pandas.pydata.org/docs/user_guide/indexing.html#returning-a-view-versus-a-copy).
However, I am confused why some methods (e.g., https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.assign.html), which do not have an 'inplace' argument, explicitly mentioned that a copy/new object is returned.
On the other hand, other methods do not mention anything at all or a VERY vague. E.g., according to the documentation (https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.query.html), pd.DataFrame.query returns a 'DataFrame resulting from the provided query expression'.
Thus, when I use a method which I haven't used before or recently, I often have to investigate whether a copy is returned. And this is very cumbersome.

I wonder whether you can confirm that methods in general return a copy? If this is the case, and if I am correct that this is not mentioned in the user guide (?), I think this should definitely be highlighted in the user guide. In this case, it might also not be necessary to clarify whether a method returns a copy or a view (if there is no 'inplace' argument). 'Only' the documentation has to be tidied, i.e., parts that mention that a copy or view is returned (e.g., https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.assign.html) should be removed.

However, if it is not true that methods return a copy in general, I would highly appreciate if every method clarifies whether it returns a copy or a view.