Review and datetime-like implementation

Made review related changes, implemented support for datetime-like input in interval_range.

Author: jschendel

doc/source/whatsnew/v0.21.0.txt

@@ -339,11 +339,11 @@ New Behavior:
 
   In [2]: pd.interval_range(start=0, end=4, periods=6)
   ---------------------------------------------------------------------------
-  ValueError: Of the three parameters, start, end, and periods, exactly two must be specified
+  ValueError: Of the three parameters: start, end, and periods, exactly two must be specified
 
   In [3]: pd.period_range(start='2017Q1', end='2017Q4', periods=6, freq='Q')  
   ---------------------------------------------------------------------------
-  ValueError: Of the three parameters, start, end, and periods, exactly two must be specified
+  ValueError: Of the three parameters: start, end, and periods, exactly two must be specified
 
 Additionally, the endpoint parameter ``end`` was not included in the intervals produced by ``interval_range``.  However, all other range functions include ``end`` in their output.  To promote consistency among the range functions, ``interval_range`` will now include ``end`` as the right endpoint of the final interval, except if ``freq`` is specified in a way which skips ``end``.
 

pandas/core/indexes/datetimes.py

@@ -293,7 +293,7 @@ def __new__(cls, data=None,
                 periods = int(periods)
             elif not is_integer(periods):
                 msg = 'periods must be a number, got {periods}'
-                raise ValueError(msg.format(periods=periods))
+                raise TypeError(msg.format(periods=periods))
 
         if data is None and freq is None:
             raise ValueError("Must provide freq argument if no data is "
@@ -2015,7 +2015,7 @@ def date_range(start=None, end=None, periods=None, freq='D', tz=None,
     end : string or datetime-like, default None
         Right bound for generating dates
     periods : integer, default None
-        Number of dates to generate
+        Number of periods to generate
     freq : string or DateOffset, default 'D' (calendar daily)
         Frequency strings can have multiples, e.g. '5H'
     tz : string, default None
@@ -2059,9 +2059,9 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
     end : string or datetime-like, default None
         Right bound for generating dates
     periods : integer, default None
-        Number of dates to generate
+        Number of periods to generate
     freq : string or DateOffset, default 'B' (business daily)
-        Frequency strings can have multiples, e.g. '5, default
+        Frequency strings can have multiples, e.g. '5H'
     tz : string or None
         Time zone name for returning localized DatetimeIndex, for example
         Asia/Beijing
@@ -2109,7 +2109,7 @@ def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
     end : string or datetime-like, default None
         Right bound for generating dates
     periods : integer, default None
-        Number of dates to generate
+        Number of periods to generate
     freq : string or DateOffset, default 'C' (CustomBusinessDay)
         Frequency strings can have multiples, e.g. '5H'
     tz : string, default None

pandas/core/indexes/interval.py

@@ -16,6 +16,7 @@
     is_interval_dtype,
     is_scalar,
     is_float,
+    is_number,
     is_integer)
 from pandas.core.indexes.base import (
     Index, _ensure_index,
@@ -26,11 +27,14 @@
     Interval, IntervalMixin, IntervalTree,
     intervals_to_interval_bounds)
 
+from pandas.core.indexes.datetimes import date_range
 from pandas.core.indexes.multi import MultiIndex
 from pandas.compat.numpy import function as nv
 from pandas.core import common as com
 from pandas.util._decorators import cache_readonly, Appender
 from pandas.core.config import get_option
+from pandas.tseries.offsets import DateOffset
+from pandas.tseries.frequencies import to_offset
 
 import pandas.core.indexes.base as ibase
 _index_doc_kwargs = dict(ibase._index_doc_kwargs)
@@ -1030,21 +1034,22 @@ def func(self, other):
 
 
 def interval_range(start=None, end=None, periods=None, freq=None,
-                   name=None, closed='right', **kwargs):
+                   name=None, closed='right'):
     """
     Return a fixed frequency IntervalIndex
 
     Parameters
     ----------
-    start : numeric, string, or datetime-like, default None
+    start : numeric or datetime-like, default None
         Left bound for generating intervals
-    end : numeric, string, or datetime-like, default None
+    end : numeric or datetime-like, default None
         Right bound for generating intervals
     periods : integer, default None
-        Number of intervals to generate
-    freq : numeric, string, or DateOffset, default 1
-        The length of each interval. Must be consistent with the
-        type of start and end
+        Number of periods to generate
+    freq : numeric, string, or DateOffset, default None
+        The length of each interval. Must be consistent with the type of start
+        and end, e.g. 2 for numeric, or '5H' for datetime-like.  Default is 1
+        for numeric and 'D' (calendar daily) for datetime-like.
     name : string, default None
         Name of the resulting IntervalIndex
     closed : string, default 'right'
@@ -1058,32 +1063,107 @@ def interval_range(start=None, end=None, periods=None, freq=None,
     Returns
     -------
     rng : IntervalIndex
+
+    Examples
+    --------
+
+    Numeric ``start`` and  ``end`` is supported.
+
+    >>> pd.interval_range(start=0, end=5)
+    IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]]
+                  closed='right', dtype='interval[int64]')
+
+    Additionally, datetime-like input is also supported.
+
+    >>> pd.interval_range(start='2017-01-01', end='2017-01-04')
+    IntervalIndex([(2017-01-01, 2017-01-02], (2017-01-02, 2017-01-03],
+                   (2017-01-03, 2017-01-04]]
+                  closed='right', dtype='interval[datetime64[ns]]')
+
+    The ``freq`` parameter specifies the frequency between the left and right.
+    endpoints of the individual intervals within the ``IntervalIndex``.  For
+    numeric ``start`` and ``end``, the frequency must also be numeric.
+
+    >>> pd.interval_range(start=0, periods=4, freq=1.5)
+    IntervalIndex([(0.0, 1.5], (1.5, 3.0], (3.0, 4.5], (4.5, 6.0]]
+                  closed='right', dtype='interval[float64]')
+
+    Similarly, for datetime-like ``start`` and ``end``, the frequency must be
+    convertible to a DateOffset.
+
+    >>> pd.interval_range(start='2017-01-01', periods=3, freq='MS')
+    IntervalIndex([(2017-01-01, 2017-02-01], (2017-02-01, 2017-03-01],
+                   (2017-03-01, 2017-04-01]]
+                  closed='right', dtype='interval[datetime64[ns]]')
+
+    The ``closed`` parameter specifies which endpoints of the individual
+    intervals within the ``IntervalIndex`` are closed.
+
+    >>> pd.interval_range(end=5, periods=4, closed='both')
+    IntervalIndex([[1, 2], [2, 3], [3, 4], [4, 5]]
+                  closed='both', dtype='interval[int64]')
     """
     if com._count_not_none(start, end, periods) != 2:
         raise ValueError('Of the three parameters: start, end, and periods, '
                          'exactly two must be specified')
 
-    # must all be same units or None
-    arr = np.array(list(com._not_none(start, end, freq)))
-    if is_object_dtype(arr):
-        raise ValueError("start, end, freq need to be the same type")
+    # assume datetime-like unless we find numeric start or end
+    is_datetime_interval = True
+
+    if is_number(start):
+        is_datetime_interval = False
+    elif start is not None:
+        try:
+            start = Timestamp(start)
+        except (TypeError, ValueError):
+            raise ValueError('start must be numeric or datetime-like')
 
-    if freq is None:
-        freq = 1
+    if is_number(end):
+        is_datetime_interval = False
+    elif end is not None:
+        try:
+            end = Timestamp(end)
+        except (TypeError, ValueError):
+            raise ValueError('end must be numeric or datetime-like')
 
-    if periods is None:
-        periods = int((end - start) // freq)
-    elif is_float(periods):
+    if is_float(periods):
         periods = int(periods)
-    elif not is_integer(periods):
+    elif not is_integer(periods) and periods is not None:
         msg = 'periods must be a number, got {periods}'
-        raise ValueError(msg.format(periods=periods))
+        raise TypeError(msg.format(periods=periods))
 
-    if start is None:
-        start = end - periods * freq
+    if is_datetime_interval:
+        freq = freq or 'D'
+        if not isinstance(freq, DateOffset):
+            try:
+                freq = to_offset(freq)
+            except ValueError:
+                raise ValueError('freq must be convertible to DateOffset when '
+                                 'start/end are datetime-like')
+    else:
+        freq = freq or 1
 
-    # force end to be consistent with freq (truncate if freq skips over end)
-    end = start + periods * freq
+    # verify type compatibility
+    is_numeric_interval = all(map(is_number, com._not_none(start, end, freq)))
+    if not is_datetime_interval and not is_numeric_interval:
+        raise TypeError("start, end, freq need to be type compatible")
+
+    if is_numeric_interval:
+        if periods is None:
+            periods = int((end - start) // freq)
+
+        if start is None:
+            start = end - periods * freq
+
+        # force end to be consistent with freq (lower if freq skips over end)
+        end = start + periods * freq
+
+        # end + freq for inclusive endpoint
+        breaks = np.arange(start, end + freq, freq)
+    else:
+        # add one to account for interval endpoints (n breaks = n-1 intervals)
+        if periods is not None:
+            periods += 1
+        breaks = date_range(start=start, end=end, periods=periods, freq=freq)
 
-    return IntervalIndex.from_breaks(np.arange(start, end + freq, freq),
-                                     name=name, closed=closed, **kwargs)
+    return IntervalIndex.from_breaks(breaks, name=name, closed=closed)

pandas/core/indexes/period.py

@@ -200,7 +200,7 @@ def __new__(cls, data=None, ordinal=None, freq=None, start=None, end=None,
                 periods = int(periods)
             elif not is_integer(periods):
                 msg = 'periods must be a number, got {periods}'
-                raise ValueError(msg.format(periods=periods))
+                raise TypeError(msg.format(periods=periods))
 
         if name is None and hasattr(data, 'name'):
             name = data.name

pandas/core/indexes/timedeltas.py

@@ -181,7 +181,7 @@ def __new__(cls, data=None, unit=None,
                 periods = int(periods)
             elif not is_integer(periods):
                 msg = 'periods must be a number, got {periods}'
-                raise ValueError(msg.format(periods=periods))
+                raise TypeError(msg.format(periods=periods))
 
         if data is None and freq is None:
             raise ValueError("Must provide freq argument if no data is "
@@ -971,7 +971,7 @@ def timedelta_range(start=None, end=None, periods=None, freq='D',
     end : string or timedelta-like, default None
         Right bound for generating timedeltas
     periods : integer, default None
-        Number of timedeltas to generate
+        Number of periods to generate
     freq : string or DateOffset, default 'D' (calendar daily)
         Frequency strings can have multiples, e.g. '5H'
     name : string, default None
@@ -991,6 +991,29 @@ def timedelta_range(start=None, end=None, periods=None, freq='D',
 
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
+
+    Examples
+    --------
+
+    >>> pd.timedelta_range(start='1 day', periods=4)
+    TimedeltaIndex(['1 days', '2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq='D')
+
+    The ``closed`` parameter specifies which endpoint is included.  The default
+    behavior is to include both endpoints.
+
+    >>> pd.timedelta_range(start='1 day', periods=4, closed='right')
+    TimedeltaIndex(['2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq='D')
+
+    The ``freq`` parameter specifies the frequency of the TimedeltaIndex.
+    Only fixed frequencies can be passed, non-fixed frequencies such as
+    'M' (month end) will raise.
+
+    >>> pd.timedelta_range(start='1 day', end='2 days', freq='6H')
+    TimedeltaIndex(['1 days 00:00:00', '1 days 06:00:00', '1 days 12:00:00',
+                    '1 days 18:00:00', '2 days 00:00:00'],
+                   dtype='timedelta64[ns]', freq='6H')
     """
     return TimedeltaIndex(start=start, end=end, periods=periods,
                           freq=freq, name=name, closed=closed)

pandas/tests/indexes/datetimes/test_construction.py

@@ -307,8 +307,9 @@ def test_constructor_coverage(self):
         exp = date_range('1/1/2000', periods=10)
         tm.assert_index_equal(rng, exp)
 
-        pytest.raises(ValueError, DatetimeIndex, start='1/1/2000',
-                      periods='foo', freq='D')
+        msg = 'periods must be a number, got foo'
+        with tm.assert_raises_regex(TypeError, msg):
+            DatetimeIndex(start='1/1/2000', periods='foo', freq='D')
 
         pytest.raises(ValueError, DatetimeIndex, start='1/1/2000',
                       end='1/10/2000')

pandas/tests/indexes/datetimes/test_date_range.py

@@ -248,8 +248,13 @@ def test_constructor(self):
         bdate_range(START, END, freq=BDay())
         bdate_range(START, periods=20, freq=BDay())
         bdate_range(end=START, periods=20, freq=BDay())
-        pytest.raises(ValueError, date_range, '2011-1-1', '2012-1-1', 'B')
-        pytest.raises(ValueError, bdate_range, '2011-1-1', '2012-1-1', 'B')
+
+        msg = 'periods must be a number, got B'
+        with tm.assert_raises_regex(TypeError, msg):
+            date_range('2011-1-1', '2012-1-1', 'B')
+
+        with tm.assert_raises_regex(TypeError, msg):
+            bdate_range('2011-1-1', '2012-1-1', 'B')
 
     def test_naive_aware_conflicts(self):
         naive = bdate_range(START, END, freq=BDay(), tz=None)
@@ -527,8 +532,13 @@ def test_constructor(self):
         cdate_range(START, END, freq=CDay())
         cdate_range(START, periods=20, freq=CDay())
         cdate_range(end=START, periods=20, freq=CDay())
-        pytest.raises(ValueError, date_range, '2011-1-1', '2012-1-1', 'C')
-        pytest.raises(ValueError, cdate_range, '2011-1-1', '2012-1-1', 'C')
+
+        msg = 'periods must be a number, got C'
+        with tm.assert_raises_regex(TypeError, msg):
+            date_range('2011-1-1', '2012-1-1', 'C')
+
+        with tm.assert_raises_regex(TypeError, msg):
+            cdate_range('2011-1-1', '2012-1-1', 'C')
 
     def test_cached_range(self):
         DatetimeIndex._cached_range(START, END, offset=CDay())

pandas/tests/indexes/period/test_period_range.py

@@ -87,3 +87,8 @@ def test_errors(self):
 
         with tm.assert_raises_regex(ValueError, msg):
             period_range(start='2017Q1', end=NaT)
+
+        # invalid periods param
+        msg = 'periods must be a number, got foo'
+        with tm.assert_raises_regex(TypeError, msg):
+            period_range(start='2017Q1', periods='foo')