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!

pandas/errors/__init__.py

pandas/tests/util/test_pandas_deprecation_warning.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?

Dr-Irv

I'm good with the current version. I'll let others decide when to merge.

doc/source/whatsnew/v3.0.0.rst

Co-authored-by: Simon Hawkins <simonjayhawkins@gmail.com>

simonjayhawkins · 2025-07-15T09:16:53Z

doc/source/whatsnew/v3.0.0.rst

+- :class:`pandas.errors.Pandas5Warning`: Warnings which will be enforced in pandas 5.0.
+- :class:`pandas.errors.PandasPendingDeprecationWarning`: Base class of all warnings which emit a ``PendingDeprecationWarning``, independent of the version they will be enforced.
+- :class:`pandas.errors.PandasDeprecationWarning`: Base class of all warnings which emit a ``DeprecationWarning``, independent of the version they will be enforced.
+- :class:`pandas.errors.PandasFutureWarning`: Base class of all warnings which emit a ``PandasFutureWarning``, independent of the version they will be enforced.


Suggested change

- :class:`pandas.errors.PandasFutureWarning`: Base class of all warnings which emit a ``PandasFutureWarning``, independent of the version they will be enforced.

- :class:`pandas.errors.PandasFutureWarning`: Base class of all warnings which emit a ``FutureWarning``, independent of the version they will be enforced.

web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md

mroeschke

Can you think of a linting rule that could remind us to use these new warning classes instead of FutureWarning and DeprecationWarning?

mroeschke

Can you think of a linting rule that could remind us to use these new warning classes instead of FutureWarning and DeprecationWarning?

Accident

…policy.md Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com>

rhshadrach · 2025-07-19T13:20:14Z

Can you think of a linting rule that could remind us to use these new warning classes instead of FutureWarning and DeprecationWarning?

I think we can raise in tm.assert_produces_warning whenever a straight Future/Deprecation/PendingDeprecationWarning is passed. However we cannot do this at the moment as there are a bunch of FutureWarnings that need to be enforced for pandas 3.0.

My suggestion would be to move forward here, enforce pandas 3.0 deprecations, and revisit adding such logic to tm.assert_produces_warning. I don't doubt there will be adding warnings that need to be converted at that point, happy to take up that work.

rhshadrach · 2025-07-19T15:51:28Z

I can only build the docs in this PR if I specify --num-jobs=1 and cannot reproduce this locally.

simonjayhawkins · 2025-07-21T10:58:57Z

pandas/util/_decorators.py

-        keyword-only. If None, then the warning message won't
-        specify any particular version.
-
+    klass : Warning, optional


is this optional? None has been removed from the annotations for klass?

simonjayhawkins · 2025-07-21T11:04:32Z

web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md

@@ -58,8 +58,12 @@ Additionally, when one introduces a deprecation, they should:

 ### Which warning class to use

-Deprecations should initially use ``DeprecationWarning``, and then be switched to ``FutureWarning`` for broader visibility in the last minor release before the major release they are planned to be removed in.  
-This implementation detail can be ignored by using the appropriate ``PandasDeprecationWarning`` variable, which will be aliased to the proper warning class based on the pandas version.
+Starting in pandas 3.0, pandas will provide version-specific warnings. For example, ``Pandas4Warnings`` for all deprecation warnings that will be enforced in pandas 4.0. In addition to these, pandas exposes four additional classes to give users more control over pandas deprecation warnings.


when changing a PDEP text, should the revision and date be bumped?

If this was a real change, yes. I'd argue this is not: while the name of the classes have been expanded upon, this is an implementation detail that is not impactful to any users yet. E.g. users haven't taken some action to prepare their code for PandasDeprecationWarning and now need to update it.

But happy to bump if others think differently.

we've had some PDEPs that have their status updated to "Implemented". Would we want to do that here?

…ement_pdep17

rhshadrach · 2025-07-27T15:38:05Z

doc/source/whatsnew/v0.23.0.rst

+   df = pd.DataFrame(
+       {
+           'foo': [1, 2, 3, 4],
+           'bar': ['a', 'b', 'c', 'd'],
+           'baz': pd.date_range('2018-01-01', freq='d', periods=4),
+           'qux': pd.Categorical(['a', 'b', 'c', 'c'])
+       },
+       index=pd.Index(range(4), name='idx')
+   )
+
   df.index.name = 'index'


I don't understand how this worked on main, but it seems to fix the docs build issue here.

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

Dr-Irv approved these changes Jun 4, 2025

View reviewed changes

rhshadrach requested review from Aloqeely and mroeschke June 4, 2025 18:06

simonjayhawkins reviewed Jun 25, 2025

View reviewed changes

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

Update doc/source/whatsnew/v3.0.0.rst

3b9617d

Co-authored-by: Simon Hawkins <simonjayhawkins@gmail.com>

simonjayhawkins reviewed Jul 15, 2025

View reviewed changes

mroeschke reviewed Jul 15, 2025

View reviewed changes

web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md Outdated Show resolved Hide resolved

mroeschke previously requested changes Jul 15, 2025

View reviewed changes

mroeschke reviewed Jul 15, 2025

View reviewed changes

rhshadrach and others added 2 commits July 19, 2025 08:56

Update web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-…

087dba6

…policy.md Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com>

Merge branch 'main' into implement_pdep17

a6edff6

rhshadrach added 4 commits July 19, 2025 09:50

Debug docs build

25405f2

Revert

9df8b32

Debug docs build

31b2460

Debug docs build

8e85f5c

simonjayhawkins reviewed Jul 21, 2025

View reviewed changes

rhshadrach added 14 commits July 21, 2025 17:22

Fixup & revert

ce08582

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

f93374c

…ement_pdep17

Try removing file

1fcdd4a

Restore v0.23.0

ee3f4f2

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

871b88a

…ement_pdep17

Cleanup v0.23.0.rst

dbb7e46

Debug

f45b45a

Debug

d984c1c

Debug

a92650d

Debug

a034332

Debug

0b0a850

Debug

747f5ce

No whammies!

0b111fa

Finish up

7273d4f

rhshadrach commented Jul 27, 2025

View reviewed changes

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

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

		import inspect

		from pandas.errors import Pandas4Warning

	- :class:`pandas.errors.PandasFutureWarning`: Base class of all warnings which emit a ``PandasFutureWarning``, independent of the version they will be enforced.
	- :class:`pandas.errors.PandasFutureWarning`: Base class of all warnings which emit a ``FutureWarning``, independent of the version they will be enforced.

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rhshadrach commented Jun 4, 2025

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mroeschke left a comment

Choose a reason for hiding this comment

Uh oh!

mroeschke left a comment

Choose a reason for hiding this comment

Uh oh!

rhshadrach commented Jul 19, 2025

Uh oh!

rhshadrach commented Jul 19, 2025

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 Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

rhshadrach commented May 20, 2025 •

edited

Loading

Aloqeely May 30, 2025 •

edited

Loading

rhshadrach Jul 21, 2025 •

edited

Loading