django_evolution.serialization

Serialization and deserialization.

These classes are responsible for converting objects/values to signature data or to Python code (for evolution hints), and for converting signature data back to objects.

The classes in this file are considered private API. The only public API is:

deserialize_from_python()
serialize_to_signature()
serialize_to_python()

Added in version 2.2.

Functions

`deserialize_from_signature`(payload)	Deserialize a value from the signature.
`serialize_to_python`(value)	Serialize a value to a Python code string.
`serialize_to_signature`(value)	Serialize a value to the signature.

Classes

`BaseIterableSerialization`()	Base class for iterable types.
`BaseSerialization`()	Base class for serialization.
`ClassSerialization`()	Base class for serialization for classes.
`CombinedExpressionSerialization`()	Base class for serialization for CombinedExpression objects.
`DeconstructedSerialization`()	Base class for serialization for objects supporting deconstruction.
`DictSerialization`()	Base class for serialization for dictionaries.
`EnumSerialization`()	Serialization for enums.
`ListSerialization`()	Base class for serialization for lists.
`PlaceholderSerialization`()	Base class for serialization for a placeholder object.
`PrimitiveSerialization`()	Base class for serialization for Python primitives.
`QSerialization`()	Base class for serialization for Q objects.
`SetSerialization`()	Base class for serialization for sets.
`StringSerialization`()	Base class for serialization for strings.
`TupleSerialization`()	Base class for serialization for tuples.

class django_evolution.serialization.BaseSerialization

Bases: object

Base class for serialization.

Subclasses should override the methods within this class to provide serialization and deserialization logic specific to one or more types.

Added in version 2.2.

classmethod serialize_to_signature(value)

Serialize a value to JSON-compatible signature data.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting signature data.
Return type:: object

classmethod serialize_to_python(value)

Serialize a value to a Python code string.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting Python code.
Return type:: unicode

classmethod deserialize_from_signature(payload)

Deserialize signature data to a value.

Parameters:: payload (object) – The payload to deserialize.
Returns:: The resulting value.
Return type:: object or type

classmethod deserialize_from_deconstructed(type_cls, args, kwargs)

Deserialize an object from deconstructed object information.

Parameters:

type_cls (type) – The type of object to construct.
args (tuple) – The positional arguments passed to the constructor.
kwargs (dict) – The keyword arguments passed to the constructor.

Returns:

The resulting object.

Return type:

object

class django_evolution.serialization.BaseIterableSerialization

Bases: BaseSerialization

Base class for iterable types.

This will handle the signature-related serialization/deserialization automatically, based on iterable_type.

Added in version 2.2.

item_type = None

The type used to store items.

Type:: type

classmethod serialize_to_signature(value)

Serialize a value to JSON-compatible signature data.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting signature data.
Return type:: object

classmethod deserialize_from_signature(payload)

Deserialize signature data to a value.

Parameters:: payload (object) – The payload to deserialize.
Returns:: The resulting value.
Return type:: object or type

__annotations__ = {}

class django_evolution.serialization.PrimitiveSerialization

Bases: BaseSerialization

Base class for serialization for Python primitives.

This will wrap simple values, deep-copying them when storing as signature data, returning a repr() result when converting to Python code, and using the value as-is when deserializing.

Added in version 2.2.

classmethod serialize_to_signature(value)

Serialize a value to JSON-compatible signature data.

Parameters:: value (object) – The value to serialize.
Returns:: A deep copy of the provided value.
Return type:: object

classmethod serialize_to_python(value)

Serialize a value to a Python code string.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting Python code.
Return type:: unicode

classmethod deserialize_from_signature(payload)

Deserialize signature data to a value.

This will just return the value as-is.

Parameters:: payload (object) – The payload to deserialize.
Returns:: The resulting value.
Return type:: object or type

__annotations__ = {}

class django_evolution.serialization.ClassSerialization

Bases: BaseSerialization

Base class for serialization for classes.

This is able to serialize a class name to Python. It cannot be used for signature data.

Added in version 2.2.

classmethod serialize_to_python(value)

Serialize a value to a Python code string.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.DictSerialization

Bases: BaseSerialization

Base class for serialization for dictionaries.

This will be used for plain dict instances and for collections.OrderedDict.

Added in version 2.2.

classmethod serialize_to_signature(value)

Serialize a dictionary to JSON-compatible signature data.

Parameters:: value (dict) – The dictionary to serialize.
Returns:: The resulting dictionary.
Return type:: dict

classmethod serialize_to_python(value)

Serialize a dictionary to a Python code string.

Parameters:: value (dict) – The dictionary to serialize.
Returns:: The resulting Python code.
Return type:: unicode

classmethod deserialize_from_signature(payload)

Deserialize dictionary signature data to a value.

Parameters:: payload (dict) – The payload to deserialize.
Returns:: The resulting value.
Return type:: dict

__annotations__ = {}

class django_evolution.serialization.EnumSerialization

Bases: BaseSerialization

Serialization for enums.

Added in version 2.2.

classmethod serialize_to_signature(value)

Serialize a value to JSON-compatible signature data.

Parameters:: value (object) – The value to serialize.
Returns:: A deep copy of the provided value.
Return type:: object

classmethod serialize_to_python(value)

Serialize an enum value to a Python code string.

Parameters:: value (enum.Enum) – The enum value to serialize.
Returns:: The resulting Python code.
Return type:: unicode

classmethod deserialize_from_signature(payload)

Deserialize signature data to a value.

This will just return the value as-is.

Parameters:: payload (object) – The payload to deserialize.
Returns:: The resulting value.
Return type:: object or type

__annotations__ = {}

class django_evolution.serialization.ListSerialization

Bases: BaseIterableSerialization

Base class for serialization for lists.

Added in version 2.2.

item_type: alias of list

classmethod serialize_to_python(value)

Serialize a list to a Python code string.

Parameters:: value (list) – The list to serialize.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.TupleSerialization

Bases: BaseIterableSerialization

Base class for serialization for tuples.

Added in version 2.2.

item_type: alias of tuple

classmethod serialize_to_python(value)

Serialize a tuple to a Python code string.

Parameters:: value (tuple) – The tuple to serialize.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.SetSerialization

Bases: BaseIterableSerialization

Base class for serialization for sets.

Added in version 2.2.

item_type: alias of set

classmethod serialize_to_python(value)

Serialize a set to a Python code string.

Parameters:: value (set) – The set to serialize.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.StringSerialization

Bases: PrimitiveSerialization

Base class for serialization for strings.

This will encode to a string, and ensure the results are consistent across Python 2 and 3.

Added in version 2.2.

classmethod serialize_to_signature(value)

Serialize a string to JSON-compatible string.

Parameters:: value (bytes or unicode) – The string to serialize. If a byte string, it’s expected to contain UTF-8 data.
Returns:: The resulting string.
Return type:: unicode

classmethod serialize_to_python(value)

Serialize a string to a Python code string.

Parameters:: value (bytes or unicode) – The string to serialize. If a byte string, it’s expected to contain UTF-8 data.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.DeconstructedSerialization

Bases: BaseSerialization

Base class for serialization for objects supporting deconstruction.

This is used for Django objects that support a deconstruct() method. It will convert to/from deconstructed signature data, and provide a suitable representation in Python.

Added in version 2.2.

classmethod serialize_to_signature(value)

Serialize a value to JSON-compatible signature data.

This will deconstruct the object and return a dictionary containing the deconstructed information and a flag noting that it must be reconstructed.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting signature data.
Return type:: object

classmethod serialize_to_python(value)

Serialize an object to a Python code string.

This will generate code that constructs an instance of the object.

Parameters:: value (object) – The object to serialize.
Returns:: The resulting Python code.
Return type:: unicode

classmethod deserialize_from_signature(payload)

Deserialize deconstructed dictionary signature data to an object.

This will attempt to re-construct an object from the deconstructed signature data. This may fail if there is any issue looking up or instantiating the object.

Parameters:

payload (dict) – The payload to deserialize.

Returns:

The resulting value.

Return type:

dict

Raises:

Exception – An unexpected error occurred when instantiating the object.
ImportError – The class specified in the signature data could not be imported.

__annotations__ = {}

class django_evolution.serialization.PlaceholderSerialization

Bases: BaseSerialization

Base class for serialization for a placeholder object.

Added in version 2.2.

classmethod serialize_to_python(value)

Serialize a placeholder object to a Python code string.

Parameters:: value (django_evolution.placeholders.BasePlaceholder) – The object to serialize.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.CombinedExpressionSerialization

Bases: DeconstructedSerialization

Base class for serialization for CombinedExpression objects.

This ensures a consistent representation of django.db.models.CombinedExpression objects across all supported versions of Django.

Note that while this can technically be used in version of Django prior to 2.0, many of the objects nested within won’t be supported. In practice, database features really start to make use of this in a way that impacts serialization code in Django 2.0 and higher.

Added in version 2.2.

classmethod serialize_to_python(value)

Serialize a CombinedExpression object to a Python code string.

Parameters:: value (object) – The object to serialize.
Returns:: The resulting Python code.
Return type:: unicode

__annotations__ = {}

class django_evolution.serialization.QSerialization

Bases: DeconstructedSerialization

Base class for serialization for Q objects.

This ensures a consistent representation of django.db.models.Q objects across all supported versions of Django.

Django 1.7 through 3.1 encode the data in a different form than 3.2+. This ensures serialized data in a form closer to 3.2+’s version, while providing compatibility with older versions.

Added in version 2.2.

child_separators = {'AND': ' & ', 'OR': ' | '}

classmethod serialize_to_signature(q)

Serialize a Q object to JSON-compatible signature data.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting signature data.
Return type:: object

classmethod serialize_to_python(value)

Serialize a Q object to a Python code string.

This will generate code that constructs an instance of the object, handling negation, AND/OR connections, and children.

Parameters:: value (object) – The object to serialize.
Returns:: The resulting Python code.
Return type:: unicode

classmethod deserialize_from_deconstructed(type_cls, args, kwargs)

Deserialize an object from deconstructed object information.

Parameters:

type_cls (type) – The type of object to construct.
args (tuple) – The positional arguments passed to the constructor.
kwargs (dict) – The keyword arguments passed to the constructor.

Returns:

The resulting object.

Return type:

object

__annotations__ = {}

django_evolution.serialization.serialize_to_signature(value)

Serialize a value to the signature.

Added in version 2.2.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting JSON-serializable data.
Return type:: object

django_evolution.serialization.serialize_to_python(value)

Serialize a value to a Python code string.

Added in version 2.2.

Parameters:: value (object or type) – The value to serialize.
Returns:: The resulting Python code string.
Return type:: unicode

django_evolution.serialization.deserialize_from_signature(payload)

Deserialize a value from the signature.

Added in version 2.2.

Parameters:: payload (object) – The payload to deserialize.
Returns:: The resulting deserialized value.
Return type:: object or type
Raises:: Exception – An unexpected error occurred when deserializing. This is specific to the type of deserializer.