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'>, alternative='', message='')

Deprecate a _renamed_ or _removed_ 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_namestr or sequence of str

The old name of the argument.

new_namestr or sequence of str or None

The new name of the argument. Set this to None to remove the argument old_name instead of renaming it.

sincestr or number or sequence of str or number

The release at which the old argument became deprecated.

arg_in_kwargsbool or sequence of bool, 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.

relaxbool or sequence of bool, 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.

pendingbool or sequence of bool, optional

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

warning_typeWarning

Warning to be issued. Default is AstropyDeprecationWarning.

alternativestr, optional

An alternative function or class name that the user may use in place of the deprecated object if new_name is None. The deprecation warning will tell the user about this alternative if provided.

messagestr, optional

A custom warning message. If provided then since and alternative options will have no effect.

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.