npu.inout.serialization_context

Classes

SerializationContext()

class npu.inout.serialization_context.SerializationContext

Author:: Alberto M. Esmoris Pena

A serialization context can be used to track objects universally even after they pass through serialization/deserialization processes, no matter how many. This enables externalizing some variables so their values can be updated at each serialization process while making sure these changes happen independently for each object, as they are universally tracked by the SerializationContext.

For example, one object could be serialized pointing to a given path. This path could point to a file that contains information that must be considered when deserializing. Perhaps, the object is moved to another location. In that case, the path could be updated during deserialization if it is externalized to a serialization context. In other words, the serialization context extends the standard python serialization so the deserialization supports context variables.

The main logic for a serialization context is based on objects and identifiers. Let \(o_i\) be an object that is identified by a key \(\kappa_i\). Now let \(x_{j}\) be the name of an attribute for the object \(o_i\) and \(y_{ij}\) the corresponding value. There is a context (i.e., a key-value map) identified by \(\kappa_i\). Inside this context, each attribute name \(x_j\) identifies each attribute that is tracked. Note that \(x_j\) can appear many times, but the pair \((k_i, x_j)\) will uniquely identify \(y_{ij}\).

Variables:

contexts (dict of dict) – The dictionary whose keys are the identifiers of the objects \(k_i\) and whose values are dictionaries that have as keys the names of the attributes \(x_j\).
SCID_VARNAME (str) – The string representing the name of the attribute used to store the serialization context identifier in foreign objects. By default, it is "NPU_SCID".

SCID_VARNAME = 'NPU_SCID'

__init__(): Instantiate a SerializationContext.

abstractmethod extract_serialization_prefix(comp)

Obtain the prefix used to identify the component. Note that this logic must be overridden by any particular implementation of SerializationContext to provide a way to obtain a prefix representing the object. Typically, software using NPU SerializationContext will extend the class and implement the logic for this method.

Parameters:: comp (object) – The component whose prefix must be obtained.
Returns:: The prefix for the identifier of the object as a function of its type/class.
Return type:: str

generate_identifier(prefix='')

Generate an identifier with the given prefix to uniquely identify an object. Note that, once generated, this identifier should be used as a member attribute of the object and always included when serializing or deserializing it to keep it tracked.

Note that identifiers are strings with the following format prefix:uuid.

Parameters:: prefix (str) – The prefix for the identifier.
Returns:: The generated identifier.
Return type:: str

generate_identifier_from_component(comp)

Generate an identifier from a component. This means that npu.inout.serialization_context.SerializationContext.extract_serialization_prefix() is called to obtain the corresponding prefix, and then it is used as input for npu.inout.serialization_context.SerializationContext.generate_identifier() to generate the final identifier.

Note that this method is not reproducible, i.e., calling it twice on the same or identical components is not guaranteed to generate the same identifier. Instead, once generated, it must be kept as a unique universal identifier for the object.

Parameters:: comp (object) – The component whose identifier must be generated.
Returns:: The identifier generated from the given component.
Return type:: str

has_identifier(comp)

Check whether the given component (object) has an NPU serialization context identifier (SCID_VARNAME).

Parameters:: comp (object) – The object to be checked.
Returns:: True if the object has a NPU serialization context identifier, False otherwise.
Return type:: bool

get_identifier(comp)

Obtain the context identifier (SCID_VARNAME) of the given component (object).

Parameters:: comp (object) – The object whose context identifier must be obtained.
Returns:: The context identifier of the given object.
Return type:: str

set_identifier(comp, scid)

Set the context identifier (SCID_VARNAME) of the given component (object).

Parameters:

comp (object) – The component whose context identifier must be set.
scid (str) – The context identifier for the given object.

Returns:

The serialization context itself, for fluent programming.

Return type:

npu.inout.serialization_context.SerializationContext

track(scid)

Make the serialization context track the given identifier. This mostly reduces to initializing an empty dictionary in the contexts dictionary associated to the given serialization context identifier.

Parameters:: scid (str) – The serialization context identifier that must be tracked.
Returns:: The serialization context itself, for fluent programming.
Return type:: npu.inout.serialization_context.SerializationContext

track_component(comp)

Checks if the component has an identifier
1. If it has an identifier, use it.
2. If it does not have an identifier, generate one and assign it to the component.
Tracks the identifier associated to the component.

Parameters:: comp (object) – The component whose serialization context identifier must be tracked.
Returns:: The serialization context itself, for fluent programming.
Return type:: npu.inout.serialization_context.SerializationContext

is_tracked(scid)

Checks whether the given serialization context identifier is already being tracked by the serialization context object (True) or not (False).

Parameters:: scid (str) – The serialization context identifier to be checked.
Returns:: True if the given serialization context identifier is being tracked, False otherwise.
Return type:: bool

is_tracked_component(comp)

Similar to npu.inout.serialization_context.SerializationContext.is_tracked() but automatically derives the serialization context identifier from the component.

Parameters:: comp (object) – Component whose tracking must be checked.

store_attribute(scid, attr_name, attr_val)

Store the given attribute associated to the given serialization context identifier.

Parameters:

scid (str) – The serialization context identifier \(\kappa_i\).
attr_name (str) – The name of the attribute \(x_i\).
attr_val – The value of the attribute \(y_i\).

Returns:

The serialization context itself, for fluent programming.

Return type:

npu.inout.serialization_context.SerializationContext

store_attribute_from_component(comp, attr_name, attr_val)

Like npu.inout.serialization_context.SerializationContext.store_attribute() but receiving the component instead of its serialization context identifier. Note that the component must already be tracked.

Parameters:: comp (object) – The component whose attribute must be stored to the serialized context.

has_attribute(scid, attr_name)

Checks whether the given attribute has been stored for the object identified with the given serialization context identifier.

Parameters:

scid (str) – The serialization context identifier for the check, i.e., \(\kappa_i\).
attr_name (str) – The name of the attribute for the check, i.e., \(x_i\).

Returns:

True if the given attribute has been stored for the object identified with the given serialization context identifier, False otherwise.

Return type:

bool

has_attribute_from_component(comp, attr_name)

Like npu.inout.serialization_context.SerializationContext.has_attribute() but receiving the component instead of its serialization context identifier. Note that the component must already be tracked.

Parameters:: comp (object) – The component whose attribute existence in the serialization context must be checked.

load_attribute(scid, attr_name)

Load the given attribute from the serialization context

Parameters:

scid (str) – The serialization context identifier \(\kappa_i\).
attr_name (str) – The attribute name \(x_i\).

Returns:

The attribute value \(y_i\).

load_attribute_from_component(comp, attr_name)

Like npu.inout.serialization_context.SerializationContext.load_attribute() but receiving the component instead of its serialization context identifier. Note that the component must already be tracked.

Parameters:: comp (object) – The component whose attribute must be loaded from the serialized context.

get_contexts()

Obtain the dictionary representing the serialization context.

Returns:: The dictionary representing the serialization context.
Return type:: dict