ArrayBuffer, TypedArray, DataView
Python equivalents of JavaScript’s binary data buffer types.
jstypes.JSArrayBuffer
jstypes.JSArrayBuffer(self, data=None, byte_length=None, *, max_byte_length=None, resizable=None, copy_data=None, readonly=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
dataas 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)
Resize the buffer, within the max_byte_length limit.
jstypes.create_view
jstypes.create_view(buffer, format, *, byte_offset=0, byte_length=None, readonly=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
| 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, item_offset=0, item_length=None, readonly=None)
Python equivalent of JavaScript’s TypedArray.
As in JavaScript, this is an abstract type which cannot be instantiated.
See Also
create_view()-
Create a (subtype) instance of
JSTypedArray. JS*Arraytypes-
This module contains many subtypes for specific data formats, e.g.
JSUint8Array.
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, *, byte_offset=0, byte_length=None, readonly=None)
Create a view, validating byte offsets as JavaScript does.
See Also
create_view()- Create a view without specifying the view class.
get_buffer
jstypes.JSTypedArray.get_buffer(readonly=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 128get_buffer_as_memoryview
jstypes.JSTypedArray.get_buffer_as_memoryview(readonly=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, item_offset=0, item_length=None, readonly=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, *, byte_offset=0, byte_length=None, readonly=None)
Create a view, validating byte offsets as JavaScript does.
See Also
create_view()- Create a view without specifying the view class.
get_buffer
jstypes.JSDataView.get_buffer(readonly=None)
Access the view’s region of .backing_buffer as a DataViewBuffer.
get_buffer_as_memoryview
jstypes.JSDataView.get_buffer_as_memoryview(readonly=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)
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
.bufferon exit. - This is a Buffer which exposes its
.bufferas a memoryview.
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.
See Also
- Python’s
structmodule - This is the builtin way to read/write binary data with Python.
- NumPy Structured Arrays
- NumPy provides Structured Arrays which can read/write structured binary data in bulk.
Attributes
| Name | Description |
|---|---|
| buffer | The memoryview this view is operating on. |
Methods
get_bigint64
jstypes.DataViewBuffer.get_bigint64(byte_offset, little_endian=False)
get_biguint64
jstypes.DataViewBuffer.get_biguint64(byte_offset, little_endian=False)
get_float16
jstypes.DataViewBuffer.get_float16(byte_offset, little_endian=False)
get_float32
jstypes.DataViewBuffer.get_float32(byte_offset, little_endian=False)
get_float64
jstypes.DataViewBuffer.get_float64(byte_offset, little_endian=False)
get_int16
jstypes.DataViewBuffer.get_int16(byte_offset, little_endian=False)
get_int32
jstypes.DataViewBuffer.get_int32(byte_offset, little_endian=False)
get_int8
jstypes.DataViewBuffer.get_int8(byte_offset)
get_uint16
jstypes.DataViewBuffer.get_uint16(byte_offset, little_endian=False)
get_uint32
jstypes.DataViewBuffer.get_uint32(byte_offset, little_endian=False)
get_uint8
jstypes.DataViewBuffer.get_uint8(byte_offset)
read
jstypes.DataViewBuffer.read(struct_format, byte_offset)
set_bigint64
jstypes.DataViewBuffer.set_bigint64(byte_offset, value, little_endian=False)
set_biguint64
jstypes.DataViewBuffer.set_biguint64(byte_offset, value, little_endian=False)
set_float16
jstypes.DataViewBuffer.set_float16(byte_offset, value, little_endian=False)
set_float32
jstypes.DataViewBuffer.set_float32(byte_offset, value, little_endian=False)
set_float64
jstypes.DataViewBuffer.set_float64(byte_offset, value, little_endian=False)
set_int16
jstypes.DataViewBuffer.set_int16(byte_offset, value, little_endian=False)
set_int32
jstypes.DataViewBuffer.set_int32(byte_offset, value, little_endian=False)
set_int8
jstypes.DataViewBuffer.set_int8(byte_offset, value)
set_uint16
jstypes.DataViewBuffer.set_uint16(byte_offset, value, little_endian=False)
set_uint32
jstypes.DataViewBuffer.set_uint32(byte_offset, value, little_endian=False)
set_uint8
jstypes.DataViewBuffer.set_uint8(byte_offset, value)
write
jstypes.DataViewBuffer.write(struct_format, byte_offset, *values)
jstypes.DataFormat
jstypes.DataFormat(self, byte_length, data_type, format)
A struct format for a specific data type and precision.
Attributes
| Name | Description |
|---|---|
| byte_length | |
| data_type | |
| format |
Methods
| Name | Description |
|---|---|
| resolve | Find the struct format on this platform with a given size and data type. |
resolve
jstypes.DataFormat.resolve(data_type, byte_length)
Find the struct format on this platform with a given size and data type.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
data_type |
DataType | 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
| Type | Description |
|---|---|
A DataFormat matching the parameters. |
Raises
| 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. |
jstypes.ArrayBufferViewStructFormat
jstypes.ArrayBufferViewStructFormat(self, value)
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 ArrayBufferViewTagResolve 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, byte_offset, byte_length, buffer_byte_length)
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, *, byte_length, max_byte_length)
Raised when a byte length is out of bounds.
Attributes
| Name | Description |
|---|---|
| byte_length | |
| max_byte_length |
jstypes.ItemSizeJSArrayBufferError
jstypes.ItemSizeJSArrayBufferError(self, message, *, itemsize, byte_offset, byte_length)
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, item_offset=0, item_length=None, readonly=None)
jstypes.JSUint8Array
jstypes.JSUint8Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSUint8ClampedArray
jstypes.JSUint8ClampedArray(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSInt16Array
jstypes.JSInt16Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSUint16Array
jstypes.JSUint16Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSInt32Array
jstypes.JSInt32Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSUint32Array
jstypes.JSUint32Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSBigInt64Array
jstypes.JSBigInt64Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSBigUint64Array
jstypes.JSBigUint64Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSFloat16Array
jstypes.JSFloat16Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSFloat32Array
jstypes.JSFloat32Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSFloat64Array
jstypes.JSFloat64Array(self, backing_buffer, item_offset=0, item_length=None, readonly=None)
jstypes.JSArrayBufferTransfer
jstypes.JSArrayBufferTransfer(self, transfer_id)
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 |