deprecated
deprecated copied to clipboard
tantale
[RFC] deprecate an old parameter in favor of a new one
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 https://github.com/mne-tools/mne-python/pull/5844
Check it out and if you think this is desirable, maybe we can cut a PR out of it.
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))
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.
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?
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.
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?
I’d give the end user the new docs, and mention the old API in a .. versionchanged:: block:
.. versionchanged:: versionSimilar to versionadded, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.).
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.
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.
