Customized Encoding
The v8serialize.encode module writes V8-serialized data.
default_encode_steps
default_encode_steps
The default sequence of encode steps used to map Python objects to JavaScript values.
The defaults represent common Python types as their JavaScript equivalents, and serializes the v8serialize.jstypes.JS* types as their corresponding JavaScript type.
This sequence contains serialize_object_references and an instance of TagWriter.
encode.serialize_object_references
encode.serialize_object_references(
value: object,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)Serialize references to previously-seen objects instead of duplicating them.
Objects that have already been written to the stream are written as references to the original instance. This:
- Avoids duplication of data.
- Preserves object identity after de-serializing.
- Allows cyclic object hierarchies to be serialized and deserialized without causing infinite loops.
Notes
This is an encode step that can be used as one of the encode_steps with dumps() or Encoder().
encode.TagWriter
encode.TagWriter(self)Defines the conversion of Python types into the V8 serialization format.
TagWriters are responsible for making suitable calls to a WritableTagStream to represent Python objects with the various encoded representations supported by the V8 serialization format.
The stream delegates back to the EncodeContext when writing hierarchical objects, like arrays, to let the context pass sub-values through a sequence of encode steps, typically ending with a TagWriter as the final step.
Methods
encode
encode.TagWriter.encode(
value: object,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_bigint
encode.TagWriter.serialize_bigint(
value: int,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_bool
encode.TagWriter.serialize_bool(
value: bool,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_buffer
encode.TagWriter.serialize_buffer(
value: bytes | bytearray,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_buffer_view
encode.TagWriter.serialize_buffer_view(
value: JSArrayBufferView,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_collection
encode.TagWriter.serialize_collection(
value: Collection[object],
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_float
encode.TagWriter.serialize_float(
value: float,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_hole
encode.TagWriter.serialize_hole(
value: JSHoleType,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_int
encode.TagWriter.serialize_int(
value: int,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_js_array
encode.TagWriter.serialize_js_array(
value: JSArray[object],
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_js_array_buffer
encode.TagWriter.serialize_js_array_buffer(
value: JSArrayBuffer | JSSharedArrayBuffer | JSArrayBufferTransfer,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_js_error
encode.TagWriter.serialize_js_error(
value: AnyJSError,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_js_object
encode.TagWriter.serialize_js_object(
value: JSObject[object],
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_js_primitive_object
encode.TagWriter.serialize_js_primitive_object(
value: JSPrimitiveObject,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_js_regexp
encode.TagWriter.serialize_js_regexp(
value: JSRegExp,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_mapping
encode.TagWriter.serialize_mapping(
value: Mapping[object, object],
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_none
encode.TagWriter.serialize_none(
value: None,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_python_datetime
encode.TagWriter.serialize_python_datetime(
value: datetime,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_python_exception
encode.TagWriter.serialize_python_exception(
value: BaseException,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_python_regexp
encode.TagWriter.serialize_python_regexp(
value: re.Pattern[AnyStr],
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_set
encode.TagWriter.serialize_set(
value: AbstractSet[object],
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_str
encode.TagWriter.serialize_str(
value: str,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)serialize_undefined
encode.TagWriter.serialize_undefined(
value: JSUndefinedType,
/,
ctx: EncodeContext,
next: EncodeNextFn,
)encode.DefaultEncodeContext
encode.DefaultEncodeContext(
self,
encode_steps: Iterable[EncodeStepObject | EncodeStepFn] | None = None,
*,
stream: WritableTagStream | None = None,
deduplicate_max_size: int | None = None,
)Attributes
| Name | Description |
|---|---|
| encode_steps | |
| stream |
Methods
| Name | Description |
|---|---|
| deduplicate | |
| encode_object | Serialize a single Python value to the stream. |
deduplicate
encode.DefaultEncodeContext.deduplicate(value: T)encode_object
encode.DefaultEncodeContext.encode_object(value: object)Serialize a single Python value to the stream.
The encode_steps convert the Python value to JavaScript representation, and the stream writes out V8 serialization format tagged data.
encode.WritableTagStream
encode.WritableTagStream(
self,
data: bytearray = bytearray(),
objects: SerializedObjectLog = SerializedObjectLog(),
features: SerializationFeature = SerializationFeature.MaxCompatibility,
)Write individual tagged data items in the V8 serialization format.
This is a low-level interface to incrementally generate a V8 serialization byte stream.
Attributes
| Name | Description |
|---|---|
| allowed_tags | When set, only tags allowed by the constraint may be written. |
| data | |
| features | |
| objects | |
| pos |
Methods
| Name | Description |
|---|---|
| constrain_tags | Prevent writing tags to the stream which are not allowed in a given context. |
| write_bigint | |
| write_constant | |
| write_double | |
| write_header | Write the V8 serialization stream header. |
| write_host_object | |
| write_int32 | |
| write_js_array_buffer | |
| write_js_array_buffer_view | |
| write_js_array_dense | |
| write_js_array_sparse | |
| write_js_date | |
| write_js_error | |
| write_js_object | |
| write_js_primitive_object | |
| write_js_regexp | |
| write_jsmap | |
| write_jsset | |
| write_object_reference | |
| write_string_onebyte | Encode a OneByte string, which is latin1-encoded text. |
| write_string_twobyte | |
| write_string_utf8 | Encode a Utf8String, which is UTF-8-encoded text. |
| write_tag | |
| write_uint32 | |
| write_v8_shared_object_reference | |
| write_varint | |
| write_zigzag |
write_bigint
encode.WritableTagStream.write_bigint(
value: int,
*,
tag: Literal[SerializationTag.kBigInt] | None = SerializationTag.kBigInt,
)write_constant
encode.WritableTagStream.write_constant(constant: ConstantTags)write_double
encode.WritableTagStream.write_double(
value: float | int,
*,
tag: Literal[SerializationTag.kDouble] | None = SerializationTag.kDouble,
)write_header
encode.WritableTagStream.write_header()Write the V8 serialization stream header.
write_host_object
encode.WritableTagStream.write_host_object(
value: T,
*,
serializer: HostObjectSerializer[T],
)write_int32
encode.WritableTagStream.write_int32(
value: int,
*,
tag: Literal[SerializationTag.kInt32] | None = SerializationTag.kInt32,
)write_js_array_buffer
encode.WritableTagStream.write_js_array_buffer(
buffer: AnyArrayBuffer | AnySharedArrayBuffer | AnyArrayBufferTransfer,
*,
identity: object | None = None,
)write_js_array_buffer_view
encode.WritableTagStream.write_js_array_buffer_view(
buffer_view: AnyArrayBufferView,
*,
identity: object | None = None,
)write_js_array_dense
encode.WritableTagStream.write_js_array_dense(
array: Collection[object],
ctx: EncodeContext,
*,
properties: Iterable[tuple[Any, Any]] | None = None,
identity: object | None = None,
)write_js_array_sparse
encode.WritableTagStream.write_js_array_sparse(
items: Iterable[tuple[object, object]],
ctx: EncodeContext,
*,
length: int,
identity: object | None = None,
)write_js_date
encode.WritableTagStream.write_js_date(
value: datetime,
*,
identity: object | None = None,
)write_js_error
encode.WritableTagStream.write_js_error(
error: AnyJSError,
ctx: EncodeContext,
*,
identity: object | None = None,
)write_js_object
encode.WritableTagStream.write_js_object(
items: Iterable[tuple[object, object]],
ctx: EncodeContext,
*,
identity: object | None = None,
)write_js_primitive_object
encode.WritableTagStream.write_js_primitive_object(
obj: JSPrimitiveObject,
*,
identity: object | None = None,
)write_js_regexp
encode.WritableTagStream.write_js_regexp(
regexp: JSRegExp,
*,
identity: object | None = None,
)write_jsmap
encode.WritableTagStream.write_jsmap(
items: Iterable[tuple[object, object]],
ctx: EncodeContext,
*,
identity: object | None = None,
)write_jsset
encode.WritableTagStream.write_jsset(
values: Iterable[object],
ctx: EncodeContext,
*,
identity: object | None = None,
)write_object_reference
encode.WritableTagStream.write_object_reference(
obj: object | None = None,
serialized_id: SerializedId | None = None,
)write_string_onebyte
encode.WritableTagStream.write_string_onebyte(
value: str,
*,
tag: Literal[SerializationTag.kOneByteString] | None = SerializationTag.kOneByteString,
)Encode a OneByte string, which is latin1-encoded text.
write_string_twobyte
encode.WritableTagStream.write_string_twobyte(
value: str,
*,
tag: Literal[SerializationTag.kTwoByteString] | None = SerializationTag.kTwoByteString,
)write_string_utf8
encode.WritableTagStream.write_string_utf8(
value: str,
*,
tag: Literal[SerializationTag.kUtf8String] | None = SerializationTag.kUtf8String,
)Encode a Utf8String, which is UTF-8-encoded text.
Note: We never encode Utf8String at runtime, but we use it to test the decoder. The V8 implementation only decodes Utf8String.
write_tag
encode.WritableTagStream.write_tag(tag: SerializationTag | None)write_uint32
encode.WritableTagStream.write_uint32(
value: int,
*,
tag: Literal[SerializationTag.kUint32] | None = SerializationTag.kUint32,
)write_varint
encode.WritableTagStream.write_varint(n: int)write_zigzag
encode.WritableTagStream.write_zigzag(n: int)encode.TagConstraintRemover
encode.TagConstraintRemover(self, stream: WritableTagStream)Context manager that resets the tag constraint on a WritableTagStream.
Upon exiting, the stream’s allowed_tags is reset back to None allowing any tag to be written.
Attributes
| Name | Description |
|---|---|
| stream |
encode.HostObjectSerializer
encode.HostObjectSerializer
Either a HostObjectSerializerObj or HostObjectSerializerFn.