Feature: Issue DeprecationWarnings/DeprecationErrors when calling API changes

[kmuehlbauer]

Here I would like to discuss the possibility to extend the functionality of this package to notice about forthcoming API changes and the like.

In many cases functions/classes/methods (you name it) are not deprecated but a change in the API will take place. So it would be useful to warn the user about forthcoming changes with a special decorator.

We used this in the past in our package but would like to see it added here, where it belongs (IMHO). Please have a look at possible use cases here.

The current code would naturally need quite bit of lifting to adapt it to this packages style.

Thoughts?

[briancurtin]

1. I would be fine adding support for FutureWarning when current_version < deprecated_in. That part should be fairly easy on its own, just going from our two-state check between deprecated and removed to looking at the version against the three states of future, deprecated, and removed.

2. Getting into looking at the caller's kwargs and figuring out types and stuff is probably further than I think this decorator should go as a general purpose library. What if there was some parameter to deprecated that was a callable that received the caller's *args, **kwargs and did that determination itself? For example, this is just pseudo-code, but what if the details parameter took that callable argument and generated the details from it?

def arg_checker(*args, **kwargs):
    if "x" in kwargs":
        if isinstance(kwargs["x"], int):
            return "x will become a str in 0.5"

@deprecated(deprecated_in="0.5", current_version="0.2",
            details=arg_checker)
def func(a, b, x=None, y=None):
    ...

[kmuehlbauer]

@briancurtin Thank you for the comment. Especially the idea with the 'arg_checker' is charming. This will keep the flexibility at the user side and the simple code in the package.

I'll think about this a day or two.