Files
claude-config/bin/record_store/stores.py
T

95 lines
3.9 KiB
Python

"""The one way a tool reads or writes a project's records: through the store its config names for each.
Each record has its own setting in the config, so a project may keep one record in its wiki and another as a file. The setting's value names the backend. A path names a markdown file, the only backend so far."""
import dataclasses
import pathlib
import typing
from failure import Failure
from git_cli.git_repo import file_at, git, Git
from project_config.settings import ProjectConfig
from text_files.file_writes import replace_file
# The settings in a project's config that each name a record.
RECORDS = ("decisions", "score-anchors", "comprehension-history", "reading-cost", "changelog")
class RecordStore(typing.Protocol):
"""One record, as text. record_store.contract holds every backend to the same behaviour."""
@property
def label(self) -> str:
"""What a message calls the record, such as its path."""
@property
def tracked(self) -> str | None:
"""The record's path from the checkout's top, as git names a file in a commit; None where no commit holds a version of it, as for a file outside the checkout or a wiki page."""
def read(self) -> str | Failure:
"""The record's text as it stands, empty where it doesn't exist yet."""
def write(self, text: str) -> Failure | None:
"""Replaces the record's whole text, creating the record where it doesn't exist yet."""
@dataclasses.dataclass(frozen=True)
class FileStore:
"""A record kept as a markdown file at path."""
path: pathlib.Path
tracked: str | None
@property
def label(self) -> str:
return str(self.path)
def read(self) -> str | Failure:
try:
# Decoded from bytes, so the text keeps the line ends the file holds.
return self.path.read_bytes().decode("utf-8")
except FileNotFoundError:
return ""
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"cannot read {self.path}: {failure}")
def write(self, text: str) -> Failure | None:
try:
self.path.parent.mkdir(parents=True, exist_ok=True)
except OSError as failure:
return Failure(f"cannot write {self.path}: {failure}")
unwritten = replace_file(self.path, text.encode("utf-8"))
return Failure(f"cannot write {self.path}: {unwritten.reason}") if unwritten else None
def store(config: ProjectConfig, record: str) -> RecordStore:
"""The store config names for record, one of RECORDS."""
if record not in RECORDS:
raise ValueError(f"{record} is not a record; the records are {', '.join(RECORDS)}")
return FileStore(config.paths[record], config.tracked(record))
def held_at(revision: str, record: RecordStore, cwd: str, run: Git = git) -> str | Failure:
"""record's text at revision, read in the checkout at cwd, where its commits hold the record; else as it stands. Empty where there is no such record."""
return record.read() if record.tracked is None else file_at(revision, record.tracked, cwd, run)
def local_file(record: RecordStore, copy: pathlib.Path) -> pathlib.Path | Failure:
"""A file holding record's text, for an agent, which reads and edits files: the record's own file where a file is its backend, else copy, written with the text as it stands. Neither exists where the record doesn't yet. `stored` puts an edited copy back."""
if isinstance(record, FileStore):
return record.path
text = record.read()
if isinstance(text, Failure):
return text
if text and (unwritten := FileStore(copy, None).write(text)):
return unwritten
return copy
def stored(record: RecordStore, copy: pathlib.Path) -> Failure | None:
"""Stores in record the text of copy, the file `local_file` gave for it. Where that is the record's own file, the edit is already the record."""
if isinstance(record, FileStore):
return None
text = FileStore(copy, None).read()
if isinstance(text, Failure):
return text
return record.write(text) if text else Failure(f"{copy} is missing or empty, so nothing is stored in {record.label}; `record open` writes the file to edit")