Dynamic module importing

Import any class, function, or module at runtime using a fully-qualified dotted string path.

The alexber.utils.importer module lets you resolve Python constructs — classes, functions, modules — from plain strings at runtime. This is the foundation for the plugin/strategy pattern used throughout alexber.utils.

importer(dotted_path)

Converts a dotted string path into the Python object it names, recursively importing packages as needed.

from alexber.utils.importer import importer

# Import a class
MyParser = importer('myapp.parsers.YamlParser')
parser = MyParser()

# Import a function
process = importer('myapp.pipeline.process_record')
result = process(data)

# Import a module
mod = importer('myapp.utils')

Parameter	Type	Description
dotted_path	str	Fully-qualified dotted path to the target, e.g. "myapp.parsers.YamlParser".

Returns the resolved class, function, module, or other compile-time construct. Instances are never returned — use new_instance() for that.

Only compile-time constructs are supported (classes, functions, modules, constants). importer will not return an instance of a class.

Namespace package support

importer supports PEP 420 implicit namespace packages. If a component does not yet exist on the parent object, the function imports the full path up to that point before retrying the attribute lookup.

new_instance(target, *args, **kwargs)

Like importer, but if the resolved object is a class it instantiates it and returns the instance.

from alexber.utils.importer import new_instance

# Resolves the class and calls MyParser(*args, **kwargs)
parser = new_instance('myapp.parsers.YamlParser', strict=True)

Configuring a parser class via init_app_conf

A common pattern in alexber.utils is accepting a class (or its dotted string path) as a configuration parameter so callers can swap implementations without changing code.

The example below shows how default_parser_cls in init_app_conf uses importer internally:

# config.yml
# default_parser_cls: myapp.parsers.TomlParser

from alexber.utils.importer import importer

def init_app_conf(**kwargs):
    parser_cls = kwargs.get('default_parser_cls', 'alexber.utils.parsers.safe_load')

    # Accept either a class object or a dotted string
    if isinstance(parser_cls, str):
        parser_cls = importer(parser_cls)

    return parser_cls()

This pattern is used in fix_env, fix_retry_env, run_sub_process, and initStream. Anywhere a cls or *_cls parameter appears, you can pass either the class itself or a dotted string and importer handles the rest.

How the resolution algorithm works

1. Split the path

   The dotted string is split on '.'. The first component is imported as a top-level module.

2. Walk the remaining components

   For each remaining component the function first tries getattr. If the attribute does not exist it imports the full path up to that point (triggering __init__.py execution) and tries getattr again.

3. Return the resolved object

   The final object is returned. No instance is created.