virtuals-binary-codec 0.1.0__tar.gz → 0.1.2__tar.gz

{virtuals_binary_codec-0.1.0/src/virtuals_binary_codec.egg-info → virtuals_binary_codec-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtuals-binary-codec
-Version: 0.1.0
+Version: 0.1.2
 Summary: Cython-optimized binary key codec for Virtuals.
 Author-email: Gor Arakelyan <gorarkln@gmail.com>
 License-Expression: Apache-2.0

{virtuals_binary_codec-0.1.0 → virtuals_binary_codec-0.1.2}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
 # ============================================================================
 [project]
 name = "virtuals-binary-codec"
-version = "0.1.0"
+version = "0.1.2"
 description = "Cython-optimized binary key codec for Virtuals."
 readme = "README.md"
 license = "Apache-2.0"

{virtuals_binary_codec-0.1.0 → virtuals_binary_codec-0.1.2}/src/virtuals_binary_codec/binary_codec.pyi

@@ -12,3 +12,7 @@ class BinaryKeyCodec:
     def decode(self, encoded: bytes) -> tuple[str | int, ...]:
         """Decode binary data back to original tuple key."""
         ...
+
+    def upper_bound_of_prefix(self, key: tuple[str | int, ...]) -> bytes:
+        r"""Bytes strictly greater than every child key of ``key`` (``encode(key) + b"\xff"``)."""
+        ...

{virtuals_binary_codec-0.1.0 → virtuals_binary_codec-0.1.2}/src/virtuals_binary_codec/binary_codec.pyx

@@ -132,6 +132,11 @@ cdef class BinaryKeyCodec:
     - Null bytes in content: 0x00 -> 0x00 0xFF (escaped)
     - Terminator is bare 0x00 (not escaped)
     - This ensures shorter strings sort before longer strings with same prefix
+
+    Empty strings:
+    - "" encodes as 0x02 0x00 and sorts before every other string
+    - Unambiguous: a terminator is followed by a type marker (0x01/0x02) or
+      the end of the key, never by the escape byte 0xFF
     """
 
     def encode(self, tuple key):
@@ -180,9 +185,9 @@ cdef class BinaryKeyCodec:
                 str_data = <const unsigned char*>PyBytes_AS_STRING(str_bytes)
                 str_len = PyBytes_GET_SIZE(str_bytes)
 
-                # Check string length bounds
-                if str_len == 0:
-                    raise EncodeError(f"Empty string at index {i} not allowed")
+                # Check string length bound. The empty string is legal: it
+                # encodes as TYPE_STR + TERMINATOR and sorts before every
+                # other string.
                 if str_len > MAX_STRING_LENGTH:
                     raise EncodeError(
                         f"String at index {i} too long: {str_len} bytes "
@@ -241,6 +246,24 @@ cdef class BinaryKeyCodec:
 
         return result
 
+    def upper_bound_of_prefix(self, tuple key):
+        """Encoded bytes strictly greater than every child key of ``key``.
+
+        Appends ``0xFF`` to ``encode(key)``. The trailing 0xFF sorts strictly
+        above every valid segment type marker (``TYPE_INT=0x01``, ``TYPE_STR=0x02``),
+        so any child key of the form ``key + (segment,)`` compares less than
+        the returned bytes. Used by container-side reverse scans to seed
+        ``StorageScanOptions.start`` with an inclusive upper bound of the
+        child prefix range.
+
+        Args:
+            key: Tuple containing strings and/or integers
+
+        Returns:
+            Binary bytes that sort strictly greater than every child key of ``key``
+        """
+        return self.encode(key) + b"\xff"
+
     def decode(self, bytes encoded):
         """Decode binary data back to original tuple key.
 

{virtuals_binary_codec-0.1.0 → virtuals_binary_codec-0.1.2/src/virtuals_binary_codec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtuals-binary-codec
-Version: 0.1.0
+Version: 0.1.2
 Summary: Cython-optimized binary key codec for Virtuals.
 Author-email: Gor Arakelyan <gorarkln@gmail.com>
 License-Expression: Apache-2.0