tenso package

Subpackages

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.cache module

TensoCache: In-process tensor cache backed by shared memory.

Provides an embeddable, tensor-aware cache with mutable entries, zero-copy reads, LRU eviction, TTL, in-place updates, and metadata inspection without deserialization.

Memory Layout (single SHM segment):

┌──────────────────────────────────────────┐ │ POOL HEADER (4096 bytes) │ │ magic | version | pool_size | max_entries│ │ active_entries | free_bytes | watermark │ │ lru_head | lru_tail | free_list_head │ │ lock_word | generation | hits | misses │ ├──────────────────────────────────────────┤ │ ENTRY INDEX TABLE (max_entries × 256 b) │ ├──────────────────────────────────────────┤ │ DATA REGION (rest of pool) │ │ 64-byte aligned Tenso packets + free │ └──────────────────────────────────────────┘

class tenso.cache.TensoCache(max_memory='256MB', name=None, create=True)[source]

Bases: object

In-process tensor cache backed by a single shared memory pool.

Supports mutable entries, zero-copy reads, LRU eviction, TTL, in-place updates, and metadata inspection without deserialization.

Example:

import numpy as np
from tenso import TensoCache

with TensoCache("64MB") as cache:
    cache.put("weights", np.random.randn(1000, 1000).astype(np.float32))
    arr = cache.get("weights")        # zero-copy view into SHM
    print(cache.info("weights"))       # metadata without deserialization
    print(cache.stats)                 # hit/miss counts, memory usage
clear()[source]

Remove all entries from the cache.

close()[source]

Close access to the shared memory pool.

delete(key)[source]

Delete an entry from the cache.

Parameters:

key (str) – Cache key.

Returns:

True if the key was found and deleted.

Return type:

bool

get(key, copy=False, device=None)[source]

Retrieve a tensor from the cache.

Parameters:

  • key (str) – Cache key.

  • copy (bool) – If True, return a writeable copy. Default returns zero-copy view.

  • device (str, optional) – Target device for the result. Format: “framework” or “framework:device_spec” (e.g. “torch”, “torch:cuda:0”, “jax”, “cupy:0”). When set, the result is converted from numpy. Implies copy (SHM buffer cannot be shared with frameworks).

Returns:

The tensor, or None if not found or expired.

Return type:

Optional[np.ndarray or framework tensor]

info(key)[source]

Get metadata about a cached entry without deserializing.

Parameters:

key (str) – Cache key.

Returns:

Dictionary with ‘shape’, ‘dtype’, ‘ndim’, ‘size_bytes’, ‘ttl’, ‘age’, or None if key not found.

Return type:

Optional[dict]

keys()[source]

Return a list of all active (non-expired) keys.

Return type:

list

property name: str
put(key, tensor, ttl=None, quantize=None)[source]

Store a tensor in the cache.

Parameters:

  • key (str) – Cache key (max 128 bytes UTF-8).

  • tensor (np.ndarray, QuantizedTensor, or framework tensor) – Tensor to store. PyTorch, JAX, and CuPy tensors are automatically converted to numpy before caching.

  • ttl (float, optional) – Time-to-live in seconds. None means no expiry.

  • quantize (str, optional) – Quantization dtype (‘qint8’, ‘quint8’, ‘qint4’, ‘quint4’).

Returns:

Number of bytes written.

Return type:

int

Raises:

  • ValueError – If key exceeds 128 bytes.

  • MemoryError – If pool is exhausted after eviction attempts.

property stats: dict

Cache statistics.

Returns:

Keys: entries, max_entries, pool_size, used_bytes, free_bytes, data_region_size, hits, misses, hit_rate

Return type:

dict

Request destruction of the shared memory segment.

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.config.QDTYPE_QINT4 = 18

4-bit signed quantized (packed, 2 per byte) (int)

tenso.config.QDTYPE_QINT8 = 16

8-bit signed quantized (int)

tenso.config.QDTYPE_QUINT4 = 19

4-bit unsigned quantized (packed, 2 per byte) (int)

tenso.config.QDTYPE_QUINT8 = 17

8-bit unsigned quantized (int)

tenso.config.QUANT_PER_CHANNEL = 1

One scale/zero_point per channel slice (int)

tenso.config.QUANT_PER_GROUP = 2

One scale/zero_point per group of elements (int)

tenso.config.QUANT_PER_TENSOR = 0

Single scale/zero_point for the entire tensor (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

Raises:

  • ValueError – If packet is invalid or integrity check fails.

  • EOFError – If stream ends prematurely.

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

Serialize a GPU tensor directly to an I/O stream using pinned memory staging.

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.quantize module

Quantized Tensor support for Tenso.

Provides QuantizedTensor for 4-bit and 8-bit quantized representations with per-tensor, per-channel, and per-group quantization schemes.

class tenso.quantize.QuantizedTensor(data, scales, zero_points, shape, dtype_code, quant_scheme=0, group_size=0)[source]

Bases: object

A quantized tensor with scale/zero_point metadata.

dequantize()[source]

Reconstruct a float32 approximation of the original tensor.

Return type:

ndarray

property dtype_name: str
property is_4bit: bool
property is_signed: bool
property nbytes: int
classmethod quantize(tensor, dtype, scheme='per_tensor', group_size=0, axis=0)[source]

Quantize a float tensor.

Parameters:

  • tensor (np.ndarray) – Input tensor (will be converted to float32).

  • dtype (str) – Target quantized dtype name: “qint8”, “quint8”, “qint4”, “quint4”.

  • scheme (str) – Quantization scheme: “per_tensor”, “per_channel”, “per_group”.

  • group_size (int) – Group size for per_group scheme.

  • axis (int) – Channel axis for per_channel scheme.

Return type:

QuantizedTensor

tenso.ray module

Ray Integration for Tenso.

Registers Tenso as a custom serializer for Ray, replacing pickle-based serialization with zero-copy tensor transfer for numpy arrays and optionally PyTorch tensors.

Usage:

import ray
from tenso.ray import register

ray.init()
register()  # Register Tenso as the serializer for numpy arrays

# All ray.put/get operations now use Tenso for numpy arrays
ref = ray.put(np.zeros((1000, 1000)))
arr = ray.get(ref)  # Deserialized via Tenso (46x less CPU than pickle)

# Works transparently with remote functions and actors
@ray.remote
def process(tensor):
    return tensor.mean()

ray.get(process.remote(np.random.randn(1000, 1000)))
tenso.ray.register(include_torch=False, include_jax=False)[source]

Register Tenso as the custom serializer for tensor types in Ray.

After calling this, all ray.put(), ray.get(), remote function arguments, and actor method arguments involving registered types will be serialized using Tenso instead of pickle.

Parameters:

  • include_torch (bool, default False) – Also register serializers for torch.Tensor. Requires PyTorch.

  • include_jax (bool, default False) – Also register serializers for JAX arrays. Requires JAX.

Raises:

ImportError – If ray is not installed or if optional frameworks are not available.

Return type:

None

Examples

>>> import ray
>>> from tenso.ray import register
>>> ray.init()
>>> register()
>>> ref = ray.put(np.zeros((100, 100)))
>>> arr = ray.get(ref)
tenso.ray.unregister()[source]

Remove Tenso serializers from Ray, reverting to default pickle behavior.

This deregisters all types that were registered by register().

Return type:

None

tenso.shm module

Shared Memory Transport for Tenso.

This module provides high-performance Inter-Process Communication (IPC) capabilities using POSIX Shared Memory. It allows zero-copy transfer of tensors between local processes.

class tenso.shm.TensoShm(name, create=False, size=0)[source]

Bases: object

A wrapper around SharedMemory for Tenso-protocol objects.

Example:

# Writer
ary = np.random.rand(100, 100)
with TensoShm.create_from("my_tensor", ary) as shm:
    print("Wrote to SHM")
    input("Press enter to cleanup...")

# Reader
with TensoShm("my_tensor") as shm:
    ary = shm.get()
    print(ary.shape)
property buffer: memoryview
close()[source]

Close access to the shared memory.

classmethod create_from(name, obj, check_integrity=False, compress=False, alignment=64)[source]

Create a new SharedMemory segment sized to fit the object and write it.

Return type:

Self

get()[source]

Deserialize the object currently in shared memory.

Returns a zero-copy view into the shared memory buffer. The view remains valid as long as the underlying SHM segment has not been unlinked.

Returns:

The reconstructed object (zero-copy view).

Return type:

Optional[Union[np.ndarray, dict]]

property name: str
put(obj, check_integrity=False, compress=False, alignment=64)[source]

Serialize an object directly into the shared memory.

Returns:

Number of bytes written.

Return type:

int

property size: int

Request that the shared memory be destroyed.

tenso.tenso_rs module

tenso.tenso_rs.dump_to_buffer_rs(array, buffer, check_integrity=False, compress=False, alignment=64)
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.

class tenso.QuantizedTensor(data, scales, zero_points, shape, dtype_code, quant_scheme=0, group_size=0)[source]

Bases: object

A quantized tensor with scale/zero_point metadata.

dequantize()[source]

Reconstruct a float32 approximation of the original tensor.

Return type:

ndarray

property dtype_name: str
property is_4bit: bool
property is_signed: bool
property nbytes: int
classmethod quantize(tensor, dtype, scheme='per_tensor', group_size=0, axis=0)[source]

Quantize a float tensor.

Parameters:

  • tensor (np.ndarray) – Input tensor (will be converted to float32).

  • dtype (str) – Target quantized dtype name: “qint8”, “quint8”, “qint4”, “quint4”.

  • scheme (str) – Quantization scheme: “per_tensor”, “per_channel”, “per_group”.

  • group_size (int) – Group size for per_group scheme.

  • axis (int) – Channel axis for per_channel scheme.

Return type:

QuantizedTensor

class tenso.TensoCache(max_memory='256MB', name=None, create=True)[source]

Bases: object

In-process tensor cache backed by a single shared memory pool.

Supports mutable entries, zero-copy reads, LRU eviction, TTL, in-place updates, and metadata inspection without deserialization.

Example:

import numpy as np
from tenso import TensoCache

with TensoCache("64MB") as cache:
    cache.put("weights", np.random.randn(1000, 1000).astype(np.float32))
    arr = cache.get("weights")        # zero-copy view into SHM
    print(cache.info("weights"))       # metadata without deserialization
    print(cache.stats)                 # hit/miss counts, memory usage
clear()[source]

Remove all entries from the cache.

close()[source]

Close access to the shared memory pool.

delete(key)[source]

Delete an entry from the cache.

Parameters:

key (str) – Cache key.

Returns:

True if the key was found and deleted.

Return type:

bool

get(key, copy=False, device=None)[source]

Retrieve a tensor from the cache.

Parameters:

  • key (str) – Cache key.

  • copy (bool) – If True, return a writeable copy. Default returns zero-copy view.

  • device (str, optional) – Target device for the result. Format: “framework” or “framework:device_spec” (e.g. “torch”, “torch:cuda:0”, “jax”, “cupy:0”). When set, the result is converted from numpy. Implies copy (SHM buffer cannot be shared with frameworks).

Returns:

The tensor, or None if not found or expired.

Return type:

Optional[np.ndarray or framework tensor]

info(key)[source]

Get metadata about a cached entry without deserializing.

Parameters:

key (str) – Cache key.

Returns:

Dictionary with ‘shape’, ‘dtype’, ‘ndim’, ‘size_bytes’, ‘ttl’, ‘age’, or None if key not found.

Return type:

Optional[dict]

keys()[source]

Return a list of all active (non-expired) keys.

Return type:

list

property name: str
put(key, tensor, ttl=None, quantize=None)[source]

Store a tensor in the cache.

Parameters:

  • key (str) – Cache key (max 128 bytes UTF-8).

  • tensor (np.ndarray, QuantizedTensor, or framework tensor) – Tensor to store. PyTorch, JAX, and CuPy tensors are automatically converted to numpy before caching.

  • ttl (float, optional) – Time-to-live in seconds. None means no expiry.

  • quantize (str, optional) – Quantization dtype (‘qint8’, ‘quint8’, ‘qint4’, ‘quint4’).

Returns:

Number of bytes written.

Return type:

int

Raises:

  • ValueError – If key exceeds 128 bytes.

  • MemoryError – If pool is exhausted after eviction attempts.

property stats: dict

Cache statistics.

Returns:

Keys: entries, max_entries, pool_size, used_bytes, free_bytes, data_region_size, hits, misses, hit_rate

Return type:

dict

Request destruction of the shared memory segment.

class tenso.TensoShm(name, create=False, size=0)[source]

Bases: object

A wrapper around SharedMemory for Tenso-protocol objects.

Example:

# Writer
ary = np.random.rand(100, 100)
with TensoShm.create_from("my_tensor", ary) as shm:
    print("Wrote to SHM")
    input("Press enter to cleanup...")

# Reader
with TensoShm("my_tensor") as shm:
    ary = shm.get()
    print(ary.shape)
property buffer: memoryview
close()[source]

Close access to the shared memory.

classmethod create_from(name, obj, check_integrity=False, compress=False, alignment=64)[source]

Create a new SharedMemory segment sized to fit the object and write it.

Return type:

Self

get()[source]

Deserialize the object currently in shared memory.

Returns a zero-copy view into the shared memory buffer. The view remains valid as long as the underlying SHM segment has not been unlinked.

Returns:

The reconstructed object (zero-copy view).

Return type:

Optional[Union[np.ndarray, dict]]

property name: str
put(obj, check_integrity=False, compress=False, alignment=64)[source]

Serialize an object directly into the shared memory.

Returns:

Number of bytes written.

Return type:

int

property size: int

Request that the shared memory be destroyed.

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:

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.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.

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.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

Raises:

  • ValueError – If packet is invalid or integrity check fails.

  • EOFError – If stream ends prematurely.

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