tenso package¶

Subpackages¶

tenso.grpc package
- Module contents

Submodules¶

tenso.async_core module¶

Async I/O Support for Tenso.

Provides coroutines for reading and writing Tenso packets using asyncio stream readers and writers.

async tenso.async_core.aread_stream(reader)[source]¶

Asynchronously read a Tenso packet from a StreamReader.

Parameters:: reader (asyncio.StreamReader) – The stream reader source.
Returns:: The deserialized array.
Return type:: Optional[np.ndarray]

async tenso.async_core.awrite_stream(tensor, writer, strict=False, check_integrity=False)[source]¶

Asynchronously write a tensor to a StreamWriter.

Parameters:

tensor (np.ndarray) – The array to write.
writer (asyncio.StreamWriter) – The stream writer destination.
strict (bool, default False) – Strict contiguous check.
check_integrity (bool, default False) – Include checksum.

Return type:

None

tenso.config module¶

Configuration and Protocol Constants for Tenso.

This module defines the binary protocol version, magic numbers, memory alignment requirements, and feature flags used across the library.

tenso.config.FLAG_ALIGNED = 1¶: Packet uses 64-byte alignment (int)

tenso.config.FLAG_BUNDLE = 16¶: Packet contains a collection (dict) of tensors (int)

tenso.config.FLAG_COMPRESSION = 4¶: Packet body is compressed using LZ4 (int)

tenso.config.FLAG_CUST_ALIGN = 128¶: Packet uses custom alignment (exponent byte follows shape) (int)

tenso.config.FLAG_INTEGRITY = 2¶: Packet includes an 8-byte XXH3 checksum footer (int)

tenso.config.FLAG_SPARSE = 8¶: Packet contains a Sparse COO tensor (int)

tenso.config.FLAG_SPARSE_CSC = 64¶: Packet contains a Sparse CSC tensor (int)

tenso.config.FLAG_SPARSE_CSR = 32¶: Packet contains a Sparse CSR tensor (int)

tenso.config.MAX_ELEMENTS = 1000000000¶: Maximum elements per tensor (int)

tenso.config.MAX_NDIM = 32¶: Maximum number of dimensions (int)

tenso.core module¶

Core Serialization Engine for Tenso.

This module provides high-performance functions for converting NumPy arrays, Sparse matrices, and Dictionaries to the Tenso binary format. It supports zero-copy memory mapping, LZ4 compression, and XXH3 integrity verification.

tenso.core.dump(tensor, fp, strict=False, check_integrity=False)[source]¶

Serialize a tensor and write it to an open binary file.

Optimized for large arrays by writing the complete packet in a single system call instead of multiple small writes.

Parameters:

tensor (np.ndarray) – The array to serialize.
fp (BinaryIO) – Open binary file object.
strict (bool, default False) – If True, raises error for non-contiguous arrays.
check_integrity (bool, default False) – If True, includes XXH3 hash for verification.

Return type:

None

tenso.core.dumps(tensor, strict=False, check_integrity=False, compress=False, alignment=64)[source]¶

Serialize an object (Array, Sparse Matrix, or Dict) to a Tenso packet.

Parameters:

tensor (Any) – The object to serialize.
strict (bool, default False) – If True, raises error for non-contiguous arrays.
check_integrity (bool, default False) – If True, includes XXH3 hash for verification.
compress (bool, default False) – If True, uses LZ4 compression on the data body.
alignment (int, default 64) – Memory alignment boundary (must be power of 2).

Returns:

A view of the complete Tenso packet bytes.

Return type:

memoryview

tenso.core.iter_dumps(tensor, strict=False, check_integrity=False)[source]¶

Vectored serialization: Yields packet parts to avoid memory copies.

Parameters:

tensor (np.ndarray) – The array to serialize.
strict (bool, default False) – If True, raises ValueError for non-contiguous arrays.
check_integrity (bool, default False) – If True, includes an XXH3 checksum footer.

Yields:

Union[bytes, memoryview] – Sequential chunks of the Tenso packet.

Return type:

Generator[Union[bytes, memoryview], None, None]

tenso.core.load(fp, mmap_mode=False, copy=False)[source]¶

Deserialize an object from an open binary file.

Parameters:

fp (BinaryIO) – Open binary file object.
mmap_mode (bool, default False) – Use memory mapping for large files.
copy (bool, default False) – Return a writeable copy.

Returns:

The reconstructed object.

Return type:

Any

tenso.core.loads(data, copy=False)[source]¶

Deserialize a Tenso packet into its original Python object.

Parameters:

data (Union[bytes, bytearray, memoryview, np.ndarray, mmap.mmap]) – The raw Tenso packet data.
copy (bool, default False) – If True, returns a writeable copy. Otherwise returns a read-only view.

Returns:

The reconstructed NumPy array, Dictionary, or Sparse Matrix.

Return type:

Any

tenso.core.read_stream(source)[source]¶

Read and deserialize an object from a stream source with DoS protection.

This function supports streaming deserialization for dense NumPy arrays, multi-tensor bundles (dictionaries), and sparse matrices (COO, CSR, CSC). It avoids loading the entire packet into memory before parsing, making it suitable for large-scale data ingestion.

Parameters:

source (Any) – Stream source to read from (must support .read() or .recv()).

Returns:

The deserialized NumPy array, Sparse matrix, or Dictionary. Returns None if the stream ended before any data was read.

Return type:

Optional[Any]

Raises:

ValueError – If the packet is invalid or exceeds security limits.
EOFError – If the stream ends prematurely during reading.
ImportError – If scipy is missing during sparse matrix deserialization.

tenso.core.write_stream(tensor, dest, strict=False, check_integrity=False)[source]¶

Write a tensor to a destination using memory-efficient streaming. Supports both file-like objects (.write) and sockets (.sendall).

Parameters:

tensor (np.ndarray) – The array to serialize.
dest (Any) – Destination supporting .write() or .sendall().
strict (bool, default False) – Strict contiguous check.
check_integrity (bool, default False) – Include integrity hash.

Returns:

The total number of bytes written.

Return type:

int

tenso.fastapi module¶

FastAPI Integration for Tenso.

Allows zero-copy streaming of tensors from API endpoints and high-performance ingestion of incoming Tenso packets.

class tenso.fastapi.TensoResponse(tensor, filename=None, strict=False, check_integrity=False, **kwargs)[source]¶

Bases: StreamingResponse

FastAPI Response for zero-copy tensor streaming.

Parameters:

tensor (np.ndarray) – The tensor to stream.
filename (str, optional) – Filename for Content-Disposition header.
strict (bool, default False) – Strict contiguous check.
check_integrity (bool, default False) – Include checksum.
**kwargs – Passed to StreamingResponse.

async tenso.fastapi.get_tenso_data(request)[source]¶

Dependency to extract a Tenso object from an incoming FastAPI Request.

Parameters:: request (Request) – The FastAPI request object.
Returns:: The deserialized array, bundle, or sparse matrix.
Return type:: Any
Raises:: HTTPException – If the payload is invalid or headers are missing.

tenso.gpu module¶

GPU Acceleration for Tenso.

Implements fast transfers between device memory (CuPy/PyTorch/JAX) and Tenso streams using pinned host memory.

tenso.gpu.read_to_device(source, device_id=0)[source]¶

Read a Tenso packet from a stream directly into GPU memory.

Parameters:

source (Any) – Stream-like object (file, socket).
device_id (int, default 0) – The target GPU device ID.

Returns:

The GPU tensor.

Return type:

Any

tenso.gpu.write_from_device(tensor, dest, check_integrity=False)[source]¶

Serialize a GPU tensor directly to an I/O stream.

Parameters:

tensor (Any) – A GPU-resident array (CuPy, PyTorch, or JAX).
dest (Any) – Destination with .write() method.
check_integrity (bool, default False) – Include XXH3 checksum.

Returns:

Number of bytes written.

Return type:

int

tenso.tenso_rs module¶

tenso.tenso_rs.dump_to_fd_rs(array, fd, check_integrity=False, compress=False, alignment=64)¶

tenso.tenso_rs.dumps_rs(array, check_integrity=False, compress=False, alignment=64)¶

tenso.tenso_rs.get_packet_info_rs(data)¶

tenso.tenso_rs.loads_rs(data)¶

tenso.utils module¶

tenso.utils.get_packet_info(data)[source]¶

Extract metadata from a Tenso packet without deserializing the full tensor.

This function parses the header of a Tenso packet to provide information about the tensor’s properties, such as dtype, shape, and flags.

Parameters:

data (bytes) – The raw bytes of the Tenso packet.

Returns:

A dictionary containing packet information with keys: - ‘version’: Protocol version - ‘dtype’: NumPy dtype of the tensor - ‘shape’: Tuple representing tensor shape - ‘ndim’: Number of dimensions - ‘flags’: Raw flags byte - ‘aligned’: Boolean indicating if packet uses alignment - ‘integrity_protected’: Boolean indicating if integrity check is enabled - ‘total_elements’: Total number of elements in the tensor - ‘data_size_bytes’: Size of the tensor data in bytes

Return type:

dict

Raises:

ValueError – If the packet is too short or invalid.
Uses Rust implementation for performance if available, otherwise falls back to Python. –

tenso.utils.is_aligned(data, alignment=64)[source]¶

Check if the given bytes data is aligned to the specified boundary.

Parameters:

data (bytes) – The bytes object to check alignment for.
alignment (int, optional) – The alignment boundary in bytes. Default is 64.

Returns:

True if the data is aligned, False otherwise.

Return type:

bool

Module contents¶

Tenso: High-performance tensor serialization and streaming.

This package provides efficient serialization, deserialization, and streaming of numpy arrays (tensors), with optional support for asynchronous and GPU-accelerated workflows.

Main API:

dumps, loads, dump, load: Core serialization/deserialization functions.
read_stream, write_stream: Stream-based I/O.
aread_stream: Async stream reader (if available).
read_to_device: GPU direct transfer (if available).
get_packet_info, is_aligned: Utilities for packet inspection and alignment.

async tenso.aread_stream(reader)[source]¶

Asynchronously read a Tenso packet from a StreamReader.

Parameters:: reader (asyncio.StreamReader) – The stream reader source.
Returns:: The deserialized array.
Return type:: Optional[np.ndarray]

tenso.dump(tensor, fp, strict=False, check_integrity=False)[source]¶

Serialize a tensor and write it to an open binary file.

Optimized for large arrays by writing the complete packet in a single system call instead of multiple small writes.

Parameters:

tensor (np.ndarray) – The array to serialize.
fp (BinaryIO) – Open binary file object.
strict (bool, default False) – If True, raises error for non-contiguous arrays.
check_integrity (bool, default False) – If True, includes XXH3 hash for verification.

Return type:

None

tenso.dumps(tensor, strict=False, check_integrity=False, compress=False, alignment=64)[source]¶

Serialize an object (Array, Sparse Matrix, or Dict) to a Tenso packet.

Parameters:

tensor (Any) – The object to serialize.
strict (bool, default False) – If True, raises error for non-contiguous arrays.
check_integrity (bool, default False) – If True, includes XXH3 hash for verification.
compress (bool, default False) – If True, uses LZ4 compression on the data body.
alignment (int, default 64) – Memory alignment boundary (must be power of 2).

Returns:

A view of the complete Tenso packet bytes.

Return type:

memoryview

tenso.get_packet_info(data)[source]¶

Extract metadata from a Tenso packet without deserializing the full tensor.

This function parses the header of a Tenso packet to provide information about the tensor’s properties, such as dtype, shape, and flags.

Parameters:

data (bytes) – The raw bytes of the Tenso packet.

Returns:

Return type:

dict

Raises:

ValueError – If the packet is too short or invalid.
Uses Rust implementation for performance if available, otherwise falls back to Python. –

tenso.is_aligned(data, alignment=64)[source]¶

Check if the given bytes data is aligned to the specified boundary.

Parameters:

data (bytes) – The bytes object to check alignment for.
alignment (int, optional) – The alignment boundary in bytes. Default is 64.

Returns:

True if the data is aligned, False otherwise.

Return type:

bool

tenso.iter_dumps(tensor, strict=False, check_integrity=False)[source]¶

Vectored serialization: Yields packet parts to avoid memory copies.

Parameters:

tensor (np.ndarray) – The array to serialize.
strict (bool, default False) – If True, raises ValueError for non-contiguous arrays.
check_integrity (bool, default False) – If True, includes an XXH3 checksum footer.

Yields:

Union[bytes, memoryview] – Sequential chunks of the Tenso packet.

Return type:

Generator[Union[bytes, memoryview], None, None]

tenso.load(fp, mmap_mode=False, copy=False)[source]¶

Deserialize an object from an open binary file.

Parameters:

fp (BinaryIO) – Open binary file object.
mmap_mode (bool, default False) – Use memory mapping for large files.
copy (bool, default False) – Return a writeable copy.

Returns:

The reconstructed object.

Return type:

Any

tenso.loads(data, copy=False)[source]¶

Deserialize a Tenso packet into its original Python object.

Parameters:

data (Union[bytes, bytearray, memoryview, np.ndarray, mmap.mmap]) – The raw Tenso packet data.
copy (bool, default False) – If True, returns a writeable copy. Otherwise returns a read-only view.

Returns:

The reconstructed NumPy array, Dictionary, or Sparse Matrix.

Return type:

Any

tenso.read_stream(source)[source]¶

Read and deserialize an object from a stream source with DoS protection.

Parameters:

source (Any) – Stream source to read from (must support .read() or .recv()).

Returns:

The deserialized NumPy array, Sparse matrix, or Dictionary. Returns None if the stream ended before any data was read.

Return type:

Optional[Any]

Raises:

ValueError – If the packet is invalid or exceeds security limits.
EOFError – If the stream ends prematurely during reading.
ImportError – If scipy is missing during sparse matrix deserialization.

tenso.read_to_device(source, device_id=0)[source]¶

Read a Tenso packet from a stream directly into GPU memory.

Parameters:

source (Any) – Stream-like object (file, socket).
device_id (int, default 0) – The target GPU device ID.

Returns:

The GPU tensor.

Return type:

Any

tenso.write_stream(tensor, dest, strict=False, check_integrity=False)[source]¶

Write a tensor to a destination using memory-efficient streaming. Supports both file-like objects (.write) and sockets (.sendall).

Parameters:

tensor (np.ndarray) – The array to serialize.
dest (Any) – Destination supporting .write() or .sendall().
strict (bool, default False) – Strict contiguous check.
check_integrity (bool, default False) – Include integrity hash.

Returns:

The total number of bytes written.

Return type:

int