Skip to main content

edgefirst-tensor

Zero-copy tensor memory for edge AI inference pipelines — DMA-BUF, IOSurface, AHardwareBuffer, OpenGL PBO, POSIX shared memory and heap behind one Python API.

PyPI License

Part of the EdgeFirst HAL

edgefirst-tensor is one of five Python packages built from the EdgeFirst Hardware Abstraction Layer.

The EdgeFirstAI/hal repository is the home for all of them — source, issue tracker, architecture documentation and release notes.

Package Provides
edgefirst-tensor Zero-copy tensor allocation and host/GPU/CUDA mapping (this package)
edgefirst-codec JPEG and PNG decoding directly into pre-allocated tensors
edgefirst-image GPU-accelerated colour conversion, resize, letterbox, tiling and drawing
edgefirst-decoder YOLO and ModelPack output decoding
edgefirst-tracker ByteTrack multi-object tracking

This package is the foundation the other four build on; installing any of them installs this one.

Installation

pip install edgefirst-tensor

Requires Python 3.8 or newer and NumPy. Wheels are published for Linux (x86_64, aarch64), macOS (arm64), and Windows (x86_64).

The _codec, _image, _decoder and _tracker extensions locate libedgefirst_tensor.so via DT_RUNPATH=$ORIGIN/../tensor. That assumes every edgefirst.* package lands in the same site-packages tree, which pip normally guarantees. A split layout (pip install --target, some vendored trees) will fail at import with libedgefirst_tensor.so.0: cannot open shared object file. On Windows the library is edgefirst_tensor.dll in that same edgefirst/tensor/ directory and there is no rpath: each sibling package's __init__.py registers the directory with os.add_dll_directory() before loading its extension, because Python 3.8+ does not consult PATH for extension-module DLLs.

Packages install under the PEP 420 edgefirst.* namespace, so imports are edgefirst.tensor, edgefirst.codec, and so on. No package ships an edgefirst/__init__.py — a single one would shadow the namespace and hide its siblings.

Building from source

edgefirst-tensor carries the shared libedgefirst_tensor the codec, image and decoder wheels link against, so these four are built with the dynamic tensor backend:

make wheel            # or, per package, from its directory:
cd crates/python-tensor && maturin build --release

The crate's .cargo/config.toml selects the dynamic backend; a build from the repository root without --config .cargo/tensor-dynamic.toml fails with a message naming the fix. edgefirst.tensor.__tensor_backend__ reports "dynamic" for every wheel built this way.

Quick start

Allocate an image tensor, fill it through a mapped host view, and read it back as NumPy:

import numpy as np
from edgefirst.tensor import Tensor, PixelFormat

# Allocate once; a real pipeline reuses the tensor every frame.
# mem=None selects the best backend available on the platform.
tensor = Tensor.image(1920, 1080, PixelFormat.Rgb, None, "readwrite")

with tensor.map() as view:
    frame = np.asarray(view)  # shape, dtype and strides all carried
    frame[:] = 128

print(tensor.shape, tensor.format, tensor.dtype)

map() returns a HostView implementing the buffer protocol, so np.asarray wraps the tensor's memory without copying — and because the view publishes shape, dtype and the real row stride, no manual reshape is needed and a pitch-aligned DMA buffer is read correctly rather than sheared. The view is released when the with block exits.

The map also owns its cache-coherency bracket, and access chooses the direction. The default "readwrite" flushes the whole buffer on release; a reader does not need that, and on a non-coherent Arm DMA-BUF backing skipping it is a per-frame saving:

with tensor.map("read") as view:
    frame = np.asarray(view)  # read-only view, not writable

pin_host() is the exception: it is deliberately decoupled from coherency so a pinned address can survive across convert() calls, which is why it pairs with an explicit cpu_access() bracket instead.

Handing memory to an external runtime

pin_host() returns a stable host address that outlives any map guard and carries no borrow of the tensor, so a pinned buffer can be given to an inference runtime (TFLite custom allocations, ONNX Runtime external tensors) while your frame loop keeps writing to it:

pin = tensor.pin_host("readwrite")
print(hex(pin.ptr), pin.len, pin.alignment)

# pin.ptr stays valid for the lifetime of `pin` — across re-maps and across
# ImageProcessor.convert() calls — so an external runtime can hold on to it.
pin.release()

What this package provides

API Purpose
Tensor Allocation, reshape, host mapping, NumPy interchange
Tensor.image() Allocate with image dimensions and a pixel format
Tensor.map() / HostView Buffer-protocol host access, released on scope exit
Tensor.pin_host() / HostPin Stable host address for external runtimes
Tensor.cuda_map() / CudaMap Zero-copy CUDA device pointer for TensorRT (Jetson)
TensorMemory, PixelFormat, Region Backend selection, pixel layout, sub-regions
Quantization, Colorimetry Quantization parameters and colour metadata
is_dma_available() and friends Runtime capability probes
Tracing, build_info() Diagnostics

Interoperability

Each edgefirst-* package is a separate PyO3 extension module, so edgefirst.tensor.Tensor and, say, edgefirst.codec.Tensor are different Python classes even though they wrap the same Rust type — a known PyO3 limitation (issue #1444). A tensor still crosses package boundaries safely, through the __edgefirst_tensor__ capsule protocol every Tensor implements:

# CORRECT — works regardless of which edgefirst.* package produced obj
if hasattr(obj, "__edgefirst_tensor__"):
    ...

# WRONG — always False for a tensor from a sibling package
if isinstance(obj, edgefirst.image.Tensor):
    ...

edgefirst.tensor.EdgeFirstTensorExportable is a typing.Protocol you can annotate a cross-package parameter with, so a type checker accepts a tensor from any edgefirst.* package. See crates/python-common/INTEROP.md for the full protocol — capsule names, lifetime and ownership rules, and versioning.

Versioning and changelog

All four edgefirst-* packages are versioned and released together with the HAL itself, so a given version number refers to the same source tree in every language. Because of that there is no per-package changelog: release notes for every version live in the single CHANGELOG.md in the hal repository, which follows Keep a Changelog and Semantic Versioning.

License

Apache-2.0

Metadata

Release files for edgefirst-tensor 0.40.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for edgefirst-tensor 0.40.0
File Actions
edgefirst_tensor-0.40.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for edgefirst_tensor-0.40.0-cp311-abi3-win_amd64.whl
edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_tensor-0.40.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for edgefirst_tensor-0.40.0-cp311-abi3-macosx_11_0_arm64.whl
edgefirst_tensor-0.40.0-cp38-abi3-win_amd64.whl CPython 3.8 abi3 Windows x86-64 Details for edgefirst_tensor-0.40.0-cp38-abi3-win_amd64.whl
edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.8 abi3 Linux glibc 2.17+ x86-64 Details for edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.8 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_tensor-0.40.0-cp38-abi3-macosx_11_0_arm64.whl CPython 3.8 abi3 macOS 11.0+ ARM64 Details for edgefirst_tensor-0.40.0-cp38-abi3-macosx_11_0_arm64.whl

Total release size: 9.1 MB

Release files / edgefirst_tensor-0.40.0-cp311-abi3-win_amd64.whl

Download URL edgefirst_tensor-0.40.0-cp311-abi3-win_amd64.whl
Size 1.1 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
18401feb45e9952ad365e6d91718f1a81361ecd7d69fb31ed69a6f2f84accc57
BLAKE2b-256 checksum
How to use checksums
7bed07c861f447e7c72796a592f08606951842ddf4d640af9a97c5c13a4847e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 1.2 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
8895b47007bfae41a6340227834645e68e2f1a68984c16cd09cf2d290b37eea3
BLAKE2b-256 checksum
How to use checksums
d3fa010833b3ce4643f95f6ec956868f44795c71160804fec841b8655b8db274
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL edgefirst_tensor-0.40.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.1 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
56a88a6a0cfbd9eb75e287f196d6490838b899efa144ac1e02b543ac89c3817d
BLAKE2b-256 checksum
How to use checksums
d8e4794661748e6f4d89015bbee6cc585441ec936a2fc6845d2ed2d46ace4b9a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL edgefirst_tensor-0.40.0-cp311-abi3-macosx_11_0_arm64.whl
Size 1.2 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9f07782badf47979aff61e445ca902b01cdea26bdf80ac75d251b22e0a3e03cf
BLAKE2b-256 checksum
How to use checksums
a66acc54a222683cd9afd11c5534b9c98f42bc7b5ffcfb6c3e7539227c378826
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp38-abi3-win_amd64.whl

Download URL edgefirst_tensor-0.40.0-cp38-abi3-win_amd64.whl
Size 1.1 MB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
6347f0f82d6776cc9c1d2640e4a34636a53e3f20effc8174a3a6fe013f8d6ef1
BLAKE2b-256 checksum
How to use checksums
6c6ae7f83a9ac5044119efec2ea41f35a793458be1533e45b549face8b0ceac2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 1.2 MB
Tags CPython 3.8 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
b8db394eccb6d5b498a07b9ecadd06da98e5e53c265781af410c722b6d99d401
BLAKE2b-256 checksum
How to use checksums
cfce7cf6cb14fec2bd1826decc70f0f655f95700ee978e3104c767acbf3a848b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL edgefirst_tensor-0.40.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.1 MB
Tags CPython 3.8 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
5995542d7c3c83111f56857e28276e0efd070e54e475a576596686958641bf2e
BLAKE2b-256 checksum
How to use checksums
23c34f013f637bb175dc1b311acca3af7432fc52687e50f7f91f2a30c446f70c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / edgefirst_tensor-0.40.0-cp38-abi3-macosx_11_0_arm64.whl

Download URL edgefirst_tensor-0.40.0-cp38-abi3-macosx_11_0_arm64.whl
Size 1.2 MB
Tags CPython 3.8 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0df2392990a5cc09c96b33e7051d8a777155695d5493da84cc7d50717137917c
BLAKE2b-256 checksum
How to use checksums
b4e95fdcf24b39fd23246cfad3bdfe0876d2b4d8b3a8a1250548b9d3e8c3c3ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for edgefirst-tensor 0.40.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for edgefirst_tensor-0.40.0-cp311-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page