Skip to content

_subprocess_env

_subprocess_env

Environment helper for spawned terok_sandbox child processes.

Centralises the PYTHONPATH shim every subprocess.run / Popen of sys.executable must use, so adding a new spawn site can't silently regress the Nix-wrapped-Python fix.

child_process_env(overrides=None)

Build the environment for a spawned terok_sandbox child process.

Threads the parent's absolute, non-cwd sys.path through as PYTHONPATH so the child can import terok_sandbox regardless of how the parent was launched. Under Nix, the launcher augments the parent's import path, but spawning sys.executable directly bypasses that launcher, leaving the child unable to find the terok_sandbox package. This shim restores it.

overrides are applied on top of the parent env; PYTHONPATH always wins so a stray ambient value can't shadow the parent's real import path. Cwd and relative entries are excluded to preserve the child's -P isolation, including symlink aliases of the cwd.

Source code in src/terok_sandbox/_util/_subprocess_env.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
def child_process_env(overrides: dict[str, str] | None = None) -> dict[str, str]:
    """Build the environment for a spawned ``terok_sandbox`` child process.

    Threads the parent's absolute, non-cwd ``sys.path`` through as ``PYTHONPATH`` so the
    child can import ``terok_sandbox`` regardless of how the parent was
    launched. Under Nix, the launcher augments the parent's import path,
    but spawning ``sys.executable`` directly bypasses that launcher,
    leaving the child unable to find the ``terok_sandbox`` package.
    This shim restores it.

    *overrides* are applied on top of the parent env; ``PYTHONPATH``
    always wins so a stray ambient value can't shadow the parent's
    real import path. Cwd and relative entries are excluded to preserve
    the child's ``-P`` isolation, including symlink aliases of the cwd.
    """
    cwd = Path.cwd()
    import_paths = (
        entry for entry in sys.path if os.path.isabs(entry) and Path(entry).resolve() != cwd
    )
    return {**os.environ, **(overrides or {}), "PYTHONPATH": os.pathsep.join(import_paths)}