Make *_range functions consistent

Author: jschendel

doc/source/whatsnew/v0.21.0.txt

@@ -310,6 +310,59 @@ Previously, :func:`to_datetime` did not localize datetime ``Series`` data when `
 
 Additionally, DataFrames with datetime columns that were parsed by :func:`read_sql_table` and :func:`read_sql_query` will also be localized to UTC only if the original SQL columns were timezone aware datetime columns.
 
+.. _whatsnew_0200.api.consistency_of_range_functions:
+
+Consistency of Range Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In previous versions, there were some inconsistencies between the various range functions: ``date_range``, ``bdate_range``, ``cdate_range``, ``interval_range``, ``period_range``, and ``timedelta_range``.   (:issue:`17471`).
+
+One of the inconsistent behaviors occurred when the ``start``, ``end`` and ``period`` parameters were all specified, potentially leading to ambiguous ranges.  When all three parameters were passed, ``interval_range`` ignored the ``period`` parameter, ``period_range`` ignored the ``end`` parameter, and the other range functions raised.  To promote consistency among the range functions, and avoid potentially ambiguous ranges, ``interval_range`` and ``period_range`` will now raise when all three parameters are passed.
+
+Previous Behavior:
+
+.. code-block:: ipython
+
+  In [2]: pd.interval_range(start=0, end=4, periods=6)
+  Out[2]:
+  IntervalIndex([(0, 1], (1, 2], (2, 3]]
+                closed='right',
+                dtype='interval[int64]')
+
+  In [3]: pd.period_range(start='2017Q1', end='2017Q4', periods=6, freq='Q')
+  Out[3]: PeriodIndex(['2017Q1', '2017Q2', '2017Q3', '2017Q4', '2018Q1', '2018Q2'], dtype='period[Q-DEC]', freq='Q-DEC')
+
+New Behavior:
+
+.. code-block:: ipython
+
+  In [2]: pd.interval_range(start=0, end=4, periods=6)
+  ---------------------------------------------------------------------------
+  ValueError: Must specify exactly two of start, end, or periods
+
+  In [3]: pd.period_range(start='2017Q1', end='2017Q4', periods=6, freq='Q')  
+  ---------------------------------------------------------------------------
+  ValueError: Must specify exactly two of start, end, or periods
+
+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``.
+
+Previous Behavior:
+
+.. code-block:: ipython
+
+  In [4]: pd.interval_range(start=0, end=4)
+  Out[4]:
+  IntervalIndex([(0, 1], (1, 2], (2, 3]]
+                closed='right',
+                dtype='interval[int64]')
+
+
+New Behavior:
+
+  .. ipython:: python
+
+     pd.interval_range(start=0, end=4)
+
 .. _whatsnew_0210.api:
 
 Other API Changes

pandas/core/indexes/datetimes.py

@@ -412,7 +412,8 @@ def __new__(cls, data=None,
     def _generate(cls, start, end, periods, name, offset,
                   tz=None, normalize=False, ambiguous='raise', closed=None):
         if com._count_not_none(start, end, periods) != 2:
-            raise ValueError('Must specify two of start, end, or periods')
+            msg = 'Must specify exactly two of start, end, or periods'
+            raise ValueError(msg)
 
         _normalized = True
 
@@ -2030,7 +2031,7 @@ def date_range(start=None, end=None, periods=None, freq='D', tz=None,
 
     Notes
     -----
-    2 of start, end, or periods must be specified
+    Exactly two of start, end, or periods must be specified
 
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
@@ -2073,7 +2074,7 @@ def bdate_range(start=None, end=None, periods=None, freq='B', tz=None,
 
     Notes
     -----
-    2 of start, end, or periods must be specified
+    Exactly two of start, end, or periods must be specified
 
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
@@ -2127,7 +2128,7 @@ def cdate_range(start=None, end=None, periods=None, freq='C', tz=None,
 
     Notes
     -----
-    2 of start, end, or periods must be specified
+    Exactly two of start, end, or periods must be specified
 
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.

pandas/core/indexes/interval.py

@@ -1039,43 +1039,35 @@ def interval_range(start=None, end=None, freq=None, periods=None,
         Left bound for generating data
     end : string or datetime-like, default None
         Right bound for generating data
-    freq : interger, string or DateOffset, default 1
-    periods : interger, default None
+    freq : integer, string or DateOffset, default 1
+    periods : integer, default None
     name : str, default None
         Name of the resulting index
     closed : string, default 'right'
         options are: 'left', 'right', 'both', 'neither'
 
     Notes
     -----
-    2 of start, end, or periods must be specified
+    Exactly two of start, end, or periods must be specified
 
     Returns
     -------
     rng : IntervalIndex
     """
+    if com._count_not_none(start, end, periods) != 2:
+        raise ValueError('Must specify exactly two of start, end, or periods')
 
     if freq is None:
         freq = 1
-
     if start is None:
-        if periods is None or end is None:
-            raise ValueError("must specify 2 of start, end, periods")
         start = end - periods * freq
     if end is None:
-        if periods is None or start is None:
-            raise ValueError("must specify 2 of start, end, periods")
         end = start + periods * freq
-    if periods is None:
-        if start is None or end is None:
-            raise ValueError("must specify 2 of start, end, periods")
-        pass
 
     # must all be same units or None
     arr = np.array([start, end, freq])
     if is_object_dtype(arr):
         raise ValueError("start, end, freq need to be the same type")
 
-    return IntervalIndex.from_breaks(np.arange(start, end, freq),
-                                     name=name,
-                                     closed=closed)
+    return IntervalIndex.from_breaks(np.arange(start, end + 1, freq),
+                                     name=name, closed=closed, **kwargs)

pandas/core/indexes/period.py

@@ -1051,8 +1051,8 @@ def tz_localize(self, tz, infer_dst=False):
 
 
 def _get_ordinal_range(start, end, periods, freq, mult=1):
-    if com._count_not_none(start, end, periods) < 2:
-        raise ValueError('Must specify 2 of start, end, periods')
+    if com._count_not_none(start, end, periods) != 2:
+        raise ValueError('Must specify exactly two of start, end, or periods')
 
     if freq is not None:
         _, mult = _gfc(freq)
@@ -1160,7 +1160,6 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None):
     Return a fixed frequency datetime index, with day (calendar) as the default
     frequency
 
-
     Parameters
     ----------
     start : starting value, period-like, optional
@@ -1172,6 +1171,13 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None):
     name : str, default None
         Name for the resulting PeriodIndex
 
+    Notes
+    -----
+    Exactly two of start, end, or periods must be specified
+
+    To learn more about the frequency strings, please see `this link
+    <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
+
     Returns
     -------
     prng : PeriodIndex

pandas/core/indexes/timedeltas.py

@@ -234,7 +234,8 @@ def __new__(cls, data=None, unit=None,
     @classmethod
     def _generate(cls, start, end, periods, name, offset, closed=None):
         if com._count_not_none(start, end, periods) != 2:
-            raise ValueError('Must specify two of start, end, or periods')
+            msg = 'Must specify exactly two of start, end, or periods'
+            raise ValueError(msg)
 
         if start is not None:
             start = Timedelta(start)
@@ -985,7 +986,7 @@ def timedelta_range(start=None, end=None, periods=None, freq='D',
 
     Notes
     -----
-    2 of start, end, or periods must be specified.
+    Exactly two of start, end, or periods must be specified.
 
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.

pandas/tests/indexes/datetimes/test_date_range.py

@@ -107,8 +107,8 @@ def test_date_range_ambiguous_arguments(self):
         start = datetime(2011, 1, 1, 5, 3, 40)
         end = datetime(2011, 1, 1, 8, 9, 40)
 
-        pytest.raises(ValueError, date_range, start, end, freq='s',
-                      periods=10)
+        with pytest.raises(ValueError):
+            date_range(start, end, periods=10, freq='s')
 
     def test_date_range_businesshour(self):
         idx = DatetimeIndex(['2014-07-04 09:00', '2014-07-04 10:00',
@@ -146,14 +146,26 @@ def test_date_range_businesshour(self):
 
     def test_range_misspecified(self):
         # GH #1095
+        with pytest.raises(ValueError):
+            date_range(start='1/1/2000')
+
+        with pytest.raises(ValueError):
+            date_range(end='1/1/2000')
+
+        with pytest.raises(ValueError):
+            date_range(periods=10)
+
+        with pytest.raises(ValueError):
+            date_range(start='1/1/2000', freq='H')
+
+        with pytest.raises(ValueError):
+            date_range(end='1/1/2000', freq='H')
 
-        pytest.raises(ValueError, date_range, '1/1/2000')
-        pytest.raises(ValueError, date_range, end='1/1/2000')
-        pytest.raises(ValueError, date_range, periods=10)
+        with pytest.raises(ValueError):
+            date_range(periods=10, freq='H')
 
-        pytest.raises(ValueError, date_range, '1/1/2000', freq='H')
-        pytest.raises(ValueError, date_range, end='1/1/2000', freq='H')
-        pytest.raises(ValueError, date_range, periods=10, freq='H')
+        with pytest.raises(ValueError):
+            date_range()
 
     def test_compat_replace(self):
         # https://github.com/statsmodels/statsmodels/issues/3349

pandas/tests/indexes/period/test_construction.py

@@ -440,7 +440,7 @@ def test_constructor_error(self):
         with tm.assert_raises_regex(ValueError, msg):
             PeriodIndex(start=start, end=end_intv)
 
-        msg = 'Must specify 2 of start, end, periods'
+        msg = 'Must specify exactly two of start, end, or periods'
         with tm.assert_raises_regex(ValueError, msg):
             PeriodIndex(start=start)
 

pandas/tests/indexes/period/test_period_range.py

@@ -0,0 +1,52 @@
+import pytest
+import pandas.util.testing as tm
+from pandas import date_range, period_range, PeriodIndex
+
+
+class TestPeriodRange(object):
+
+    @pytest.mark.parametrize('freq', ['D', 'W', 'M', 'Q', 'A'])
+    def test_construction(self, freq):
+        # non-empty
+        expected = date_range(start='2017-01-01', periods=5,
+                              freq=freq, name='foo').to_period()
+        start, end = str(expected[0]), str(expected[-1])
+
+        result = period_range(start=start, end=end, freq=freq, name='foo')
+        tm.assert_index_equal(result, expected)
+
+        result = period_range(start=start, periods=5, freq=freq, name='foo')
+        tm.assert_index_equal(result, expected)
+
+        result = period_range(end=end, periods=5, freq=freq, name='foo')
+        tm.assert_index_equal(result, expected)
+
+        # empty
+        expected = PeriodIndex([], freq=freq, name='foo')
+
+        result = period_range(start=start, periods=0, freq=freq, name='foo')
+        tm.assert_index_equal(result, expected)
+
+        result = period_range(end=end, periods=0, freq=freq, name='foo')
+        tm.assert_index_equal(result, expected)
+
+        result = period_range(start=end, end=start, freq=freq, name='foo')
+        tm.assert_index_equal(result, expected)
+
+    def test_errors(self):
+        # not enough params
+        with pytest.raises(ValueError):
+            period_range(start='2017Q1')
+
+        with pytest.raises(ValueError):
+            period_range(end='2017Q1')
+
+        with pytest.raises(ValueError):
+            period_range(periods=5)
+
+        with pytest.raises(ValueError):
+            period_range()
+
+        # too many params
+        with pytest.raises(ValueError):
+            period_range(start='2017Q1', end='2018Q1', periods=8, freq='Q')

pandas/tests/indexes/test_interval.py

@@ -721,40 +721,66 @@ def test_is_non_overlapping_monotonic(self):
 
 class TestIntervalRange(object):
 
-    def test_construction(self):
-        result = interval_range(0, 5, name='foo', closed='both')
+    @pytest.mark.parametrize('closed', ['left', 'right', 'neither', 'both'])
+    def test_construction(self, closed):
+        # combinations of start/end/periods without freq
         expected = IntervalIndex.from_breaks(
-            np.arange(0, 5), name='foo', closed='both')
+            np.arange(0, 6), name='foo', closed=closed)
+
+        result = interval_range(start=0, end=5, name='foo', closed=closed)
         tm.assert_index_equal(result, expected)
 
-    def test_errors(self):
+        result = interval_range(start=0, periods=5, name='foo', closed=closed)
+        tm.assert_index_equal(result, expected)
+
+        result = interval_range(end=5, periods=5, name='foo', closed=closed)
+        tm.assert_index_equal(result, expected)
+
+        # combinations of start/end/periods with freq
+        expected = IntervalIndex.from_tuples([(0, 2), (2, 4), (4, 6)],
+                                             name='foo', closed=closed)
+
+        result = interval_range(start=0, end=6, freq=2, name='foo',
+                                closed=closed)
+        tm.assert_index_equal(result, expected)
+
+        result = interval_range(start=0, periods=3, freq=2, name='foo',
+                                closed=closed)
+        tm.assert_index_equal(result, expected)
+
+        result = interval_range(end=6, periods=3, freq=2, name='foo',
+                                closed=closed)
+        tm.assert_index_equal(result, expected)
+
+        # output truncates early if freq causes end to be skipped.
+        result = interval_range(start=0, end=7, freq=2, name='foo',
+                                closed=closed)
+        tm.assert_index_equal(result, expected)
 
+    def test_errors(self):
         # not enough params
-        def f():
-            interval_range(0)
+        with pytest.raises(ValueError):
+            interval_range(start=0)
 
-        pytest.raises(ValueError, f)
+        with pytest.raises(ValueError):
+            interval_range(end=5)
 
-        def f():
+        with pytest.raises(ValueError):
             interval_range(periods=2)
 
-        pytest.raises(ValueError, f)
-
-        def f():
+        with pytest.raises(ValueError):
             interval_range()
 
-        pytest.raises(ValueError, f)
+        # too many params
+        with pytest.raises(ValueError):
+            interval_range(start=0, end=5, periods=6)
 
         # mixed units
-        def f():
-            interval_range(0, Timestamp('20130101'), freq=2)
-
-        pytest.raises(ValueError, f)
-
-        def f():
-            interval_range(0, 10, freq=Timedelta('1day'))
+        with pytest.raises(ValueError):
+            interval_range(start=0, end=Timestamp('20130101'), freq=2)
 
-        pytest.raises(ValueError, f)
+        with pytest.raises(ValueError):
+            interval_range(start=0, end=10, freq=Timedelta('1day'))
 
 
 class TestIntervalTree(object):