kkrunner.projects.ProjectRepository

class kkrunner.projects.ProjectRepository(directory=None)[source]

Bases: object

Persist and publish generation-checked project JSON documents.

Files remain authoritative. The in-memory snapshot exists only to report changes discovered by refresh(); every save still performs its generation check against the current on-disk document while holding the corresponding stable sidecar lock.

Parameters:

directory (str | Path | None)

subscribe(listener)[source]

Subscribe to local or refreshed project changes.

Parameters:

listener (Callable[[str], None])

Return type:

Callable[[], None]

projects()[source]

Load and remember the complete project forest.

Return type:

tuple[Project, …]

project(project_id)[source]

Load and remember one project by UUID.

Parameters:

project_id (str)

Return type:

Project

refresh()[source]

Reload project files and publish ids whose snapshots changed.

Return type:

tuple[Project, …]

create(name, *, parent_id=None, directory=None)[source]

Create a root or child project at generation one.

Parameters:
  • name (str)

  • parent_id (str | None)

  • directory (str | Path | None)

Return type:

Project

save(project, *, expected_generation, overwrite=False)[source]

Persist an edited project snapshot using optimistic concurrency.

overwrite means exactly that: the supplied snapshot replaces newer persisted values after validating it against the current project forest. It is intentionally not an implicit merge operation.

Parameters:
  • project (Project)

  • expected_generation (int)

  • overwrite (bool)

Return type:

Project

delete(project_id, *, expected_generation)[source]

Delete an inactive leaf project and its globally stored run history.

Parameters:
  • project_id (str)

  • expected_generation (int)

Return type:

None