style: apply ruff format

Author: LioriE

big-plan.md

@@ -0,0 +1,86 @@
+# Async Rollout Plan — python-sdk
+
+## Current state
+- `future_utils.py` exists with `then`, `wrap`, `resolve` helpers
+- `HTTPClient` stores `async_mode_experimental` but doesn't act on it yet
+- `DescopeClient.__init__` accepts and forwards the flag
+
+---
+
+## Stage 0 — Foundation: async HTTP transport (1 PR + 1 test PR)
+
+**PR 0a — Implementation:**
+- Add `httpx.AsyncClient` (persistent, per-instance) alongside the existing synchronous path
+- Add `async def _async_execute_with_retry(request_fn)` mirroring the sync retry loop
+- Each public method accepts an explicit `async_mode: bool = False` parameter; passing `True` delegates to the async path and returns a coroutine; the class-level `async_mode_experimental` flag is stored but inert until the final global-rollout stage
+- No callers change yet — this PR is purely internal to `HTTPClient`
+
+**PR 0b — Tests:**
+- Unit tests asserting async mode methods return coroutines (`asyncio.iscoroutine`)
+- Verify sync mode is completely unaffected (all existing tests continue to pass unchanged)
+- Test async retry logic (mock 503s, assert delays and retry count)
+
+---
+
+## Stage 1–9 — Auth methods (one file per PR pair)
+
+**Pattern for every auth method file:**
+
+```python
+# Before
+response = self._http.post(uri, body=body)
+return Auth.extract_masked_address(response.json(), method)
+
+# After (using then from future_utils)
+from descope.future_utils import then
+response = self._http.post(uri, body=body)
+return then(response, lambda r: Auth.extract_masked_address(r.json(), method))
+```
+
+When the HTTP client returns a plain `httpx.Response` (sync mode), `then` applies the lambda immediately and returns the final value — zero behaviour change. When it returns a coroutine (async mode), `then` returns a new coroutine that awaits it and applies the lambda.
+
+Rollout order (each is one implementation PR + one test PR):
+
+| Stage | File | Methods |
+|-------|------|---------|
+| 1 | `authmethod/otp.py` | sign\_in, sign\_up, sign\_up\_or\_in, verify\_code, update\_user\_email, update\_user\_phone |
+| 2 | `authmethod/magiclink.py` | sign\_in, sign\_up, sign\_up\_or\_in, verify, update\_user\_email, update\_user\_phone |
+| 3 | `authmethod/enchantedlink.py` | sign\_in, sign\_up, sign\_up\_or\_in, verify, get\_session, update\_user\_email, update\_user\_phone |
+| 4 | `authmethod/oauth.py` | start, exchange\_token, update\_user |
+| 5 | `authmethod/password.py` | sign\_in, sign\_up, send\_reset, update, replace, get\_policy |
+| 6 | `authmethod/totp.py` | sign\_in, sign\_up, sign\_up\_or\_in, update\_user, verify |
+| 7 | `authmethod/webauthn.py` | sign\_in\_start/finish, sign\_up\_start/finish, update\_user\_start/finish |
+| 8 | `authmethod/saml.py` + `sso.py` | start methods |
+| 9 | `auth.py` | validate\_session, refresh\_session, exchange\_access\_key (I/O-bound JWKS fetch) |
+
+---
+
+## Stage 10–N — Management files (one file per PR pair)
+
+Same `then()` wrapping pattern. Suggested order by impact:
+
+| Stage | File |
+|-------|------|
+| 10 | `management/user.py` |
+| 11 | `management/access_key.py` |
+| 12 | `management/tenant.py` |
+| 13 | `management/role.py` + `permission.py` |
+| 14 | `management/audit.py` |
+| 15 | `management/authz.py` + `management/fga.py` |
+| 16 | `management/sso_settings.py` + `management/sso_application.py` |
+| 17 | `management/flow.py` + `management/jwt.py` |
+| 18 | `management/group.py` + `management/project.py` + remaining files |
+
+---
+
+## Final stage — Global setting (future, after all stages done)
+
+Once every file is converted, add a class-level `async_mode` property to `DescopeClient` that applies to all methods at once, and graduate the feature out of experimental. The per-file opt-in PRs make this final step trivial since all callers already use `then()`.
+
+---
+
+## Invariants throughout
+- Sync callers are **never broken** at any stage — `then(sync_result, fn)` is identical to `fn(sync_result)`
+- No new public API surface until the global-setting stage
+- Each implementation PR is independently reviewable and rollback-safe
+- Test PRs always cover both sync (regression) and async (new) paths for the converted file

descope/descope_client.py

@@ -54,9 +54,7 @@ def __init__(
 
         async_mode_experimental = bool(kwargs.pop("async_mode_experimental", False))
         if kwargs:
-            raise TypeError(
-                f"DescopeClient.__init__() got unexpected keyword arguments: {list(kwargs)}"
-            )
+            raise TypeError(f"DescopeClient.__init__() got unexpected keyword arguments: {list(kwargs)}")
 
         # Warn about TLS verification bypass
         if skip_verify:

descope/future_utils.py

@@ -6,9 +6,7 @@
 T = TypeVar("T")
 
 
-def then(
-    result_or_coro: Union[T, Awaitable[T]], modifier: Callable[[T], Any]
-) -> Union[Any, Awaitable[Any]]:
+def then(result_or_coro: Union[T, Awaitable[T]], modifier: Callable[[T], Any]) -> Union[Any, Awaitable[Any]]:
     if inspect.isawaitable(result_or_coro):
 
         async def process_async():

descope/http_client.py

@@ -213,7 +213,11 @@ def get(
     ) -> httpx.Response | Awaitable[httpx.Response]:
         if async_mode:
             if self._async_client is None:
-                raise AuthException(400, ERROR_TYPE_INVALID_ARGUMENT, "async_mode requires async_mode_experimental=True at client construction")
+                raise AuthException(
+                    400,
+                    ERROR_TYPE_INVALID_ARGUMENT,
+                    "async_mode requires async_mode_experimental=True at client construction",
+                )
             return self._async_get(uri, params=params, allow_redirects=allow_redirects, pswd=pswd)
         response = self._execute_with_retry(
             lambda: httpx.get(
@@ -242,7 +246,11 @@ def post(
     ) -> httpx.Response | Awaitable[httpx.Response]:
         if async_mode:
             if self._async_client is None:
-                raise AuthException(400, ERROR_TYPE_INVALID_ARGUMENT, "async_mode requires async_mode_experimental=True at client construction")
+                raise AuthException(
+                    400,
+                    ERROR_TYPE_INVALID_ARGUMENT,
+                    "async_mode requires async_mode_experimental=True at client construction",
+                )
             return self._async_post(uri, body=body, params=params, pswd=pswd, base_url=base_url)
         response = self._execute_with_retry(
             lambda: httpx.post(
@@ -271,7 +279,11 @@ def put(
     ) -> httpx.Response | Awaitable[httpx.Response]:
         if async_mode:
             if self._async_client is None:
-                raise AuthException(400, ERROR_TYPE_INVALID_ARGUMENT, "async_mode requires async_mode_experimental=True at client construction")
+                raise AuthException(
+                    400,
+                    ERROR_TYPE_INVALID_ARGUMENT,
+                    "async_mode requires async_mode_experimental=True at client construction",
+                )
             return self._async_put(uri, body=body, params=params, pswd=pswd)
         response = self._execute_with_retry(
             lambda: httpx.put(
@@ -298,7 +310,11 @@ def patch(
     ) -> httpx.Response | Awaitable[httpx.Response]:
         if async_mode:
             if self._async_client is None:
-                raise AuthException(400, ERROR_TYPE_INVALID_ARGUMENT, "async_mode requires async_mode_experimental=True at client construction")
+                raise AuthException(
+                    400,
+                    ERROR_TYPE_INVALID_ARGUMENT,
+                    "async_mode requires async_mode_experimental=True at client construction",
+                )
             return self._async_patch(uri, body=body, params=params, pswd=pswd)
         response = self._execute_with_retry(
             lambda: httpx.patch(
@@ -326,7 +342,11 @@ def delete(
     ) -> httpx.Response | Awaitable[httpx.Response]:
         if async_mode:
             if self._async_client is None:
-                raise AuthException(400, ERROR_TYPE_INVALID_ARGUMENT, "async_mode requires async_mode_experimental=True at client construction")
+                raise AuthException(
+                    400,
+                    ERROR_TYPE_INVALID_ARGUMENT,
+                    "async_mode requires async_mode_experimental=True at client construction",
+                )
             return self._async_delete(uri, params=params, pswd=pswd)
         response = self._execute_with_retry(
             lambda: httpx.delete(

tests/management/test_descoper.py

@@ -532,8 +532,6 @@ def test_sync_behavior_with_async_mode_experimental(self, _mock_async):
                 '{"descopers": [{"id": "U2111111111111111111111111", "status": "invited"}], "total": 1}'
             )
             mock_put.return_value = network_resp
-            result = client.mgmt.descoper.create(
-                descopers=[DescoperCreate(login_id="user1@example.com")]
-            )
+            result = client.mgmt.descoper.create(descopers=[DescoperCreate(login_id="user1@example.com")])
             self.assertFalse(asyncio.iscoroutine(result))
             self.assertEqual(result["total"], 1)

tests/test_descope_client.py

@@ -1062,9 +1062,7 @@ def test_unknown_kwargs_raise_type_error(self):
 
     @patch("httpx.AsyncClient")
     @patch("httpx.post")
-    def test_async_mode_experimental_flag_does_not_return_coroutine(
-        self, mock_post, mock_async_client
-    ):
+    def test_async_mode_experimental_flag_does_not_return_coroutine(self, mock_post, mock_async_client):
         """DescopeClient with async_mode_experimental=True still returns sync results from auth methods."""
         import asyncio