Provide overload type hints for search_issues variants (#1861)

examples/auth.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 from collections import Counter
-from typing import cast
 
 from jira import JIRA
 from jira.client import ResultList
@@ -25,9 +24,7 @@
 props = jira.application_properties()
 
 # Find all issues reported by the admin
-# Note: we cast() for mypy's benefit, as search_issues can also return the raw json !
-#   This is if the following argument is used: `json_result=True`
-issues = cast(ResultList[Issue], jira.search_issues("assignee=admin"))
+issues: ResultList[Issue] = jira.search_issues("assignee=admin")
 
 # Find the top three projects containing issues reported by admin
 top_three = Counter([issue.fields.project.key for issue in issues]).most_common(3)

jira/client.py

@@ -3480,6 +3480,22 @@ def resolution(self, id: str) -> Resolution:
 
     # Search
 
+    @overload
+    def search_issues(
+        self,
+        jql_str: str,
+        startAt: int = 0,
+        maxResults: int = 50,
+        validate_query: bool = True,
+        fields: str | list[str] | None = "*all",
+        expand: str | None = None,
+        properties: str | None = None,
+        *,
+        json_result: Literal[False] = False,
+        use_post: bool = False,
+    ) -> ResultList[Issue]: ...
+
+    @overload
     def search_issues(
         self,
         jql_str: str,
@@ -3489,6 +3505,21 @@ def search_issues(
         fields: str | list[str] | None = "*all",
         expand: str | None = None,
         properties: str | None = None,
+        *,
+        json_result: Literal[True],
+        use_post: bool = False,
+    ) -> dict[str, Any]: ...
+
+    def search_issues(
+        self,
+        jql_str: str,
+        startAt: int = 0,
+        maxResults: int = 50,
+        validate_query: bool = True,
+        fields: str | list[str] | None = "*all",
+        expand: str | None = None,
+        properties: str | None = None,
+        *,
         json_result: bool = False,
         use_post: bool = False,
     ) -> dict[str, Any] | ResultList[Issue]:

tests/tests.py

@@ -23,7 +23,6 @@
 from parameterized import parameterized
 
 from jira import JIRA, Issue, JIRAError
-from jira.client import ResultList
 from jira.resources import Dashboard, Resource, cls_for_resource
 from tests.conftest import JiraTestCase, allow_on_cloud, rndpassword
 
@@ -231,19 +230,24 @@ def setUp(self):
 
     def test_search_issues(self):
         issues = self.jira.search_issues(f"project={self.project_b}")
-        issues = cast(ResultList[Issue], issues)
         self.assertLessEqual(len(issues), 50)  # default maxResults
         for issue in issues:
             self.assertTrue(issue.key.startswith(self.project_b))
 
+    def test_search_issues_json(self):
+        result = self.jira.search_issues(f"project={self.project_b}", json_result=True)
+        issues = result["issues"]
+        self.assertLessEqual(len(issues), 50)  # default maxResults
+        for issue in issues:
+            self.assertTrue(issue["key"].startswith(self.project_b))
+
     def test_search_issues_async(self):
         original_val = self.jira._options["async"]
         try:
             self.jira._options["async"] = True
             issues = self.jira.search_issues(
                 f"project={self.project_b}", maxResults=False
             )
-            issues = cast(ResultList[Issue], issues)
             self.assertEqual(len(issues), issues.total)
             for issue in issues:
                 self.assertTrue(issue.key.startswith(self.project_b))
@@ -263,15 +267,13 @@ def test_search_issues_startat(self):
 
     def test_search_issues_field_limiting(self):
         issues = self.jira.search_issues(f"key={self.issue}", fields="summary,comment")
-        issues = cast(ResultList[Issue], issues)
         self.assertTrue(hasattr(issues[0].fields, "summary"))
         self.assertTrue(hasattr(issues[0].fields, "comment"))
         self.assertFalse(hasattr(issues[0].fields, "reporter"))
         self.assertFalse(hasattr(issues[0].fields, "progress"))
 
     def test_search_issues_expand(self):
         issues = self.jira.search_issues(f"key={self.issue}", expand="changelog")
-        issues = cast(ResultList[Issue], issues)
         # self.assertTrue(hasattr(issues[0], 'names'))
         self.assertEqual(len(issues), 1)
         self.assertFalse(hasattr(issues[0], "editmeta"))
@@ -283,7 +285,6 @@ def test_search_issues_use_post(self):
         with pytest.raises(JIRAError):
             self.jira.search_issues(long_jql)
         issues = self.jira.search_issues(long_jql, use_post=True)
-        issues = cast(ResultList[Issue], issues)
         self.assertEqual(len(issues), 1)
         self.assertEqual(issues[0].key, self.issue)