Files
claude-config/bin/plan_store/plans.py
T

64 lines
3.1 KiB
Python

"""What every plan backend reads and writes: a Plan, a Written, the PlanStore protocol they all meet, and the fields a caller may set on an item."""
import dataclasses
import typing
from plan.todo_table import BLOCKED_BY, Item, MOVES
from failure import Failure
from plan.release import Release
TAGLINE = "Tagline"
# What a caller may set on an item, each as text in the format `rank_todo.py --help` states for the cell of that name. TAGLINE is the Item cell, bold or not.
FIELDS = ("Release", BLOCKED_BY, "Exempt", TAGLINE, "L", "E", "I", "S", MOVES)
@dataclasses.dataclass(frozen=True)
class Plan:
"""A plan as one read found it."""
# Each item with its detail, in the order the backend supplies: by release and then by rank for a markdown file, by backlog rank for a tracker.
items: list[Item]
# The releases the plan marks renamed. Such a release holds no item because its items moved, not because it is finished.
renamed: frozenset[Release] = frozenset()
@dataclasses.dataclass(frozen=True)
class Written:
"""A write that landed."""
id: int
# What the backend says of the plan after the write, for stderr, such as an item now under the bar.
notes: tuple[str, ...] = ()
class PlanStore(typing.Protocol):
"""A project's plan. plan_store.contract holds every backend that writes to the same behaviour; `jira_epic` doesn't hold it yet: it changes no link, and its own tests stand in for Jira. A write that fails leaves the plan as it was, except where its Failure says the tracker may have taken the write all the same, as when Jira's answer to a new issue, an edit or a finish is lost."""
@property
def label(self) -> str:
"""What a message calls the plan, such as its path."""
@property
def tracked(self) -> str | None:
"""The plan'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 tracker."""
def read(self) -> Plan | Failure:
"""The plan as it stands. A NoItemsTable where the project has not set one up."""
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
"""Files an item under an ID the backend picks. fields holds each of FIELDS the caller sets; detail may be empty."""
def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure:
"""Sets item id_'s fields to those given, and its detail unless None, leaving the rest. Moving an item sets its Release.
comment tells the plan's other readers why, in the project's language. A tracker posts it on the item's issue; a backend with no place for comments drops it."""
def finish(self, id_: int) -> Written | Failure:
"""Removes item id_ with its detail."""
def cells(fields: dict[str, str]) -> dict[str, str]:
"""fields by the items table's column names."""
unknown = set(fields) - set(FIELDS)
if unknown:
# A programming error, so nothing catches it: a caller takes its fields from FIELDS.
raise ValueError(f"{', '.join(sorted(unknown))}: not a field; the fields are {', '.join(FIELDS)}")
return {"Item" if name == TAGLINE else name: value for name, value in fields.items()}