fix read_excel docstring

Author: thoo

pandas/io/excel.py

@@ -39,72 +39,66 @@
 _writers = {}
 
 _read_excel_doc = """
-Read an Excel table into a pandas DataFrame.
+Read an Excel file into a pandas DataFrame.
 
 Support both `xls` and `xlsx` file extensions from a local filesystem or url.
+Support an option to read a single sheet or a list of sheets.
 
 Parameters
 ---------
-io : string, path object (pathlib.Path or py._path.local.LocalPath),
-    file-like object, pandas ExcelFile, or xlrd workbook.
+io : str, file descriptor, pathlib.Path, ExcelFile or xlrd.Book
     The string could be a URL. Valid URL schemes include http, ftp, s3,
     gcs, and file. For file URLs, a host is expected. For instance, a local
-    file could be file://localhost/path/to/workbook.xlsx
-sheet_name : string, int, mixed list of strings/ints, or None, default 0
-
+    file could be /path/to/workbook.xlsx .
+sheet_name : string, int, list, or None, default 0
     Strings are used for sheet names, Integers are used in zero-indexed
-    sheet positions.
-
-    Lists of strings/integers are used to request multiple sheets.
-
-    Specify None to get all sheets.
+    sheet positions. Lists of strings/integers are used to request
+    multiple sheets. Specify None to get all sheets.
 
-    str|int -> DataFrame is returned.
-    list|None -> Dict of DataFrames is returned, with keys representing
-    sheets.
+    Available cases:
 
-    Available Cases
+    * Defaults to 0 : 1st sheet, 1 : 2nd sheet,
+    * ``"Sheet1"`` : Load sheet with name "Sheet1"
+    * ``[0, 1, "Sheet5"]``: Load 1st, 2nd and
+      sheet named "Sheet5" as a dict of `DataFrame`
+    * None : All sheets
 
-    * Defaults to 0 -> 1st sheet as a DataFrame
-    * 1 -> 2nd sheet as a DataFrame
-    * "Sheet1" -> 1st sheet as a DataFrame
-    * [0,1,"Sheet5"] -> 1st, 2nd & 5th sheet as a dictionary of DataFrames
-    * None -> All sheets as a dictionary of DataFrames
-
-sheetname : string, int, mixed list of strings/ints, or None, default 0
+sheetname : string, int, list, or None, default 0
+    Alias of `sheet_name`.
 
     .. deprecated:: 0.21.0
        Use `sheet_name` instead
 
-header : int, list of ints, default 0
+header : int, list of int, default 0
     Row (0-indexed) to use for the column labels of the parsed
     DataFrame. If a list of integers is passed those row positions will
     be combined into a ``MultiIndex``. Use None if there is no header.
 names : array-like, default None
     List of column names to use. If file contains no header row,
-    then you should explicitly pass header=None
-index_col : int, list of ints, default None
+    then you should explicitly pass header=None.
+index_col : int, list of int, default None
     Column (0-indexed) to use as the row labels of the DataFrame.
     Pass None if there is no such column.  If a list is passed,
     those columns will be combined into a ``MultiIndex``.  If a
     subset of data is selected with ``usecols``, index_col
     is based on the subset.
 parse_cols : int or list, default None
+    Alias of `usecols`.
 
     .. deprecated:: 0.21.0
-       Pass in `usecols` instead.
+       Use `usecols` instead.
 
 usecols : int, str, list-like, or callable default None
-    * If None, then parse all columns,
     * If int, then indicates last column to be parsed
 
     .. deprecated:: 0.24.0
-       Pass in a list of ints instead from 0 to `usecols` inclusive.
+       Pass in a list of int instead from 0 to `usecols` inclusive.
 
+    * If None, then parse all columns,
     * If string, then indicates comma separated list of Excel column letters
       and column ranges (e.g. "A:E" or "A,C,E:F"). Ranges are inclusive of
       both sides.
-    * If list of ints, then indicates list of column numbers to be parsed.
+    * If list of int, then indicates list of column numbers to be parsed.
     * If list of strings, then indicates list of column names to be parsed.
 
     .. versionadded:: 0.24.0
@@ -114,7 +108,7 @@
 
     .. versionadded:: 0.24.0
 
-squeeze : boolean, default False
+squeeze : bool, default False
     If the parsed data only contains one column then return a Series
 dtype : Type name or dict of column -> type, default None
     Data type for data or columns. E.g. {'a': np.float64, 'b': np.int32}
@@ -124,7 +118,7 @@
 
     .. versionadded:: 0.20.0
 
-engine : string, default None
+engine : str, default None
     If io is not a buffer or path, this must be set to identify io.
     Acceptable values are None or xlrd
 converters : dict, default None
@@ -156,7 +150,7 @@
 keep_default_na : bool, default True
     If na_values are specified and keep_default_na is False the default NaN
     values are overridden, otherwise they're appended to.
-verbose : boolean, default False
+verbose : bool, default False
     Indicate number of NA values placed in non-numeric columns
 thousands : str, default None
     Thousands separator for parsing string columns to numeric.  Note that
@@ -168,96 +162,86 @@
     argument to indicate comments in the input file. Any data between the
     comment string and the end of the current line is ignored.
 skip_footer : int, default 0
+    Alias to `skipfooter`.
 
     .. deprecated:: 0.23.0
-       Pass in `skipfooter` instead.
+       Use `skipfooter` instead.
 skipfooter : int, default 0
     Rows at the end to skip (0-indexed)
-convert_float : boolean, default True
+convert_float : bool, default True
     convert integral floats to int (i.e., 1.0 --> 1). If False, all numeric
     data will be read in as floats: Excel stores all numbers as floats
-    internally
-mangle_dupe_cols : boolean, default True
+    internally.
+mangle_dupe_cols : bool, default True
     Duplicate columns will be specified as 'X', 'X.1', ...'X.N', rather than
     'X'...'X'. Passing in False will cause data to be overwritten if there
     are duplicate names in the columns.
 
 Returns
 -------
-parsed : DataFrame or Dict of DataFrames
+parsed : DataFrame or dict of DataFrames
     DataFrame from the passed in Excel file. See notes in sheet_name
     argument for more information on when a dict of DataFrames is returned.
 
-Examples
+See Also
 --------
+to_excel : Write DataFrame to an Excel file.
+to_csv : Write DataFrame to a comma-separated values (csv) file.
+read_csv : Read a comma-separated values (csv) file into DataFrame.
+read_fwf : Read a table of fixed-width formatted lines into DataFrame.
 
-An example DataFrame written to a local file
-
->>> df_out = pd.DataFrame([('string1', 1),
-...                        ('string2', 2),
-...                        ('string3', 3)],
-...                       columns=['Name', 'Value'])
->>> df_out
-      Name  Value
-0  string1      1
-1  string2      2
-2  string3      3
->>> df_out.to_excel('tmp.xlsx')
-
+Examples
+--------
 The file can be read using the file name as string or an open file object:
 
->>> pd.read_excel('tmp.xlsx')
-      Name  Value
-0  string1      1
-1  string2      2
-2  string3      3
+>>> pd.read_excel('tmp.xlsx', index_col=0)  # doctest: +SKIP
+       Name  Value
+0   string1      1
+1   string2      2
+2  #string3      3
 
->>> pd.read_excel(open('tmp.xlsx','rb'))
-      Name  Value
-0  string1      1
-1  string2      2
-2  string3      3
+>>> pd.read_excel(open('tmp.xlsx', 'rb'), sheet_name='Sheet3')  # doctest: +SKIP
+   Unnamed: 0      Name  Value
+0           0   string1      1
+1           1   string2      2
+2           2  #string3      3
 
 Index and header can be specified via the `index_col` and `header` arguments
 
->>> pd.read_excel('tmp.xlsx', index_col=None, header=None)
-     0        1      2
-0  NaN     Name  Value
-1  0.0  string1      1
-2  1.0  string2      2
-3  2.0  string3      3
+>>> pd.read_excel('tmp.xlsx', index_col=None, header=None)  # doctest: +SKIP
+     0         1      2
+0  NaN      Name  Value
+1  0.0   string1      1
+2  1.0   string2      2
+3  2.0  #string3      3
 
 Column types are inferred but can be explicitly specified
 
->>> pd.read_excel('tmp.xlsx', dtype={'Name':str, 'Value':float})
-      Name  Value
-0  string1    1.0
-1  string2    2.0
-2  string3    3.0
+>>> pd.read_excel('tmp.xlsx', index_col=0,
+...               dtype={'Name': str, 'Value': float})  # doctest: +SKIP
+       Name  Value
+0   string1    1.0
+1   string2    2.0
+2  #string3    3.0
 
 True, False, and NA values, and thousands separators have defaults,
 but can be explicitly specified, too. Supply the values you would like
 as strings or lists of strings!
 
->>> pd.read_excel('tmp.xlsx',
-...               na_values=['string1', 'string2'])
-      Name  Value
-0      NaN      1
-1      NaN      2
-2  string3      3
+>>> pd.read_excel('tmp.xlsx', index_col=0,
+...               na_values=['string1', 'string2'])  # doctest: +SKIP
+       Name  Value
+0       NaN      1
+1       NaN      2
+2  #string3      3
 
 Comment lines in the excel input file can be skipped using the `comment` kwarg
 
->>> df = pd.DataFrame({'a': ['1', '#2'], 'b': ['2', '3']})
->>> df.to_excel('tmp.xlsx', index=False)
->>> pd.read_excel('tmp.xlsx')
-    a  b
-0   1  2
-1  #2  3
-
->>> pd.read_excel('tmp.xlsx', comment='#')
-   a  b
-0  1  2
+>>> pd.read_excel('tmp.xlsx', index_col=0, comment='#')  # doctest: +SKIP
+      Name  Value
+0  string1    1.0
+1  string2    2.0
+2     None    NaN
 """