deprecate

glotaran.deprecation.deprecation_utils.deprecate(*, deprecated_qual_name_usage: str, new_qual_name_usage: str, to_be_removed_in_version: str, has_glotaran_replacement: bool = True, importable_indices: tuple[int, int] = (1, 1)) → Callable[[DecoratedCallable], DecoratedCallable][source]

Decorate a function, method or class to deprecate it.

This raises deprecation warning with old / new usage information and end of support version.

Parameters:

  • deprecated_qual_name_usage (str) – Old usage with fully qualified name e.g.: 'glotaran.read_model_from_yaml(model_yml_str)'

  • new_qual_name_usage (str) – New usage as fully qualified name e.g.: 'glotaran.io.load_model(model_yml_str, format_name="yml_str")'

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

  • has_glotaran_replacement (bool) – Whether or not this functionality has a replacement in core pyglotaran. This will be mapped to the second entry of check_qualnames in warn_deprecated().

  • importable_indices (Sequence[int]) – Indices from right for most nested item which is importable for deprecated_qual_name_usage and new_qual_name_usage after splitting at .. This is used when the old or new usage is a method or mapping access. E.g. let deprecated_qual_name_usage be package.module.class.mapping["key"], then you would use importable_indices=(2, 1), this way func:check_qualnames_in_tests will import package.module.class and check if class has an attribute mapping. Default

Returns:

Original function or class throwing a Deprecation warning when used.

Return type:

DecoratedCallable

Raises:

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

See also

warn_deprecated, deprecate_module_attribute, deprecate_submodule, check_qualnames_in_tests

Examples

This is the way the old read_parameters_from_yaml_file was deprecated and the usage of load_model was promoted instead.

glotaran/deprecation/modules/glotaran_root.py
@deprecate(
    deprecated_qualname_usage="glotaran.read_parameters_from_yaml_file(model_path)",
    new_qualname_usage="glotaran.io.load_model(model_path)",
    to_be_removed_in_version="0.6.0",
)
def read_parameters_from_yaml_file(model_path: str):
    return load_model(model_path)