ENH: Implement PDEP-17 #61468

rhshadrach · 2025-05-20T22:22:11Z

closes #xxxx (Replace xxxx with the GitHub issue number)
Tests added and passed if fixing a bug or adding a new feature
All code checks passed.
Added type annotations to new arguments/methods/functions.
Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

Continuation of #58169

Still needs tests and some cleanup with the docs and decorator arguments, but I'd like to get a first look.

rhshadrach · 2025-05-20T22:31:44Z

pandas/errors/__init__.py

+class PandasChangeWarning(Warning):
+    """
+    Warning raised for any an upcoming change.
+    """


Not in love with this name, but PandasDeprecationWarning is taken below. Bikeshedding here is most welcome!

We could also make this internal if we want to not have it be public.

datapythonista · 2025-05-20T23:04:21Z

Seems like the label PDEP can only be used for the PDEP themselves. Otherwise building the website fails, as it expects the PR to be a PDEP that needs to be rendered in the roadmap.

Dr-Irv

I think there should be separate docs about the deprecation policy and these classes, aside from what is in the whatsnew document.

doc/source/whatsnew/v3.0.0.rst

pandas/errors/__init__.py

pandas/util/_decorators.py

doc/source/reference/testing.rst

rhshadrach · 2025-05-21T20:39:15Z

@Dr-Irv - Thanks for the review! I'm negative on the name PandasWarning for a class that has to do with deprecations. pandas emits many warnings, not all are about deprecations.

Dr-Irv · 2025-05-21T21:16:54Z

@Dr-Irv - Thanks for the review! I'm negative on the name PandasWarning for a class that has to do with deprecations. pandas emits many warnings, not all are about deprecations.

Maybe a different name would solve that? Maybe PandasDeprecationOrFutureWarning or something like that.

rhshadrach · 2025-05-30T18:23:10Z

Maybe a different name would solve that? Maybe PandasDeprecationOrFutureWarning or something like that.

Currently using PandasChangeWarning, which has my personal preference so far. Always open to other options or opinions!

Aloqeely

Thanks for working on this!

Aloqeely · 2025-05-30T20:12:34Z

pandas/errors/__init__.py

@@ -91,6 +91,96 @@ class PerformanceWarning(Warning):
    """


+class PandasChangeWarning(Warning):
+    """
+    Warning raised for any an upcoming change.


Suggested change

Warning raised for any an upcoming change.

Warning raised for any upcoming change.

Aloqeely · 2025-05-30T20:13:20Z

pandas/errors/__init__.py

+
+    See Also
+    --------
+    errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.


Suggested change

See Also

--------

errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.

Aloqeely · 2025-05-30T20:33:48Z

pandas/tests/util/test_deprecate_nonkeyword_arguments.py

@@ -4,13 +4,16 @@

 import inspect

+from pandas.errors import Pandas4Warning


Will this test case need to be updated every version? I think having a variable that points to the current version's warning might reduce some of the work.

Then that variable will just have to be updated instead, seems about the same amount of work to me.

I suppose if this is needed in multiple files, then it could become more of a hassle. Will add.

pandas/util/_decorators.py

…ement_pdep17

rhshadrach · 2025-06-02T10:58:02Z

I think there should be separate docs about the deprecation policy and these classes, aside from what is in the whatsnew document.

I've added some implementation details to PDEP-17, and more details to the whatsnew. If you'd like to see this documented somewhere else, can you detail where.

Dr-Irv

Looking good!

Dr-Irv · 2025-06-03T19:51:13Z

pandas/errors/__init__.py

+
+    See Also
+    --------
+    errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.


Shouldn't this be errors.PandasDeprecationWarning ? i.e., the see also should refer to the general non-version specific class

Absolutely no objection to changing it, but I'm curious as to the reason. I added the See Also sections only because our code-checks fail without it.

Because otherwise we'd have to change the docs with each new release.

Thanks - I added line items here for all classes that aren't versioned (and the class itself).

Dr-Irv · 2025-06-03T19:51:50Z

pandas/errors/__init__.py

+
+    See Also
+    --------
+    errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.


same comment as above

Dr-Irv · 2025-06-03T19:51:59Z

pandas/errors/__init__.py

+
+    See Also
+    --------
+    errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.


Dr-Irv · 2025-06-03T19:52:35Z

pandas/errors/__init__.py

+    See Also
+    --------
+    errors.Pandas4Warning : Class for deprecations to be enforced in pandas 4.0.


maybe delete this? Otherwise we have to update this docs upon every new major release.

Change it to a PandasDeprecationWarning instead? Otherwise we'll have to add an exception to the code-checks to allow a docstring without any See Also.

Cross referencing to PandasDeprecationWarning makes sense, and then PandasDeprecationWarning can cross-reference to PandasFutureWarning

Dr-Irv · 2025-06-03T19:57:34Z

pandas/tests/util/test_pandas_deprecation_warning.py

+def f1():
+    warnings.warn("f1", PandasChangeWarning)
+
+
+def test_function_warns_pandas_deprecation_warning():
+    with tm.assert_produces_warning(PandasChangeWarning):
+        f1()
+
+
+@deprecate_kwarg(PandasChangeWarning, "old", new_arg_name="new")
+def f2(new=0):
+    return new
+
+
+def test_decorator_warns_pandas_deprecation_warning():
+    with tm.assert_produces_warning(PandasChangeWarning):
+        f2(old=1)


Shouldn't you add tests for PandasDeprecationWarning, PandasFutureWarning and PandasPendingDeprecationWarning ?

I deleted this file and added one more test to tests/test_errors.py.

rhshadrach · 2025-06-04T00:55:59Z

@bashtage - pandas_datareader is using the deprecate_kwarg decorator. I'm modifying it here, is this an issue?

Aloqeely and others added 2 commits May 20, 2025 18:21

ENH: Implement PDEP-17

80edcb3

Refinements

054398d

rhshadrach commented May 20, 2025

View reviewed changes

rhshadrach added this to the 3.0 milestone May 20, 2025

rhshadrach added Enhancement Warnings Warnings that appear or should be added to pandas PDEP pandas enhancement proposal labels May 20, 2025

datapythonista removed the PDEP pandas enhancement proposal label May 20, 2025

rhshadrach added 2 commits May 21, 2025 00:00

Refinements

4e46d69

Fixup

3f3293f

Dr-Irv requested changes May 21, 2025

View reviewed changes

doc/source/whatsnew/v3.0.0.rst Outdated Show resolved Hide resolved

pandas/errors/__init__.py Outdated Show resolved Hide resolved

pandas/util/_decorators.py Outdated Show resolved Hide resolved

doc/source/reference/testing.rst Show resolved Hide resolved

Aloqeely reviewed May 30, 2025

View reviewed changes

rhshadrach added 3 commits June 2, 2025 06:05

Merge branch 'main' of https://github.com/pandas-dev/pandas into impl…

cac0126

…ement_pdep17

Refinements

638ca5b

Add implementation details to PDEP-17

e2960b6

API test fixup

92a4e7e

Dr-Irv requested changes Jun 3, 2025

View reviewed changes

Refinements

6bca579

rhshadrach requested a review from Dr-Irv June 4, 2025 00:42

	Warning raised for any an upcoming change.
	Warning raised for any upcoming change.

		@@ -4,13 +4,16 @@

		import inspect

		from pandas.errors import Pandas4Warning

Uh oh!

ENH: Implement PDEP-17 #61468

Are you sure you want to change the base?

ENH: Implement PDEP-17 #61468

Conversation

rhshadrach commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

datapythonista commented May 20, 2025

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rhshadrach commented May 21, 2025

Uh oh!

Dr-Irv commented May 21, 2025

Uh oh!

rhshadrach commented May 30, 2025

Uh oh!

Aloqeely left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aloqeely May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rhshadrach commented Jun 2, 2025

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rhshadrach commented Jun 4, 2025

Uh oh!

Uh oh!

rhshadrach commented May 20, 2025 •

edited

Loading

Aloqeely May 30, 2025 •

edited

Loading