DEPR: Deprecate range-based PeriodIndex construction

Closes pandas-dev#20535

Author: TomAugspurger

doc/source/whatsnew/v0.24.0.rst

@@ -1142,7 +1142,7 @@ Deprecations
 - Timezone converting a tz-aware ``datetime.datetime`` or :class:`Timestamp` with :class:`Timestamp` and the ``tz`` argument is now deprecated. Instead, use :meth:`Timestamp.tz_convert` (:issue:`23579`)
 - :func:`pandas.api.types.is_period` is deprecated in favor of `pandas.api.types.is_period_dtype` (:issue:`23917`)
 - :func:`pandas.api.types.is_datetimetz` is deprecated in favor of `pandas.api.types.is_datetime64tz` (:issue:`23917`)
-- Creating a :class:`TimedeltaIndex` or :class:`DatetimeIndex` by passing range arguments `start`, `end`, and `periods` is deprecated in favor of :func:`timedelta_range` and :func:`date_range` (:issue:`23919`)
+- Creating a :class:`TimedeltaIndex`, :class:`DatetimeIndex`, or :class:`PeriodIndex` by passing range arguments `start`, `end`, and `periods` is deprecated in favor of :func:`timedelta_range`, :func:`date_range`, or :func:`period_range` (:issue:`23919`)
 - Passing a string alias like ``'datetime64[ns, UTC]'`` as the ``unit`` parameter to :class:`DatetimeTZDtype` is deprecated. Use :class:`DatetimeTZDtype.construct_from_string` instead (:issue:`23990`).
 - In :meth:`Series.where` with Categorical data, providing an ``other`` that is not present in the categories is deprecated. Convert the categorical to a different dtype or add the ``other`` to the categories first (:issue:`24077`).
 - :meth:`Series.clip_lower`, :meth:`Series.clip_upper`, :meth:`DataFrame.clip_lower` and :meth:`DataFrame.clip_upper` are deprecated and will be removed in a future version. Use ``Series.clip(lower=threshold)``, ``Series.clip(upper=threshold)`` and the equivalent ``DataFrame`` methods (:issue:`24203`)
@@ -1313,6 +1313,7 @@ Datetimelike
 - Bug in :meth:`Series.combine_first` not properly aligning categoricals, so that missing values in ``self`` where not filled by valid values from ``other`` (:issue:`24147`)
 - Bug in :func:`DataFrame.combine` with datetimelike values raising a TypeError (:issue:`23079`)
 - Bug in :func:`date_range` with frequency of ``Day`` or higher where dates sufficiently far in the future could wrap around to the past instead of raising ``OutOfBoundsDatetime`` (:issue:`14187`)
+- Bug in :func:`period_range` ignoring the frequency of ``start`` and ``end`` when those are provided as :class:`Period` objects (:issue:`20535`).
 - Bug in :class:`PeriodIndex` with attribute ``freq.n`` greater than 1 where adding a :class:`DateOffset` object would return incorrect results (:issue:`23215`)
 - Bug in :class:`Series` that interpreted string indices as lists of characters when setting datetimelike values (:issue:`23451`)
 - Bug in :class:`Timestamp` constructor which would drop the frequency of an input :class:`Timestamp` (:issue:`22311`)

pandas/core/indexes/datetimes.py

@@ -223,13 +223,13 @@ def __new__(cls, data=None,
             verify_integrity = True
 
         if data is None:
+            result = cls._generate_range(start, end, periods,
+                                         freq=freq, tz=tz, normalize=normalize,
+                                         closed=closed, ambiguous=ambiguous)
             warnings.warn("Creating a DatetimeIndex by passing range "
                           "endpoints is deprecated.  Use "
                           "`pandas.date_range` instead.",
                           FutureWarning, stacklevel=2)
-            result = cls._generate_range(start, end, periods,
-                                         freq=freq, tz=tz, normalize=normalize,
-                                         closed=closed, ambiguous=ambiguous)
             result.name = name
             return result
 

pandas/core/indexes/period.py

@@ -183,6 +183,14 @@ def __new__(cls, data=None, ordinal=None, freq=None, start=None, end=None,
             # range-based.
             data, freq = PeriodArray._generate_range(start, end, periods,
                                                      freq, fields)
+            # PeriodArray._generate range does validate that fields is
+            # empty when really using the range-based constructor.
+            if not fields:
+                warnings.warn("Creating a PeriodIndex by passing range "
+                              "endpoints is deprecated.  Use "
+                              "`pandas.period_range` instead.",
+                              FutureWarning, stacklevel=2)
+
             data = PeriodArray(data, freq=freq)
         else:
             freq = validate_dtype_freq(dtype, freq)
@@ -983,7 +991,7 @@ def base(self):
 PeriodIndex._add_datetimelike_methods()
 
 
-def period_range(start=None, end=None, periods=None, freq='D', name=None):
+def period_range(start=None, end=None, periods=None, freq=None, name=None):
     """
     Return a fixed frequency PeriodIndex, with day (calendar) as the default
     frequency
@@ -996,8 +1004,11 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None):
         Right bound for generating periods
     periods : integer, default None
         Number of periods to generate
-    freq : string or DateOffset, default 'D'
-        Frequency alias
+    freq : string or DateOffset, optional
+        Frequency alias. By default the freq is taken from `start` or `end`
+        if those are Period objects. Otherwise, the default is ``"D"`` for
+        daily frequency.
+
     name : string, default None
         Name of the resulting PeriodIndex
 
@@ -1035,5 +1046,7 @@ def period_range(start=None, end=None, periods=None, freq='D', name=None):
         raise ValueError('Of the three parameters: start, end, and periods, '
                          'exactly two must be specified')
 
-    return PeriodIndex(start=start, end=end, periods=periods,
-                       freq=freq, name=name)
+    data, freq = PeriodArray._generate_range(start, end, periods, freq,
+                                             fields={})
+    data = PeriodArray(data, freq=freq)
+    return PeriodIndex(data, name=name)

pandas/tests/indexes/period/test_arithmetic.py

@@ -4,7 +4,7 @@
 import pytest
 
 import pandas as pd
-from pandas import PeriodIndex
+from pandas import PeriodIndex, period_range
 import pandas.util.testing as tm
 
 
@@ -26,36 +26,36 @@ def test_pi_shift_ndarray(self):
         tm.assert_index_equal(result, expected)
 
     def test_shift(self):
-        pi1 = PeriodIndex(freq='A', start='1/1/2001', end='12/1/2009')
-        pi2 = PeriodIndex(freq='A', start='1/1/2002', end='12/1/2010')
+        pi1 = period_range(freq='A', start='1/1/2001', end='12/1/2009')
+        pi2 = period_range(freq='A', start='1/1/2002', end='12/1/2010')
 
         tm.assert_index_equal(pi1.shift(0), pi1)
 
         assert len(pi1) == len(pi2)
         tm.assert_index_equal(pi1.shift(1), pi2)
 
-        pi1 = PeriodIndex(freq='A', start='1/1/2001', end='12/1/2009')
-        pi2 = PeriodIndex(freq='A', start='1/1/2000', end='12/1/2008')
+        pi1 = period_range(freq='A', start='1/1/2001', end='12/1/2009')
+        pi2 = period_range(freq='A', start='1/1/2000', end='12/1/2008')
         assert len(pi1) == len(pi2)
         tm.assert_index_equal(pi1.shift(-1), pi2)
 
-        pi1 = PeriodIndex(freq='M', start='1/1/2001', end='12/1/2009')
-        pi2 = PeriodIndex(freq='M', start='2/1/2001', end='1/1/2010')
+        pi1 = period_range(freq='M', start='1/1/2001', end='12/1/2009')
+        pi2 = period_range(freq='M', start='2/1/2001', end='1/1/2010')
         assert len(pi1) == len(pi2)
         tm.assert_index_equal(pi1.shift(1), pi2)
 
-        pi1 = PeriodIndex(freq='M', start='1/1/2001', end='12/1/2009')
-        pi2 = PeriodIndex(freq='M', start='12/1/2000', end='11/1/2009')
+        pi1 = period_range(freq='M', start='1/1/2001', end='12/1/2009')
+        pi2 = period_range(freq='M', start='12/1/2000', end='11/1/2009')
         assert len(pi1) == len(pi2)
         tm.assert_index_equal(pi1.shift(-1), pi2)
 
-        pi1 = PeriodIndex(freq='D', start='1/1/2001', end='12/1/2009')
-        pi2 = PeriodIndex(freq='D', start='1/2/2001', end='12/2/2009')
+        pi1 = period_range(freq='D', start='1/1/2001', end='12/1/2009')
+        pi2 = period_range(freq='D', start='1/2/2001', end='12/2/2009')
         assert len(pi1) == len(pi2)
         tm.assert_index_equal(pi1.shift(1), pi2)
 
-        pi1 = PeriodIndex(freq='D', start='1/1/2001', end='12/1/2009')
-        pi2 = PeriodIndex(freq='D', start='12/31/2000', end='11/30/2009')
+        pi1 = period_range(freq='D', start='1/1/2001', end='12/1/2009')
+        pi2 = period_range(freq='D', start='12/31/2000', end='11/30/2009')
         assert len(pi1) == len(pi2)
         tm.assert_index_equal(pi1.shift(-1), pi2)
 
@@ -100,7 +100,7 @@ def test_shift_gh8083(self):
 
     def test_shift_periods(self):
         # GH #22458 : argument 'n' was deprecated in favor of 'periods'
-        idx = PeriodIndex(freq='A', start='1/1/2001', end='12/1/2009')
+        idx = period_range(freq='A', start='1/1/2001', end='12/1/2009')
         tm.assert_index_equal(idx.shift(periods=0), idx)
         tm.assert_index_equal(idx.shift(0), idx)
         with tm.assert_produces_warning(FutureWarning,

pandas/tests/indexes/period/test_asfreq.py

@@ -2,20 +2,20 @@
 import pytest
 
 import pandas as pd
-from pandas import DataFrame, PeriodIndex, Series
+from pandas import DataFrame, PeriodIndex, Series, period_range
 from pandas.util import testing as tm
 
 
 class TestPeriodIndex(object):
 
     def test_asfreq(self):
-        pi1 = PeriodIndex(freq='A', start='1/1/2001', end='1/1/2001')
-        pi2 = PeriodIndex(freq='Q', start='1/1/2001', end='1/1/2001')
-        pi3 = PeriodIndex(freq='M', start='1/1/2001', end='1/1/2001')
-        pi4 = PeriodIndex(freq='D', start='1/1/2001', end='1/1/2001')
-        pi5 = PeriodIndex(freq='H', start='1/1/2001', end='1/1/2001 00:00')
-        pi6 = PeriodIndex(freq='Min', start='1/1/2001', end='1/1/2001 00:00')
-        pi7 = PeriodIndex(freq='S', start='1/1/2001', end='1/1/2001 00:00:00')
+        pi1 = period_range(freq='A', start='1/1/2001', end='1/1/2001')
+        pi2 = period_range(freq='Q', start='1/1/2001', end='1/1/2001')
+        pi3 = period_range(freq='M', start='1/1/2001', end='1/1/2001')
+        pi4 = period_range(freq='D', start='1/1/2001', end='1/1/2001')
+        pi5 = period_range(freq='H', start='1/1/2001', end='1/1/2001 00:00')
+        pi6 = period_range(freq='Min', start='1/1/2001', end='1/1/2001 00:00')
+        pi7 = period_range(freq='S', start='1/1/2001', end='1/1/2001 00:00:00')
 
         assert pi1.asfreq('Q', 'S') == pi2
         assert pi1.asfreq('Q', 's') == pi2
@@ -70,7 +70,7 @@ def test_asfreq(self):
         pytest.raises(ValueError, pi7.asfreq, 'T', 'foo')
         result1 = pi1.asfreq('3M')
         result2 = pi1.asfreq('M')
-        expected = PeriodIndex(freq='M', start='2001-12', end='2001-12')
+        expected = period_range(freq='M', start='2001-12', end='2001-12')
         tm.assert_numpy_array_equal(result1.asi8, expected.asi8)
         assert result1.freqstr == '3M'
         tm.assert_numpy_array_equal(result2.asi8, expected.asi8)
@@ -126,7 +126,7 @@ def test_asfreq_combined_pi(self):
             assert result.freq == exp.freq
 
     def test_asfreq_ts(self):
-        index = PeriodIndex(freq='A', start='1/1/2001', end='12/31/2010')
+        index = period_range(freq='A', start='1/1/2001', end='12/31/2010')
         ts = Series(np.random.randn(len(index)), index=index)
         df = DataFrame(np.random.randn(len(index), 3), index=index)
 

pandas/tests/indexes/period/test_construction.py

@@ -40,8 +40,12 @@ def test_construction_base_constructor(self):
     def test_constructor_use_start_freq(self):
         # GH #1118
         p = Period('4/2/2012', freq='B')
-        index = PeriodIndex(start=p, periods=10)
-        expected = PeriodIndex(start='4/2/2012', periods=10, freq='B')
+        with tm.assert_produces_warning(FutureWarning):
+            index = PeriodIndex(start=p, periods=10)
+        expected = period_range(start='4/2/2012', periods=10, freq='B')
+        tm.assert_index_equal(index, expected)
+
+        index = period_range(start=p, periods=10)
         tm.assert_index_equal(index, expected)
 
     def test_constructor_field_arrays(self):
@@ -93,7 +97,7 @@ def test_constructor_arrays_negative_year(self):
         years = np.arange(1960, 2000, dtype=np.int64).repeat(4)
         quarters = np.tile(np.array([1, 2, 3, 4], dtype=np.int64), 40)
 
-        pindex = PeriodIndex(year=years, quarter=quarters)
+        pindex = period_range(year=years, quarter=quarters)
 
         tm.assert_index_equal(pindex.year, pd.Index(years))
         tm.assert_index_equal(pindex.quarter, pd.Index(quarters))
@@ -320,19 +324,28 @@ def test_constructor_year_and_quarter(self):
     def test_constructor_freq_mult(self):
         # GH #7811
         for func in [PeriodIndex, period_range]:
-            # must be the same, but for sure...
-            pidx = func(start='2014-01', freq='2M', periods=4)
+
+            if func is PeriodIndex:
+                warning = FutureWarning
+            else:
+                warning = None
+
+            with tm.assert_produces_warning(warning):
+                # must be the same, but for sure...
+                pidx = func(start='2014-01', freq='2M', periods=4)
             expected = PeriodIndex(['2014-01', '2014-03',
                                     '2014-05', '2014-07'], freq='2M')
             tm.assert_index_equal(pidx, expected)
 
-            pidx = func(start='2014-01-02', end='2014-01-15', freq='3D')
+            with tm.assert_produces_warning(warning):
+                pidx = func(start='2014-01-02', end='2014-01-15', freq='3D')
             expected = PeriodIndex(['2014-01-02', '2014-01-05',
                                     '2014-01-08', '2014-01-11',
                                     '2014-01-14'], freq='3D')
             tm.assert_index_equal(pidx, expected)
 
-            pidx = func(end='2014-01-01 17:00', freq='4H', periods=3)
+            with tm.assert_produces_warning(warning):
+                pidx = func(end='2014-01-01 17:00', freq='4H', periods=3)
             expected = PeriodIndex(['2014-01-01 09:00', '2014-01-01 13:00',
                                     '2014-01-01 17:00'], freq='4H')
             tm.assert_index_equal(pidx, expected)
@@ -354,7 +367,7 @@ def test_constructor_freq_mult(self):
     @pytest.mark.parametrize('mult', [1, 2, 3, 4, 5])
     def test_constructor_freq_mult_dti_compat(self, mult, freq):
         freqstr = str(mult) + freq
-        pidx = PeriodIndex(start='2014-04-01', freq=freqstr, periods=10)
+        pidx = period_range(start='2014-04-01', freq=freqstr, periods=10)
         expected = date_range(start='2014-04-01', freq=freqstr,
                               periods=10).to_period(freqstr)
         tm.assert_index_equal(pidx, expected)
@@ -364,63 +377,68 @@ def test_constructor_freq_combined(self):
             pidx = PeriodIndex(['2016-01-01', '2016-01-02'], freq=freq)
             expected = PeriodIndex(['2016-01-01 00:00', '2016-01-02 00:00'],
                                    freq='25H')
-        for freq, func in zip(['1D1H', '1H1D'], [PeriodIndex, period_range]):
-            pidx = func(start='2016-01-01', periods=2, freq=freq)
+        for freq in ['1D1H', '1H1D']:
+            pidx = period_range(start='2016-01-01', periods=2, freq=freq)
             expected = PeriodIndex(['2016-01-01 00:00', '2016-01-02 01:00'],
                                    freq='25H')
             tm.assert_index_equal(pidx, expected)
 
+    def test_constructor_range_based_deprecated(self):
+        with tm.assert_produces_warning(FutureWarning):
+            pi = PeriodIndex(freq='A', start='1/1/2001', end='12/1/2009')
+        assert len(pi) == 9
+
     def test_constructor(self):
-        pi = PeriodIndex(freq='A', start='1/1/2001', end='12/1/2009')
+        pi = period_range(freq='A', start='1/1/2001', end='12/1/2009')
         assert len(pi) == 9
 
-        pi = PeriodIndex(freq='Q', start='1/1/2001', end='12/1/2009')
+        pi = period_range(freq='Q', start='1/1/2001', end='12/1/2009')
         assert len(pi) == 4 * 9
 
-        pi = PeriodIndex(freq='M', start='1/1/2001', end='12/1/2009')
+        pi = period_range(freq='M', start='1/1/2001', end='12/1/2009')
         assert len(pi) == 12 * 9
 
-        pi = PeriodIndex(freq='D', start='1/1/2001', end='12/31/2009')
+        pi = period_range(freq='D', start='1/1/2001', end='12/31/2009')
         assert len(pi) == 365 * 9 + 2
 
-        pi = PeriodIndex(freq='B', start='1/1/2001', end='12/31/2009')
+        pi = period_range(freq='B', start='1/1/2001', end='12/31/2009')
         assert len(pi) == 261 * 9
 
-        pi = PeriodIndex(freq='H', start='1/1/2001', end='12/31/2001 23:00')
+        pi = period_range(freq='H', start='1/1/2001', end='12/31/2001 23:00')
         assert len(pi) == 365 * 24
 
-        pi = PeriodIndex(freq='Min', start='1/1/2001', end='1/1/2001 23:59')
+        pi = period_range(freq='Min', start='1/1/2001', end='1/1/2001 23:59')
         assert len(pi) == 24 * 60
 
-        pi = PeriodIndex(freq='S', start='1/1/2001', end='1/1/2001 23:59:59')
+        pi = period_range(freq='S', start='1/1/2001', end='1/1/2001 23:59:59')
         assert len(pi) == 24 * 60 * 60
 
         start = Period('02-Apr-2005', 'B')
-        i1 = PeriodIndex(start=start, periods=20)
+        i1 = period_range(start=start, periods=20)
         assert len(i1) == 20
         assert i1.freq == start.freq
         assert i1[0] == start
 
         end_intv = Period('2006-12-31', 'W')
-        i1 = PeriodIndex(end=end_intv, periods=10)
+        i1 = period_range(end=end_intv, periods=10)
         assert len(i1) == 10
         assert i1.freq == end_intv.freq
         assert i1[-1] == end_intv
 
         end_intv = Period('2006-12-31', '1w')
-        i2 = PeriodIndex(end=end_intv, periods=10)
+        i2 = period_range(end=end_intv, periods=10)
         assert len(i1) == len(i2)
         assert (i1 == i2).all()
         assert i1.freq == i2.freq
 
         end_intv = Period('2006-12-31', ('w', 1))
-        i2 = PeriodIndex(end=end_intv, periods=10)
+        i2 = period_range(end=end_intv, periods=10)
         assert len(i1) == len(i2)
         assert (i1 == i2).all()
         assert i1.freq == i2.freq
 
         end_intv = Period('2005-05-01', 'B')
-        i1 = PeriodIndex(start=start, end=end_intv)
+        i1 = period_range(start=start, end=end_intv)
 
         # infer freq from first element
         i2 = PeriodIndex([end_intv, Period('2005-05-05', 'B')])
@@ -453,7 +471,7 @@ def test_constructor_error(self):
     @pytest.mark.parametrize('freq', ['M', 'Q', 'A', 'D', 'B',
                                       'T', 'S', 'L', 'U', 'N', 'H'])
     def test_recreate_from_data(self, freq):
-        org = PeriodIndex(start='2001/04/01', freq=freq, periods=1)
+        org = period_range(start='2001/04/01', freq=freq, periods=1)
         idx = PeriodIndex(org.values, freq=freq)
         tm.assert_index_equal(idx, org)
 

pandas/tests/indexes/period/test_indexing.py

@@ -147,7 +147,8 @@ def test_getitem_seconds(self):
         # GH#6716
         didx = pd.date_range(start='2013/01/01 09:00:00', freq='S',
                              periods=4000)
-        pidx = PeriodIndex(start='2013/01/01 09:00:00', freq='S', periods=4000)
+        pidx = period_range(start='2013/01/01 09:00:00', freq='S',
+                            periods=4000)
 
         for idx in [didx, pidx]:
             # getitem against index should raise ValueError
@@ -171,7 +172,7 @@ def test_getitem_day(self):
         # GH#6716
         # Confirm DatetimeIndex and PeriodIndex works identically
         didx = pd.date_range(start='2013/01/01', freq='D', periods=400)
-        pidx = PeriodIndex(start='2013/01/01', freq='D', periods=400)
+        pidx = period_range(start='2013/01/01', freq='D', periods=400)
 
         for idx in [didx, pidx]:
             # getitem against index should raise ValueError
@@ -281,8 +282,8 @@ def test_take(self):
             assert result.freq == 'D'
 
     def test_take_misc(self):
-        index = PeriodIndex(start='1/1/10', end='12/31/12', freq='D',
-                            name='idx')
+        index = period_range(start='1/1/10', end='12/31/12', freq='D',
+                             name='idx')
         expected = PeriodIndex([datetime(2010, 1, 6), datetime(2010, 1, 7),
                                 datetime(2010, 1, 9), datetime(2010, 1, 13)],
                                freq='D', name='idx')