expand issue comments method to include all available API options (#1939)

Author: thedeltaflyer

jira/client.py

@@ -2337,19 +2337,35 @@ def assign_issue(self, issue: int | str, assignee: str | None) -> bool:
         return True
 
     @translate_resource_args
-    def comments(self, issue: int | str, expand: str | None = None) -> list[Comment]:
+    def comments(
+        self,
+        issue: int | str,
+        expand: str | None = None,
+        start_at: int | None = None,
+        max_results: int | None = None,
+        order_by: str | None = None,
+    ) -> list[Comment]:
         """Get a list of comment Resources of the issue provided.
 
         Args:
             issue (Union[int, str]): the issue ID or key to get the comments from
             expand (Optional[str]): extra information to fetch for each comment such as renderedBody and properties.
+            start_at (Optional[int]): index of the first comment to return (page offset)
+            max_results (Optional[int]): maximum number of comments to return
+            order_by (Optional[str]): order of the comments to return; should be 'created', '+created' or '-created'.
 
         Returns:
             List[Comment]
         """
         params = {}
         if expand is not None:
             params["expand"] = expand
+        if start_at is not None:
+            params["startAt"] = str(start_at)
+        if max_results is not None:
+            params["maxResults"] = str(max_results)
+        if order_by is not None:
+            params["orderBy"] = order_by
         r_json = self._get_json(f"issue/{issue}/comment", params=params)
 
         comments = [

tests/resources/test_comment.py

@@ -28,6 +28,51 @@ def test_comments(self):
             comments = self.jira.comments(issue)
             assert len(comments) == 0
 
+    def test_comments_start_at(self):
+        comments_created = []
+        for i in range(10):
+            comments_created.append(
+                self.jira.add_comment(self.issue_1_key, f"Comment #{i+1}")
+            )
+        comments = self.jira.comments(self.issue_1_key, start_at=5)
+        self.assertEqual(len(comments), 5)
+        self.assertEqual(comments[0].body, "Comment #6")
+        for comment in comments_created:
+            comment.delete()
+        comments = self.jira.comments(self.issue_1_key)
+        assert len(comments) == 0
+
+    def test_comments_max_results(self):
+        comments_created = []
+        for i in range(10):
+            comments_created.append(
+                self.jira.add_comment(self.issue_1_key, f"Comment #{i+1}")
+            )
+        comments = self.jira.comments(self.issue_1_key, max_results=4)
+        self.assertEqual(len(comments), 4)
+        self.assertEqual(comments[0].body, "Comment #1")
+        for comment in comments_created:
+            comment.delete()
+        comments = self.jira.comments(self.issue_1_key)
+        assert len(comments) == 0
+
+    def test_comments_order_by(self):
+        comments_created = []
+        for i in range(10):
+            comments_created.append(
+                self.jira.add_comment(self.issue_1_key, f"Comment #{i+1}")
+            )
+        comments = self.jira.comments(self.issue_1_key, order_by="created")
+        self.assertEqual(comments[0].body, "Comment #1")
+        comments = self.jira.comments(self.issue_1_key, order_by="+created")
+        self.assertEqual(comments[0].body, "Comment #1")
+        comments = self.jira.comments(self.issue_1_key, order_by="-created")
+        self.assertEqual(comments[0].body, "Comment #10")
+        for comment in comments_created:
+            comment.delete()
+        comments = self.jira.comments(self.issue_1_key)
+        assert len(comments) == 0
+
     def test_expanded_comments(self):
         comment1 = self.jira.add_comment(self.issue_1_key, "First comment")
         comment2 = self.jira.add_comment(self.issue_1_key, "Second comment")