TST: provide warning when using ExcelWriter/ExcelObject if from deprecated path

DOC: minor edits in 0.11.1

DOC: cookbook/io.rst doc updates

TST: py3 issue on catching test warnings in test_parser_deprecated

Author: jreback

doc/source/cookbook.rst

@@ -32,25 +32,25 @@ Selection
 
 The :ref:`indexing <indexing>` docs.
 
-`Boolean Rows Indexing
+Indexing using both row labels and conditionals, see
+`here
 <http://stackoverflow.com/questions/14725068/pandas-using-row-labels-in-boolean-indexing>`__
-    Indexing using both row labels and conditionals
 
-`Using loc and iloc in selections
+Use loc for label-oriented slicing and iloc positional slicing, see
+`here
 <https://github.com/pydata/pandas/issues/2904>`__
-    Use loc for label-oriented slicing and iloc positional slicing
 
-`Extending a panel along the minor axis
+Extend a panel frame by transposing, adding a new dimension, and transposing back to the original dimensions, see
+`here
 <http://stackoverflow.com/questions/15364050/extending-a-pandas-panel-frame-along-the-minor-axis>`__
-    Extend a panel frame by transposing, adding a new dimension, and transposing back to the original dimensions
 
-`Boolean masking in a panel
+Mask a panel by using ``np.where`` and then reconstructing the panel with the new masked values
+`here
 <http://stackoverflow.com/questions/14650341/boolean-mask-in-pandas-panel>`__
-    Mask a panel by using ``np.where`` and then reconstructing the panel with the new masked values
 
-`Selecting via the complement
+Using ``~`` to take the complement of a boolean array, see
+`here
 <http://stackoverflow.com/questions/14986510/picking-out-elements-based-on-complement-of-indices-in-python-pandas>`__
-    ``~`` can be used to take the complement of a boolean array
 
 `Efficiently creating columns using applymap
 <http://stackoverflow.com/questions/16575868/efficiently-creating-additional-columns-in-a-pandas-dataframe-using-map>`__

doc/source/io.rst

@@ -989,9 +989,22 @@ module and use the same parsing code as the above to convert tabular data into
 a DataFrame. See the :ref:`cookbook<cookbook.excel>` for some
 advanced strategies
 
-.. code-block:: python
+.. note::
+
+   The prior method of accessing Excel is now deprecated as of 0.11.1,
+   this will work but will be removed in a future version.
+
+      .. code-block:: python
+
+         from pandas.io.parsers import ExcelFile
+         xls = ExcelFile('path_to_file.xls')
+         xls.parse('Sheet1', index_col=None, na_values=['NA'])
+
+   Replaced by 
+
+     .. code-block:: python
 
-   read_excel('path_to_file.xls', 'Sheet1', index_col=None, na_values=['NA'])
+        read_excel('path_to_file.xls', 'Sheet1', index_col=None, na_values=['NA'])
 
 To read sheets from an Excel 2007 file, you can pass a filename with a ``.xlsx``
 extension, in which case the ``openpyxl`` module will be used to read the file.

doc/source/v0.11.1.txt

@@ -90,18 +90,20 @@ API changes
   - IO api
 
     - added top-level function ``read_excel`` to replace the following,
-      however, the original API remains as well
+      The original API is deprecated and will be removed in a future version
 
       .. code-block:: python
 
+         from pandas.io.parsers import ExcelFile
          xls = ExcelFile('path_to_file.xls')
          xls.parse('Sheet1', index_col=None, na_values=['NA'])
 
       With
 
       .. code-block:: python
 
-         read_excel('path_to_file.xls', 'Sheet1', index_col=None, na_values=['NA'])
+         import pandas as pd
+         pd.read_excel('path_to_file.xls', 'Sheet1', index_col=None, na_values=['NA'])
 
     - added top-level function ``read_sql`` that is equivalent to the following
 

pandas/io/parsers.py

@@ -1979,3 +1979,19 @@ def __init__(self, f, **kwds):
 
     def _make_reader(self, f):
         self.data = FixedWidthReader(f, self.colspecs, self.delimiter)
+
+
+from pandas.io import excel
+class ExcelWriter(excel.ExcelWriter):
+    def __init__(self, path):
+        from warnings import warn
+        warn("ExcelWriter can now be imported from: pandas.io.excel", FutureWarning)
+        super(ExcelWriter, self).__init__(path)
+
+class ExcelFile(excel.ExcelFile):
+    def __init__(self, path_or_buf, kind=None, **kwds):
+        from warnings import warn
+        warn("ExcelFile can now be imported from: pandas.io.excel", FutureWarning)
+        super(ExcelFile, self).__init__(path_or_buf, kind=kind, **kwds)
+
+  

pandas/io/tests/test_excel.py

@@ -854,6 +854,23 @@ def roundtrip(df, header=True, parser_hdr=0):
         self.assertEqual(res.shape, (1, 2))
         self.assertTrue(res.ix[0, 0] is not np.nan)
 
+    def test_deprecated_from_parsers(self):
+
+        # since 0.11.1 changed the import path
+        import warnings
+
+        with warnings.catch_warnings() as w:
+            warnings.filterwarnings(action='ignore', category=FutureWarning)
+
+            _skip_if_no_xlrd()
+            from pandas.io.parsers import ExcelFile as xf
+            xf(self.xls1)
+
+            _skip_if_no_xlwt()
+            with ensure_clean('test.xls') as path:
+                from pandas.io.parsers import ExcelWriter as xw
+                xw(path)
+
 if __name__ == '__main__':
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],
                    exit=False)