59 lines
2.4 KiB
Python
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)
|