95 lines
3.9 KiB
Python
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")
|