Function attempt_import

xarray/core/utils.py:1334–1385

Import an optional dependency, and raise an informative error on failure. Parameters ---------- module : str Module to import. For example, ``'zarr'`` or ``'matplotlib.pyplot'``. Returns ------- module : ModuleType The Imported module. Raises ------

(module: str)

def attempt_import(module: str) -> ModuleType:
    """Import an optional dependency, and raise an informative error on failure.

    Parameters
    ----------
    module : str
        Module to import. For example, ``'zarr'`` or ``'matplotlib.pyplot'``.

    Returns
    -------
    module : ModuleType
        The Imported module.

    Raises
    ------
    ImportError
        If the module could not be imported.

    Notes
    -----
    Static type checkers will not be able to infer the type of the returned module,
    so it is recommended to precede this function with a direct import of the module,
    guarded by an ``if TYPE_CHECKING`` block, to preserve type checker functionality.
    See the examples section below for a demonstration.

    Examples
    --------
    >>> from xarray.core.utils import attempt_import
    >>> if TYPE_CHECKING:
    ...     import zarr
    ... else:
    ...     zarr = attempt_import("zarr")
    ...
    """
    install_mapping = dict(nc_time_axis="nc-time-axis")
    package_purpose = dict(
        zarr="for working with Zarr stores",
        cftime="for working with non-standard calendars",
        matplotlib="for plotting",
        hypothesis="for the `xarray.testing.strategies` submodule",
    )
    package_name = module.split(".", maxsplit=1)[0]  # e.g. "zarr" from "zarr.storage"
    install_name = install_mapping.get(package_name, package_name)
    reason = package_purpose.get(package_name, "")
    try:
        return importlib.import_module(module)
    except ImportError as e:
        raise ImportError(
            f"The {install_name} package is required {reason}"
            " but could not be imported."
            " Please install it with your package manager (e.g. conda or pip)."
        ) from e


_DEFAULT_NAME = ReprObject("<default-name>")