From 741df4dfc52d19e7218f5f88a276ca1ee00223ff Mon Sep 17 00:00:00 2001
From: Jack Liu <5811028+zheyuan-liu@users.noreply.github.com>
Date: Tue, 18 May 2021 21:53:21 -0700
Subject: [PATCH] ENH: Deprecate positional arguments for DataFrame.fillna and
 Series.fillna (GH41485)

---
 doc/source/whatsnew/v1.3.0.rst             |  1 +
 pandas/core/frame.py                       |  1 +
 pandas/core/series.py                      |  1 +
 pandas/tests/frame/methods/test_fillna.py  | 12 ++++++++++++
 pandas/tests/series/methods/test_fillna.py | 12 ++++++++++++
 5 files changed, 27 insertions(+)

diff --git a/doc/source/whatsnew/v1.3.0.rst b/doc/source/whatsnew/v1.3.0.rst
index 1eb22436204a8..c25a27e6bb740 100644
--- a/doc/source/whatsnew/v1.3.0.rst
+++ b/doc/source/whatsnew/v1.3.0.rst
@@ -649,6 +649,7 @@ Deprecations
 - Deprecated behavior of :meth:`DatetimeIndex.union` with mixed timezones; in a future version both will be cast to UTC instead of object dtype (:issue:`39328`)
 - Deprecated using ``usecols`` with out of bounds indices for ``read_csv`` with ``engine="c"`` (:issue:`25623`)
 - Deprecated passing arguments as positional (except for ``"method"``) in :meth:`DataFrame.interpolate` and :meth:`Series.interpolate` (:issue:`41485`)
+- Deprecated passing arguments (apart from ``value``) as positional in :meth:`DataFrame.fillna` and :meth:`Series.fillna` (:issue:`41485`)
 
 .. ---------------------------------------------------------------------------
 
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index 705962bef8086..e55b3984b1c39 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -5179,6 +5179,7 @@ def fillna(
     ) -> DataFrame | None:
         ...
 
+    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "value"])
     @doc(NDFrame.fillna, **_shared_doc_kwargs)
     def fillna(
         self,
diff --git a/pandas/core/series.py b/pandas/core/series.py
index aaf37ad191e87..2e060014fdb53 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -4708,6 +4708,7 @@ def fillna(
         ...
 
     # error: Cannot determine type of 'fillna'
+    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "value"])
     @doc(NDFrame.fillna, **_shared_doc_kwargs)  # type: ignore[has-type]
     def fillna(
         self,
diff --git a/pandas/tests/frame/methods/test_fillna.py b/pandas/tests/frame/methods/test_fillna.py
index b827547b0753e..cb01de11a4be9 100644
--- a/pandas/tests/frame/methods/test_fillna.py
+++ b/pandas/tests/frame/methods/test_fillna.py
@@ -538,6 +538,18 @@ def test_fillna_downcast_dict(self):
         expected = DataFrame({"col1": [1, 2]})
         tm.assert_frame_equal(result, expected)
 
+    def test_fillna_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        df = DataFrame({"a": [1, 2, 3, np.nan]}, dtype=float)
+        msg = (
+            r"In a future version of pandas all arguments of DataFrame.fillna "
+            r"except for the argument 'value' will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = df.fillna(0, None, None)
+        expected = DataFrame({"a": [1, 2, 3, 0]}, dtype=float)
+        tm.assert_frame_equal(result, expected)
+
 
 def test_fillna_nonconsolidated_frame():
     # https://github.com/pandas-dev/pandas/issues/36495
diff --git a/pandas/tests/series/methods/test_fillna.py b/pandas/tests/series/methods/test_fillna.py
index 51864df915f8c..97804e0fef8b9 100644
--- a/pandas/tests/series/methods/test_fillna.py
+++ b/pandas/tests/series/methods/test_fillna.py
@@ -748,6 +748,18 @@ def test_fillna_datetime64_with_timezone_tzinfo(self):
         expected = Series([ser[0], ts, ser[2]], dtype=object)
         tm.assert_series_equal(result, expected)
 
+    def test_fillna_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        srs = Series([1, 2, 3, np.nan], dtype=float)
+        msg = (
+            r"In a future version of pandas all arguments of Series.fillna "
+            r"except for the argument 'value' will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = srs.fillna(0, None, None)
+        expected = Series([1, 2, 3, 0], dtype=float)
+        tm.assert_series_equal(result, expected)
+
 
 class TestFillnaPad:
     def test_fillna_bug(self):