74 lines
3.5 KiB
Python
74 lines
3.5 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 no_item(label: str, id_: int | str) -> str:
|
|
"""What every store says of an item id_ that the plan label names doesn't hold. `chunk-pr merge` reads `todo-item show`'s answer by it, through says_no_item."""
|
|
return f"{label} holds no item {id_}"
|
|
|
|
|
|
def says_no_item(reason: str, id_: int | str) -> bool:
|
|
"""Whether a failure's reason, such as `todo-item show`'s, says the plan doesn't hold item id_, as no_item words it."""
|
|
return no_item("", id_) in reason
|
|
|
|
|
|
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()}
|