API reference · grader/executor.py · 395 lines

`grader.executor`

Notebook execution (design.md §18-19).

Two modes share one code path: the notebook is instrumented with probe cells, written into an isolated working directory, and executed by a subprocess. Docker is the default because student code is untrusted; local execution exists for machines without Docker and is labelled unsafe everywhere it appears.

Summary

Name	Kind	Description
`ExecutionConfig`	class	Limits for one notebook execution, derived from `GraderSettings`.
`ExecutionError`	class
`build_probe_cells()`	function	Return the notebook cells that dump the student's namespace to JSON.
`build_url_redirect_cell()`	function	A first cell that points data URLs at the supplied local file.
`instrument_notebook()`	function	Append probe cells (and, if needed, prepend URL redirects) to a copy.
`docker_available()`	function	Whether a Docker daemon answers on this machine.
`docker_image_exists()`	function	Whether the sandbox image has been built locally.
`execute_submission()`	function	Execute one prepared submission. Returns (execution record, probe payload).
`strip_probe_cells()`	function	Remove the injected cells so the saved notebook is the student's work.

Constants

Name	Value	Notes
`MODE_DOCKER`	`'docker'`
`MODE_LOCAL`	`'local'`
`PACKAGE_DIR`	`Path(__file__).resolve().parent`
`RUNNER_SOURCE`	`PACKAGE_DIR / 'notebook_runner.py'`
`PROBE_SOURCE`	`PACKAGE_DIR / 'probe_runtime.py'`
`INSTRUMENTED_NAME`	`'_musa_instrumented.ipynb'`
`RUNNER_NAME`	`'_musa_runner.py'`
`ARTIFACTS_DIRNAME`	`'_musa_artifacts'`
`DEFAULT_IMAGE`	`'musa-grader:latest'`
`URL_REDIRECT_TEMPLATE`	`'# --- MUSA Grader: the grading run is offline; URLs of supplied data files read the local copy ---\ndef _musa_install_url_redirects(redire…`

Classes

class ExecutionConfig #[source]

dataclass

Limits for one notebook execution, derived from GraderSettings.

Fields

Name	Type	Default
`mode`	`str`	`MODE_DOCKER`
`docker_image`	`str`	`DEFAULT_IMAGE`
`timeout_seconds`	`int`	`600`
`cell_timeout_seconds`	`int`	`300`
`memory_limit`	`str`	`'2g'`
`cpu_limit`	`str`	`'1.0'`

Properties

property hard_timeout: int #[source]: No description.

class ExecutionError(RuntimeError) #[source]

No description.

Functions

build_probe_cells(probe_config: dict[str, Any]) -> list[Any] #[source]: Return the notebook cells that dump the student's namespace to JSON.

build_url_redirect_cell(redirects: dict[str, str]) -> Any #[source]

A first cell that points data URLs at the supplied local file.

The container has no network, by design. A student who loads the data straight from Zillow's URL is following a reasonable pattern, so a URL whose filename matches a file the instructor supplied is read from that local copy; any other URL still fails exactly as it would offline.

instrument_notebook(notebook_path: str | Path, probe_config: dict[str, Any], output_path: str | Path, url_redirects: dict[str, str] | None = None) -> Path #[source]: Append probe cells (and, if needed, prepend URL redirects) to a copy.

docker_available() -> bool #[source]: Whether a Docker daemon answers on this machine.

docker_image_exists(image: str) -> bool #[source]: Whether the sandbox image has been built locally.

execute_submission(workdir: str | Path, probe_config: dict[str, Any], config: ExecutionConfig, run_subdir: str = '') -> tuple[ExecutionRecord, dict[str, Any] | None] #[source]

Execute one prepared submission. Returns (execution record, probe payload).

run_subdir is where inside workdir the notebook runs from (see prepare_workdir); artifacts always go to workdir/_musa_artifacts.

strip_probe_cells(notebook_path: str | Path) -> Path #[source]: Remove the injected cells so the saved notebook is the student's work.