deprecated_renamed_argument#
- sunpy.util.deprecated_renamed_argument(
- old_name,
- new_name,
- since,
- arg_in_kwargs=False,
- relax=False,
- pending=False,
- warning_type=<class 'sunpy.util.exceptions.SunpyDeprecationWarning'>,
- 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 thenew_name
replaced it at the same position in the signature. If theold_name
argument is given when calling the decorated function the decorator will catch it and issue a deprecation warning and pass it on asnew_name
argument.- Parameters:
old_name (str or sequence of str) – The old name of the argument.
new_name (str or sequence of str or None) – The new name of the argument. Set this to
None
to remove the argumentold_name
instead of renaming it.since (str or number or sequence of str or number) – The release at which the old argument became deprecated.
arg_in_kwargs (bool 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 toTrue
. Otherwise the decorator will throw an Exception if thenew_name
cannot be found in the signature of the decorated function. Default isFalse
.relax (bool or sequence of bool, optional) – If
False
aTypeError
is raised if bothnew_name
andold_name
are given. IfTrue
the value fornew_name
is used and a Warning is issued. Default isFalse
.pending (bool or sequence of bool, optional) – If
True
this will hide the deprecation warning and ignore the correspondingrelax
parameter value. Default isFalse
.warning_type (Warning) – Warning to be issued. Default is
AstropyDeprecationWarning
.alternative (str, 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.message (str, optional) – A custom warning message. If provided then
since
andalternative
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 thenew_name
andsince
must also be a list or tuple with the same number of entries.relax
andarg_in_kwarg
can be a single bool (applied to all) or also a list/tuple with the same number of entries likenew_name
, etc.