utils.import_utils

Module Contents

Classes

UnavailableMeta	A metaclass for generating placeholder objects for unavailable symbols
UnavailableNullContext	A placeholder class for unavailable context managers

Functions

image_only_import_from	A function used to import symbols required only in image installs
is_unavailable	Helper to check if given symbol is actually a placeholder
null_decorator
safe_import	A function used to import modules that may not be available
safe_import_from	A function used to import symbols from modules that may not be available

Data

IMAGE_INSTALL_STRING
logger

API

utils.import_utils.IMAGE_INSTALL_STRING = <Multiline-String>

exception utils.import_utils.UnavailableError

Bases: Exception

Error thrown if a symbol is unavailable due to an issue importing it

Initialization

Initialize self. See help(type(self)) for accurate signature.

class utils.import_utils.UnavailableMeta

Bases: type

A metaclass for generating placeholder objects for unavailable symbols

This metaclass allows errors to be deferred from import time to the time that a symbol is actually used in order to streamline the usage of optional dependencies. This is particularly useful for attempted imports of GPU-only modules which will only be invoked if GPU-only functionality is specifically used.

If an attempt to import a symbol fails, this metaclass is used to generate a class which stands in for that symbol. Any attempt to call the symbol (instantiate the class) or access its attributes will throw an UnavailableError exception. Furthermore, this class can be used in e.g. isinstance checks, since it will (correctly) fail to match any instance it is compared against.

In addition to calls and attribute access, a number of dunder methods are implemented so that other common usages of imported symbols (e.g. arithmetic) throw an UnavailableError, but this is not guaranteed for all possible uses. In such cases, other exception types (typically TypeErrors) will be thrown instead.

class utils.import_utils.UnavailableNullContext(*args, **kwargs)

A placeholder class for unavailable context managers

This context manager will return a value which will throw an UnavailableError if used in any way, but the context manager itself can be safely invoked.

Initialization

utils.import_utils.image_only_import_from(

module: str,

symbol: str,

*,

alt: object | None = None,

) → object

A function used to import symbols required only in image installs

This function will attempt to import a module with the given name. This function will attempt to import a symbol with the given name from the given module, but it will not throw an ImportError if the symbol is not found. Instead, it will return a placeholder object which will raise an exception only if used with instructions on installing an image build.

Parameters

module: str The name of the module to import. symbol: str The name of the symbol to import. alt: object An optional object to be used in place of the given symbol if it fails to import in a non-image install

Returns

object The imported symbol, the given alternate, or a class derived from UnavailableMeta.

utils.import_utils.is_unavailable(obj: object) → bool

Helper to check if given symbol is actually a placeholder

utils.import_utils.logger

‘getLogger(…)’

utils.import_utils.null_decorator(*args, **kwargs)

utils.import_utils.safe_import(

module: str,

*,

msg: str | None = None,

alt: object | None = None,

) → object

A function used to import modules that may not be available

This function will attempt to import a module with the given name, but it will not throw an ImportError if the module is not found. Instead, it will return a placeholder object which will raise an exception only if used.

Parameters

module: str The name of the module to import. msg: str or None An optional error message to be displayed if this module is used after a failed import. alt: object An optional module to be used in place of the given module if it fails to import

Returns

object The imported module, the given alternate, or a class derived from UnavailableMeta.

utils.import_utils.safe_import_from(

module: str,

symbol: str,

*,

msg: str | None = None,

alt: object | None = None,

) → object

A function used to import symbols from modules that may not be available

This function will attempt to import a symbol with the given name from the given module, but it will not throw an ImportError if the symbol is not found. Instead, it will return a placeholder object which will raise an exception only if used.

Parameters

module: str The name of the module in which the symbol is defined. symbol: str The name of the symbol to import. msg: str or None An optional error message to be displayed if this symbol is used after a failed import. alt: object An optional object to be used in place of the given symbol if it fails to import

Returns

object The imported symbol, the given alternate, or a class derived from UnavailableMeta.