pds4_tools.utils.deprecation module

exception PDS4ToolsDeprecationWarning(message=None, name=None, obj_type=None, since=None, removal=None, alternative=None, addendum=None)

Bases: UserWarning

Custom warning for deprecated PDS4 Tools features.

Parameters

messagestr, optional

Message to show to user. When given, all other options are ignored.

namestr, optional

Name of feature that is deprecated. Required when message is absent.

obj_typestr, optional

Type of feature that is deprecated; e.g., function or class. Required when message is absent.

sincestr, optional

Version from which feature is deprecated. Required when message is absent.

removalstr or bool, optional

Version from which feature may be removed. Defaults to the next release after since, unless set to False.

alternativestr, optional

An alternative API to suggest to the user.

addendumstr, optional

An addendum following the main deprecation message.

Notes

Inherits from UserWarning rather than DeprecationWarning because the latter is not necessarily shown to user by default.

warn_deprecated(since=None, message=None, name=None, obj_type=None, removal=None, alternative=None, addendum=None, stacklevel=1)

Emit a warning that a PDS4 Tools feature is deprecated.

Parameters

sincestr, optional

Version from which feature is deprecated. Required when message is absent.

messagestr, optional

Message to show to user. When given, all other options are ignored.

namestr, optional

Name of feature that is deprecated. Required when message is absent.

obj_typestr, optional

Type of feature that is deprecated; e.g., function or class. Required when message is absent.

removalstr or bool, optional

Version from which feature may be removed. Defaults to the next release after since, unless set to False.

alternativestr, optional

An alternative API to suggest to the user.

addendumstr, optional

An addendum following the main deprecation message.

stacklevelint, optional

When above 1, makes the warning refer to deprecation()’s caller, rather than to the source of deprecation() itself. Defaults to 1.

Returns

None

deprecated(since=None, message=None, name=None, removal=None, alternative=None, addendum=None)

Decorator to mark a function, property or class as deprecated.

Parameters

sincestr, optional

Version from which feature is deprecated. Required when message is absent.

messagestr, optional

Message to show to user. When given, all other options are ignored.

namestr, optional

Name of feature that is deprecated. Required when message is absent.

removalstr or bool, optional

Version from which feature may be removed. Defaults to the next release after since, unless set to False.

alternativestr, optional

An alternative API to suggest to the user.

addendumstr, optional

An addendum following the main deprecation message.

Notes

Adapted from mpl._api.deprecation.deprecated.

Examples

@deprecated('1.3')
def func_to_deprecate():
    pass

rename_parameter(since, old, new, func=None, removal=None)

Decorator to indicate that parameter old of func is renamed to new.

The actual implementation of func should use new, not old. If old is passed to func, a deprecation warning is emitted, and its value is used unless new was also passed.

Parameters

sincestr

Version in which the parameter was renamed.

oldstr

Old name of the parameter.

newstr

New name of the parameter.

funcfunc, optional

Function in which the parameter was renamed.

removalstr or bool, optional

Version in which support for the old parameter will be fully dropped. Defaults to the next release after since, unless set to False.

Notes

Adapted from mpl._api.deprecation.rename_parameter.

Examples

@rename_parameter('1.3', 'bad_name', 'good_name')
def func(good_name):
    pass

delete_parameter(since, name, func=None, removal=None, alternative=None)

Decorator to indicate that parameter name of func is being deprecated.

The actual implementation of func should keep the name parameter in its signature.

Parameters that come after the deprecated parameter effectively become keyword-only.

Parameters

sincestr

Version in which the parameter was deprecated.

namestr

Name of the parameter.

funcfunc, optional

Function in which the parameter is deprecated.

removalstr or bool, optional

Version in which support for the parameter will be fully dropped. Defaults to the next release after since, unless set to False.

alternativestr, optional

An alternative API to suggest to the user.

Notes

Adapted from mpl._api.deprecation.delete_parameter.

Examples

@delete_parameter('1.3', 'unused')
def func(used_arg, other_arg, unused, more_args):
    pass