DEPR: Deprecate Timestamp.to_datetime (#14101)

* DEPR: Deprecate Timestamp.to_datetime * API: Issue real warning in to_pydatetime * DEPR: Deprecate NaT.to_datetime Closes gh-8254.

Author: gfyoung

doc/source/whatsnew/v0.19.0.txt

@@ -436,6 +436,7 @@ API changes
 ~~~~~~~~~~~
 
 
+- ``Timestamp.to_pydatetime`` will issue a ``UserWarning`` when ``warn=True``, and the instance has a non-zero number of nanoseconds (:issue:`14101`)
 - ``Panel.to_sparse`` will raise a ``NotImplementedError`` exception when called (:issue:`13778`)
 - ``Index.reshape`` will raise a ``NotImplementedError`` exception when called (:issue:`12882`)
 - Non-convertible dates in an excel date column will be returned without conversion and the column will be ``object`` dtype, rather than raising an exception (:issue:`10001`)
@@ -1060,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`)
 
+- ``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_offsets.py

@@ -261,8 +261,19 @@ def _check_offsetfunc_works(self, offset, funcname, dt, expected,
  self.assertTrue(isinstance(result, Timestamp))
  self.assertEqual(result, expected)
 
- # test nano second is preserved
- result = func(Timestamp(dt) + Nano(5))
+ # see gh-14101
+ exp_warning = None
+ ts = Timestamp(dt) + Nano(5)
+
+ if (offset_s.__class__.__name__ == 'DateOffset' and
+ (funcname == 'apply' or normalize) and
+ ts.nanosecond > 0):
+ exp_warning = UserWarning
+
+ # test nanosecond is preserved
+ with tm.assert_produces_warning(exp_warning,
+ check_stacklevel=False):
+ result = func(ts)
  self.assertTrue(isinstance(result, Timestamp))
  if normalize is False:
  self.assertEqual(result, expected + Nano(5))
@@ -289,8 +300,19 @@ def _check_offsetfunc_works(self, offset, funcname, dt, expected,
  self.assertTrue(isinstance(result, Timestamp))
  self.assertEqual(result, expected_localize)
 
- # test nano second is preserved
- result = func(Timestamp(dt, tz=tz) + Nano(5))
+ # see gh-14101
+ exp_warning = None
+ ts = Timestamp(dt, tz=tz) + Nano(5)
+
+ if (offset_s.__class__.__name__ == 'DateOffset' and
+ (funcname == 'apply' or normalize) and
+ ts.nanosecond > 0):
+ exp_warning = UserWarning
+
+ # test nanosecond is preserved
+ with tm.assert_produces_warning(exp_warning,
+ check_stacklevel=False):
+ result = func(ts)
  self.assertTrue(isinstance(result, Timestamp))
  if normalize is False:
  self.assertEqual(result, expected_localize + Nano(5))

pandas/tseries/tests/test_timeseries.py

@@ -1020,7 +1020,13 @@ def test_NaT_methods(self):
 
  for method in nat_methods:
  if hasattr(NaT, method):
- self.assertIs(getattr(NaT, method)(), NaT)
+ # see gh-8254
+ exp_warning = None
+ if method == 'to_datetime':
+ exp_warning = FutureWarning
+ with tm.assert_produces_warning(
+ exp_warning, check_stacklevel=False):
+ self.assertIs(getattr(NaT, method)(), NaT)
 
  # GH 12300
  self.assertEqual(NaT.isoformat(), 'NaT')

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

@@ -47,12 +47,17 @@ def test_max_valid(self):
  def test_to_datetime_bijective(self):
  # Ensure that converting to datetime and back only loses precision
  # by going from nanoseconds to microseconds.
- self.assertEqual(
- Timestamp(Timestamp.max.to_pydatetime()).value / 1000,
- Timestamp.max.value / 1000)
- self.assertEqual(
- Timestamp(Timestamp.min.to_pydatetime()).value / 1000,
- Timestamp.min.value / 1000)
+ exp_warning = None if Timestamp.max.nanosecond == 0 else UserWarning
+ with tm.assert_produces_warning(exp_warning, check_stacklevel=False):
+ self.assertEqual(
+ Timestamp(Timestamp.max.to_pydatetime()).value / 1000,
+ Timestamp.max.value / 1000)
+
+ exp_warning = None if Timestamp.min.nanosecond == 0 else UserWarning
+ with tm.assert_produces_warning(exp_warning, check_stacklevel=False):
+ self.assertEqual(
+ Timestamp(Timestamp.min.to_pydatetime()).value / 1000,
+ Timestamp.min.value / 1000)
 
 
 class TestTimestamp(tm.TestCase):
@@ -616,6 +621,26 @@ 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)
+
+ def to_pydatetime_nonzero_nano(self):
+ ts = Timestamp('2011-01-01 9:00:00.123456789')
+
+ # Warn the user of data loss (nanoseconds).
+ with tm.assert_produces_warning(UserWarning,
+ check_stacklevel=False):
+ expected = datetime.datetime(2011, 1, 1, 9, 0, 0, 123456)
+ result = ts.to_pydatetime()
+ 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:
@@ -805,11 +791,11 @@ def _make_nan_func(func_name):
  f.__name__ = func_name
  return f
 
-_nat_methods = ['date', 'now', 'replace', 'to_datetime', 'today']
+_nat_methods = ['date', 'now', 'replace', 'to_pydatetime', 'today']
 
 _nan_methods = ['weekday', 'isoweekday', 'total_seconds']
 
-_implemented_methods = ['to_datetime64', 'isoformat']
+_implemented_methods = ['to_datetime', 'to_datetime64', 'isoformat']
 _implemented_methods.extend(_nat_methods)
 _implemented_methods.extend(_nan_methods)
 
@@ -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()
 
  self._assert_tzawareness_compat(other)
 
@@ -1078,9 +1064,28 @@ 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:
+ warnings.warn("Discarding nonzero nanoseconds in conversion",
+ UserWarning, stacklevel=2)
  ts = convert_to_tsobject(self, self.tzinfo, None, 0, 0)
  dts = ts.dts
  return datetime(dts.year, dts.month, dts.day,