Improve doc strings, also indexer_at/between/_time

Author: tp

doc/source/whatsnew/v0.23.0.txt

@@ -810,6 +810,10 @@ Datetimelike API Changes
 - :class:`CacheableOffset` and :class:`WeekDay` are no longer available in the ``pandas.tseries.offsets`` module (:issue:`17830`)
 - ``pandas.tseries.frequencies.get_freq_group()`` and ``pandas.tseries.frequencies.DAYS`` are removed from the public API (:issue:`18034`)
 - :func:`Series.truncate` and :func:`DataFrame.truncate` will raise a ``ValueError`` if the index is not sorted instead of an unhelpful ``KeyError`` (:issue:`17935`)
+- :attr:`Series.at_time` and :attr:`DataFrame.at_time` will now raise a ``TypeError``
+  rather than ``NotImplementedError`` when index is not a :class:`DatetimeIndex``.
+- :attr:`Series.between_time` and :attr:`DateFrame.between_time` will now raise
+  a ``TypeError`` rather than ``NotImplementedError`` when index is not a :class:`DatetimeIndex``.
 - Restricted ``DateOffset`` keyword arguments. Previously, ``DateOffset`` subclasses allowed arbitrary keyword arguments which could lead to unexpected behavior. Now, only valid arguments will be accepted. (:issue:`17176`, :issue:`18226`).
 - :func:`pandas.merge` provides a more informative error message when trying to merge on timezone-aware and timezone-naive columns (:issue:`15800`)
 - For :class:`DatetimeIndex` and :class:`TimedeltaIndex` with ``freq=None``, addition or subtraction of integer-dtyped array or ``Index`` will raise ``NullFrequencyError`` instead of ``TypeError`` (:issue:`19895`)

pandas/core/generic.py

@@ -6704,9 +6704,10 @@ def at_time(self, time, asof=False):
         """
         Select values at particular time of day (e.g. 9:30AM).
 
-        Notes
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
@@ -6718,25 +6719,27 @@ def at_time(self, time, asof=False):
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='4D2min')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='12H')
         >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
         >>> ts
                              A
-        date
         2018-04-09 00:00:00  1
-        2018-04-13 00:02:00  2
-        2018-04-17 00:04:00  3
-        2018-04-21 00:06:00  4
-        >>> ts.at_time('0:02')
+        2018-04-09 12:00:00  2
+        2018-04-10 00:00:00  3
+        2018-04-10 12:00:00  4
+
+        >>> ts.at_time('12:00')
                              A
-        date
-        2018-04-13 00:02:00  2
+        2018-04-09 12:00:00  2
+        2018-04-10 12:00:00  4
 
         See Also
         --------
         between_time : Select values between particular times of the day
         first : Select initial periods of time series based on a date offset
         last : Select final periods of time series based on a date offset
+        DatetimeIndex.indexer_at_time : Get just the index locations for
+            values at particular time of the day
         """
         try:
             indexer = self.index.indexer_at_time(time, asof=asof)
@@ -6749,9 +6752,13 @@ def between_time(self, start_time, end_time, include_start=True,
         """
         Select values between particular times of the day (e.g., 9:00-9:30 AM).
 
-        Notes
+        By setting ``start_time`` to be later than ``end_time``,
+        you can get the times that are *not* between the two times.
+
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
@@ -6766,24 +6773,35 @@ def between_time(self, start_time, end_time, include_start=True,
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='2min')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='1D20min')
         >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
         >>> ts
                              A
         2018-04-09 00:00:00  1
-        2018-04-09 00:02:00  2
-        2018-04-09 00:04:00  3
-        2018-04-09 00:06:00  4
-        >>> ts.between_time('0:02', '0:04')
+        2018-04-10 00:20:00  2
+        2018-04-11 00:40:00  3
+        2018-04-12 01:00:00  4
+
+        >>> ts.between_time('0:15', '0:45')
+                             A
+        2018-04-10 00:20:00  2
+        2018-04-11 00:40:00  3
+
+        You get the times that are *not* between two times by setting
+        ``start_time`` later than ``end_time``:
+
+        >>> ts.between_time('0:45', '0:15')
                              A
-        2018-04-09 00:02:00  2
-        2018-04-09 00:04:00  3
+        2018-04-09 00:00:00  1
+        2018-04-12 01:00:00  4
 
         See Also
         --------
         at_time : Select values at a particular time of the day
         first : Select initial periods of time series based on a date offset
         last : Select final periods of time series based on a date offset
+        DatetimeIndex.indexer_between_time : Get just the index locations for
+            values between particular times of the day
         """
         try:
             indexer = self.index.indexer_between_time(
@@ -7037,29 +7055,35 @@ def first(self, offset):
         Convenience method for subsetting initial periods of time series data
         based on a date offset.
 
-        Notes
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
         offset : string, DateOffset, dateutil.relativedelta
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='D')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
         >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
         >>> ts
                     A
         2018-04-09  1
-        2018-04-10  2
-        2018-04-11  3
-        2018-04-12  4
+        2018-04-11  2
+        2018-04-13  3
+        2018-04-15  4
+
+        Get the rows for the first 3 days:
+
         >>> ts.first('3D')
                     A
         2018-04-09  1
-        2018-04-10  2
-        2018-04-11  3
+        2018-04-11  2
+
+        Notice the data for 3 first calender days were returned, not the first
+        3 days observed, and therefore data for 2018-04-13 was not returned.
 
         Returns
         -------
@@ -7073,8 +7097,7 @@ def first(self, offset):
         """
         from pandas.tseries.frequencies import to_offset
         if not isinstance(self.index, DatetimeIndex):
-            raise NotImplementedError("'first' only supports a DatetimeIndex "
-                                      "index")
+            raise TypeError("'first' only supports a DatetimeIndex index")
 
         if len(self.index) == 0:
             return self
@@ -7095,29 +7118,35 @@ def last(self, offset):
         Convenience method for subsetting final periods of time series data
         based on a date offset.
 
-        Notes
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
         offset : string, DateOffset, dateutil.relativedelta
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='D')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
         >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
         >>> ts
                     A
         2018-04-09  1
-        2018-04-10  2
-        2018-04-11  3
-        2018-04-12  4
+        2018-04-11  2
+        2018-04-13  3
+        2018-04-15  4
+
+        Get the rows for the last 3 days:
+
         >>> ts.last('3D')
                     A
-        2018-04-10  2
-        2018-04-11  3
-        2018-04-12  4
+        2018-04-13  3
+        2018-04-15  4
+
+        Notice the data for 3 last calender days were returned, not the last
+        3 observed days, and therefore data for 2018-04-11 was not returned.
 
         Returns
         -------
@@ -7131,8 +7160,7 @@ def last(self, offset):
         """
         from pandas.tseries.frequencies import to_offset
         if not isinstance(self.index, DatetimeIndex):
-            raise NotImplementedError("'last' only supports a DatetimeIndex "
-                                      "index")
+            raise TypeError("'last' only supports a DatetimeIndex index")
 
         if len(self.index) == 0:
             return self

pandas/core/indexes/datetimes.py

@@ -2378,15 +2378,23 @@ def tz_localize(self, tz, ambiguous='raise', errors='raise'):
 
     def indexer_at_time(self, time, asof=False):
         """
-        Select values at particular time of day (e.g. 9:30AM)
+        Returns index locations of index values at particular time of day
+        (e.g. 9:30AM).
 
         Parameters
         ----------
         time : datetime.time or string
+            datetime.time or string in appropriate format ("%H:%M", "%H%M",
+            "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
+            "%I%M%S%p").
 
         Returns
         -------
-        values_at_time : TimeSeries
+        values_at_time : array of integers
+
+        See Also
+        --------
+        indexer_between_time, DataFrame.at_time
         """
         from dateutil.parser import parse
 
@@ -2408,24 +2416,25 @@ def indexer_at_time(self, time, asof=False):
     def indexer_between_time(self, start_time, end_time, include_start=True,
                              include_end=True):
         """
-        Select values between particular times of day (e.g., 9:00-9:30AM).
-
-        Return values of the index between two times.  If start_time or
-        end_time are strings then tseries.tools.to_time is used to convert to
-        a time object.
+        Return index locations of values between particular times of day
+        (e.g., 9:00-9:30AM).
 
         Parameters
         ----------
         start_time, end_time : datetime.time, str
             datetime.time or string in appropriate format ("%H:%M", "%H%M",
             "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
-            "%I%M%S%p")
+            "%I%M%S%p").
         include_start : boolean, default True
         include_end : boolean, default True
 
         Returns
         -------
-        values_between_time : TimeSeries
+        values_between_time : array of integers
+
+        See Also
+        --------
+        indexer_at_time, DataFrame.between_time
         """
         start_time = tools.to_time(start_time)
         end_time = tools.to_time(end_time)