Skip to content

ENH: Implement PDEP-17 #61468

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 20 commits into
base: main
Choose a base branch
from
Open

Conversation

rhshadrach
Copy link
Member

@rhshadrach rhshadrach commented May 20, 2025

  • 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.

cc @Dr-Irv @Aloqeely

Comment on lines 94 to 97
class PandasChangeWarning(Warning):
"""
Warning raised for any an upcoming change.
"""
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@rhshadrach rhshadrach added this to the 3.0 milestone May 20, 2025
@rhshadrach rhshadrach added Enhancement Warnings Warnings that appear or should be added to pandas PDEP pandas enhancement proposal labels May 20, 2025
@datapythonista datapythonista removed the PDEP pandas enhancement proposal label May 20, 2025
@datapythonista
Copy link
Member

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.

Copy link
Contributor

@Dr-Irv Dr-Irv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@rhshadrach
Copy link
Member Author

@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
Copy link
Contributor

Dr-Irv commented May 21, 2025

@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
Copy link
Member Author

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!

Copy link
Member

@Aloqeely Aloqeely left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this!

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


class PandasChangeWarning(Warning):
"""
Warning raised for any an upcoming change.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines 157 to 160

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

import inspect

from pandas.errors import Pandas4Warning
Copy link
Member

@Aloqeely Aloqeely May 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@rhshadrach
Copy link
Member Author

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.

Copy link
Contributor

@Dr-Irv Dr-Irv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good!

@rhshadrach rhshadrach requested a review from Dr-Irv June 4, 2025 00:42
@rhshadrach
Copy link
Member Author

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

Copy link
Contributor

@Dr-Irv Dr-Irv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@rhshadrach rhshadrach requested review from Aloqeely and mroeschke June 4, 2025 18:06
Co-authored-by: Simon Hawkins <simonjayhawkins@gmail.com>
@rhshadrach
Copy link
Member Author

@mroeschke - this should be ready.

- :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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@mroeschke mroeschke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@mroeschke mroeschke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@mroeschke mroeschke dismissed their stale review July 15, 2025 17:03

Accident

rhshadrach and others added 2 commits July 19, 2025 08:56
…policy.md

Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com>
@rhshadrach
Copy link
Member Author

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
Copy link
Member Author

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@rhshadrach rhshadrach Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Enhancement Warnings Warnings that appear or should be added to pandas
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants