Jira: object has no attribute 'enhanced_jql'

 #1631

Author: gonchik

atlassian/jira/jira_cloud.py

@@ -5,7 +5,7 @@
 the compatibility clients for Server, Data Center, and existing Cloud users.
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 from ..rest_client import AtlassianRestAPI
 from .core_methods import JiraCloudCoreMethods
@@ -38,6 +38,62 @@ def endpoint(self, resource: str, api_version: Optional[Union[str, int]] = None)
             raise ValueError("Jira Cloud Core api_version must be 2 or 3")
         return self.resource_url(resource, api_root="rest/api", api_version=version)
 
+    def enhanced_jql(
+        self,
+        jql: str,
+        fields: Union[str, List[str]] = "*all",
+        nextPageToken: Optional[str] = None,
+        limit: Optional[int] = None,
+        expand: Optional[str] = None,
+    ):
+        """Search Jira Cloud issues through the v3 enhanced JQL endpoint.
+
+        Use ``nextPageToken`` from a previous response to retrieve the next
+        page. Unlike the older search API, enhanced JQL is cursor-paginated.
+        """
+        params: Dict[str, Union[str, int]] = {"jql": jql}
+        if nextPageToken is not None:
+            params["nextPageToken"] = str(nextPageToken)
+        if limit is not None:
+            params["maxResults"] = int(limit)
+        if fields is not None:
+            params["fields"] = ",".join(fields) if isinstance(fields, (list, tuple, set)) else fields
+        if expand is not None:
+            params["expand"] = expand
+        return self.get(self.endpoint("search/jql", api_version=3), params=params)
+
+    def enhanced_jql_get_list_of_tickets(
+        self,
+        jql: str,
+        fields: Union[str, List[str]] = "*all",
+        limit: Optional[int] = None,
+        expand: Optional[str] = None,
+    ) -> list:
+        """Return all cursor-paginated enhanced JQL issues up to ``limit``.
+
+        When ``limit`` is omitted, iteration continues until Jira marks the
+        result set as final.
+        """
+        results = []
+        next_page_token = None
+        while True:
+            response = self.enhanced_jql(
+                jql,
+                fields=fields,
+                nextPageToken=next_page_token,
+                limit=limit,
+                expand=expand,
+            )
+            if not response:
+                break
+            results.extend(response.get("issues", []))
+            if limit is not None and len(results) >= limit:
+                return results[:limit]
+            next_page_token = response.get("nextPageToken")
+            if response.get("isLast", False) or not next_page_token:
+                break
+        return results
+
 
 class JiraSoftware(JiraSoftwareMethods, AtlassianRestAPI):
     """Jira Software Cloud REST APIs.

docs/jira_cloud.rst

@@ -32,6 +32,24 @@ existing contract.  ``Jira`` still defaults to its historical string version
 ``"2"`` and does not automatically enable Cloud mode; this is intentional
 backward compatibility.
 
+Enhanced JQL search
+-------------------
+
+Both ``JiraCloud`` and the legacy ``Jira(..., cloud=True)`` client provide
+``enhanced_jql()``. The method always uses Jira Cloud's v3
+``/search/jql`` endpoint, regardless of the Core client's selected version.
+Pass the returned ``nextPageToken`` to fetch another page, or use
+``enhanced_jql_get_list_of_tickets()`` to collect cursor-paginated results.
+
+.. code-block:: python
+
+    issues = core.enhanced_jql_get_list_of_tickets(
+        'project = EXAMPLE ORDER BY updated DESC',
+        fields=["summary", "description"],
+        limit=100,
+        expand="names",
+    )
+
 Software API roots
 ------------------
 

tests/test_jira_cloud_clients.py

@@ -48,6 +48,44 @@ def test_core_methods_honor_the_selected_v2_route(self):
             jira.get_issue("ABC-1")
         get.assert_called_once_with("rest/api/2/issue/ABC-1", params=None, data=None)
 
+    def test_core_client_supports_enhanced_jql_at_v3(self):
+        jira = JiraCloud("https://example.atlassian.net", api_version=2)
+
+        with patch.object(jira, "get", return_value={"issues": [], "isLast": True}) as get:
+            jira.enhanced_jql(
+                "project = EXAMPLE ORDER BY key DESC",
+                fields=["summary", "description"],
+                nextPageToken="next-token",
+                limit=100,
+                expand="names",
+            )
+
+        get.assert_called_once_with(
+            "rest/api/3/search/jql",
+            params={
+                "jql": "project = EXAMPLE ORDER BY key DESC",
+                "fields": "summary,description",
+                "nextPageToken": "next-token",
+                "maxResults": 100,
+                "expand": "names",
+            },
+        )
+
+    def test_core_client_enhanced_jql_collects_cursor_pages(self):
+        jira = JiraCloud("https://example.atlassian.net")
+
+        with patch.object(
+            jira,
+            "enhanced_jql",
+            side_effect=[
+                {"issues": [{"key": "EXAMPLE-1"}], "nextPageToken": "next", "isLast": False},
+                {"issues": [{"key": "EXAMPLE-2"}], "isLast": True},
+            ],
+        ):
+            issues = jira.enhanced_jql_get_list_of_tickets("project = EXAMPLE")
+
+        self.assertEqual([issue["key"] for issue in issues], ["EXAMPLE-1", "EXAMPLE-2"])
+
     def test_software_client_builds_each_documented_api_root(self):
         jira = JiraSoftware("https://example.atlassian.net", cloud=False)