Encoding & Decoding

loads() and dumps() read and write V8-serialized data.

dumps

dumps(value, *, encode_steps=default_encode_steps, features=None, v8_version=None)

Serialize a Python value into a JavaScript value in the V8 serialization format.

v8_version and features together control the SerializationFeatures that are enabled. Setting v8_version enables all features supported by the version. Setting features selectively enables the specified features. The union of these feature sets is enabled when encoding.

If features and v8_version are left unchanged, no serialization features beyond the baseline are enabled, so serialized data can be read by any V8 runtime from SerializationFeature.MaxCompatibility.first_v8_version.

Parameters

Name Type Description Default
value object The Python value to serialize. required
encode_steps Iterable[EncodeStep] | None The sequence of encode steps that control how the value is converted to JavaScript types. default_encode_steps
features SerializationFeature | None Additional features of the V8 serialization format to enable. None
v8_version Version | SymbolicVersion | str | None The minimum version of V8 that needs to be able to read the serialized data. None

Returns

Type Description
bytes The serialized data.

Raises

Type Description
UnhandledValueEncodeV8SerializeError When a value (or a sub-value within it) is not supported by the encode_steps.
FeatureNotEnabledEncodeV8SerializeError When encoding value requires a SerializationFeature to be enabled that isn’t enabled.
EncodeV8SerializeError Is the parent of all data-specific errors thrown when encoding.

Examples

>>> from base64 import b64encode
>>> from v8serialize import loads
>>> from v8serialize.jstypes import JSObject, JSSet
>>>
>>> data = dumps(JSObject(id=42, title='Stuff', tags=JSSet(['foo', 'bar'])))
>>> loads(data)
JSObject(id=42, title='Stuff', tags=JSSet(['foo', 'bar']))

loads

loads(data, *, decode_steps=None, nodejs=None, jsmap_type=None, jsset_type=None, js_object_type=None, js_array_type=None, js_constants=None, host_object_deserializer=None, js_error_builder=None, default_timezone=None)

Deserialize a JavaScript value encoded in V8 serialization format.

The serialized JavaScript types are mapped to appropriate Python equivalents according to the keyword argument options:

  1. If decode_steps is set, the steps are used as-is and no other options can also be set.
  2. If decode_steps is not set, other options are used to construct a TagReader to serve as the decode_steps.

Parameters

Name Type Description Default
data ReadableBinary | Buffer The bytes to deserialize as a bytes-like object such as bytes, bytearray, memoryview. required
decode_steps Iterable[DecodeStep] | None A sequence of decode steps, which are responsible for creating Python values to represent the JavaScript values found in the data. None
nodejs bool | None Node.js’s custom buffer HostObject extension is enabled unless False, or host_object_deserializer is set. None
jsmap_type JSMapType | None A function returning an empty dict to represent Map. Default: JSMap. None
jsset_type JSSetType | None A function returning an empty set to represent Set. Default: JSSet. None
js_object_type JSObjectType | None A function returning an empty dict to represent Object. Default: JSObject. None
js_array_type JSArrayType | None A function returning an empty dict to represent Array. Default: JSArray. None
js_constants Mapping[ConstantTags, object] | None A dict mapping tags from JS_CONSTANT_TAGS to the values to represent them as. Default: see JS_CONSTANT_TAGS. None
host_object_deserializer HostObjectDeserializer[object] | None A HostObjectDeserializer to load HostObject extension tags. Default: see desc. None
js_error_builder JSErrorBuilder[object] | None A JSErrorBuilder to create Error representations. Default: JSError.builder None
default_timezone tzinfo | None The timezone to use when creating datetime to represent Date. Default: datetimes have no timezone. None

Returns

Type Description
object The first value in the data, as deserialized by the decode_steps. Using the default_decode_steps, this will be a type from v8serialize.jstypes, such as JSObject to represent a JavaScript Object.

Raises

Type Description
DecodeV8SerializeError When data is not well-formed V8 serialization format data.
UnhandledTagDecodeV8SerializeError When the decode_steps don’t support a JavaScript type occurring in the data.

Notes

Data serialized by V8 serialization format version 13 or newer can be decoded. (13 was introduced in 2017, V8 version 5.8.294, used by Node.JS 16.)

loads() does not need any configuration of V8 version or serialization features, because it automatically supports decoding data encoded with or without optional features enabled.

Examples

>>> from v8serialize import dumps, loads
>>> loads(dumps({'Hello': 'World'}))
JSMap({'Hello': 'World'})

The types used to represent JavaScript values can be changed, for example, we can use a regular Python dict to represent JavaScript Map.

>>> loads(dumps({'Hello': 'World'}), jsmap_type=dict)
{'Hello': 'World'}

By default JavaScript null and undefined are also different in Python:

>>> from v8serialize.constants import SerializationTag
>>> from v8serialize.jstypes import JSUndefined, JSObject
>>> loads(dumps(JSObject(missing_null=None, missing_undefined=JSUndefined)))
JSObject(missing_null=None, missing_undefined=JSUndefined)

But we can make them both be None:

>>> loads(dumps(JSObject(missing_null=None,
...                      missing_undefined=JSUndefined)),
...       js_constants={SerializationTag.kUndefined: None})
JSObject(missing_null=None, missing_undefined=None)

Encoder

Encoder(self, *, encode_steps=default_encode_steps, features=None, v8_version=None)

A re-usable configuration for serializing objects into V8 serialization format.

The encode_steps, features and v8_version arguments behave as described for dumps(). The encode() method behaves like dumps() without needing to pass the arguments for every call.

Parameters

Name Type Description Default
encode_steps Iterable[EncodeStep] | None The sequence of encode steps that control how the value is converted to JavaScript types. default_encode_steps
features SerializationFeature | None Additional features of the V8 serialization format to enable. None
v8_version Version | UnreleasedVersion | str | None The minimum version of V8 that needs to be able to read the serialized data. None

Attributes

Name Description
encode_steps
features
first_v8_version The earliest version of V8 that can read data produced by this Encoder.

Methods

Name Description
encode Serialize a value in the V8 serialization format.

encode

Encoder.encode(value)

Serialize a value in the V8 serialization format.

Parameters

Name Type Description Default
value object The Python object to serialize. required

Returns

Type Description
bytearray A bytearray containing the encoded bytes.

Decoder

Decoder(self, decode_steps=default_decode_steps)

A re-usable configuration for deserializing V8 serialization format data.

The decode_steps argument behaves as described for loads(). The decode() and decodes() methods behave like loads() without needing to pass the decode_steps for every call.

Parameters

Name Type Description Default
decode_steps Iterable[DecodeStep] | None A sequence of decode steps, which are responsible for creating Python values to represent the JavaScript values found when decoding data. default_decode_steps

Attributes

Name Description
decode_steps The sequence of decode steps that define how to create Python values.

Methods

Name Description
decode Deserialize V8 serialization format data from a file.
decodes Deserialize V8 serialization format data from a bytes-like object.

decode

Decoder.decode(fp)

Deserialize V8 serialization format data from a file.

This Decoder’s decode_steps are used to create Python types from the serialized data.

Parameters

Name Type Description Default
fp SupportsRead[bytes] The file-like object to read and deserialize. required

Returns

Type Description
object The first value in the fp.

decodes

Decoder.decodes(data)

Deserialize V8 serialization format data from a bytes-like object.

This Decoder’s decode_steps are used to create Python types from the serialized data.

Parameters

Name Type Description Default
data ReadableBinary | Buffer The bytes-like object to deserialize. required

Returns

Type Description
object The first value in data.