attempt_import

(function from pyomo.common.dependencies)

pyomo.common.dependencies.attempt_import(name, error_message=None, only_catch_importerror=None, minimum_version=None, alt_names=None, callback=None, importer=None, defer_check=None, defer_import=None, deferred_submodules=None, catch_exceptions=None)[source]

Attempt to import the specified module.

This will attempt to import the specified module, returning a (module, available) tuple. If the import was successful, module will be the imported module and available will be True. If the import results in an exception, then module will be an instance of ModuleUnavailable and available will be False

The following

>>> from pyomo.common.dependencies import attempt_import
>>> numpy, numpy_available = attempt_import('numpy')

Is roughly equivalent to

>>> from pyomo.common.dependencies import ModuleUnavailable
>>> try:
...     import numpy
...     numpy_available = True
... except ImportError as e:
...     numpy = ModuleUnavailable('numpy', 'Numpy is not available',
...                               '', str(e), globals()['__name__'])
...     numpy_available = False

The import can be “deferred” until the first time the code either attempts to access the module or checks the Boolean value of the available flag. This allows optional dependencies to be declared at the module scope but not imported until they are actually used by the module (thereby speeding up the initial package import). Deferred imports are handled by two helper classes (DeferredImportModule and DeferredImportIndicator). Upon actual import, DeferredImportIndicator.resolve() attempts to replace those objects (in both the local and original global namespaces) with the imported module and Boolean flag so that subsequent uses of the module do not incur any overhead due to the delayed import.

Parameters:

  • name (str) – The name of the module to import

  • error_message (str, optional) – The message for the exception raised by ModuleUnavailable

  • only_catch_importerror (bool, optional) –

    DEPRECATED: use catch_exceptions instead of only_catch_importerror.

    If True (the default), exceptions other than ImportError raised during module import will be reraised. If False, any exception will result in returning a ModuleUnavailable object. (deprecated in version 5.7.3)

  • minimum_version (str, optional) – The minimum acceptable module version (retrieved from module.__version__)

  • alt_names (list, optional) –

    DEPRECATED: alt_names no longer needs to be specified and is ignored.

    A list of common alternate names by which to look for this module in the globals() namespaces. For example, the alt_names for NumPy would be ['np']. (deprecated in version 6.0)

  • callback (Callable[[ModuleType, bool], None], optional) – A function with the signature fcn(module, available) that will be called after the import is first attempted.

  • importer (function, optional) – A function that will perform the import and return the imported module (or raise an ImportError). This is useful for cases where there are several equivalent modules and you want to import/return the first one that is available.

  • defer_check (bool, optional) – DEPRECATED: renamed to defer_import (deprecated in version 6.7.2)

  • defer_import (bool, optional) – If True, then the attempted import is deferred until the first use of either the module or the availability flag. The method will return instances of DeferredImportModule and DeferredImportIndicator. If False, the import will be attempted immediately. If not set, then the import will be deferred unless the name is already present in sys.modules.

  • deferred_submodules (Iterable[str], optional) – If provided, an iterable of submodule names within this module that can be accessed without triggering a deferred import of this module. For example, this module uses deferred_submodules=['pyplot', 'pylab'] for matplotlib.

  • catch_exceptions (Iterable[Exception], optional) – If provided, this is the list of exceptions that will be caught when importing the target module, resulting in attempt_import returning a ModuleUnavailable instance. The default is to only catch ImportError. This is useful when a module can regularly return additional exceptions during import.

Returns: