Field Paths

Decodes Huffman-coded field path operations used to address properties inside entity deltas.

See also: Field Paths & Huffman

gem.field_path.read_field_paths(r: BitReader) -> list[FieldPath]

Decode a Huffman-coded sequence of field paths from r.

Uses a flat O(1) decode table to resolve each Huffman op in a single peek + skip rather than a per-bit tree walk. The peek/skip/rem_bits calls are inlined directly against BitReader's private attributes to eliminate ~22M Python function calls per replay.

Falls back to the tree walk for the last few bits when fewer than _HUFF_TABLE_BITS bits remain in the buffer.

Parameters:

Name	Type	Description	Default
r	BitReader	BitReader positioned at the start of the field path sequence.	required

Returns:

Type	Description
list[FieldPath]	List of FieldPath objects, one per updated field (not including the
list[FieldPath]	finish sentinel).

Source code in src/gem/field_path.py

def read_field_paths(r: BitReader) -> list[FieldPath]:
    """Decode a Huffman-coded sequence of field paths from r.

    Uses a flat O(1) decode table to resolve each Huffman op in a single
    peek + skip rather than a per-bit tree walk.  The peek/skip/rem_bits
    calls are inlined directly against BitReader's private attributes to
    eliminate ~22M Python function calls per replay.

    Falls back to the tree walk for the last few bits when fewer than
    ``_HUFF_TABLE_BITS`` bits remain in the buffer.

    Args:
        r: BitReader positioned at the start of the field path sequence.

    Returns:
        List of FieldPath objects, one per updated field (not including the
        finish sentinel).
    """
    fp = FieldPath()
    paths: list[FieldPath] = []
    ops = FIELD_PATH_OPS
    table = _HUFF_DECODE_TABLE
    table_bits = _HUFF_TABLE_BITS
    mask = (1 << table_bits) - 1

    buf = r._buf
    size = r._size
    unpack_from = struct.unpack_from

    while not fp.done:
        # Inline rem_bits: (size - pos) * 8 + bit_count
        if (size - r._pos) * 8 + r._bit_count >= table_bits:
            # Inline peek_bits(table_bits): refill then read without consuming
            while table_bits > r._bit_count:
                remaining = size - r._pos
                if remaining >= 4:
                    r._bit_val |= unpack_from("<I", buf, r._pos)[0] << r._bit_count
                    r._pos += 4
                    r._bit_count += 32
                elif remaining > 0:
                    r._bit_val |= buf[r._pos] << r._bit_count
                    r._pos += 1
                    r._bit_count += 8
                else:
                    break
            bits = r._bit_val & mask
            op_idx, consumed = table[bits]
            # Inline skip_bits(consumed)
            r._bit_val >>= consumed
            r._bit_count -= consumed
        else:
            # Fallback: tree walk for the last few bits
            node = HUFF_TREE
            while not node.is_leaf:
                node = node.right if r.read_bits(1) else node.left  # type: ignore[assignment]
            op_idx = node.value

        ops[op_idx].fn(r, fp)
        if not fp.done:
            paths.append(fp.copy())

    return paths

---

gem.field_path.FieldPath

A mutable path of up to 7 integer field indices.

Starts at path = [-1, 0, 0, 0, 0, 0, 0], last = 0. Operations mutate path and last in place.

Attributes:

Name	Type	Description
path	list[int]	Seven-element list; active indices are path[0:last+1].
last	int	Index of the deepest active level (0-based).
done	bool	Set to True by FieldPathEncodeFinish to stop iteration.

Source code in src/gem/field_path.py

class FieldPath:
    """A mutable path of up to 7 integer field indices.

    Starts at ``path = [-1, 0, 0, 0, 0, 0, 0]``, ``last = 0``.
    Operations mutate ``path`` and ``last`` in place.

    Attributes:
        path: Seven-element list; active indices are ``path[0:last+1]``.
        last: Index of the deepest active level (0-based).
        done: Set to True by ``FieldPathEncodeFinish`` to stop iteration.
    """

    __slots__ = ("path", "last", "done")

    def __init__(self) -> None:
        self.path: list[int] = [-1, 0, 0, 0, 0, 0, 0]
        self.last: int = 0
        self.done: bool = False

    def reset(self) -> None:
        """Reset to the initial empty state."""
        self.path[:] = _RESET
        self.last = 0
        self.done = False

    def pop(self, n: int) -> None:
        """Pop n levels off the path, zeroing the vacated slots.

        Args:
            n: Number of levels to remove.
        """
        for _ in range(n):
            self.path[self.last] = 0
            self.last -= 1

    def copy(self) -> FieldPath:
        """Return an independent copy of this path.

        Returns:
            A new FieldPath with identical state.
        """
        fp = FieldPath()
        fp.path[:] = self.path
        fp.last = self.last
        fp.done = self.done
        return fp

    def to_tuple(self) -> tuple[int, ...]:
        """Return the active indices as an immutable tuple.

        Returns:
            Tuple of active integer indices, e.g. ``(2, 0, 5)``.
        """
        return tuple(self.path[: self.last + 1])

    def to_str(self) -> str:
        """Return a slash-separated string of active indices.

        Returns:
            String like ``"2/0/5"``.
        """
        return "/".join(str(self.path[i]) for i in range(self.last + 1))

    def plus_one(self) -> None:
        """Increment the deepest index by 1."""
        self.path[self.last] += 1

reset() -> None

Reset to the initial empty state.

Source code in src/gem/field_path.py

def reset(self) -> None:
    """Reset to the initial empty state."""
    self.path[:] = _RESET
    self.last = 0
    self.done = False

pop(n: int) -> None

Pop n levels off the path, zeroing the vacated slots.

Parameters:

Name	Type	Description	Default
n	int	Number of levels to remove.	required

Source code in src/gem/field_path.py

def pop(self, n: int) -> None:
    """Pop n levels off the path, zeroing the vacated slots.

    Args:
        n: Number of levels to remove.
    """
    for _ in range(n):
        self.path[self.last] = 0
        self.last -= 1

copy() -> FieldPath

Return an independent copy of this path.

Returns:

Type	Description
FieldPath	A new FieldPath with identical state.

Source code in src/gem/field_path.py

def copy(self) -> FieldPath:
    """Return an independent copy of this path.

    Returns:
        A new FieldPath with identical state.
    """
    fp = FieldPath()
    fp.path[:] = self.path
    fp.last = self.last
    fp.done = self.done
    return fp

to_tuple() -> tuple[int, ...]

Return the active indices as an immutable tuple.

Returns:

Type	Description
tuple[int, ...]	Tuple of active integer indices, e.g. (2, 0, 5).

Source code in src/gem/field_path.py

def to_tuple(self) -> tuple[int, ...]:
    """Return the active indices as an immutable tuple.

    Returns:
        Tuple of active integer indices, e.g. ``(2, 0, 5)``.
    """
    return tuple(self.path[: self.last + 1])

to_str() -> str

Return a slash-separated string of active indices.

Returns:

Type	Description
str	String like "2/0/5".

Source code in src/gem/field_path.py

def to_str(self) -> str:
    """Return a slash-separated string of active indices.

    Returns:
        String like ``"2/0/5"``.
    """
    return "/".join(str(self.path[i]) for i in range(self.last + 1))

plus_one() -> None

Increment the deepest index by 1.

Source code in src/gem/field_path.py

def plus_one(self) -> None:
    """Increment the deepest index by 1."""
    self.path[self.last] += 1

---

gem.field_path.FieldPathOp dataclass

A single field-path operation with its Huffman weight.

Attributes:

Name	Type	Description
name	str	Human-readable operation name.
weight	int	Huffman frequency weight (higher = shallower in tree).
fn	Callable[[BitReader, FieldPath], None]	Callable that mutates a FieldPath using bits from a BitReader.

Source code in src/gem/field_path.py

@dataclass(frozen=True)
class FieldPathOp:
    """A single field-path operation with its Huffman weight.

    Attributes:
        name: Human-readable operation name.
        weight: Huffman frequency weight (higher = shallower in tree).
        fn: Callable that mutates a FieldPath using bits from a BitReader.
    """

    name: str
    weight: int
    fn: Callable[[BitReader, FieldPath], None]