Skip to content

Prepared copies

prepare_project creates a disposable copy of a project and a separate snapshot of its inputs. An adapter created on the original context still runs in place: only adapters created inside use() run in the copy. Preparing gives no permission to clean up the existing project. Use it when tests may write, remove or change project files. Getting started shows the basic use, and Containers the use in a container.

prepare_project installs no interpreters, build tools or dependencies. Each language operation keeps its own setup and capability checks, so preparing a copy does not make an unsupported operation available.

Inputs and outputs

Besides the project, prepare_project(companions=(...)) copies directories outside it that its runs use, such as a suite beside the project. bytecode= takes a langadapter.python.project.BytecodeStore, which writes stored compiled modules into each use's copy and stores what the runs compiled.

Do not change the original project while it is being copied. A copy holds ordinary files and directories, never symbolic links, junctions or special files. Entries left out with exclude, and Python bytecode caches, are skipped before this check. A link or special file anywhere else makes the project refused rather than copied in part. The project directory itself must not be a link either, while the directories above it may be links. PreparedProject.stage_suite applies the same rule to a suite it copies into the copy: no link inside the suite's directory or as that directory. The parent directory of the copy, the parent directory of the receipts (the records of each copy's creation) and the system's temporary directory, which holds the snapshot, must each lie outside the original project. For a project on this machine prepare_project refuses one that lies inside. In a container it checks that the work directory, which holds the copy, lies outside the project. For a project inside the work directory it also refuses a receipts' directory or temporary directory inside the project, and for every project one inside a companion directory. For a project outside the work directory the caller keeps those two directories outside the project. The two parent directories may be the same directory. prepare_project(parent=..., receipt_parent=...) chooses them. The copy goes to parent, else to the context's work directory when it has one, else to the system's temporary directory. In a container it always goes to the work directory, and another parent is refused. The receipts, and the snapshot a copy is restored from, go to the system's temporary directory unless receipt_parent names another for the receipts. The system's temporary directory is used by its physical path: links in it are resolved (macOS's /var becomes /private/var), and on Windows short names are expanded. A directory named by parent, receipt_parent or the work directory is used as named.

prepare_project(context, inputs=ProjectInputSelection(exclude=(...))) leaves named entries out of the copy. A program uses this for files that are not project inputs, such as a virtual environment directory inside the project or the program's own configuration. Paths named in required= and the test framework configuration file selected inside the project cannot be left out. Nothing else is protected, so name the suite's files in required= when an exclusion could cover them.

Each use() restores the whole copy from its snapshot, including changed and deleted input files. Paths to test framework configuration that belongs to the project point to the copy. Project resources and build wrappers keep their relative locations. Tools and configuration chosen explicitly outside the project stay as chosen. Environment variable values that contain the original project directory's path are refused, never silently rewritten, whether alone, in a path list or in an option. A letter, digit, ., _ or - directly before or after the path makes it part of another directory's name. For a project at a drive root such as P:\, or at / in a container, every path below it counts as inside. So for a project at /app the values /app-env, /app2 and /opt/app are outside, while /app/src, --rootdir=/app -x, /app env and /app (2) count as inside. PWD and OLDPWD are exempt: they name the caller's shell location. Choose the toolchain and the environment variables before preparing: changing them on a copied context gives it no new permission to run commands.

An environment inside the project is the exception on the host. A value whose every path into the project lies in a directory holding pyvenv.cfg or conda-meta, such as VIRTUAL_ENV=/app/.venv or /app/.venv/bin on PATH, is admitted when nothing in that environment's site directories leads into the project outside it. The check reads them without running the environment: .pth path entries and the import hooks they load, .egg-link files, sitecustomize and usercustomize, package directories linked in, and the records of editable installs. When one leads into the project, as an editable install of the project does, the refusal names the file and the path. An environment that includes the base interpreter's packages (--system-site-packages) is refused, since their directories are not read. An admitted environment's directory is left out of the copy, and the copy's commands use it in place. In a container such values stay refused.

One change is allowed. An adapter that runs another adapter on the same project, as the C adapter runs Python tests through Python's, makes the context it gives that adapter with context.derived(environment=..., work_dir=...). The derived context keeps the root, the interpreter, its flags and the test framework. It adds variables and a work directory the caller made. A variable the context sets itself is refused, unless extend names it with its separator, as in extend={"PYTHONPATH": os.pathsep}: the added value then comes first and the context's value follows. An added variable overlays the caller's environment as the context's own variables do. Made from the context use() yields, it belongs to that use and stops with it. The directories LangAdapter makes in its work directory keep their creation receipts there, so removing the work directory removes them too. Its observations record the variables as given, with the work directory's path written <work_dir>.

A use runs commands from one thread at a time. An engine that runs its units of work side by side, as the C adapter runs its mutants, does so with langadapter.execution.run_parallel(function, items, workers=...). Inside a use, the use lends itself to those threads for their calls. Every command they run is checked as the use's own, and the call returns only once every thread has ended, raising the first error a call raised. Each call must write only in a directory of its own, never in the copy's tree.

Build requests from the root that use() yields. Paths and strings in requests are not rewritten to point into the copy. Write delivered suites, logs and other lasting outputs outside the copy and the snapshot. A successful close() removes both directories it created and their ownership records. Results already returned do not depend on that cleanup.

remove_created_files=True needs this prepared context, in Python and in Java. It refuses an ordinary shared project with OwnershipRefused, a LangAdapterError. Between completed runs in one use, only files that the copy recorded as its own outputs are removed. Files created later are left alone, and directories are removed only when empty. Cleanup is refused for output directories that contain links and while a command has not been confirmed to have ended. Repeated uses also restore changed or deleted inputs from the snapshot. Ordinary runs without cleanup still work without preparation.

Python imports in a copy

A Python run in a copy measures the copy's module under test. An installed copy of the project, or an editable install that points to the original project, would give the tests another file, and the copy would read as never run. When another location provides the project's package, the run puts the copy's directory first on the import path. This works for a package in the project directory or in any directory directly inside it, and for a module in the project directory or in its src, lib or python directory. An interpreter inside the project, such as the project's own .venv, runs in place from the original directory, and its installs are checked the same way.

During the run, the adapter records the file the tests execute the module under test from. A run that executed it only from another file is refused with infrastructure_failure and a reason that names that file:

  • An import hook of an editable install, as meson-python and setuptools in strict mode write one, takes precedence over the import path. Reinstall the project without editable mode (pip install .), and the copy's directory then goes first.
  • An installed copy, or another directory, that the copy's directory could not be put ahead of, such as a package more than one directory deep in the project, is not supported.
  • A compiled module built beside the module under test (an extension built in place) is loaded instead of the source. This is not supported. Remove the built module to measure the source.

A project whose package needs compiled modules that the copy does not hold, because they were built only into an installed copy or a build directory, is not supported either. A run that could not collect its tests without them is refused, and the reason names the module. A module that the tests never import is no refusal: its coverage is 0, and every mutant survives.

A run that names no module under test, such as a run of the whole suite, keeps its import path. It records each of the copy's modules that the tests executed from a file outside the copy, and it is refused the same way when there is one. It checks the modules in the project directory, in its src, lib or python directory and in a directory of the import path inside the copy. Modules elsewhere in the project are not checked. Naming the module under test has the copy's directory put first. A benchmark checks only through its first warmup repetition, so a benchmark without one is not checked. Its measured repetitions run without the check.

Lifetime and recovery

Only one use() or close() may hold a prepared project at a time. A scoped context belongs to its current use and thread. Cached adapters, copied contexts and sessions cannot run anything after that use, even during a later use of the same copy, and use from a thread that was not registered is refused. In a worker, create and use a separate prepared project rather than sharing a scoped context whose use has ended.

Close mutation sessions inside use(). Started commands and open sessions must confirm that they ended before the lease, the lock that reserves the copy for running commands, is released. An exception, an interruption, an owner mismatch or uncertain cleanup keeps the copy, the snapshot, the receipts and the lease. The owner is the object whose close() cleans them up. Keep the original owner and the session's cleanup handles, recover those resources and only then call close() on the same owner again. A process ID that disappeared does not make cleanup safe, and the lease must not be removed by hand.

root names the disposable copy. It is for diagnosis, not for taking over a copy: a context built on the copy, or on the snapshot it is restored from, is refused. A closed owner cannot be reused. Calling its close() again does no harm, and after a failed removal a new call retries only the directories that remain.

A prepared copy owns and restores its own directories only. Processes a run starts can still reach other files, and nothing records which process wrote which file. Keep unrelated processes and valuable files outside the disposable directories. Extension adapters must run commands through the context's executor and keep their cleanup handles. Subprocesses started outside that executor are not managed.

If an operation fails while it is uncertain whether a command has ended, it raises the original exception with its recovery handle instead of returning a failure result without one. Failures after a confirmed stop may return their normal typed outcome. Keep exceptions and owners until recovery completes. A failure result or a missing process ID alone does not permit discarding a copy that was kept.

Worker threads and separate measurements

Use prepared.worker(scoped) when an existing worker thread needs the current use's context. Enter it on that worker with the exact context use() yielded. It lends the context to that worker, one loan at a time. It is not a copied context or another use. Operations of the parent and competing loans are refused while it is active. An idle mutation session may stay open across loans. Close it before leaving the parent use. A loan neither restores the snapshot nor restarts the session. A mutation session whose cleanup failed or was interrupted may have left the target mutated or its workers running. Until its close(), retried on the parent's thread, succeeds, the use refuses every other operation, new loans and separate measurements included, and the refusal names the session as its cleanup_handle. Any other resource a loan leaves unresolved ends the use's work.

For a separate measurement, call prepare_project(original_context) inside the parent use, then enter and close that child's own use(). The original project must stay unchanged and outside the parent's copy and snapshot, and the directories and receipts of parent and child must not overlap. Children in a container need the same explicit container mapping and helper Python. Parent operations are refused while a child operation is active. An idle parent session and changed parent inputs stay intact. A child can be prepared and used only inside the use() of another prepared project, and it stays tied to that use.

Close every child before leaving the use that contains it. A child's error or a failed prepare_project call can keep the directories and commands it acquired even when no usable context was returned. Keep the original exception and pass it to langadapter.recovery_owners(error). Resolve the sessions, commands and scopes it returns first. Then call close() again on the owner it returns: the child's PreparedProject or, for a preparation that failed before one existed, the owner of the directories it allocated. An incomplete preparation cannot run anything. Once a child's use() or preparation ends with an exception, the parent's current use runs nothing more, even if you catch the error. New adapters, operations, children and worker loans are refused. The only call it still accepts is close() on the child's owner. Leaving the parent's use() fails, and keeps the parent's copy, until that close() succeeds. To run more, start a new use() of the parent.