`bridge.utils.instantiate_utils`#

Module Contents#

Classes#

`InstantiationMode`	Enum for instantiation modes.
`_Keys`	Special keys in configs used by instantiate.

Functions#

`instantiate`	Instantiate an object or callable from a config object.
`instantiate_node`	Recursively instantiates a node within a configuration structure.
`_locate`	Locate an object by name or dotted path, importing as necessary. This function attempts to import modules starting from the most specific path (back to front), making it possible to import objects where the final component could be either a module or an attribute of the previous module.
`_is_target`
`_call_target`	Call target (type) with args and kwargs.
`_convert_target_to_string`
`_prepare_input_dict_or_list`
`_resolve_target`	Resolve target string, type or callable into type or callable.
`_extract_pos_args`
`_convert_node`

API#

exception bridge.utils.instantiate_utils.InstantiationException#

Bases: Exception

Custom exception type for instantiation errors.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class bridge.utils.instantiate_utils.InstantiationMode(*args, **kwds)#

Bases: enum.Enum

Enum for instantiation modes.

Initialization

STRICT#: ‘strict’

LENIENT#: ‘lenient’

class bridge.utils.instantiate_utils._Keys#

Bases: str, enum.Enum

Special keys in configs used by instantiate.

Initialization

Initialize self. See help(type(self)) for accurate signature.

TARGET#: ‘target’

PARTIAL#: ‘partial’

CALL#: ‘call’

ARGS#: ‘args’

bridge.utils.instantiate_utils.instantiate(

config: Any,

*args: Any,

mode: bridge.utils.instantiate_utils.InstantiationMode = InstantiationMode.LENIENT,

**kwargs: Any,

) → Any#

Instantiate an object or callable from a config object.

This function takes a configuration object (dictionary, list, OmegaConf config, or Structured Config instance) and instantiates the target specified within it.

The config object must contain: target (str): The fully qualified name of the class or callable to instantiate.

The config object may also contain: args (list): Positional arguments for the target. partial (bool): If True, return a functools.partial object instead of calling the target. Defaults to False. call (bool): If False, simply resolves and returns the target without calling it. Defaults to True. Additional keyword arguments to pass to the target.

Parameters:

config – The configuration object describing the target and its parameters.
*args – Optional positional arguments that will override args in the config if provided.
mode – Instantiation mode (STRICT or LENIENT). In LENIENT mode (default), errors during instantiation of parameters are logged as warnings, and None is used instead. In STRICT mode, errors are raised.
**kwargs – Optional keyword arguments that will override parameters in the config. Note: Dataclass instances in kwargs are treated as nested configs.

Returns:

The instantiated object or the return value of the callable. If config.partial is True, returns a functools.partial object. If config.call is False, returns the resolved target callable/class itself. Returns None if the input config is None.

Raises:

InstantiationException – If the config is invalid, the target cannot be resolved, or instantiation fails in STRICT mode.
TypeError – If the partial flag is not a boolean.

bridge.utils.instantiate_utils.instantiate_node( node: Any, *args: Any, partial: bool = False, mode: bridge.utils.instantiate_utils.InstantiationMode = InstantiationMode.LENIENT, ) → Any#

Recursively instantiates a node within a configuration structure.

This function handles the instantiation of individual nodes (dictionaries, lists, or primitive values) within a larger configuration tree, typically managed by OmegaConf.

If the node is a dictionary containing a _target_ key, it resolves and instantiates the target callable/class using the other items in the dictionary as keyword arguments. Nested nodes are recursively instantiated.

If the node is a list, it recursively instantiates each item in the list.

If the node is not an OmegaConf config node (e.g., a primitive type), it’s returned directly.

Parameters:

node – The configuration node to instantiate (can be DictConfig, ListConfig, or a primitive type).
*args – Positional arguments passed down from the top-level instantiate call, used primarily for the final target call if the node is a dictionary with _target_.
partial – Boolean flag indicating whether to return a functools.partial object instead of calling the target. This can be overridden by a _partial_ key within the node itself.
mode – Instantiation mode (STRICT or LENIENT). Determines error handling behavior for nested instantiations.

Returns:

The instantiated object, list, or the original node if it wasn’t a config. Returns None if the input node is None or represents a None value in OmegaConf.

Raises:

InstantiationException – If instantiation fails in STRICT mode, or if there are issues like incompatible arguments or non-callable targets.
TypeError – If a _partial_ flag within the config is not a boolean.

bridge.utils.instantiate_utils._locate(path: str) → Any#: Locate an object by name or dotted path, importing as necessary. This function attempts to import modules starting from the most specific path (back to front), making it possible to import objects where the final component could be either a module or an attribute of the previous module.

bridge.utils.instantiate_utils._is_target(x: Any) → bool#

bridge.utils.instantiate_utils._call_target( _target_: Callable[..., Any], _partial_: bool, args: tuple[Any, ...], kwargs: dict[str, Any], full_key: str, ) → Any#: Call target (type) with args and kwargs.

bridge.utils.instantiate_utils._convert_target_to_string(t: Any) → Any#

bridge.utils.instantiate_utils._prepare_input_dict_or_list( d: Union[dict[Any, Any], list[Any]], ) → Any#

bridge.utils.instantiate_utils._resolve_target( target: Union[str, type, Callable[..., Any]], full_key: str, check_callable: bool = True, ) → Union[type, Callable[..., Any], object]#: Resolve target string, type or callable into type or callable.

bridge.utils.instantiate_utils._extract_pos_args( input_args: Any, kwargs: Any, ) → tuple[Any, Any]#

bridge.utils.instantiate_utils._convert_node(node: Any) → Any#

bridge.utils.instantiate_utils#

Module Contents#

Classes#

Functions#

API#

`bridge.utils.instantiate_utils`#