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='')[source]#

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.