From cf6d36b9dd5e3639f406be476066ed8f84d1a7bf Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Thu, 10 Apr 2025 14:27:31 +0200 Subject: [PATCH 1/7] API: Rename `arg` to `func` in `Series.map` --- doc/source/whatsnew/v3.0.0.rst | 1 + pandas/core/series.py | 28 +++++++++++++++++++------ pandas/tests/series/methods/test_map.py | 24 +++++++++++++++++++++ 3 files changed, 47 insertions(+), 6 deletions(-) diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst index 873c1e7cd41cc..226c450cff6dd 100644 --- a/doc/source/whatsnew/v3.0.0.rst +++ b/doc/source/whatsnew/v3.0.0.rst @@ -371,6 +371,7 @@ Other API changes - Index set operations (like union or intersection) will now ignore the dtype of an empty ``RangeIndex`` or empty ``Index`` with object dtype when determining the dtype of the resulting Index (:issue:`60797`) +- Renamed the ``arg`` parameter of ``Series.map`` to ``func``. (:issue:`61260`) .. --------------------------------------------------------------------------- .. _whatsnew_300.deprecations: diff --git a/pandas/core/series.py b/pandas/core/series.py index da46f8ede3409..5ba06e7224923 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -52,6 +52,9 @@ doc, set_module, ) +from pandas.util._exceptions import ( + find_stack_level, +) from pandas.util._validators import ( validate_ascending, validate_bool_kwarg, @@ -4320,7 +4323,7 @@ def unstack( def map( self, - arg: Callable | Mapping | Series, + func: Callable | Mapping | Series | None = None, na_action: Literal["ignore"] | None = None, **kwargs, ) -> Series: @@ -4333,8 +4336,8 @@ def map( Parameters ---------- - arg : function, collections.abc.Mapping subclass or Series - Mapping correspondence. + func : function, collections.abc.Mapping subclass or Series + Function or mapping correspondence. na_action : {None, 'ignore'}, default None If 'ignore', propagate NaN values, without passing them to the mapping correspondence. @@ -4404,9 +4407,22 @@ def map( 3 I am a rabbit dtype: object """ - if callable(arg): - arg = functools.partial(arg, **kwargs) - new_values = self._map_values(arg, na_action=na_action) + if func is None: + if "arg" in kwargs: + # `.map(arg=my_func)` + func = kwargs.pop("arg") + warnings.warn( + "The parameter `arg` has been renamed to `func`, and it " + "will stop being supported in a future version of pandas.", + FutureWarning, + stacklevel=find_stack_level(), + ) + else: + raise ValueError("The `func` parameter is required") + + if callable(func): + func = functools.partial(func, **kwargs) + new_values = self._map_values(func, na_action=na_action) return self._constructor(new_values, index=self.index, copy=False).__finalize__( self, method="map" ) diff --git a/pandas/tests/series/methods/test_map.py b/pandas/tests/series/methods/test_map.py index 84b60a2afe6eb..384b7ce3dc985 100644 --- a/pandas/tests/series/methods/test_map.py +++ b/pandas/tests/series/methods/test_map.py @@ -604,3 +604,27 @@ def test_map_kwargs(): result = Series([2, 4, 5]).map(lambda x, y: x + y, y=2) expected = Series([4, 6, 7]) tm.assert_series_equal(result, expected) + + +def test_map_arg_as_kwarg(): + with tm.assert_produces_warning( + FutureWarning, match="`arg` has been renamed to `func`" + ): + Series([1, 2]).map(arg={}) + + +def test_map_func_and_arg(): + # `arg`is considered a normal kwarg that should be passed to the function + result = Series([1, 2]).map(lambda _, arg: arg, arg=3) + expected = Series([3, 3]) + tm.assert_series_equal(result, expected) + + +def test_map_no_func_or_arg(): + with pytest.raises(ValueError, match="The `func` parameter is required"): + Series([1, 2]).map() + + +def test_map_func_is_none(): + with pytest.raises(ValueError, match="The `func` parameter is required"): + Series([1, 2]).map(func=None) From c5d44f6538539674be03891c52a191d2960ce934 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Thu, 10 Apr 2025 15:42:02 +0200 Subject: [PATCH 2/7] mypy From 1d758e677dc858490a21de6a68e01f78542f5987 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 12 Apr 2025 21:01:41 +0200 Subject: [PATCH 3/7] Moving release note to deprecations --- doc/source/whatsnew/v3.0.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst index a13dbc9b7d252..5be814e251350 100644 --- a/doc/source/whatsnew/v3.0.0.rst +++ b/doc/source/whatsnew/v3.0.0.rst @@ -372,7 +372,6 @@ Other API changes - Index set operations (like union or intersection) will now ignore the dtype of an empty ``RangeIndex`` or empty ``Index`` with object dtype when determining the dtype of the resulting Index (:issue:`60797`) -- Renamed the ``arg`` parameter of ``Series.map`` to ``func``. (:issue:`61260`) .. --------------------------------------------------------------------------- .. _whatsnew_300.deprecations: @@ -423,6 +422,7 @@ Other Deprecations - Deprecated parameter ``method`` in :meth:`DataFrame.reindex_like` / :meth:`Series.reindex_like` (:issue:`58667`) - Deprecated strings ``w``, ``d``, ``MIN``, ``MS``, ``US`` and ``NS`` denoting units in :class:`Timedelta` in favour of ``W``, ``D``, ``min``, ``ms``, ``us`` and ``ns`` (:issue:`59051`) - Deprecated using ``epoch`` date format in :meth:`DataFrame.to_json` and :meth:`Series.to_json`, use ``iso`` instead. (:issue:`57063`) +- Renamed the ``arg`` parameter of ``Series.map`` to ``func``. (:issue:`61260`) .. --------------------------------------------------------------------------- .. _whatsnew_300.prior_deprecations: From 0796d9f7967cb07b0c209a2920bd62c9a838b7bc Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sun, 13 Apr 2025 15:35:31 +0200 Subject: [PATCH 4/7] Update doc/source/whatsnew/v3.0.0.rst Co-authored-by: Richard Shadrach <45562402+rhshadrach@users.noreply.github.com> --- doc/source/whatsnew/v3.0.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst index 5be814e251350..322177b690b14 100644 --- a/doc/source/whatsnew/v3.0.0.rst +++ b/doc/source/whatsnew/v3.0.0.rst @@ -422,7 +422,7 @@ Other Deprecations - Deprecated parameter ``method`` in :meth:`DataFrame.reindex_like` / :meth:`Series.reindex_like` (:issue:`58667`) - Deprecated strings ``w``, ``d``, ``MIN``, ``MS``, ``US`` and ``NS`` denoting units in :class:`Timedelta` in favour of ``W``, ``D``, ``min``, ``ms``, ``us`` and ``ns`` (:issue:`59051`) - Deprecated using ``epoch`` date format in :meth:`DataFrame.to_json` and :meth:`Series.to_json`, use ``iso`` instead. (:issue:`57063`) -- Renamed the ``arg`` parameter of ``Series.map`` to ``func``. (:issue:`61260`) +- Deprecated the ``arg`` parameter of ``Series.map``; pass the added ``func`` argument instead. (:issue:`61260`) .. --------------------------------------------------------------------------- .. _whatsnew_300.prior_deprecations: From 5f270b3e43f5332b058ff407d24d05fe7ae38ef2 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sun, 13 Apr 2025 20:31:53 +0200 Subject: [PATCH 5/7] Fix CI From 843668ef0b276dbc051ff39123dc96ff1c39dd0f Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sun, 13 Apr 2025 20:32:35 +0200 Subject: [PATCH 6/7] Fix CI From cbe2c687c9300a1d72173ad6b92acbf317563fcb Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sun, 13 Apr 2025 20:33:52 +0200 Subject: [PATCH 7/7] Fix CI --- doc/source/whatsnew/v3.0.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst index 322177b690b14..8873f7c1a8fe8 100644 --- a/doc/source/whatsnew/v3.0.0.rst +++ b/doc/source/whatsnew/v3.0.0.rst @@ -421,8 +421,8 @@ Other Deprecations - Deprecated lowercase strings ``w``, ``w-mon``, ``w-tue``, etc. denoting frequencies in :class:`Week` in favour of ``W``, ``W-MON``, ``W-TUE``, etc. (:issue:`58998`) - Deprecated parameter ``method`` in :meth:`DataFrame.reindex_like` / :meth:`Series.reindex_like` (:issue:`58667`) - Deprecated strings ``w``, ``d``, ``MIN``, ``MS``, ``US`` and ``NS`` denoting units in :class:`Timedelta` in favour of ``W``, ``D``, ``min``, ``ms``, ``us`` and ``ns`` (:issue:`59051`) -- Deprecated using ``epoch`` date format in :meth:`DataFrame.to_json` and :meth:`Series.to_json`, use ``iso`` instead. (:issue:`57063`) - Deprecated the ``arg`` parameter of ``Series.map``; pass the added ``func`` argument instead. (:issue:`61260`) +- Deprecated using ``epoch`` date format in :meth:`DataFrame.to_json` and :meth:`Series.to_json`, use ``iso`` instead. (:issue:`57063`) .. --------------------------------------------------------------------------- .. _whatsnew_300.prior_deprecations: