CLN: added io.api for i/o importing functions

[jreback]

closes most of #3411 (all except the deprecation of from_csv)

• moved excel functionaility out of io.parsers to io.excel
  added read_excel top-level function
  aliases from pandas.io.excel
• added read_stata top-level function, to_stata DataFrame method
  aliases from pandas.io.stata
  removed read_dta (replace by read_stata)
• added read_sql top-level function, to_sql DataFrame method
  aliases from pandas.io.sql

DOC: doc updates for all the above and intro section to io.rst

[jreback]

@wesm pls give this a once over

[jreback]

@y-p @wesm ok on this?

[ghost]

IIRC, users rely on ExcelWriter directly to write mutliple tabs to the same file,
these changes would break (at least) that, no?

[jreback]

nope...its still there (and still exported by default)

[ghost]

I must be missing something, how is this not a breaking change?

In [1]: from pandas.io.parsers import ExcelWriter

In [2]: from pandas.io.parsers import ExcelFile

In [3]: pd.__version__
Out[3]: '1.11.0.dev-6d08f1e'

(Note, I just pushed a change to master turning 0.12.0->0.11.1)

This PR:

In [1]: from pandas.io.parsers import ExcelFile
---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
<ipython-input-1-a9154a289dc3> in <module>()
----> 1 from pandas.io.parsers import ExcelFile

ImportError: cannot import name ExcelFile

In [2]: from pandas.io.parsers import ExcelWriter
---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
<ipython-input-2-39a586c0fd73> in <module>()
----> 1 from pandas.io.parsers import ExcelWriter

ImportError: cannot import name ExcelWriter

In [3]: pd.__version__
Out[3]: '0.12.0.dev-f7ad3c3'

[jreback]

yes, that is an API change, let me see if I can do a warning on that, or let it break?

in any event, the top-level namespace

import pandas as pd
pd.ExcelWriter

succeeds

[jreback]

I updated to give a warning if you try to use an ExcelWriter/ExcelObject imported from pandas.io.parsers

do you know if its possible to do this on import though?

e.g.

from pandas.io.parsers import ExcelWriter
ExcelWriter('foo.xls')

the warning won't print till the ExcelWriter line; any way to actually have it warn on that particular import?
some kind of import hook?

[ghost]

Scratch that, Obviously everyone will get the object from the toplevel namespace.

[jreback]

actually, I think you have a valid point (as the docs did originally have you import from pandas.io.parsers)

[ghost]

If you think so, then this doesn't belong in a minor release.
The semver contract is "if you upgrade a minor release, your code won't break", not "you'll get a warning".

Other then that, a welcome cleanup of an increasingly crowded space.

[jreback]

ahh...but I have made that so, you WILL get a warning (and your code wont' break)

ok....will proceed then...

[jreback]

@wesm any comments?