API Reference#

Factory#

class dessinemoi.Factory(registry=_Nothing.NOTHING)[source]#
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.

New 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)[source]#

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)[source]#

Register a new alias to a registered type.

Parameters:

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

  • alias_id (str) – Created alias ID.

Raises:

ValueError –

Return type:

None

New in version 22.2.0.

get_type(type_id)[source]#

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.

New in version 22.1.1.

create(type_id, allowed_cls=None, construct=None, args=None, kwargs=None)[source]#

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)[source]#

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.

FactoryRegistryEntry#

class dessinemoi.FactoryRegistryEntry(cls, dict_constructor)[source]#

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.

New in version 21.3.0.

LazyType#

class dessinemoi.LazyType(mod, attr)[source]#

A lightweight data class specifying a lazily loaded type.

New 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)[source]#

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()[source]#

Import the specified lazy type.

Return type:

Type

Returns:

Imported type.