Customized Decoding
The v8serialize.decode module reads V8-serialized data.
default_decode_steps
default_decode_steps
The default sequence of decode steps used to map SerializationTags to Python objects.
This is an instance of TagReader with no options changed from the defaults.
JavaScript types are deserialized as the v8serialize.jstypes.JS* types, unless a built-in Python type can represent the value precisely, such as strings and numbers.
decode.TagReader
decode.TagReader(
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,
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,
)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 |
| 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 |
Attributes
| Name | Description |
|---|---|
| default_timezone | |
| host_object_deserializer | |
| js_array_type | |
| js_constants | |
| js_error_builder | |
| js_object_type | |
| js_primitive_objects | |
| jsmap_type | |
| jsset_type | |
| tag_readers |
Methods
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,
)register_tag_readers
decode.TagReader.register_tag_readers(tag_readers: TagReaderRegistry)decode.DefaultDecodeContext
decode.DefaultDecodeContext(
data: ReadableBinary | None = None,
stream: ReadableTagStream | None = None,
decode_steps: Iterable[DecodeStep] | None = None,
)The default implementation of DecodeContext.
Attributes
| Name | Description |
|---|---|
| decode_steps | |
| stream |
Methods
| Name | Description |
|---|---|
| decode_object |
decode_object
decode.DefaultDecodeContext.decode_object(tag: SerializationTag | None = None)decode.ReadableTagStream
decode.ReadableTagStream(
data: ReadableBinary,
pos: int = 0,
objects: SerializedObjectLog = SerializedObjectLog(),
version: int = kLatestVersion,
)Attributes
| Name | Description |
|---|---|
| data | |
| eof | |
| objects | |
| pos | |
| version |
Methods
| Name | Description |
|---|---|
| ensure_capacity | |
| peak_tag | Get the current position as a SerializationTag without advancing position. |
| read_bigint | |
| read_bytes | |
| read_double | |
| read_error_tag | |
| read_header | Read the V8 serialization stream header and verify it’s a supported version. |
| read_host_object | |
| read_int32 | |
| read_js_array_buffer | |
| read_js_array_buffer_view | |
| read_js_array_dense | |
| read_js_array_sparse | |
| read_js_date | |
| read_js_error | |
| read_js_object | |
| read_js_primitive_object | |
| read_js_regexp | |
| read_jsmap | |
| read_jsset | |
| read_object_reference | |
| read_padding | |
| read_string_onebyte | Decode a OneByteString, which is latin1-encoded text. |
| read_string_twobyte | Decode a TwoByteString, which is UTF-16-encoded text. |
| read_string_utf8 | Decode a Utf8String, which is UTF8-encoded text. |
| read_tag | Read the tag at the current position. |
| read_uint32 | |
| read_v8_shared_object_reference | |
| read_varint | |
| read_zigzag | |
| throw |
ensure_capacity
decode.ReadableTagStream.ensure_capacity(count: int)peak_tag
decode.ReadableTagStream.peak_tag()Get the current position as a SerializationTag without advancing position.
Returns
| Name | Type | Description |
|---|---|---|
| SerializationTag | None | The SerializationTag if the current byte corresponds to one, otherwise None. |
read_bigint
decode.ReadableTagStream.read_bigint(tag: bool = False)read_bytes
decode.ReadableTagStream.read_bytes(count: int)read_double
decode.ReadableTagStream.read_double(tag: bool = False)read_error_tag
decode.ReadableTagStream.read_error_tag()read_header
decode.ReadableTagStream.read_header()Read the V8 serialization stream header and verify it’s a supported version.
@return the header’s version number.
read_host_object
decode.ReadableTagStream.read_host_object(
deserializer: HostObjectDeserializer[T],
tag: bool = False,
)read_int32
decode.ReadableTagStream.read_int32(tag: bool = False)read_js_array_buffer
decode.ReadableTagStream.read_js_array_buffer(
array_buffer: ArrayBufferConstructor[BufferT1],
shared_array_buffer: SharedArrayBufferConstructor[BufferT2],
array_buffer_transfer: ArrayBufferTransferConstructor[BufferT3],
tag: ArrayBufferTags | None = None,
)read_js_array_buffer_view
decode.ReadableTagStream.read_js_array_buffer_view(
backing_buffer: BufferT,
*,
array_buffer_view: ArrayBufferViewConstructor[BufferT, ViewT],
tag: bool = False,
)read_js_array_dense
decode.ReadableTagStream.read_js_array_dense(
ctx: DecodeContext,
*,
identity: object,
tag: bool = False,
)read_js_array_sparse
decode.ReadableTagStream.read_js_array_sparse(
ctx: DecodeContext,
*,
identity: object,
tag: bool = False,
)read_js_date
decode.ReadableTagStream.read_js_date(
tz: tzinfo | None = None,
tag: bool = False,
)read_js_error
decode.ReadableTagStream.read_js_error(
ctx: DecodeContext,
*,
error: JSErrorBuilder[T] | None = None,
tag: bool = False,
)read_js_object
decode.ReadableTagStream.read_js_object(
ctx: DecodeContext,
*,
identity: object,
tag: bool = False,
)read_js_primitive_object
decode.ReadableTagStream.read_js_primitive_object(
ctx: DecodeContext,
*,
tag: PrimitiveObjectTag | None = None,
)read_js_regexp
decode.ReadableTagStream.read_js_regexp(
ctx: DecodeContext,
*,
tag: bool = False,
)read_jsmap
decode.ReadableTagStream.read_jsmap(
ctx: DecodeContext,
*,
identity: object,
tag: bool = False,
)read_jsset
decode.ReadableTagStream.read_jsset(
ctx: DecodeContext,
*,
identity: object,
tag: bool = False,
)read_object_reference
decode.ReadableTagStream.read_object_reference(tag: bool = False)read_padding
decode.ReadableTagStream.read_padding()read_string_onebyte
decode.ReadableTagStream.read_string_onebyte(tag: bool = False)Decode a OneByteString, which is latin1-encoded text.
read_string_twobyte
decode.ReadableTagStream.read_string_twobyte(tag: bool = False)Decode a TwoByteString, which is UTF-16-encoded text.
read_string_utf8
decode.ReadableTagStream.read_string_utf8(tag: bool = False)Decode a Utf8String, which is UTF8-encoded text.
read_tag
decode.ReadableTagStream.read_tag(
tag: SerializationTag | TagConstraint | None = None,
*,
consume: bool = True,
)Read the tag at the current position.
Padding tags are read and ignored until a non-padding tag is found. If consume is False, the current self.pos remains on the tag after returning rather than moving to the next byte. (Padding is always consumed regardless.)
read_uint32
decode.ReadableTagStream.read_uint32(tag: bool = False)read_varint
decode.ReadableTagStream.read_varint(max_bits: int | None = None)read_zigzag
decode.ReadableTagStream.read_zigzag(max_bits: int | None = None)throw
decode.ReadableTagStream.throw(
message: str,
*,
cause: BaseException | None = None,
)decode.ArrayReadResult
decode.ArrayReadResult()The data being deserialized from a dense or sparse array.
Attributes
| Name | Description |
|---|---|
| items | The array and object properties. |
| length | The length of the array being deserialized. |
decode.ReferencedObject
decode.ReferencedObject()Attributes
| Name | Description |
|---|---|
| object | |
| serialized_id |
decode.TagReaderRegistry
decode.TagReaderRegistry(entries: TagReaderRegistry | None = None)A registry of SerializationTags and the functions that can read them.
TagReader uses this to dispatch decode calls to an appropriate function.
Attributes
| Name | Description |
|---|---|
| index |
Methods
| Name | Description |
|---|---|
| match | Get the TagReaderFn function registered for a tag, or None. |
| register | Associate a function with a tag, so that match() will return it. |
| register_all | Copy the registrations of another registry into this one. |
match
decode.TagReaderRegistry.match(tag: TagT)Get the TagReaderFn function registered for a tag, or None.
register
decode.TagReaderRegistry.register(
tag: TagT | TagConstraint[TagT],
tag_reader: TagReaderFn[TagT],
)Associate a function with a tag, so that match() will return it.
register_all
decode.TagReaderRegistry.register_all(registry: TagReaderRegistry)Copy the registrations of another registry into this one.
Existing registrations that also occur in registry are overwritten.
decode.read_stream
decode.read_stream(rts_fn: ReadableTagStreamReadFunction)Create a TagReaderFn that calls a read_xxx function on the stream.