psrunner

The Python SDK of PythonScriptRunner, a .NET library that runs Python scripts with a typed contract.

A stage is one Python script with typed inputs and outputs. The .NET runner validates the inputs, runs the script in an isolated process with a timeout and a memory limit, and validates the outputs. psrunner handles the protocol between the two sides, so the script only contains the logic.

Documentation: Python SDK guide | guia em português

Installation

The .NET runner installs psrunner in every environment it creates, so stages never list it in their requirements. Install it yourself to write and test scripts locally:

pip install psrunner             # Python 3.10 or newer
pip install "psrunner[pandas]"   # table inputs arrive as pandas.DataFrame

Writing a stage

from psrunner import stage, StageError

@stage
def run(inputs, ctx):
    a1, ratio, n = inputs["a1"], inputs["ratio"], inputs["n"]
    if n < 1:
        raise StageError("n must be at least 1.", code="INVALID_N")

    terms = [a1 * ratio**i for i in range(n)]
    ctx.log.info("generated %d terms", n)
    return {"terms": terms}

The contract lives in stage.json, next to the script:

{
  "key": "progression-terms",
  "version": 1,
  "name": "Progression terms",
  "inputs": [
    { "name": "a1", "type": "number" },
    { "name": "ratio", "type": "number" },
    { "name": "n", "type": "integer" }
  ],
  "outputs": [ { "name": "terms", "type": "list", "itemType": "number" } ]
}

The rules:

• One entry point: exactly one function per script is marked with @stage. It receives the inputs, already converted, and the context.
• Return value: it returns a dict with the outputs. Required outputs must be present, and outputs outside the contract are an error.

Types

The context

A File has path, name, content_type, size and sha256, and the methods read_bytes(), read_text() and open().

@stage
def run(inputs, ctx):
    report = ctx.new_file("report.csv", "text/csv")
    report.path.write_text("x,y\n1,2\n", encoding="utf-8")
    return {"report": report}

Errors

• Business errors: StageError(message, code="CODE", details={...}) fails the run as ScriptError with that code.
• Unexpected exceptions: any other exception also becomes ScriptError, with the traceback of your script.
• Contract violations: a missing output, a wrong type or a non-finite number becomes OutputContractViolation.

Testing with pytest

psrunner.testing.run_stage runs the function with the same conversions and validations as the real runner, without .NET:

from psrunner.testing import run_stage

def test_terms():
    result = run_stage(
        "stages/progression-terms/script.py",
        {"a1": 1, "ratio": 2, "n": 4},
        stage_json="stages/progression-terms/stage.json",
    )
    assert result.ok
    assert result.outputs == {"terms": [1, 2, 4, 8]}

run_stage also accepts secrets, files (file fields mapped to local paths), work_dir and run_id. The result has ok, outputs, wire_outputs, error (kind, code, message, traceback), logs and work_dir.

Command line

psrunner validate stages/progression-terms
psrunner run stages/progression-terms --input sample.json --secret NAME=value --keep

The same commands work as python -m psrunner.

Compatibility

psrunner follows protocol 1, the format exchanged with the .NET runner, for as long as that protocol is in use.

License

MIT