DOC: clarify purpose of DataFrame.from_csv (GH4191)

[jorisvandenbossche]

Closes #9556

xref #9568, #4916, #4191

However, while writing this up, I started to doubt a bit if this is necessary.
DataFrame.from_csv is implemented as a round-trip method together with to_csv. If you use a plain df.to_csv(path), you cannnot read it in as pd.read_csv(path) to get exactly the same. You at least need pd.read_csv(path, index_col=True) and a parse_dates keyword if you have datetimes.

Secondly, there is also the question of Series.from_csv. It would be logical to deprecate this as well, but for this you don't directly have an alternative (but pd.read_csv(path, index_col=0)[0] will work). There is also for example this SO answer of Wes: http://stackoverflow.com/questions/13557559/how-to-write-read-pandas-series-to-from-csv (and it is used in the Python for Data Analysis book).

[jreback]

pd.read_csv(path, index_col=0, squeeze=True) should work for Series.from_csv.

I am also not strong on actually deprecating this particular method (as you say its the inverse of to_csv).

[jreback]

let's push this off / close. Not sure this is necessary.

[jreback]

let's just update the docs a tiny bit to note that DataFrame.to_csv <-> DataFrame.from_csv (and put it on pd.read_csv somewhere? I don't think we can actually deprecate this

[jorisvandenbossche]

Yes, it was on my to do list to update this PR with only the docs part (and not the actual deprecation).
I think we can still encourage users in the docstring to use read_csv, but note that from_csv is useful if you want an exact opposite of to_csv

[jorisvandenbossche]

which is actually the part from the docstring that I now removed ... :-)

[jorisvandenbossche]

@jreback updated it. Thoughts?

I still have to do the same for Series.from_csv

[jreback]

lgtm. DISCOURAGED should be an official term!

[jreback]

lgtm

[jorisvandenbossche]

updated with similar text for Series.from_csv