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

59 lines
2.4 KiB
Python

"""A project's goals and audience kept as the description of one Jira Cloud epic, read over Jira's REST API with the credentials of the config's env-file, and converted by the adf-codec shim.
The store only reads: a write, such as `project-record save goals-and-audience`, fails, saying to edit the epic in Jira."""
import dataclasses
import pathlib
from adf_codec.convert import adfs_to_markdown, Refused
from atlassian.client import basic_auth, Http, jira_json, ToMarkdown
from project_config.settings import Epic
from failure import Failure
from record_store.held import Held
READ_ONLY = "goals and audience kept in Jira are only read: edit the epic's description in Jira"
@dataclasses.dataclass(frozen=True)
class EpicDescription:
"""The description of epic as markdown, read with the credentials env_file holds."""
epic: Epic
env_file: pathlib.Path
http: Http = jira_json
to_markdown: ToMarkdown = adfs_to_markdown
@property
def label(self) -> str:
return self.epic.spelling
@property
def tracked(self) -> str | None:
return None
def read(self) -> str | Failure:
"""The description as markdown; empty where the epic has none."""
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
key = self.epic.key
answer = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{key}?fields=description", authorization, None)
if isinstance(answer, Failure):
return Failure(f"cannot read the epic {key}: {answer.reason}")
fields = answer.get("fields") if isinstance(answer, dict) else None
if not isinstance(fields, dict) or "description" not in fields or not isinstance(fields["description"], dict | None):
return Failure(f"the epic {key} is not in the shape Jira Cloud's REST API version 3 documents: its description field is missing, or neither a document nor null")
if fields["description"] is None:
return ""
texts = self.to_markdown([fields["description"]])
if isinstance(texts, Refused):
return Failure(f"{key}'s description: {texts.failure.reason}")
if isinstance(texts, Failure):
return Failure(f"cannot convert {key}'s description to markdown: {texts.reason}")
return texts[0]
def held(self) -> Held | Failure:
text = self.read()
return text if isinstance(text, Failure) else Held(text)
def write(self, text: str, over: str | None = None) -> Held | Failure:
return Failure(READ_ONLY)