deprecate_kwarg(old_arg_name: 'str', new_arg_name: 'str | None', mapping: 'Mapping[Any, Any] | Callable[[Any], Any] | None' = None, stacklevel: 'int' = 2) -> 'Callable[[F], F]'

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.

Decorator to deprecate a keyword argument of a function.

Examples

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

This example is valid syntax, but we were not able to check execution

>>> @deprecate_kwarg(old_arg_name='cols', new_arg_name='columns')
... def f(columns=''):
...     print(columns)
...

This example is valid syntax, but we were not able to check execution

>>> f(columns='should work ok')
should work ok

This example is valid syntax, but we were not able to check execution

>>> f(cols='should raise warning')  # doctest: +SKIP
FutureWarning: cols is deprecated, use columns instead
  warnings.warn(msg, FutureWarning)
should raise warning

This example is valid syntax, but we were not able to check execution

>>> f(cols='should error', columns="can't pass do both")  # doctest: +SKIP
TypeError: Can only specify 'cols' or 'columns', not both

This example is valid syntax, but we were not able to check execution

>>> @deprecate_kwarg('old', 'new', {'yes': True, 'no': False})
... def f(new=False):
...     print('yes!' if new else 'no!')
...

This example is valid syntax, but we were not able to check execution

>>> f(old='yes')  # doctest: +SKIP
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

This example is valid syntax, but we were not able to check execution

>>> @deprecate_kwarg(old_arg_name='cols', new_arg_name=None)
... def f(cols='', another_param=''):
...     print(cols)
...

This example is valid syntax, but we were not able to check execution

>>> f(cols='should raise warning')  # doctest: +SKIP
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

This example is valid syntax, but we were not able to check execution

>>> f(another_param='should not raise warning')  # doctest: +SKIP
should not raise warning

This example is valid syntax, but we were not able to check execution

>>> f(cols='should raise warning', another_param='')  # doctest: +SKIP
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

See :

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/util/_decorators.py#93
type: <class 'function'>
Commit: