deprecate_module_attribute

glotaran.deprecation.deprecation_utils.deprecate_module_attribute(*, deprecated_qual_name: str, new_qual_name: str, to_be_removed_in_version: str, module_load_overwrite: str = '') → Any[source]

Import and return and anttribute from the new location.

This needs to be wrapped in the definition of a module wide __getattr__ function so it won’t throw warnings all the time (see example).

Parameters:

  • deprecated_qual_name (str) – Fully qualified name of the deprecated attribute e.g.: glotaran.ParameterGroup

  • new_qual_name (str) – Fully qualified name of the new attribute e.g.: glotaran.parameter.ParameterGroup

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

  • module_load_overwrite (str) – Overwrite the location the functionality will be set from. This allows preserving functionality without polluting a new module with code just for the sake of it. By default ‘’

Returns:

Module attribute from its new location.

Return type:

Any

Raises:

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

See also

deprecate, warn_deprecated, deprecate_submodule

Examples

When deprecating the usage of ParameterGroup the root of glotaran and promoting to import it from glotaran.parameter the following code was added to the root __init__.py.

glotaran/__init__.py
def __getattr__(attribute_name: str):
    from glotaran.deprecation import deprecate_module_attribute

    if attribute_name == "ParameterGroup":
        return deprecate_module_attribute(
            deprecated_qual_name="glotaran.ParameterGroup",
            new_qual_name="glotaran.parameter.ParameterGroup",
            to_be_removed_in_version="0.6.0",
        )

    raise AttributeError(f"module {__name__} has no attribute {attribute_name}")