Import an optional dependency. By default, if a dependency is missing an ImportError with a nice message will be raised. If a dependency is present, but too old, we raise. Parameters ---------- name : str The module name. extra : str Additional text
(
name: str,
extra: str = "",
min_version: str | None = None,
*,
errors: Literal["raise", "warn", "ignore"] = "raise",
)
| 61 | |
| 62 | |
| 63 | def import_optional_dependency( |
| 64 | name: str, |
| 65 | extra: str = "", |
| 66 | min_version: str | None = None, |
| 67 | *, |
| 68 | errors: Literal["raise", "warn", "ignore"] = "raise", |
| 69 | ) -> types.ModuleType | None: |
| 70 | """ |
| 71 | Import an optional dependency. |
| 72 | |
| 73 | By default, if a dependency is missing an ImportError with a nice |
| 74 | message will be raised. If a dependency is present, but too old, |
| 75 | we raise. |
| 76 | |
| 77 | Parameters |
| 78 | ---------- |
| 79 | name : str |
| 80 | The module name. |
| 81 | extra : str |
| 82 | Additional text to include in the ImportError message. |
| 83 | errors : str {'raise', 'warn', 'ignore'} |
| 84 | What to do when a dependency is not found or its version is too old. |
| 85 | |
| 86 | * raise : Raise an ImportError |
| 87 | * warn : Only applicable when a module's version is to old. |
| 88 | Warns that the version is too old and returns None |
| 89 | * ignore: If the module is not installed, return None, otherwise, |
| 90 | return the module, even if the version is too old. |
| 91 | It's expected that users validate the version locally when |
| 92 | using ``errors="ignore"`` (see. ``io/html.py``) |
| 93 | min_version : str, default None |
| 94 | Specify a minimum version that is different from the global pandas |
| 95 | minimum version required. |
| 96 | Returns |
| 97 | ------- |
| 98 | maybe_module : Optional[ModuleType] |
| 99 | The imported module, when found and the version is correct. |
| 100 | None is returned when the package is not found and `errors` |
| 101 | is False, or when the package's version is too old and `errors` |
| 102 | is ``'warn'`` or ``'ignore'``. |
| 103 | """ |
| 104 | assert errors in {"warn", "raise", "ignore"} |
| 105 | |
| 106 | package_name = INSTALL_MAPPING.get(name) |
| 107 | install_name = package_name if package_name is not None else name |
| 108 | |
| 109 | msg = ( |
| 110 | f"Missing optional dependency '{install_name}'. {extra} " |
| 111 | f"Use pip or conda to install {install_name}." |
| 112 | ) |
| 113 | try: |
| 114 | module = importlib.import_module(name) |
| 115 | except ImportError as err: |
| 116 | if errors == "raise": |
| 117 | raise ImportError(msg) from err |
| 118 | return None |
| 119 | |
| 120 | # Handle submodules: if we have submodule, grab parent module from sys.modules |
no test coverage detected