[mahdi-shafiei]

Summary

A run_python child sends its result on a file only it knows, so no library output can be read as the result.

 child                                   parent (run_python)
-print(json.dumps(value))   -> stdout -> ChildResult.last_json_as(shape)   # last stdout line
+report(value)              -> $SUBSTRAX_CHILD_REPORT file
+                                       ChildResult.report_as(shape) / report_json()
 libraries (Gloo, C++)      -> stdout    stays in ChildResult.stdout

• substrax.testing.report(value) writes once, to a staging file moved into place, and refuses a second report or a process run_python did not start.
• ChildResult.report holds the text (None when the child sent none). report_as(shape) keeps the strict pydantic validation; report_json() decodes it unshaped.
• run_example reads main()'s summary through the same channel.
• last_json and last_json_as are removed. Every child in the tests, the README and docs/api/testing.md reports instead; import probes measure sys.modules before they import report.

Evidence

• Before: datarax run 40894143757 (2026-10-29, Python 3.13 shard 4): test_multi_process_placement.py::TestRefusedAcrossProcesses::test_a_configuration_differing_between_processes_is_refused_in_every_process failed with json_invalid, input_value='[Gloo] Rank 1 is connect...'. Gloo's line arrived after the child's JSON.
• After: test_a_report_survives_output_written_after_it has the child report, then print a Gloo-shaped line and write to file descriptor 1; the report reads back and stdout's last line is the descriptor write. Red first: the test module failed to import report.
• Local, one directory per process: tests/testing 184 passed, tests/runtime 124, tests/checkpoint 96, tests/rng 24, tests/artifacts 16, tests/tracking 60. The 2 skips are GPU tests on a CPU lane.
• Coverage 100% on child_report.py, child_process.py, examples.py and _example_main.py. ruff, format, pyright (0 errors) and every pre-commit hook pass.

Merge Danger

Door: two-way

Blast Radius: testing helpers

A breaking change to substrax.testing, which only test suites import. After the release and re-pin, datarax moves 7 parser calls in 5 files and the children of 13 run_processes callers, and artifex moves 2 parser calls and about 55 run_repo_json children. No other sibling calls last_json or last_json_as. One choice beyond the decision record: a second report in one child raises instead of replacing the first.

[read-the-docs-community]

Documentation build overview

📚 substrax | 🛠️ Build #35513567 | 📁 Comparing 76b7d63 against latest (79a37e8)

  🔍 Preview build  

2 files changed

± index.html
± api/testing/index.html