Skip to main content

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 .rtsdb file, and reads them back — including while the file is still being written;
  • a wandb-compatible façade (naw.wandb) so that code already instrumented with wandb.init() / run.log() keeps working with nothing but an import change.

Full documentation: https://mlacage.gitlabpages.inria.fr/naw

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

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

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

Source distribution (sdist)

Source distribution for naw 0.0.11
File Size Uploaded Provenance Actions
naw-0.0.11.tar.gz 54.1 kB Without provenance Details for naw-0.0.11.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for naw 0.0.11
File Actions
naw-0.0.11-py3-none-any.whl Python 3 none any Details for naw-0.0.11-py3-none-any.whl
naw-0.0.11-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.11-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.11-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.11-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.11-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.11-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.11-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64, Linux glibc 2.5+ x86-64 Details for naw-0.0.11-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.11-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.5+ x86-64 Details for naw-0.0.11-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Total release size: 3.4 MB

Release files / naw-0.0.11.tar.gz

Download URL naw-0.0.11.tar.gz
Size 54.1 kB
Tags Source
SHA-256 checksum
How to use checksums
650771d8a91b333ba266151e692bbb35a3900997ce713379b73fd5e5794e262a
BLAKE2b-256 checksum
How to use checksums
b4bda4f3a84b0bc5a1c9cf55f9686eb66d082a329d203aedce05534d551e7017
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11-py3-none-any.whl

Download URL naw-0.0.11-py3-none-any.whl
Size 58.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
229ce2cb99a0b3c5b2f7b98a065a717dbec9c47cad04e8d97bcd3e7d139c1432
BLAKE2b-256 checksum
How to use checksums
b1363f214dab3f166df32516ec117940681c065bbb2f8f339b3a615742fcc728
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.11-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 660.4 kB
Tags CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
949a3d4ad21302dd5a5cebbab1601217125f93463ad7dfae82394ae4b4250af2
BLAKE2b-256 checksum
How to use checksums
02f8ed264edaa0f352bb8769780c6e769594f42c1050f2d8b36747e88e080f97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.11-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 665.6 kB
Tags CPython 3.13 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
f5fdbb781f8da59bbe4c74cad4ad36a6d9eca7696fa8df593e11d7139f2ad8e9
BLAKE2b-256 checksum
How to use checksums
420bc265e724e782ac68fd7edcc105f2d536a833d0d967914faedc99826db9b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.11-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
724cf3eefe53c72f6178b84713e5f8225223535c32cf7c6da4ac0db4d86d9500
BLAKE2b-256 checksum
How to use checksums
d176eeea492766b23598366209edec4a7bb0cd261f6d2e39928af82db95aee15
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.11-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
e75ee637228e6dec8a2c89944ab942dc93c0eef413ded2da2c475914ef481205
BLAKE2b-256 checksum
How to use checksums
636324093e7d317d05287bdaed2fc97e8be8e123fa60b9ee9287d83ec9c1ee8a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.11-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
6c859b4eb51f2673c2ac57b1887a94e6bcae65430a7cbe9d96df48bb5dd78ed9
BLAKE2b-256 checksum
How to use checksums
36cedcd5f156e318adb76cfbdd15f5c1e05537f9abfb317183106c77c3de95ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.33 {"installer":{"name":"uv","version":"0.11.33","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.11

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.

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