def deprecate_kwarg(old_arg_name, new_arg_name, mapping=None, stacklevel=<NUM_LIT:2>):
if mapping is not None and not hasattr(mapping, '<STR_LIT>') andnot callable(mapping):<EOL><INDENT>raise TypeError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>def _deprecate_kwarg(func):<EOL><INDENT>@wraps(func)<EOL>def wrapper(*args, **kwargs):<EOL><INDENT>old_arg_value = kwargs.pop(old_arg_name, None)<EOL>if new_arg_name is None and old_arg_value is not None:<EOL><INDENT>msg = (<EOL>"<STR_LIT>"<EOL>"<STR_LIT>"<EOL>"<STR_LIT>"<EOL>).format(old_name=old_arg_name)<EOL>warnings.warn(msg, FutureWarning, stacklevel=stacklevel)<EOL>kwargs[old_arg_name] = old_arg_value<EOL>return func(*args, **kwargs)<EOL><DEDENT>if old_arg_value is not None:<EOL><INDENT>if mapping is not None:<EOL><INDENT>if hasattr(mapping, '<STR_LIT>'):<EOL><INDENT>new_arg_value = mapping.get(old_arg_value,<EOL>old_arg_value)<EOL><DEDENT>else:<EOL><INDENT>new_arg_value = mapping(old_arg_value)<EOL><DEDENT>msg = ("<STR_LIT>"<EOL>"<STR_LIT>"<EOL>).format(old_name=old_arg_name,<EOL>old_val=old_arg_value,<EOL>new_name=new_arg_name,<EOL>new_val=new_arg_value)<EOL><DEDENT>else:<EOL><INDENT>new_arg_value = old_arg_value<EOL>msg = ("<STR_LIT>"<EOL>"<STR_LIT>"<EOL>).format(old_name=old_arg_name,<EOL>new_name=new_arg_name)<EOL><DEDENT>warnings.warn(msg, FutureWarning, stacklevel=stacklevel)<EOL>if kwargs.get(new_arg_name, None) is not None:<EOL><INDENT>msg = ("<STR_LIT>"<EOL>"<STR_LIT>").format(old_name=old_arg_name,<EOL>new_name=new_arg_name)<EOL>raise TypeError(msg)<EOL><DEDENT>else:<EOL><INDENT>kwargs[new_arg_name] = new_arg_value<EOL><DEDENT><DEDENT>return func(*args, **kwargs)<EOL><DEDENT>return wrapper<EOL><DEDENT>return _deprecate_kwarg<EOL>
Decorator to deprecate a keyword argument of a function.

Parameters
----------
old_arg_name : str
    Name of argument in function to deprecate
new_arg_name : str or None
    Name of preferred argument in function. Use None to raise warning that
    ``old_arg_name`` keyword is deprecated.
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.

Examples
--------
The following deprecates 'cols', using 'columns' instead

>>> @deprecate_kwarg(old_arg_name='cols', new_arg_name='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!

To raise a warning that a keyword will be removed entirely in the future

>>> @deprecate_kwarg(old_arg_name='cols', new_arg_name=None)
... def f(cols='', another_param=''):
...     print(cols)
...
>>> f(cols='should raise warning')
FutureWarning: the 'cols' keyword is deprecated and will be removed in a
future version please takes steps to stop use of 'cols'
should raise warning
>>> f(another_param='should not raise warning')
should not raise warning

>>> f(cols='should raise warning', another_param='')
FutureWarning: the 'cols' keyword is deprecated and will be removed in a
future version please takes steps to stop use of 'cols'
should raise warning