speechbrain.utils.importutils module

Module importing related utilities.

Author

• Sylvain de Langen 2024

Summary

Classes:

DeprecatedModuleRedirect	Defines a module type that lazily imports the target module using LazyModule, but logging a deprecation warning when the import is actually being performed.
LazyModule	Defines a module type that lazily imports the target module, thus exposing contents without importing the target module needlessly.

Functions:

deprecated_redirect	Patches the module list to add a lazy redirection from old_import to new_import, emitting a DeprecationWarning when imported.
find_imports	Returns a list of importable scripts in the same module as the specified file.
lazy_export	Makes name lazily available under the module list for the specified package, unless it was loaded already, in which case it is ignored.
lazy_export_all	Makes all modules under a module lazily importable merely by accessing them; e.g. foo/bar.py could be accessed with foo.bar.some_func().

Reference

class speechbrain.utils.importutils.LazyModule(name: str, target: str, package: str | None)

Bases: ModuleType

Defines a module type that lazily imports the target module, thus exposing contents without importing the target module needlessly.

Parameters:

• name (str) – Name of the module.

• target (str) – Module to be loading lazily.

• package (str, optional) – If specified, the target module load will be relative to this package. Depending on how you inject the lazy module into the environment, you may choose to specify the package here, or you may choose to include it into the name with the dot syntax. e.g. see how lazy_export() and deprecated_redirect() differ.

ensure_module(stacklevel: int) → ModuleType

Ensures that the target module is imported and available as self.lazy_module, also returning it.

Parameters:

stacklevel (int) – The stack trace level of the function that caused the import to occur, relative to the caller of this function (e.g. if in function f you call ensure_module(1), it will refer to the function that called f).

Raises:

AttributeError – When the function responsible for the import attempt is found to be inspect.py, we raise an AttributeError here. This is because some code will inadvertently cause our modules to be imported, such as some of PyTorch’s op registering machinery.

Return type:

The target module after ensuring it is imported.

class speechbrain.utils.importutils.DeprecatedModuleRedirect(old_import: str, new_import: str, extra_reason: str | None = None)

Bases: LazyModule

Defines a module type that lazily imports the target module using LazyModule, but logging a deprecation warning when the import is actually being performed.

This is only the module type itself; if you want to define a redirection, use deprecated_redirect() instead.

Parameters:

• old_import (str) – Old module import path e.g. mypackage.myoldmodule

• new_import (str) – New module import path e.g. mypackage.mynewcoolmodule.mycoolsubmodule

• extra_reason (str, optional) – If specified, extra text to attach to the warning for clarification (e.g. justifying why the move has occurred, or additional problems to look out for).

ensure_module(stacklevel: int) → ModuleType

speechbrain.utils.importutils.find_imports(file_path: str, find_subpackages: bool = False) → List[str]

Returns a list of importable scripts in the same module as the specified file. e.g. if you have foo/__init__.py and foo/bar.py, then files_in_module("foo/__init__.py") then the result will be ["bar"].

Not recursive; this is only applies to the direct modules/subpackages of the package at the given path.

Parameters:

• file_path (str) – Path of the file to navigate the directory of. Typically the __init__.py path this is called from, using __file__.

• find_subpackages (bool) – Whether we should find the subpackages as well.

Returns:

imports – List of importable scripts with the same module.

Return type:

List[str]

speechbrain.utils.importutils.lazy_export(name: str, package: str)

Makes name lazily available under the module list for the specified package, unless it was loaded already, in which case it is ignored.

Parameters:

• name (str) – Name of the module, as long as it can get imported with {package}.{name}.

• package (str) – The relevant package, usually determined with __name__ from the __init__.py.

Return type:

None

speechbrain.utils.importutils.lazy_export_all(init_file_path: str, package: str, export_subpackages: bool = False)

Makes all modules under a module lazily importable merely by accessing them; e.g. foo/bar.py could be accessed with foo.bar.some_func().

Parameters:

• init_file_path (str) – Path of the __init__.py file, usually determined with __file__ from there.

• package (str) – The relevant package, usually determined with __name__ from the __init__.py.

• export_subpackages (bool) – Whether we should make the subpackages (subdirectories) available directly as well.

speechbrain.utils.importutils.deprecated_redirect(old_import: str, new_import: str, extra_reason: str | None = None, also_lazy_export: bool = False) → None

Patches the module list to add a lazy redirection from old_import to new_import, emitting a DeprecationWarning when imported.

Parameters:

• old_import (str) – Old module import path e.g. mypackage.myoldmodule

• new_import (str) – New module import path e.g. mypackage.mycoolpackage.mynewmodule

• extra_reason (str, optional) – If specified, extra text to attach to the warning for clarification (e.g. justifying why the move has occurred, or additional problems to look out for).

• also_lazy_export (bool) – Whether the module should also be exported as a lazy module in the package determined in old_import. e.g. if you had a foo.bar.somefunc import as old_import, assuming you have foo imported (or lazy loaded), you could use foo.bar.somefunc directly without importing foo.bar explicitly.