triepack 1.3.1__tar.gz

triepack-1.3.1/LICENSE.txt

@@ -0,0 +1,23 @@
+triepack is Copyright (c) 2026, M. A. Chatterjee <deftio at deftio dot com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

triepack-1.3.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# The test suite reads fixtures from tests/conformance/ in the repository, so
+# it cannot run from an unpacked sdist. Shipping tests that are guaranteed to
+# fail is worse than not shipping them; run them from a checkout instead.
+prune tests

triepack-1.3.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: triepack
+Version: 1.3.1
+Summary: Compressed trie dictionary format (.trp) — compact binary key-value storage with fast lookups and prefix search. Pure Python, no dependencies.
+Author-email: "M. A. Chatterjee" <deftio@deftio.com>
+License-Expression: BSD-2-Clause
+Project-URL: Homepage, https://deftio.github.io/triepack/
+Project-URL: Documentation, https://deftio.github.io/triepack/guide/api-reference/
+Project-URL: Repository, https://github.com/deftio/triepack
+Project-URL: Issues, https://github.com/deftio/triepack/issues
+Project-URL: Changelog, https://github.com/deftio/triepack/blob/main/CHANGELOG.md
+Keywords: trie,prefix-tree,dictionary,binary-format,serialization,compression,key-value,prefix-search,trp,triepack
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# triepack
+
+Compressed trie dictionary format (`.trp`) — compact binary key-value storage
+with fast lookups and prefix search.
+
+This is the native Python implementation: pure Python, no dependencies, no C
+extension to build. It reads and writes the same bytes as the C reference
+library and the JavaScript, Go, Rust, Swift, Java and Kotlin implementations.
+
+## Install
+
+```bash
+pip install triepack
+```
+
+## Use
+
+```python
+from triepack import encode, decode
+
+buf = encode({"hello": 42, "world": "foo"})
+# buf is bytes holding the .trp binary
+
+result = decode(buf)
+print(result)  # {'hello': 42, 'world': 'foo'}
+```
+
+## Values
+
+| Python            | `.trp` type        |
+|-------------------|--------------------|
+| `None`            | null               |
+| `bool`            | bool               |
+| `int >= 0`        | uint               |
+| `int < 0`         | int                |
+| `float`           | float64            |
+| `str`             | string (UTF-8)     |
+| `bytes`           | blob               |
+
+Decoding also accepts float32 values written by other implementations,
+widening them to a Python float. Python integers are arbitrary precision, so
+the full 64-bit signed and unsigned ranges round-trip exactly.
+
+## Format
+
+Every buffer carries a 32-byte header, a bit-packed prefix trie, a typed value
+store and a CRC-32. Keys are stored once per shared prefix, and symbols are
+packed at the minimum width the key alphabet needs.
+
+The encoder is deterministic: the same input produces the same bytes in every
+implementation, which is checked by a
+[shared conformance suite](https://github.com/deftio/triepack/tree/main/tests/conformance)
+that all nine implementations run.
+
+## Links
+
+- [Documentation](https://deftio.github.io/triepack/)
+- [API reference](https://deftio.github.io/triepack/guide/api-reference/)
+- [Source and issues](https://github.com/deftio/triepack)
+- [Changelog](https://github.com/deftio/triepack/blob/main/CHANGELOG.md)
+
+## Development
+
+```bash
+cd bindings/python
+pip install -e ".[test]"
+python -m pytest
+```
+
+## License
+
+Copyright (c) 2026 M. A. Chatterjee. BSD-2-Clause — see
+[LICENSE.txt](LICENSE.txt).

triepack-1.3.1/README.md

@@ -0,0 +1,73 @@
+# triepack
+
+Compressed trie dictionary format (`.trp`) — compact binary key-value storage
+with fast lookups and prefix search.
+
+This is the native Python implementation: pure Python, no dependencies, no C
+extension to build. It reads and writes the same bytes as the C reference
+library and the JavaScript, Go, Rust, Swift, Java and Kotlin implementations.
+
+## Install
+
+```bash
+pip install triepack
+```
+
+## Use
+
+```python
+from triepack import encode, decode
+
+buf = encode({"hello": 42, "world": "foo"})
+# buf is bytes holding the .trp binary
+
+result = decode(buf)
+print(result)  # {'hello': 42, 'world': 'foo'}
+```
+
+## Values
+
+| Python            | `.trp` type        |
+|-------------------|--------------------|
+| `None`            | null               |
+| `bool`            | bool               |
+| `int >= 0`        | uint               |
+| `int < 0`         | int                |
+| `float`           | float64            |
+| `str`             | string (UTF-8)     |
+| `bytes`           | blob               |
+
+Decoding also accepts float32 values written by other implementations,
+widening them to a Python float. Python integers are arbitrary precision, so
+the full 64-bit signed and unsigned ranges round-trip exactly.
+
+## Format
+
+Every buffer carries a 32-byte header, a bit-packed prefix trie, a typed value
+store and a CRC-32. Keys are stored once per shared prefix, and symbols are
+packed at the minimum width the key alphabet needs.
+
+The encoder is deterministic: the same input produces the same bytes in every
+implementation, which is checked by a
+[shared conformance suite](https://github.com/deftio/triepack/tree/main/tests/conformance)
+that all nine implementations run.
+
+## Links
+
+- [Documentation](https://deftio.github.io/triepack/)
+- [API reference](https://deftio.github.io/triepack/guide/api-reference/)
+- [Source and issues](https://github.com/deftio/triepack)
+- [Changelog](https://github.com/deftio/triepack/blob/main/CHANGELOG.md)
+
+## Development
+
+```bash
+cd bindings/python
+pip install -e ".[test]"
+python -m pytest
+```
+
+## License
+
+Copyright (c) 2026 M. A. Chatterjee. BSD-2-Clause — see
+[LICENSE.txt](LICENSE.txt).

triepack-1.3.1/pyproject.toml

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "triepack"
+version = "1.3.1"
+description = "Compressed trie dictionary format (.trp) — compact binary key-value storage with fast lookups and prefix search. Pure Python, no dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "BSD-2-Clause"
+license-files = ["LICENSE.txt"]
+authors = [{ name = "M. A. Chatterjee", email = "deftio@deftio.com" }]
+keywords = [
+    "trie",
+    "prefix-tree",
+    "dictionary",
+    "binary-format",
+    "serialization",
+    "compression",
+    "key-value",
+    "prefix-search",
+    "trp",
+    "triepack",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Archiving :: Compression",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://deftio.github.io/triepack/"
+Documentation = "https://deftio.github.io/triepack/guide/api-reference/"
+Repository = "https://github.com/deftio/triepack"
+Issues = "https://github.com/deftio/triepack/issues"
+Changelog = "https://github.com/deftio/triepack/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools]
+# Ship the package only. The test suite reads fixtures from tests/conformance/
+# in the repository, which is not part of a release.
+packages = ["triepack"]

triepack-1.3.1/setup.cfg

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

triepack-1.3.1/setup.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+
+from setuptools import setup
+
+setup()

triepack-1.3.1/triepack/__init__.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+
+"""triepack — Native Python implementation of the Triepack .trp binary format."""
+
+__version__ = "1.3.1"
+
+from .decoder import decode
+from .encoder import MAX_ALPHABET_SIZE, encode
+
+#: Version of the on-disk .trp format this implementation writes. Distinct
+#: from the library version: it changes only when the bytes change.
+FORMAT_VERSION_MAJOR = 1
+FORMAT_VERSION_MINOR = 0
+
+
+def version():
+    """Return metadata about this build.
+
+    Every triepack implementation answers with the same shape, so a polyglot
+    system can ask each one what it is.
+    """
+    major, minor, patch = (int(p) for p in __version__.split("."))
+    return {
+        "name": "triepack",
+        "implementation": "python",
+        "version": __version__,
+        "version_major": major,
+        "version_minor": minor,
+        "version_patch": patch,
+        "format_version_major": FORMAT_VERSION_MAJOR,
+        "format_version_minor": FORMAT_VERSION_MINOR,
+        "max_alphabet_size": MAX_ALPHABET_SIZE,
+    }
+
+
+__all__ = [
+    "encode",
+    "decode",
+    "version",
+    "MAX_ALPHABET_SIZE",
+    "FORMAT_VERSION_MAJOR",
+    "FORMAT_VERSION_MINOR",
+    "__version__",
+]

triepack-1.3.1/triepack/bitstream.py

@@ -0,0 +1,160 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+"""Arbitrary-width bit I/O — MSB-first, matching src/bitstream/."""
+
+
+class BitWriter:
+    """Write arbitrary-width bit fields into a growable buffer."""
+
+    def __init__(self, initial_cap=256):
+        self._buf = bytearray(initial_cap or 256)
+        self._pos = 0  # bit position
+
+    @property
+    def position(self):
+        return self._pos
+
+    def _ensure(self, n_bits):
+        needed = (self._pos + n_bits + 7) >> 3
+        if needed <= len(self._buf):
+            return
+        new_cap = len(self._buf) * 2
+        while new_cap < needed:
+            new_cap *= 2
+        self._buf.extend(b"\x00" * (new_cap - len(self._buf)))
+
+    def write_bits(self, value, n):
+        if n == 0 or n > 64:
+            raise ValueError("write_bits: n must be 1..64")
+        self._ensure(n)
+        for i in range(n):
+            bit = (value >> (n - 1 - i)) & 1
+            byte_idx = self._pos >> 3
+            bit_idx = 7 - (self._pos & 7)
+            if bit:
+                self._buf[byte_idx] |= 1 << bit_idx
+            else:
+                self._buf[byte_idx] &= ~(1 << bit_idx)
+            self._pos += 1
+
+    def write_bit(self, val):
+        self._ensure(1)
+        byte_idx = self._pos >> 3
+        bit_idx = 7 - (self._pos & 7)
+        if val:
+            self._buf[byte_idx] |= 1 << bit_idx
+        else:
+            self._buf[byte_idx] &= ~(1 << bit_idx)
+        self._pos += 1
+
+    def write_u8(self, val):
+        self.write_bits(val & 0xFF, 8)
+
+    def write_u16(self, val):
+        self.write_bits(val & 0xFFFF, 16)
+
+    def write_u32(self, val):
+        self.write_bits(val & 0xFFFFFFFF, 32)
+
+    def write_u64(self, hi32, lo32):
+        self.write_bits((hi32 >> 0) & 0xFFFFFFFF, 32)
+        self.write_bits((lo32 >> 0) & 0xFFFFFFFF, 32)
+
+    def write_bytes(self, data):
+        for b in data:
+            self.write_u8(b)
+
+    def align_to_byte(self):
+        rem = self._pos & 7
+        if rem != 0:
+            pad = 8 - rem
+            self._ensure(pad)
+            self._pos += pad
+
+    def to_bytes(self):
+        length = (self._pos + 7) >> 3
+        return bytes(self._buf[:length])
+
+    def get_buffer(self):
+        return self._buf
+
+
+class BitReader:
+    """Read arbitrary-width bit fields from a buffer."""
+
+    def __init__(self, buf):
+        if isinstance(buf, (bytes, bytearray)):
+            self._buf = buf
+        else:
+            self._buf = bytes(buf)
+        self._bit_len = len(self._buf) * 8
+        self._pos = 0
+
+    @property
+    def position(self):
+        return self._pos
+
+    @property
+    def remaining(self):
+        return self._bit_len - self._pos
+
+    def seek(self, bit_pos):
+        self._pos = bit_pos
+
+    def advance(self, n_bits):
+        self._pos += n_bits
+
+    def read_bits(self, n):
+        if n == 0 or n > 64:
+            raise ValueError("read_bits: n must be 1..64")
+        if self._pos + n > self._bit_len:
+            raise EOFError("EOF")
+        val = 0
+        for i in range(n):
+            byte_idx = self._pos >> 3
+            bit_idx = 7 - (self._pos & 7)
+            val = (val << 1) | ((self._buf[byte_idx] >> bit_idx) & 1)
+            self._pos += 1
+        return val
+
+    def read_bit(self):
+        if self._pos >= self._bit_len:
+            raise EOFError("EOF")
+        byte_idx = self._pos >> 3
+        bit_idx = 7 - (self._pos & 7)
+        bit = (self._buf[byte_idx] >> bit_idx) & 1
+        self._pos += 1
+        return bit
+
+    def read_u8(self):
+        return self.read_bits(8)
+
+    def read_u16(self):
+        return self.read_bits(16)
+
+    def read_u32(self):
+        return self.read_bits(32)
+
+    def read_u64(self):
+        hi = self.read_u32()
+        lo = self.read_u32()
+        return hi * 0x100000000 + lo
+
+    def read_bytes(self, n):
+        out = bytearray(n)
+        for i in range(n):
+            out[i] = self.read_u8()
+        return bytes(out)
+
+    def peek_bits(self, n):
+        saved = self._pos
+        val = self.read_bits(n)
+        self._pos = saved
+        return val
+
+    def align_to_byte(self):
+        rem = self._pos & 7
+        if rem != 0:
+            self._pos += 8 - rem
+
+    def is_aligned(self):
+        return (self._pos & 7) == 0

triepack-1.3.1/triepack/crc32.py

@@ -0,0 +1,47 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+"""CRC-32 computation — standard polynomial (same table as C integrity.c)."""
+
+# fmt: off
+TABLE = [
+    0x00000000, 0x77073096, 0xEE0E612C, 0x990951BA, 0x076DC419, 0x706AF48F, 0xE963A535, 0x9E6495A3,
+    0x0EDB8832, 0x79DCB8A4, 0xE0D5E91E, 0x97D2D988, 0x09B64C2B, 0x7EB17CBD, 0xE7B82D07, 0x90BF1D91,
+    0x1DB71064, 0x6AB020F2, 0xF3B97148, 0x84BE41DE, 0x1ADAD47D, 0x6DDDE4EB, 0xF4D4B551, 0x83D385C7,
+    0x136C9856, 0x646BA8C0, 0xFD62F97A, 0x8A65C9EC, 0x14015C4F, 0x63066CD9, 0xFA0F3D63, 0x8D080DF5,
+    0x3B6E20C8, 0x4C69105E, 0xD56041E4, 0xA2677172, 0x3C03E4D1, 0x4B04D447, 0xD20D85FD, 0xA50AB56B,
+    0x35B5A8FA, 0x42B2986C, 0xDBBBC9D6, 0xACBCF940, 0x32D86CE3, 0x45DF5C75, 0xDCD60DCF, 0xABD13D59,
+    0x26D930AC, 0x51DE003A, 0xC8D75180, 0xBFD06116, 0x21B4F4B5, 0x56B3C423, 0xCFBA9599, 0xB8BDA50F,
+    0x2802B89E, 0x5F058808, 0xC60CD9B2, 0xB10BE924, 0x2F6F7C87, 0x58684C11, 0xC1611DAB, 0xB6662D3D,
+    0x76DC4190, 0x01DB7106, 0x98D220BC, 0xEFD5102A, 0x71B18589, 0x06B6B51F, 0x9FBFE4A5, 0xE8B8D433,
+    0x7807C9A2, 0x0F00F934, 0x9609A88E, 0xE10E9818, 0x7F6A0DBB, 0x086D3D2D, 0x91646C97, 0xE6635C01,
+    0x6B6B51F4, 0x1C6C6162, 0x856530D8, 0xF262004E, 0x6C0695ED, 0x1B01A57B, 0x8208F4C1, 0xF50FC457,
+    0x65B0D9C6, 0x12B7E950, 0x8BBEB8EA, 0xFCB9887C, 0x62DD1DDF, 0x15DA2D49, 0x8CD37CF3, 0xFBD44C65,
+    0x4DB26158, 0x3AB551CE, 0xA3BC0074, 0xD4BB30E2, 0x4ADFA541, 0x3DD895D7, 0xA4D1C46D, 0xD3D6F4FB,
+    0x4369E96A, 0x346ED9FC, 0xAD678846, 0xDA60B8D0, 0x44042D73, 0x33031DE5, 0xAA0A4C5F, 0xDD0D7CC9,
+    0x5005713C, 0x270241AA, 0xBE0B1010, 0xC90C2086, 0x5768B525, 0x206F85B3, 0xB966D409, 0xCE61E49F,
+    0x5EDEF90E, 0x29D9C998, 0xB0D09822, 0xC7D7A8B4, 0x59B33D17, 0x2EB40D81, 0xB7BD5C3B, 0xC0BA6CAD,
+    0xEDB88320, 0x9ABFB3B6, 0x03B6E20C, 0x74B1D29A, 0xEAD54739, 0x9DD277AF, 0x04DB2615, 0x73DC1683,
+    0xE3630B12, 0x94643B84, 0x0D6D6A3E, 0x7A6A5AA8, 0xE40ECF0B, 0x9309FF9D, 0x0A00AE27, 0x7D079EB1,
+    0xF00F9344, 0x8708A3D2, 0x1E01F268, 0x6906C2FE, 0xF762575D, 0x806567CB, 0x196C3671, 0x6E6B06E7,
+    0xFED41B76, 0x89D32BE0, 0x10DA7A5A, 0x67DD4ACC, 0xF9B9DF6F, 0x8EBEEFF9, 0x17B7BE43, 0x60B08ED5,
+    0xD6D6A3E8, 0xA1D1937E, 0x38D8C2C4, 0x4FDFF252, 0xD1BB67F1, 0xA6BC5767, 0x3FB506DD, 0x48B2364B,
+    0xD80D2BDA, 0xAF0A1B4C, 0x36034AF6, 0x41047A60, 0xDF60EFC3, 0xA867DF55, 0x316E8EEF, 0x4669BE79,
+    0xCB61B38C, 0xBC66831A, 0x256FD2A0, 0x5268E236, 0xCC0C7795, 0xBB0B4703, 0x220216B9, 0x5505262F,
+    0xC5BA3BBE, 0xB2BD0B28, 0x2BB45A92, 0x5CB36A04, 0xC2D7FFA7, 0xB5D0CF31, 0x2CD99E8B, 0x5BDEAE1D,
+    0x9B64C2B0, 0xEC63F226, 0x756AA39C, 0x026D930A, 0x9C0906A9, 0xEB0E363F, 0x72076785, 0x05005713,
+    0x95BF4A82, 0xE2B87A14, 0x7BB12BAE, 0x0CB61B38, 0x92D28E9B, 0xE5D5BE0D, 0x7CDCEFB7, 0x0BDBDF21,
+    0x86D3D2D4, 0xF1D4E242, 0x68DDB3F8, 0x1FDA836E, 0x81BE16CD, 0xF6B9265B, 0x6FB077E1, 0x18B74777,
+    0x88085AE6, 0xFF0F6A70, 0x66063BCA, 0x11010B5C, 0x8F659EFF, 0xF862AE69, 0x616BFFD3, 0x166CCF45,
+    0xA00AE278, 0xD70DD2EE, 0x4E048354, 0x3903B3C2, 0xA7672661, 0xD06016F7, 0x4969474D, 0x3E6E77DB,
+    0xAED16A4A, 0xD9D65ADC, 0x40DF0B66, 0x37D83BF0, 0xA9BCAE53, 0xDEBB9EC5, 0x47B2CF7F, 0x30B5FFE9,
+    0xBDBDF21C, 0xCABAC28A, 0x53B39330, 0x24B4A3A6, 0xBAD03605, 0xCDD70693, 0x54DE5729, 0x23D967BF,
+    0xB3667A2E, 0xC4614AB8, 0x5D681B02, 0x2A6F2B94, 0xB40BBE37, 0xC30C8EA1, 0x5A05DF1B, 0x2D02EF8D,
+]
+# fmt: on
+
+
+def crc32(data):
+    """Compute CRC-32 over *data* (bytes-like)."""
+    crc = 0xFFFFFFFF
+    for b in data:
+        crc = TABLE[(crc ^ b) & 0xFF] ^ ((crc >> 8) & 0x00FFFFFF)
+    return (crc ^ 0xFFFFFFFF) & 0xFFFFFFFF

triepack-1.3.1/triepack/decoder.py

@@ -0,0 +1,182 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+"""Trie decoder — port of src/core/decoder.c (via JavaScript decoder.js)."""
+
+from .bitstream import BitReader
+from .crc32 import crc32
+from .values import decode_value
+from .varint import read_var_uint
+
+# Format constants
+TP_MAGIC = bytes([0x54, 0x52, 0x50, 0x00])
+TP_HEADER_SIZE = 32
+TP_FLAG_HAS_VALUES = 1
+NUM_CONTROL_CODES = 6
+
+# Control code indices
+CTRL_END = 0
+CTRL_END_VAL = 1
+CTRL_SKIP = 2
+CTRL_BRANCH = 5
+
+
+def decode(buffer):
+    """Decode a .trp binary buffer into a dict. Returns dict."""
+    if not isinstance(buffer, (bytes, bytearray)):
+        raise TypeError("decode expects bytes or bytearray")
+    if len(buffer) < TP_HEADER_SIZE + 4:
+        raise ValueError("Data too short for .trp format")
+
+    buf = bytes(buffer)
+
+    # Validate magic
+    for i in range(4):
+        if buf[i] != TP_MAGIC[i]:
+            raise ValueError("Invalid magic bytes — not a .trp file")
+
+    # Version
+    version_major = buf[4]
+    if version_major != 1:
+        raise ValueError(f"Unsupported format version: {version_major}")
+
+    # Flags
+    flags = (buf[6] << 8) | buf[7]
+    has_values = (flags & TP_FLAG_HAS_VALUES) != 0
+
+    # num_keys
+    num_keys = (buf[8] << 24) | (buf[9] << 16) | (buf[10] << 8) | buf[11]
+
+    # Offsets
+    trie_data_offset = (buf[12] << 24) | (buf[13] << 16) | (buf[14] << 8) | buf[15]
+    value_store_offset = (buf[16] << 24) | (buf[17] << 16) | (buf[18] << 8) | buf[19]
+
+    # CRC verification
+    crc_data_len = len(buf) - 4
+    expected_crc = (
+        (buf[crc_data_len] << 24)
+        | (buf[crc_data_len + 1] << 16)
+        | (buf[crc_data_len + 2] << 8)
+        | buf[crc_data_len + 3]
+    )
+    actual_crc = crc32(buf[:crc_data_len])
+    if actual_crc != expected_crc:
+        raise ValueError("CRC-32 integrity check failed")
+
+    if num_keys == 0:
+        return {}
+
+    # Parse trie config
+    reader = BitReader(buf)
+    data_start = TP_HEADER_SIZE * 8
+
+    reader.seek(data_start)
+    bps = reader.read_bits(4)
+    # Symbol codes index 256-entry maps, so a symbol may not be wider than a
+    # byte; 0 would make the trie unreadable.
+    if bps < 1 or bps > 8:
+        raise ValueError(f"Invalid trie config: bits_per_symbol must be 1..8, got {bps}")
+    symbol_count = reader.read_bits(8)
+    # Must leave room for the control codes and fit in bits_per_symbol.
+    if symbol_count < NUM_CONTROL_CODES or symbol_count > (1 << bps):
+        raise ValueError(f"Invalid trie config: symbol_count out of range: {symbol_count}")
+
+    # Read control codes
+    ctrl_codes = [0] * NUM_CONTROL_CODES
+    code_is_ctrl = [False] * 256
+    for c in range(NUM_CONTROL_CODES):
+        ctrl_codes[c] = reader.read_bits(bps)
+        if ctrl_codes[c] < 256:
+            code_is_ctrl[ctrl_codes[c]] = True
+
+    # Read symbol table
+    reverse_map = [0] * 256
+    for cd in range(NUM_CONTROL_CODES, symbol_count):
+        cp = read_var_uint(reader)
+        if cd < 256 and cp < 256:
+            reverse_map[cd] = cp
+
+    trie_start = data_start + trie_data_offset
+    value_start = data_start + value_store_offset
+    # The trie occupies [trie_start, value_start); the value store (when
+    # present), the byte padding and the CRC follow it.
+    trie_end = value_start
+
+    # DFS iteration
+    result = {}
+    key_stack = []
+
+    # Every subtree knows where it ends: a child with a SKIP ends at
+    # child_start + skip_dist, the last child ends where its parent does, and
+    # the root ends at trie_end. `end` is the only authority on whether more
+    # symbols belong to this subtree -- the bits that happen to follow are
+    # not, because past the last terminal they are padding and CRC.
+    def dfs_walk(r, end):
+        while True:
+            if r.position >= end:
+                return
+            sym = r.read_bits(bps)
+
+            if sym == ctrl_codes[CTRL_END]:
+                key_str = bytes(key_stack).decode("utf-8")
+                result[key_str] = None
+                walk_branch_if_present(r, end)
+                return
+
+            if sym == ctrl_codes[CTRL_END_VAL]:
+                read_var_uint(r)  # value index
+                key_str = bytes(key_stack).decode("utf-8")
+                result[key_str] = None
+                walk_branch_if_present(r, end)
+                return
+
+            if sym == ctrl_codes[CTRL_BRANCH]:
+                child_count = read_var_uint(r)
+                walk_branch(r, child_count, end)
+                return
+
+            # Regular symbol
+            byte_val = reverse_map[sym] if sym < 256 else 0
+            key_stack.append(byte_val)
+
+    # A terminal is followed by a BRANCH exactly when the subtree has not
+    # reached its end -- keys that share this terminal as a prefix.
+    def walk_branch_if_present(r, end):
+        if r.position >= end:
+            return
+        sym = r.read_bits(bps)
+        if sym != ctrl_codes[CTRL_BRANCH]:
+            raise ValueError("Malformed trie: expected BRANCH after terminal")
+        child_count = read_var_uint(r)
+        walk_branch(r, child_count, end)
+
+    def walk_branch(r, child_count, end):
+        saved_key_len = len(key_stack)
+        for ci in range(child_count):
+            has_skip = ci < child_count - 1
+            skip_dist = 0
+
+            if has_skip:
+                r.read_bits(bps)  # SKIP control code
+                skip_dist = read_var_uint(r)
+
+            child_start_pos = r.position
+            del key_stack[saved_key_len:]
+            dfs_walk(r, child_start_pos + skip_dist if has_skip else end)
+
+            if has_skip:
+                r.seek(child_start_pos + skip_dist)
+
+        del key_stack[saved_key_len:]
+
+    # Walk the trie
+    reader.seek(trie_start)
+    if num_keys > 0:
+        dfs_walk(reader, trie_end)
+
+    # Decode values
+    if has_values:
+        reader.seek(value_start)
+        sorted_keys = sorted(result.keys(), key=lambda k: k.encode("utf-8"))
+        for key in sorted_keys:
+            result[key] = decode_value(reader)
+
+    return result

triepack-1.3.1/triepack/encoder.py

@@ -0,0 +1,346 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+"""Trie encoder — port of src/core/encoder.c (via JavaScript encoder.js)."""
+
+from .bitstream import BitWriter
+from .crc32 import crc32
+from .values import encode_value
+from .varint import var_uint_bits, write_var_uint
+
+# Format constants (match core_internal.h)
+TP_MAGIC = bytes([0x54, 0x52, 0x50, 0x00])  # "TRP\0"
+TP_VERSION_MAJOR = 1
+TP_VERSION_MINOR = 0
+TP_HEADER_SIZE = 32
+TP_FLAG_HAS_VALUES = 1
+
+# Control code indices
+CTRL_END = 0
+CTRL_END_VAL = 1
+CTRL_SKIP = 2
+# CTRL_SUFFIX = 3
+# CTRL_ESCAPE = 4
+CTRL_BRANCH = 5
+NUM_CONTROL_CODES = 6
+
+# Largest number of distinct byte values the keys may use: symbol_count is an
+# 8-bit header field holding the alphabet plus the control codes.
+MAX_ALPHABET_SIZE = 255 - NUM_CONTROL_CODES  # 249
+
+
+def encode(data):
+    """Encode a dict into the .trp binary format. Returns bytes."""
+    if not isinstance(data, dict):
+        raise TypeError("encode expects a dict")
+
+    # Collect entries: (key_bytes, val)
+    entries = []
+    for k, v in data.items():
+        key_bytes = k.encode("utf-8") if isinstance(k, str) else bytes(k)
+        entries.append((key_bytes, v))
+
+    # Sort lexicographically by key bytes
+    entries.sort(key=lambda e: e[0])
+
+    deduped = entries  # dict keys are unique; no dedup needed
+
+    # Determine if any entries have non-null values
+    has_values = any(e[1] is not None for e in deduped)
+
+    # Symbol analysis
+    used = [False] * 256
+    for kb, _ in deduped:
+        for b in kb:
+            used[b] = True
+
+    alphabet_size = sum(used)
+    total_symbols = alphabet_size + NUM_CONTROL_CODES
+    # The trie config packs symbol_count into 8 header bits, so the alphabet
+    # plus the 6 control codes must fit in 255. Encoding a wider alphabet used
+    # to produce a buffer with a valid CRC that decoded to nothing.
+    if total_symbols > 255:
+        raise ValueError(
+            f"Keys use too many distinct byte values ({alphabet_size}); "
+            f"the format allows at most {MAX_ALPHABET_SIZE}"
+        )
+    bps = 1
+    while (1 << bps) < total_symbols:
+        bps += 1
+
+    # Control codes: 0..5
+    ctrl_codes = list(range(NUM_CONTROL_CODES))
+
+    # Symbol map: byte value -> N-bit code
+    symbol_map = [0] * 256
+    reverse_map = [0] * 256
+    code = NUM_CONTROL_CODES
+    for i in range(256):
+        if used[i]:
+            symbol_map[i] = code
+            if code < 256:
+                reverse_map[code] = i
+            code += 1
+
+    # Build the bitstream
+    w = BitWriter(256)
+
+    # Write 32-byte header placeholder
+    for b in TP_MAGIC:
+        w.write_u8(b)
+    w.write_u8(TP_VERSION_MAJOR)
+    w.write_u8(TP_VERSION_MINOR)
+    flags = TP_FLAG_HAS_VALUES if has_values else 0
+    w.write_u16(flags)
+    w.write_u32(len(deduped))  # num_keys
+    w.write_u32(0)  # trie_data_offset placeholder
+    w.write_u32(0)  # value_store_offset placeholder
+    w.write_u32(0)  # suffix_table_offset placeholder
+    w.write_u32(0)  # total_data_bits placeholder
+    w.write_u32(0)  # reserved
+
+    data_start = w.position  # should be 256 (32 bytes * 8)
+
+    # Trie config: bits_per_symbol (4 bits) + symbol_count (8 bits)
+    w.write_bits(bps, 4)
+    w.write_bits(total_symbols, 8)
+
+    # Control code mappings
+    for c in range(NUM_CONTROL_CODES):
+        w.write_bits(ctrl_codes[c], bps)
+
+    # Symbol table
+    for cd in range(NUM_CONTROL_CODES, total_symbols):
+        byte_val = reverse_map[cd] if cd < 256 else 0
+        write_var_uint(w, byte_val)
+
+    trie_data_offset = w.position - data_start
+
+    # Write prefix trie
+    ctx = {
+        "deduped": deduped,
+        "bps": bps,
+        "symbol_map": symbol_map,
+        "ctrl_codes": ctrl_codes,
+        "has_values": has_values,
+    }
+    value_idx = [0]
+    if deduped:
+        _trie_write(ctx, w, 0, len(deduped), 0, value_idx)
+
+    value_store_offset = w.position - data_start
+
+    # Write value store
+    if has_values:
+        for _, val in deduped:
+            encode_value(w, val)
+
+    total_data_bits = w.position - data_start
+
+    w.align_to_byte()
+
+    # Get pre-CRC buffer
+    pre_crc_buf = bytearray(w.to_bytes())
+    crc_val = crc32(pre_crc_buf)
+
+    # Append CRC
+    w.write_u32(crc_val)
+
+    out_buf = bytearray(w.to_bytes())
+
+    # Patch header offsets
+    _patch_u32(out_buf, 12, trie_data_offset)
+    _patch_u32(out_buf, 16, value_store_offset)
+    _patch_u32(out_buf, 20, 0)  # suffix_table_offset
+    _patch_u32(out_buf, 24, total_data_bits)
+
+    # Recompute CRC over patched data
+    crc_data_len = len(out_buf) - 4
+    crc_val = crc32(out_buf[:crc_data_len])
+    _patch_u32(out_buf, crc_data_len, crc_val)
+
+    return bytes(out_buf)
+
+
+def _patch_u32(buf, offset, value):
+    buf[offset] = (value >> 24) & 0xFF
+    buf[offset + 1] = (value >> 16) & 0xFF
+    buf[offset + 2] = (value >> 8) & 0xFF
+    buf[offset + 3] = value & 0xFF
+
+
+def _trie_subtree_size(ctx, start, end, prefix_len, value_idx):
+    """Compute subtree size in bits (dry run)."""
+    deduped = ctx["deduped"]
+    bps = ctx["bps"]
+    has_values = ctx["has_values"]
+    bits = 0
+
+    # Find common prefix beyond prefix_len
+    common = prefix_len
+    while True:
+        all_have = True
+        ch = 0
+        for i in range(start, end):
+            if len(deduped[i][0]) <= common:
+                all_have = False
+                break
+            if i == start:
+                ch = deduped[i][0][common]
+            elif deduped[i][0][common] != ch:
+                all_have = False
+                break
+        if not all_have:
+            break
+        common += 1
+
+    bits += (common - prefix_len) * bps
+
+    has_terminal = len(deduped[start][0]) == common
+    children_start = start + 1 if has_terminal else start
+
+    # Count children
+    child_count = 0
+    cs = children_start
+    while cs < end:
+        child_count += 1
+        ch = deduped[cs][0][common]
+        ce = cs + 1
+        while ce < end and deduped[ce][0][common] == ch:
+            ce += 1
+        cs = ce
+
+    if has_terminal and child_count == 0:
+        if has_values and deduped[start][1] is not None:
+            bits += bps
+            bits += var_uint_bits(value_idx[0])
+        else:
+            bits += bps
+        value_idx[0] += 1
+    elif has_terminal and child_count > 0:
+        if has_values and deduped[start][1] is not None:
+            bits += bps
+            bits += var_uint_bits(value_idx[0])
+        else:
+            bits += bps
+        value_idx[0] += 1
+        bits += bps
+        bits += var_uint_bits(child_count)
+
+        cs = children_start
+        child_i = 0
+        while cs < end:
+            ch = deduped[cs][0][common]
+            ce = cs + 1
+            while ce < end and deduped[ce][0][common] == ch:
+                ce += 1
+            if child_i < child_count - 1:
+                child_sz = _trie_subtree_size(ctx, cs, ce, common, value_idx)
+                bits += bps
+                bits += var_uint_bits(child_sz)
+                bits += child_sz
+            else:
+                bits += _trie_subtree_size(ctx, cs, ce, common, value_idx)
+            child_i += 1
+            cs = ce
+    else:  # not has_terminal, child_count > 1
+        bits += bps
+        bits += var_uint_bits(child_count)
+
+        cs = children_start
+        child_i = 0
+        while cs < end:
+            ch = deduped[cs][0][common]
+            ce = cs + 1
+            while ce < end and deduped[ce][0][common] == ch:
+                ce += 1
+            if child_i < child_count - 1:
+                child_sz = _trie_subtree_size(ctx, cs, ce, common, value_idx)
+                bits += bps
+                bits += var_uint_bits(child_sz)
+                bits += child_sz
+            else:
+                bits += _trie_subtree_size(ctx, cs, ce, common, value_idx)
+            child_i += 1
+            cs = ce
+
+    return bits
+
+
+def _trie_write(ctx, w, start, end, prefix_len, value_idx):
+    """Write the trie subtree."""
+    deduped = ctx["deduped"]
+    bps = ctx["bps"]
+    symbol_map = ctx["symbol_map"]
+    ctrl_codes = ctx["ctrl_codes"]
+    has_values = ctx["has_values"]
+
+    # Find common prefix beyond prefix_len
+    common = prefix_len
+    while True:
+        all_have = True
+        ch = 0
+        for i in range(start, end):
+            if len(deduped[i][0]) <= common:
+                all_have = False
+                break
+            if i == start:
+                ch = deduped[i][0][common]
+            elif deduped[i][0][common] != ch:
+                all_have = False
+                break
+        if not all_have:
+            break
+        common += 1
+
+    # Write common prefix symbols
+    for i in range(prefix_len, common):
+        ch = deduped[start][0][i]
+        w.write_bits(symbol_map[ch], bps)
+
+    has_terminal = len(deduped[start][0]) == common
+    children_start = start + 1 if has_terminal else start
+
+    # Count children
+    child_count = 0
+    cs = children_start
+    while cs < end:
+        child_count += 1
+        ch = deduped[cs][0][common]
+        ce = cs + 1
+        while ce < end and deduped[ce][0][common] == ch:
+            ce += 1
+        cs = ce
+
+    # Write terminal
+    if has_terminal:
+        if has_values and deduped[start][1] is not None:
+            w.write_bits(ctrl_codes[CTRL_END_VAL], bps)
+            write_var_uint(w, value_idx[0])
+        else:
+            w.write_bits(ctrl_codes[CTRL_END], bps)
+        value_idx[0] += 1
+
+    if child_count == 0:
+        return
+
+    # BRANCH
+    w.write_bits(ctrl_codes[CTRL_BRANCH], bps)
+    write_var_uint(w, child_count)
+
+    cs = children_start
+    child_i = 0
+    while cs < end:
+        ch = deduped[cs][0][common]
+        ce = cs + 1
+        while ce < end and deduped[ce][0][common] == ch:
+            ce += 1
+
+        if child_i < child_count - 1:
+            vi_copy = [value_idx[0]]
+            child_sz = _trie_subtree_size(ctx, cs, ce, common, vi_copy)
+            w.write_bits(ctrl_codes[CTRL_SKIP], bps)
+            write_var_uint(w, child_sz)
+
+        _trie_write(ctx, w, cs, ce, common, value_idx)
+
+        child_i += 1
+        cs = ce

triepack-1.3.1/triepack/values.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+"""Value encoder/decoder for 8 type tags — matches src/core/value.c."""
+
+import struct
+
+from .varint import read_var_int, read_var_uint, write_var_int, write_var_uint
+
+# Type tags (4-bit, matches tp_value_type enum)
+TP_NULL = 0
+TP_BOOL = 1
+TP_INT = 2
+TP_UINT = 3
+TP_FLOAT32 = 4
+TP_FLOAT64 = 5
+TP_STRING = 6
+TP_BLOB = 7
+
+
+def encode_value(writer, val):
+    """Encode a Python value into the bitstream."""
+    if val is None:
+        writer.write_bits(TP_NULL, 4)
+        return
+
+    if isinstance(val, bool):
+        writer.write_bits(TP_BOOL, 4)
+        writer.write_bit(1 if val else 0)
+        return
+
+    if isinstance(val, int):
+        if val < 0:
+            writer.write_bits(TP_INT, 4)
+            write_var_int(writer, val)
+        else:
+            writer.write_bits(TP_UINT, 4)
+            write_var_uint(writer, val)
+        return
+
+    if isinstance(val, float):
+        writer.write_bits(TP_FLOAT64, 4)
+        packed = struct.pack(">d", val)
+        hi = struct.unpack(">I", packed[:4])[0]
+        lo = struct.unpack(">I", packed[4:])[0]
+        writer.write_u64(hi, lo)
+        return
+
+    if isinstance(val, str):
+        encoded = val.encode("utf-8")
+        writer.write_bits(TP_STRING, 4)
+        write_var_uint(writer, len(encoded))
+        writer.align_to_byte()
+        writer.write_bytes(encoded)
+        return
+
+    if isinstance(val, (bytes, bytearray)):
+        writer.write_bits(TP_BLOB, 4)
+        write_var_uint(writer, len(val))
+        writer.align_to_byte()
+        writer.write_bytes(val)
+        return
+
+    raise TypeError(f"Unsupported value type: {type(val)}")
+
+
+def decode_value(reader):
+    """Decode a value from the bitstream."""
+    tag = reader.read_bits(4)
+
+    if tag == TP_NULL:
+        return None
+    if tag == TP_BOOL:
+        return reader.read_bit() != 0
+    if tag == TP_INT:
+        return read_var_int(reader)
+    if tag == TP_UINT:
+        return read_var_uint(reader)
+    if tag == TP_FLOAT32:
+        bits = reader.read_u32()
+        packed = struct.pack(">I", bits)
+        return struct.unpack(">f", packed)[0]
+    if tag == TP_FLOAT64:
+        hi = reader.read_u32()
+        lo = reader.read_u32()
+        packed = struct.pack(">II", hi, lo)
+        return struct.unpack(">d", packed)[0]
+    if tag == TP_STRING:
+        slen = read_var_uint(reader)
+        reader.align_to_byte()
+        raw = reader.read_bytes(slen)
+        return raw.decode("utf-8")
+    if tag == TP_BLOB:
+        blen = read_var_uint(reader)
+        reader.align_to_byte()
+        return reader.read_bytes(blen)
+
+    raise ValueError(f"Unknown value type tag: {tag}")

triepack-1.3.1/triepack/varint.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 M. A. Chatterjee, BSD-2-Clause.
+"""LEB128 unsigned VarInt + zigzag signed VarInt — matches bitstream_varint.c."""
+
+VARINT_MAX_GROUPS = 10
+
+
+def write_var_uint(writer, value):
+    """Write an unsigned LEB128 VarInt."""
+    if value < 0:
+        raise ValueError("write_var_uint: negative value")
+    while True:
+        byte = value & 0x7F
+        value >>= 7
+        if value > 0:
+            byte |= 0x80
+        writer.write_u8(byte)
+        if value == 0:
+            break
+
+
+def read_var_uint(reader):
+    """Read an unsigned LEB128 VarInt."""
+    val = 0
+    shift = 0
+    for _ in range(VARINT_MAX_GROUPS):
+        byte = reader.read_u8()
+        val |= (byte & 0x7F) << shift
+        if (byte & 0x80) == 0:
+            return val
+        shift += 7
+    raise OverflowError("VarInt overflow")
+
+
+def write_var_int(writer, value):
+    """Write a signed zigzag VarInt."""
+    if value >= 0:
+        raw = value * 2
+    else:
+        raw = (-value) * 2 - 1
+    write_var_uint(writer, raw)
+
+
+def read_var_int(reader):
+    """Read a signed zigzag VarInt."""
+    raw = read_var_uint(reader)
+    if raw & 1:
+        return -(raw >> 1) - 1
+    return raw >> 1
+
+
+def var_uint_bits(val):
+    """Return the number of bits needed to encode val as a VarInt."""
+    bits = 0
+    while True:
+        bits += 8
+        val >>= 7
+        if val == 0:
+            break
+    return bits

triepack-1.3.1/triepack.egg-info/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: triepack
+Version: 1.3.1
+Summary: Compressed trie dictionary format (.trp) — compact binary key-value storage with fast lookups and prefix search. Pure Python, no dependencies.
+Author-email: "M. A. Chatterjee" <deftio@deftio.com>
+License-Expression: BSD-2-Clause
+Project-URL: Homepage, https://deftio.github.io/triepack/
+Project-URL: Documentation, https://deftio.github.io/triepack/guide/api-reference/
+Project-URL: Repository, https://github.com/deftio/triepack
+Project-URL: Issues, https://github.com/deftio/triepack/issues
+Project-URL: Changelog, https://github.com/deftio/triepack/blob/main/CHANGELOG.md
+Keywords: trie,prefix-tree,dictionary,binary-format,serialization,compression,key-value,prefix-search,trp,triepack
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# triepack
+
+Compressed trie dictionary format (`.trp`) — compact binary key-value storage
+with fast lookups and prefix search.
+
+This is the native Python implementation: pure Python, no dependencies, no C
+extension to build. It reads and writes the same bytes as the C reference
+library and the JavaScript, Go, Rust, Swift, Java and Kotlin implementations.
+
+## Install
+
+```bash
+pip install triepack
+```
+
+## Use
+
+```python
+from triepack import encode, decode
+
+buf = encode({"hello": 42, "world": "foo"})
+# buf is bytes holding the .trp binary
+
+result = decode(buf)
+print(result)  # {'hello': 42, 'world': 'foo'}
+```
+
+## Values
+
+| Python            | `.trp` type        |
+|-------------------|--------------------|
+| `None`            | null               |
+| `bool`            | bool               |
+| `int >= 0`        | uint               |
+| `int < 0`         | int                |
+| `float`           | float64            |
+| `str`             | string (UTF-8)     |
+| `bytes`           | blob               |
+
+Decoding also accepts float32 values written by other implementations,
+widening them to a Python float. Python integers are arbitrary precision, so
+the full 64-bit signed and unsigned ranges round-trip exactly.
+
+## Format
+
+Every buffer carries a 32-byte header, a bit-packed prefix trie, a typed value
+store and a CRC-32. Keys are stored once per shared prefix, and symbols are
+packed at the minimum width the key alphabet needs.
+
+The encoder is deterministic: the same input produces the same bytes in every
+implementation, which is checked by a
+[shared conformance suite](https://github.com/deftio/triepack/tree/main/tests/conformance)
+that all nine implementations run.
+
+## Links
+
+- [Documentation](https://deftio.github.io/triepack/)
+- [API reference](https://deftio.github.io/triepack/guide/api-reference/)
+- [Source and issues](https://github.com/deftio/triepack)
+- [Changelog](https://github.com/deftio/triepack/blob/main/CHANGELOG.md)
+
+## Development
+
+```bash
+cd bindings/python
+pip install -e ".[test]"
+python -m pytest
+```
+
+## License
+
+Copyright (c) 2026 M. A. Chatterjee. BSD-2-Clause — see
+[LICENSE.txt](LICENSE.txt).

triepack-1.3.1/triepack.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+triepack/__init__.py
+triepack/bitstream.py
+triepack/crc32.py
+triepack/decoder.py
+triepack/encoder.py
+triepack/values.py
+triepack/varint.py
+triepack.egg-info/PKG-INFO
+triepack.egg-info/SOURCES.txt
+triepack.egg-info/dependency_links.txt
+triepack.egg-info/requires.txt
+triepack.egg-info/top_level.txt

triepack-1.3.1/triepack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

triepack-1.3.1/triepack.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest

triepack-1.3.1/triepack.egg-info/top_level.txt

@@ -0,0 +1 @@
+triepack