From 8169e4ecf62c21b0338c3529c6803cb8b7a460a1 Mon Sep 17 00:00:00 2001
From: uditbaliyan <baliyanvdit@gmail.com>
Date: Thu, 15 Aug 2024 23:39:27 +0530
Subject: [PATCH 1/4] Fix docstrings for pandas.Period.year SA01

---
 ci/code_checks.sh              |  1 -
 pandas/_libs/tslibs/period.pyx | 42 ++++++++++++++++++++++++++++++++--
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 50cea056b9204..dbfe0230d835c 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -79,7 +79,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Period.ordinal GL08" \
         -i "pandas.Period.strftime PR01,SA01" \
         -i "pandas.Period.to_timestamp SA01" \
-        -i "pandas.Period.year SA01" \
         -i "pandas.PeriodDtype SA01" \
         -i "pandas.PeriodDtype.freq SA01" \
         -i "pandas.PeriodIndex.day SA01" \
diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx
index 84d9b57340ed4..2130a10d0f724 100644
--- a/pandas/_libs/tslibs/period.pyx
+++ b/pandas/_libs/tslibs/period.pyx
@@ -2038,11 +2038,49 @@ cdef class _Period(PeriodMixin):
         """
         Return the year this Period falls on.
 
+        Returns
+        -------
+        int
+            The year (e.g., 2023)
+
+        See Also
+        --------
+        period.month : Get the month of the year on the given Period.
+        period.day : Return the day of the month the Period falls on.
+
+        Notes
+        -----
+        The year is based on the `ordinal` and `base` attributes of the Period.
+
         Examples
         --------
-        >>> period = pd.Period('2022-01', 'M')
+        Create a Period object for January 2023 and get the year:
+
+        >>> period = pd.Period('2023-01', 'M')
         >>> period.year
-        2022
+        2023
+
+        Create a Period object for 01 January 2023 and get the year:
+        >>> period = pd.Period('2023', 'D')
+        >>> period.year
+        2023
+
+        Get the year for a period representing a quarter:
+
+        >>> period = pd.Period('2023Q2', 'Q')
+        >>> period.year
+        2023
+
+        Handle a case where the Period object is empty, which results in `NaN`:
+
+        >>> period = pd.Period('nan', 'M')
+        >>> period.month
+        nan
+
+        Period object with an invalid format:
+
+        >>> period = pd.Period('invalid', 'M')
+            # Will raise an DateParseError
         """
         base = self._dtype._dtype_code
         return pyear(self.ordinal, base)

From cde723f06927acf41f1fb7d8745306d93c84689f Mon Sep 17 00:00:00 2001
From: uditbaliyan <baliyanvdit@gmail.com>
Date: Fri, 16 Aug 2024 00:02:24 +0530
Subject: [PATCH 2/4] Fix docstrings for pandas.Period.year SA01 Validate
 Docstrings err

---
 pandas/_libs/tslibs/period.pyx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx
index 2130a10d0f724..45044888d435d 100644
--- a/pandas/_libs/tslibs/period.pyx
+++ b/pandas/_libs/tslibs/period.pyx
@@ -2041,7 +2041,6 @@ cdef class _Period(PeriodMixin):
         Returns
         -------
         int
-            The year (e.g., 2023)
 
         See Also
         --------

From f52c61080a331597197711465742ace1bdfcd1dd Mon Sep 17 00:00:00 2001
From: uditbaliyan <baliyanvdit@gmail.com>
Date: Fri, 16 Aug 2024 00:38:12 +0530
Subject: [PATCH 3/4] Fix docstrings for pandas.Period.year SA01 Validate
 Docstrings err

---
 pandas/_libs/tslibs/period.pyx | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx
index 45044888d435d..cdeca432ffc91 100644
--- a/pandas/_libs/tslibs/period.pyx
+++ b/pandas/_libs/tslibs/period.pyx
@@ -2044,7 +2044,7 @@ cdef class _Period(PeriodMixin):
 
         See Also
         --------
-        period.month : Get the month of the year on the given Period.
+        period.month : Get the month of the year for the given Period.
         period.day : Return the day of the month the Period falls on.
 
         Notes
@@ -2060,9 +2060,10 @@ cdef class _Period(PeriodMixin):
         2023
 
         Create a Period object for 01 January 2023 and get the year:
+
         >>> period = pd.Period('2023', 'D')
-        >>> period.year
-        2023
+        >>> period.year
+        2023
 
         Get the year for a period representing a quarter:
 
@@ -2073,13 +2074,13 @@ cdef class _Period(PeriodMixin):
         Handle a case where the Period object is empty, which results in `NaN`:
 
         >>> period = pd.Period('nan', 'M')
-        >>> period.month
+        >>> period.year
         nan
 
         Period object with an invalid format:
 
         >>> period = pd.Period('invalid', 'M')
-            # Will raise an DateParseError
+        # Will raise a DateParseError
         """
         base = self._dtype._dtype_code
         return pyear(self.ordinal, base)

From cdf36b2faa6c95848d6210c801ee287f0b7084fd Mon Sep 17 00:00:00 2001
From: Udit Baliyan <130930448+uditbaliyan@users.noreply.github.com>
Date: Fri, 16 Aug 2024 07:41:03 +0530
Subject: [PATCH 4/4] Removed dateparseerror example from period.year

Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com>
---
 pandas/_libs/tslibs/period.pyx | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx
index cdeca432ffc91..4f5dfc75a20bf 100644
--- a/pandas/_libs/tslibs/period.pyx
+++ b/pandas/_libs/tslibs/period.pyx
@@ -2076,11 +2076,6 @@ cdef class _Period(PeriodMixin):
         >>> period = pd.Period('nan', 'M')
         >>> period.year
         nan
-
-        Period object with an invalid format:
-
-        >>> period = pd.Period('invalid', 'M')
-        # Will raise a DateParseError
         """
         base = self._dtype._dtype_code
         return pyear(self.ordinal, base)