Adding Python Modules & the Overlay

Three mechanisms get extra Python code into the runtime, in increasing order of weight.

In-memory modules

Install small pure-Python packages when you create the factory:

PythonExecutorFactory factory = PythonExecutorFactory
  .builder()
  .withStdlibPath(pythonRoot)
  .withModule("my_package", "helpers", "def double(x): return x * 2")
  .build();

from my_package.helpers import double

withLibrary(name, modules) does the same for a map of module name → source. Use this for small helper code generated or selected at runtime.

The resource overlay (repo contributors)

Inside this repo, most packaged runtime files under core/src/main/resources/python/ are generated by the WASM/CPython pipeline and git-ignored. Small source-controlled Python additions to the stock runtime live under core/src/main/resources/python-overlay/, which mirrors the guest filesystem layout:

core/src/main/resources/python-overlay/usr/local/lib/python3.14/boomslang_host/asyncio.py
→ <stdlibPath>/usr/local/lib/python3.14/boomslang_host/asyncio.py

During factory creation, boomslang extracts the generated python/ resources first, then copies the overlay on top.

Snapshot precedence: modules that are prewarmed into the Wizer snapshot are served from the frozen sys.modules at runtime — for those, editing the overlay file has no effect until the WASM is rebuilt. Use the overlay only for modules that are imported at execution time.

The resource pipeline

Larger third-party packages — anything with native code, or big enough that in-memory installation is impractical — belong in the WASM/Python build pipeline, where they are baked into the runtime resources (and optionally prewarmed). See Custom Python builds.