devplacepy/issues.py at afb954deaa721c8f9a044fcecd97bd7d8058cf6b

 # retoor <retoor@molodetz.nl>
 from __future__ import annotations
 from ..spec import Action
 from ._shared import ATTACHMENTS, body, confirm, path, query
 ISSUE_ACTIONS: tuple[Action, ...] = (
     Action(
         name="list_issues",
         method="GET",
         path="/issues",
         summary="List issue tickets from the Gitea tracker",
         requires_auth=False,
         params=(
             query("state", "Filter by state: open, closed, or all."),
             query("page", "1-based page number."),
         ),
     ),
     Action(
         name="create_issue",
         method="POST",
         path="/issues/create",
         summary="Report an issue. It is rewritten by AI and filed on the tracker.",
         description=(
             "Queues a background issue creation job and returns {uid, status_url}. Poll the "
             "status_url with issue_job_status until status is 'done', then show the user the "
             "issue_url pointing at the filed ticket."
         ),
         params=(
             body("title", "Issue title.", required=True),
             body("description", "Issue description.", required=True),
         ),
     ),
     Action(
         name="planning_report_generate",
         method="POST",
         path="/issues/planning",
         summary="Queue an admin planning report of open tickets.",
         description=(
             "Queues a background job that builds a phased, ordered markdown implementation "
             "document for open tickets and returns {uid, status_url}. Pass 'numbers' as a "
             "comma-separated list of issue numbers to plan only those tickets; omit it to plan "
             "every open ticket. Each ticket's full description is reproduced verbatim, both "
             "inline and in a 'Source Tickets (verbatim)' appendix, so the document is "
             "self-contained. Poll the status_url until status is 'done', then show the markdown "
             "and the download_url. Admin only."
         ),
         params=(
             body(
                 "numbers",
                 "Comma-separated issue numbers to include (e.g. '1,4,7'). Omit for all open tickets.",
             ),
         ),
         requires_auth=True,
         requires_admin=True,
     ),
     Action(
         name="issue_job_status",
         method="GET",
         path="/issues/jobs/{uid}",
         summary="Poll an issue creation job and obtain the filed issue ticket URL once finished",
         description=(
             "Returns the job status. When status is 'done', issue_url and number are populated; "
             "while 'pending' or 'running', poll again shortly."
         ),
         params=(path("uid", "Issue job uid returned by create_issue."),),
         requires_auth=False,
     ),
     Action(
         name="view_issue",
         method="GET",
         path="/issues/{number}",
         summary="View an issue ticket and its developer updates",
         requires_auth=False,
         params=(path("number", "The issue ticket number from a /issues listing."),),
     ),
     Action(
         name="comment_issue",
         method="POST",
         path="/issues/{number}/comment",
         summary="Post a comment on an issue ticket, attributed to the current user",
         params=(
             path("number", "The issue ticket number."),
             body("body", "Comment text.", required=True),
         ),
     ),
     Action(
         name="set_issue_status",
         method="POST",
         path="/issues/{number}/status",
         summary="Change an issue ticket status (admin only)",
         requires_admin=True,
         params=(
             path("number", "The issue ticket number."),
             body("status", "New status: open or closed.", required=True),
         ),
     ),
     Action(
         name="list_issue_attachments",
         method="GET",
         path="/issues/{number}/attachments",
         summary="List the files attached to an issue ticket",
         requires_auth=False,
         params=(path("number", "The issue ticket number."),),
     ),
     Action(
         name="add_issue_attachment",
         method="POST",
         path="/issues/{number}/attachments",
         summary="Attach already-uploaded files to an open issue ticket",
         description=(
             "Upload files first with upload_file, then pass their uids here. Only works while "
             "the issue is open; the files are mirrored to the tracker."
         ),
         params=(
             path("number", "The issue ticket number."),
             body("attachment_uids", ATTACHMENTS, required=True),
         ),
     ),
     Action(
         name="delete_issue_attachment",
         method="DELETE",
         path="/issues/{number}/attachments/{uid}",
         summary="Delete a file from an open issue ticket (your own, or any when administrator). Soft delete, confirmation required",
         params=(
             path("number", "The issue ticket number."),
             path("uid", "The attachment uid."),
             confirm(),
         ),
     ),
     Action(
         name="add_comment_attachment",
         method="POST",
         path="/issues/{number}/comments/{cid}/attachments",
         summary="Attach already-uploaded files to an issue comment (issue must be open)",
         params=(
             path("number", "The issue ticket number."),
             path("cid", "The Gitea comment id."),
             body("attachment_uids", ATTACHMENTS, required=True),
         ),
     ),
     Action(
         name="delete_comment_attachment",
         method="DELETE",
         path="/issues/{number}/comments/{cid}/attachments/{uid}",
         summary="Delete a file from an issue comment (your own, or any when administrator). Soft delete, confirmation required",
         params=(
             path("number", "The issue ticket number."),
             path("cid", "The Gitea comment id."),
             path("uid", "The attachment uid."),
             confirm(),
         ),
     ),
 )