Main classes and functions¶

objectory ¶

Contain the main features of the objectory package.

objectory.AbstractFactory ¶

Bases: ABCMeta

Implement the abstract factory metaclass to create factories automatically.

Please read the documentation about this abstract factory to learn how it works and how to use it.

To avoid potential conflicts with the other classes, all the non-public attributes or functions starts with _abstractfactory_**** where **** is the name of the attribute or the function.

Parameters:

Name	Type	Description	Default
`name`	`str`	The class name. This becomes the `__name__` attribute of the class.	required
`bases`	`tuple`	A tuple of the base classes from which the class inherits. This becomes the `__bases__` attribute of the class.	required
`dct`	`dict`	A namespace dictionary containing definitions for the class body. This becomes the `__dict__` attribute of the class.	required

Example usage:

>>> from objectory import AbstractFactory
>>> class BaseClass(metaclass=AbstractFactory):
...     pass
...
>>> class MyClass(BaseClass):
...     pass
...
>>> obj = BaseClass.factory("MyClass")
>>> obj
<....MyClass object at 0x...>

objectory.AbstractFactory.inheritors `property` ¶

inheritors: dict[str, Any]

Get the inheritors.

Returns:

Type	Description
`dict[str, Any]`	The inheritors.

Example usage:

>>> from objectory import AbstractFactory
>>> class BaseClass(metaclass=AbstractFactory):
...     pass
...
>>> class MyClass(BaseClass):
...     pass
...
>>> BaseClass.inheritors
{'....BaseClass': <class '....BaseClass'>, '....MyClass': <class '....MyClass'>}

objectory.AbstractFactory.factory ¶

factory(
    _target_: str,
    *args: Any,
    _init_: str = "__init__",
    **kwargs: Any
) -> Any

Instantiate dynamically an object given its configuration.

This method creates an instance of a registered class or calls a registered function. The target can be specified using either the short name (e.g., "MyClass") or the fully qualified name (e.g., "mymodule.MyClass"). If the target is not yet registered, it will attempt to import and register it automatically.

Parameters:

Name	Type	Description	Default
`_target_`	`str`	The name of the object (class or function) to instantiate. It can be the class name or the full class name. Supports name resolution for registered objects.	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. 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 with the given parameters.

Raises:

Type	Description
`AbstractClassAbstractFactoryError`	when an abstract class is instantiated.
`UnregisteredClassAbstractFactoryError`	when the target is not found.

Example usage:

>>> from objectory import AbstractFactory
>>> class BaseClass(metaclass=AbstractFactory):
...     pass
...
>>> class MyClass(BaseClass):
...     pass
...
>>> obj = BaseClass.factory("MyClass")
>>> obj
<....MyClass object at 0x...>

objectory.AbstractFactory.register_object ¶

register_object(obj: type | Callable) -> None

Register a class or function to the factory.

This method manually registers a class or function with the factory, making it available for instantiation. This is particularly useful when working with third-party libraries where you cannot modify the source code to inherit from the factory. The object is registered using its fully qualified name. If an object with the same name already exists, it will be replaced with a warning.

Parameters:

Name	Type	Description	Default
`obj`	`type \| Callable`	The class or function to register to the factory. Must be a valid class or function object (not a lambda function).	required

Raises:

Type	Description
`IncorrectObjectAbstractFactoryError`	if the object is not a class or function, or if it is a lambda function.

Example usage:

>>> from objectory import AbstractFactory
>>> class BaseClass(metaclass=AbstractFactory):
...     pass
...
>>> class MyClass:
...     pass
...
>>> BaseClass.register_object(MyClass)
>>> BaseClass.inheritors
{...}

objectory.AbstractFactory.unregister ¶

unregister(name: str) -> None

Remove a registered object from the factory.

This method removes a class or function from the factory's registry. The object will no longer be available for instantiation through the factory. This is an experimental function and may change in the future.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the object to remove. Can be either the short name (e.g., "MyClass") or the fully qualified name (e.g., "mymodule.MyClass"). This function uses the name resolution mechanism to find the full name if only the short name is given.	required

Example usage:

>>> from objectory import AbstractFactory
>>> class BaseClass(metaclass=AbstractFactory):
...     pass
...
>>> class MyClass:
...     pass
...
>>> BaseClass.register_object(MyClass)
>>> BaseClass.unregister("MyClass")
>>> BaseClass.inheritors
{'....BaseClass': <class '....BaseClass'>}

objectory.Registry ¶

Implement the registry class.

This class can be used to register some objects and instantiate an object from its configuration.

Example usage:

>>> from objectory import Registry
>>> from collections import Counter
>>> registry = Registry()
>>> registry.register_object(Counter)
>>> registry.factory("collections.Counter")
Counter()

objectory.Registry.getattr ¶

__getattr__(key: str) -> Registry | type

Get the registry associated to a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key.	required

Returns:

Type	Description
`Registry \| type`	The registry associated to the key.

Raises:

Type	Description
`InvalidAttributeRegistryError`	if the associated attribute is not a registry.

Example usage:

>>> from collections import Counter
>>> registry = Registry()
>>> registry.other.register_object(Counter)

objectory.Registry.len ¶

__len__() -> int

Return the number of registered objects.

Returns:

Type	Description
`int`	The number of registered objects.

Example usage:

>>> from objectory import Registry
>>> from collections import Counter
>>> registry = Registry()
>>> registry.register_object(Counter)
>>> len(registry)
1

objectory.Registry.clear ¶

clear(nested: bool = False) -> None

Clear the registry.

This functions removes all the registered objects in the registry.

Parameters:

Name	Type	Description	Default
`nested`	`bool`	Indicates if the sub-registries should be cleared or not.	`False`

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> # Clear the main registry.
>>> registry.clear()
>>> # Clear only the sub-registry other.
>>> registry.other.clear()
>>> # Clear the main registry and its sub-registries.
>>> registry.clear(nested=True)

objectory.Registry.clear_filters ¶

clear_filters(nested: bool = False) -> None

Clear all the filters of the registry.

Parameters:

Name	Type	Description	Default
`nested`	`bool`	Indicates if the filters of all the sub-registries should be cleared or not.	`False`

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> # Clear the filters of the main registry.
>>> registry.clear_filters()
>>> # Clear the filters of the sub-registry other.
>>> registry.other.clear_filters()
>>> # Clear the filters of the main registry and all its sub-registries.
>>> registry.clear_filters(nested=True)

objectory.Registry.factory ¶

factory(
    _target_: str,
    *args: Any,
    _init_: str = "__init__",
    **kwargs: Any
) -> Any

Instantiate dynamically an object given its configuration.

This method creates an instance of a registered class or calls a registered function. The target can be specified using either the short name or the fully qualified name. If the target is not yet registered, it will attempt to import and register it automatically.

Parameters:

Name	Type	Description	Default
`_target_`	`str`	The name of the object (class or function) to instantiate. It can be the class name or the full class name. Supports name resolution for registered objects.	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. 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 with the given parameters.

Raises:

Type	Description
`AbstractClassAbstractFactoryError`	when an abstract class is instantiated.
`UnregisteredClassAbstractFactoryError`	if the target name is not found.

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> @registry.register()
... class MyClass:
...     pass
...
>>> registry.factory("MyClass")
<....MyClass object at 0x...>

objectory.Registry.register ¶

register(
    name: str | None = None,
) -> Callable[[Registerable], Registerable]

Define a decorator to add a class or a function to the registry.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	The name to use to register the object. If `None`, the full name of the object is used as name.	`None`

Returns:

Type	Description
`Callable[[Registerable], Registerable]`	The decorated object.

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> @registry.register()
... class ClassToRegister:
...     pass
...
>>> registry.registered_names()
{'....ClassToRegister'}
>>> @registry.register()
... def function_to_register(*args, **kwargs):
...     pass
...
>>> registry.registered_names()
{...}

objectory.Registry.register_child_classes ¶

register_child_classes(
    cls: type, ignore_abstract_class: bool = True
) -> None

Register a given class and its child classes.

This function registers all the child classes including the child classes of the child classes, etc. If you use this function, you cannot choose the names used to register the objects. It will use the fully qualified name of each object.

Parameters:

Name	Type	Description	Default
`cls`	`type`	The class to register along with its child classes.	required
`ignore_abstract_class`	`bool`	Indicate if the abstract classes should be ignored or not. By default, the abstract classes are not registered because they cannot be instantiated.	`True`

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> registry.register_child_classes(dict)
>>> registry.registered_names()
{...}

objectory.Registry.register_object ¶

register_object(
    obj: type | Callable, name: str | None = None
) -> None

Register an object.

This method adds a class or function to the registry, making it available for instantiation through the factory method. You can optionally specify a custom name for the object; otherwise, its fully qualified name will be used. If a class filter is set, the object must be a subclass of the filter class.

Parameters:

Name	Type	Description	Default
`obj`	`type \| Callable`	The object to register. The object must be a class or a function (not a lambda function).	required
`name`	`str \| None`	The name to use to register the object. If `None`, the fully qualified name of the object is used. Cannot conflict with sub-registry names.	`None`

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> class ClassToRegister:
...     pass
...
>>> registry.register_object(ClassToRegister)
>>> registry.registered_names()
{'....ClassToRegister'}
>>> def function_to_register(*args, **kwargs):
...     pass
...
>>> registry.register_object(function_to_register)
>>> registry.registered_names()
{...}

objectory.Registry.registered_names ¶

registered_names(include_registry: bool = True) -> set[str]

Get the names of all the registered objects.

Parameters:

Name	Type	Description	Default
`include_registry`	`bool`	Indicates if the other (sub-)registries should be included in the set. By default, the other (sub-)registries are included.	`True`

Returns:

Type	Description
`set[str]`	The names of the registered objects.

Example usage:

>>> from objectory import Registry
>>> registry = Registry()
>>> registry.registered_names()
>>> # Show name of all the registered objects except the sub-registries.
>>> registry.registered_names(include_registry=False)

objectory.Registry.set_class_filter ¶

set_class_filter(cls: type | None) -> None

Set the class filter so only the child classes of this class can be registered.

If you set this filter, you cannot register functions. To unset this filter, you can use set_class_filter(None).

Parameters:

Name	Type	Description	Default
`cls`	`type \| None`	The class to use as filter. Only the child classes of this class can be registered.	required

Raises:

Type	Description
`TypeError`	if the input is not a class or `None`.

Example usage:

>>> from collections import Counter, OrderedDict
>>> from objectory import Registry
>>> registry = Registry()
>>> registry.mapping.set_class_filter(dict)
>>> registry.mapping.register_object(OrderedDict)
>>> registry.mapping.registered_names()
{'collections.OrderedDict'}

objectory.Registry.unregister ¶

unregister(name: str) -> None

Remove a registered object.

This method removes a class or function from the registry. The object will no longer be available for instantiation through the factory method.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the object to remove. Can be either the short name or the fully qualified name. This function uses the name resolution mechanism to find the full name if only the short name is given.	required

Raises:

Type	Description
`UnregisteredObjectFactoryError`	if the name does not exist in the registry.

Example usage:

>>> from objectory import Registry
>>> from collections import Counter
>>> registry = Registry()
>>> registry.register_object(Counter)
>>> registry.unregister("collections.Counter")

objectory.factory ¶

factory(
    _target_: str,
    *args: Any,
    _init_: str = "__init__",
    **kwargs: Any
) -> Any

Instantiate dynamically an object given its configuration.

This function provides a universal factory that can instantiate any class or call any function by its fully qualified name. Unlike the AbstractFactory or Registry approaches, this function does not require prior registration of classes.

Parameters:

Name	Type	Description	Default
`_target_`	`str`	The fully qualified name of the object (class or function) to instantiate, e.g., "collections.Counter" or "math.isclose".	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. 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 with the given parameters.

Raises:

Type	Description
`RuntimeError`	if the target cannot be found.

Example usage:

>>> from objectory import factory
>>> factory("collections.Counter", [1, 2, 1, 3])
Counter({1: 2, 2: 1, 3: 1})

Main classes and functions¶

objectory ¶

objectory.AbstractFactory ¶

objectory.AbstractFactory.inheritors property ¶

objectory.AbstractFactory.factory ¶

objectory.AbstractFactory.register_object ¶

objectory.AbstractFactory.unregister ¶

objectory.Registry ¶

objectory.Registry.__getattr__ ¶

objectory.Registry.__len__ ¶

objectory.Registry.clear ¶

objectory.Registry.clear_filters ¶

objectory.Registry.factory ¶

objectory.Registry.register ¶

objectory.Registry.register_child_classes ¶

objectory.Registry.register_object ¶

objectory.Registry.registered_names ¶

objectory.Registry.set_class_filter ¶

objectory.Registry.unregister ¶

objectory.factory ¶

objectory.AbstractFactory.inheritors `property` ¶

objectory.Registry.getattr ¶

objectory.Registry.len ¶