trave 1.0.0__tar.gz

trave-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edde746
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trave-1.0.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: trave
+Version: 1.0.0
+Summary: Trave: tables of named, typed columns packed for an app to read with nothing but a gzip decoder
+Author: edde746
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/edde746/trave
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# trave (Python)
+
+The reference writer and reader of [Trave](https://github.com/edde746/trave): one module, Python 3.9 or newer,
+standard library only. The format, the API and examples are in the repository's README.

trave-1.0.0/README.md

@@ -0,0 +1,4 @@
+# trave (Python)
+
+The reference writer and reader of [Trave](https://github.com/edde746/trave): one module, Python 3.9 or newer,
+standard library only. The format, the API and examples are in the repository's README.

trave-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trave"
+version = "1.0.0"
+description = "Trave: tables of named, typed columns packed for an app to read with nothing but a gzip decoder"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "edde746" }]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+
+[project.urls]
+Homepage = "https://github.com/edde746/trave"
+
+[tool.setuptools]
+py-modules = ["trave"]

trave-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trave-1.0.0/tests/test_trave.py

@@ -0,0 +1,90 @@
+import json
+import sys
+import unittest
+from pathlib import Path
+
+PYTHON = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PYTHON))
+import trave  # noqa: E402
+
+VECTORS = json.loads((PYTHON.parent / "vectors.json").read_text(encoding="utf-8"))
+MAGIC = VECTORS["magic"].encode("ascii")
+TYPES = {name: kind for kind, name in trave.TYPE_NAMES.items()}
+
+
+def expected(vector):
+    """The vector's tables as read() returns them."""
+    return {t["name"]: (t["rows"], {c["name"]: c["values"] for c in t["columns"]}) for t in vector["tables"]}
+
+
+def to_pack(vector):
+    return [(t["name"], t["rows"], [(c["name"], TYPES[c["type"]], c["values"]) for c in t["columns"]])
+            for t in vector["tables"]]
+
+
+class Vectors(unittest.TestCase):
+    def test_valid_files_read_as_expected(self):
+        for v in VECTORS["vectors"]:
+            if "error" in v:
+                continue
+            with self.subTest(v["name"]):
+                got = trave.read(bytes.fromhex(v["hex"]), MAGIC)
+                self.assertEqual(got, expected(v))
+                self.assertEqual(list(got), [t["name"] for t in v["tables"]])  # in the file's order
+
+    def test_canonical_files_pack_to_the_same_bytes(self):
+        for v in VECTORS["vectors"]:
+            if v.get("canonical"):
+                with self.subTest(v["name"]):
+                    self.assertEqual(trave.pack(MAGIC, to_pack(v)), bytes.fromhex(v["hex"]))
+
+    def test_invalid_files_are_errors(self):
+        for v in VECTORS["vectors"]:
+            if "error" in v:
+                with self.subTest(v["name"]):
+                    with self.assertRaises(ValueError):
+                        trave.read(bytes.fromhex(v["hex"]), MAGIC)
+
+
+class Compression(unittest.TestCase):
+    data = trave.pack(MAGIC, [("t", 2, [("s", trave.STR, ["a", None])])])
+
+    def test_gzip_is_read_and_deterministic(self):
+        packed = trave.gzip_bytes(self.data)
+        self.assertEqual(packed, trave.gzip_bytes(self.data))
+        self.assertEqual(trave.read(packed), trave.read(self.data))
+
+    @unittest.skipIf(trave.zstd is None, "zstd needs Python 3.14")
+    def test_zstd_is_read(self):
+        self.assertEqual(trave.read(trave.zstd.compress(self.data)), trave.read(self.data))
+
+
+class Errors(unittest.TestCase):
+    def test_another_magic_is_an_error(self):
+        with self.assertRaises(ValueError):
+            trave.read(trave.pack(b"AAAA", []), b"BBBB")
+
+    def test_writer_refuses_what_readers_cannot_hold(self):
+        cases = {
+            "int -2^63": [("t", 1, [("i", trave.INT, [-(1 << 63)])])],
+            "delta over 2^63 - 1": [("t", 2, [("d", trave.INT_DELTA, [-1, (1 << 63) - 1])])],
+            "int_delta value -2^63": [("t", 2, [("d", trave.INT_DELTA, [-1, -(1 << 63)])])],
+            "list item 2^63": [("t", 1, [("l", trave.INT_LIST, [[1 << 63]])])],
+            "values for another row count": [("t", 2, [("i", trave.INT, [1])])],
+            "two columns of one name": [("t", 0, [("i", trave.INT, []), ("i", trave.STR, [])])],
+            "unknown type": [("t", 0, [("i", 9, [])])],
+        }
+        for name, tables in cases.items():
+            with self.subTest(name):
+                with self.assertRaises(ValueError):
+                    trave.pack(MAGIC, tables)
+
+    def test_magic_that_reads_as_compressed_is_refused(self):
+        for magic in (b"\x1f\x8bAB", b"\x28\xb5\x2f\xfd", b"ABC"):
+            with self.subTest(magic):
+                with self.assertRaises(ValueError):
+                    trave.pack(magic, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

trave-1.0.0/trave.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: trave
+Version: 1.0.0
+Summary: Trave: tables of named, typed columns packed for an app to read with nothing but a gzip decoder
+Author: edde746
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/edde746/trave
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# trave (Python)
+
+The reference writer and reader of [Trave](https://github.com/edde746/trave): one module, Python 3.9 or newer,
+standard library only. The format, the API and examples are in the repository's README.

trave-1.0.0/trave.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+trave.py
+tests/test_trave.py
+trave.egg-info/PKG-INFO
+trave.egg-info/SOURCES.txt
+trave.egg-info/dependency_links.txt
+trave.egg-info/top_level.txt

trave-1.0.0/trave.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

trave-1.0.0/trave.egg-info/top_level.txt

@@ -0,0 +1 @@
+trave

trave-1.0.0/trave.py

@@ -0,0 +1,287 @@
+"""Trave: tables of named, typed columns packed for an app to read with nothing but a gzip or zstd decoder.
+
+The reference writer and reader of the README's format, Python 3.9 or newer, standard library only (zstd input needs
+Python 3.14's compression.zstd). One module with no dependencies: install the `trave` package or copy this file.
+
+  pack(magic, tables) -> bytes      tables: [(name, rows, [(column name, type, values)])], None for an absent value
+  gzip_bytes(data) -> bytes         gzip -9 with no file name and no time: the same data gives the same bytes
+  read(data, magic=None)            -> {table: (rows, {column: values})}, gzip, zstd or not compressed
+
+Usage:
+  python -m trave FILE...           print each file's magic, tables and columns with their sizes
+"""
+import argparse
+import gzip
+import io
+from pathlib import Path
+
+try:
+    from compression import zstd
+except ImportError:
+    zstd = None
+
+VERSION = 1
+
+# Column types, one byte each in the file. A reader skips a column of any other type.
+INT, INT_DELTA, STR, DICT, INT_LIST, STR_LIST = 1, 2, 3, 4, 5, 6
+TYPE_NAMES = {INT: "int", INT_DELTA: "int_delta", STR: "str", DICT: "dict", INT_LIST: "int_list", STR_LIST: "str_list"}
+
+GZIP_MAGIC, ZSTD_MAGIC = b"\x1f\x8b", b"\x28\xb5\x2f\xfd"
+U64 = 1 << 64
+# An int or int_delta value, and an int_delta difference, is within ±MAX_INT; only a list item can be -2**63.
+MAX_INT = (1 << 63) - 1
+
+
+# --- writing ---------------------------------------------------------------------------------------------------------
+
+def varint(n, out):
+    if not 0 <= n < U64:
+        raise ValueError(f"varint of {n}, outside 0 .. 2**64 - 1")
+    while n > 0x7F:
+        out.append(n & 0x7F | 0x80)
+        n >>= 7
+    out.append(n)
+
+
+def zigzag(n):
+    return n * 2 if n >= 0 else -n * 2 - 1
+
+
+def text(s, out):
+    b = s.encode("utf-8")
+    varint(len(b), out)
+    out += b
+
+
+def column(kind, values):
+    """The column's bytes: one value per row, `None` for an absent value."""
+    out = bytearray()
+    if kind == DICT:
+        words = list(dict.fromkeys(v for v in values if v is not None))  # in order of first use
+        varint(len(words), out)
+        for w in words:
+            text(w, out)
+        index = {w: i for i, w in enumerate(words)}
+    previous = 0
+    for v in values:
+        if v is None:
+            out.append(0)
+        elif kind in (INT, INT_DELTA):
+            if not -MAX_INT <= v <= MAX_INT:
+                raise ValueError(f"value {v} outside ±(2**63 - 1)")
+            if kind == INT:
+                varint(zigzag(v) + 1, out)
+            else:
+                if not -MAX_INT <= v - previous <= MAX_INT:
+                    raise ValueError(f"difference {v - previous} outside ±(2**63 - 1)")
+                varint(zigzag(v - previous) + 1, out)
+                previous = v
+        elif kind == STR:
+            b = v.encode("utf-8")
+            varint(len(b) + 1, out)
+            out += b
+        elif kind == DICT:
+            varint(index[v] + 1, out)
+        elif kind == INT_LIST:
+            varint(len(v) + 1, out)
+            for x in v:
+                if not -(1 << 63) <= x < 1 << 63:
+                    raise ValueError(f"list item {x} is not a signed 64-bit integer")
+                varint(zigzag(x), out)
+        elif kind == STR_LIST:
+            varint(len(v) + 1, out)
+            for x in v:
+                text(x, out)
+    return out
+
+
+def pack(magic, tables):
+    """tables: [(name, rows, [(column name, type, values)])] -> the file's bytes, not compressed."""
+    if len(magic) != 4 or magic.startswith(GZIP_MAGIC) or magic.startswith(ZSTD_MAGIC):
+        raise ValueError(f"magic {magic!r}: 4 bytes expected, not starting like gzip or zstd")
+    out = bytearray(magic)
+    out.append(VERSION)
+    varint(len(tables), out)
+    if len({name for name, _, _ in tables}) != len(tables):
+        raise ValueError("two tables of the same name")
+    for name, nrows, columns in tables:
+        text(name, out)
+        varint(nrows, out)
+        varint(len(columns), out)
+        if len({cname for cname, _, _ in columns}) != len(columns):
+            raise ValueError(f"{name}: two columns of the same name")
+        for cname, kind, values in columns:
+            if kind not in TYPE_NAMES:
+                raise ValueError(f"{name}.{cname}: unknown type {kind}")
+            if len(values) != nrows:
+                raise ValueError(f"{name}.{cname}: {len(values)} values for {nrows} rows")
+            try:
+                body = column(kind, values)
+            except ValueError as e:
+                raise ValueError(f"{name}.{cname}: {e}") from None
+            text(cname, out)
+            out.append(kind)
+            varint(len(body), out)
+            out += body
+    return bytes(out)
+
+
+def gzip_bytes(data):
+    """gzip -9 with no file name and no time, so the same data gives the same bytes."""
+    buffer = io.BytesIO()
+    with gzip.GzipFile(filename="", mode="wb", compresslevel=9, fileobj=buffer, mtime=0) as f:
+        f.write(data)
+    return buffer.getvalue()
+
+
+# --- reading ---------------------------------------------------------------------------------------------------------
+
+class Reader:
+    def __init__(self, data, pos=0, end=None):
+        self.data, self.pos, self.end = data, pos, len(data) if end is None else end
+
+    def byte(self):
+        if self.pos >= self.end:
+            raise ValueError("cut short")
+        self.pos += 1
+        return self.data[self.pos - 1]
+
+    def varint(self):
+        n = shift = 0
+        while True:
+            b = self.byte()
+            n |= (b & 0x7F) << shift
+            if b < 0x80:
+                break
+            shift += 7
+            if shift > 63:
+                raise ValueError("a varint longer than 10 bytes")
+        if n >= U64:
+            raise ValueError("a varint over 2**64 - 1")
+        return n
+
+    def bytes(self, n):
+        if self.pos + n > self.end:
+            raise ValueError("cut short")
+        self.pos += n
+        return self.data[self.pos - n:self.pos]
+
+    def text(self):
+        return self.bytes(self.varint()).decode("utf-8")
+
+    def signed(self):
+        return unzigzag(self.varint())
+
+
+def unzigzag(n):
+    return n >> 1 if n % 2 == 0 else -(n >> 1) - 1
+
+
+def read_column(kind, nrows, r):
+    """A column's values, `None` for absent; `r` reads exactly the column's bytes."""
+    words = [r.text() for _ in range(r.varint())] if kind == DICT else None
+    values, previous = [], 0
+    for _ in range(nrows):
+        tag = r.varint()
+        if tag == 0:
+            values.append(None)
+            continue
+        if kind == INT:
+            values.append(unzigzag(tag - 1))
+        elif kind == INT_DELTA:
+            previous += unzigzag(tag - 1)
+            if not -MAX_INT <= previous <= MAX_INT:
+                raise ValueError(f"int_delta value {previous} outside ±(2**63 - 1)")
+            values.append(previous)
+        elif kind == STR:
+            values.append(r.bytes(tag - 1).decode("utf-8"))
+        elif kind == DICT:
+            if tag > len(words):
+                raise ValueError(f"dictionary string {tag - 1} of {len(words)}")
+            values.append(words[tag - 1])
+        elif kind == INT_LIST:
+            values.append([r.signed() for _ in range(tag - 1)])
+        elif kind == STR_LIST:
+            values.append([r.text() for _ in range(tag - 1)])
+    if r.pos != r.end:
+        raise ValueError(f"{r.end - r.pos} bytes left in a column")
+    return values
+
+
+def unpack(data):
+    """The file's bytes, decompressed if they are gzip or zstd."""
+    if data[:2] == GZIP_MAGIC:
+        return gzip.decompress(data)
+    if data[:4] == ZSTD_MAGIC:
+        if zstd is None:
+            raise ValueError("zstd input needs Python 3.14 or newer")
+        return zstd.decompress(data)
+    return data
+
+
+def read(data, magic=None):
+    """The file (gzip, zstd or not compressed) as {table: (rows, {column: values})}, the tables and columns in the
+    file's order; columns of an unknown type are skipped. With `magic`, a file with another magic is an error."""
+    data = unpack(data)
+    r = Reader(data)
+    found = r.bytes(4)
+    if magic is not None and found != magic:
+        raise ValueError(f"magic {found!r}, not {magic!r}")
+    version = r.byte()
+    if version != VERSION:
+        raise ValueError(f"version {version}, not {VERSION}")
+    out = {}
+    for _ in range(r.varint()):
+        name, nrows = r.text(), r.varint()
+        if name in out:
+            raise ValueError(f"two tables named {name!r}")
+        columns, seen = {}, set()
+        for _ in range(r.varint()):
+            cname, kind, length = r.text(), r.byte(), r.varint()
+            if cname in seen:
+                raise ValueError(f"{name}: two columns named {cname!r}")
+            seen.add(cname)
+            body = Reader(data, r.pos, r.pos + length)
+            r.bytes(length)
+            if kind in TYPE_NAMES:
+                try:
+                    columns[cname] = read_column(kind, nrows, body)
+                except ValueError as e:
+                    raise ValueError(f"{name}.{cname}: {e}") from None
+        out[name] = (nrows, columns)
+    if r.pos != len(data):
+        raise ValueError(f"{len(data) - r.pos} bytes after the last table")
+    return out
+
+
+# --- command line ----------------------------------------------------------------------------------------------------
+
+def dump(path):
+    data = Path(path).read_bytes()
+    raw = unpack(data)
+    read(raw)  # the whole file is valid before anything is printed
+    r = Reader(raw)
+    magic, version = r.bytes(4), r.byte()
+    print(f"{path}: magic {magic.decode('ascii', 'backslashreplace')}, version {version}, "
+          f"{len(data):,} bytes, {len(raw):,} unpacked")
+    for _ in range(r.varint()):
+        name, nrows = r.text(), r.varint()
+        print(f"{name}: {nrows:,} rows")
+        for _ in range(r.varint()):
+            cname, kind, length = r.text(), r.byte(), r.varint()
+            r.bytes(length)
+            print(f"  {cname:20} {TYPE_NAMES.get(kind, f'type {kind}'):10} {length:>11,} bytes")
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("files", nargs="+", type=Path)
+    for path in p.parse_args().files:
+        try:
+            dump(path)
+        except ValueError as e:
+            raise SystemExit(f"{path}: {e}")
+
+
+if __name__ == "__main__":
+    main()