Python (tet-py)

tet-py is the official Python package for Tetration. Install from PyPI, import tet, and use the same query engine and .tet layout as the Rust crate and tet CLI.

PyPI

tet-py 0.1.1 on PyPI: pip install tet-py

Do not pip install tetration — that PyPI name is unrelated math code.

Naming

Role	Value
PyPI / GitHub	tet-py
Import	import tet
Rust core	tetration 0.1.9 (linked at build time)
Native extension	tet._native (PyO3 / maturin, abi3 cp311+)

Python bindings use PyO3 → tetration rlib, not the C ABI layer. The C ABI remains in the tetration repo for Julia/R/Go embedders.

What's shipped (0.1.1)

Topic	Status
PyPI wheels (Linux, macOS, Windows)	✅
Open .tet, catalog, info() / summary()	✅
Reductions + QueryResult (preview=N → .preview ndarray)	✅
build_query, selections	✅
NumPy ram — read_numpy, transform.to_numpy	✅
NumPy spill — read_spill, transform.to_spill	✅
NumPy sidecar — transform.to_sidecar.*	✅
NumPy write — TetWriter, write_dataset (f32/f64)	✅
tet.convert extras (h5py, zarr, …)	Planned
Zero-copy mmap → NumPy	Planned
Object-store paths (s3://…)	Upstream tetration Phase 12

Sections

• Install — PyPI and build from source
• Quick start — open, query, inspect
• Query operations — reductions, transforms, QueryResult
• NumPy interchange — ram / spill / sidecar read and write
• Version alignment — tet-py ↔ tetration crate

When to use each sink

Sink	Output	Typical use
ram	numpy.ndarray in process	Notebooks, arrays that fit memory budget
spill	Row-major .bin beside source	Large transforms; reload with .to_numpy()
sidecar	One-chunk .tet beside source	Keep transformed data as a mmap-friendly .tet (re-query, share, append pipeline)

Sidecar is transform-only (no top-level read_sidecar — the engine writes a derived .tet, then you side.open(f) or tet.open(path)). Spill is raw bytes; sidecar is a full catalog file. Sidecar vs TetWriter: sidecar presets path, naming, and provenance from the transform; TetWriter is general authoring from your array (NumPy — sidecar vs TetWriter).

Minimal example

import tet

with tet.open("data.tet") as f:
    print(tet.__version__, tet.core_version())
    print(f.mean("temperature"))
    r = f.mean("temperature", preview=32)   # QueryResult: scalar + capped preview
    arr = f.read_numpy("temperature")
    z = f.transform.to_numpy.zscore("temperature")
    side = f.transform.to_sidecar.zscore("temperature", path="temperature.zscore.tet")
    arr = side.to_numpy(f)

When to use what

Need	Use
Python notebooks / NumPy / pandas	tet-py
Fast HDF5/NetCDF/Zarr import on a machine with native libs	tet convert CLI
Custom Rust service or lowest-level control	tetration crate
Other language bindings	C ABI / FFI

Related

• Getting started — CLI install and first queries
• Query engine guide — wire document schema (shared with CLI)
• Rust crate — underlying implementation
• tet-py repo — source, CI, issue tracker (Linear canonical)