Main classes and functions¶

objectory ¶

Contain the main features of the objectory package.

objectory.AbstractFactory ¶

Bases: ABCMeta

Implement the abstract factory metaclass to create automatically factories.

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`	Specifies the class name. This becomes the `__name__` attribute of the class.	required
`bases`	`tuple`	Specifies a tuple of the base classes from which the class inherits. This becomes the `__bases__` attribute of the class.	required
`dct`	`dict`	Specifies 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.

Please read the documentation for more information.

Parameters:

Name	Type	Description	Default
`_target_`	`str`	Specifies the name of the object (class or function) to instantiate. It can be the class name or the full class name.	required
`*args`	`Any`	Variable length argument list.	`()`
`_init_`	`str`	Specifies the function to use to create the object. If `"__init__"`, the object is created by calling the constructor.	`'__init__'`
`**kwargs`	`Any`	Arbitrary keyword arguments.	`{}`

Returns:

Type	Description
`Any`	The instantiated object with the given parameters.

Raises:

Type	Description
`AbstractClassAbstractFactoryError`	if you try to instantiate an abstract class.
`UnregisteredClassAbstractFactoryError`	if 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. It is useful if you are using a 3rd party library.

For example, you use a 3rd party library, and you cannot modify the classes to add AbstractFactory. You can use this function to register some classes or functions of a 3rd party library.

Parameters:

Name	Type	Description	Default
`obj`	`type \| Callable`	Specifies the class or function to register to the factory.	required

Raises:

Type	Description
`IncorrectObjectAbstractFactoryError`	if the object is not a class.

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 is an experimental function and may change in the future.

Parameters:

Name	Type	Description	Default
`name`	`str`	Specifies the name of the object to remove. 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`	Specifies 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.

Please read the documentation for more information.

Parameters:

Name	Type	Description	Default
`_target_`		Specifies the name of the object (class or function) to instantiate. It can be the class name or the full class name.	required
`*args`	`Any`	Variable length argument list.	`()`
`_init_`	`str`	Specifies the function to use to create the object. If `"__init__"`, the object is created by calling the constructor.	`'__init__'`
`**kwargs`	`Any`	Arbitrary keyword arguments.	`{}`

Returns:

Type	Description
`Any`	The instantiated object with the given parameters.

Raises:

Type	Description
`AbstractClassAbstractFactoryError`	if you try to instantiate an abstract class.
`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

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

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	Specifies 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`	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 of a given class.

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 full name of each object.

Parameters:

Name	Type	Description	Default
`cls`	`type`	Specifies the class to register its child classes.	required
`ignore_abstract_class`	`bool`	Indicate if the abstract class should be ignored or not. Be 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.

Please read the documentation for more information.

Parameters:

Name	Type	Description	Default
`obj`	`type \| Callable`	Specifies the object to register. The object is expected to be a class or a function.	required
`name`	`str \| None`	Specifies the name to use to register the object. If `None`, the full name of the object is used as name.	`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`	Specifies if the other (sub-)registries should be included in the set. By default, the other (sub-)registries are included.	`True`

Returns:

Name	Type	Description
`set`	`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`	Specifies 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.

Parameters:

Name	Type	Description	Default
`name`	`str`	Specifies the name of the object to remove. 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.

Parameters:

Name	Type	Description	Default
`_target_`	`str`	Specifies the name of the object (class or function) to instantiate. It can be the class name or the full class name.	required
`*args`	`Any`	Variable length argument list.	`()`
`_init_`	`str`	Specifies the function to use to create the object. If `"__init__"`, the object is created by calling the constructor.	`'__init__'`
`**kwargs`	`Any`	Arbitrary keyword arguments.	`{}`

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 ¶