code review: adding docs, references, minor formatting

Author: miccoli

doc/source/whatsnew/v0.24.0.txt

@@ -646,6 +646,7 @@ Datetimelike
 - Bug in :class:`DatetimeIndex` subtraction that incorrectly failed to raise ``OverflowError`` (:issue:`22492`, :issue:`22508`)
 - Bug in :class:`DatetimeIndex` incorrectly allowing indexing with ``Timedelta`` object (:issue:`20464`)
 - Bug in :class:`DatetimeIndex` where frequency was being set if original frequency was ``None`` (:issue:`22150`)
+- Bug in rounding methods of :class:`DatetimeIndex` (:meth:`~DatetimeIndex.round`, :meth:`~DatetimeIndex.ceil`, :meth:`~DatetimeIndex.floor`) and :class:`Timestamp` (:meth:`~Timestamp.round`, :meth:`~Timestamp.ceil`, :meth:`~Timestamp.floor`) could give raise to loss of precision (:issue:`22591`)
 
 Timedelta
 ^^^^^^^^^

pandas/_libs/tslibs/timestamps.pyx

@@ -60,6 +60,38 @@ cdef inline object create_timestamp_from_ts(int64_t value,
 
 @enum.unique
 class RoundTo(enum.Enum):
+    """
+    enumeration defining the available rounding modes
+
+    Attributes
+    ----------
+    MINUS_INFTY
+        round towards -∞, or floor [2]_
+    PLUS_INFTY
+        round towards +∞, or ceil [3]_
+    NEAREST_HALF_EVEN
+        round to nearest, tie-break half to even [6]_
+    NEAREST_HALF_MINUS_INFTY
+        round to nearest, tie-break half to -∞ [5]_
+    NEAREST_HALF_PLUS_INFTY
+        round to nearest, tie-break half to +∞ [4]_
+
+
+    References
+    ----------
+    .. [1] "Rounding - Wikipedia"
+           https://en.wikipedia.org/wiki/Rounding
+    .. [2] "Rounding down"
+           https://en.wikipedia.org/wiki/Rounding#Rounding_down
+    .. [3] "Rounding up"
+           https://en.wikipedia.org/wiki/Rounding#Rounding_up
+    .. [4] "Round half up"
+           https://en.wikipedia.org/wiki/Rounding#Round_half_up
+    .. [5] "Round half down"
+           https://en.wikipedia.org/wiki/Rounding#Round_half_down
+    .. [6] "Round half to even"
+           https://en.wikipedia.org/wiki/Rounding#Round_half_to_even
+    """
     MINUS_INFTY = 0
     PLUS_INFTY = 1
     NEAREST_HALF_EVEN = 2

pandas/tests/indexes/datetimes/test_scalar_compat.py

@@ -184,27 +184,30 @@ def test_ceil_floor_edge(self, test_input, rounder, freq, expected):
     def test_round_int64(self, start, index_freq, periods, rounding_freq):
         dt = DatetimeIndex(start=start, freq=index_freq, periods=periods)
         unit = to_offset(rounding_freq).nanos
+
         # test floor
-        result = dt.floor(rounding_freq).asi8
-        diff = dt.asi8 - result
-        mod = result % unit
+        result = dt.floor(rounding_freq)
+        diff = dt.asi8 - result.asi8
+        mod = result.asi8 % unit
         assert (mod == 0).all(), "floor not a %s multiple" % (rounding_freq, )
         assert (0 <= diff).all() and (diff < unit).all(), "floor error"
+
         # test ceil
-        result = dt.ceil(rounding_freq).asi8
-        diff = result - dt.asi8
-        mod = result % unit
+        result = dt.ceil(rounding_freq)
+        diff = result.asi8 - dt.asi8
+        mod = result.asi8 % unit
         assert (mod == 0).all(), "ceil not a %s multiple" % (rounding_freq, )
         assert (0 <= diff).all() and (diff < unit).all(), "ceil error"
+
         # test round
-        result = dt.round(rounding_freq).asi8
-        diff = abs(result - dt.asi8)
-        mod = result % unit
+        result = dt.round(rounding_freq)
+        diff = abs(result.asi8 - dt.asi8)
+        mod = result.asi8 % unit
         assert (mod == 0).all(), "round not a %s multiple" % (rounding_freq, )
         assert (diff <= unit // 2).all(), "round error"
         if unit % 2 == 0:
             assert (
-                result[diff == unit // 2] % 2 == 0
+                result.asi8[diff == unit // 2] % 2 == 0
             ).all(), "round half to even error"
 
     # ----------------------------------------------------------------

pandas/tests/scalar/timestamp/test_unary_ops.py

@@ -176,14 +176,17 @@ def test_round_int64(self, timestamp, freq):
         """
         dt = Timestamp(timestamp)
         unit = to_offset(freq).nanos
+
         # test floor
         result = dt.floor(freq)
         assert result.value % unit == 0, "floor not a %s multiple" % (freq, )
         assert 0 <= dt.value - result.value < unit, "floor error"
+
         # test ceil
         result = dt.ceil(freq)
         assert result.value % unit == 0, "ceil not a %s multiple" % (freq, )
         assert 0 <= result.value - dt.value < unit, "ceil error"
+
         # test round
         result = dt.round(freq)
         assert result.value % unit == 0, "round not a %s multiple" % (freq, )