120 lines
5.4 KiB
Python
120 lines
5.4 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, and `confluence:` a Confluence Cloud page; the goals file may also be a Jira epic's description, which `goals_store` picks."""
|
|
import dataclasses
|
|
import pathlib
|
|
import typing
|
|
|
|
from record_store.confluence_page import ConfluencePage
|
|
from record_store.jira_description import EpicDescription
|
|
from failure import Failure
|
|
from git_cli.git_repo import file_at, git, Git
|
|
from project_config.settings import ProjectConfig, RECORDS, TOUCH_PREDICTIONS
|
|
from text_files.file_writes import replace_file
|
|
|
|
|
|
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:
|
|
return self.path.read_text(encoding="utf-8")
|
|
except FileNotFoundError:
|
|
return ""
|
|
except UnicodeDecodeError as failure:
|
|
return Failure(f"cannot read {self.path}: not UTF-8 on line {failure.object[: failure.start].count(b'\n') + 1}")
|
|
except OSError as failure:
|
|
return Failure(f"cannot read {self.path}: {failure.strerror}")
|
|
|
|
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.strerror}")
|
|
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, kept: pathlib.Path | None = None) -> RecordStore:
|
|
"""The store config names for record, one of RECORDS. A record on a Confluence page keeps the version it read in the file the parameter kept names, for a later process that writes it; where kept is None, the store keeps the version only in memory."""
|
|
if record not in RECORDS:
|
|
raise ValueError(f"{record} is not a record; the records are {', '.join(RECORDS)}")
|
|
if record not in config.pages:
|
|
return FileStore(config.paths[record], config.tracked(record))
|
|
# load refuses a config that names a page and no env-file.
|
|
assert config.env_file is not None
|
|
return ConfluencePage(config.pages[record], config.env_file, kept)
|
|
|
|
|
|
def touch_predictions_store(config: ProjectConfig) -> RecordStore | None:
|
|
"""The store of the touch-predictions record, the one record a config may leave out; None where it does."""
|
|
if TOUCH_PREDICTIONS not in config.paths:
|
|
return None
|
|
return FileStore(config.paths[TOUCH_PREDICTIONS], config.tracked(TOUCH_PREDICTIONS))
|
|
|
|
|
|
def goals_store(config: ProjectConfig) -> RecordStore:
|
|
"""The store config names for the goals file, which holds ## Goals and ## Audience: a markdown file, or a Jira epic's description, which the store only reads."""
|
|
if config.goals_epic is None:
|
|
return FileStore(config.paths["goals-and-audience"], config.tracked("goals-and-audience"))
|
|
# load refuses a config that names an epic and no env-file.
|
|
assert config.env_file is not None
|
|
return EpicDescription(config.goals_epic, config.env_file)
|
|
|
|
|
|
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:
|
|
return FileStore(copy, None).write(text) or copy
|
|
try:
|
|
# An earlier copy would read as the record's text, and `stored` would put it back.
|
|
copy.unlink(missing_ok=True)
|
|
except OSError as failure:
|
|
return Failure(f"cannot remove {copy}: {failure.strerror}")
|
|
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}")
|