Utilities

class LazyDependencyManager(*, name=None, callback=None, install=None, msg=None)

A mananger for some optional features that are expensive to import, or to verify the existence of.

These objects can be used as Booleans, such as if x, and will evaluate True if the dependency they test for is available, and False if not. The presence of the dependency will only be tested when the Boolean is evaluated, so it can be used as a runtime test in functions and methods without requiring an import-time test.

These objects also encapsulate the error handling if their dependency is not present, so you can do things such as:

from qiskit.utils import LazyImportManager
HAS_MATPLOTLIB = LazyImportManager("matplotlib")
 
@HAS_MATPLOTLIB.require_in_call
def my_visualisation():
    ...
 
def my_other_visualisation():
    # ... some setup ...
    HAS_MATPLOTLIB.require_now("my_other_visualisation")
    ...
 
def my_third_visualisation():
    if HAS_MATPLOTLIB:
        from matplotlib import pyplot
    else:
        ...

In all of these cases, matplotlib is not imported until the functions are entered. In the case of the decorator, matplotlib is tested for import when the function is called for the first time. In the second and third cases, the loader attempts to import matplotlib when the require_now() method is called, or when the Boolean context is evaluated. For the require methods, an error is raised if the library is not available.

This is the base class, which provides the Boolean context checking and error management. The concrete classes LazyImportTester and LazySubprocessTester provide convenient entry points for testing that certain symbols are importable from modules, or certain command-line tools are available, respectively.

Parameters

• name – the name of this optional dependency.
• callback – a callback that is called immediately after the availability of the library is tested with the result. This will only be called once.
• install – how to install this optional dependency. Passed to MissingOptionalLibraryError as the pip_install parameter.
• msg – an extra message to include in the error raised if this is required.

_is_available

disable_locally

require_in_call

require_in_instance

require_now

class LazyImportTester(name_map_or_modules, *, name=None, callback=None, install=None, msg=None)

A lazy dependency tester for importable Python modules. Any required objects will only be imported at the point that this object is tested for its Boolean value.

Parameters

name_map_or_modules (Union[str, Dict[str, Iterable[str]], Iterable[str]]) – if a name map, then a dictionary where the keys are modules or packages, and the values are iterables of names to try and import from that module. It should be valid to write from <module> import <name1>, <name2>, .... If simply a string or iterable of strings, then it should be valid to write import <module> for each of them.

Raises

ValueError – if no modules are given.

class LazySubprocessTester(command, *, name=None, callback=None, install=None, msg=None)

A lazy checker that a command-line tool is available. The command will only be run once, at the point that this object is checked for its Boolean value.

Parameters

command (Union[str, Iterable[str]]) – the strings that make up the command to be run. For example, ["pdflatex", "-version"].

Raises

ValueError – if an empty command is given.