DEPR: Deprecate Timestamp.to_datetime

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`)
 
+- ``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`)
 - ``DataFrame.to_html()`` and ``DataFrame.to_latex()`` have dropped the ``colSpace`` parameter in favor of ``col_space`` (:issue:`13857`)

pandas/io/tests/json/test_pandas.py

@@ -908,17 +908,17 @@ def test_tz_is_utc(self):
 
         ts = Timestamp('2013-01-10 05:00:00Z')
         self.assertEqual(exp, pd.json.dumps(ts, iso_dates=True))
-        dt = ts.to_datetime()
+        dt = ts.to_pydatetime()
         self.assertEqual(exp, pd.json.dumps(dt, iso_dates=True))
 
         ts = Timestamp('2013-01-10 00:00:00', tz='US/Eastern')
         self.assertEqual(exp, pd.json.dumps(ts, iso_dates=True))
-        dt = ts.to_datetime()
+        dt = ts.to_pydatetime()
         self.assertEqual(exp, pd.json.dumps(dt, iso_dates=True))
 
         ts = Timestamp('2013-01-10 00:00:00-0500')
         self.assertEqual(exp, pd.json.dumps(ts, iso_dates=True))
-        dt = ts.to_datetime()
+        dt = ts.to_pydatetime()
         self.assertEqual(exp, pd.json.dumps(dt, iso_dates=True))
 
     def test_tz_range_is_utc(self):

pandas/tests/indexes/test_base.py

@@ -502,7 +502,7 @@ def test_asof(self):
         d = self.dateIndex[-1]
         self.assertEqual(self.dateIndex.asof(d + timedelta(1)), d)
 
-        d = self.dateIndex[0].to_datetime()
+        d = self.dateIndex[0].to_pydatetime()
         tm.assertIsInstance(self.dateIndex.asof(d), Timestamp)
 
     def test_asof_datetime_partial(self):

pandas/tests/test_groupby.py

@@ -779,7 +779,7 @@ def test_get_group(self):
         g = df.groupby('DATE')
         key = list(g.groups)[0]
         result1 = g.get_group(key)
-        result2 = g.get_group(Timestamp(key).to_datetime())
+        result2 = g.get_group(Timestamp(key).to_pydatetime())
         result3 = g.get_group(str(Timestamp(key)))
         assert_frame_equal(result1, result2)
         assert_frame_equal(result1, result3)
@@ -788,7 +788,7 @@ def test_get_group(self):
 
         key = list(g.groups)[0]
         result1 = g.get_group(key)
-        result2 = g.get_group((Timestamp(key[0]).to_datetime(), key[1]))
+        result2 = g.get_group((Timestamp(key[0]).to_pydatetime(), key[1]))
         result3 = g.get_group((str(Timestamp(key[0])), key[1]))
         assert_frame_equal(result1, result2)
         assert_frame_equal(result1, result3)

pandas/tseries/tests/test_base.py

@@ -1127,11 +1127,11 @@ def test_subtraction_ops_with_tz(self):
         # check that dt/dti subtraction ops with tz are validated
         dti = date_range('20130101', periods=3)
         ts = Timestamp('20130101')
-        dt = ts.to_datetime()
+        dt = ts.to_pydatetime()
         dti_tz = date_range('20130101', periods=3).tz_localize('US/Eastern')
         ts_tz = Timestamp('20130101').tz_localize('US/Eastern')
         ts_tz2 = Timestamp('20130101').tz_localize('CET')
-        dt_tz = ts_tz.to_datetime()
+        dt_tz = ts_tz.to_pydatetime()
         td = Timedelta('1 days')
 
         def _check(result, expected):

pandas/tseries/tests/test_timezones.py

@@ -169,7 +169,7 @@ def test_timestamp_to_datetime_tzoffset(self):
         from dateutil.tz import tzoffset
         tzinfo = tzoffset(None, 7200)
         expected = Timestamp('3/11/2012 04:00', tz=tzinfo)
-        result = Timestamp(expected.to_datetime())
+        result = Timestamp(expected.to_pydatetime())
         self.assertEqual(expected, result)
 
     def test_timedelta_push_over_dst_boundary(self):

pandas/tseries/tests/test_tslib.py

@@ -616,6 +616,16 @@ def test_pprint(self):
  'foo': 1}"""
         self.assertEqual(result, expected)
 
+    def to_datetime_depr(self):
+        # see gh-8254
+        ts = Timestamp('2011-01-01')
+
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            expected = datetime.datetime(2011, 1, 1)
+            result = ts.to_datetime()
+            self.assertEqual(result, expected)
+
 
 class TestDatetimeParsingWrappers(tm.TestCase):
     def test_does_not_convert_mixed_integer(self):

pandas/tslib.pyx

@@ -1,5 +1,7 @@
 # cython: profile=False
 
+import warnings
+
 cimport numpy as np
 from numpy cimport (int8_t, int32_t, int64_t, import_array, ndarray,
                     NPY_INT64, NPY_DATETIME, NPY_TIMEDELTA)
@@ -637,22 +639,6 @@ class Timestamp(_Timestamp):
         return Timestamp(datetime.replace(self, **kwds),
                          freq=self.freq)
 
-    def to_pydatetime(self, warn=True):
-        """
-        If warn=True, issue warning if nanoseconds is nonzero
-        """
-        cdef:
-            pandas_datetimestruct dts
-            _TSObject ts
-
-        if self.nanosecond != 0 and warn:
-            print 'Warning: discarding nonzero nanoseconds'
-        ts = convert_to_tsobject(self, self.tzinfo, None, 0, 0)
-
-        return datetime(ts.dts.year, ts.dts.month, ts.dts.day,
-                        ts.dts.hour, ts.dts.min, ts.dts.sec,
-                        ts.dts.us, ts.tzinfo)
-
     def isoformat(self, sep='T'):
         base = super(_Timestamp, self).isoformat(sep=sep)
         if self.nanosecond == 0:
@@ -986,7 +972,7 @@ cdef class _Timestamp(datetime):
             ots = other
         elif isinstance(other, datetime):
             if self.nanosecond == 0:
-                val = self.to_datetime()
+                val = self.to_pydatetime()
                 return PyObject_RichCompareBool(val, other, op)
 
             try:
@@ -1048,7 +1034,7 @@ cdef class _Timestamp(datetime):
 
     cdef bint _compare_outside_nanorange(_Timestamp self, datetime other,
                                          int op) except -1:
-        cdef datetime dtval = self.to_datetime()
+        cdef datetime dtval = self.to_pydatetime(warn=False)
 
         self._assert_tzawareness_compat(other)
 
@@ -1078,9 +1064,27 @@ cdef class _Timestamp(datetime):
             raise TypeError('Cannot compare tz-naive and tz-aware timestamps')
 
     cpdef datetime to_datetime(_Timestamp self):
+        """
+        DEPRECATED: use :meth:`to_pydatetime` instead.
+
+        Convert a Timestamp object to a native Python datetime object.
+        """
+        warnings.warn("to_datetime is deprecated. Use self.to_pydatetime()",
+                      FutureWarning, stacklevel=2)
+        return self.to_pydatetime(warn=False)
+
+    cpdef datetime to_pydatetime(_Timestamp self, warn=True):
+        """
+        Convert a Timestamp object to a native Python datetime object.
+
+        If warn=True, issue a warning if nanoseconds is nonzero.
+        """
         cdef:
             pandas_datetimestruct dts
             _TSObject ts
+
+        if self.nanosecond != 0 and warn:
+            print 'Warning: discarding nonzero nanoseconds'
         ts = convert_to_tsobject(self, self.tzinfo, None, 0, 0)
         dts = ts.dts
         return datetime(dts.year, dts.month, dts.day,