deprecator

Function for recording and reporting deprecations.

Notes

this file is copied (with minor modifications) from the Nibabel. nipy/nibabel. See COPYING file distributed along with the Nibabel package for the copyright and license terms.

_LEADING_WHITE	Compiled regular expression object.
ExpiredDeprecationError	Error for expired deprecation.
ArgsDeprecationWarning	Warning for args deprecation.
cmp_pkg_version(version_str[, pkg_version_str])	Compare version_str to current package version.
is_bad_version(version_str[, version_comparator])	Return True if version_str is too high.
deprecate_with_version(message[, since, ...])	Return decorator function for deprecation warning / error.
deprecated_params(old_name[, new_name, ...])	Deprecate a renamed or removed function argument.

_LEADING_WHITE

fury.deprecator._LEADING_WHITE

Compiled regular expression object.

ExpiredDeprecationError

class fury.deprecator.ExpiredDeprecationError

Bases: RuntimeError

Error for expired deprecation.

Error raised when a called function or method has passed out of its deprecation period.

ArgsDeprecationWarning

class fury.deprecator.ArgsDeprecationWarning

Bases: DeprecationWarning

Warning for args deprecation.

Warning raised when a function or method argument has changed or removed.

cmp_pkg_version

fury.deprecator.cmp_pkg_version(version_str, pkg_version_str='0.12.0')

Compare version_str to current package version.

Parameters:

version_strstr

Version string to compare to current package version

pkg_version_strstr, optional

Version of our package. Optional, set from __version__ by default.

Returns:

version_cmpint

1 if version_str is a later version than pkg_version_str, 0 if same, -1 if earlier.

Examples

>>> cmp_pkg_version('1.2.1', '1.2.0')
1
>>> cmp_pkg_version('1.2.0dev', '1.2.0')
-1

is_bad_version

fury.deprecator.is_bad_version(version_str, version_comparator=<function cmp_pkg_version>)

Return True if version_str is too high.

deprecate_with_version

fury.deprecator.deprecate_with_version(message, since='', until='', version_comparator=<function cmp_pkg_version>, warn_class=<class 'DeprecationWarning'>, error_class=<class 'fury.deprecator.ExpiredDeprecationError'>)

Return decorator function for deprecation warning / error.

The decorated function / method will:

• Raise the given warning_class warning when the function / method gets called, up to (and including) version until (if specified);

• Raise the given error_class error when the function / method gets called, when the package version is greater than version until (if specified).

Parameters:

messagestr

Message explaining deprecation, giving possible alternatives.

sincestr, optional

Released version at which object was first deprecated.

untilstr, optional

Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

version_comparatorcallable

Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator`, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.

warn_classclass, optional

Class of warning to generate for deprecation.

error_classclass, optional

Class of error to generate when version_comparator returns 1 for a given argument of until.

Returns:

deprecatorfunc

Function returning a decorator.

deprecated_params

fury.deprecator.deprecated_params(old_name, new_name=None, since='', until='', version_comparator=<function cmp_pkg_version>, arg_in_kwargs=False, warn_class=<class 'fury.deprecator.ArgsDeprecationWarning'>, error_class=<class 'fury.deprecator.ExpiredDeprecationError'>, alternative='')

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 list/tuple thereof

The old name of the argument.

new_namestr or list/tuple thereof or None, optional

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

sincestr or number or list/tuple thereof, optional

The release at which the old argument became deprecated.

untilstr or number or list/tuple thereof, optional

Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

version_comparatorcallable

Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.

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

warn_classwarning, optional

Warning to be issued.

error_classException, optional

Error to be issued

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.

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

This function is based on the Astropy (major modification). astropy/astropy. See COPYING file distributed along with the astropy package for the copyright and license terms.

Examples

The deprecation warnings are not shown in the following examples. To deprecate a positional or keyword argument:: >>> from fury.deprecator import deprecated_params >>> @deprecated_params(‘sig’, ‘sigma’, ‘0.3’) … def test(sigma): … return sigma >>> test(2) 2 >>> test(sigma=2) 2 >>> test(sig=2) # doctest: +SKIP 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_params([‘a’, ‘b’], [‘alpha’, ‘beta’], … [‘0.2’, 0.4]) … def test(alpha, beta): … return alpha, beta >>> test(a=2, b=3) # doctest: +SKIP (2, 3)