From ff4aa150f7cb0ba86e9f4608f5a9a8c0f1d41a48 Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Fri, 18 Apr 2025 09:43:15 -0400
Subject: [PATCH 1/7] type pct_change kwargs according to shift params

---
 pandas-stubs/_typing.pyi     | 8 +++++++-
 pandas-stubs/core/frame.pyi  | 4 +++-
 pandas-stubs/core/series.pyi | 4 +++-
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/pandas-stubs/_typing.pyi b/pandas-stubs/_typing.pyi
index 2655f09f..c8d5283e 100644
--- a/pandas-stubs/_typing.pyi
+++ b/pandas-stubs/_typing.pyi
@@ -8,7 +8,7 @@ from collections.abc import (
     Sequence,
 )
 import datetime
-from datetime import tzinfo
+from datetime import timedelta, tzinfo
 from os import PathLike
 from re import Pattern
 import sys
@@ -842,4 +842,10 @@ IntoColumn: TypeAlias = (
     AnyArrayLike | Scalar | Callable[[DataFrame], AnyArrayLike | Scalar]
 )
 
+class PctChangeKwargs(TypedDict, total=False):
+    periods: int
+    freq: Frequency | timedelta | None
+    axis: AxisIndex
+    fill_value: object | None
+
 __all__ = ["npt", "type_t"]
diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi
index cbaa3096..509c6516 100644
--- a/pandas-stubs/core/frame.pyi
+++ b/pandas-stubs/core/frame.pyi
@@ -16,6 +16,7 @@ from typing import (
     Literal,
     NoReturn,
     overload,
+    Unpack,
 )
 
 from _typing import TimeZones
@@ -113,6 +114,7 @@ from pandas._typing import (
     NaPosition,
     NDFrameT,
     ParquetEngine,
+    PctChangeKwargs,
     QuantileInterpolation,
     RandomState,
     ReadBuffer,
@@ -1991,7 +1993,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         fill_method: None = ...,
         limit: int | None = ...,
         freq=...,
-        **kwargs: Any,  # TODO: make more precise https://github.com/pandas-dev/pandas-stubs/issues/1169
+        **kwargs: Unpack[PctChangeKwargs],
     ) -> Self: ...
     def pop(self, item: _str) -> Series: ...
     def pow(
diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi
index c6b7f8d5..dd040355 100644
--- a/pandas-stubs/core/series.pyi
+++ b/pandas-stubs/core/series.pyi
@@ -22,6 +22,7 @@ from typing import (
     Literal,
     NoReturn,
     overload,
+    Unpack,
 )
 
 from _typing import (
@@ -143,6 +144,7 @@ from pandas._typing import (
     MaskType,
     NaPosition,
     ObjectDtypeArg,
+    PctChangeKwargs,
     QuantileInterpolation,
     RandomState,
     Renamer,
@@ -1552,7 +1554,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         fill_method: _str = ...,
         limit: int | None = ...,
         freq=...,
-        **kwargs: Any,  # TODO: make more precise https://github.com/pandas-dev/pandas-stubs/issues/1169
+        **kwargs: Unpack[PctChangeKwargs],
     ) -> Series[S1]: ...
     def first_valid_index(self) -> Scalar: ...
     def last_valid_index(self) -> Scalar: ...

From b67e8e90c32cd29deb97d665a1e0699a3ce1e5af Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Tue, 22 Apr 2025 21:08:30 +0800
Subject: [PATCH 2/7] remove duplicate params and add defaults

---
 pandas-stubs/_typing.pyi     | 4 +---
 pandas-stubs/core/frame.pyi  | 6 +++---
 pandas-stubs/core/series.pyi | 8 ++++----
 3 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/pandas-stubs/_typing.pyi b/pandas-stubs/_typing.pyi
index c8d5283e..5837ade7 100644
--- a/pandas-stubs/_typing.pyi
+++ b/pandas-stubs/_typing.pyi
@@ -8,7 +8,7 @@ from collections.abc import (
     Sequence,
 )
 import datetime
-from datetime import timedelta, tzinfo
+from datetime import tzinfo
 from os import PathLike
 from re import Pattern
 import sys
@@ -843,8 +843,6 @@ IntoColumn: TypeAlias = (
 )
 
 class PctChangeKwargs(TypedDict, total=False):
-    periods: int
-    freq: Frequency | timedelta | None
     axis: AxisIndex
     fill_value: object | None
 
diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi
index 509c6516..a2ca001a 100644
--- a/pandas-stubs/core/frame.pyi
+++ b/pandas-stubs/core/frame.pyi
@@ -15,8 +15,8 @@ from typing import (
     Generic,
     Literal,
     NoReturn,
-    overload,
     Unpack,
+    overload,
 )
 
 from _typing import TimeZones
@@ -1989,10 +1989,10 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     def ne(self, other, axis: Axis = ..., level: Level | None = ...) -> Self: ...
     def pct_change(
         self,
-        periods: int = ...,
+        periods: int = 1,
         fill_method: None = ...,
         limit: int | None = ...,
-        freq=...,
+        freq: Frequency | dt.timedelta | None = None,
         **kwargs: Unpack[PctChangeKwargs],
     ) -> Self: ...
     def pop(self, item: _str) -> Series: ...
diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi
index dd040355..f08a0826 100644
--- a/pandas-stubs/core/series.pyi
+++ b/pandas-stubs/core/series.pyi
@@ -21,8 +21,8 @@ from typing import (
     Generic,
     Literal,
     NoReturn,
-    overload,
     Unpack,
+    overload,
 )
 
 from _typing import (
@@ -1550,10 +1550,10 @@ class Series(IndexOpsMixin[S1], NDFrame):
     ) -> Series[S1]: ...
     def pct_change(
         self,
-        periods: int = ...,
-        fill_method: _str = ...,
+        periods: int = 1,
+        fill_method: None = ...,
         limit: int | None = ...,
-        freq=...,
+        freq: Frequency | timedelta | None = None,
         **kwargs: Unpack[PctChangeKwargs],
     ) -> Series[S1]: ...
     def first_valid_index(self) -> Scalar: ...

From fc66d9a707e696e295afa744135e934d16dfcd3e Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Tue, 22 Apr 2025 21:24:59 +0800
Subject: [PATCH 3/7] remove typeddict

---
 pandas-stubs/_typing.pyi     | 4 ----
 pandas-stubs/core/frame.pyi  | 6 +++---
 pandas-stubs/core/series.pyi | 6 +++---
 3 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/pandas-stubs/_typing.pyi b/pandas-stubs/_typing.pyi
index 5837ade7..2655f09f 100644
--- a/pandas-stubs/_typing.pyi
+++ b/pandas-stubs/_typing.pyi
@@ -842,8 +842,4 @@ IntoColumn: TypeAlias = (
     AnyArrayLike | Scalar | Callable[[DataFrame], AnyArrayLike | Scalar]
 )
 
-class PctChangeKwargs(TypedDict, total=False):
-    axis: AxisIndex
-    fill_value: object | None
-
 __all__ = ["npt", "type_t"]
diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi
index a2ca001a..6466390e 100644
--- a/pandas-stubs/core/frame.pyi
+++ b/pandas-stubs/core/frame.pyi
@@ -15,7 +15,6 @@ from typing import (
     Generic,
     Literal,
     NoReturn,
-    Unpack,
     overload,
 )
 
@@ -114,7 +113,6 @@ from pandas._typing import (
     NaPosition,
     NDFrameT,
     ParquetEngine,
-    PctChangeKwargs,
     QuantileInterpolation,
     RandomState,
     ReadBuffer,
@@ -1993,7 +1991,9 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         fill_method: None = ...,
         limit: int | None = ...,
         freq: Frequency | dt.timedelta | None = None,
-        **kwargs: Unpack[PctChangeKwargs],
+        *,
+        axis: AxisIndex = ...,
+        fill_value: object | None = ...,
     ) -> Self: ...
     def pop(self, item: _str) -> Series: ...
     def pow(
diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi
index f08a0826..5729f857 100644
--- a/pandas-stubs/core/series.pyi
+++ b/pandas-stubs/core/series.pyi
@@ -21,7 +21,6 @@ from typing import (
     Generic,
     Literal,
     NoReturn,
-    Unpack,
     overload,
 )
 
@@ -144,7 +143,6 @@ from pandas._typing import (
     MaskType,
     NaPosition,
     ObjectDtypeArg,
-    PctChangeKwargs,
     QuantileInterpolation,
     RandomState,
     Renamer,
@@ -1554,7 +1552,9 @@ class Series(IndexOpsMixin[S1], NDFrame):
         fill_method: None = ...,
         limit: int | None = ...,
         freq: Frequency | timedelta | None = None,
-        **kwargs: Unpack[PctChangeKwargs],
+        *,
+        axis: AxisIndex = ...,
+        fill_value: object | None = ...,
     ) -> Series[S1]: ...
     def first_valid_index(self) -> Scalar: ...
     def last_valid_index(self) -> Scalar: ...

From c0ab69bfa679136e101be0f8267bff3c45751e76 Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Wed, 23 Apr 2025 21:10:09 +0800
Subject: [PATCH 4/7] address comments

---
 pandas-stubs/core/frame.pyi  | 13 ++++++-------
 pandas-stubs/core/series.pyi | 14 ++++++--------
 2 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi
index 6466390e..2c2fcb15 100644
--- a/pandas-stubs/core/frame.pyi
+++ b/pandas-stubs/core/frame.pyi
@@ -67,6 +67,7 @@ from pandas._libs.lib import NoDefault
 from pandas._libs.missing import NAType
 from pandas._libs.tslibs import BaseOffset
 from pandas._libs.tslibs.nattype import NaTType
+from pandas._libs.tslibs.offsets import DateOffset
 from pandas._typing import (
     S1,
     AggFuncTypeBase,
@@ -87,7 +88,6 @@ from pandas._typing import (
     FilePath,
     FillnaOptions,
     FormattersType,
-    Frequency,
     GroupByObjectNonScalar,
     HashableT,
     HashableT1,
@@ -831,9 +831,9 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     def shift(
         self,
         periods: int = ...,
-        freq: Frequency | dt.timedelta | None = ...,
+        freq: DateOffset | dt.timedelta | None = ...,
         axis: Axis = ...,
-        fill_value: Hashable | None = ...,
+        fill_value: Scalar | NAType | None = ...,
     ) -> Self: ...
     @overload
     def set_index(
@@ -1987,13 +1987,12 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     def ne(self, other, axis: Axis = ..., level: Level | None = ...) -> Self: ...
     def pct_change(
         self,
-        periods: int = 1,
+        periods: int = ...,
         fill_method: None = ...,
-        limit: int | None = ...,
-        freq: Frequency | dt.timedelta | None = None,
+        freq: DateOffset | dt.timedelta | None = ...,
         *,
         axis: AxisIndex = ...,
-        fill_value: object | None = ...,
+        fill_value: Scalar | NAType | None = ...,
     ) -> Self: ...
     def pop(self, item: _str) -> Series: ...
     def pow(
diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi
index 5729f857..eded9a20 100644
--- a/pandas-stubs/core/series.pyi
+++ b/pandas-stubs/core/series.pyi
@@ -102,6 +102,7 @@ from pandas._libs.lib import NoDefault
 from pandas._libs.missing import NAType
 from pandas._libs.tslibs import BaseOffset
 from pandas._libs.tslibs.nattype import NaTType
+from pandas._libs.tslibs.offsets import DateOffset
 from pandas._typing import (
     S1,
     S2,
@@ -125,7 +126,6 @@ from pandas._typing import (
     FilePath,
     FillnaOptions,
     FloatDtypeArg,
-    Frequency,
     GroupByObjectNonScalar,
     HashableT1,
     IgnoreRaise,
@@ -1131,9 +1131,9 @@ class Series(IndexOpsMixin[S1], NDFrame):
     def shift(
         self,
         periods: int = ...,
-        freq: Frequency | timedelta | None = ...,
+        freq: DateOffset | timedelta | None = ...,
         axis: AxisIndex = ...,
-        fill_value: object | None = ...,
+        fill_value: Scalar | NAType | None = ...,
     ) -> UnknownSeries: ...
     def info(
         self,
@@ -1548,13 +1548,11 @@ class Series(IndexOpsMixin[S1], NDFrame):
     ) -> Series[S1]: ...
     def pct_change(
         self,
-        periods: int = 1,
+        periods: int = ...,
         fill_method: None = ...,
-        limit: int | None = ...,
-        freq: Frequency | timedelta | None = None,
+        freq: DateOffset | dt.timedelta | None = ...,
         *,
-        axis: AxisIndex = ...,
-        fill_value: object | None = ...,
+        fill_value: Scalar | NAType | None = ...,
     ) -> Series[S1]: ...
     def first_valid_index(self) -> Scalar: ...
     def last_valid_index(self) -> Scalar: ...

From 3a222e3679ec3d85cb3f9f28cf7b3c0ceb080292 Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Wed, 23 Apr 2025 21:15:13 +0800
Subject: [PATCH 5/7] add tests, fix axis argument type

---
 pandas-stubs/core/frame.pyi | 2 +-
 tests/test_frame.py         | 3 +++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi
index 2c2fcb15..fbba67de 100644
--- a/pandas-stubs/core/frame.pyi
+++ b/pandas-stubs/core/frame.pyi
@@ -1991,7 +1991,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         fill_method: None = ...,
         freq: DateOffset | dt.timedelta | None = ...,
         *,
-        axis: AxisIndex = ...,
+        axis: Axis = ...,
         fill_value: Scalar | NAType | None = ...,
     ) -> Self: ...
     def pop(self, item: _str) -> Series: ...
diff --git a/tests/test_frame.py b/tests/test_frame.py
index 99f11b3c..f59df18f 100644
--- a/tests/test_frame.py
+++ b/tests/test_frame.py
@@ -2428,7 +2428,10 @@ def test_groupby_series_methods() -> None:
 
 def test_dataframe_pct_change() -> None:
     df = pd.DataFrame({"x": [1, 2, 2, 3, 3], "y": [10, 20, 30, 40, 50]})
+    df.pct_change()
     df.pct_change(fill_method=None)
+    df.pct_change(axis="columns", periods=-1)
+    df.pct_change(fill_value=0)
 
 
 def test_indexslice_setitem():

From bf84514105a3fdef0bcb58a5986a7799b7bfe296 Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Wed, 23 Apr 2025 21:31:35 +0800
Subject: [PATCH 6/7] fix shift/pct_change param types

---
 pandas-stubs/core/frame.pyi  | 6 +++---
 pandas-stubs/core/series.pyi | 8 ++++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi
index fbba67de..165f1614 100644
--- a/pandas-stubs/core/frame.pyi
+++ b/pandas-stubs/core/frame.pyi
@@ -830,8 +830,8 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     ) -> Self: ...
     def shift(
         self,
-        periods: int = ...,
-        freq: DateOffset | dt.timedelta | None = ...,
+        periods: int | Sequence[int] = ...,
+        freq: DateOffset | dt.timedelta | _str | None = ...,
         axis: Axis = ...,
         fill_value: Scalar | NAType | None = ...,
     ) -> Self: ...
@@ -1989,7 +1989,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         self,
         periods: int = ...,
         fill_method: None = ...,
-        freq: DateOffset | dt.timedelta | None = ...,
+        freq: DateOffset | dt.timedelta | _str | None = ...,
         *,
         axis: Axis = ...,
         fill_value: Scalar | NAType | None = ...,
diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi
index eded9a20..5737dc26 100644
--- a/pandas-stubs/core/series.pyi
+++ b/pandas-stubs/core/series.pyi
@@ -1130,9 +1130,9 @@ class Series(IndexOpsMixin[S1], NDFrame):
     ) -> Series[S1]: ...
     def shift(
         self,
-        periods: int = ...,
-        freq: DateOffset | timedelta | None = ...,
-        axis: AxisIndex = ...,
+        periods: int | Sequence[int] = ...,
+        freq: DateOffset | timedelta | _str | None = ...,
+        axis: Axis = ...,
         fill_value: Scalar | NAType | None = ...,
     ) -> UnknownSeries: ...
     def info(
@@ -1550,7 +1550,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         self,
         periods: int = ...,
         fill_method: None = ...,
-        freq: DateOffset | dt.timedelta | None = ...,
+        freq: DateOffset | timedelta | _str | None = ...,
         *,
         fill_value: Scalar | NAType | None = ...,
     ) -> Series[S1]: ...

From 87a28538faf8dc951e07011db5cb77f88fae8f7f Mon Sep 17 00:00:00 2001
From: yangdanny97 <dzy4@cornell.edu>
Date: Thu, 24 Apr 2025 22:35:42 +0800
Subject: [PATCH 7/7] fix return type of series pct_change, add test for
 series.pct_change

---
 pandas-stubs/core/series.pyi |  2 +-
 tests/test_frame.py          | 11 +++++++----
 tests/test_series.py         | 20 ++++++++++++++++++++
 3 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi
index 5737dc26..ada315b7 100644
--- a/pandas-stubs/core/series.pyi
+++ b/pandas-stubs/core/series.pyi
@@ -1553,7 +1553,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         freq: DateOffset | timedelta | _str | None = ...,
         *,
         fill_value: Scalar | NAType | None = ...,
-    ) -> Series[S1]: ...
+    ) -> Series[float]: ...
     def first_valid_index(self) -> Scalar: ...
     def last_valid_index(self) -> Scalar: ...
     @overload
diff --git a/tests/test_frame.py b/tests/test_frame.py
index f59df18f..2bde7062 100644
--- a/tests/test_frame.py
+++ b/tests/test_frame.py
@@ -2428,10 +2428,13 @@ def test_groupby_series_methods() -> None:
 
 def test_dataframe_pct_change() -> None:
     df = pd.DataFrame({"x": [1, 2, 2, 3, 3], "y": [10, 20, 30, 40, 50]})
-    df.pct_change()
-    df.pct_change(fill_method=None)
-    df.pct_change(axis="columns", periods=-1)
-    df.pct_change(fill_value=0)
+    check(assert_type(df.pct_change(), pd.DataFrame), pd.DataFrame)
+    check(assert_type(df.pct_change(fill_method=None), pd.DataFrame), pd.DataFrame)
+    check(
+        assert_type(df.pct_change(axis="columns", periods=-1), pd.DataFrame),
+        pd.DataFrame,
+    )
+    check(assert_type(df.pct_change(fill_value=0), pd.DataFrame), pd.DataFrame)
 
 
 def test_indexslice_setitem():
diff --git a/tests/test_series.py b/tests/test_series.py
index 0a9d6909..cb6fe085 100644
--- a/tests/test_series.py
+++ b/tests/test_series.py
@@ -441,6 +441,26 @@ def test_types_shift() -> None:
     check(assert_type(s.shift(freq="1D"), pd.Series), pd.Series, np.integer)
 
 
+def test_series_pct_change() -> None:
+    s = pd.Series([1, 2, 3], index=pd.date_range("2020", periods=3))
+    check(assert_type(s.pct_change(), "pd.Series[float]"), pd.Series, np.floating)
+    check(
+        assert_type(s.pct_change(fill_method=None), "pd.Series[float]"),
+        pd.Series,
+        np.floating,
+    )
+    check(
+        assert_type(s.pct_change(periods=-1), "pd.Series[float]"),
+        pd.Series,
+        np.floating,
+    )
+    check(
+        assert_type(s.pct_change(fill_value=0), "pd.Series[float]"),
+        pd.Series,
+        np.floating,
+    )
+
+
 def test_types_rank() -> None:
     s = pd.Series([1, 1, 2, 5, 6, np.nan])
     s.rank()