Description
Pandas version checks
- I have checked that the issue still exists on the latest versions of the docs on
mainhere
Location of the documentation
https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_pickle.html
Documentation problem
The documentation for pd.DataFrame.to_csv specifies the argument name path_or_buf, indicating that a buffer can be passed to write the dataframe's csv data to. In contrast, pd.DataFrame.to_pickle simply provides the path argument, which is hinted as a str. However, (from what I can tell) the to_pickle's path argument behaves the same as the path_or_buf argument of to_csv with respect to file buffers, but this behavior is undocumented on the page for to_pickle. In my opinion, the path should match the path_or_buf name, or to_pickle should not support writing to buffers. But since either one of these would be breaking changes, the best we can do is just update the documentation.
Suggested fix for documentation
Update the following documentation for the path argument:
File path where the pickled object will be stored.
To
File path where the pickled object will be stored, or file-like object implementing a write() function.
Additionally, the type hint should be updated. This is a beneficial change because it provides greater clarity for the functionality of pd.DataFrame.to_pickle, and will avoid false-positive type checking warnings/errors.