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,
    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:

If decode_steps is set, the steps are used as-is and no other options can also be set.
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`
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(
    self,
    *,
    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(self, 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`.