product: maestro audience: test-developer authority: normative

Python Dependencies and Offline Environments

Production test stations are frequently deployed in air-gapped networks with no internet access. The Python runner Docker image ships with only the gRPC transport libraries — nothing else. Third-party packages MUST be made available before a test executes.

How pipPackages works

Declare dependencies in package.json:

{
  "requirements": {
    "minPythonVersion": "3.11",
    "pipPackages": ["requests>=2.32.0"]
  }
}

The Python runner automatically installs these packages at startup by scanning every installed package and reading pipPackages from each package.json.

Vendoring wheels for production

Step 1 — Download wheels on a machine with internet access:

# Helper script (reads pipPackages from package.json)
.\scripts\vendor-wheels.ps1 -PackagePath "path\to\my-package"

# Or manually
pip download requests>=2.32.0 \
  --dest wheels/ \
  --platform manylinux2014_x86_64 \
  --python-version 3.11 \
  --only-binary=:all:

The Python runner runs on python:3.11-slim (Debian Linux, x86_64). Always download wheels for manylinux2014_x86_64 and Python 3.11.

Step 2 — Commit wheels into wheels/ in your package. The runner installs them automatically at startup — no manual docker exec required.

How the runner finds Python modules

The runner adds to sys.path at startup:

1. /app/scripts — legacy mount for ad-hoc scripts.
2. <package>/python_modules/ for every installed package — picked up automatically on every step invocation.

Development vs production

• Development: Set ALLOW_ONLINE_PIP=true in the environment to install from PyPI. This IS already configured in the dev docker-compose.yml.
• Production: MUST vendor wheels. MUST NOT rely on internet access.