deprecate_kwarg

sknano.core.meta.deprecate_kwarg(kwarg, since=None, message=None, alternative=None, mapping=None, pending=False, obj_type='keyword argument')

Decorator to deprecate a keyword argument of a function.

Modified implementation of pandas.util.decorators.deprecate_kwargs.

Parameters:

• kwarg (str) – Name of argument in function to deprecate
• since (str, optional) – The release at which this API became deprecated.
• message (str, optional) – Override the default deprecation message. The format specifier %(func)s may be used for the name of the function, and %(alternative)s may be used in the deprecation message to insert the name of an alternative to the deprecated function. %(obj_type)s may be used to insert a friendly name for the type of object being deprecated.
• alternative (str) – Name of prefered argument in function
• mapping (dict or callable) – If mapping is present, use it to translate old arguments to new arguments. A callable must do its own value checking; values not found in a dict will be forwarded unchanged.
• pending (bool, optional) – If True, uses a PendingDeprecationWarning instead of a DeprecationWarning.

Examples

The following deprecates ‘cols’, using ‘columns’ instead

>>> @deprecate_kwarg(kwarg='cols', alternative='columns')
... def f(columns=''):
...     print(columns)
...
>>> f(columns='should work ok')
should work ok
>>> f(cols='should raise warning')
FutureWarning: cols is deprecated, use columns instead
  warnings.warn(msg, FutureWarning)
should raise warning
>>> f(cols='should error', columns="can't pass do both")
TypeError: Can only specify 'cols' or 'columns', not both
>>> @deprecate_kwarg('old', 'new', {'yes': True, 'no': False})
... def f(new=False):
...     print('yes!' if new else 'no!')
...
>>> f(old='yes')
FutureWarning: old='yes' is deprecated, use new=True instead
  warnings.warn(msg, FutureWarning)
yes!