DEPR: Deprecate PeriodIndex.to_datetime.

Deprecation is in favour of PeriodIndex.to_timestamp.

Author: gfyoung

doc/source/whatsnew/v0.19.0.txt

@@ -1061,6 +1061,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`)
 
+- ``PeriodIndex.to_datetime`` has been deprecated in favour of ``PeriodIndex.to_timestamp`` (:issue:`8254`)
 - ``Timestamp.to_datetime`` has been deprecated in favour of ``Timestamp.to_pydatetime`` (:issue:`8254`)
 - ``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`)

pandas/tests/frame/test_to_csv.py

@@ -294,7 +294,7 @@ def _to_uni(x):
                         list(map(Timestamp, to_datetime(recons.index))),
                         dtype=r_dtype)
                     df.index = np.array(
-                        list(map(Timestamp, df.index.to_datetime())),
+                        list(map(Timestamp, df.index.to_timestamp())),
                         dtype=r_dtype)
                 else:
                     r_dtype = type_map.get(r_dtype)
@@ -319,7 +319,7 @@ def _to_uni(x):
                         lmap(Timestamp, to_datetime(recons.columns)),
                         dtype=c_dtype)
                     df.columns = np.array(
-                        lmap(Timestamp, df.columns.to_datetime()),
+                        lmap(Timestamp, df.columns.to_timestamp()),
                         dtype=c_dtype)
                 else:
                     c_dtype = type_map.get(c_dtype)

pandas/tseries/period.py

@@ -1,6 +1,7 @@
 # pylint: disable=E1101,E1103,W0232
 from datetime import datetime, timedelta
 import numpy as np
+import warnings
 
 
 from pandas.core import common as com
@@ -550,6 +551,13 @@ def asfreq(self, freq=None, how='E'):
         return self._simple_new(new_data, self.name, freq=freq)
 
     def to_datetime(self, dayfirst=False):
+        """
+        DEPRECATED: use :meth:`to_timestamp` instead.
+
+        Cast to DatetimeIndex.
+        """
+        warnings.warn("to_datetime is deprecated. Use self.to_timestamp(...)",
+                      FutureWarning, stacklevel=2)
         return self.to_timestamp()
 
     year = _field_accessor('year', 0, "The year of the period")

pandas/tseries/tests/test_period.py

@@ -3560,12 +3560,20 @@ def test_with_multi_index(self):
 
         tm.assertIsInstance(s.index.values[0][0], Period)
 
-    def test_to_datetime_1703(self):
+    def test_to_timestamp_1703(self):
         index = period_range('1/1/2012', periods=4, freq='D')
 
-        result = index.to_datetime()
+        result = index.to_timestamp()
         self.assertEqual(result[0], Timestamp('1/1/2012'))
 
+    def test_to_datetime_depr(self):
+        index = period_range('1/1/2012', periods=4, freq='D')
+
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            result = index.to_datetime()
+            self.assertEqual(result[0], Timestamp('1/1/2012'))
+
     def test_get_loc_msg(self):
         idx = period_range('2000-1-1', freq='A', periods=10)
         bad_period = Period('2012', 'A')