scenic.core.serialization

Utilities to help serialize Scenic objects.

The functions in this module usually do not need to be used directly. For high-level serialization APIs, see Scenario.sceneToBytes, Scenario.simulationToBytes, and Scene.dumpAsScenicCode.

Summary of Module Members

Functions

deterministicHash	Compute a deterministic hash for a mapping of options.
dumpAsScenicCode	Utility function to help export Scenic objects as Scenic code.
patched_save_module
readBool
readBytes
readFloat
readInt
readStr
scenicToJSON	Utility function to help serialize Scenic objects to JSON.
writeBool
writeBytes
writeFloat
writeInt
writeStr

Classes

Serializer

Class for (de)serializing scenes, etc.

Exceptions

SerializationError

An error occurring during serialization/deserialization of Scenic objects.

Member Details

deterministicHash(mapping, *, digest_size=8)

Compute a deterministic hash for a mapping of options.

Keys are sorted (by their string representation) and encoded with explicit separators so that different key/value combinations do not collide under simple concatenation.

Only int/float/str (and bool, as a subclass of int) values are encoded directly; any other value is replaced by a generic placeholder byte, to avoid nondeterminism from reprs containing memory addresses or other run-specific data.

scenicToJSON(obj)

Utility function to help serialize Scenic objects to JSON.

Suitable for passing as the default argument to json.dump. At the moment this only supports very basic types like scalars and vectors: it does not allow encoding of an entire Object.

dumpAsScenicCode(value, stream)

Utility function to help export Scenic objects as Scenic code.

exception SerializationError

Bases: Exception

An error occurring during serialization/deserialization of Scenic objects.

class Serializer(data=b'', allowPickle=False, detectEnd=False)

Class for (de)serializing scenes, etc.

Ordinary Scenic users do not need to know about this class: they can use public APIs such as Scenario.sceneToBytes. If you have defined a custom type of Distribution whose valueType isn’t one of the types used by the built-in primitive distributions (i.e. int, float, Vector), read on.

The sampled value of a Distribution is encoded as follows:

1. If the Distribution is _deterministic, recursively encode the sampled values of its dependencies.

2. If its valueType is a type for which we have a “codec” (like int or float), use the encoding function provided by the codec.

3. If the valueType provides a encodeTo method, use that.

4. If the user has allowed the use of pickle, pickle the value.

5. Otherwise raise a SerializationError.

Thus, you need only extend the serialization mechanism if your Distribution cannot be made deterministic (by adding appropriate dependencies with simpler valueTypes) and it has an unusual valueType. In that case, it’s best to have your valueType implement encodeTo and decodeFrom methods: see Vector for example. If for some reason you can’t add those methods to the class in question, you can use Serializer.addCodec to register encoder/decoder functions. Finally, if you’re only using serialization internally and aren’t concerned about security issues or making the encoding as compact as possible, you can turn on the allowPickle option: this will use pickle to encode any objects for which no specialized encoder is known.

classmethod sceneFormatVersion()

Current version of the Scene serialization format.

Must be incremented if the writeScene method or any of its helper methods (e.g. writeValue) change, or if a new codec is added.

classmethod replayFormatVersion()

Current version of the Simulation replay serialization format.

Must be incremented if the writeReplayHeader or writeValue methods change, or if a new codec is added.

writeScene(scenario, scene)

Serialize a Scene.

writeReplayHeader(flags)

Begin the encoding of a Simulation replay.

classmethod addCodec(ty, encoder, decoder)

Register encoder and decoder functions for the given type.

The encoder function should have signature encoder(value, stream) with stream a binary file-like object. The decoder function should have signature decoder(stream) and return the decoded value.

writeValue(value, ty)

Serialize a value of the given type.