Examples
These three directories are in samples/. Each one validates, and each
one can be run with the commands below. They do not change the files in
the sample directory. New files appear in the session workspace.
Destroy the named session before you run the same sample again.
Hello
samples/hello is a note and a script that writes one new file.
version: 1
sandbox:
name: hello
description: Write one file in a copied project.
workspace:
source: .
execution:
commands:
- id: write
run:
- python3
- write.py
"""Write one new file. The copied note.txt is left as it was."""
from pathlib import Path
Path("generated.txt").write_text("ok\n")
sandbox validate samples/hello/sandbox.yml
sandbox run samples/hello/sandbox.yml
sandbox diff hello
sandbox logs hello
sandbox destroy hello
sandbox diff hello lists generated.txt as added. note.txt is in
the copy and is not listed, because the script does not change it. The
note.txt in samples/hello is still the original file.
The same script without a recipe, from samples/hello:
sandbox run --name hello-once -- python3 write.py
sandbox show hello-once
sandbox destroy hello-once
Report
samples/report runs two commands. The first creates dist/results.txt.
The second reads it and exits 0 only when the text is ok. The recipe
stops after a failure, so a broken build does not pretend the check
passed.
version: 1
sandbox:
name: report
description: Build a result file, then check it.
workspace:
source: .
execution:
stop_on_error: true
commands:
- id: build
run:
- python3
- build.py
- id: check
run:
- python3
- check.py
outputs:
include:
- dist/**
"""Create the file the later command checks."""
from pathlib import Path
output = Path("dist")
output.mkdir(exist_ok=True)
(output / "results.txt").write_text("ok\n")
sandbox validate samples/report/sandbox.yml
sandbox run samples/report/sandbox.yml
sandbox diff report
sandbox export report --include "dist/**" --to ./output --dry-run
sandbox export report --include "dist/**" --to ./output
sandbox destroy report
The dry run creates nothing, including the destination directory. The
real export copies dist/results.txt into ./output and leaves the
file in the workspace as well. Run the export from a directory where
./output is a place you want those files.
To see a refused apply, change nothing in the sample and ask for a dry run after the session exists:
Do that before sandbox destroy report. Apply will offer the new
dist/results.txt only when that path is absent from the original
sample. It will not overwrite a source file that no longer matches the
snapshot from session creation.
Compare Notes
samples/compare-notes records sys.version into python-version.txt.
Sandbox stages the sample once and runs that snapshot on both sides.
version: 1
sandbox:
name: compare-notes
description: Record the Python version used in the workspace.
workspace:
source: .
execution:
commands:
- id: record
run:
- python3
- record.py
"""Record the interpreter that actually ran this command."""
import sys
from pathlib import Path
Path("python-version.txt").write_text(sys.version + "\n")
sandbox validate samples/compare-notes/sandbox.yml
sandbox compare samples/compare-notes/sandbox.yml \
--python-a python3 \
--python-b python3
Both sides use the same interpreter, so python-version.txt is reported
as identical. Point the two flags at two interpreters you already have
installed when you want the file to differ:
Sandbox does not download those interpreters. If one of them is missing, the command stops before it creates the sessions. A difference in the report is the text each interpreter wrote. It is not a verdict that the program is incompatible.
The sessions are named compare-notes-a and compare-notes-b.