From 95b18210977c90668de7108742b4d48b323f3ec4 Mon Sep 17 00:00:00 2001 From: Richard Howe Date: Sun, 11 Feb 2024 20:57:13 -0500 Subject: [PATCH 1/7] Updated whatsnew and added deprecation message. --- doc/source/whatsnew/v3.0.0.rst | 1 + pandas/core/series.py | 3 +++ 2 files changed, 4 insertions(+) diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst index aa378faac2a00..435090913b458 100644 --- a/doc/source/whatsnew/v3.0.0.rst +++ b/doc/source/whatsnew/v3.0.0.rst @@ -96,6 +96,7 @@ Deprecations ~~~~~~~~~~~~ - Deprecated :meth:`Timestamp.utcfromtimestamp`, use ``Timestamp.fromtimestamp(ts, "UTC")`` instead (:issue:`56680`) - Deprecated :meth:`Timestamp.utcnow`, use ``Timestamp.now("UTC")`` instead (:issue:`56680`) +- Deprecated allowing non-keyword arguments in :meth:`Series.to_markdown` except ``path_or_buf``. (:issue:`57280`) - .. --------------------------------------------------------------------------- diff --git a/pandas/core/series.py b/pandas/core/series.py index d5eaa2125b301..52af3b5ba49b2 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1632,6 +1632,9 @@ def to_string( +----+----------+""" ), ) + @deprecate_nonkeyword_arguments( + version="3.0", allowed_args=["self", "buf"], name="to_markdown" + ) def to_markdown( self, buf: IO[str] | None = None, From 77fbb312ac911d131b172b8eb77979c7d945105e Mon Sep 17 00:00:00 2001 From: Richard Howe Date: Sun, 11 Feb 2024 21:12:18 -0500 Subject: [PATCH 2/7] Adding unit test for deprecation warning. --- pandas/core/series.py | 2 +- pandas/tests/series/test_missing.py | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 52af3b5ba49b2..d07224129b3d9 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1633,7 +1633,7 @@ def to_string( ), ) @deprecate_nonkeyword_arguments( - version="3.0", allowed_args=["self", "buf"], name="to_markdown" + version="3.0.1", allowed_args=["self", "buf"], name="to_markdown" ) def to_markdown( self, diff --git a/pandas/tests/series/test_missing.py b/pandas/tests/series/test_missing.py index cafc69c4d0f20..09c27bf20a556 100644 --- a/pandas/tests/series/test_missing.py +++ b/pandas/tests/series/test_missing.py @@ -17,6 +17,16 @@ class TestSeriesMissingData: + def test_keyword_deprecation(self): + # GH 57280 + msg = ( + "Starting with pandas version 3.0.1 all arguments of to_markdown " + "except for the argument 'buf' will be keyword-only." + ) + s = Series(Categorical(["a", "b", np.nan, "a"])) + with tm.assert_produces_warning(FutureWarning, match=msg): + s.to_markdown(None, "wt") + def test_categorical_nan_handling(self): # NaNs are represented as -1 in labels s = Series(Categorical(["a", "b", np.nan, "a"])) From 9db6ec03a04b45e8cc19693b21af3ad11f014a88 Mon Sep 17 00:00:00 2001 From: Richard Howe Date: Sun, 11 Feb 2024 21:49:10 -0500 Subject: [PATCH 3/7] Updating unit tests. --- pandas/tests/io/formats/test_to_markdown.py | 12 ++++++++++++ pandas/tests/series/test_missing.py | 10 ---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/pandas/tests/io/formats/test_to_markdown.py b/pandas/tests/io/formats/test_to_markdown.py index 437f079c5f2f9..da1eb239c39b3 100644 --- a/pandas/tests/io/formats/test_to_markdown.py +++ b/pandas/tests/io/formats/test_to_markdown.py @@ -3,10 +3,22 @@ import pytest import pandas as pd +import pandas._testing as tm pytest.importorskip("tabulate") +def test_keyword_deprecation(): + # GH 57280 + msg = ( + "Starting with pandas version 3.0.1 all arguments of to_markdown " + "except for the argument 'buf' will be keyword-only." + ) + s = pd.Series() + with tm.assert_produces_warning(FutureWarning, match=msg): + s.to_markdown(None, "wt") + + def test_simple(): buf = StringIO() df = pd.DataFrame([1, 2, 3]) diff --git a/pandas/tests/series/test_missing.py b/pandas/tests/series/test_missing.py index 09c27bf20a556..cafc69c4d0f20 100644 --- a/pandas/tests/series/test_missing.py +++ b/pandas/tests/series/test_missing.py @@ -17,16 +17,6 @@ class TestSeriesMissingData: - def test_keyword_deprecation(self): - # GH 57280 - msg = ( - "Starting with pandas version 3.0.1 all arguments of to_markdown " - "except for the argument 'buf' will be keyword-only." - ) - s = Series(Categorical(["a", "b", np.nan, "a"])) - with tm.assert_produces_warning(FutureWarning, match=msg): - s.to_markdown(None, "wt") - def test_categorical_nan_handling(self): # NaNs are represented as -1 in labels s = Series(Categorical(["a", "b", np.nan, "a"])) From be2f3c80cf1bce095d33456320773c6b4bb81f4d Mon Sep 17 00:00:00 2001 From: Richard Howe <45905457+rmhowe425@users.noreply.github.com> Date: Mon, 12 Feb 2024 19:16:50 -0500 Subject: [PATCH 4/7] Update series.py --- pandas/core/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index d07224129b3d9..8c7a33bd6f0f9 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1633,7 +1633,7 @@ def to_string( ), ) @deprecate_nonkeyword_arguments( - version="3.0.1", allowed_args=["self", "buf"], name="to_markdown" + version="3.0.0", allowed_args=["self", "buf"], name="to_markdown" ) def to_markdown( self, From d5dfbe44fcecbcbab374984d732f247343e4f486 Mon Sep 17 00:00:00 2001 From: Richard Howe Date: Mon, 12 Feb 2024 23:02:24 -0500 Subject: [PATCH 5/7] Updating unit test and documentation. --- doc/source/whatsnew/v3.0.0.rst | 2 +- pandas/tests/io/formats/test_to_markdown.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst index 435090913b458..9daf0c0bfd108 100644 --- a/doc/source/whatsnew/v3.0.0.rst +++ b/doc/source/whatsnew/v3.0.0.rst @@ -96,7 +96,7 @@ Deprecations ~~~~~~~~~~~~ - Deprecated :meth:`Timestamp.utcfromtimestamp`, use ``Timestamp.fromtimestamp(ts, "UTC")`` instead (:issue:`56680`) - Deprecated :meth:`Timestamp.utcnow`, use ``Timestamp.now("UTC")`` instead (:issue:`56680`) -- Deprecated allowing non-keyword arguments in :meth:`Series.to_markdown` except ``path_or_buf``. (:issue:`57280`) +- Deprecated allowing non-keyword arguments in :meth:`Series.to_markdown` except ``buf``. (:issue:`57280`) - .. --------------------------------------------------------------------------- diff --git a/pandas/tests/io/formats/test_to_markdown.py b/pandas/tests/io/formats/test_to_markdown.py index da1eb239c39b3..fffb1b9b9d2a4 100644 --- a/pandas/tests/io/formats/test_to_markdown.py +++ b/pandas/tests/io/formats/test_to_markdown.py @@ -11,7 +11,7 @@ def test_keyword_deprecation(): # GH 57280 msg = ( - "Starting with pandas version 3.0.1 all arguments of to_markdown " + "Starting with pandas version 3.0.0 all arguments of to_markdown " "except for the argument 'buf' will be keyword-only." ) s = pd.Series() From cd4ac01f2d1172f71c4ce521044cfea2cd0d1bb6 Mon Sep 17 00:00:00 2001 From: Richard Howe Date: Sun, 18 Feb 2024 11:27:40 -0500 Subject: [PATCH 6/7] Adding in to_markdown overload functions per reviewer feedback. --- pandas/core/series.py | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/pandas/core/series.py b/pandas/core/series.py index ca2e202728645..9df1dd9c15e5c 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1637,6 +1637,42 @@ def to_string( +----+----------+""" ), ) + @overload + def to_markdown( + self, + buf: None = ..., + *, + mode: str = ..., + index: bool = ..., + storage_options: StorageOptions | None = ..., + **kwargs, + ) -> str: + ... + + @overload + def to_markdown( + self, + buf: IO[str], + *, + mode: str = ..., + index: bool = ..., + storage_options: StorageOptions | None = ..., + **kwargs, + ) -> None: + ... + + @overload + def to_markdown( + self, + buf: IO[str] | None, + *, + mode: str = ..., + index: bool = ..., + storage_options: StorageOptions | None = ..., + **kwargs, + ) -> str | None: + ... + @deprecate_nonkeyword_arguments( version="3.0.0", allowed_args=["self", "buf"], name="to_markdown" ) From 43d8a0e8dc1e5868709f44a30203f2cae00344a4 Mon Sep 17 00:00:00 2001 From: Richard Howe Date: Sun, 18 Feb 2024 16:08:27 -0500 Subject: [PATCH 7/7] Updating implementation based on reviewer feedback. --- pandas/core/series.py | 62 +++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 9df1dd9c15e5c..ed82a62d0f345 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1606,37 +1606,6 @@ def to_string( f.write(result) return None - @doc( - klass=_shared_doc_kwargs["klass"], - storage_options=_shared_docs["storage_options"], - examples=dedent( - """Examples - -------- - >>> s = pd.Series(["elk", "pig", "dog", "quetzal"], name="animal") - >>> print(s.to_markdown()) - | | animal | - |---:|:---------| - | 0 | elk | - | 1 | pig | - | 2 | dog | - | 3 | quetzal | - - Output markdown with a tabulate option. - - >>> print(s.to_markdown(tablefmt="grid")) - +----+----------+ - | | animal | - +====+==========+ - | 0 | elk | - +----+----------+ - | 1 | pig | - +----+----------+ - | 2 | dog | - +----+----------+ - | 3 | quetzal | - +----+----------+""" - ), - ) @overload def to_markdown( self, @@ -1673,6 +1642,37 @@ def to_markdown( ) -> str | None: ... + @doc( + klass=_shared_doc_kwargs["klass"], + storage_options=_shared_docs["storage_options"], + examples=dedent( + """Examples + -------- + >>> s = pd.Series(["elk", "pig", "dog", "quetzal"], name="animal") + >>> print(s.to_markdown()) + | | animal | + |---:|:---------| + | 0 | elk | + | 1 | pig | + | 2 | dog | + | 3 | quetzal | + + Output markdown with a tabulate option. + + >>> print(s.to_markdown(tablefmt="grid")) + +----+----------+ + | | animal | + +====+==========+ + | 0 | elk | + +----+----------+ + | 1 | pig | + +----+----------+ + | 2 | dog | + +----+----------+ + | 3 | quetzal | + +----+----------+""" + ), + ) @deprecate_nonkeyword_arguments( version="3.0.0", allowed_args=["self", "buf"], name="to_markdown" )