Package: py-jsonic
Jsonic: pythonic utility for JSON SerializationJsonicis a lightweight utility for serializing/deserializing python objects to/from JSON.Jsonictargets mainly serialization ofdata classes, and aims to make serialization of such classes smooth and painless process.
As a serialization layer on top of your DB layer, or serialization layer for your custom communication protocol
between python micro-services it can do magicsNevertheless, Jsonic might not be the right tool for serializing your super complex (and awesome) custom data structure to json
(although you could probably do it with some extra work)DefinitionsSome definitions that are used in the rest of this fileDefinition:jsonic typejsonic typeis one of the following :intfloatstrboolanydata class(see definition ofdata classbelow)Class extendingSerializableClass registered usingregister_serializable_typeClass that a custom@serializerand@deserializerwas registered fordictwithstrkeys that all it's nested values are ofjsonic typelistwith which all it's elements are ofjsonic typeDefinition:jsonic representationjsonic representationis an output of a successful call ofserializefunction onjsonic typeinstanceSupported forms of representations:Python generic dictJSON stringDefinition:data classdata classis any class that answer the next criteria:it's__init__method has nopositional-onlyparametersit's__init__method has*argsor**kwargsparametersevery parameter of it's__init__function has corresponding instance attribute with the same nameJsonic Featuresserialize anyjsonic typetojsonic representationFor classes that extendsSerializableor are registered usingregister_serializable_typeyou could
declare instance attributes as transient, so they won't take place in the serialization processYou could create your own custom serializer for a specific type using@jsonic_serializerdecoratorYou can choose to serialize topython generic dictor toJSON stringYou can choose to leave private attributes out of the serialization processdeserializejsonic representationtojsonic typeinstanceFor classes that extendsSerializableor are registered usingregister_serializable_typeyou could
create mapping from__init__parameter name to it's corresponding instance attribute name.
If not mapped, it is assumed__init__parameter has instance attribute with the same nameYou could deserialize anyJsonic representationwhether it ispython generic dictorJSON stringYou could pass the expected deserialized instance type todeserializefunction for type safety.
if the serialized instance was of another type, an error will be thrownYou can choose to leave private attributes out of the deserialization processJsonic componentsSerializable classClasses extendingSerializablecan be serialized into json dict/string representing the object,
and deserialized back to class instance.
Extending classes can declare some attributes as transient. To do so they should have
class attribute:transient_attributes: List[str]which should be a list of attributes names that would be transient (won't be serialized and deserialized)Classes that has__init__parameter with a different name than it's corresponding instance attribute should have class attribute:init_parameters_mapping: Dict[str, str]which should be a dictionary mapping from__init__parameter name to the corresponding instance attribute name.
When deserializing class instance, the corresponding instance attribute will be passed to the__init__function.
For__init__parameter which has no mapping defined, it is assumed that the corresponding instance variable has
the same name as the parameter.Note:Any nested object in such class must be ofjsonic typeregister_serializable_type functionUsed to register classes that don't extend theSerializableclass, and are notdata class,
therefore optional meta-data is required for them.This is equivalent to extendingSerializable, but extendingSerializableis preferred when possible.
Most common usage is for classes from external source that you want to serialize, but is ajsonic typeserialize functionSerializesjsonic typeintojsonic representaionrepresenting the inputNote:Onlyjsonic typecan be serialized using this functiondeserialize functionDeserializesjsonic representaionto instance of jsonic typeNote:Onlyjsonic representationcan be deserialized using this function@jsonic_serializer DecoratorUsed to register custom serializer for specific type.These custom serializers are used in the process of serializingjsonic type@jsonic_deserializer DecoratorUsed to register custom deserializer for specific type.These custom deserializers are used in the process of deserializingjsonic representationJsonic current limitationsThere are few obvious limitations toJsonicand a few more subtle ones.
The main source of those limitations is the nature of serialization process in general.
The main focus ofJsonicis serialization ofdata classes, which represents big chunk
of serialization work in general.Most obvious limitation is that only instances ofjsonic type's can be serialized.
This means there are classes that cannot be serialized and deserialized using JsonicJsonic is meant mostly to serializedata classes, and have some technical limitations:If a class__init__method has parameters it gets but not persisting as an attribute, it is notjsonic typeeven if it meets
all there conditions.
This is because when deserializing ajsonic representationan instance of the given type must be created.
We need to pass to the constructor the corresponding attributes. Therefore if there are parameters it gets and are not
being persisted into an instance attribute we won't be able to pass them when creating the instance.Example: A class gets in it's construction some service class instance, and in it's instance construction
it calls a method of that service, but does not persist this service instance.Jsonicwon't be able to deserialize this class properly.If a class__init__method has parameters which arepositional-onlyparameters, it is notjsonic typeeven if it meets
all other conditions.
This is because when deserializing ajsonic representationan instance of the given type must be created.
We need to pass to the constructor the corresponding attributes. We can pass only keyword arguments which correspond to
an instance attribute.*args and **kwargs: if a class__init__method accepts *args or **kwargs, in many casesJsonicwon't be able to
deserialize it properly