API: Implement set_freq for DTI/TDI, deprecate freq setter

Author: jschendel

doc/source/whatsnew/v0.23.0.txt

@@ -523,6 +523,7 @@ Other Enhancements
   library. (:issue:`20564`)
 - Added new writer for exporting Stata dta files in version 117, ``StataWriter117``.  This format supports exporting strings with lengths up to 2,000,000 characters (:issue:`16450`)
 - :func:`to_hdf` and :func:`read_hdf` now accept an ``errors`` keyword argument to control encoding error handling (:issue:`20835`)
+- :meth:`DatetimeIndex.set_freq` and :meth:`TimedeltaIndex.set_freq` are now available for setting the ``.freq`` attribute (:issue:`20886`)
 
 .. _whatsnew_0230.api_breaking:
 
@@ -997,6 +998,7 @@ Deprecations
 - Setting ``PeriodIndex.freq`` (which was not guaranteed to work correctly) is deprecated. Use :meth:`PeriodIndex.asfreq` instead (:issue:`20678`)
 - ``Index.get_duplicates()`` is deprecated and will be removed in a future version (:issue:`20239`)
 - The previous default behavior of negative indices in ``Categorical.take`` is deprecated. In a future version it will change from meaning missing values to meaning positional indices from the right. The future behavior is consistent with :meth:`Series.take` (:issue:`20664`).
+- Setting the ``.freq`` attribute is deprecated for :class:`DatetimeIndex` and :class:`TimedeltaIndex`. Use the associated ``.set_freq()`` method instead (:issue:`20886`)
 
 
 .. _whatsnew_0230.prior_deprecations:

pandas/core/indexes/datetimelike.py

@@ -236,12 +236,44 @@ def freq(self):
 
     @freq.setter
     def freq(self, value):
+        msg = ('Setting {obj}.freq has been deprecated and will be removed '
+               'in a future version; use {obj}.set_freq instead.'
+               ).format(obj=type(self).__name__)
+        warnings.warn(msg, FutureWarning, stacklevel=2)
         if value is not None:
             value = frequencies.to_offset(value)
             self._validate_frequency(self, value)
 
         self._freq = value
 
+    def set_freq(self, freq):
+        """
+        Set the frequency of the DatetimeIndex or TimedeltaIndex to the
+        specified frequency `freq`.
+
+        Parameters
+        ----------
+        freq: str or Offset
+            The frequency to set on the DatetimeIndex or TimedeltaIndex
+
+        Returns
+        -------
+        new: DatetimeIndex or TimedeltaIndex with the new frequency
+
+        Raises
+        ------
+        ValueError
+            If the values of the DatetimeIndex or TimedeltaIndex are not
+            compatible with the new frequency
+        """
+        if freq is not None:
+            freq = frequencies.to_offset(freq)
+            self._validate_frequency(self, freq)
+
+        new = self.copy()
+        new._freq = freq
+        return new
+
 
 class DatetimeIndexOpsMixin(object):
     """ common ops mixin to support a unified interface datetimelike Index """

pandas/core/indexes/datetimes.py

@@ -250,6 +250,7 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin,
     normalize
     strftime
     snap
+    set_freq
     tz_convert
     tz_localize
     round
@@ -459,7 +460,7 @@ def __new__(cls, data=None,
         if freq_infer:
             inferred = subarr.inferred_freq
             if inferred:
-                subarr.freq = to_offset(inferred)
+                subarr._freq = to_offset(inferred)
 
         return subarr._deepcopy_if_needed(ref_to_data, copy)
 
@@ -751,7 +752,7 @@ def _cached_range(cls, start=None, end=None, periods=None, freq=None,
             arr = tools.to_datetime(list(xdr), box=False)
 
             cachedRange = DatetimeIndex._simple_new(arr)
-            cachedRange.freq = freq
+            cachedRange._freq = freq
             cachedRange = cachedRange.tz_localize(None)
             cachedRange.name = None
             drc[freq] = cachedRange
@@ -786,7 +787,7 @@ def _cached_range(cls, start=None, end=None, periods=None, freq=None,
 
         indexSlice = cachedRange[startLoc:endLoc]
         indexSlice.name = name
-        indexSlice.freq = freq
+        indexSlice._freq = freq
 
         return indexSlice
 
@@ -1176,7 +1177,7 @@ def union(self, other):
                 result._tz = timezones.tz_standardize(this.tz)
                 if (result.freq is None and
                         (this.freq is not None or other.freq is not None)):
-                    result.freq = to_offset(result.inferred_freq)
+                    result._freq = to_offset(result.inferred_freq)
             return result
 
     def to_perioddelta(self, freq):
@@ -1224,7 +1225,7 @@ def union_many(self, others):
                     this._tz = timezones.tz_standardize(tz)
 
         if this.freq is None:
-            this.freq = to_offset(this.inferred_freq)
+            this._freq = to_offset(this.inferred_freq)
         return this
 
     def join(self, other, how='left', level=None, return_indexers=False,
@@ -1385,7 +1386,7 @@ def intersection(self, other):
             result = Index.intersection(self, other)
             if isinstance(result, DatetimeIndex):
                 if result.freq is None:
-                    result.freq = to_offset(result.inferred_freq)
+                    result._freq = to_offset(result.inferred_freq)
             return result
 
         elif (other.freq is None or self.freq is None or
@@ -1396,7 +1397,7 @@ def intersection(self, other):
             result = self._shallow_copy(result._values, name=result.name,
                                         tz=result.tz, freq=None)
             if result.freq is None:
-                result.freq = to_offset(result.inferred_freq)
+                result._freq = to_offset(result.inferred_freq)
             return result
 
         if len(self) == 0:
@@ -1730,9 +1731,13 @@ def offset(self):
     def offset(self, value):
         """get/set the frequency of the Index"""
         msg = ('DatetimeIndex.offset has been deprecated and will be removed '
-               'in a future version; use DatetimeIndex.freq instead.')
+               'in a future version; use DatetimeIndex.set_freq instead.')
         warnings.warn(msg, FutureWarning, stacklevel=2)
-        self.freq = value
+        if value is not None:
+            value = to_offset(value)
+            self._validate_frequency(self, value)
+
+        self._freq = value
 
     year = _field_accessor('year', 'Y', "The year of the datetime")
     month = _field_accessor('month', 'M',

pandas/core/indexes/timedeltas.py

@@ -149,6 +149,7 @@ class TimedeltaIndex(DatetimeIndexOpsMixin, TimelikeOps, Int64Index):
 
     Methods
     -------
+    set_freq
     to_pytimedelta
     to_series
     round
@@ -253,14 +254,14 @@ def __new__(cls, data=None, unit=None, freq=None, start=None, end=None,
             if freq is not None and not freq_infer:
                 index = cls._simple_new(data, name=name)
                 cls._validate_frequency(index, freq)
-                index.freq = freq
+                index._freq = freq
                 return index
 
         if freq_infer:
             index = cls._simple_new(data, name=name)
             inferred = index.inferred_freq
             if inferred:
-                index.freq = to_offset(inferred)
+                index._freq = to_offset(inferred)
             return index
 
         return cls._simple_new(data, name=name, freq=freq)
@@ -598,7 +599,7 @@ def union(self, other):
             result = Index.union(this, other)
             if isinstance(result, TimedeltaIndex):
                 if result.freq is None:
-                    result.freq = to_offset(result.inferred_freq)
+                    result._freq = to_offset(result.inferred_freq)
             return result
 
     def join(self, other, how='left', level=None, return_indexers=False,

pandas/core/resample.py

@@ -904,7 +904,7 @@ def _downsample(self, how, **kwargs):
         if not len(ax):
             # reset to the new freq
             obj = obj.copy()
-            obj.index.freq = self.freq
+            obj.index = obj.index.set_freq(self.freq)
             return obj
 
         # do we have a regular frequency

pandas/tests/categorical/test_constructors.py

@@ -256,36 +256,31 @@ def test_constructor_with_generator(self):
         cat = Categorical([0, 1, 2], categories=xrange(3))
         tm.assert_categorical_equal(cat, exp)
 
-    def test_constructor_with_datetimelike(self):
-
+    @pytest.mark.parametrize('dtl', [
+        date_range('1995-01-01', periods=5, freq='s'),
+        date_range('1995-01-01', periods=5, freq='s', tz='US/Eastern'),
+        timedelta_range('1 day', periods=5, freq='s')])
+    def test_constructor_with_datetimelike(self, dtl):
         # 12077
         # constructor wwth a datetimelike and NaT
+        s = Series(dtl)
+        c = Categorical(s)
+        expected = dtl._constructor(s).set_freq(None)
+        tm.assert_index_equal(c.categories, expected)
+        tm.assert_numpy_array_equal(c.codes, np.arange(5, dtype='int8'))
+
+        # with NaT
+        s2 = s.copy()
+        s2.iloc[-1] = NaT
+        c = Categorical(s2)
+        expected = dtl._constructor(s2.dropna()).set_freq(None)
+        tm.assert_index_equal(c.categories, expected)
+
+        exp = np.array([0, 1, 2, 3, -1], dtype=np.int8)
+        tm.assert_numpy_array_equal(c.codes, exp)
 
-        for dtl in [date_range('1995-01-01 00:00:00', periods=5, freq='s'),
-                    date_range('1995-01-01 00:00:00', periods=5,
-                               freq='s', tz='US/Eastern'),
-                    timedelta_range('1 day', periods=5, freq='s')]:
-
-            s = Series(dtl)
-            c = Categorical(s)
-            expected = type(dtl)(s)
-            expected.freq = None
-            tm.assert_index_equal(c.categories, expected)
-            tm.assert_numpy_array_equal(c.codes, np.arange(5, dtype='int8'))
-
-            # with NaT
-            s2 = s.copy()
-            s2.iloc[-1] = NaT
-            c = Categorical(s2)
-            expected = type(dtl)(s2.dropna())
-            expected.freq = None
-            tm.assert_index_equal(c.categories, expected)
-
-            exp = np.array([0, 1, 2, 3, -1], dtype=np.int8)
-            tm.assert_numpy_array_equal(c.codes, exp)
-
-            result = repr(c)
-            assert 'NaT' in result
+        result = repr(c)
+        assert 'NaT' in result
 
     def test_constructor_from_index_series_datetimetz(self):
         idx = date_range('2015-01-01 10:00', freq='D', periods=3,

pandas/tests/indexes/datetimelike.py

@@ -67,7 +67,7 @@ def test_map_dictlike(self, mapper):
 
         # don't compare the freqs
         if isinstance(expected, pd.DatetimeIndex):
-            expected.freq = None
+            expected = expected.set_freq(None)
 
         result = self.index.map(mapper(expected, self.index))
         tm.assert_index_equal(result, expected)
@@ -88,3 +88,15 @@ def test_asobject_deprecated(self):
         with tm.assert_produces_warning(FutureWarning):
             i = d.asobject
         assert isinstance(i, pd.Index)
+
+    def test_freq_setter_deprecated(self):
+        # GH 20678/20886
+        idx = self.create_index()
+
+        # no warning for getter
+        with tm.assert_produces_warning(None):
+            idx.freq
+
+        # warning for setter
+        with tm.assert_produces_warning(FutureWarning):
+            idx.freq = pd.offsets.Day()

pandas/tests/indexes/datetimes/test_date_range.py

@@ -379,6 +379,7 @@ def test_misc(self):
         assert len(dr) == 20
         assert dr[0] == firstDate
         assert dr[-1] == end
+        assert dr.freq == BDay()
 
     def test_date_parse_failure(self):
         badly_formed_date = '2007/100/1'
@@ -399,7 +400,6 @@ def test_daterange_bug_456(self):
         # GH #456
         rng1 = bdate_range('12/5/2011', '12/5/2011')
         rng2 = bdate_range('12/2/2011', '12/5/2011')
-        rng2.freq = BDay()
 
         result = rng1.union(rng2)
         assert isinstance(result, DatetimeIndex)
@@ -641,12 +641,12 @@ def test_misc(self):
         assert len(dr) == 20
         assert dr[0] == firstDate
         assert dr[-1] == end
+        assert dr.freq == CDay()
 
     def test_daterange_bug_456(self):
         # GH #456
         rng1 = bdate_range('12/5/2011', '12/5/2011', freq='C')
         rng2 = bdate_range('12/2/2011', '12/5/2011', freq='C')
-        rng2.freq = CDay()
 
         result = rng1.union(rng2)
         assert isinstance(result, DatetimeIndex)

pandas/tests/indexes/datetimes/test_ops.py

@@ -406,37 +406,75 @@ def test_equals(self):
         assert not idx.equals(list(idx3))
         assert not idx.equals(pd.Series(idx3))
 
+    @pytest.mark.parametrize('values', [
+        ['20180101', '20180103', '20180105'], []])
+    @pytest.mark.parametrize('freq', [
+        '2D', Day(2), '2B', BDay(2), '48H', Hour(48)])
+    @pytest.mark.parametrize('tz', [None, 'US/Eastern'])
+    def test_set_freq(self, values, freq, tz):
+        # GH 20886
+        idx = DatetimeIndex(values, tz=tz)
+
+        # can set to an offset, converting from string if necessary
+        idx = idx.set_freq(freq)
+        assert idx.freq == freq
+        assert isinstance(idx.freq, ABCDateOffset)
+
+        # can reset to None
+        idx = idx.set_freq(None)
+        assert idx.freq is None
+
+    def test_set_freq_errors(self):
+        # GH 20886
+        idx = DatetimeIndex(['20180101', '20180103', '20180105'])
+
+        # setting with an incompatible freq
+        msg = ('Inferred frequency 2D from passed values does not conform to '
+               'passed frequency 5D')
+        with tm.assert_raises_regex(ValueError, msg):
+            idx.set_freq('5D')
+
+        # setting with non-freq string
+        with tm.assert_raises_regex(ValueError, 'Invalid frequency'):
+            idx.set_freq('foo')
+
     @pytest.mark.parametrize('values', [
         ['20180101', '20180103', '20180105'], []])
     @pytest.mark.parametrize('freq', [
         '2D', Day(2), '2B', BDay(2), '48H', Hour(48)])
     @pytest.mark.parametrize('tz', [None, 'US/Eastern'])
     def test_freq_setter(self, values, freq, tz):
-        # GH 20678
+        # GH 20678/20886
         idx = DatetimeIndex(values, tz=tz)
 
         # can set to an offset, converting from string if necessary
-        idx.freq = freq
+        with tm.assert_produces_warning(FutureWarning):
+            idx.freq = freq
+
         assert idx.freq == freq
         assert isinstance(idx.freq, ABCDateOffset)
 
         # can reset to None
-        idx.freq = None
+        with tm.assert_produces_warning(FutureWarning):
+            idx.freq = None
+
         assert idx.freq is None
 
     def test_freq_setter_errors(self):
-        # GH 20678
+        # GH 20678/20886
         idx = DatetimeIndex(['20180101', '20180103', '20180105'])
 
         # setting with an incompatible freq
         msg = ('Inferred frequency 2D from passed values does not conform to '
                'passed frequency 5D')
         with tm.assert_raises_regex(ValueError, msg):
-            idx.freq = '5D'
+            with tm.assert_produces_warning(FutureWarning):
+                idx.freq = '5D'
 
         # setting with non-freq string
         with tm.assert_raises_regex(ValueError, 'Invalid frequency'):
-            idx.freq = 'foo'
+            with tm.assert_produces_warning(FutureWarning):
+                idx.freq = 'foo'
 
     def test_offset_deprecated(self):
         # GH 20716

pandas/tests/indexes/datetimes/test_setops.py

@@ -91,9 +91,7 @@ def test_union_bug_4564(self):
 
     def test_union_freq_both_none(self):
         # GH11086
-        expected = bdate_range('20150101', periods=10)
-        expected.freq = None
-
+        expected = bdate_range('20150101', periods=10).set_freq(None)
         result = expected.union(expected)
         tm.assert_index_equal(result, expected)
         assert result.freq is None