DEPR: Deprecated Index.to_datetime (#14096)

Partially addresses gh-8254.
Closes gh-8612 because pd.to_datetime has a format arg.

Author: gfyoung

doc/source/whatsnew/v0.19.0.txt

@@ -1031,6 +1031,7 @@ Deprecations
 - ``Categorical.reshape`` has been deprecated and will be removed in a subsequent release (:issue:`12882`)
 - ``Series.reshape`` has been deprecated and will be removed in a subsequent release (:issue:`12882`)
 
+- ``Index.to_datetime`` and ``DatetimeIndex.to_datetime`` have been deprecated in favour of ``pd.to_datetime`` (:issue:`8254`)
 - ``SparseList`` has been deprecated and will be removed in a future version (:issue:`13784`)
 - ``DataFrame.to_html()`` and ``DataFrame.to_latex()`` have dropped the ``colSpace`` parameter in favor of ``col_space`` (:issue:`13857`)
 - ``DataFrame.to_sql()`` has deprecated the ``flavor`` parameter, as it is superfluous when SQLAlchemy is not installed (:issue:`13611`)

pandas/indexes/base.py

@@ -851,9 +851,14 @@ def _to_safe_for_reshape(self):
 
     def to_datetime(self, dayfirst=False):
         """
+        DEPRECATED: use :meth:`pandas.to_datetime` instead.
+
         For an Index containing strings or datetime.datetime objects, attempt
         conversion to DatetimeIndex
         """
+        warnings.warn("to_datetime is deprecated. Use pd.to_datetime(...)",
+                      FutureWarning, stacklevel=2)
+
         from pandas.tseries.index import DatetimeIndex
         if self.inferred_type == 'string':
             from dateutil.parser import parse

pandas/io/tests/parser/parse_dates.py

@@ -20,8 +20,7 @@
 
 from pandas import DataFrame, Series, Index, DatetimeIndex
 from pandas import compat
-from pandas.compat import(parse_date, StringIO,
-                          lrange, lmap)
+from pandas.compat import parse_date, StringIO, lrange
 from pandas.tseries.index import date_range
 
 
@@ -291,33 +290,18 @@ def test_yy_format_with_yearfirst(self):
         tm.assert_frame_equal(rs, xp)
 
     def test_parse_dates_column_list(self):
-        from pandas.core.datetools import to_datetime
-
-        data = '''date;destination;ventilationcode;unitcode;units;aux_date
-01/01/2010;P;P;50;1;12/1/2011
-01/01/2010;P;R;50;1;13/1/2011
-15/01/2010;P;P;50;1;14/1/2011
-01/05/2010;P;P;50;1;15/1/2011'''
-
-        expected = self.read_csv(StringIO(data), sep=";", index_col=lrange(4))
-
-        lev = expected.index.levels[0]
-        levels = list(expected.index.levels)
-        levels[0] = lev.to_datetime(dayfirst=True)
-        # hack to get this to work - remove for final test
-        levels[0].name = lev.name
-        expected.index.set_levels(levels, inplace=True)
-        expected['aux_date'] = to_datetime(expected['aux_date'],
-                                           dayfirst=True)
-        expected['aux_date'] = lmap(Timestamp, expected['aux_date'])
-        tm.assertIsInstance(expected['aux_date'][0], datetime)
-
-        df = self.read_csv(StringIO(data), sep=";", index_col=lrange(4),
-                           parse_dates=[0, 5], dayfirst=True)
+        data = 'a,b,c\n01/01/2010,1,15/02/2010'
+
+        expected = DataFrame({'a': [datetime(2010, 1, 1)], 'b': [1],
+                              'c': [datetime(2010, 2, 15)]})
+        expected = expected.set_index(['a', 'b'])
+
+        df = self.read_csv(StringIO(data), index_col=[0, 1],
+                           parse_dates=[0, 2], dayfirst=True)
         tm.assert_frame_equal(df, expected)
 
-        df = self.read_csv(StringIO(data), sep=";", index_col=lrange(4),
-                           parse_dates=['date', 'aux_date'], dayfirst=True)
+        df = self.read_csv(StringIO(data), index_col=[0, 1],
+                           parse_dates=['a', 'c'], dayfirst=True)
         tm.assert_frame_equal(df, expected)
 
     def test_multi_index_parse_dates(self):

pandas/tseries/tests/test_timeseries.py

@@ -2535,15 +2535,19 @@ def test_unit_mixed(self):
     def test_index_to_datetime(self):
         idx = Index(['1/1/2000', '1/2/2000', '1/3/2000'])
 
-        result = idx.to_datetime()
-        expected = DatetimeIndex(datetools.to_datetime(idx.values))
-        tm.assert_index_equal(result, expected)
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            result = idx.to_datetime()
+            expected = DatetimeIndex(datetools.to_datetime(idx.values))
+            tm.assert_index_equal(result, expected)
 
-        today = datetime.today()
-        idx = Index([today], dtype=object)
-        result = idx.to_datetime()
-        expected = DatetimeIndex([today])
-        tm.assert_index_equal(result, expected)
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            today = datetime.today()
+            idx = Index([today], dtype=object)
+            result = idx.to_datetime()
+            expected = DatetimeIndex([today])
+            tm.assert_index_equal(result, expected)
 
     def test_dataframe(self):