class_tagger

Class Taggers that implement a mapping between classes and their unique identifier string tags.

class parityos_serialization.utils.class_tagger.ClassTagger

Bases: ABC

Interface for classes that uniquely identify classes with generated class string tags.

abstractmethod get_tag_from_class(cls: type) → str

Return tag generated for a given class cls.

Parameters:

cls – Class for which to return a tag.

Returns:

The tag created for cls.

abstractmethod get_class_from_tag(class_tag: str) → type

Return class for a tag class_tag.

Parameters:

class_tag – Tag for which to return the class.

Returns:

The class corresponding to class_tag.

abstractmethod get_class_from_object(obj: object) → type

Get class from obj.

Depending on the type of obj, get its class. Custom hooks for getting the class for instances of particular classes can be registered with register_class_getter_hook or register_predicate_class_getter_hook.

Parameters:

obj – Object for which to obtain the class.

Returns:

The object’s class as determined by registered hooks.

abstractmethod register_class_getter_hook(cls: type[T], class_getter_fun: Callable[[T], type])

Register a custom class getter function for class cls.

Hooks registered here are used in get_class_from_object to get the class from a passed object obj. The simplest case for class_getter_fun is to just return type(obj), i.e. cls itself. Registering alternative hooks enables something more elaborate like e.g. returning a higher up base class, such that get_class_from_object returns something else than type(obj).

Parameters:

• cls – The class for which to use class_getter_fun.

• class_getter_fun – ClassGetterHook that takes an object of type cls and returns a class for it.

abstractmethod register_predicate_class_getter_hook(predicate: Callable[[T], bool], class_getter_fun: Callable[[T], type])

Register a custom class getter function for objects that fulfill a predicate.

In contrast to register_class_getter_hook this method allows to register class getter hooks that get triggered by inspecting the object itself rather than its class or base classes.

The registered class_getter_fun gets triggered whenever predicate evaluates to True on an object.

Parameters:

• predicate – ClassGetterPredicate that takes an object and triggers class_getter_fun if returning True.

• class_getter_fun – ClassGetterHook for getting the class of an object for which predicate returns True.

abstractmethod register_tag_getter_hook(cls: type[T], tag_getter_fun: Callable[[type[T]], str])

Register a custom tag getter function for class cls.

Hooks registered here are used in get_tag_from_class to get the tag for a passed class cls. The simplest tag_getter_fun is to just return cls.__name__. Registering alternative hooks enables more elaborate schemes like e.g. returning a custom identifier unifying several equivalent classes.

Parameters:

• cls – The class for which to use tag_getter_fun.

• tag_getter_fun – TagGetterHook taking a class cls and returning a tag string for it.

abstractmethod register_predicate_tag_getter_hook(predicate: Callable[[type[T]], bool], tag_getter_fun: Callable[[type[T]], str])

Register a custom tag getter function for objects that fulfill a predicate.

In contrast to register_tag_getter_hook this method allows to register tag getter hooks that get triggered by inspecting the object itself rather than its class or base classes.

The registered tag_getter_fun gets triggered whenever predicate evaluates to True on an object.

Parameters:

• predicate – TagGetterPredicate that takes a class T and triggers tag_getter_fun if returning True.

• tag_getter_fun – TagGetterHook taking a class T and returning a tag string for it.

class parityos_serialization.utils.class_tagger.DispatchClassTagger

Bases: ClassTagger, ABC

Base class for ClassTagger implementations that rely on singledispatch objects.

abstractmethod get_default_tag_from_class(cls: type) → str

Default implementation of a tag getter function.

Used as fallback implementation for get_tag_from_class.

Parameters:

cls – Class for which to get a tag string.

Returns:

Default tag string generated for cls.

get_class_from_object(obj: object) → type

Get class from obj.

Depending on the type of obj, get its class. Custom hooks for getting the class for instances of particular classes can be registered with register_class_getter_hook or register_predicate_class_getter_hook.

Parameters:

obj – Object for which to obtain the class.

Returns:

The object’s class as determined by registered hooks.

register_class_getter_hook(cls: type[T], class_getter_fun: Callable[[T], type])

Register a custom class getter function for class cls.

Hooks registered here are used in get_class_from_object to get the class from a passed object obj. The simplest case for class_getter_fun is to just return type(obj), i.e. cls itself. Registering alternative hooks enables something more elaborate like e.g. returning a higher up base class, such that get_class_from_object returns something else than type(obj).

Parameters:

• cls – The class for which to use class_getter_fun.

• class_getter_fun – ClassGetterHook that takes an object of type cls and returns a class for it.

get_tag_from_class(cls: type) → str

Return tag generated for a given class cls.

Parameters:

cls – Class for which to return a tag.

Returns:

The tag created for cls.

register_predicate_class_getter_hook(predicate: Callable[[T], bool], class_getter_fun: Callable[[T], type])

Register a custom class getter function for objects that fulfill a predicate.

In contrast to register_class_getter_hook this method allows to register class getter hooks that get triggered by inspecting the object itself rather than its class or base classes.

The registered class_getter_fun gets triggered whenever predicate evaluates to True on an object.

Parameters:

• predicate – ClassGetterPredicate that takes an object and triggers class_getter_fun if returning True.

• class_getter_fun – ClassGetterHook for getting the class of an object for which predicate returns True.

register_tag_getter_hook(cls: type, tag_getter_fun: Callable[[type[Any]], str])

Register a custom tag getter function for class cls.

Hooks registered here are used in get_tag_from_class to get the tag for a passed class cls. The simplest tag_getter_fun is to just return cls.__name__. Registering alternative hooks enables more elaborate schemes like e.g. returning a custom identifier unifying several equivalent classes.

Parameters:

• cls – The class for which to use tag_getter_fun.

• tag_getter_fun – TagGetterHook taking a class cls and returning a tag string for it.

register_predicate_tag_getter_hook(predicate: Callable[[type[T]], bool], tag_getter_fun: Callable[[type[T]], str])

Register a custom tag getter function for objects that fulfill a predicate.

In contrast to register_tag_getter_hook this method allows to register tag getter hooks that get triggered by inspecting the object itself rather than its class or base classes.

The registered tag_getter_fun gets triggered whenever predicate evaluates to True on an object.

Parameters:

• predicate – TagGetterPredicate that takes a class T and triggers tag_getter_fun if returning True.

• tag_getter_fun – TagGetterHook taking a class T and returning a tag string for it.

class parityos_serialization.utils.class_tagger.ImportPathClassTagger

Bases: DispatchClassTagger

ClassTagger implementation that uses the class’s full import path as tag.

By using the full import path for each class, this class tagger class does not need an internal mapping between classes and their tags as the classes can be bootstrapped from the import paths. However, similar to pickle, this class is susceptible to refactoring operations, where classes are moved or renamed.

get_default_tag_from_class(cls: type) → str

Return full import path of cls as class string tag.

Parameters:

cls – Class for which to return a tag.

Returns:

The tag created for cls from its full import path.

get_class_from_tag(class_tag: str) → type

Return the class by importing it from the path represented by class_tag.

Note

The full import path represented by class_tag must contain a module and a class part. For built-in types, the module is builtins.

Parameters:

class_tag – Tag for which to return the class.

Returns:

The class imported from the path represented by class_tag.

Raises:

• ValueError – If class_tag doesn’t contain a module part.

• ModuleNotFoundError – If the module in the import path represented by class_tag could not be imported.

• AttributeError – If the imported module contains no class corresponding to the class part in class_tag.

class parityos_serialization.utils.class_tagger.NameClassTagger(*classes: type)

Bases: DispatchClassTagger

ClassTagger implementation that uses the class’s name as tag.

In order to generate and maintain a unique mapping between classes and their names as tags, this class keeps an internal mapping between classes and their names. Consequently, classes must be registered (i.e. added to that mapping) before they can be deserialized, such that the class can be looked up from its string tag. Use register_classes for that purpose.

Parameters:

*classes – Class or classes to be registered with this class tagger at initialization, including all of their (currently imported) subclasses. Any classes not passed here can be registered at any later time using register_classes. Any registered classes can be deregistered using deregister_classes.

register_tag_getter_hook(cls: type, tag_getter_fun: Callable[[type[Any]], str])

Register a custom tag getter function for class cls.

Hooks registered here are used in get_tag_from_class to get the tag for a passed class cls. The simplest tag_getter_fun is to just return cls.__name__. Registering alternative hooks enables more elaborate schemes like e.g. returning a custom identifier unifying several equivalent classes.

Parameters:

• cls – The class for which to use tag_getter_fun.

• tag_getter_fun – TagGetterHook taking a class cls and returning a tag string for it.

register_predicate_tag_getter_hook(predicate: Callable[[type[T]], bool], tag_getter_fun: Callable[[type[T]], str])

Register a custom tag getter function for objects that fulfill a predicate.

In contrast to register_tag_getter_hook this method allows to register tag getter hooks that get triggered by inspecting the object itself rather than its class or base classes.

The registered tag_getter_fun gets triggered whenever predicate evaluates to True on an object.

Parameters:

• predicate – TagGetterPredicate that takes a class T and triggers tag_getter_fun if returning True.

• tag_getter_fun – TagGetterHook taking a class T and returning a tag string for it.

get_default_tag_from_class(cls: type) → str

Return class name of cls as class string tag.

Parameters:

cls – Class for which to return a tag.

Returns:

The tag created for cls from its name.

get_class_from_tag(class_tag: str) → type

Return the class registered for class_tag in internal inventory.

The target class must be registered first using register_classes.

Parameters:

class_tag – Tag for which to return the class

Returns:

The class corresponding to class_tag.

Raises:

ClassError – If no class is registered for class_tag.

register_classes(*classes: type, include_subclasses: bool = False)

Register one or several classes in the internal inventory.

Every class that is to be deserialized needs to be registered first. This is because the Serializer serializes class information of an object through a tag generated by get_tag_from_class.

During deserialization, the Serializer looks in an internal mapping from tags to classes to retrieve the correct class corresponding to a tag. This method registers a class in this mapping such that it can be retrieved from its tag during deserialization.

Note

Registering a (de)serialization hook for a class cls with a serializer using a NameClassTagger usually also requires registering cls with the serializer’s class tagger.

Parameters:

• *classes – Class or classes to register in the internal registry with its corresponding tag.

• include_subclasses – Whether to register all subclasses of all passed classes as well. Defaults to False.

deregister_classes(*classes: type, include_subclasses: bool = False)

Deregister one or several classes from the internal inventory.

Caution

After deregistering a class cls, calling get_class_from_tag with a tag that was registered for cls before will raise a KeyError.

Parameters:

• *classes – Class to deregister from this class tagger.

• include_subclasses – Whether subclasses of each class in classes should also be deregistered.

parityos_serialization.utils.class_tagger.register(*class_taggers: NameClassTagger) → Callable[[type[T]], type[T]]

Decorator that registers a class and all its subclasses that are imported at the time of execution with all class taggers in class_taggers.

In cases where there is no control over the class to be registered, use NameClassTagger.register_classes.

Parameters:

*class_taggers – Serializer or serializers for which to register the decorated class. Pass at least one class tagger.

Returns:

A decorator for the class to be registered with all class_taggers.

Raises:

ValueError – If no class tagger is passed.

Examples

Register a class A and its subclasses B and C with two distinct serializers by using one decorator only.

>>> dict_serializer = Serializer()
>>> pair_serializer = Serializer(PairTypedDataConverter())
>>>
>>> @register([dict_serializer.class_tagger, pair_serializer.class_tagger])
>>> @frozen
>>> class A:
>>>     dim: int
>>>
>>> @frozen
>>> class B(A):
>>>     value: float
>>>
>>> @frozen
>>> class C(A):
>>>     name: str
>>>
>>> assert dict_serializer.deserializer({"_cls": "B", "_data": {"dim": 2, "value": -33.3}}) == B(2, -33.3)
>>> assert pair_serializer.deserializer(("C", {"dim": 2, "name": "Two"})) == C(2, "Two")