API Autodocs

The LazyImporter Class

class ducktools.lazyimporter.LazyImporter(imports=None, *, globs=None, eager_process=None, eager_import=None)

Create a LazyImporter to import modules and objects when they are accessed on this importer object.

globals() must be provided to the importer if relative imports are used.

eager_process and eager_import are included to help with debugging, there are global variables (that will be pulled from environment variables) that can be used to force all processing or imports to be done eagerly. These can be overridden by providing arguments here.

Parameters:

  • imports (Optional[list[ImportBase]]) – list of imports

  • globs (dict[str, Any]) – globals object for relative imports

  • eager_process (Optional[bool]) – filter and check the imports eagerly

  • eager_import (Optional[bool]) – perform all imports eagerly

Importers

class ducktools.lazyimporter.ModuleImport(module_name, asname=None)

Equivalent to import <module_name> [as <asname>] when provided to a LazyImporter.

Parameters:

  • module_name (str) – Name of the module to import eg: “dataclasses”

  • asname (str) – Optional name to use as the attribute name for the module

class ducktools.lazyimporter.FromImport(module_name, attrib_name, asname=None)

Equivalent to from <module_name> import <attrib_name> [as <asname>] when provided to a LazyImporter

Parameters:

  • module_name (str) – name of the module containing the objects to import

  • attrib_name (str) – name of the attribute to import

  • asname (str | None) – name to use as the name of the attribute on the lazy importer

class ducktools.lazyimporter.MultiFromImport(module_name, attrib_names)

Equivalent to from <module_name> import <attrib_names[0]>, <attrib_names[1]>, … when provided to a LazyImporter

Optional ‘asname’ for attributes if given as a tuple.

Parameters:

  • module_name (str) – Name of the module to import from

  • attrib_names (list[str | tuple[str, str]]) – List of attributes or (attribute, asname) pairs.

class ducktools.lazyimporter.TryExceptImport(module_name, except_module, asname)

Equivalent to:

try:
    import <module_name> as <asname>
except ImportError:
    import <except_module> as <asname>

Inside a LazyImporter

Parameters:

  • module_name (str) – Name of the ‘try’ module

  • except_module (str) – Name of the module to import in the case that the ‘try’ module fails

  • asname (str) – Name to use for either on successful import

class ducktools.lazyimporter.TryExceptFromImport(module_name, attribute_name, except_module, except_attribute, asname)

Equivalent to:

try:
    from <module_name> import <attribute_name> as <asname>
except ImportError:
    from <except_module> import <except_attribute> as <asname>
Parameters:

  • module_name (str) – Name of module to ‘try’ to import from

  • attribute_name (str) – Name of attribute to import from module_name

  • except_module (str) – Name of module to import from if initial import fails

  • except_attribute (str) – Name of attribute from the except_module

  • asname (str) – Name to use to access this attribute on the LazyImporter

Functions

ducktools.lazyimporter.get_importer_state(importer)

Get the importer state showing what has been imported and what attributes remain.

Parameters:

importer (LazyImporter) – LazyImporter object to be examined

Returns:

Dict of imported_modules and lazy_modules

Return type:

dict[str, dict[str, Any] | list[str]]

ducktools.lazyimporter.get_module_funcs(importer, module_name=None)

Get simplified __getattr__ and __dir__ functions for a module that includes the imports from the importer as if they are part of the module.

If a module name is provided, attributes from the module will appear in the __dir__ function and __getattr__ will set the attributes on the module when they are first accessed. If they are not provided, if the implementation provides frame inspection it will be inferred.

If a module already has __dir__ and/or __getattr__ functions it is probably better to use the result of dir(importer) and getattr(importer, name) to extend those functions.

Parameters:

  • importer (LazyImporter) – Lazy importer that provides additional objects to export as part of a module

  • module_name (str) – Name of the module that needs the __dir__ and __getattr__ functions. Usually __name__.

Returns:

__getattr__ and __dir__ functions

Return type:

tuple[types.FunctionType, types.FunctionType]

ducktools.lazyimporter.force_imports(importer)

Force the importer to perform all imports.

This is intended as a debug tool to make sure that all of the imports defined will work.

Parameters:

importer (LazyImporter) – The LazyImporter instance