deprecate_dict_entry

glotaran.deprecation.deprecation_utils.deprecate_dict_entry(*, dict_to_check: MutableMapping[Hashable, Any], deprecated_usage: str, new_usage: str, to_be_removed_in_version: str, swap_keys: tuple[Hashable, Hashable] | None = None, replace_rules: tuple[Mapping[Hashable, Any], Mapping[Hashable, Any]] | None = None, stacklevel: int = 3) → None[source]

Replace dict entry inplace and warn about usage change, if present in the dict.

Parameters:

  • dict_to_check (MutableMapping[Hashable, Any]) – Dict which should be checked.

  • deprecated_usage (str) – Old usage to inform user (only used in warning).

  • new_usage (str) – New usage to inform user (only used in warning).

  • to_be_removed_in_version (str) – Version the support for this usage will be removed.

  • swap_keys (tuple[Hashable, Hashable]) – (old_key, new_key), dict_to_check[new_key] will be assigned the value dict_to_check[old_key] and old_key will be removed from the dict. by default None

  • replace_rules (Mapping[Hashable, tuple[Any, Any]]) – ({old_key: old_value}, {new_key: new_value}), If dict_to_check[old_key] has the value old_value, dict_to_check[new_key] it will be set to new_value. old_key will be removed from the dict if old_key and new_key aren’t equal. by default None

  • stacklevel (int) – Stack at which the warning should be shown as raise. , by default 3

Raises:

  • ValueError – If both swap_keys and replace_rules are None (default) or not None.

  • OverDueDeprecation – If the current version is greater or equal to to_be_removed_in_version.

See also

warn_deprecated

Notes

To prevent confusion exactly one of replace_rules and swap_keys needs to be passed.

Examples

For readability sake the warnings won’t be shown in the examples.

Swapping key names:

>>> dict_to_check = {"foo": 123}
>>> deprecate_dict_entry(
        dict_to_check=dict_to_check,
        deprecated_usage="foo",
        new_usage="bar",
        to_be_removed_in_version="0.6.0",
        swap_keys=("foo", "bar")
    )
>>> dict_to_check
{"bar": 123}

Changing values:

>>> dict_to_check = {"foo": 123}
>>> deprecate_dict_entry(
        dict_to_check=dict_to_check,
        deprecated_usage="foo: 123",
        new_usage="foo: 123.0",
        to_be_removed_in_version="0.6.0",
        replace_rules=({"foo": 123}, {"foo": 123.0})
    )
>>> dict_to_check
{"foo": 123.0}

Swapping key names AND changing values:

>>> dict_to_check = {"type": "kinetic-spectrum"}
>>> deprecate_dict_entry(
        dict_to_check=dict_to_check,
        deprecated_usage="type: kinectic-spectrum",
        new_usage="default_megacomplex: decay",
        to_be_removed_in_version="0.6.0",
        replace_rules=({"type": "kinetic-spectrum"}, {"default_megacomplex": "decay"})
    )
>>> dict_to_check
{"default_megacomplex": "decay"}