anaplan-sdk 0.4.0a3__tar.gz → 0.4.2__tar.gz

{anaplan_sdk-0.4.0a3 → anaplan_sdk-0.4.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.0a3
-Summary: Provides pythonic access to the Anaplan API
+Version: 0.4.2
+Summary: Streamlined Python Interface for Anaplan
 Project-URL: Homepage, https://vinzenzklass.github.io/anaplan-sdk/
 Project-URL: Repository, https://github.com/VinzenzKlass/anaplan-sdk
 Project-URL: Documentation, https://vinzenzklass.github.io/anaplan-sdk/
@@ -13,7 +13,7 @@ Requires-Python: >=3.10.4
 Requires-Dist: httpx<1.0.0,>=0.27.0
 Requires-Dist: pydantic<3.0.0,>=2.7.2
 Provides-Extra: cert
-Requires-Dist: cryptography<45.0.0,>=42.0.7; extra == 'cert'
+Requires-Dist: cryptography<46.0.0,>=42.0.7; extra == 'cert'
 Provides-Extra: oauth
 Requires-Dist: oauthlib<4.0.0,>=3.0.0; extra == 'oauth'
 Description-Content-Type: text/markdown

{anaplan_sdk-0.4.0a3 → anaplan_sdk-0.4.2}/anaplan_sdk/_async_clients/_bulk.py

@@ -1,12 +1,12 @@
 import logging
 from asyncio import gather, sleep
 from copy import copy
-from typing import AsyncIterator, Callable, Iterator
+from typing import AsyncIterator, Iterator
 
 import httpx
 from typing_extensions import Self
 
-from anaplan_sdk._auth import create_auth
+from anaplan_sdk._auth import AuthCodeCallback, AuthTokenRefreshCallback, create_auth
 from anaplan_sdk._base import _AsyncBaseClient, action_url
 from anaplan_sdk.exceptions import AnaplanActionError, InvalidIdentifierException
 from anaplan_sdk.models import (
@@ -56,7 +56,8 @@ class AsyncClient(_AsyncBaseClient):
         redirect_uri: str | None = None,
         refresh_token: str | None = None,
         oauth2_scope: str = "openid profile email offline_access",
-        on_token_refresh: Callable[[dict[str, str]], None] | None = None,
+        on_auth_code: AuthCodeCallback = None,
+        on_token_refresh: AuthTokenRefreshCallback = None,
         timeout: float | httpx.Timeout = 30,
         retry_count: int = 2,
         status_poll_delay: int = 1,
@@ -91,11 +92,27 @@ class AsyncClient(_AsyncBaseClient):
         :param refresh_token: If you have a valid refresh token, you can pass it to skip the
                               interactive authentication code step.
         :param oauth2_scope: The scope of the Oauth2 token, if you want to narrow it.
+        :param on_auth_code: A callback that takes the redirect URI as a single argument and must
+                             return the entire response URI. This will substitute the interactive
+                             authentication code step in the terminal. The callback can be either
+                             a synchronous function or an async coroutine function - both will be
+                             handled appropriately regardless of the execution context (in a thread,
+                             with or without an event loop, etc.).
+                             **Note**: When using asynchronous callbacks in complex applications
+                             with multiple event loops, be aware that callbacks may execute in a
+                             separate event loop context from where they were defined, which can
+                             make debugging challenging.
         :param on_token_refresh: A callback function that is called whenever the token is refreshed.
+                                 This includes the initial token retrieval and any subsequent calls.
                                  With this you can for example securely store the token in your
                                  application or on your server for later reuse. The function
                                  must accept a single argument, which is the token dictionary
                                  returned by the Oauth2 token endpoint and does not return anything.
+                                 This can be either a synchronous function or an async coroutine
+                                 function. **Note**: When using asynchronous callbacks in complex
+                                 applications with multiple event loops, be aware that callbacks
+                                 may execute in a separate event loop context from where they were
+                                 defined, which can make debugging challenging.
         :param timeout: The timeout in seconds for the HTTP requests. Alternatively, you can pass
                         an instance of `httpx.Timeout` to set the timeout for the HTTP requests.
         :param retry_count: The number of times to retry an HTTP request if it fails. Set this to 0
@@ -124,6 +141,7 @@ class AsyncClient(_AsyncBaseClient):
                     redirect_uri=redirect_uri,
                     refresh_token=refresh_token,
                     oauth2_scope=oauth2_scope,
+                    on_auth_code=on_auth_code,
                     on_token_refresh=on_token_refresh,
                 )
             ),

{anaplan_sdk-0.4.0a3 → anaplan_sdk-0.4.2}/anaplan_sdk/_auth.py

@@ -1,7 +1,11 @@
+import asyncio
+import inspect
 import logging
 import os
+import threading
 from base64 import b64encode
-from typing import Callable
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Awaitable, Callable, Coroutine
 
 import httpx
 
@@ -9,6 +13,11 @@ from .exceptions import AnaplanException, InvalidCredentialsException, InvalidPr
 
 logger = logging.getLogger("anaplan_sdk")
 
+AuthCodeCallback = (Callable[[str], str] | Callable[[str], Awaitable[str]]) | None
+AuthTokenRefreshCallback = (
+    Callable[[dict[str, str]], None] | Callable[[dict[str, str]], Awaitable[None]]
+) | None
+
 
 class _AnaplanAuth(httpx.Auth):
     requires_response_body = True
@@ -144,7 +153,8 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
         redirect_uri: str,
         refresh_token: str | None = None,
         scope: str = "openid profile email offline_access",
-        on_token_refresh: Callable[[dict[str, str]], None] | None = None,
+        on_auth_code: AuthCodeCallback = None,
+        on_token_refresh: AuthTokenRefreshCallback = None,
     ):
         try:
             from oauthlib.oauth2 import WebApplicationClient
@@ -163,6 +173,7 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
         self._refresh_token = refresh_token
         self._scope = scope
         self._id_token = None
+        self._on_auth_code = on_auth_code
         self._on_token_refresh = on_token_refresh
         if not refresh_token:
             self.__auth_code_flow()
@@ -186,7 +197,7 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
         self._token = token["access_token"]
         self._refresh_token = token["refresh_token"]
         if self._on_token_refresh:
-            self._on_token_refresh(token)
+            _run_callback(self._on_token_refresh, token)
         self._id_token = token.get("id_token")
 
     def __auth_code_flow(self):
@@ -195,13 +206,17 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
         try:
             logger.info("Creating Authentication Token with OAuth2 Authorization Code Flow.")
             url, _, _ = self._oauth.prepare_authorization_request(
-                "https://us1a.app.anaplan.com/auth/authorize",
+                "https://us1a.app.anaplan.com/auth/prelogin",
                 redirect_url=self._redirect_uri,
                 scope=self._scope,
             )
-            authorization_response = input(
-                f"Please go to {url} and authorize the app.\n"
-                "Then paste the entire redirect URL here: "
+            authorization_response = (
+                _run_callback(self._on_auth_code, url)
+                if self._on_auth_code
+                else input(
+                    f"Please go to {url} and authorize the app.\n"
+                    "Then paste the entire redirect URL here: "
+                )
             )
             url, headers, body = self._oauth.prepare_token_request(
                 token_url=self._token_url,
@@ -211,7 +226,7 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
             )
             self._parse_auth_response(httpx.post(url=url, headers=headers, content=body))
         except (httpx.HTTPError, ValueError, TypeError, OAuth2Error) as error:
-            raise AnaplanException("Error during OAuth2 authorization flow.") from error
+            raise InvalidCredentialsException("Error during OAuth2 authorization flow.") from error
 
 
 def create_auth(
@@ -225,7 +240,8 @@ def create_auth(
     redirect_uri: str | None = None,
     refresh_token: str | None = None,
     oauth2_scope: str = "openid profile email offline_access",
-    on_token_refresh: Callable[[dict[str, str]], None] | None = None,
+    on_auth_code: AuthCodeCallback = None,
+    on_token_refresh: AuthTokenRefreshCallback = None,
 ) -> _AnaplanAuth:
     if certificate and private_key:
         return AnaplanCertAuth(certificate, private_key, private_key_password)
@@ -238,6 +254,7 @@ def create_auth(
             redirect_uri=redirect_uri,
             refresh_token=refresh_token,
             scope=oauth2_scope,
+            on_auth_code=on_auth_code,
             on_token_refresh=on_token_refresh,
         )
     raise ValueError(
@@ -246,3 +263,32 @@ def create_auth(
         "- certificate and private_key, or\n"
         "- client_id, client_secret, and redirect_uri"
     )
+
+
+def _run_callback(func, *arg, **kwargs):
+    if not inspect.iscoroutinefunction(func):
+        return func(*arg, **kwargs)
+    coro = func(*arg, **kwargs)
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+    if threading.current_thread() is threading.main_thread():
+        if not loop.is_running():
+            return loop.run_until_complete(coro)
+        else:
+            with ThreadPoolExecutor() as pool:
+                future = pool.submit(__run_in_new_loop, coro)
+                return future.result(timeout=30)
+    else:
+        return asyncio.run_coroutine_threadsafe(coro, loop).result()
+
+
+def __run_in_new_loop(coroutine: Coroutine[Any, Any, Any]):
+    new_loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(new_loop)
+    try:
+        return new_loop.run_until_complete(coroutine)
+    finally:
+        new_loop.close()

{anaplan_sdk-0.4.0a3 → anaplan_sdk-0.4.2}/anaplan_sdk/_clients/_bulk.py

@@ -58,6 +58,7 @@ class Client(_BaseClient):
         redirect_uri: str | None = None,
         refresh_token: str | None = None,
         oauth2_scope: str = "openid profile email offline_access",
+        on_auth_code: Callable[[str], str] | None = None,
         on_token_refresh: Callable[[dict[str, str]], None] | None = None,
         timeout: float | httpx.Timeout = 30,
         retry_count: int = 2,
@@ -94,7 +95,11 @@ class Client(_BaseClient):
         :param refresh_token: If you have a valid refresh token, you can pass it to skip the
                               interactive authentication code step.
         :param oauth2_scope: The scope of the Oauth2 token, if you want to narrow it.
+        :param on_auth_code: A callback that takes the redirect URI as a single argument and must
+                     return the entire response URI. This will substitute the interactive
+                     authentication code step in the terminal.
         :param on_token_refresh: A callback function that is called whenever the token is refreshed.
+                                 This includes the initial token retrieval and any subsequent calls.
                                  With this you can for example securely store the token in your
                                  application or on your server for later reuse. The function
                                  must accept a single argument, which is the token dictionary
@@ -130,6 +135,7 @@ class Client(_BaseClient):
                     redirect_uri=redirect_uri,
                     refresh_token=refresh_token,
                     oauth2_scope=oauth2_scope,
+                    on_auth_code=on_auth_code,
                     on_token_refresh=on_token_refresh,
                 )
             ),

{anaplan_sdk-0.4.0a3 → anaplan_sdk-0.4.2}/docs/guides/authentication.md

@@ -142,6 +142,47 @@ will need to copy the entire redirect URI from your browser and paste it into th
     Unfortunately, registering localhost redirect URIs is not supported by Anaplan. This means we cannot intercept the
     redirect URI and extract the `authorization_code` automatically. This is a limitation of Anaplan's OAuth2 implementation. See [this Community Note](https://community.anaplan.com/discussion/156599/oauth-rediredt-url-port-for-desktop-apps).
 
+### Authorization Code
+
+When using OAuth authentication, the default behavior prompts you to manually open a URL, authorize the application, and paste the redirect URL back into your terminal. However, you can customize this flow by providing the `on_auth_code` callback.
+
+The `on_auth_code` callback lets you hook into the Auth Flow to handle the authorization URL programmatically and return the authorization response. `on_auth_code` must be a callable that takes the authorization URL as a single argument of type `str` and returns the redirect URL as a `str`.
+
+
+???+ warning "Asynchronous Callbacks"
+    Both `on_auth_code` and `on_token_refresh` can be either synchronous or asynchronous. When using asynchronous 
+    callbacks in complex applications with multiple event loops, be aware that callbacks may execute in a separate 
+    event loop context from where they were defined, which can make debugging challenging.
+
+=== "Synchronous"
+    ```python
+    def on_auth_code(redirect_uri: str) -> str:
+        return input(f"Go fetch! {redirect_uri}\nPaste here: ")
+
+    anaplan = anaplan_sdk.Client(
+        workspace_id="AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        model_id="11111111111111111111111111111111",
+        redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
+        client_id="my_anaplan_oauth_client_id",
+        client_secret="my_anaplan_oauth_client_secret",
+        on_auth_code=on_auth_code,
+    )
+    ```
+=== "Asynchronous"
+    ```python
+    async def on_auth_code(redirect_uri: str) -> str: # Can be sync or async
+        return input(f"Go fetch! {redirect_uri}\nPaste here: ")
+
+    anaplan = anaplan_sdk.AsyncClient(
+        workspace_id="AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        model_id="11111111111111111111111111111111",
+        redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
+        client_id="my_anaplan_oauth_client_id",
+        client_secret="my_anaplan_oauth_client_secret",
+        on_auth_code=on_auth_code,
+    )
+    ```
+
 ### Refresh Tokens
 
 You can extend the above example to also pass a `refresh_token` to authenticate without any user interaction, and 
@@ -186,7 +227,7 @@ a single argument of type `dict[str, str]` and returns `None`.
     kp = PyKeePass("db.kdbx", password="keepass")
     group = kp.add_group(kp.root_group, "Anaplan")
     
-    def on_token_refresh(token: dict[str, str]) -> None:
+    def on_token_refresh(token: dict[str, str]) -> None: # Can also be async
         kp.add_entry(
             group, title="Anaplan Token", username=None, password=json.dumps(token)
         )

{anaplan_sdk-0.4.0a3 → anaplan_sdk-0.4.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "anaplan-sdk"
-version = "0.4.0a3"
-description = "Provides pythonic access to the Anaplan API"
+version = "0.4.2"
+description = "Streamlined Python Interface for Anaplan"
 license = "Apache-2.0"
 authors = [{ name = "Vinzenz Klass", email = "vinzenz.klass@valantic.com" }]
 readme = "README.md"
@@ -24,7 +24,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-cert = ["cryptography>=42.0.7,<45.0.0"]
+cert = ["cryptography>=42.0.7,<46.0.0"]
 oauth = ["oauthlib>=3.0.0,<4.0.0"]
 
 [dependency-groups]
@@ -40,7 +40,7 @@ dev = [
     "polars>=1.29.0",
     "griffe-fieldz>=0.2.1",
     "oauthlib>=3.2.2",
-    "cryptography>=42.0.7",
+    "cryptography>=45.0.0",
 ]
 
 [project.urls]
@@ -84,7 +84,7 @@ exclude = [
 
 line-length = 100
 fix = true
-target-version = "py312"
+target-version = "py313"
 
 [tool.ruff.format]
 skip-magic-trailing-comma = true