Skip to content

Optional import

optional_import #

Functions:

Name Description
optional_import

Attempt to import an optional module and handle its absence gracefully.

optional_import #

optional_import(
    module_name: str, raise_error: bool = False
) -> typing.Tuple[typing.Any, bool]

Attempt to import an optional module and handle its absence gracefully.

This function is useful when you want to provide optional features that depend on modules that may not be installed.

Parameters:

Name Type Description Default

module_name #

str

Name of the module to import (e.g., 'numpy', 'torch').

required

raise_error #

bool

If True, raise an OptionalImportError when the module is not found. If False, return (None, False) when import fails.

False

Returns:

Type Description
tuple

A tuple containing (module, success_flag), where: - module: The imported module if successful, None if failed - success_flag: True if import succeeded, False otherwise

Examples:

>>> # Basic usage - silent failure
>>> numpy, has_numpy = optional_import("numpy")
>>> if not has_numpy:
...     raise OptionalImportError("numpy")
>>> # Usage with error raising
>>> torch, _ = optional_import(
...     "torch", raise_error=True
... )
>>> # Will raise OptionalImportError if torch is not installed
Source code in src/imgtools/utils/optional_import.py
def optional_import(
    module_name: str,
    raise_error: bool = False,
) -> Tuple[Any, bool]:
    """
    Attempt to import an optional module and handle its absence gracefully.

    This function is useful when you want to provide optional features that depend
    on modules that may not be installed.

    Parameters
    ----------
    module_name : str
        Name of the module to import (e.g., 'numpy', 'torch').
    raise_error : bool, optional
        If True, raise an OptionalImportError when the module is not found.
        If False, return (None, False) when import fails.

    Returns
    -------
    tuple
        A tuple containing (module, success_flag), where:
        - module: The imported module if successful, None if failed
        - success_flag: True if import succeeded, False otherwise
    Examples
    --------
    >>> # Basic usage - silent failure
    >>> numpy, has_numpy = optional_import("numpy")
    >>> if not has_numpy:
    ...     raise OptionalImportError("numpy")

    >>> # Usage with error raising
    >>> torch, _ = optional_import(
    ...     "torch", raise_error=True
    ... )
    >>> # Will raise OptionalImportError if torch is not installed
    """
    try:
        module = importlib.import_module(module_name)
        return module, True
    except ImportError as ie:
        if raise_error:
            raise OptionalImportError(module_name) from ie
        return None, False