pulse2percept.utils.deprecation

deprecated, deprecate_parameter, deprecated_alias, rename_parameter, is_deprecated

Functions

is_deprecated(func)

Helper to check if func is wrapped by the deprecated decorator

rename_deprecated_params(obj_name, params, specs)

Rewrite renamed model parameters that were supplied by their old name

warn_deprecated_params(obj_name, supplied, specs)

Warn about deprecated model parameters that were supplied by name

Classes

deprecate_parameter(name[, ...])

Decorator for a deprecated function or method parameter.

deprecated([alt_func, deprecated_version, ...])

Decorator to mark deprecated functions and classes with a warning.

deprecated_alias(new_name[, ...])

Descriptor that keeps a renamed model parameter usable by its old name.

rename_parameter(old_name, new_name[, ...])

Decorator for a renamed function or method parameter.
class pulse2percept.utils.deprecation.deprecated(alt_func=None, deprecated_version=None, removed_version=None, extra_msg=None)[source]

Decorator to mark deprecated functions and classes with a warning.

See also

Adapted from https://github.com/scikit-learn/scikit-learn/blob/master/sklearn/utils/deprecation.py.

Parameters:

  • alt_func (str) – If given, tell user what function to use instead.

  • deprecated_version (float or str) – The package version in which the function/class was first marked as deprecated.

  • removed_version (float or str) – The package version in which the deprecated function/class will be removed.

  • extra_msg (str, optional) –

    Appended to the warning and to the docstring. Say here what a caller has to change beyond the name when alt_func is not a drop-in replacement – different defaults, dropped behavior – so that swapping one for the other cannot silently change results.

    Added in version 0.11.0.

class pulse2percept.utils.deprecation.deprecate_parameter(name, deprecated_version=None, removed_version=None, addendum=None)[source]

Decorator for a deprecated function or method parameter.

The parameter remains accepted but is ignored, and explicit use raises DeprecationWarning. Use rename_parameter when the parameter is only being renamed.

Added in version 0.9.1.

Parameters:

  • name (str) – Deprecated parameter name.

  • deprecated_version (float or str) – Version in which it was deprecated.

  • removed_version (float or str) – Version in which it will be removed.

  • addendum (str, optional) – Additional warning text.

class pulse2percept.utils.deprecation.rename_parameter(old_name, new_name, deprecated_version=None, removed_version=None)[source]

Decorator for a renamed function or method parameter.

Keyword use of the old name is forwarded to the new name and emits DeprecationWarning.

Added in version 0.10.0.

Parameters:

  • old_name (str) – Deprecated parameter name.

  • new_name (str) – Replacement parameter name.

  • deprecated_version (float or str) – Version in which the old name was deprecated.

  • removed_version (float or str) – Version in which the old name will be removed.

class pulse2percept.utils.deprecation.deprecated_alias(new_name, deprecated_version=None, removed_version=None)[source]

Descriptor that keeps a renamed model parameter usable by its old name.

Use this for parameters stored in get_default_params. For parameters declared in a function signature, use rename_parameter.

Added in version 0.10.0.

pulse2percept.utils.deprecation.warn_deprecated_params(obj_name, supplied, specs, stacklevel=3)[source]

Warn about deprecated model parameters that were supplied by name

pulse2percept models take their parameters as **params, validated against get_default_params rather than declared in a signature, so deprecate_parameter cannot see them. This is the equivalent for that path: hand it the names the caller actually supplied, and it warns for the deprecated ones.

Added in version 0.9.1.

Parameters:

  • obj_name (str) – Name of the model, as it should appear in the warning.

  • supplied (iterable of str) – Parameter names the caller passed explicitly. Names that are not deprecated are skipped, so it is fine to pass all of them.

  • specs (dict) – Maps a deprecated parameter name to the deprecate_parameter describing it, so that signature-level and model-level deprecations word alike.

  • stacklevel (int, optional) – Passed to warnings.warn. Exact attribution is not possible through a chain of super().__init__ calls of varying depth, so the message names the parameter and the model rather than relying on it.

pulse2percept.utils.deprecation.rename_deprecated_params(obj_name, params, specs)[source]

Rewrite renamed model parameters that were supplied by their old name

The counterpart of warn_deprecated_params() for parameters that were renamed rather than retired: the value is kept, but moves to the new name, and the warning names the replacement.

Handing the caller a rewritten dict, rather than letting the assignment fall through to the deprecated_alias descriptor, keeps the warning to one per parameter and lets it name the model the user actually called.

Added in version 0.10.0.

Parameters:

  • obj_name (str) – Name of the model, as it should appear in the warning.

  • params (dict) – Parameters the caller supplied. Names that were not renamed are left alone, so it is fine to pass all of them.

  • specs (dict) – Maps a renamed parameter’s old name to the deprecated_alias describing it.

Returns:

params – params with every renamed key replaced by its new name. The original dict is returned untouched if none of the keys were renamed.

Return type:

dict

Raises:

TypeError – If both names of the same parameter were supplied. Which one won would otherwise come down to the order they were passed in.

pulse2percept.utils.deprecation.is_deprecated(func)[source]

Helper to check if func is wrapped by the deprecated decorator