Add note in whatsnew; address reviewer requests

pandas-dev · jreback · Aug 24, 2017 · Aug 12, 2017 · Aug 12, 2017 · Aug 13, 2017
commit b86a7b9f455c154bafb674a210afd2b6f0c2915a
diff --git a/doc/source/whatsnew/v0.21.0.txt b/doc/source/whatsnew/v0.21.0.txt
@@ -132,6 +132,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

diff --git a/pandas/_libs/period.pyx b/pandas/_libs/period.pyx
@@ -18,7 +18,6 @@ from pandas import compat
 from pandas.compat import PY2
 
 cimport cython
-# this is _libs.src.datetime, not python stdlib
 from datetime cimport *
 
 cimport util, lib

diff --git a/pandas/tests/scalar/test_period.py b/pandas/tests/scalar/test_period.py
@@ -1406,3 +1406,13 @@ 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
diff --git a/pandas/tests/test_lib.py b/pandas/tests/test_lib.py
@@ -248,13 +248,3 @@ def test_empty_like(self):
         expected = np.array([True])
 
         self._check_behavior(arr, expected)
-
-
-def test_period_immutable():
-    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