Author constrained .cso.py calculations with Python 3.11+. Runtime dependencies
are the standard library only. Read authoring before
writing calculations and use two-panel for
shared metadata and composed calls.
Install from PyPI with python -m pip install cs-object. The import package and
module command remain cso_python.
Follow workspace setup to build and install a wheel. Distribution metadata lives in pyproject.toml. Use the interpreter containing that wheel:
python -m cso_python bindings examples/two-panel
python -m cso_python execute examples/two-panel/estimate.cso.py \
--function estimate --input width=2bindings --check checks generated interfaces without writing or executing
calculations. execute returns a versioned execution response; export returns
CSO JSON. Inspect python -m cso_python --help and each subcommand's --help
for options. Paths resolve from the invoking directory. Authored output and
operational messages go to stderr so stdout contains one JSON response.
cso bindings derives an importable _cso_bindings package from your .cso.py
definitions. Each generated .py module creates callable handles containing a
relative source path, function name and interface fingerprint. Its .pyi stub
provides keyword-only signatures and typed dictionaries of public results.
Generation parses definitions without executing the authored calculations.
Importing a handle does not run the calculation. Calling it captures dependencies,
plans the invocation and records its execution. This keeps composed calculations
in the document and execution evidence. The generation and planning paths share
the same definition parser. An outdated interface raises STALE_BINDINGS.
After workspace setup, run this ordinary Python consumer from the repository root:
"$PYTHON" -m cso_python bindings examples/two-panel
(cd examples/two-panel && "$PYTHON" - <<'PY'
from _cso_bindings.geometry import rectangle
result = rectangle(width=2, height=3)
print(result["area"]) # 6
print(result["perimeter"]) # 10
PY
)This uses the same calculation as the composed report. Successful execution
alone does not establish source-to-document consistency; run cso verify or
cso pdf for that check. See authoring
for generation roots, source-control policy and regeneration rules.
The generation workflow resembles Convex's generated function references: application functions determine the generated interface that callers import. CSO handles invoke local calculations through its capture and execution pipeline. This analogy does not prescribe a Git policy. Convex recommends committing its generated code so a checkout can type-check immediately; this repository regenerates ignored bindings during setup and consumer preparation.
A generated handle reuses its captured plan and compiled code while its supplied input names, source bytes and assets remain unchanged. Calls through one handle run serially because each call updates that handle's execution trace.
Successful execution supplies observations; it does not establish formula consistency. Use the verified CLI for that check. The captured path preflights local source and executes captured UTF-8 bytes. Older single-file exports retain the development exporter. This is trusted local calculation authoring, not isolation for hostile Python.
Public helpers, capture, definitions, planner, execution and bindings implement the pipeline described in the code map.
With the wheel installed, run python -I tests/run.py from this package directory.
The tests use package-owned synthetic fixtures and temporary bindings; no root
examples or Node are required. Workspace integration
owns actual example, installed cross-package and PDF acceptance.