deprecator

Function for recording and reporting deprecations.

Notes

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

ArgsDeprecationWarning

Warning for args deprecation.

ExpiredDeprecationError

Error for expired deprecation.

cmp_pkg_version(version_str[, pkg_version_str])

Compare version_str to current package version.

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.

is_bad_version(version_str[, version_comparator])

Return True if version_str is too high.

optional_package(name[, trip_msg])

Return package-like thing and module setup for package name.

signature(obj, *[, follow_wrapped])

Get a signature object for the passed callable.

ArgsDeprecationWarning

class fury.deprecator.ArgsDeprecationWarning[source]

Bases: DeprecationWarning

Warning for args deprecation.

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

__init__()

Initialize self. See help(type(self)) for accurate signature.

ExpiredDeprecationError

class fury.deprecator.ExpiredDeprecationError[source]

Bases: RuntimeError

Error for expired deprecation.

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

__init__()

Initialize self. See help(type(self)) for accurate signature.

cmp_pkg_version

fury.deprecator.cmp_pkg_version(version_str, pkg_version_str='0.6.0')[source]

Compare version_str to current package version.

Parameters
  • version_str (str) – Version string to compare to current package version

  • pkg_version_str (str, optional) – Version of our package. Optional, set fom __version__ by default.

Returns

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

Return type

int

Examples

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

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

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
  • message (str) – Message explaining deprecation, giving possible alternatives.

  • since (str, optional) – Released version at which object was first deprecated.

  • until (str, optional) – Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

  • version_comparator (callable) – 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_class (class, optional) – Class of warning to generate for deprecation.

  • error_class (class, optional) – Class of error to generate when version_comparator returns 1 for a given argument of until.

Returns

deprecator – Function returning a decorator.

Return type

func

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='')[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_name (str or list/tuple thereof) – The old name of the argument.

  • new_name (str 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.

  • since (str or number or list/tuple thereof, optional) – The release at which the old argument became deprecated.

  • until (str 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_comparator (callable) – 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_kwargs (bool 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_class (warning, optional) – Warning to be issued.

  • error_class (Exception, optional) – Error to be issued

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

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). https://github.com/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)  
2

To deprecate an argument caught inside the **kwargs the arg_in_kwargs has to be set:

>>> @deprecated_params('sig', 'sigma', '1.0',
...                    arg_in_kwargs=True)
... def test(**kwargs):
...     return kwargs['sigma']
>>> test(sigma=2)
2
>>> 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_params(['a', 'b'], ['alpha', 'beta'],
...                    ['0.2', 0.4])
... def test(alpha, beta):
...     return alpha, beta
>>> test(a=2, b=3)  
(2, 3)

is_bad_version

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

Return True if version_str is too high.

optional_package

fury.deprecator.optional_package(name, trip_msg=None)[source]

Return package-like thing and module setup for package name.

Parameters
  • name (str) – package name

  • trip_msg (None or str) – message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.

Returns

  • pkg_like (module or TripWire instance) – If we can import the package, return it. Otherwise return an object raising an error when accessed

  • have_pkg (bool) – True if import for package was successful, false otherwise

  • module_setup (function) – callable usually set as setup_module in calling namespace, to allow skipping tests.

Examples

Typical use would be something like this at the top of a module using an optional package: >>> from fury.optpkg import optional_package >>> pkg, have_pkg, setup_module = optional_package(‘not_a_package’) Of course in this case the package doesn’t exist, and so, in the module: >>> have_pkg False and >>> pkg.some_function() #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): … TripWireError: We need package not_a_package for these functions, but import not_a_package raised an ImportError If the module does exist - we get the module >>> pkg, _, _ = optional_package(‘os’) >>> hasattr(pkg, ‘path’) True Or a submodule if that’s what we asked for >>> subpkg, _, _ = optional_package(‘os.path’) >>> hasattr(subpkg, ‘dirname’) True

signature

fury.deprecator.signature(obj, *, follow_wrapped=True)[source]

Get a signature object for the passed callable.