Make pd.Period immutable

doc/source/whatsnew/v0.21.0.txt

@@ -138,6 +138,16 @@ Other Enhancements
 Backwards incompatible API changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. _whatsnew_0210.api_breaking.Period:
+
+pd.Period objects are now immutable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`Period` will now raise an ``AttributeError`` when a user tries to
+assign a new value to the `ordinal` or `freq` attributes.  This will allow
+for reliable caching which will improve performance in indexing
+operations (:issue:`17116`).
+
 .. _whatsnew_0210.api_breaking.pandas_eval:
 
 Improved error handling during item assignment in pd.eval

pandas/_libs/period.pyx

@@ -29,7 +29,9 @@ from datetime cimport (
     PANDAS_FR_ns,
     INT32_MIN)
 
+
 cimport util, lib
+
 from lib cimport is_null_datetimelike, is_period
 from pandas._libs import tslib, lib
 from pandas._libs.tslib import (Timedelta, Timestamp, iNaT,
@@ -688,13 +690,17 @@ class IncompatibleFrequency(ValueError):
 
 cdef class _Period(object):
 
-    cdef public:
+    cdef readonly:
         int64_t ordinal
         object freq
 
     _comparables = ['name', 'freqstr']
     _typ = 'period'
 
+    def __cinit__(self, ordinal, freq):
+        self.ordinal = ordinal
+        self.freq = freq
+
     @classmethod
     def _maybe_convert_freq(cls, object freq):
 
@@ -718,9 +724,8 @@ cdef class _Period(object):
         if ordinal == iNaT:
             return NaT
         else:
-            self = _Period.__new__(cls)
-            self.ordinal = ordinal
-            self.freq = cls._maybe_convert_freq(freq)
+            freq = cls._maybe_convert_freq(freq)
+            self = _Period.__new__(cls, ordinal, freq)
             return self
 
     def __richcmp__(self, other, op):
@@ -772,7 +777,7 @@ cdef class _Period(object):
     def __add__(self, other):
         if isinstance(self, Period):
             if isinstance(other, (timedelta, np.timedelta64,
-                                  offsets.Tick, offsets.DateOffset,
+                                  offsets.DateOffset,
                                   Timedelta)):
                 return self._add_delta(other)
             elif other is NaT:
@@ -790,7 +795,7 @@ cdef class _Period(object):
     def __sub__(self, other):
         if isinstance(self, Period):
             if isinstance(other, (timedelta, np.timedelta64,
-                                  offsets.Tick, offsets.DateOffset,
+                                  offsets.DateOffset,
                                   Timedelta)):
                 neg_other = -other
                 return self + neg_other

pandas/tests/scalar/test_period.py

@@ -1406,3 +1406,14 @@ def test_period_ops_offset(self):
 
         with tm.assert_raises_regex(period.IncompatibleFrequency, msg):
             p - offsets.Hour(2)
+
+
+def test_period_immutable():
+    # see gh-17116
+    per = pd.Period('2014Q1')
+    with pytest.raises(AttributeError, message="is not writable"):
+        per.ordinal = 14
+
+    freq = per.freq
+    with pytest.raises(AttributeError, message="is not writable"):
+        per.freq = 2 * freq