Fix docstrings for pandas.Period.month

Author: uditbaliyan

ci/code_checks.sh

@@ -79,7 +79,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Period.asfreq SA01" \
         -i "pandas.Period.freq GL08" \
         -i "pandas.Period.freqstr SA01" \
-        -i "pandas.Period.month SA01" \
         -i "pandas.Period.ordinal GL08" \
         -i "pandas.Period.strftime PR01,SA01" \
         -i "pandas.Period.to_timestamp SA01" \

pandas/_libs/tslibs/period.pyx

@@ -2011,15 +2011,61 @@ cdef class _Period(PeriodMixin):
 
     @property
     def month(self) -> int:
-        """
-        Return the month this Period falls on.
+    """
+    Return the month this Period falls on.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    int : The month number of the Period.
+
+    See Also
+    --------
+    period.week : Get the week of the year on the given Period.
+    Period.year : Return the year this Period falls on.
+    Period.day : Return the day of the month this Period falls on.
+
+
+    Examples
+    --------
+    Create a Period object for January 2022 and get the month:
+
+    >>> period = pd.Period('2022-01', 'M')
+    >>> period.month
+    1
+
+    Create a Period object with no specified frequency, resulting in a default frequency:
+
+    >>> period = pd.Period('2022', 'Y')
+    >>> period.month
+    12
+
+    Create a Period object with a specified frequency but an incomplete date string:
+
+    >>> period = pd.Period('2022', 'M')
+    >>> period.month
+    1
+
+    Handle a case where the Period object is invalid or empty, which results in `NaN`:
+
+    >>> period = pd.Period('nan', 'M')
+    >>> period.month
+    nan
+
+    Handle a case where the Period object is invalid or empty, which results in `NaN`:
+
+    >>> period = pd.Period('nan', 'M')
+    >>> period.month
+    nan
+
+    Notes
+    -----
+    The month is determined based on the `ordinal` and `base` attributes of the Period.
+    """
 
-        Examples
-        --------
-        >>> period = pd.Period('2022-01', 'M')
-        >>> period.month
-        1
-        """
         base = self._dtype._dtype_code
         return pmonth(self.ordinal, base)