hbutils.reflection.imports

Overview:

Import functions, may be useful when support some dynamic features (such as imports in cli development).

This module provides utilities for dynamically importing Python objects, modules, and attributes. It supports pattern matching and flexible import strategies for runtime object resolution.

import_object

hbutils.reflection.imports.import_object(obj_name: str, module_name: str | None = None)[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 name.

Parameters:

full_name (str) – Full dotted name of the object, attribute access is supported.
predicate (Optional[Callable]) – Optional predicate function to filter results. Should accept (obj, module_name, obj_name) and return bool. 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]

Quickly 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]) – Optional predicate function to filter results. Should accept (obj, module_name, obj_name) and return bool. 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]]

Raises:

ModuleNotFoundError – If no valid module can be found in the pattern.

Example::

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