API Reference

class dessinemoi.Factory(registry=NOTHING)

registry: Dict[str, FactoryRegistryEntry]

Dictionary holding the factory registry.

Changed in version 21.3.0: Changed type from Dict[str, Type] to Dict[str, FactoryRegistryEntry].

property registered_types: List[str]

List of currently registered types, without duplicates.

Added in version 21.3.0.

register(cls=<class 'dessinemoi._core._Missing'>, *, type_id=None, dict_constructor=None, aliases=None, overwrite_id=False, allow_lazy=True)

If parameter cls is passed, register cls to the factory. Otherwise, i.e. if this method is used as a decorator, register the decorated class to the factory.

Note

All arguments, except cls, are keyword-only.

Parameters:

• cls (Any) – If set, type to register to the factory. If unset, this function returns a callable which can be used to register classes. In practice, this parameter is unset when the method is used as a class decorator. A LazyType instance or a string convertible to LazyType may also be passed.

• type_id (Optional[str]) – Identifier string used to register cls. Required if cls is a lazy type or if it does not specify its identifier itself.

• dict_constructor (Optional[str]) – Class method to be used for dictionary-based construction. If None, the default constructor is used.

• aliases (Optional[List[str]]) – If True, a given type can be registered multiple times under different IDs.

• overwrite_id (bool) – If True, existing IDs can be overwritten.

• allow_lazy (bool) – If False, force eager loading of lazy types.

Raises:

• ValueError – If allow_aliases is False and cls is already registered.

• ValueError – If allow_id_overwrite is False and type_id is already used to reference a type in the registry.

Return type:

Any

Changed in version 21.3.0: Made keyword-only.

Changed in version 21.3.0: Added dict_constructor argument.

Changed in version 22.1.0: Added allow_lazy argument. Accept LazyType and strings for cls.

Changed in version 22.2.0: Renamed allow_id_overwrite to overwrite_id. Removed allow_aliases, replaced by aliases.

alias(type_id, alias_id, overwrite_id=False)

Register a new alias to a registered type.

Parameters:

• type_id (str) – ID of the aliased type.

• alias_id (str) – Created alias ID.

• overwrite_id (bool) – If True and alias_id is already registered, the existing alias is redefined; else, a ValueError is raised.

Raises:

ValueError – If the new alias cannot be registered, either because the target type is not registered, or because the alias exists and is protected against overwrites.

Return type:

None

Added in version 22.2.0.

get_type(type_id)

Return the type corresponding to the requested type ID. Lazy types will be loaded.

Parameters:

type_id (str) – ID of a registered type.

Return type:

Type

Returns:

Corresponding type.

Added in version 22.1.1.

create(type_id, allowed_cls=None, construct=None, args=None, kwargs=None)

Create a new instance of a registered type.

Parameters:

• type_id (str) – ID of the type to be instantiated.

• allowed_cls (Union[Type, Tuple[Type], None]) – If not None, one or several types to which creation shall be restricted. If type_id does not reference one of these allowed types, an exception will be raised.

• construct (Optional[str]) – If not None, attempt instantiation using a class method constructor instead of the default constructor.

• args (Optional[Sequence]) – A sequence of arguments to pass to the constructor of the created type.

• kwargs (Optional[MutableMapping]) – A mapping of keyword arguments to passed to the constructor of the created type.

Return type:

Any

Returns:

Created object.

Raises:

• ValueError – If type_id does not reference a registered type.

• TypeError – If the requested type is not allowed.

Changed in version 21.2.0: Added construct keyword argument.

convert(value=<class 'dessinemoi._core._Missing'>, *, allowed_cls=None)

Convert a dictionary to one of the types supported by the factory.

Note

All arguments, except self and value, are keyword-only.

Parameters:

• value (MutableMapping) – Value to attempt conversion of. If value is a dictionary, the method tries to convert it to a registered type based on the type. If value is not a dictionary, it is returned without change. If value is unset, the method returns a callable which can later be used for conversion.

• allowed_cls (Union[Type, Tuple[Type], None]) – Types to restrict conversion to. If set, value will be checked and an exception will be raised if it does not have one of the allowed types.

Return type:

Any

Returns:

Created object if value is a dictionary; value otherwise.

Raises:

TypeError – If allowed_cls is specified and value.type refers to a disallowed type or type(value) is disallowed.

Changed in version 21.3.0: Made all args keyword-only except for value.

class dessinemoi.FactoryRegistryEntry(cls, dict_constructor)

Data class holding a (cls: Type, dict_constructor: Optional[str]) pair.

• cls is a type registered to a factory;

• dict_constructor is a string pointing to the class method constructor used by default when Factory.convert() attempts dictionary conversion.

If dict_constructor is set to None, it means that the default constructor should be used.

Added in version 21.3.0.

class dessinemoi.LazyType(mod, attr)

A lightweight data class specifying a lazily loaded type.

Added in version 22.1.0.

mod: str

Module where the imported object will be looked up.

attr: str

Name of the imported object.

property fullname

Fully qualified name of the object.

classmethod from_str(value)

Initialize a LazyType from a string representing its fully qualified name.

Parameters:

value (str) – String representing an absolute import path to the target type.

Return type:

LazyType

Returns:

Created lazy type specification.

Raises:

ValueError – If the value cannot be interpreted as a fully qualified name and, therefore, is suspected to be a relative import path.

load()

Import the specified lazy type.

Return type:

Type

Returns:

Imported type.