Skip to content

feat(db-python): read-side bindings with type registry and annotations - #82

Open
EnriqueParodi wants to merge 1 commit into
feat/jsonrpc-ts-clientfrom
feat/db-python-bindings
Open

feat(db-python): read-side bindings with type registry and annotations#82
EnriqueParodi wants to merge 1 commit into
feat/jsonrpc-ts-clientfrom
feat/db-python-bindings

Conversation

@EnriqueParodi

Copy link
Copy Markdown
Collaborator

pybind11 bindings for sen::db that let a Python script open a recording,
walk a cursor, and reflect on every payload through the same type system
the recorder used.

Surface:

  • sen.Input(path): opens a recording. Owns its CustomTypeRegistry; a
    process can open several recordings independently.
  • Input.types: live view of the registry (Python class objects, dynamic
    via getattr so unknown names raise AttributeError fast).
  • Cursor: forward iterator over recorded events; advance(), payload,
    timestamp; entry.payload is a tagged union dispatched by isinstance.
  • Snapshot / Creation: object views with reflection. objectId surfaces
    the recorder's stable id (renamed from the ambiguous .id).
  • KeyedVar: dict-shaped (tag -> value); reviewed and kept as dict for
    ergonomic reasons (the class-shape alternative was rejected).
  • Annotation surfacing on every entry; annotation.type goes through
    asCustomType so the same reflection path covers it.

Correctness commitments:

  • ObjectId pybind11 caster validates range + signedness + error path
    (previously could silently truncate / accept negatives).
  • typeNeedsAdaptation cache keys by Type* not MemberHash (MemberHash
    collisions between unrelated types in different recordings were
    reachable).
  • Payload copies into Python so keep_alive lifetime chains hold across
    cursor advance.
  • Annotation.type uses asCustomType; docstring matches behaviour.
  • InputPy clears its lookupProperty cache on destruction (no stale
    pointers if a second Input opens the same recording shape).
  • Built-in dispatch is O(1) via lookup table, not the prior linear scan.
  • propertyNames cached per ClassType (not recomputed per Snapshot).
  • pybind11 idiom + include hygiene: const-ref string visitors,
    TypeRegistryPy cached on the module, std::filesystem in headers.

Testing:

  • bindings smoke test: opens a small recording fixture, walks one
    cursor, asserts on the reflected types. Catches "file deleted but
    module still compiles" cases that pure C++ build verification misses.
  • CMake piggybacks on SEN_BUILD_PY (no separate option fan-out per
    per-element-with rule).

Documentation:

  • users-guide page + db_library cross-ref + Tier 2 walk example
    (a small Python script that opens a recording and aggregates
    per-class state, runs as written).

@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from 2738b1e to f49a9a7 Compare August 16, 2026 16:24
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from 5b25282 to 3d68fd2 Compare August 16, 2026 16:24
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from f49a9a7 to 751d7b5 Compare August 16, 2026 17:04
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch 2 times, most recently from 740f0aa to d111b42 Compare August 16, 2026 17:26
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch 2 times, most recently from f6e22c6 to e1114f6 Compare August 16, 2026 20:05
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from d111b42 to 1dacf1e Compare August 16, 2026 20:05
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from e1114f6 to 5bb1d7d Compare August 17, 2026 07:13
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from 1dacf1e to 4335c87 Compare August 17, 2026 07:13
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from 5bb1d7d to bdfa58e Compare August 17, 2026 07:46
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from 4335c87 to 1da23a4 Compare August 17, 2026 07:46
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from bdfa58e to 9e5bd31 Compare August 18, 2026 22:27
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch 2 times, most recently from 4fb9677 to c7479da Compare August 19, 2026 07:42
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from 9e5bd31 to 567004c Compare August 19, 2026 07:42
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch 4 times, most recently from d9c66fc to 1e7ef49 Compare August 19, 2026 17:01
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from 567004c to 548c5d2 Compare August 19, 2026 17:01
@EnriqueParodi
EnriqueParodi marked this pull request as ready for review August 19, 2026 17:03
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from 1e7ef49 to c83d794 Compare August 19, 2026 19:05
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from 548c5d2 to 9794fd5 Compare August 19, 2026 19:05
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from c83d794 to 376955b Compare August 19, 2026 21:21
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch 2 times, most recently from 4f43ff8 to 1525d2f Compare August 20, 2026 11:26
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from 376955b to 0b8c2ba Compare August 20, 2026 11:26
pybind11 bindings for sen::db so a Python script can open a recording, walk a
cursor and reflect on every payload through the same type system the recorder
used. Read-side only, and the CMake side rides on SEN_BUILD_PY rather than
adding another option.
@EnriqueParodi
EnriqueParodi force-pushed the feat/jsonrpc-ts-client branch from 0b8c2ba to 0eeb2fe Compare August 20, 2026 21:03
@EnriqueParodi
EnriqueParodi force-pushed the feat/db-python-bindings branch from 1525d2f to 1e1f837 Compare August 20, 2026 21:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant