warn_deprecated

glotaran.deprecation.deprecation_utils.warn_deprecated(*, deprecated_qual_name_usage: str, new_qual_name_usage: str, to_be_removed_in_version: str, check_qual_names: tuple[bool, bool] = (True, True), stacklevel: int = 2, importable_indices: tuple[int, int] = (1, 1)) → None[source]

Raise deprecation warning with change information.

The change information are 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.

  • check_qual_names (tuple[bool, bool]) –

    Whether or not to check for the existence deprecated_qual_name_usage and deprecated_qual_name_usage

    • Set the first value to False to prevent infinite recursion error when changing a module attribute import.

    • Set the second value to False if the new usage in in a different package or there is none.

  • stacklevel (int) – Stack at which the warning should be shown as raise. Default: 2

  • importable_indices (tuple[int, 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.

Raises:

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

See also

deprecate, deprecate_module_attribute, deprecate_submodule, check_qualnames_in_tests

Examples

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

glotaran/deprecation/modules/glotaran_root.py
def read_parameters_from_yaml_file(model_path: str):
    warn_deprecated(
        deprecated_qual_name_usage="glotaran.read_parameters_from_yaml_file(model_path)",
        new_qual_name_usage="glotaran.io.load_model.load_model(model_path)",
        to_be_removed_in_version="0.6.0",
    )
    return load_model(model_path)