Group runs in projects
Projects are optional. ProjectRepository stores project names,
hierarchy and working directories. ProjectExecutionManager
associates runs with a selected project and uses the same persistence and
reservations as RunManager. Project definitions and run
records have separate stores.
import sys
import tempfile
from pathlib import Path
from kkrunner import ExecutionSpec, RunStore
from kkrunner.backends import LocalExecutor
from kkrunner.projects import ProjectExecutionManager, ProjectRepository
workspace = tempfile.TemporaryDirectory()
directory = Path(workspace.name)
projects = ProjectRepository(directory / "projects")
project = projects.create("Example", directory=directory)
manager = ProjectExecutionManager(
store=RunStore(directory / "runs"),
project_repository=projects,
project=project,
)
run = manager.create_run(
LocalExecutor(),
ExecutionSpec([sys.executable, "-c", "pass"], directory=directory),
)
print(run.run().return_code)
print(manager.store.get(run.id).project_id == project.id)
0
True
You can also create an unbound manager and call manager.for_project(project).
It returns a bound manager without replacing an already bound project’s identity.
Explicitly supplied stores are shared across projects; file reservations still
prevent conflicting runs in different projects.
Project snapshots are immutable. project.modify(...) returns an edited
snapshot; persist it using repository.save(..., expected_generation=...).
Stale generations raise ProjectConflictError. Deleting a root,
a project with children, or a project with active runs raises
ProjectDeleteError. Subscribers receive repository changes
through refresh(); on-disk files remain authoritative.
For application integration, retain the application’s existing project repository location and pass it explicitly. Choosing a new run-record namespace must not silently move or hide existing project definitions.