Repository: pandas-dev/pandas

Issue:
DataFrame.from_csv undocumented behavior of index_col
Took me a while to find this (in the end by stackoverflow), but I ran into the problem while trying to parse a csv file. Panda kept parsing the first column as the index column instead of generating a new index. I could not find a way to disable this after reading the docs here:

http://pandas.pydata.org/pandas-docs/dev/generated/pandas.DataFrame.from_csv.html

As it turns out, due to the line of code below, if the argument is set to False, then it has the behavior I desired. This is completely undocumented and would be very helpful to have. I haven't contributed before to Pandas, so if it is more than a quick change a maintainer can make, I could put the work in for a PR, even if its just documentation changes.

https://github.com/pydata/pandas/blob/master/pandas/io/parsers.py#L1064



Discussion:
Please have a look at the docstring of read_csv: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.read_csv.html

I think there this feature is explained. `from_csv` should actually be deprecated and the docs should just refer to `read_csv` (see #4191)

I would agree with #4191 which points to #4916 that it should be deprecated. For the short term, could the docs be updated to reflect that from_csv will be deprecated or that users should use read_csv instead (perhaps additionally document the False usage).

Yes I will do a PR. At least the 'deprecation' can be documented by removing the current doctring and just pointing to `read_csv` (and noting the one difference in the default value of `parse_dates`)

or if you would like to do a PR for this, certainly welcome!

I would be good with either. Should be a quick change, most of the time tbh would be in forking and generating the docs. I could probably work on it tonight/tomorrow.

Give it a go! (I would also work at it this weekend at the earliest). Normally, for such a small change, building the full docs should not be necessary (but of course, it can be a good exercise to try to build them), just have a look at the existing docstrings for the format (and here for a description of the format: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard)


Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -180,7 +180,6 @@ class DataFrame(NDFrame):
     --------
     DataFrame.from_records : constructor from tuples, also record arrays
     DataFrame.from_dict : from dicts of Series, arrays, or dicts
-    DataFrame.from_csv : from CSV files
     DataFrame.from_items : from sequence of (key, value) pairs
     pandas.read_csv, pandas.read_table, pandas.read_clipboard
     """
@@ -1052,13 +1051,29 @@ def from_csv(cls, path, header=0, sep=',', index_col=0,
                  parse_dates=True, encoding=None, tupleize_cols=False,
                  infer_datetime_format=False):
         """
-        Read delimited file into DataFrame
+        Read CSV file (DISCOURAGED, please use :func:`pandas.read_csv` instead).
+
+        It is preferable to use the more powerful :func:`pandas.read_csv`
+        for most general purposes, but ``from_csv`` makes for an easy
+        roundtrip to and from a file (the exact counterpart of
+        ``to_csv``), especially with a DataFrame of time series data.
+
+        This method only differs from the preferred :func:`pandas.read_csv`
+        in some defaults:
+
+        - `index_col` is ``0`` instead of ``None`` (take first column as index
+          by default)
+        - `parse_dates` is ``True`` instead of ``False`` (try parsing the index
+          as datetime by default)
+
+        So a ``pd.DataFrame.from_csv(path)`` can be replaced by
+        ``pd.read_csv(path, index_col=0, parse_dates=True)``.
 
         Parameters
         ----------
         path : string file path or file handle / StringIO
         header : int, default 0
-            Row to use at header (skip prior rows)
+            Row to use as header (skip prior rows)
         sep : string, default ','
             Field delimiter
         index_col : int or sequence, default 0
@@ -1074,15 +1089,14 @@ def from_csv(cls, path, header=0, sep=',', index_col=0,
             datetime format based on the first datetime string. If the format
             can be inferred, there often will be a large parsing speed-up.
 
-        Notes
-        -----
-        Preferable to use read_table for most general purposes but from_csv
-        makes for an easy roundtrip to and from file, especially with a
-        DataFrame of time series data
+        See also
+        --------
+        pandas.read_csv
 
         Returns
         -------
         y : DataFrame
+
         """
         from pandas.io.parsers import read_table
         return read_table(path, header=header, sep=sep,
diff --git a/pandas/core/series.py b/pandas/core/series.py
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -2313,7 +2313,24 @@ def between(self, left, right, inclusive=True):
     def from_csv(cls, path, sep=',', parse_dates=True, header=None,
                  index_col=0, encoding=None, infer_datetime_format=False):
         """
-        Read delimited file into Series
+        Read CSV file (DISCOURAGED, please use :func:`pandas.read_csv` instead).
+
+        It is preferable to use the more powerful :func:`pandas.read_csv`
+        for most general purposes, but ``from_csv`` makes for an easy
+        roundtrip to and from a file (the exact counterpart of
+        ``to_csv``), especially with a time Series.
+
+        This method only differs from :func:`pandas.read_csv` in some defaults:
+
+        - `index_col` is ``0`` instead of ``None`` (take first column as index
+          by default)
+        - `header` is ``None`` instead of ``0`` (the first row is not used as
+          the column names)
+        - `parse_dates` is ``True`` instead of ``False`` (try parsing the index
+          as datetime by default)
+
+        With :func:`pandas.read_csv`, the option ``squeeze=True`` can be used
+        to return a Series like ``from_csv``.
 
         Parameters
         ----------
@@ -2322,8 +2339,8 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None,
             Field delimiter
         parse_dates : boolean, default True
             Parse dates. Different default from read_table
-        header : int, default 0
-            Row to use at header (skip prior rows)
+        header : int, default None
+            Row to use as header (skip prior rows)
         index_col : int or sequence, default 0
             Column to use for index. If a sequence is given, a MultiIndex
             is used. Different default from read_table
@@ -2335,6 +2352,10 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None,
             datetime format based on the first datetime string. If the format
             can be inferred, there often will be a large parsing speed-up.
 
+        See also
+        --------
+        pandas.read_csv
+
         Returns
         -------
         y : Series


Test patch: