ArrayBuffer, TypedArray, DataView

Python equivalents of JavaScript’s binary data buffer types.

jstypes.JSArrayBuffer

jstypes.JSArrayBuffer(
    self,
    data: AnyBuffer | None | int = None,
    byte_length: int | None = None,
    *,
    max_byte_length: int | None = None,
    resizable: bool | None = None,
    copy_data: bool | None = None,
    readonly: bool | None = None,
)

Python equivalent of JavaScript’s ArrayBuffer.

This is a context manager which returns itself and calls close() on exit.
This is a Buffer which exposes its data as a memoryview.

Parameters

Name	Type	Description	Default
data	`AnyBuffer` \| None \| int	Binary data to populate the buffer with. Default: null bytes of `byte_length`.	`None`
byte_length	int \| None	The number of bytes the buffer will be created with. Default: length of `data` or 0.	`None`
max_byte_length	int \| None	The maximum length the buffer can be resized to. The buffer will not be resizable if this isn’t set. Default: the initial length of the buffer.	`None`
resizable	bool \| None	Make the buffer resizable, starting at its maximum length. Default: `True` if a `max_byte_length` is set.	`None`
copy_data	bool \| None	Whether to copy the `data` parameter, or wrap it as is. Default: `True`.	`None`
readonly	bool \| None	Whether to allow the buffer data to be modified. Default: `False`	`None`

Attributes

Name	Description
data	The buffer’s binary data.
max_byte_length	The maximum size that `resize()` can expand this buffer to.
resizable	Whether this buffer can be resized with `resize()`.

Methods

Name	Description
close	Release the buffer’s data if it’s a `memoryview`.
resize	Resize the buffer, within the `max_byte_length` limit.

close

jstypes.JSArrayBuffer.close()

Release the buffer’s data if it’s a memoryview.

resize

jstypes.JSArrayBuffer.resize(byte_length: int)

Resize the buffer, within the max_byte_length limit.

jstypes.create_view

jstypes.create_view(
    buffer: JSArrayBufferT,
    format: ArrayBufferViewTag | DataFormat | ArrayBufferViewStructFormat,
    *,
    byte_offset: int = 0,
    byte_length: int | None = None,
    readonly: Literal[True] | None = None,
)

Create a view over a data buffer, enforcing byte boundaries as JavaScript does.

This creates an instance of the appropriate view type for the format.

Returns

Name	Type	Description
	DataView \| TypedArray:	An instance of `DataView` or `TypedArray` wrapping `buffer`.

Examples

>>> from v8serialize.constants import ArrayBufferViewTag
>>> create_view(b'', format=ArrayBufferViewTag.kUint32Array)
JSUint32Array(b'')

>>> uint64 = DataFormat.resolve(data_type=DataType.UnsignedInt, byte_length=8)
>>> create_view(b'', format=uint64)
JSBigUint64Array(b'')

jstypes.JSTypedArray

jstypes.JSTypedArray(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

Python equivalent of JavaScript’s TypedArray.

Note

As in JavaScript, this is an abstract type which cannot be instantiated.

Attributes

Name	Description
backing_buffer	The byte buffer this view exposes a range of.
byte_length	The number of bytes accessible through this view.
byte_offset	The view’s position in the backing_buffer.
data_format	The `DataFormat` for this view’s data type.
element_type	The Python type of this view’s individual indexes.
is_backing_buffer_resizable	Whether `.backing_buffer` can change its byte length.
is_in_range	Whether this view’s entire range exists in the `.backing_buffer`.
is_length_tracking	Whether this view changes length to match a resizable `.backing_buffer`.
item_length	The number of items in the view’s backing_buffer range.
item_offset	The start of the view’s backing_buffer range.
readonly	Whether the view must be readonly.
view_tag	The `ArrayBufferViewTag` this view is for.

Methods

Name	Description
from_bytes	Create a view, validating byte offsets as JavaScript does.
get_buffer	Get a context manager that provides this view’s region as a `memoryview`.
get_buffer_as_memoryview	Access the view’s region of `.backing_buffer` as a `memoryview`.

from_bytes

jstypes.JSTypedArray.from_bytes(
    backing_buffer: JSArrayBufferT,
    *,
    byte_offset: int = 0,
    byte_length: int | None = None,
    readonly: Literal[True] | None = None,
)

Create a view, validating byte offsets as JavaScript does.

get_buffer

jstypes.JSTypedArray.get_buffer(readonly: Literal[True] | None = None)

Get a context manager that provides this view’s region as a memoryview.

Examples

>>> with JSUint8Array.from_bytes(b'\xFF\x80').get_buffer() as mv:
...     assert isinstance(mv, memoryview)
...     print(mv[0], mv[1])
255 128

get_buffer_as_memoryview

jstypes.JSTypedArray.get_buffer_as_memoryview(
    readonly: Literal[True] | None = None,
)

Access the view’s region of .backing_buffer as a memoryview.

The returned memoryview:

Will be empty if the view is not in range.
Is always 1-dimensional and contains uint8 items (format "B").

Parameters

Name	Type	Description	Default
readonly	Literal[True] \| None	If True, the returned `memoryview` will be read-only (even if this view itself is not read-only).	`None`

jstypes.JSDataView

jstypes.JSDataView(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

Python equivalent of [JavaScript's DataView].

[JavaScript's DataView]: https://developer.mozilla.org/en-US/docs/Web/\

JavaScript/Reference/Global_Objects/DataView

Examples

>>> dv = JSDataView(bytearray(3))
>>> with dv.get_buffer() as buf:
...     buf.set_uint8(0, 1)
...     buf.set_uint8(1, 2)
...     print("256 + 2 =", buf.get_uint16(0))  # big-endian by default
...     print("256 * 2 + 1 =", buf.get_uint16(0, little_endian=True))
256 + 2 = 258
256 * 2 + 1 = 513
>>> dv.backing_buffer
bytearray(b'\x01\x02\x00')

Attributes

Name	Description
backing_buffer	The byte buffer this view exposes a range of.
byte_length	The number of bytes accessible through this view.
byte_offset	The view’s position in the backing_buffer.
data_format
is_backing_buffer_resizable	Whether `.backing_buffer` can change its byte length.
is_in_range	Whether this view’s entire range exists in the `.backing_buffer`.
is_length_tracking	Whether this view changes length to match a resizable `.backing_buffer`.
item_length	The number of items in the view’s backing_buffer range.
item_offset	The start of the view’s backing_buffer range.
readonly	Whether the view must be readonly.
view_tag

Methods

Name	Description
from_bytes	Create a view, validating byte offsets as JavaScript does.
get_buffer	Access the view’s region of `.backing_buffer` as a `DataViewBuffer`.
get_buffer_as_memoryview	Access the view’s region of `.backing_buffer` as a `memoryview`.

from_bytes

jstypes.JSDataView.from_bytes(
    backing_buffer: JSArrayBufferT,
    *,
    byte_offset: int = 0,
    byte_length: int | None = None,
    readonly: Literal[True] | None = None,
)

Create a view, validating byte offsets as JavaScript does.

get_buffer

jstypes.JSDataView.get_buffer(readonly: Literal[True] | None = None)

Access the view’s region of .backing_buffer as a DataViewBuffer.

get_buffer_as_memoryview

jstypes.JSDataView.get_buffer_as_memoryview(
    readonly: Literal[True] | None = None,
)

Access the view’s region of .backing_buffer as a memoryview.

The returned memoryview:

Will be empty if the view is not in range.
Is always 1-dimensional and contains uint8 items (format "B").

Parameters

Name	Type	Description	Default
readonly	Literal[True] \| None	If True, the returned `memoryview` will be read-only (even if this view itself is not read-only).	`None`

jstypes.DataViewBuffer

jstypes.DataViewBuffer(self, buffer: memoryview)

Provides methods to read/write data types in a JSDataView.

This is return type of JSDataView.get_buffer(). It provides all the methods to read/write binary data as variable-width int/float data types that JavaScript’s DataView provides.

This is a context manager which returns itself and releases .buffer on exit.
This is a Buffer which exposes its .buffer as a memoryview.

Note

The get_*/set_* methods read & write values as big-endian unless the little_endian=True argument is used. Most computers are have little-endian native byte order, and the V8 serialization format itself is defined as using the system’s native byte order, and v8serialize assumes it’s running on a little-endian system.

Attributes

Name	Description
buffer	The `memoryview` this view is operating on.

Methods

Name	Description
get_bigint64
get_biguint64
get_float16
get_float32
get_float64
get_int16
get_int32
get_int8
get_uint16
get_uint32
get_uint8
read
set_bigint64
set_biguint64
set_float16
set_float32
set_float64
set_int16
set_int32
set_int8
set_uint16
set_uint32
set_uint8
write

get_bigint64

jstypes.DataViewBuffer.get_bigint64(
    byte_offset: int,
    little_endian: bool = False,
)

get_biguint64

jstypes.DataViewBuffer.get_biguint64(
    byte_offset: int,
    little_endian: bool = False,
)

get_float16

jstypes.DataViewBuffer.get_float16(
    byte_offset: int,
    little_endian: bool = False,
)

get_float32

jstypes.DataViewBuffer.get_float32(
    byte_offset: int,
    little_endian: bool = False,
)

get_float64

jstypes.DataViewBuffer.get_float64(
    byte_offset: int,
    little_endian: bool = False,
)

get_int16

jstypes.DataViewBuffer.get_int16(byte_offset: int, little_endian: bool = False)

get_int32

jstypes.DataViewBuffer.get_int32(byte_offset: int, little_endian: bool = False)

get_int8

jstypes.DataViewBuffer.get_int8(byte_offset: int)

get_uint16

jstypes.DataViewBuffer.get_uint16(byte_offset: int, little_endian: bool = False)

get_uint32

jstypes.DataViewBuffer.get_uint32(byte_offset: int, little_endian: bool = False)

get_uint8

jstypes.DataViewBuffer.get_uint8(byte_offset: int)

read

jstypes.DataViewBuffer.read(struct_format: str, byte_offset: int)

set_bigint64

jstypes.DataViewBuffer.set_bigint64(
    byte_offset: int,
    value: int,
    little_endian: bool = False,
)

set_biguint64

jstypes.DataViewBuffer.set_biguint64(
    byte_offset: int,
    value: int,
    little_endian: bool = False,
)

set_float16

jstypes.DataViewBuffer.set_float16(
    byte_offset: int,
    value: float,
    little_endian: bool = False,
)

set_float32

jstypes.DataViewBuffer.set_float32(
    byte_offset: int,
    value: float,
    little_endian: bool = False,
)

set_float64

jstypes.DataViewBuffer.set_float64(
    byte_offset: int,
    value: float,
    little_endian: bool = False,
)

set_int16

jstypes.DataViewBuffer.set_int16(
    byte_offset: int,
    value: int,
    little_endian: bool = False,
)

set_int32

jstypes.DataViewBuffer.set_int32(
    byte_offset: int,
    value: int,
    little_endian: bool = False,
)

set_int8

jstypes.DataViewBuffer.set_int8(byte_offset: int, value: int)

set_uint16

jstypes.DataViewBuffer.set_uint16(
    byte_offset: int,
    value: int,
    little_endian: bool = False,
)

set_uint32

jstypes.DataViewBuffer.set_uint32(
    byte_offset: int,
    value: int,
    little_endian: bool = False,
)

set_uint8

jstypes.DataViewBuffer.set_uint8(byte_offset: int, value: int)

write

jstypes.DataViewBuffer.write(struct_format: str, byte_offset: int, *values: Any)

jstypes.DataFormat

jstypes.DataFormat(self, byte_length: int, data_type: AnyDataType, format: str)

A struct format for a specific data type and precision.

Attributes

Name	Description
byte_length
data_type
format

Methods

Name	Description
cast
resolve	Find the struct format on this platform with a given size and data type.

cast

jstypes.DataFormat.cast(view: memoryview[Any])

resolve

jstypes.DataFormat.resolve(data_type: AnyDataType, byte_length: int)

Find the struct format on this platform with a given size and data type.

Parameters

Name	Type	Description	Default
data_type	`AnyDataType`	The data type to resolve.	required
byte_length	int	The required precision in bytes (\(bits/8\), e.g. 32 bits is 4 bytes).	required

Returns

Name	Type	Description
	A `DataFormat` matching the parameters.

Raises

Name	Type	Description
	ValueError	If the platform does not support a data type with the requested parameters.

Examples

>>> DataFormat.resolve(data_type=DataType.UnsignedInt, byte_length=4)
DataFormat(byte_length=4, data_type=DataType.UnsignedInt, format='I')

jstypes.DataType

jstypes.DataType()

An enum of the data types used in JavaScript buffers.

Attributes

Name	Description
Bytes
Float
SignedInt
UnsignedInt
python_type	The Python type that represents this data type.
struct_formats	The struct module format characters for this `DataType`.

Methods

Name	Description
cast

cast

jstypes.DataType.cast(view: memoryview, *, data_format: DataFormat)

jstypes.ArrayBufferViewStructFormat

jstypes.ArrayBufferViewStructFormat(
    self,
    value: ArrayBufferViewTag | DataFormat | ArrayBufferViewStructFormat,
)

An enum of the TypedArray and DataView types.

This is used to name view types, and resolve the view type for an ArrayBufferViewTag value.

Examples

>>> from v8serialize.constants import ArrayBufferViewTag

Resolve a view type from a ArrayBufferViewTag:

>>> ArrayBufferViewStructFormat(ArrayBufferViewTag.kUint32Array).view_type
<class 'v8serialize.jstypes.jsbuffers.JSUint32Array'>

Resolve a view type from data type and precision:

>>> uint64 = DataFormat.resolve(data_type=DataType.UnsignedInt, byte_length=8)
>>> ArrayBufferViewStructFormat(uint64).view_type
<class 'v8serialize.jstypes.jsbuffers.JSBigUint64Array'>

Attributes

Name	Description
BigInt64Array
BigUint64Array
DataView
Float16Array
Float32Array
Float64Array
Int16Array
Int32Array
Int8Array
Uint16Array
Uint32Array
Uint8Array
Uint8ClampedArray

jstypes.JSArrayBufferError

jstypes.JSArrayBufferError(self)

The parent type of exceptions raised by the JavaScript buffer types.

jstypes.BoundsJSArrayBufferError

jstypes.BoundsJSArrayBufferError(
    self,
    message: str,
    byte_offset: int,
    byte_length: int | None,
    buffer_byte_length: int,
)

Raised when a byte offset is out of bounds.

Attributes

Name	Description
buffer_byte_length
byte_length
byte_offset

jstypes.ByteLengthJSArrayBufferError

jstypes.ByteLengthJSArrayBufferError(
    self,
    message: str,
    *,
    byte_length: int,
    max_byte_length: int | None,
)

Raised when a byte length is out of bounds.

Attributes

Name	Description
byte_length
max_byte_length

jstypes.ItemSizeJSArrayBufferError

jstypes.ItemSizeJSArrayBufferError(
    self,
    message: str,
    *,
    itemsize: int,
    byte_offset: int,
    byte_length: int | None,
)

Raised when a byte offset or length is not divisible by itemsize.

Attributes

Name	Description
byte_length
byte_offset
itemsize

jstypes.JSInt8Array

jstypes.JSInt8Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSUint8Array

jstypes.JSUint8Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSUint8ClampedArray

jstypes.JSUint8ClampedArray(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSInt16Array

jstypes.JSInt16Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSUint16Array

jstypes.JSUint16Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSInt32Array

jstypes.JSInt32Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSUint32Array

jstypes.JSUint32Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSBigInt64Array

jstypes.JSBigInt64Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSBigUint64Array

jstypes.JSBigUint64Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSFloat16Array

jstypes.JSFloat16Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSFloat32Array

jstypes.JSFloat32Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSFloat64Array

jstypes.JSFloat64Array(
    self,
    backing_buffer: JSArrayBufferT,
    item_offset: int = 0,
    item_length: int | None = None,
    readonly: Literal[True] | None = None,
)

jstypes.JSSharedArrayBuffer

jstypes.JSSharedArrayBuffer(self, buffer_id: SharedArrayBufferId)

Python equivalent of JavaScript’s SharedArrayBuffer.

This type exists for completeness, and to allow these values to be round-tripped back to V8 if they ever do occur.

Much like JSArrayBufferTransfer, this type should not occur in practice. It currently does nothing other than hold an integer buffer_id. V8 does not seem to allow SharedArrayBuffer objects to be serialized by Node.JS’s v8.serialize() API.

Attributes

Name	Description
buffer_id

jstypes.JSArrayBufferTransfer

jstypes.JSArrayBufferTransfer(self, transfer_id: TransferId)

A non-standard V8 type representing an ArrayBuffer being transferred.

This type exists for completeness, but should not occur in data serialized by JavaScript runtimes using APIs like Node.JS’s v8.serialize(). Transferring ArrayBuffers is an internal activity in V8 and it’s not possible to access this type from JavaScript code running in V8, so it can’t be serialized from JavaScript code.

Attributes

Name	Description
transfer_id

ArrayBuffer, TypedArray, DataView

jstypes.JSArrayBuffer

Parameters

Attributes

Methods

close

resize

jstypes.create_view

Returns

Examples

jstypes.JSTypedArray

See Also

Attributes

Methods

from_bytes

See Also

get_buffer

Examples

get_buffer_as_memoryview

Parameters

jstypes.JSDataView

Examples

Attributes

Methods

from_bytes

See Also

get_buffer

get_buffer_as_memoryview

Parameters

jstypes.DataViewBuffer

See Also

Attributes

Methods

get_bigint64

get_biguint64

get_float16

get_float32

get_float64

get_int16

get_int32

get_int8

get_uint16

get_uint32

get_uint8

read

set_bigint64

set_biguint64

set_float16

set_float32

set_float64

set_int16

set_int32

set_int8

set_uint16

set_uint32

set_uint8

write

jstypes.DataFormat

Attributes

Methods

cast

resolve

Parameters

Returns

Raises

Examples

jstypes.DataType

Attributes

Methods

cast

jstypes.ArrayBufferViewStructFormat

Examples

Attributes

jstypes.JSArrayBufferError

jstypes.BoundsJSArrayBufferError

Attributes

jstypes.ByteLengthJSArrayBufferError

Attributes

jstypes.ItemSizeJSArrayBufferError

Attributes