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]
toDict[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, registercls
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. ALazyType
instance or a string convertible toLazyType
may also be passed.type_id (
Optional
[str
]) – Identifier string used to registercls
. Required ifcls
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. IfNone
, the default constructor is used.aliases (
Optional
[List
[str
]]) – IfTrue
, a given type can be registered multiple times under different IDs.overwrite_id (
bool
) – IfTrue
, existing IDs can be overwritten.allow_lazy (
bool
) – IfFalse
, force eager loading of lazy types.
- Raises:
ValueError – If
allow_aliases
isFalse
andcls
is already registered.ValueError – If
allow_id_overwrite
isFalse
andtype_id
is already used to reference a type in the registry.
- Return type:
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. AcceptLazyType
and strings forcls
.Changed in version 22.2.0: Renamed
allow_id_overwrite
tooverwrite_id
. Removedallow_aliases
, replaced byaliases
.
- alias(type_id, alias_id, overwrite_id=False)[source]#
Register a new alias to a registered type.
- Parameters:
- Raises:
- Return type:
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.
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 notNone
, one or several types to which creation shall be restricted. Iftype_id
does not reference one of these allowed types, an exception will be raised.construct (
Optional
[str
]) – If notNone
, 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:
- 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
andvalue
, are keyword-only.- Parameters:
value (
MutableMapping
) – Value to attempt conversion of. Ifvalue
is a dictionary, the method tries to convert it to a registered type based on thetype
. Ifvalue
is not a dictionary, it is returned without change. Ifvalue
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:
- Returns:
Created object if
value
is a dictionary;value
otherwise.- Raises:
TypeError – If
allowed_cls
is specified andvalue.type
refers to a disallowed type ortype(value)
is disallowed.
Changed in version 21.3.0: Made all args keyword-only except for
value
.
-
registry:
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 whenFactory.convert()
attempts dictionary conversion.
If
dict_constructor
is set toNone
, 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.
- property fullname#
Fully qualified name of the object.
- classmethod from_str(value)[source]#
Initialise 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:
- 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.