Getting Started in Python#

Note

The ovstage Python bindings are a ctypes layer over the ovstage C ABI. The minimal example runs against the released ovstage wheel using uv. ovstage is pre-release: if uv cannot resolve the pinned ovstage wheel, the public wheel is not published yet.

The minimal example is a uv project that pins the ovstage wheel in its pyproject.toml:

cd examples/python/minimal
uv run main.py

The bindings load the ovstage shared loader through ctypes the first time you create a Stage or PathDictionary. If you are running against a locally built shared library instead of the wheel, put its directory on the loader path (LD_LIBRARY_PATH on Linux, PATH on Windows) or point the loader at it with OVSTAGE_LIBRARY_PATH_HINT.

Minimal Example#

The minimal example creates a stage, interns paths and tokens through the instance-owned path dictionary, writes an attribute column, advances the write floor, and reads the latest committed data back.

# Write one value per prim, then advance the watermark before reading.
# wait() reports asynchronous failures; the context manager and finally
# block release the read and its result even if consuming the data fails.
stage.write_attribute(
    query, attr, ordinal=1, tensors=np.array([1.0, 2.0, 3.0], np.float32), is_array=False
).wait()
stage.advance_write_floor(ordinal=1).wait()

with stage.read_attributes(query, [attr], OrdinalRange.latest(1)) as read:
    read.wait()
    group = read.fetch_next()
    if group is None:
        raise SystemExit("read returned no group at ordinal 1")
    try:
        # group.array(i) is a zero-copy numpy view of tensor i (CPU).
        print("read back ordinal", group.ordinal, group.array(0))  # -> [1. 2. 3.]
    finally:
        stage.release_group(group)

The example above is provided as a Python project in the examples/python/minimal directory in the repository.

Next Steps#