deprecated_renamed_argument

astropy.utils.decorators.deprecated_renamed_argument(old_name, new_name, since, arg_in_kwargs=False, relax=False, pending=False)

Deprecate a _renamed_ function argument.

The decorator assumes that the argument with the old_name was removed from the function signature and the new_name replaced it at the same position in the signature. If the old_name argument is given when calling the decorated function the decorator will catch it and issue a deprecation warning and pass it on as new_name argument.

Parameters:

old_name : str or list/tuple thereof

The old name of the argument.

new_name : str or list/tuple thereof

The new name of the argument.

since : str or number or list/tuple thereof

The release at which the old argument became deprecated.

arg_in_kwargs : bool or list/tuple thereof, optional

If the argument is not a named argument (for example it was meant to be consumed by **kwargs) set this to True. Otherwise the decorator will throw an Exception if the new_name cannot be found in the signature of the decorated function. Default is False.

relax : bool or list/tuple thereof, optional

If False a TypeError is raised if both new_name and old_name are given. If True the value for new_name is used and a Warning is issued. Default is False.

pending : bool or list/tuple thereof, optional

If True this will hide the deprecation warning and ignore the corresponding relax parameter value. Default is False.

Raises:

TypeError

If the new argument name cannot be found in the function signature and arg_in_kwargs was False or if it is used to deprecate the name of the *args-, **kwargs-like arguments. At runtime such an Error is raised if both the new_name and old_name were specified when calling the function and “relax=False”.

Notes

The decorator should be applied to a function where the name of an argument was changed but it applies the same logic.

Warning

If old_name is a list or tuple the new_name and since must also be a list or tuple with the same number of entries. relax and arg_in_kwarg can be a single bool (applied to all) or also a list/tuple with the same number of entries like new_name, etc.

Examples

The deprecation warnings are not shown in the following examples.

To deprecate a positional or keyword argument:

>>> from astropy.utils.decorators import deprecated_renamed_argument
>>> @deprecated_renamed_argument('sig', 'sigma', '1.0')
... def test(sigma):
...     return sigma

>>> test(2)
2
>>> test(sigma=2)
2
>>> test(sig=2)
2

To deprecate an argument catched inside the **kwargs the arg_in_kwargs has to be set:

>>> @deprecated_renamed_argument('sig', 'sigma', '1.0',
...                             arg_in_kwargs=True)
... def test(**kwargs):
...     return kwargs['sigma']

>>> test(sigma=2)
2
>>> test(sig=2)
2

By default providing the new and old keyword will lead to an Exception. If a Warning is desired set the relax argument:

>>> @deprecated_renamed_argument('sig', 'sigma', '1.0', relax=True)
... def test(sigma):
...     return sigma

>>> test(sig=2)
2

It is also possible to replace multiple arguments. The old_name, new_name and since have to be tuple or list and contain the same number of entries:

>>> @deprecated_renamed_argument(['a', 'b'], ['alpha', 'beta'],
...                              ['1.0', 1.2])
... def test(alpha, beta):
...     return alpha, beta

>>> test(a=2, b=3)
(2, 3)

In this case arg_in_kwargs and relax can be a single value (which is applied to all renamed arguments) or must also be a tuple or list with values for each of the arguments.

Warning

This decorator needs to access the original signature of the decorated function. Therefore this decorator must be the first decorator on any function if it needs to work for Python before version 3.4.