feat(jira): give JiraClient both a sync and an async call form

Wraps the 12 client methods with flyte's @Syncify, matching how the SDK
itself exposes Run.listall, flyte.run and flyte.serve. Each method now has
two forms: `client.foo(...)` blocks, `await client.foo.aio(...)` does not.

- Adds __enter__/__exit__ so the blocking form is actually usable. They run
  __aenter__/__aexit__ on syncify's background loop -- the same loop the
  syncified methods run on -- so the httpx.AsyncClient is created and used
  on a single loop.
- Internal self-calls use .aio(). The blocking form would deadlock when
  called from syncify's own loop thread.
- The MCP tool bridge uses .aio(). `await getattr(client, name)(...)` would
  otherwise raise TypeError on the returned value, and would stall the MCP
  server's event loop for the duration of every tool call.
- Tests, examples and READMEs use .aio() on async paths, and document both
  forms plus when not to reach for the blocking one.

The syncified client type-checks clean: mypy resolves methods to
SyncFunction[...] and the error count on the package is unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VKZrTNjjWVzTZUxDFbn4Nk

Author: cosmicBboy

plugins/jira/README.md

@@ -47,7 +47,7 @@ from flyteplugins.jira import JiraClient
 @env.task
 async def open_ticket(project_key: str, summary: str) -> str:
     async with JiraClient() as client:
-        issue = await client.create_issue(project_key, summary)
+        issue = await client.create_issue.aio(project_key, summary)
     return issue["url"]
 ```
 
@@ -57,6 +57,24 @@ comments are converted to Jira's Atlassian Document Format automatically, and
 issue descriptions are converted back to plain text on read. Errors are raised
 as `JiraAPIError`; 429 rate limits are retried.
 
+### Both call forms
+
+Every client method is available two ways. `await client.get_issue.aio(...)` is the
+async form — use it in `async def` tasks and anywhere on an app's event loop.
+`client.get_issue(...)` is the blocking form, for plain `def` tasks and scripts:
+
+```python
+@env.task
+def summarize(...) -> str:
+    with JiraClient() as client:          # note: `with`, not `async with`
+        issue = client.get_issue(issue_key)
+    ...
+```
+
+The blocking form parks the calling thread until the call returns, so never
+reach for it inside an `async def` task or a webhook handler — it would stall
+the event loop and everything else waiting on it.
+
 ## React to Jira events
 
 `JiraAppEnvironment` serves a **setup dashboard** (`/`) and a **webhook

plugins/jira/examples/manage_ticket.py

@@ -36,24 +36,24 @@
 async def open_ticket(project_key: str, summary: str, description: str) -> str:
     """Create a ticket and return its URL."""
     async with JiraClient() as client:
-        issue = await client.create_issue(project_key, summary, description=description)
+        issue = await client.create_issue.aio(project_key, summary, description=description)
     return issue["url"]
 
 
 @env.task
 async def start_work(issue_key: str) -> str:
     """Transition a ticket to In Progress and comment on it."""
     async with JiraClient() as client:
-        await client.transition_issue(issue_key, "In Progress")
-        await client.add_comment(issue_key, "Flyte picked this ticket up.")
+        await client.transition_issue.aio(issue_key, "In Progress")
+        await client.add_comment.aio(issue_key, "Flyte picked this ticket up.")
     return issue_key
 
 
 @env.task
 async def summarize_open_bugs(project_key: str) -> str:
     """Search open bugs in a project and summarize them."""
     async with JiraClient() as client:
-        issues = await client.search_issues(
+        issues = await client.search_issues.aio(
             f"project = {project_key} AND issuetype = Bug AND statusCategory != Done ORDER BY priority DESC"
         )
     if not issues:

plugins/jira/examples/react_to_jira_events.py

@@ -68,7 +68,7 @@ async def note_done_transitions(event):
     if event.status != "Done":
         return None
     async with JiraClient() as client:
-        await client.add_comment(event.issue_key, "Flyte noticed this issue is now Done.")
+        await client.add_comment.aio(event.issue_key, "Flyte noticed this issue is now Done.")
     return {"noted": event.issue_key}
 
 

plugins/jira/src/flyteplugins/jira/__init__.py

@@ -36,10 +36,15 @@
 @env.task
 async def open_ticket(project_key: str, summary: str, description: str) -> str:
     async with JiraClient() as client:
-        issue = await client.create_issue(project_key, summary, description=description)
+        issue = await client.create_issue.aio(project_key, summary, description=description)
     return issue["url"]
 ```
 
+Every client method has two call forms: `await client.get_issue.aio(...)` for
+async tasks and app handlers, and `client.get_issue(...)` (under a plain `with`)
+for sync tasks and scripts. The blocking form stalls the calling thread, so never
+use it on an event loop.
+
 ## React to Jira events
 
 ```python

plugins/jira/src/flyteplugins/jira/_client.py

@@ -14,6 +14,7 @@
 from typing import Any
 
 import httpx
+from flyte.syncify import syncify
 
 from ._config import Config, default_config
 from ._errors import JiraAPIError, MissingCredentialsError
@@ -162,6 +163,27 @@ async def __aexit__(self, *exc_info: object) -> None:
             await self._client.aclose()
             self._client = None
 
+    def __enter__(self) -> JiraClient:
+        """Enter synchronously, for use with the blocking call form.
+
+        `__aenter__` runs on syncify's background loop — the same loop the
+        syncified methods run on — so the underlying `httpx.AsyncClient` is
+        created and used on a single loop.
+        """
+        return self._enter_sync()
+
+    def __exit__(self, *exc_info: object) -> None:
+        self._exit_sync()
+
+    @syncify
+    async def _enter_sync(self) -> JiraClient:
+        return await self.__aenter__()
+
+    @syncify
+    async def _exit_sync(self) -> None:
+        await self.__aexit__()
+
+    @syncify
     async def request(
         self,
         method: str,
@@ -215,33 +237,38 @@ async def request(
     # reads
     # ------------------------------------------------------------------
 
+    @syncify
     async def get_myself(self) -> dict[str, Any]:
         """Return the authenticated user (`GET /myself`)."""
-        data = await self.request("GET", "/myself")
+        data = await self.request.aio("GET", "/myself")
         return {
             "account_id": data.get("accountId"),
             "display_name": data.get("displayName"),
             "email": data.get("emailAddress"),
         }
 
+    @syncify
     async def list_projects(self) -> list[dict[str, Any]]:
         """List projects visible to the authenticated user."""
-        data = await self.request("GET", "/project/search", params={"maxResults": 50})
+        data = await self.request.aio("GET", "/project/search", params={"maxResults": 50})
         return [{"key": p.get("key"), "name": p.get("name"), "id": p.get("id")} for p in data.get("values", [])]
 
+    @syncify
     async def get_issue(self, issue_key: str) -> dict[str, Any]:
         """Return a single issue by key (e.g. `PROJ-123`)."""
-        data = await self.request("GET", f"/issue/{issue_key}")
+        data = await self.request.aio("GET", f"/issue/{issue_key}")
         return _simplify_issue(data, self.base_url)
 
+    @syncify
     async def search_issues(self, jql: str, max_results: int = 50) -> list[dict[str, Any]]:
         """Search issues with JQL."""
-        data = await self.request("GET", "/search", params={"jql": jql, "maxResults": max_results})
+        data = await self.request.aio("GET", "/search", params={"jql": jql, "maxResults": max_results})
         return [_simplify_issue(issue, self.base_url) for issue in data.get("issues", [])]
 
+    @syncify
     async def list_comments(self, issue_key: str) -> list[dict[str, Any]]:
         """List comments on an issue."""
-        data = await self.request("GET", f"/issue/{issue_key}/comment")
+        data = await self.request.aio("GET", f"/issue/{issue_key}/comment")
         return [
             {
                 "id": c.get("id"),
@@ -252,9 +279,10 @@ async def list_comments(self, issue_key: str) -> list[dict[str, Any]]:
             for c in data.get("comments", [])
         ]
 
+    @syncify
     async def list_transitions(self, issue_key: str) -> list[dict[str, Any]]:
         """List the transitions available for an issue."""
-        data = await self.request("GET", f"/issue/{issue_key}/transitions")
+        data = await self.request.aio("GET", f"/issue/{issue_key}/transitions")
         return [
             {"id": t.get("id"), "name": t.get("name"), "to_status": (t.get("to") or {}).get("name")}
             for t in data.get("transitions", [])
@@ -264,6 +292,7 @@ async def list_transitions(self, issue_key: str) -> list[dict[str, Any]]:
     # writes
     # ------------------------------------------------------------------
 
+    @syncify
     async def create_issue(
         self,
         project_key: str,
@@ -299,9 +328,10 @@ async def create_issue(
             fields["labels"] = labels
         if extra_fields:
             fields.update(extra_fields)
-        data = await self.request("POST", "/issue", json={"fields": fields})
+        data = await self.request.aio("POST", "/issue", json={"fields": fields})
         return {"key": data.get("key"), "id": data.get("id"), "url": f"{self.base_url}/browse/{data.get('key')}"}
 
+    @syncify
     async def update_issue(
         self,
         issue_key: str,
@@ -320,22 +350,24 @@ async def update_issue(
             fields["labels"] = labels
         if extra_fields:
             fields.update(extra_fields)
-        await self.request("PUT", f"/issue/{issue_key}", json={"fields": fields})
+        await self.request.aio("PUT", f"/issue/{issue_key}", json={"fields": fields})
         return {"key": issue_key}
 
+    @syncify
     async def add_comment(self, issue_key: str, body: str) -> dict[str, Any]:
         """Add a comment to an issue."""
-        data = await self.request("POST", f"/issue/{issue_key}/comment", json={"body": _text_to_adf(body)})
+        data = await self.request.aio("POST", f"/issue/{issue_key}/comment", json={"body": _text_to_adf(body)})
         return {"id": data.get("id"), "created": data.get("created")}
 
+    @syncify
     async def transition_issue(self, issue_key: str, transition: str) -> dict[str, Any]:
         """Transition an issue by transition name or id.
 
         Looks up available transitions when a name is given; raises
         `JiraAPIError` when the name does not match.
         """
         if not transition.isdigit():
-            transitions = await self.list_transitions(issue_key)
+            transitions = await self.list_transitions.aio(issue_key)
             match = next((t for t in transitions if t["name"].lower() == transition.lower()), None)
             if match is None:
                 available = ", ".join(t["name"] for t in transitions) or "<none>"
@@ -345,12 +377,13 @@ async def transition_issue(self, issue_key: str, transition: str) -> dict[str, A
             transition_id = match["id"]
         else:
             transition_id = transition
-        await self.request("POST", f"/issue/{issue_key}/transitions", json={"transition": {"id": transition_id}})
+        await self.request.aio("POST", f"/issue/{issue_key}/transitions", json={"transition": {"id": transition_id}})
         return {"key": issue_key, "transition": transition_id}
 
+    @syncify
     async def delete_issue(self, issue_key: str) -> None:
         """Delete an issue permanently. Destructive and irreversible."""
-        await self.request("DELETE", f"/issue/{issue_key}")
+        await self.request.aio("DELETE", f"/issue/{issue_key}")
 
 
 def _safe_json(response: httpx.Response) -> dict[str, Any] | None:

plugins/jira/src/flyteplugins/jira/_tools.py

@@ -103,7 +103,7 @@ def _make_tool(name: str, config: Config, base_url: str | None, email: str | Non
 
     async def tool(*args: Any, **kwargs: Any) -> Any:
         async with JiraClient(config, base_url=base_url, email=email, api_token=api_token) as client:
-            return await getattr(client, name)(*args, **kwargs)
+            return await getattr(client, name).aio(*args, **kwargs)
 
     tool.__signature__ = sig.replace(parameters=params)  # type: ignore[attr-defined]
     tool.__name__ = name

plugins/jira/tests/test_client.py

@@ -14,7 +14,7 @@
 async def test_basic_auth_header(jira_api, creds):
     route = jira_api.get("/myself").respond(json={"accountId": "a", "displayName": "Bot"})
     async with JiraClient() as client:
-        await client.get_myself()
+        await client.get_myself.aio()
     header = route.calls[0].request.headers["Authorization"]
     assert header == "Basic " + base64.b64encode(b"bot@acme.com:jira-token").decode()
 
@@ -30,7 +30,7 @@ async def test_missing_credentials(monkeypatch):
 async def test_get_issue_simplifies_and_extracts_description(jira_api, creds):
     jira_api.get("/issue/PROJ-1").respond(json=issue_json())
     async with JiraClient() as client:
-        issue = await client.get_issue("PROJ-1")
+        issue = await client.get_issue.aio("PROJ-1")
     assert issue["key"] == "PROJ-1"
     assert issue["status"] == "To Do"
     assert issue["description"] == "It broke."
@@ -41,7 +41,7 @@ async def test_get_issue_simplifies_and_extracts_description(jira_api, creds):
 async def test_search_issues(jira_api, creds):
     jira_api.get("/search").respond(json={"issues": [issue_json(), issue_json(key="PROJ-2")]})
     async with JiraClient() as client:
-        issues = await client.search_issues("project = PROJ")
+        issues = await client.search_issues.aio("project = PROJ")
     assert [i["key"] for i in issues] == ["PROJ-1", "PROJ-2"]
 
 
@@ -56,7 +56,7 @@ def capture(request: httpx.Request) -> httpx.Response:
 
     jira_api.post("/issue").mock(side_effect=capture)
     async with JiraClient() as client:
-        issue = await client.create_issue("PROJ", "New thing", description="details", priority="High")
+        issue = await client.create_issue.aio("PROJ", "New thing", description="details", priority="High")
     assert issue["key"] == "PROJ-3"
     fields = captured["body"]["fields"]
     assert fields["project"] == {"key": "PROJ"}
@@ -79,7 +79,7 @@ def capture(request: httpx.Request) -> httpx.Response:
 
     jira_api.post("/issue/PROJ-1/transitions").mock(side_effect=capture)
     async with JiraClient() as client:
-        result = await client.transition_issue("PROJ-1", "in progress")
+        result = await client.transition_issue.aio("PROJ-1", "in progress")
     assert result["transition"] == "21"
     assert captured["body"] == {"transition": {"id": "21"}}
 
@@ -88,21 +88,21 @@ async def test_transition_unknown_name_raises(jira_api, creds):
     jira_api.get("/issue/PROJ-1/transitions").respond(json={"transitions": [{"id": "21", "name": "In Progress"}]})
     async with JiraClient() as client:
         with pytest.raises(JiraAPIError) as excinfo:
-            await client.transition_issue("PROJ-1", "Done")
+            await client.transition_issue.aio("PROJ-1", "Done")
     assert "In Progress" in str(excinfo.value)
 
 
 async def test_add_comment(jira_api, creds):
     jira_api.post("/issue/PROJ-1/comment").respond(json={"id": "c1", "created": "t"})
     async with JiraClient() as client:
-        comment = await client.add_comment("PROJ-1", "on it")
+        comment = await client.add_comment.aio("PROJ-1", "on it")
     assert comment == {"id": "c1", "created": "t"}
 
 
 async def test_delete_issue(jira_api, creds):
     route = jira_api.delete("/issue/PROJ-1").respond(status_code=204, content=b"")
     async with JiraClient() as client:
-        assert await client.delete_issue("PROJ-1") is None
+        assert await client.delete_issue.aio("PROJ-1") is None
     assert route.called
 
 
@@ -112,7 +112,7 @@ async def test_api_error_messages(jira_api, creds):
     )
     async with JiraClient() as client:
         with pytest.raises(JiraAPIError) as excinfo:
-            await client.get_issue("NOPE-1")
+            await client.get_issue.aio("NOPE-1")
     assert excinfo.value.status_code == 404
     assert "does not exist" in str(excinfo.value)
 
@@ -126,5 +126,32 @@ async def test_retries_on_429(jira_api, creds):
     from flyteplugins.jira import Config
 
     async with JiraClient(Config(retry_backoff=0.0)) as client:
-        await client.get_myself()
+        await client.get_myself.aio()
     assert route.call_count == 2
+
+
+def test_the_blocking_call_form_works_outside_an_event_loop(jira_api):
+    """`with Client() as c: c.method(...)` -- the point of syncifying the client.
+
+    `__enter__` runs `__aenter__` on syncify's background loop, the same loop the
+    syncified methods run on, so the httpx client is created and used on one loop.
+    """
+    jira_api.get("/issue/PROJ-1").respond(json=issue_json())
+    with JiraClient(base_url="https://acme.atlassian.net", email="a@b.c", api_token="t") as client:
+        issue = client.get_issue("PROJ-1")
+    assert issue["key"] == "PROJ-1"
+
+
+async def test_the_async_form_is_the_same_method_via_aio(jira_api):
+    """Both call forms are the same method: `m(...)` blocks, `await m.aio(...)` does not."""
+    jira_api.get("/issue/PROJ-1").respond(json=issue_json())
+    async with JiraClient(base_url="https://acme.atlassian.net", email="a@b.c", api_token="t") as client:
+        issue = await client.get_issue.aio("PROJ-1")
+    assert issue["key"] == "PROJ-1"
+
+
+def test_methods_expose_both_call_forms():
+    from flyte.syncify import syncify  # noqa: F401
+
+    method = JiraClient.get_issue
+    assert hasattr(method, "aio"), "syncified methods must offer an async form"