Types & Protocols

Type annotations & Protocols used throughout v8serialize.

constants.AnySerializationTag

constants.AnySerializationTag

Literal of every SerializationTag value.

This is necessary because MyPy treats a Literal of all enum values differently to a the enum type itself, but Literal[SerializationTag] is not allowed.

constants.UnreleasedVersion

constants.UnreleasedVersion

encode.HostObjectSerializerFn

encode.HostObjectSerializerFn()

The type of a function that writes custom HostObjects.

encode.HostObjectSerializerObj

encode.HostObjectSerializerObj()

Attributes

Name	Description
serialize_host_object	The same as `HostObjectSerializerFn`.

encode.HostObjectSerializer

encode.HostObjectSerializer

Either a HostObjectSerializerObj or HostObjectSerializerFn.

encode.EncodeContext

encode.EncodeContext()

Maintains the state needed to write Python objects in V8 format.

Attributes

Name	Description
stream	The `WritableTagStream` this context writes to.

Methods

Name	Description
deduplicate	Look up and return a previously seen value equal to this value.
encode_object	Encode and write a single Python value to the stream.

deduplicate

encode.EncodeContext.deduplicate(value: T)

Look up and return a previously seen value equal to this value.

If value is not hashable or not found, it’s returned as-is.

encode_object

encode.EncodeContext.encode_object(value: object)

Encode and write a single Python value to the stream.

encode.EncodeNextFn

encode.EncodeNextFn()

Delegate to the next encode step in the sequence to write a value.

Raises

Name	Type	Description
	UnhandledValueEncodeV8SerializeError	If none of the following steps were able to handle a value.

encode.EncodeStepFn

encode.EncodeStepFn()

The signature of a function that writes V8-serialized data to reflect objects.

Encode steps can either write the ctx.stream directly, or delegate to the next encode step by calling next(). Steps can modify the representation of objects as JavaScript by passing a different value to next than the one they received.

encode.EncodeStepObject

encode.EncodeStepObject()

Attributes

Name	Description
encode	The same as `EncodeStepFn`.

encode.EncodeStep

encode.EncodeStep

Either an EncodeStepObject or EncodeStepFn.

decode.HostObjectDeserializerFn

decode.HostObjectDeserializerFn()

The signature of a function that reads HostObject tags from a stream.

decode.HostObjectDeserializerObj

decode.HostObjectDeserializerObj()

Attributes

Name	Description
deserialize_host_object	The same as `HostObjectDeserializerFn`.

decode.HostObjectDeserializer

decode.HostObjectDeserializer

Either HostObjectDeserializerObj or HostObjectDeserializerFn.

decode.TagReader

decode.TagReader(
    self,
    tag_readers: TagReaderRegistry | 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,
)

Controls how V8 serialization data is converted to Python values when deserializing.

Customise the way JavaScript values are represented in Python by creating a TagReader instance with non-default options, and passing it to the decode_steps option of v8serialize.loads() or v8serialize.Decoder()

Parameters

Name	Type	Description	Default
tag_readers	TagReaderRegistry \| None	Override the tag reader functions implied by other arguments. Default: no overrides.	`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`

Attributes

Name	Description
default_timezone
host_object_deserializer
js_array_type
js_constants
js_error_builder
js_object_type
jsmap_type
jsset_type
tag_readers

Methods

Name	Description
decode
deserialize_constant
deserialize_host_object
deserialize_js_array_buffer
deserialize_js_array_buffer_view
deserialize_js_array_dense
deserialize_js_array_sparse
deserialize_js_bigint
deserialize_js_date
deserialize_js_double
deserialize_js_error
deserialize_js_object
deserialize_js_primitive_object
deserialize_js_regexp
deserialize_jsmap
deserialize_jsset
deserialize_object_reference
deserialize_unsupported_wasm
deserialize_v8_shared_object_reference
register_tag_readers

decode

decode.TagReader.decode(
    tag: SerializationTag,
    /,
    ctx: DecodeContext,
    next: DecodeNextFn,
)

deserialize_constant

decode.TagReader.deserialize_constant(tag: ConstantTags, ctx: DecodeContext)

deserialize_host_object

decode.TagReader.deserialize_host_object(
    tag: Literal[SerializationTag.kHostObject],
    ctx: DecodeContext,
)

deserialize_js_array_buffer

decode.TagReader.deserialize_js_array_buffer(
    tag: ArrayBufferTags,
    ctx: DecodeContext,
)

deserialize_js_array_buffer_view

decode.TagReader.deserialize_js_array_buffer_view(
    tag: Literal[SerializationTag.kArrayBufferView],
    ctx: DecodeContext,
)

deserialize_js_array_dense

decode.TagReader.deserialize_js_array_dense(
    tag: Literal[SerializationTag.kBeginDenseJSArray],
    ctx: DecodeContext,
)

deserialize_js_array_sparse

decode.TagReader.deserialize_js_array_sparse(
    tag: Literal[SerializationTag.kBeginSparseJSArray],
    ctx: DecodeContext,
)

deserialize_js_bigint

decode.TagReader.deserialize_js_bigint(
    tag: Literal[SerializationTag.kBigInt],
    ctx: DecodeContext,
)

deserialize_js_date

decode.TagReader.deserialize_js_date(
    tag: Literal[SerializationTag.kDate],
    ctx: DecodeContext,
)

deserialize_js_double

decode.TagReader.deserialize_js_double(
    tag: Literal[SerializationTag.kDouble],
    ctx: DecodeContext,
)

deserialize_js_error

decode.TagReader.deserialize_js_error(
    tag: Literal[SerializationTag.kError],
    ctx: DecodeContext,
)

deserialize_js_object

decode.TagReader.deserialize_js_object(
    tag: Literal[SerializationTag.kBeginJSObject],
    ctx: DecodeContext,
)

deserialize_js_primitive_object

decode.TagReader.deserialize_js_primitive_object(
    tag: PrimitiveObjectTag,
    ctx: DecodeContext,
)

deserialize_js_regexp

decode.TagReader.deserialize_js_regexp(
    tag: Literal[SerializationTag.kRegExp],
    ctx: DecodeContext,
)

deserialize_jsmap

decode.TagReader.deserialize_jsmap(
    tag: Literal[SerializationTag.kBeginJSMap],
    ctx: DecodeContext,
)

deserialize_jsset

decode.TagReader.deserialize_jsset(
    tag: Literal[SerializationTag.kBeginJSSet],
    ctx: DecodeContext,
)

deserialize_object_reference

decode.TagReader.deserialize_object_reference(
    tag: Literal[SerializationTag.kObjectReference],
    ctx: DecodeContext,
)

deserialize_unsupported_wasm

decode.TagReader.deserialize_unsupported_wasm(
    tag: Literal[SerializationTag.kWasmMemoryTransfer, SerializationTag.kWasmModuleTransfer],
    ctx: DecodeContext,
)

deserialize_v8_shared_object_reference

decode.TagReader.deserialize_v8_shared_object_reference(
    tag: Literal[SerializationTag.kSharedObject],
    ctx: DecodeContext,
)

register_tag_readers

decode.TagReader.register_tag_readers(tag_readers: TagReaderRegistry)

decode.ReadableTagStreamReadFunction

decode.ReadableTagStreamReadFunction()

The type of an unbound, argument-less ReadableTagStream method.

decode.DecodeContext

decode.DecodeContext()

Attributes

Name	Description
stream	The `ReadableTagStream` this context reads from.

Methods

Name	Description
decode_object	Return a value by reading a tag’s data from this context’s stream.

decode_object

decode.DecodeContext.decode_object(tag: SerializationTag | None = ...)

Return a value by reading a tag’s data from this context’s stream.

If tag is None, the stream is positioned on a tag which must be read and advanced over. If tag is a SerializationTag, it is the tag that the stream is now positioned just after, and a tag must not be read from the stream again before handling the provided tag.

Returns

Name	Type	Description
	object	A value representing the `tag`.

Raises

Name	Type	Description
	UnhandledTagDecodeV8SerializeError	If it’s not possible to read the tag.

decode.DecodeNextFn

decode.DecodeNextFn()

Delegate to the next decode step in the sequence to read a tag from the stream.

Returns

Name	Type	Description
		The value representing the tag the next decode step read.

Raises

Name	Type	Description
	UnhandledTagDecodeV8SerializeError	If none of the following decode steps were able to read the tag.

decode.DecodeStepFn

decode.DecodeStepFn()

The signature of a function that returns objects to reflect V8-serialized data.

Decode steps can either read the ctx.stream directly, or delegate to the next decode step by calling next(). Steps can modify the return the value decoded by the next step before returning it.

decode.DecodeStepObject

decode.DecodeStepObject()

Attributes

Name	Description
decode	The same as `DecodeStepFn`.

decode.DecodeStep

decode.DecodeStep

Either a DecodeStepObject or DecodeStepFn.

decode.JSMapType

decode.JSMapType

decode.JSSetType

decode.JSSetType

decode.JSObjectType

decode.JSObjectType

decode.JSArrayType

decode.JSArrayType

decode.AnyJSError

decode.AnyJSError()

A Protocol matching JSError and JSErrorData.

Attributes

Name	Description
cause
message
name
stack

decode.ArrayBufferConstructor

decode.ArrayBufferConstructor()

A function that creates a representation of a serialized ArrayBuffer.

decode.ArrayBufferTransferConstructor

decode.ArrayBufferTransferConstructor()

A function that creates a representation of a serialized ArrayBufferTransfer.

decode.ArrayBufferViewConstructor

decode.ArrayBufferViewConstructor()

A function that creates a representation of a serialized ArrayBuffer view.

decode.JSErrorBuilder

decode.JSErrorBuilder()

A function that creates a representation of a serialized Error.

decode.SharedArrayBufferConstructor

decode.SharedArrayBufferConstructor()

A function that creates a representation of a serialized SharedArrayBuffer.

decode.SharedArrayBufferId

decode.SharedArrayBufferId

decode.TransferId

decode.TransferId

Buffer

Buffer()

An alias of collections.abc.Buffer.

BufferSequence

BufferSequence()

A Sequence[int] that’s also a Buffer.

Essentially binary data, like bytes, bytearray, array.array and memoryview.

ReadableBinary

ReadableBinary

Binary data such as bytes, bytearray, array.array and memoryview.

Can also be any BufferSequence.

SparseMutableSequence

SparseMutableSequence()

A writable extension of SparseSequence.

Methods

Name	Description
resize	Change the length of the array.

resize

SparseMutableSequence.resize(length: int)

Change the length of the array.

Elements are dropped if the length is reduced, or gaps are created at the end if the length is increased.

SparseSequence

SparseSequence()

A Sequence that can have holes — indexes with no value present.

Similar to an ordered dict with int keys, but the empty values have a type that need not be None — the hole_value property — with type _HoleT_co.

Unlike a dict, the bounds are defined, __len__ is the length including holes. Indexing with __getitem__ returns the hole value instead of raising a KeyError as dict does. Accessing out-of-bound values raises an IndexError as other Sequences do.

elements() provides a view of the non-hole values as a Mapping.

Attributes

Name	Description
elements_used	The number of index positions that are not holes.
hole_value	The empty value used by the sequence to represent holes.

Methods

Name	Description
element_indexes	Iterate over the indexes in the sequence that are not holes.
elements	Get a live view of the index elements with existant values.

element_indexes

SparseSequence.element_indexes(order: Order = ...)

Iterate over the indexes in the sequence that are not holes.

order is Order.ASCENDING if not specified. Order.UNORDERED allows the implementation to use whichever order is most efficient.

elements

SparseSequence.elements(order: Order = ...)

Get a live view of the index elements with existant values.

order is Order.ASCENDING if not specified. Order.UNORDERED allows the implementation to use whichever order is most efficient.

This is analogous to the items() method of Mappings.

Types & Protocols

constants.AnySerializationTag

constants.UnreleasedVersion

encode.HostObjectSerializerFn

encode.HostObjectSerializerObj

Attributes

encode.HostObjectSerializer

encode.EncodeContext

Attributes

Methods

deduplicate

encode_object

encode.EncodeNextFn

Raises

encode.EncodeStepFn

encode.EncodeStepObject

Attributes

encode.EncodeStep

See Also

decode.HostObjectDeserializerFn

decode.HostObjectDeserializerObj

Attributes

decode.HostObjectDeserializer

decode.TagReader

Parameters

Attributes

Methods

decode

deserialize_constant

deserialize_host_object

deserialize_js_array_buffer

deserialize_js_array_buffer_view

deserialize_js_array_dense

deserialize_js_array_sparse

deserialize_js_bigint

deserialize_js_date

deserialize_js_double

deserialize_js_error

deserialize_js_object

deserialize_js_primitive_object

deserialize_js_regexp

deserialize_jsmap

deserialize_jsset

deserialize_object_reference

deserialize_unsupported_wasm

deserialize_v8_shared_object_reference

register_tag_readers

decode.ReadableTagStreamReadFunction

decode.DecodeContext

Attributes

Methods

decode_object

Returns

Raises

decode.DecodeNextFn

Returns

Raises

decode.DecodeStepFn

decode.DecodeStepObject

Attributes

decode.DecodeStep

See Also

decode.JSMapType

decode.JSSetType

decode.JSObjectType

decode.JSArrayType

decode.AnyJSError

Attributes

decode.ArrayBufferConstructor

decode.ArrayBufferTransferConstructor

decode.ArrayBufferViewConstructor

decode.JSErrorBuilder

decode.SharedArrayBufferConstructor

decode.SharedArrayBufferId

decode.TransferId

Buffer

BufferSequence

ReadableBinary

SparseMutableSequence

Methods