API: read_excel signature
State: closed

Replace the `**kwds` in `read_excel` with the actual list of supported keyword args. This doesn't
change any functionality, just nicer for interactive use.  Also a bit of clarification on the `thousands`
arg in the docstring.

Additionally, `chunksize` was a parameter in the `ExcelFile.parse` signature, but didn't do anything (xref #8011).  I removed this and raise `NotImplementedError` if passed, which is potentially breaking.


Labels:
name: API Design
name: IO Excel
description: read_excel, to_excel

Comments:
@jreback - alright, I deprecated `ExcelFile.parse`, modified a bunch of tests to no longer use that.

I also reordered the Excel docs to fit the new note; I think it reads more logically now.

@jreback - made the changes you noted.

looks good. ping when green.

Is there a good reason to deprecate `ExcelFile.parse`? 
The docs gives an explicit use for it compared to `read_excel`: http://pandas.pydata.org/pandas-docs/stable/io.html#reading-excel-files

@jorisvandenbossche - there's no super-compelling reason; the main idea was to match up with api of `to_excel`, i.e. the "`ExcelFileWrapper`" (`ExcelFile`, `ExcelWriter`) doesn't have any pandas-specific functionality, instead you pass it into the io functions (`read_excel`, `to_excel`).

I did update the docs to cover that specific example. edit: although it may be hard to see in the diff - rendered below.

![image](https://cloud.githubusercontent.com/assets/1924092/10125523/6cbc2eec-653d-11e5-9fe5-8d67df8b157d.png)

OK, I see that you changed that explanation in the docs I was pointing to. But, what is the point of `ExcelFile` then? What advantage does it give above just providing the string name?

@jorisvandenbossche 

I would say there _isn't_ any usecase for exposing `ExcelFile` in the current impl. Before `read_excel`, sure it was the way you passed things around. But it is not necessary anymore, unless I am missing something.

So should deprecate this as well.

I _could_ see a use as an object holding the iterator if we _do_ support chunksizing (e.g. kind of like the `TableIterator/TextReader` classes). But these are actually internal and not exposed (except thru the iteration itself).

What I mean is:

```
xls = pd.ExcelFile('path_to_file.xls')
data['Sheet1'] = pd.read_excel(xls, 'Sheet1', index_col=None, na_values=['NA'])
data['Sheet2'] = pd.read_excel(xls, 'Sheet2', index_col=1)
```

In the above, the `ExcelFile` is rather superfluous, and does not seem to add any value (you can just pass the string to both, which yields the same but is shorter). So if we want to deprecate `parse`, I would rather deprecate `ExcelFile` itself.

One thing that is possible with `Excelfile` is to inspect the sheet names. So that is a reason to keep it I think. But if we keep it, I don't really see a reason to deprecate its `parse` method. It's just like you also have both `read_hdf` as `HDFStore` (but I know, `HDFStore` has more extra functionality).

So right now `ExcelFile` does two useful things - first it exposes `sheet_names` (list of sheets in that file) which can be handy for interactive.

Second, because `xlrd` loads the whole worbook into memory (as far as I can tell) - there can be a performance benefit.

```
In [12]: df = pd.DataFrame({'a': np.arange(10000),
    ...:                    'b': np.arange(10000)})

In [13]: with pd.ExcelWriter('temp.xlsx') as f:
    ...:     df.to_excel(f, 'Sheet1')
    ...:     df.to_excel(f, 'Sheet2')

In [14]: %%time
    ...: with pd.ExcelFile('temp.xlsx') as f:
    ...:     pd.read_excel(f, 'Sheet1')
    ...:     pd.read_excel(f, 'Sheet2')
Wall time: 862 ms


In [16]: %%time
    ...: pd.read_excel('temp.xlsx', 'Sheet1')
    ...: pd.read_excel('temp.xlsx', 'Sheet2')
Wall time: 1.55 s
```

@chris-b1 oh, that is good 2 know (maybe add a note about that in the docs).

Ok, I do see some utility in `ExcelFile`. but `.parse` seems kind of 'internal' to me. Its superfluous. So we can deprecate to remove from the public API (though it doesn't hurt anything).

@jreback - expanded the `ExcelFile` docs to try and better clarify the purpose and mention the performance consideration.

I am still not fully convinced that deprecating `parse` is needed. OK, it does not have much added value, but given this already exists such a long time (and is explicitly included in the api.rst), it will only annoy users by removing it. And it is also not very costly to keep, since the one just calls the other. 

This is more subjective, but, when having such a `ExcelFile` object, it feels a bit more natural to do `ExcelFile.parse` than passing it to a function like  `pd.read_excel(ExcelFile)` (although `ExcelFile.read` have been better).

And for clarity, big +1 on the signature and doc changes!

ok, @chris-b1 why don't you back out the deprecation of `.parse`. I don't think its a big deal. 

Sure, not a problem.  Latest changes backs out the deprecation - I left the testing changes in (primarily using `read_excel` over `ExcelFile`) although did add back a couple calls to `ExcelFile.parse`.

some minor doc changes

@jreback - made those doc changes.  The travis failure seems to be unrelated?  Has to do with HTML formatting

yeh that failure happens once in a while, no idea why

@chris-b1 I was just thinking: to make it more clear in the docs that `ExcelFile.parse` is superfluous, we could eg also limit its docstring with a reference to `read_excel` (and then the template is not needed)

@jorisvandenbossche - sure makes sense to me, see update.

merged via https://github.com/pydata/pandas/commit/0d39ca1109fddc980e9e7640d7d8f9be852d5194

thanks!