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 to mark a single function or method parameter as deprecated

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

Decorator to mark deprecated functions and classes with a warning.

deprecated_alias(new_name[, ...])

Class attribute that keeps a renamed parameter usable under its old name

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

Decorator to rename a single function or method parameter
class pulse2percept.utils.deprecation.deprecated(alt_func=None, deprecated_version=None, removed_version=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.

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

Decorator to mark a single function or method parameter as deprecated

The decorated callable keeps accepting the parameter, so that existing code does not break, but the value is ignored. A DeprecationWarning is raised whenever the parameter is passed explicitly, whether by keyword or by position.

Use this when a parameter is going away but the callable itself stays. To deprecate an entire function, class, or property, use deprecated instead. To keep a parameter that is merely being renamed working under its old name, use rename_parameter instead.

Added in version 0.9.1.

Note

This decorator only produces the warning. Document the parameter itself by adding a .. deprecated:: directive to its entry in the docstring’s Parameters section, which is where numpydoc expects it.

See also

Modeled on matplotlib’s matplotlib._api.delete_parameter.

Parameters:

  • name (str) – Name of the deprecated parameter. Must appear in the signature of the decorated callable, otherwise a ValueError is raised at decoration time (which catches the parameter being renamed or dropped).

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

  • removed_version (float or str) – The package version in which the parameter will be removed.

  • addendum (str, optional) – Text appended to the warning, e.g. to spell out what the parameter used to do or how the behavior differs now that it is ignored.

Examples

>>> from pulse2percept.utils import deprecate_parameter
>>> @deprecate_parameter('engine', deprecated_version='0.9.1',
...                      removed_version='0.10.0')
... def predict(data, engine=None):
...     return data
>>> predict([1, 2])  # no warning
[1, 2]
class pulse2percept.utils.deprecation.rename_parameter(old_name, new_name, deprecated_version=None, removed_version=None)[source]

Decorator to rename a single function or method parameter

Calls that use the old name keep working: the value is forwarded to the new parameter, so the callable behaves exactly as it did before, but a DeprecationWarning is raised. Use this when a parameter is only being renamed; when its value is no longer read at all, use deprecate_parameter instead.

Only keyword use of the old name is forwarded, which is the only way it can be recognized: a positional argument is bound by position and never mentions either name.

Added in version 0.10.0.

Note

Models take their parameters as **params, validated against get_default_params rather than declared in a signature, so this decorator cannot see them. Rename those with a deprecated_alias instead.

Parameters:

  • old_name (str) – The name being retired. Must not appear in the signature of the decorated callable, otherwise a ValueError is raised at decoration time (which catches the rename never having been made).

  • new_name (str) – The name that replaces it. Must appear in the signature, otherwise a ValueError is raised at decoration time.

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

  • removed_version (float or str) – The package version in which the old name will stop working.

Examples

>>> from pulse2percept.utils import rename_parameter
>>> @rename_parameter('axlambda', 'lam', deprecated_version='0.10.0',
...                   removed_version='0.11.0')
... def decay(lam=1):
...     return lam
>>> decay(lam=3)  # no warning
3
class pulse2percept.utils.deprecation.deprecated_alias(new_name, deprecated_version=None, removed_version=None)[source]

Class attribute that keeps a renamed parameter usable under its old name

Assign one in the class body, under the old name, to a Parametrized subclass whose parameters live in get_default_params rather than in a signature:

class MyModel(BaseModel):

    axlambda = deprecated_alias('lam', deprecated_version='0.10.0')

    def get_default_params(self):
        return {'lam': 500}

Reading or writing model.axlambda then reads or writes model.lam and raises a DeprecationWarning. The alias also registers itself in the owner’s _renamed_params, which is what lets the constructor, set_params and build keep accepting the old name as a keyword argument (see rename_deprecated_params()).

To rename a parameter that is declared in a signature, use rename_parameter instead.

Added in version 0.10.0.

Note

Document the rename by adding a .. versionchanged:: directive to the new parameter’s entry in the docstring’s Parameters section. The old name has no entry of its own, since nothing should be written against it any more.

Parameters:

  • new_name (str) – Name of the parameter that replaces the alias.

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

  • removed_version (float or str) – The package version in which the old name will stop working.

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