[RFC] deprecate an old parameter in favor of a new one

[massich]

I checked deprecated and other packages in search of this and I couldn't find it. So I end up making my own deprecation help function mne-tools/mne-python#5844

Check it out and if you think this is desirable, maybe we can cut a PR out of it.

[laurent-laporte-pro]

Hi Joan,
If I understand you clearly, you want to deprecate a function parameter.
Currently, with the Deprecated Library, you can only deprecate a function/method (or class).

Deprecating a parameter (for instance when you want to rename a parameter) means that the function signature is changing. So, the function itself is changing… Deprecating a function parameter is similar to deprecate the function.

You can have:

# coding: utf-8
from deprecated import deprecated


@deprecated(version="0.2.3",
            reason="The *i* parameter is deprecated, "
                   "you may consider using *increment* instead.")
def my_add(x, i=None, increment=0):
    increment = increment if i is None else i
    return x + increment


print(my_add(5, i=9))

You get:

14
demo_deprecate_param.py:13: DeprecationWarning: Call to deprecated function (or staticmethod) my_add. (The *i* parameter is deprecated, you may consider using *increment* instead.) -- Deprecated since version 0.2.3.
  print(my_add(5, i=9))

[laurent-laporte-pro]

In the other hand, if you want to document the deprecation in Sphinx, you can use deprecated.sphinx.deprecated decorator. For example:

# coding: utf-8
from deprecated.sphinx import deprecated


@deprecated(version="0.2.3",
            reason="The *i* parameter is deprecated, "
                   "you may consider using *increment* instead.")
def my_add(x, i=None, increment=0):
    """
    This function adds *x* and *increment*.

    :param x: The *x* value.
    :param i: *i* parameter is deprecated, use *increment* instead.
    :param increment: The increment value.
    :return: sum of *x* and *increment*.
    """
    increment = increment if i is None else i
    return x + increment


print(my_add.__doc__)

You get:

This function adds *x* and *increment*.

:param x: The *x* value.
:param i: *i* parameter is deprecated, use *increment* instead.
:param increment: The increment value.
:return: sum of *x* and *increment*.


.. deprecated:: 0.2.3
   The *i* parameter is deprecated, you may consider using *increment*
   instead.

[massich]

Yes. What you are proposing is close to what we had before.

I guess that what I was asking was if you would be interested in such a feature. A decorator that took care of the old parameter.

And if so, how do you guys want me to contribute the software?

[flying-sheep]

I created a module that does something like this:

https://github.com/flying-sheep/legacy-api-wrap

It currently doesn’t do anything when a removed parameter is provided, but the code can be easily extended to accommodate that.

Would you like to merge with my project here? I think @deprecated sends the wrong message if only individual parameters are deprecated and not the whole function.

[laurent-laporte-pro]

Ok, I understand what you mean @flying-sheep,

If you had to write the documentation of a function with your @legacy_api decorator. What would you say to the end user? Is there any example, for instance from the Standard Library, which contains such a deprecation?

[flying-sheep]

I’d give the end user the new docs, and mention the old API in a .. versionchanged:: block:

.. versionchanged:: version

Similar to versionadded, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.).

[tantale]

I finally had time to think about this.
See (and comment) the “Deprecate a function parameter — Contribution Guide” #8 (or the “Désapprouver un paramètre de fonction — Guide de contribution” #7).
Thanks.

[martinberoiz]

Hello,

I just wanted to point out that I found this gist today that is related to this issue.

https://gist.github.com/rfezzani/002181c8667ec4c671421a4d938167eb

I looked at deprecated code and I'm not brave enough to write a PR but maybe someone more familiar with the code can give it a go.

[tantale]

Parameter-level depreciation is currently being developed. Stay tune.