BUG,ENH: make deprecated decorator work (and more flexibly) #7651
Conversation
1) Fix the bug in which _generate_deprecation_message was failing to substitute arguments for string formats in user-supplied message argument. 2) Make internal naming consistent: the argument is "name", and now the string format specifications also use "name", not "func". 3) Add an "addendum" kwarg so that the standard message, with its convenient argument substitution, can be used, and additional explanation can be appended as a plain text string. Closes matplotlib#7647.
|
My two cents on our deprecation functions is that they are extremely complicated to use and hard to predict what the deprecation message is going to be. Is there a way to simplify that? |
|
This PR should make it quite a bit easier; in most cases, just leave all kwargs but the last as defaults (unless "alternative" can be specified) and put additional information in "addendum". That way, the message always starts out with the standard pattern, automatically identifying what is being deprecated and when. Also, part of the difficulty you experienced might have been because the behavior did not match the documentation--there was a huge bug, which this PR fixes. Additional steps to make it easier would be adding full examples to the documentation, showing exactly what happens by default, and with common combinations of kwargs. |
|
My strategy is currently to git grep and see what people do or to provide explicitely the deprecation message :) |
|
@amueller 's https://github.com/amueller/futurepast might be interesting to look at here as well. |
|
unfortunately |
|
I think the system we have right now, with the present PR merged, serves our purposes well. |
to substitute arguments for string formats in user-supplied
message argument.
now the string format specifications also use "name", not "func".
convenient argument substitution, can be used, and additional
explanation can be appended as a plain text string.
Closes #7647.