flatbuffers 25.12.19: flatbuffers

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify flatbuffers in pkg:pypi/flatbuffers@25.12.19
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/flatbuffers@25.12.19
Demonstrate these symbols/APIs:
  - flatbuffers

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:fecfdf1d633028cedd37957be11892f665eabccbd4e2a4f63c82b47c45b8fa74","contract":["flatbuffers.__version__ reports package version matching 25.12.19","flatbuffers.Table inspects present and omitted scalar fields and default values using GetSlot and GetVOffsetTSlot","flatbuffers.Table.String decodes null-terminated byte sequences at absolute buffer offsets","flatbuffers.Table.Vector and Table.VectorLen resolve element offset and length for byte vector fields","flatbuffers.Table.Indirect resolves relative offsets to target nested tables","flatbuffers.Table.Union re-points table reference to inline union table offsets","flatbuffers.util.BufferHasIdentifier and flatbuffers.util.GetBufferIdentifier validate and extract 4-byte file identifiers for standard and size-prefixed buffers","flatbuffers.util.GetSizePrefix and flatbuffers.util.RemoveSizePrefix decode buffer length prefixes and advance buffer offsets past the prefix","flatbuffers.encode.Get and flatbuffers.encode.Write pack and unpack binary scalar representations using flatbuffers.packer formats","flatbuffers.number_types.enforce_number validates value ranges against type flags and raises TypeError on out-of-range inputs"],"goal":"verify flatbuffers in pkg:pypi/flatbuffers@25.12.19","kind":"HOW","packages":["pkg:pypi/flatbuffers@25.12.19"],"schemaVersion":1,"symbols":["flatbuffers"]},"contractCommand":["python3","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"uv","runtime":"python","runtimeVersion":"3.12","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/flatbuffers@25.12.19"],"schemaVersion":1,"subject":"pkg:pypi/flatbuffers@25.12.19","symbols":["flatbuffers"],"verifierAdapter":"python@1"}

[project]
name = "sample-flatbuffers"
version = "0.1.0"
requires-python = ">=3.8"
dependencies = [
    "flatbuffers==25.12.19",
]

flatbuffers==25.12.19

{
  "schemaVersion": 1,
  "goal": "verify flatbuffers in pkg:pypi/flatbuffers@25.12.19",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/flatbuffers@25.12.19"
  ],
  "symbols": [
    "flatbuffers"
  ]
}

import flatbuffers
from flatbuffers import Builder, encode, number_types, packer, util
from flatbuffers.table import Table


def test_package_version():
    assert flatbuffers.__version__ == "25.12.19", (
        f"Expected version 25.12.19, got {flatbuffers.__version__}"
    )


def test_table_slots_and_defaults():
    b = Builder(256)
    b.StartObject(2)
    b.PrependInt32Slot(0, 42, 0)
    root = b.EndObject()
    b.Finish(root)

    buf = b.Output()
    root_pos = encode.Get(number_types.UOffsetTFlags.packer_type, buf, 0)
    tab = Table(buf, root_pos)

    val0 = tab.GetSlot(4, 999, number_types.Int32Flags)
    assert val0 == 42, f"Expected 42, got {val0}"
    voffset0 = tab.GetVOffsetTSlot(4, 0)
    assert voffset0 > 0, f"Expected positive voffset, got {voffset0}"

    val1 = tab.GetSlot(6, 999, number_types.Int32Flags)
    assert val1 == 999, f"Expected default 999, got {val1}"
    voffset1 = tab.GetVOffsetTSlot(6, 0)
    assert voffset1 == 0, f"Expected default 0, got {voffset1}"


def test_table_string_and_vector():
    b = Builder(256)
    s_offset = b.CreateString("sample_payload")
    raw_bytes = b"\xaa\xbb\xcc\xdd\xee"
    v_offset = b.CreateByteVector(raw_bytes)

    b.StartObject(2)
    b.PrependUOffsetTRelativeSlot(0, s_offset, 0)
    b.PrependUOffsetTRelativeSlot(1, v_offset, 0)
    root = b.EndObject()
    b.Finish(root)

    buf = b.Output()
    root_pos = encode.Get(number_types.UOffsetTFlags.packer_type, buf, 0)
    tab = Table(buf, root_pos)

    field0 = tab.Offset(4)
    assert field0 != 0, "String field offset missing"
    decoded_str = tab.String(tab.Pos + field0)
    assert decoded_str == b"sample_payload", f"Decoded string mismatch: {repr(decoded_str)}"

    field1 = tab.Offset(6)
    assert field1 != 0, "Vector field offset missing"
    assert tab.VectorLen(field1) == len(raw_bytes), "Vector length mismatch"
    vec_start = tab.Vector(field1)
    assert bytes(tab.Bytes[vec_start : vec_start + len(raw_bytes)]) == raw_bytes, "Vector bytes mismatch"


def test_table_indirect_and_union():
    b = Builder(256)
    s_child = b.CreateString("child_table_name")
    b.StartObject(1)
    b.PrependUOffsetTRelativeSlot(0, s_child, 0)
    child = b.EndObject()

    b.StartObject(1)
    b.PrependUOffsetTRelativeSlot(0, child, 0)
    root = b.EndObject()
    b.Finish(root)

    buf = b.Output()
    root_pos = encode.Get(number_types.UOffsetTFlags.packer_type, buf, 0)
    tab = Table(buf, root_pos)
    field_off = tab.Offset(4)

    indirect_pos = tab.Indirect(tab.Pos + field_off)
    child_tab = Table(buf, indirect_pos)
    name_off = child_tab.Offset(4)
    assert child_tab.String(child_tab.Pos + name_off) == b"child_table_name"

    union_tab = Table(buf, 0)
    tab.Union(union_tab, field_off)
    u_name_off = union_tab.Offset(4)
    assert union_tab.String(union_tab.Pos + u_name_off) == b"child_table_name"


def test_util_file_identifier():
    ident = b"CSX1"
    b = Builder(256)
    b.StartObject(0)
    root = b.EndObject()
    b.Finish(root, file_identifier=ident)
    buf = b.Output()

    assert util.BufferHasIdentifier(buf, 0, ident) is True, "Identifier check failed"
    assert util.BufferHasIdentifier(buf, 0, b"FAIL") is False, "False identifier accepted"
    extracted = util.GetBufferIdentifier(buf, 0)
    assert bytes(extracted) == ident, f"Expected {ident}, got {extracted}"

    b_sp = Builder(256)
    b_sp.StartObject(0)
    root_sp = b_sp.EndObject()
    b_sp.FinishSizePrefixed(root_sp, file_identifier=ident)
    buf_sp = b_sp.Output()

    assert util.BufferHasIdentifier(buf_sp, 0, ident, size_prefixed=True) is True
    extracted_sp = util.GetBufferIdentifier(buf_sp, 0, size_prefixed=True)
    assert bytes(extracted_sp) == ident, f"Expected {ident}, got {extracted_sp}"


def test_util_size_prefix_operations():
    b = Builder(256)
    b.StartObject(0)
    root = b.EndObject()
    b.FinishSizePrefixed(root)
    buf = b.Output()

    size_prefix = util.GetSizePrefix(buf, 0)
    assert size_prefix == len(buf) - 4, f"Size prefix mismatch: {size_prefix} != {len(buf) - 4}"

    buf_ref, advanced_offset = util.RemoveSizePrefix(buf, 0)
    assert buf_ref is buf
    assert advanced_offset == 4


def test_encode_and_packer():
    buf = bytearray(32)
    encode.Write(packer.int32, buf, 0, -12345)
    encode.Write(packer.uint32, buf, 4, 67890)
    encode.Write(packer.float64, buf, 8, 2.718281828)
    encode.Write(packer.boolean, buf, 16, True)

    assert encode.Get(packer.int32, buf, 0) == -12345
    assert encode.Get(packer.uint32, buf, 4) == 67890
    assert abs(encode.Get(packer.float64, buf, 8) - 2.718281828) < 1e-7
    assert encode.Get(packer.boolean, buf, 16) is True


def test_number_types_enforce_range():
    number_types.enforce_number(0, number_types.Uint8Flags)
    number_types.enforce_number(255, number_types.Uint8Flags)

    try:
        number_types.enforce_number(256, number_types.Uint8Flags)
        assert False, "Out-of-range uint8 did not raise TypeError"
    except TypeError:
        pass

    try:
        number_types.enforce_number(-1, number_types.Uint8Flags)
        assert False, "Negative uint8 did not raise TypeError"
    except TypeError:
        pass


def main():
    test_package_version()
    test_table_slots_and_defaults()
    test_table_string_and_vector()
    test_table_indirect_and_union()
    test_util_file_identifier()
    test_util_size_prefix_operations()
    test_encode_and_packer()
    test_number_types_enforce_range()
    print("All flatbuffers contract assertions passed.")


if __name__ == "__main__":
    main()

version = 1
revision = 3
requires-python = ">=3.8"

[[package]]
name = "flatbuffers"
version = "25.12.19"
source = { registry = "https://pypi.org/simple" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/e8/2d/d2a548598be01649e2d46231d151a6c56d10b964d94043a335ae56ea2d92/flatbuffers-25.12.19-py2.py3-none-any.whl", hash = "sha256:7634f50c427838bb021c2d66a3d1168e9d199b0607e6329399f04846d42e20b4", size = 26661, upload-time = "2025-12-19T23:16:13.622Z" },
]

[[package]]
name = "sample-flatbuffers"
version = "0.1.0"
source = { virtual = "." }
dependencies = [
    { name = "flatbuffers" },
]

[package.metadata]
requires-dist = [{ name = "flatbuffers", specifier = "==25.12.19" }]