naw
naw logs machine-learning time-series metrics to a compressed file on disk, and gives you a CLI to read them back.
It is two things in one package:
- a storage library (
naw.rtsdb) that writes typed, columnar, compressed rows to a single.rtsdbfile, and reads them back — including while the file is still being written; - a wandb-compatible façade (
naw.wandb) so that code already instrumented withwandb.init()/run.log()keeps working with nothing but an import change.
Full documentation: https://utrain.gitlabpages.inria.fr/naw/latest/
Installation
$ pip install naw # or: uv add naw
naw requires Python 3.10 or newer and pulls in three small dependencies
(argcomplete, pyyaml, tabulate) — no NumPy. The plot and heatmap
subcommands render through uniplot and
matplotlib, which are not installed by
default; get them with the plot extra:
$ pip install "naw[plot]" # or: uv add "naw[plot]"
Log a run
import naw.wandb as wandb
run = wandb.init(project="demo", config={"lr": 3e-4})
for step in range(1000):
run.log({"loss": loss})
run.finish()
init() creates <dir>/wandb/<project>/<id>.rtsdb. A run that is never
finished is still readable — you just lose the summary.
init() also starts a background monitor that records GPU utilization, VRAM,
power draw, temperature, ECC errors and throttling — plus host CPU, memory, disk
and network — every ten seconds. NVIDIA counters come from libnvidia-ml.so.1
bound directly with ctypes, and the host counters from /proc and /sys, so
this adds no dependencies and degrades to whatever the machine actually has.
The samples are ordinary metric rows, so every subcommand below reads them:
$ naw plot wandb/demo/<run-id>.rtsdb -x _timestamp -y system.gpu.0.powerWatts --lines
Pass monitor_system=False (or set NAW_MONITOR_SYSTEM=0) to turn it off.
Read it back
Every subcommand takes the run filename as its first argument:
| Command | Description |
|---|---|
naw metadata FILE |
Show the run's identity, configuration and final summary. |
naw metrics FILE |
List the metric columns present in the run and their storage types. |
naw watch FILE |
Print metric rows as they are written, then exit when the run closes. |
naw plot FILE -y METRIC |
Plot one metric against another (terminal, matplotlib, SVG, PNG or CSV). |
naw heatmap FILE -m METRIC |
Render a histogram metric as a 2-D density map over time. |
$ naw plot wandb/demo/<run-id>.rtsdb -y loss --lines
How it compresses
Values are grouped by column rather than by row, and each column is encoded with
a scheme suited to its type: integers as a delta against the previous row then
LEB128 varint, floats as an XOR against the previous row's value then a varint
over the resulting bit pattern, and float16/bfloat16 in 2 bytes. A step
counter that increments by one costs a single byte per row.
The writer periodically emits a sync point carrying a schema index, so a
reader that opens the file mid-run can seek to the last sync point instead of
replaying the whole file. That is what makes naw watch a live tail rather than
a repeated full parse.
Documentation
- Get started — what naw is and when to reach for it.
- Quickstart — log a run and read it back in five minutes.
- CLI — every subcommand and flag.
- Python API — the
naw.rtsdbread and write path. - wandb compatibility — exactly which parts of the wandb API are covered.
- File format
— what is actually in an
.rtsdbfile. - Contributing — build, test and release.
References
The XOR-then-varint idea is the one introduced by Gorilla and refined by Chimp and Elf; naw uses varint framing rather than these papers' bit-level framing, which keeps decoding cheap and the format simple to reason about.
- Gorilla: A fast, scalable, in-memory time series database
- Chimp: efficient lossless floating point compression for time series databases
- Elf: Erasing-Based Lossless Floating-Point Compression
License
MIT — see LICENSE.
Metadata
Release files for naw 0.0.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| naw-0.0.12.tar.gz | 53.9 kB | Without provenance | Details for naw-0.0.12.tar.gz |
Built distributions (wheels)
Total release size: 3.4 MB
Release files / naw-0.0.12.tar.gz
| Download URL | naw-0.0.12.tar.gz |
|---|---|
| Size | 53.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
743fd8132bbf1176019c80727beb77282789f59664aad23e8e57bf9f934437d7
|
|
BLAKE2b-256 checksum How to use checksums |
1349583281ef38d17c70bb2ce58809ce23d641c0230870522623d312a15d8090
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naw-0.0.12-py3-none-any.whl
| Download URL | naw-0.0.12-py3-none-any.whl |
|---|---|
| Size | 58.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
12593e48563fa03046255d891f4d3f449c035d2626f113045e84d8b799cb2359
|
|
BLAKE2b-256 checksum How to use checksums |
93307e56403cd2afcf20afcc245a8a4cf181418467ae30f7b9fc2f0b87873eeb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naw-0.0.12-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | naw-0.0.12-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 660.3 kB |
| Tags | CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
400114e1d807dd68332d17c2219aa4a2371ea04f028d62854cee60f92b7f0181
|
|
BLAKE2b-256 checksum How to use checksums |
375d6719b0c1a4b49d89a520ddde5484a38574660164ec6ebadcae2d9ebcb5ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naw-0.0.12-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | naw-0.0.12-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 665.7 kB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
8f29fe34ad4cf126b76852697809bed7cdff6b51c39b2af59639c0800b8f8168
|
|
BLAKE2b-256 checksum How to use checksums |
0ae5a286f7aa8e4fa5e9b13fbf39ac493276d5e5e5807782be4e9c6cde18539f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naw-0.0.12-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | naw-0.0.12-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 675.4 kB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
97aa1cf48a30434db139abb1a3361a77afe0d0e62b7dcf083bb9274df6f0b9cd
|
|
BLAKE2b-256 checksum How to use checksums |
b1437b2a18138180cb9bbe72d6629513f5a6c5e5b7c1022177d4344a06916018
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naw-0.0.12-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | naw-0.0.12-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 635.7 kB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
e7758169237a15ef787590a3e71bda132daa2bfa5af6cc67c9f2a5f6bf649718
|
|
BLAKE2b-256 checksum How to use checksums |
429cf459d3ca7fd0a66355703b2e5676b0d5a1ecab85c0284f3e3c263dc145ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naw-0.0.12-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | naw-0.0.12-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 613.2 kB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
dbc6e6087426c1b701a9360d26dbeff5d7e47430e0176387beca06728d282e09
|
|
BLAKE2b-256 checksum How to use checksums |
b203cd261c23175560b2f8798491b054a87de383cc3a693a41ce2a9bf2ff2b06
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for naw 0.0.12
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.