Skip to content

The research behind it

redef was not designed and then justified; it was measured into existence. The cs-lab research programme "python-macros" asked what Python does instead of macros, and the library is the artifact its findings demanded. This page is the short version, with pointers.

The census

The programme scanned the 500 most-downloaded PyPI packages for program transformation. Headline numbers: 11 of 476 scanned packages (2.3%) defer a fragment the user wrote to a library; 36 (7.6%) transform programs by any mechanism. Five packages defer through the enclosing function: typeguard, torch, execnet, snowflake-snowpark-python, numba. Four of the five recover source, and hand-reading their pipelines showed each implementing a different subset of the correctness details, with the stale-source check present in exactly one (typeguard's, by qualified name, which a same-named stale body still passes).

The measurements

  • E5, source availability: the recovery pipeline across 18 execution contexts and 5 CPython versions. 10 of 18 work on 3.14; the failures and their remedies became redef's error catalogue. Re-run with redef as the subject, the matrix reproduces exactly, with the three silent cells (stale source, closures, lambdas) turned into errors.
  • E3, tooling coverage: five static checkers rate a redef-decorated file exactly as they rate the hand-rolled decorator: clean. Packaging the mechanism adds no tooling cost.
  • E6, verify-by-recompile: the stale-body detector's reliability. Zero false positives in 330 cells (22 shapes × 5 interpreters × 3 optimization levels); both detection fixtures behave.
  • The field trial: porting a 73-test choreographic-programming prototype onto redef with verification on. The first run rejected an entire test file and was right three ways: it found the future-flags defect (live in the transformation path too), the cross-build cache phenomenon, and a layering error (closures refused too early). All three fixed; the suite then passed 73/73, and the prototype's stale-notebook failure mode, demonstrated before the port, now raises at decoration time.

The papers

Two working papers document the programme; both live in the research repository and build to PDF:

  • "What Python Does Instead of Macros": the deferral taxonomy, the census, and five cost measurements.
  • "What a Function Rewriter Gets Wrong": this library, its contract, verify-by-recompile, and the evaluation by re-running the motivating experiments.

Reproducibility

Every number in these pages comes from a recorded artifact, reproduced by one command in the research repository (python verify/run_all.py, 21 steps). The library's self-test runs the acquisition, location, hygiene, staleness, and closure cases; the experiment battery is effectively its integration suite.