API reference

The root package provides backend-independent entry points for ordinary runs. Choose executors from kkrunner.backends or kkrunner.remote; projects, file manifests and advanced run contracts have their own public subpackages. These import paths are independent of the modules implementing each type.

Common entry points

ExecutionSpec(argv[, input_file, ...])

Command, files and launch intent handed to an execution backend.

ExecutionOutcome([output_file, input_file, ...])

Raw execution facts available before task-specific interpretation.

RunManager([store, executor_pool, ...])

Persist public run lifecycle without task-specific knowledge.

RunStore(directory)

Run history stored as date-sharded durable JSON files.

RunState(*values)

Single authoritative lifecycle state of one calculation run.

TaskFile(pathname[, type, info, optional])

One task file declaration, or its resolved path with retained metadata.

ProcessingPending

Execution is complete, but this observer did not perform required processing.

Execution contracts and durable records

LaunchSpec([mpi, local_root, remote_root, ...])

Portable launch and staging parameters for one concrete run.

MpiSpec([required, autodetect, launcher, ...])

Portable MPI launch semantics independent of the execution host.

MpiNotFoundWarning

MPI autodetection was requested, but no MPI launcher was found.

RunStatus(state[, backend_id, execution, ...])

Backend status facts; the client owns durable RunRecord state.

FailurePhase(*values)

Phase in which a run entered RunState.FAILED.

Runner(*args, **kwargs)

One concrete calculation run.

BackendRunner(*args, **kwargs)

Raw execution plus facts consumed by persistent orchestration.

ManagedRunner(*args, **kwargs)

A persistent observer with explicit start, refresh and detach support.

Executor()

Execution backend.

PersistentRunner(manager, executor, runner, ...)

Caller-owned runner that persists the public lifecycle directly.

RunRecord(id, state, created_at, updated_at, ...)

Single durable identity, file manifest and lifecycle of one calculation.

CorruptRunRecord(path, message)

A persisted run record cannot be decoded or validated.

DuplicateSubmissionError(record, conflicts)

A persistent run would duplicate an active calculation namespace.

HistoricalFileMismatchError

Restored contents differ from a run's captured SHA-256 digest.

Execution(endpoint, directory[, backend_id])

Backend identity plus the directory in which the job executes.

WorkingDirectory(local[, remote])

Local working directory and its optional target-side counterpart.

Declared files and identity

FileEntry([local_path, remote_path, ...])

Location of one file, with no assumptions about its content.

CacheEntry(file[, before])

Cache identity and its pre-execution remote signature.

FileMapping(local_root, remote_root[, ...])

Resolved mapping and transfer policy of this run's file manifest.

FileManifest([inputs, outputs, caches, ...])

All paths and cache baselines required for transfer and reconnect.

FileSyncPolicy(*values)

Policy controlling transfers between local and remote workspaces.

ArtifactAvailabilityState(*values)

Availability of a declared local artifact.

FileFingerprint(device, inode, mode, size, ...)

Metadata identity of one filesystem object at one point in time.

FileState(*values)

Relationship between a captured file version and its path on disk now.

FileVersion(path, fingerprint[, digest])

A path together with cheap metadata and authoritative content identity.

FileVersionCaptureError

A stable content identity could not be captured for an existing file.

Execution backends

LocalExecutor()

Create raw runners executed as local subprocesses.

PsijExecutor([backend, url, config, ...])

Execute calculations through a PSI/J backend such as Slurm or PBS.

ExecutorEndpoint([executor, host, ...])

Identity of a reusable execution backend.

ExecutorPool()

Process-local cache of reusable execution backends.

default_executor_pool()

Return the process-wide pool used by ordinary calculations.

Remote execution and transport

RemoteEndpointExecutor(transport, *[, ...])

Reusable remote endpoint with client-owned lifecycle state.

Transport()

Run commands and move files on one target machine.

RunningCommand(*args, **kwargs)

A running command with independently readable output streams.

LocalTransport()

Transport backed by asyncio subprocesses and the local filesystem.

SshTransport(host, *[, ssh, options, zstd, ...])

Transport using the system ssh client.

Projects

Project(id, generation, name[, parent_id, ...])

One immutable project snapshot.

ProjectRepository([directory])

Persist and publish generation-checked project JSON documents.

ProjectRepositoryError

Base error for persistent project metadata.

ProjectConflictError(project_id, *, ...)

A project changed after the caller loaded it.

ProjectDeleteError

A project cannot be deleted while its hierarchy role requires it.

ProjectExecutionManager([store, ...])

Track a run only when it belongs to an existing project.

default_projects_directory()

Return the KKRunner state directory containing project JSON files.

Backend implementation interfaces

These modules expose lower-level runner implementations and resource ownership helpers for backend authors. They are not re-exported by the public facades.

backends.local.LocalRunner(spec[, callback])

One local subprocess execution.

backends.psij.PsijRunner(executor, spec[, ...])

One raw job managed by a PSI/J executor.

remote.runner.RemoteRunner(executor, spec[, ...])

Client-side raw execution identified by an opaque backend ID.

runs.processing.PostprocessingRunner(runner, ...)

Convert a raw execution outcome into the caller-visible result.

runs.base.ExecutionResources(*resources)

Closable resources whose ownership is transferred to a calculation run.

runs.base.ResourceOwnedRunner(runner, resources)

Runner proxy owning resources and the public submit/cancel boundary.