From 99d92d90c217b16855c87f983ddd854d6429f369 Mon Sep 17 00:00:00 2001
From: Ahmed Nabil <hhtg250@gmail.com>
Date: Wed, 24 Sep 2025 02:38:43 +0300
Subject: [PATCH 1/2] DOC: Fix pandas.Period.freq docstring validation (GL08)

- Convert freq from cdef readonly to @property with proper docstring
- Add comprehensive NumPy-style docstring following pandas standards
- Include Returns, See Also, and Examples sections
- Remove pandas.Period.freq GL08 from ci/code_checks.sh ignore list

Part of #58063
---
 ci/code_checks.sh              |  1 -
 pandas/_libs/tslibs/period.pyx | 41 ++++++++++++++++++++++++++++++----
 2 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 68ca06564d3a6..ff930b134e058 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -70,7 +70,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         --format=actions \
         -i ES01 `# For now it is ok if docstrings are missing the extended summary` \
         -i "pandas.Series.dt PR01" `# Accessors are implemented as classes, but we do not document the Parameters section` \
-        -i "pandas.Period.freq GL08" \
         -i "pandas.Period.ordinal GL08" \
         -i "pandas.errors.IncompatibleFrequency SA01,SS06,EX01" \
         -i "pandas.api.extensions.ExtensionArray.value_counts EX01,RT03,SA01" \
diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx
index 95a18f8cb2cad..40b772cd67050 100644
--- a/pandas/_libs/tslibs/period.pyx
+++ b/pandas/_libs/tslibs/period.pyx
@@ -1746,7 +1746,9 @@ cdef class _Period(PeriodMixin):
     cdef readonly:
         int64_t ordinal
         PeriodDtypeBase _dtype
-        BaseOffset freq
+    
+    cdef:
+        BaseOffset _freq
 
     # higher than np.ndarray, np.matrix, np.timedelta64
     __array_priority__ = 100
@@ -1756,9 +1758,40 @@ cdef class _Period(PeriodMixin):
 
     def __cinit__(self, int64_t ordinal, BaseOffset freq):
         self.ordinal = ordinal
-        self.freq = freq
+        self._freq = freq
         self._dtype = PeriodDtypeBase(freq._period_dtype_code, freq.n)
 
+    @property
+    def freq(self) -> BaseOffset:
+        """
+        Get the frequency object of the Period.
+
+        The frequency represents the span of the period. This can be any valid
+        pandas frequency string (e.g., 'D' for daily, 'M' for monthly) or a
+        DateOffset object.
+
+        Returns
+        -------
+        BaseOffset
+            The frequency object of the Period.
+
+        See Also
+        --------
+        Period.freqstr : Return a string representation of the frequency.
+        Period.asfreq : Convert Period to desired frequency.
+
+        Examples
+        --------
+        >>> period = pd.Period('2020-01', freq='M')
+        >>> period.freq
+        <MonthEnd>
+        
+        >>> period = pd.Period('2020-01-01', freq='D')
+        >>> period.freq
+        <Day>
+        """
+        return self._freq
+
     @classmethod
     def _maybe_convert_freq(cls, object freq) -> BaseOffset:
         """
@@ -2660,11 +2693,11 @@ cdef class _Period(PeriodMixin):
         return value
 
     def __setstate__(self, state):
-        self.freq = state[1]
+        self._freq = state[1]
         self.ordinal = state[2]
 
     def __reduce__(self):
-        object_state = None, self.freq, self.ordinal
+        object_state = None, self._freq, self.ordinal
         return (Period, object_state)
 
     def strftime(self, fmt: str | None) -> str:

From 2a75a22156e25db42d60dc6541afde2f01c8c4d7 Mon Sep 17 00:00:00 2001
From: Ahmed Nabil <hhtg250@gmail.com>
Date: Sat, 27 Sep 2025 10:33:11 +0300
Subject: [PATCH 2/2] Fix whitespace issues in period.pyx

- Remove trailing whitespace from blank lines
- Fix formatting to pass CI pre-commit hooks
---
 pandas/_libs/tslibs/period.pyx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx
index 40b772cd67050..ede2a5829f17a 100644
--- a/pandas/_libs/tslibs/period.pyx
+++ b/pandas/_libs/tslibs/period.pyx
@@ -1746,7 +1746,7 @@ cdef class _Period(PeriodMixin):
     cdef readonly:
         int64_t ordinal
         PeriodDtypeBase _dtype
-    
+
     cdef:
         BaseOffset _freq
 
@@ -1785,7 +1785,7 @@ cdef class _Period(PeriodMixin):
         >>> period = pd.Period('2020-01', freq='M')
         >>> period.freq
         <MonthEnd>
-        
+
         >>> period = pd.Period('2020-01-01', freq='D')
         >>> period.freq
         <Day>