deprecated_renamed_argument

astropy.utils.decorators.deprecated_renamed_argument(old_name, new_name, since, arg_in_kwargs=False, relax=False, pending=False, warning_type=<class 'astropy.utils.exceptions.AstropyDeprecationWarning'>)

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.

warning_type : warning

Warning to be issued. Default is AstropyDeprecationWarning.

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 caught 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.