Utils

objectory.utils

Contain some utility functions or helpers.

objectory.utils.all_child_classes

all_child_classes(cls: type) -> set[type]

Get all the child classes (or subclasses) of a given class.

Based on: https://stackoverflow.com/a/3862957

Parameters:

Name	Type	Description	Default
cls	type	The class whose child classes are to be retrieved.	required

Returns:

Type	Description
set[type]	The set of all the child classes of the given class.

Example

>>> from objectory.utils import all_child_classes
>>> class Foo:
...     pass
...
>>> all_child_classes(Foo)
set()
>>> class Bar(Foo):
...     pass
...
>>> all_child_classes(Foo)
{<class '....Bar'>}

objectory.utils.get_fully_qualified_name

get_fully_qualified_name(obj: Any) -> str

Return the fully qualified name of a Python object.

This function computes the fully qualified name (module path + object name) for various Python objects including functions, classes, methods, and instances. For instances, it returns the fully qualified name of their class. The format is "module.path.ObjectName" (e.g., "collections.Counter").

Parameters:

Name	Type	Description	Default
obj	Any	The object whose fully qualified name is to be computed. Can be a class, function, method, or instance.	required

Returns:

Type	Description
str	The fully qualified name.

Example

>>> from objectory.utils import get_fully_qualified_name
>>> import collections
>>> get_fully_qualified_name(collections.Counter)
'collections.Counter'
>>> class MyClass:
...     pass
...
>>> get_fully_qualified_name(MyClass)
'....MyClass'
>>> get_fully_qualified_name(map)
'builtins.map'

objectory.utils.import_object

import_object(object_path: str) -> Any

Import an object given its path.

This function dynamically imports a class, function, or other Python object using its fully qualified name. The object path should have the structure module_path.object_name (e.g., "collections.Counter" or "math.isclose").

Parameters:

Name	Type	Description	Default
object_path	str	The fully qualified path of the object to import. Must be a string in the format "module.path.ObjectName".	required

Returns:

Type	Description
Any	The imported object.

Raises:

Type	Description
TypeError	if object_path is not a string.
ImportError	if object_path cannot be imported.

Example

>>> from objectory.utils import import_object
>>> cls = import_object("collections.Counter")
>>> cls()
Counter()
>>> fn = import_object("math.isclose")
>>> fn(1, 1)
True
>>> pi = import_object("math.pi")
>>> pi
3.141592653589793
>>> pkg = import_object("math")
>>> pkg
<module 'math' (built-in)>

objectory.utils.instantiate_object

instantiate_object(
    obj: Callable | type,
    *args: Any,
    _init_: str = "__init__",
    **kwargs: Any
) -> Any

Instantiate dynamically an object from its configuration.

This function creates an instance of a class or calls a function with the provided arguments. For classes, it supports different instantiation methods (constructor, new, or class methods). For functions, it simply calls them with the given arguments.

Parameters:

Name	Type	Description	Default
obj	Callable | type	The class to instantiate or the function to call. Must be a class or function object.	required
*args	Any	Positional arguments to pass to the class constructor or function.	()
_init_	str	The function or method to use to create the object. This parameter is ignored if obj is a function. For classes, if "__init__" (default), the object is created by calling the constructor. Can also be "__new__" or the name of a class method.	'__init__'
**kwargs	Any	Keyword arguments to pass to the class constructor or function.	{}

Returns:

Type	Description
Any	The instantiated object if obj is a class name, otherwise the returned value of the function.

Raises:

Type	Description
TypeError	if obj is not a class or a function.

Example

>>> from collections import Counter
>>> from objectory.utils import instantiate_object
>>> instantiate_object(Counter, [1, 2, 1])
Counter({1: 2, 2: 1})
>>> instantiate_object(list, [1, 2, 1])
[1, 2, 1]

objectory.utils.is_lambda_function

is_lambda_function(obj: Any) -> bool

Indicate if the object is a lambda function or not.

This function checks whether a given object is a lambda function by examining its type and name. Lambda functions are not allowed in factories because they cannot be reliably serialized or referenced by name. Adapted from https://stackoverflow.com/a/23852434

Parameters:

Name	Type	Description	Default
obj	Any	The object to check. Can be any Python object.	required

Returns:

Type	Description
bool	True if the input is a lambda function, otherwise False

Example

>>> from objectory.utils import is_lambda_function
>>> is_lambda_function(lambda value: value + 1)
True
>>> def my_function(value: int) -> int:
...     return value + 1
...
>>> is_lambda_function(my_function)
False
>>> is_lambda_function(1)
False

objectory.utils.is_object_config

is_object_config(config: dict[str, Any], cls: type) -> bool

Indicate if the input configuration is a configuration for a given class.

This function only checks if the value of the key _target_ is valid. It does not check the other values. If _target_ indicates a function, the returned type hint is used to check the class.

Parameters:

Name	Type	Description	Default
config	dict[str, Any]	The configuration to check.	required
cls	type	The object class.	required

Returns:

Type	Description
bool	True if the input configuration is a configuration for the given class.

Example

>>> from objectory.utils import is_object_config
>>> from collections import Counter
>>> is_object_config({"_target_": "collections.Counter", "iterable": [1, 2, 1, 3]}, Counter)
True

objectory.utils.resolve_name

resolve_name(
    name: str,
    object_names: set[str],
    allow_import: bool = True,
) -> str | None

Find a match of the query name in the set of object names.

This function implements a name resolution mechanism that allows short names (e.g., "MyClass") to be resolved to fully qualified names (e.g., "mymodule.MyClass"). The resolution is successful only if there is exactly one object name that matches the query. If the name is a fully qualified name not in the set, it will attempt to import the module and return the resolved name.

Parameters:

Name	Type	Description	Default
name	str	The query name to use to find a match in the set of object names. Can be a short name or fully qualified name.	required
object_names	set[str]	The set of registered object names to search through.	required
allow_import	bool	If True (default), the function will attempt to import the module if the name appears to be a fully qualified name not in the set.	True

Returns:

Type	Description
str | None	The resolved name if the resolution was successful, otherwise None

Example

>>> from objectory.utils import resolve_name
>>> resolve_name("OrderedDict", {"collections.OrderedDict", "collections.Counter"})
collections.OrderedDict
>>> resolve_name("objectory.utils.resolve_name", {"math.isclose"})
'objectory.utils.name_resolution.resolve_name'
>>> resolve_name("OrderedDict", {"collections.Counter", "math.isclose"})
None