Encoding & Decoding

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

dumps

dumps(
    value: object,
    *,
    encode_steps: Iterable[EncodeStep] | None = default_encode_steps,
    features: SerializationFeature | None = None,
    v8_version: Version | SymbolicVersion | str | None = 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

Name	Type	Description
	bytes	The serialized data.

Raises

Name	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: ReadableBinary | Buffer,
    *,
    decode_steps: Iterable[DecodeStep] | None = None,
    nodejs: bool | None = None,
    jsmap_type: JSMapType | None = None,
    jsset_type: JSSetType | None = None,
    js_object_type: JSObjectType | None = None,
    js_array_type: JSArrayType | None = None,
    js_constants: Mapping[ConstantTags, object] | None = None,
    js_primitive_objects: bool | None = None,
    host_object_deserializer: HostObjectDeserializer[object] | None = None,
    js_error_builder: JSErrorBuilder[object] | None = None,
    default_timezone: tzinfo | None = 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.
   • host_object_deserializer defaults to NodeJsArrayBufferViewHostObjectHandler unless nodejs is False.

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
js_primitive_objects	bool | None	If True, wrapped/boxed primitive values are decoded as JSPrimitiveObject. If False, wrapped/boxed primitives are unwrapped to native Python types. Default: False.	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

Name	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

Name	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(
    encode_steps: Iterable[EncodeStep] | None = default_encode_steps,
    features: SerializationFeature | None = None,
    v8_version: Version | UnreleasedVersion | str | None = 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: object)

Serialize a value in the V8 serialization format.

Parameters

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

Returns

Name	Type	Description
	bytearray	A bytearray containing the encoded bytes.

Decoder

Decoder(decode_steps: Iterable[DecodeStep] | None = 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: SupportsRead[bytes])

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

Name	Type	Description
	object	The first value in the fp.

decodes

Decoder.decodes(data: ReadableBinary | Buffer)

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

Name	Type	Description
	object	The first value in data.