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 valuedict_to_check[old_key]
andold_key
will be removed from the dict. by default Nonereplace_rules (Mapping[Hashable, tuple[Any, Any]]) – ({old_key: old_value}, {new_key: new_value}), If
dict_to_check[old_key]
has the valueold_value
,dict_to_check[new_key]
it will be set tonew_value
.old_key
will be removed from the dict ifold_key
andnew_key
aren’t equal. by default Nonestacklevel (int) – Stack at which the warning should be shown as raise. , by default 3
- Raises:
ValueError – If both
swap_keys
andreplace_rules
are None (default) or not None.OverDueDeprecation – If the current version is greater or equal to
to_be_removed_in_version
.
See also
Notes
To prevent confusion exactly one of
replace_rules
andswap_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"}