feat: [DEV-14864] add submission cancellation query support (#455)

Author: jacobmanderson

indico/queries/submission.py

@@ -7,7 +7,12 @@
 from indico.errors import IndicoInputError, IndicoTimeoutError
 from indico.filters import SubmissionFilter
 from indico.queries import JobStatus
-from indico.types import Job, Submission, SubmissionReviewFull
+from indico.types import (
+    Job,
+    Submission,
+    SubmissionCancellationResult,
+    SubmissionReviewFull,
+)
 from indico.types.submission import VALID_SUBMISSION_STATUSES
 from indico.types.utils import Timer
 
@@ -626,3 +631,36 @@ def process_response(self, response: "Payload") -> "List[Submission]":
         return [
             Submission(**s) for s in super().parse_payload(response)["retrySubmissions"]
         ]
+
+
+class CancelSubmissions(GraphQLRequest["SubmissionCancellationResult"]):
+    """
+    Given a list of submission ids, cancel those active submissions.
+
+    Args:
+        submission_ids (List[int]): the given submission ids to cancel.
+    """
+
+    query = """
+    mutation cancelSubmissions($submissionIds:[Int]!){
+      cancelSubmissions(submissionIds: $submissionIds){
+        cancelled
+        skipped{
+          submissionId
+          reason
+        }
+      }
+    }
+    """
+
+    def __init__(self, submission_ids: "List[int]"):
+        if submission_ids is None or len(submission_ids) < 1:
+            raise IndicoInputError("You must specify submission ids")
+        if len(set(submission_ids)) != len(submission_ids):
+            raise IndicoInputError("Cannot include duplicate submission ids")
+
+        super().__init__(self.query, variables={"submissionIds": submission_ids})
+
+    def process_response(self, response: "Payload") -> "SubmissionCancellationResult":
+        payload = super().parse_payload(response)["cancelSubmissions"]
+        return SubmissionCancellationResult(**payload)

indico/types/submission.py

@@ -42,6 +42,32 @@ class SubmissionRetries(BaseType):
     submission_id: int
 
 
+class SubmissionCancellationSkipped(BaseType):
+    """
+    Information about a submission that was skipped during cancellation.
+
+    Attributes:
+        submission_id (int): The ID of the submission that was not cancelled.
+        reason (str): The reason it was skipped.
+    """
+
+    submission_id: int
+    reason: str
+
+
+class SubmissionCancellationResult(BaseType):
+    """
+    Result payload from a submission cancellation request.
+
+    Attributes:
+        cancelled (List[int]): Submission IDs that were successfully cancelled.
+        skipped (List[SubmissionCancellationSkipped]): Submission IDs that were skipped.
+    """
+
+    cancelled: List[int]
+    skipped: List[SubmissionCancellationSkipped]
+
+
 class SubmissionReview(BaseType):
     f"""
     Information about a submission's Reviews.

tests/unit/test_submission_cancel.py

@@ -0,0 +1,35 @@
+import pytest
+
+from indico.errors import IndicoInputError
+from indico.queries import CancelSubmissions
+from indico.types import SubmissionCancellationResult
+
+
+def test_cancel_submissions_requires_ids() -> None:
+    with pytest.raises(IndicoInputError, match="must specify submission ids"):
+        CancelSubmissions([])
+
+
+def test_cancel_submissions_rejects_duplicate_ids() -> None:
+    with pytest.raises(IndicoInputError, match="duplicate submission ids"):
+        CancelSubmissions([1, 1])
+
+
+def test_cancel_submissions_process_response() -> None:
+    request = CancelSubmissions([1, 2])
+    result = request.process_response(
+        {
+            "data": {
+                "cancelSubmissions": {
+                    "cancelled": [1],
+                    "skipped": [{"submissionId": 2, "reason": "already terminal"}],
+                }
+            }
+        }
+    )
+
+    assert isinstance(result, SubmissionCancellationResult)
+    assert result.cancelled == [1]
+    assert len(result.skipped) == 1
+    assert result.skipped[0].submission_id == 2
+    assert result.skipped[0].reason == "already terminal"