python

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package python runs a scenario written as a Python file, by shelling out to a python3 interpreter the user has installed separately.

This is VegaLoad's second-class scripting path, as AGENTS.md describes it: JavaScript/TypeScript (internal/scripting/js) is embedded and needs nothing beyond the vegaload binary itself, while Python here depends on a python3 executable already being on PATH. A scenario file defines a module-level function named iteration:

def iteration():
    # one iteration's worth of work
    pass

Each VU gets its own python3 subprocess (started once, in NewVU, and reused for every iteration that VU runs) talking a line-delimited JSON RPC protocol over stdin/stdout — not a fresh process per iteration, which would make the per-request overhead dwarf whatever the scenario is actually measuring.

Per FR-CLI-08, every VU's subprocess also gets real HTTP and WebSocket access: the harness injects module-level `http` and `ws` objects (mirroring internal/scripting/js's globals of the same names) that a script calls directly:

def iteration():
    created = http.post("http://localhost:8080/launches", body='{"name":"demo"}')
    launch = created.json()
    conn = ws.connect("ws://localhost:8080/launches/" + launch["id"] + "/ignite")
    conn.send('{"action":"ignite"}')
    while True:
        frame = conn.receive(timeout_ms=5000)
        if frame is None:
            break
        msg = json.loads(frame)
        if msg["status"] in ("complete", "aborted"):
            break
    conn.close()

A Python subprocess can't hold a Go value (an *http.Client, a websocket connection), so http and ws don't talk to the network themselves — every call is proxied back over the same stdin/stdout pipe as a small request/response exchange, handled on the Go side by VU.Iteration and actually performed by internal/scripting/netapi, the same package backing the JS globals. A WebSocket connection is identified to Python by an opaque integer handle rather than any kind of reference, since that's the only thing that survives the process boundary.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Option added in v0.4.0

type Option func(*VU)

Option changes how NewVU builds a VU. An option is needed, rather than a setter called afterwards, when the script's top-level code has to see it: the top level runs while NewVU waits for the interpreter to be ready.

func WithInputs added in v0.4.0

func WithInputs(in netapi.Inputs) Option

WithInputs exposes the `env` and `data` globals (FR-CLI-17). Without it, every env name is missing and every data file is unknown.

type Script

type Script struct {
	// contains filtered or unexported fields
}

Script is a loaded, validated-at-load-time-only scenario file. Load itself only checks that the file exists and that an interpreter is available — the script's own correctness (does it define iteration?, does it even parse?) is checked once per VU, in NewVU, since that is where the interpreter that would tell us is actually started.

func Load

func Load(path string) (*Script, error)

Load returns a Script for the scenario file at path, after confirming the file exists and that pythonBin is on PATH. It does not start an interpreter or touch the script's contents — see NewVU.

func (*Script) NewVU

func (s *Script) NewVU(check netapi.SafetyCheck, timeout time.Duration, opts ...Option) (*VU, error)

NewVU starts a fresh python3 subprocess for one virtual user and waits for its ready signal, which is also where a script that fails to import, or has no iteration() function, is caught — before any iteration is attempted, the same way js.Script.NewVU validates the default export up front.

check is run (if non-nil) against the host of every call the script makes through http or ws, before connecting; timeout bounds each individual HTTP request and WebSocket handshake, same as js.Script.NewVU's parameters of the same name.

type VU

type VU struct {
	// contains filtered or unexported fields
}

VU is one virtual user's python3 subprocess, plus the HTTP client and set of open WebSocket connections (keyed by the handle the harness uses to refer to them) that back its `http`/`ws` globals.

func (*VU) Close

func (v *VU) Close() error

Close signals the interpreter to exit (by closing its stdin, which ends the harness's read loop), closes every WebSocket connection this VU's script ever opened via ws.connect (even one it never explicitly closed itself), and waits for the subprocess to exit.

func (*VU) Iteration

func (v *VU) Iteration(ctx context.Context) error

Iteration runs the script's iteration() function once, in this VU's subprocess, handling every http/ws "call" message the script makes along the way until the subprocess reports the iteration's own result. It implements engine.IterationFunc's signature directly, so a *VU can be used anywhere the engine wants one.

Unlike js.VU.Iteration, a cancelled ctx here does not interrupt iteration() mid-execution inside the subprocess — there is no in-process equivalent of Goja's Interrupt across a process boundary. It does stop Iteration from waiting on a response past ctx's deadline, returning promptly, and it bounds every http/ws call the script makes (via the same ctx, same as js.VU); the subprocess itself is only reclaimed when Close is called, which the executor is expected to do once the run ends.

func (*VU) SetCheckRecorder added in v0.4.0

func (v *VU) SetCheckRecorder(rec netapi.CheckRecorder)

SetCheckRecorder sets where this VU reports the outcome of every check() its script makes. Call it before the first Iteration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL