[MRG] Replace DeprecationWarning with FutureWarning

[NicolasHug]

closes #9857

This PR replaces DeprecationWarning with a newly created SklearnDeprecationWarning (similar to numpy's VisibleDeprecationWarning).

This fixes the custom filter issue raised in #9857 (custom filter are bad basically)

The downside is that users who are already ignoring the DeprecationWarning will need to change their code to now ignore the SklearnDeprecationWarning.

There's no backward compatibility guarantee regarding warnings, but if this PR gets merged, we should make sure to let users know as much as possible

Also we should give an update on this SO question

EDIT: changed name from VisibleDeprecationWarning to SklearnDeprecationWarning

EDIT: changed again to raise FutureWarning

[amueller]

Is it good to name it the same as Numpy? Shouldn't we have a SKLVisibleDeprecationWarning or something like that?

[NicolasHug]

I was hoping that users could ignore both ours and numpy's with a simple 'VisibleDeprecationWarning' regex but that doesn't seem to be possible anyway (maybe for the better).

I'll change to SklearnDeprecationWarning

[NicolasHug]

@adrinjalali you were thinking about warnigns ;)

[adrinjalali]

I'm wondering why we do DeprecationWarning in the first place. Python's docs say:

DeprecationWarning:
Base category for warnings about deprecated features when those warnings are intended for other Python developers (ignored by default, unless triggered by code in __main__).

The unless triggered by code in __main__ is since Python 3.7 (PEP-565)

On the other hand, we have:

FutureWarning:
Base category for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python.

And:

PendingFutureWarning:
Base category for warnings about features that will be deprecated in the future (ignored by default).

IMO most DeprecationWarnings we have, are indeed FutureWarnings, which is shown by default to the user anyway.

I'm in favor of using FutureWarning wherever we actually want the user to see them, and the other two, based on whatever suits each case, when we want to warn the package maintainers.

Packages who depend on sklearn, or any other package, should have a CI failing on DeprecationWarning, those warnings shouldn't be displayed to all users.

Also, we wan move a bunch of our UserWarnings to logger.warn.

[NicolasHug]

I agree our DeprecationWarnings should probably have been FutureWarnings in the first place. I'm OK for switching to FutureWarnings.

However I don't think we want to worry about PendingFutureWarnings (at least for now, and definitely not for this PR, let's keep things simple).

Same for DeprecationWarning: these are for Python developers, not for library users/maintainers. I don't think we should ever mess with those.

[rth]

+1 for using FutureWarnings instead of a custom warning class.

Related discussions in numpy/numpy#8829 (comment) and scikit-image/scikit-image#3244

[thomasjpfan]

+1 for FutureWarning. Do we still use the verb “deprecated” in the message?

[NicolasHug]

Why shouldn't we?

[thomasjpfan]

The options are:

1. This feature was deprecated in 0.22 and will be removed in 0.24.
2. This feature will be removed in 0.24.

Is the "deprecated in 0.22" actionable information? I am going under the assumption that "no one reads warnings", so making the warning only include actionable information is a little nicer. "Remove in 0.24" -> better do something about this before 0.24.

[NicolasHug]

I have no idea why that joblib warning is showing up :/

https://dev.azure.com/scikit-learn/scikit-learn/_build/results?buildId=9548

[adrinjalali]

I have no idea why that joblib warning is showing up :/

@jeremiedbb or @ogrisel maybe?

[NicolasHug]

It's green \o/

ping @thomasjpfan @adrinjalali @ogrisel @glemaitre

[NicolasHug]

Note: the main purpose of this PR is to remove this filter

[adrinjalali]

I'll be happy to merge soon if there are no objections. Before there are more conflicts and issues.

[adrinjalali]

Could you please add a nice whats_new for this one? I think it's missing it.

[NicolasHug]

Just pushed something but I think we can have a better message

[NicolasHug]

Thanks for the reviews!! \o/

[stefanv]

I noticed PEP 565 says:

For library and framework authors that want to ensure their API compatibility warnings are more reliably seen by their users, the recommendation is to use a custom warning class that derives from DeprecationWarning in Python 3.7+, and from FutureWarning in earlier versions.

[thomasjpfan]

In the same section Additional use case for FutureWarning in the PEP 565 it states:

The standard library documentation will be updated to explicitly recommend the use of FutureWarning (rather than DeprecationWarning) for backwards compatibility warnings that are intended to be seen by users of an application.

In the end I think we want the warning to be shown by default to users in the following situation:

# my_module.py
import warnings
def hello():
	warnings.warn("Deprecated", DeprecationWarning)

# main.py
from my_module import hello

hello()

and running python main.py.