Skip to content

Importer API Reference

This page provides detailed API documentation for the Importer module in SPOC.

The Importer is central to SPOC, enabling dynamic, dependency-aware module management. It handles:

  • Dynamic module loading at runtime
  • Caching for efficient module reuse
  • Lifecycle management with dependency-ordered initialization and teardown
  • Hook registration for custom startup/shutdown behavior

Importer Class

spoc.core.importer.Importer(on_startup_name='initialize', on_shutdown_name='teardown', mode='strict')

Dynamic module importer with caching and lifecycle management.

This class provides a clean API for: 1. Dynamically importing modules at runtime 2. Caching modules for efficient reuse 3. Managing module lifecycle (initialization/teardown) based on dependencies

Time Complexity: - Module lookup in cache: O(1) - Module loading: O(1) amortized (with caching) - Startup/shutdown: O(N + E) where N = number of modules, E = number of dependencies

Attributes:

  • _module_cache (dict[str, ModuleInfo]) –

    Internal cache of loaded modules

  • _dependency_graph –

    Graph of module dependencies for ordered initialization/teardown

  • module_hooks (ModuleHooks) –

    Dictionary of hooks to apply to modules during lifecycle events

  • on_startup_name –

    Name of the function to call for module initialization

  • on_shutdown_name –

    Name of the function to call for module teardown

Parameters:

  • on_startup_name (str | None, default: 'initialize' ) –

    Name of the initialization function in modules, or None

  • on_shutdown_name (str | None, default: 'teardown' ) –

    Name of the teardown function in modules, or None

components property

Get a dictionary of all components and their instances.

load(name)

Dynamically load a module by name.

If the module is already in the cache, returns the cached module. Otherwise, imports the module and adds it to the cache.

Parameters:

  • name (str) –

    The fully-qualified name of the module to load.

Returns:

  • ModuleType | None –

    The loaded module.

Raises:

  • ModuleNotFoundError –

    If the module cannot be found.

register(name, dependencies=None)

Register a module with dependencies and lifecycle hooks.

Parameters:

  • name (str) –

    The fully-qualified name of the module to register.

  • dependencies (list[str] | None, default: None ) –

    List of module names this module depends on.

Returns:

  • ModuleType | None –

    The loaded module.

Raises:

  • ModuleNotFoundError –

    If the module cannot be found.

register_hook(pattern, on_startup=None, on_shutdown=None) classmethod

Pre-register custom initialization and teardown functions for modules.

These hooks will be attached to the module when it's loaded, overriding any default hooks.

Parameters:

  • pattern (str) –

    The fully-qualified name of the module or a pattern with wildcards.

  • on_startup (Callable | None, default: None ) –

    Custom initialization function for this module.

  • on_shutdown (Callable | None, default: None ) –

    Custom teardown function for this module.

load_from_uri(uri)

Load a function from a full URI like 'package.module.func'.

has(name)

Check if a module is in the cache.

Parameters:

  • name (str) –

    The name of the module to check.

Returns:

  • bool –

    True if the module is in the cache, False otherwise.

get(name)

Get a module from the cache.

Parameters:

  • name (str) –

    The name of the module to get.

Returns:

  • ModuleType –

    The cached module.

Raises:

clear(name)

Remove a module from the cache.

This does not unload the module from sys.modules.

Parameters:

  • name (str) –

    The name of the module to clear.

clear_all()

Clear all modules from the cache.

This does not unload modules from sys.modules.

unload_all()

Completely unload all cached modules from memory.

This: 1. Calls teardown() on all initialized modules 2. Removes modules from the cache 3. Removes modules from sys.modules

Note: This is generally not recommended in production as it can cause unexpected behavior if other parts of the code still reference the modules.

startup()

Initialize all registered modules in dependency order.

This ensures that modules are initialized only after their dependencies have been initialized.

Raises:

shutdown()

Tear down all initialized modules in reverse dependency order.

This ensures that modules are torn down only after all modules that depend on them have been torn down.

Raises:

keys()

Get a list of all module names in the cache.

ModuleInfo Class

spoc.core.importer.ModuleInfo(name, module, dependencies=None, initialize_func='initialize', teardown_func='teardown')

Information about a dynamically loaded module.

Stores metadata and lifecycle hooks for a module.

Attributes:

  • name –

    The module name

  • module –

    The loaded module object

  • dependencies –

    List of module names this module depends on

  • initialize_func –

    Name of the initialization function in the module, or None

  • teardown_func –

    Name of the teardown function in the module, or None

  • initialized –

    Whether the module has been initialized

Parameters:

  • name (str) –

    The module name.

  • module (ModuleType) –

    The loaded module object.

  • dependencies (list[str] | None, default: None ) –

    List of module names this module depends on.

  • initialize_func (str | None, default: 'initialize' ) –

    Name of the initialization function in the module, or None.

  • teardown_func (str | None, default: 'teardown' ) –

    Name of the teardown function in the module, or None.

has_initialize()

Check if the module has an initialize function.

Returns:

  • bool –

    True if the module has an initialize function, False otherwise.

has_teardown()

Check if the module has a teardown function.

Returns:

  • bool –

    True if the module has a teardown function, False otherwise.

initialize()

Initialize the module if it has an initialize function.

Sets the initialized flag to True after successful initialization.

teardown()

Tear down the module if it has a teardown function.

Resets the initialized flag to False after successful teardown.

The Importer may raise the following exceptions:

See Core Utilities for full exception documentation.