project-setup-python

# Project Setup (Python) ## When to Use Use this skill when the user asks to create a Python project that uses ovstage, import the `ovstage` package, configure the library path so the bindings load, or scaffold a minimal Python program that reads/writes stage data. ## Inputs Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context. - Whether the consumer uses a built/installed `ovstage` wheel or the in-tree `python/` package. - Whether the build output dir (holding the ovstage shared library) is on the loader path (`PATH` on Windows, `LD_LIBRARY_PATH` on Linux). - Whether the workflow needs `numpy` (tensor I/O) and/or the path dictionary. - Repository source snippets referenced below. Treat these snippets as the API source of truth. ## Prerequisites - Python **3.10–3.13** (`requires-python = ">=3.10,<3.14"`). - A built ovstage shared library reachable by the loader (see Library Path below). - `numpy` for tensor attribute I/O. ## Instructions 1. Make the `ovstage` package importable (installed/pinned wheel — see Installing below — or the in-tree `python/` package on `PYTHONPATH`). 2. Ensure the ovstage shared library loads. The wheel bundles it at `<package>/bin` (found automatically); for the in-tree package, put the build output dir (holding it) on `PATH` (Windows) or `LD_LIBRARY_PATH` (Linux). 3. Add `numpy` for tensor I/O. 4. Write the minimal program: `Stage` + `PathDictionary`, then write → advance write floor → read. 5. Run it and confirm the read-back values. ## Output Format - For explanations, cite the relevant API names, source snippets, and caveats. - For code changes, summarize the files changed, snippets affected, and validation run. ## Scripts This skill has no scripts. ## Limitations - The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage. - **Consumption model:** ovstage is consumed as a **published `ovstage` wheel** (see Installing), distributed on public PyPI (`pip install ovstage` / `uv add ovstage`). The import + library-path mechanics here also cover consuming a **local build**. For C/C++ setup, see `project-setup-c`. ## Overview ovstage ships a Python package, **`ovstage`**, built with hatchling (`pyproject.toml`, `requires-python = ">=3.10,<3.14"`). It binds the ovstage C data-plane via ctypes, so the **ovstage shared loader must be loadable** at import time. The released wheel bundles that library at `<package>/bin`, which the bindings find automatically — a wheel consumer needs no loader-path setup. ## Installing Install the published `ovstage` wheel with your Python tool of choice. The platform wheels bundle the native library under `<package>/bin`, so a **published install needs no loader-path setup** (skip the Library Path section below — that is only for local builds): ```bash uv add ovstage # or: pip install ovstage ``` The minimal example wires this up as a ready-to-copy starting point — pin `ovstage` in its `pyproject.toml` and run with `uv run main.py`: > **Setup:** `examples/python/minimal/pyproject.toml` (pins `ovstage`; `uv run main.py` resolves, > installs, and runs it) ## Library Path For a **local build** (not a published wheel), the loader finds the ovstage shared library on the **loader path**: add the build output dir (the one holding `ovstage-dynamic.dll` / `libovstage-dynamic.so`) to `PATH` (Windows) or `LD_LIBRARY_PATH` (Linux). The wheel layout (`<package>/bin`) is also searched automatically. ```bash # Linux export LD_LIBRARY_PATH=/path/to/ovstage/build/output:$LD_LIBRARY_PATH # Windows (PowerShell) # $env:PATH = "C:\path\to\ovstage\build\output;$env:PATH" ``` > You can also point the loader at the build dir with `OVSTAGE_LIBRARY_PATH_HINT` — as an > environment variable, or as the `ovstage._src.bindings.OVSTAGE_LIBRARY_PATH_HINT` module > global for an in-process override (the module global takes precedence when both are set). ## Key Dependencies | Package | Purpose | |---------|---------| | `ovstage` | the bindings (Stage, PathDictionary, OrdinalRange, …) | | `numpy` | tensor attribute I/O (`write_attribute(tensors=...)`, `group.array(...)`) | ## Minimal Program `Stage` + `PathDictionary` (both context managers), then intern a token, build a path list, open a query, and write → advance write floor → read. Async ops return an `Operation`; call `.wait()` — it returns the object it was called on, so `read.wait().fetch_next()` chains. The verified example composes the full flow: > **Source:** `examples/python/minimal/main.py` snippet `setup` > > Followed by: `examples/python/minimal/main.py` snippet `intern-and-resolve` > > Followed by: `examples/python/minimal/main.py` snippet `path-list-query` > > Followed by: `examples/python/minimal/main.py` snippet `minimal-write-read` The context managers wrap the whole sequence — `with ovstage.Stage("demo") as stage, ovstage.PathDictionary(stage) as paths:` — and the path dictionary is the stage's (shared; no separate teardown). The fixed-size write in `minimal-write-read` passes `is_array=False`; array writes must pass `is_array=True`. Attribute kind is explicit and is never inferred from tensor shape or count. See `error-handling` (Python) for `OvstageError` / `OvxError`, `path-dictionary` (Python) for `PathDictionary`, and `string-handling` (Python) for `str` vs. interned-token args. ## Troubleshooting - **Import fails / shared loader not found:** make the build output dir (holding `ovstage-dynamic.dll` / `libovstage-dynamic.so`) reachable — set `OVSTAGE_LIBRARY_PATH_HINT` to it, or add it to `PATH` (Windows) / `LD_LIBRARY_PATH` (Linux). See Library Path. - **Unsupported Python version:** the package supports 3.10–3.13 only; recreate the env with a supported interpreter rather than editing the constraint. - **`OvstageError` / `OvxError` on calls:** these are `RuntimeError` subclasses carrying a numeric `code`; see the `error-handling` skill. - **Forgot to `.wait()`:** async ops (`write_attribute`, `advance_write_floor`, `read_attributes`) return handle objects; effects/errors are observed on `.wait()`. - **`ResourceWarning` from a chained `.wait()`:** chaining on an unbound temporary (`stage.read_attributes(...).wait().fetch_next()`) drops the handle unreleased — bind it in a `with` block first, then chain (`group = read.wait().fetch_next()`). ## References - Use the `> **Source:**` directives in this skill to locate tested snippets before reusing API patterns. - `project-setup-c` — C/C++ consumer setup. - `error-handling`, `string-handling`, `path-dictionary` skills — Python API detail. - Keep related skills, docs, and snippets synchronized when changing the workflow.