hbutils.reflection.imports

Dynamic import utilities for runtime object resolution.

This module provides helper functions to dynamically import Python modules, objects, and nested attributes by name or by patterns. It is designed for runtime resolution scenarios such as CLI plugins, configuration-based object construction, or exploratory tooling where import targets are not known ahead of time.

The module contains the following public components:

Note

Pattern-based imports rely on attribute traversal and may access a large number of attributes when wildcard matching is used.

Example:

>>> from hbutils.reflection.imports import import_object, quick_import_object
>>> import_object('zip')  # Builtin function
<class 'zip'>
>>> quick_import_object('json.loads')[0]  # Resolve from a dotted name
<function loads at ...>

__all__

hbutils.reflection.imports.__all__ = ['import_object', 'quick_import_object', 'iter_import_objects']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

import_object

hbutils.reflection.imports.import_object(obj_name: str, module_name: str | None = None) → Any[source]

Dynamically import an object from a module.

This function imports a specific object (class, function, variable, etc.) from a given module. If no module name is provided, it searches in the builtins module.

Parameters:

  • obj_name (str) – Name of the object to import.

  • module_name (Optional[str]) – Name of the module containing the object. Defaults to None, which means the builtins module.

Returns:

The imported object.

Return type:

Any

Raises:

  • AttributeError – If the object does not exist in the module.

  • ModuleNotFoundError – If the module cannot be found.

Example:

>>> import_object('zip')               # <class 'zip'>
>>> import_object('ndarray', 'numpy')  # <class 'numpy.ndarray'>

quick_import_object

hbutils.reflection.imports.quick_import_object(full_name: str, predicate: Callable | None = None) → Tuple[Any, str, str][source]

Quickly dynamically import an object with a single name.

This function attempts to import an object using its full dotted name, supporting nested attributes. It returns the first matching object along with its module and object name.

Parameters:

  • full_name (str) – Full dotted name of the object, attribute access is supported.

  • predicate (Optional[Callable[[Any, str, str], bool]]) – Optional predicate function to filter results. The callable should accept (obj, module_name, obj_name) and return True or False. Defaults to None, which means no filtering.

Returns:

A tuple containing (imported_object, module_name, object_name).

Return type:

Tuple[Any, str, str]

Raises:

ImportError – If the object cannot be imported.

Example:

>>> quick_import_object('zip')                     # (<class 'zip'>, '', 'zip')
>>> quick_import_object('numpy.ndarray')           # (<class 'numpy.ndarray'>, 'numpy', 'ndarray')
>>> quick_import_object('numpy.ndarray.__name__')  # ('ndarray', 'numpy', 'ndarray.__name__')

iter_import_objects

hbutils.reflection.imports.iter_import_objects(full_pattern: str, predicate: Callable | None = None) → Iterator[Tuple[Any, str, str]][source]

Dynamically import all objects matching a full name pattern.

This function yields all objects that match the given pattern, supporting wildcards in attribute names. It performs a breadth-first search through module attributes to find all matching objects.

Parameters:

  • full_pattern (str) – Full pattern of the object with wildcard support. Supports fnmatch-style patterns (e.g., 'numpy.array*').

  • predicate (Optional[Callable[[Any, str, str], bool]]) – Optional predicate function to filter results. The callable should accept (obj, module_name, obj_name) and return True or False. Defaults to None, which means no filtering.

Returns:

Iterator yielding tuples of (imported_object, module_name, object_name).

Return type:

Iterator[Tuple[Any, str, str]]

Example:

>>> list(iter_import_objects('os.path'))  # Yields all matching objects
>>> list(iter_import_objects('numpy.array*'))  # Yields all numpy objects starting with 'array'