tet-py

Python bindings for Tetration — mmap-friendly .tet tensor files and the JSON/TOML query engine.

| Install (PyPI) | pip install tet-py | | Import | import tet | | Rust core | tetration on crates.io | | CLI (no Python) | tet binary from the main repo |

Status (0.1.2): read/query (incl. preview=N, TOML queries, memory_budget_* kwargs); NumPy ram / spill / sidecar (incl. f16/u32/u64 export + read_numpy budget preflight); TetWriter / write_dataset (layout-v1 floats + integers); tet.convert for .npy/.npz (other formats stubbed via extras). Pins tetration 0.1.12. See CHANGELOG.md and docs/HANDOFF.md.

Do not pip install tetration — that PyPI name is an unrelated math package. Use tet-py / import tet.

Quick start

Prerequisites

• Python 3.11+
• Rust 1.95+ (.mise.toml pins rust = "1.95", or install matching rustup toolchain; native/Cargo.toml sets rust-version = "1.95")
• maturin (pip install maturin or uv tool install maturin)

Development

cd ~/Code/tet-py
uv sync --extra dev
mise run develop   # or: uv run maturin develop
uv run python -c "import tet; print(tet.__version__, tet.core_version())"
uv run pytest -q
uv run mypy python/tet

Links tetration 0.1.12 from crates.io. Test fixtures live in tests/fixtures/.

Example

import tet

with tet.open("tests/fixtures/large.tet") as f:  # or any .tet path
    print(f.mean("a"), f.quantile("a", 0.5))
    r = f.mean("a", preview=32)                   # QueryResult: r.scalar + r.preview (ndarray)
    arr = f.read_numpy("a")                         # ram
    z = f.transform.to_numpy.zscore("a")            # transform → ram
    spill = f.transform.to_spill.zscore("a", path="a_zscore.bin")
    same = spill.to_numpy()                         # transform → spill → ndarray
    side = f.transform.to_sidecar.zscore("a", path="a_zscore.tet")
    same = side.to_numpy(f)                         # transform → sidecar .tet → ndarray

Operations reference (every op with examples): docs/operations.md

info() / summary()

Both return the full tet info --json dict (superblock, datasets, all chunk rows, metadata). For exploration, prefer list(f), f.dataset(name), or info["datasets"] — not printing the whole dict in the REPL.

Project layout

tet-py/
  pyproject.toml      # PEP 621 + maturin
  python/tet/         # public API + _core, _query, _io, _transform
  native/             # PyO3 extension (links tetration 0.1.12)
  tests/fixtures/     # vendored .tet fixtures for CI
  docs/               # operations.md, HANDOFF.md
  CHANGELOG.md

Roadmap

• Scaffold: maturin, tet.open, datasets, query (JSON document)
• query() / execute(raw=False) → QueryResult
• summary() / info() — dict parity with tet info --json
• Reduction helpers (mean, sum, min, max, …)
• quantile, histogram, covariance, correlation
• build_query, axis_slice, selection_slices
• Dataset, iter_datasets(), f[0] / f["name"], axis index or dim_names
• UnknownDatasetError / UnknownAxisError; optional typing_stub()
• mypy + _native.pyi
• NumPy read — ram (read_numpy, Dataset.to_numpy, transform.to_numpy)
• NumPy read — spill (read_spill, transform.to_spill, .to_numpy() loaders)
• NumPy read — sidecar (transform.to_sidecar, SidecarTransformResult.to_numpy)
• NumPy write (TetWriter, write_dataset)
• PyPI wheels (tet-py 0.1.1); tetration pin now 0.1.12 on crates.io
• Query preview samples (preview=N, QueryResult.preview) — #7
• CI fixtures vendored in tests/fixtures/ (no sibling tetration checkout) — #6

To do

Near-term

• Pre-bump stack (THI-452) — CI mypy, budgets, TOML, tests, convert npy scaffold
• Pin tetration 0.1.12 (THI-457) — read_numpy preflight (THI-23), f16/u32/u64 export (THI-15), f64_row_major writer
• Integer / f16 write_dataset dtypes (THI-26)
• tet.convert full extras (THI-22) — h5/netcdf/zarr/csv/parquet implementations (stubs + extras exist; Rust CLI remains fast path)
• Zero-copy mmap → NumPy (THI-21) — views over mmap’d raw payloads (P2)

Docs

• Keep docs.tetration.sh/python in sync with releases

Related

• CHANGELOG.md — release notes
• docs.tetration.sh — Python — install, NumPy sinks, operations
• docs/operations.md — query ops (mean, quantile, …) with examples
• docs/README.md — doc index
• HANDOFF.md — phases, dev commands, agent notes
• Layout v1
• Query engine
• AGENTS.md — ops and phase status

License

Dual-licensed under MIT OR Apache-2.0, same as tetration.