Added doc strings and to_numpy for NaT

Author: Chris Bertinato

doc/source/whatsnew/v0.24.2.rst

@@ -15,12 +15,6 @@ Whats New in 0.24.2 (February XX, 2019)
 These are the changes in pandas 0.24.2. See :ref:`release` for a full changelog
 including other versions of pandas.
 
-.. _whatsnew_0242.api:
-
-API Changes
-~~~~~~~~~~~
-- ``Timestamp`` and ``Timedelta`` scalars now implement the :meth:`to_numpy` method as aliases to :meth:`Timestamp.to_datetime64` and :meth:`Timedelta.to_timedelta64`, respectively.
-
 .. _whatsnew_0242.regressions:
 
 Fixed Regressions

doc/source/whatsnew/v0.25.0.rst

@@ -33,7 +33,8 @@ Backwards incompatible API changes
 Other API Changes
 ^^^^^^^^^^^^^^^^^
 
--
+- ``Timestamp`` and ``Timedelta`` scalars now implement the :meth:`to_numpy` method as aliases to :meth:`Timestamp.to_datetime64` and :meth:`Timedelta.to_timedelta64`, respectively.
+
 -
 -
 

pandas/_libs/tslibs/nattype.pyx

@@ -186,6 +186,22 @@ cdef class _NaT(datetime):
         """ Returns a numpy.datetime64 object with 'ns' precision """
         return np.datetime64('NaT', 'ns')
 
+    def to_numpy(self, dtype=None, copy=False):
+        """
+        Convert NaT to a NumPy datetime64 NaT.
+
+        .. versionadded:: 0.25.0
+
+        This is an alias method for `NaT.to_datetime64()`. The dtype and
+        copy parameters are available here only for compatibility. Their values
+        will not affect the return value.
+
+        Returns
+        -------
+        numpy.datetime64('NaT')
+        """
+        return self.to_datetime64()
+
     def __repr__(self):
         return 'NaT'
 

pandas/_libs/tslibs/timedeltas.pyx

@@ -825,7 +825,23 @@ cdef class _Timedelta(timedelta):
         return np.timedelta64(self.value, 'ns')
 
     def to_numpy(self, dtype=None, copy=False):
-        """ Alias to to_timedelta64 for Timedelta scalars """
+        """
+        Convert the Timestamp to a NumPy timedelta64.
+
+        .. versionadded:: 0.25.0
+
+        This is an alias method for `Timedelta.to_timedelta64()`. The dtype and
+        copy parameters are available here only for compatibility. Their values
+        will not affect the return value.
+
+        Returns
+        -------
+        numpy.timedelta64
+
+        See Also
+        --------
+        Series.to_numpy : Similar method for Series.
+        """
         return self.to_timedelta64()
 
     def total_seconds(self):

pandas/_libs/tslibs/timestamps.pyx

@@ -344,7 +344,23 @@ cdef class _Timestamp(datetime):
         return np.datetime64(self.value, 'ns')
 
     def to_numpy(self, dtype=None, copy=False):
-        """ Alias to to_datetime64 for Timestamp scalars """
+        """
+        Convert the Timestamp to a NumPy datetime64.
+
+        .. versionadded:: 0.25.0
+
+        This is an alias method for `Timestamp.to_datetime64()`. The dtype and
+        copy parameters are available here only for compatibility. Their values
+        will not affect the return value.
+
+        Returns
+        -------
+        numpy.datetime64
+
+        See Also
+        --------
+        DatetimeIndex.to_numpy : Similar method for DatetimeIndex.
+        """
         return self.to_datetime64()
 
     def __add__(self, other):

pandas/tests/arithmetic/test_datetime64.py

@@ -2336,9 +2336,3 @@ def test_shift_months(years, months):
            for x in dti]
     expected = DatetimeIndex(raw)
     tm.assert_index_equal(actual, expected)
-
-
-def test_to_numpy_alias():
-    # GH 24653: alias .to_numpy() for scalars
-    ts = pd.Timestamp(datetime.now())
-    assert ts.to_datetime64() == ts.to_numpy()

pandas/tests/arithmetic/test_timedelta64.py

@@ -1975,9 +1975,3 @@ def test_td64arr_pow_invalid(self, scalar_td, box_with_array):
 
         with pytest.raises(TypeError, match=pattern):
             td1 ** scalar_td
-
-
-def test_to_numpy_alias():
-    # GH 24653: alias .to_numpy() for scalars
-    td = Timedelta('10m7s')
-    assert td.to_timedelta64() == td.to_numpy()

pandas/tests/scalar/test_nat.py

@@ -141,10 +141,9 @@ def test_nat_iso_format(get_nat):
 
 
 @pytest.mark.parametrize("klass,expected", [
-    (Timestamp, ["freqstr", "normalize", "to_julian_date", "to_numpy",
-                 "to_period", "tz"]),
-    (Timedelta, ["components", "delta", "is_populated", "to_numpy",
-                 "to_pytimedelta", "to_timedelta64", "view"])
+    (Timestamp, ["freqstr", "normalize", "to_julian_date", "to_period", "tz"]),
+    (Timedelta, ["components", "delta", "is_populated", "to_pytimedelta",
+                 "to_timedelta64", "view"])
 ])
 def test_missing_public_nat_methods(klass, expected):
     # see gh-17327

pandas/tests/scalar/timedelta/test_timedelta.py

@@ -394,6 +394,11 @@ def test_timedelta_conversions(self):
         assert (Timedelta(timedelta(days=1)) ==
                 np.timedelta64(1, 'D').astype('m8[ns]'))
 
+    def test_to_numpy_alias(self):
+        # GH 24653: alias .to_numpy() for scalars
+        td = Timedelta('10m7s')
+        assert td.to_timedelta64() == td.to_numpy()
+
     def test_round(self):
 
         t1 = Timedelta('1 days 02:34:56.789123456')

pandas/tests/scalar/timestamp/test_timestamp.py

@@ -962,3 +962,8 @@ def test_to_period_tz_warning(self):
         with tm.assert_produces_warning(UserWarning):
             # warning that timezone info will be lost
             ts.to_period('D')
+
+    def test_to_numpy_alias(self):
+        # GH 24653: alias .to_numpy() for scalars
+        ts = Timestamp(datetime.now())
+        assert ts.to_datetime64() == ts.to_numpy()