anaplan-sdk 0.4.1__tar.gz → 0.4.3__tar.gz

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.1
+Version: 0.4.3
 Summary: Streamlined Python Interface for Anaplan
 Project-URL: Homepage, https://vinzenzklass.github.io/anaplan-sdk/
 Project-URL: Repository, https://github.com/VinzenzKlass/anaplan-sdk

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/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,8 +56,8 @@ class AsyncClient(_AsyncBaseClient):
         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,
+        on_auth_code: AuthCodeCallback = None,
+        on_token_refresh: AuthTokenRefreshCallback = None,
         timeout: float | httpx.Timeout = 30,
         retry_count: int = 2,
         status_poll_delay: int = 1,
@@ -94,12 +94,25 @@ class AsyncClient(_AsyncBaseClient):
         :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.
+                             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

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/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,8 +153,8 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
         redirect_uri: str,
         refresh_token: str | None = None,
         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,
+        on_auth_code: AuthCodeCallback = None,
+        on_token_refresh: AuthTokenRefreshCallback = None,
     ):
         try:
             from oauthlib.oauth2 import WebApplicationClient
@@ -188,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):
@@ -202,7 +211,7 @@ class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
                 scope=self._scope,
             )
             authorization_response = (
-                self._on_auth_code(url)
+                _run_callback(self._on_auth_code, url)
                 if self._on_auth_code
                 else input(
                     f"Please go to {url} and authorize the app.\n"
@@ -231,8 +240,8 @@ def create_auth(
     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,
+    on_auth_code: AuthCodeCallback = None,
+    on_token_refresh: AuthTokenRefreshCallback = None,
 ) -> _AnaplanAuth:
     if certificate and private_key:
         return AnaplanCertAuth(certificate, private_key, private_key_password)
@@ -254,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.1 → anaplan_sdk-0.4.3}/anaplan_sdk/_clients/_bulk.py

@@ -99,6 +99,7 @@ class Client(_BaseClient):
                      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

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/anaplan_sdk/models/_bulk.py

@@ -145,10 +145,10 @@ class TaskSummary(AnaplanModel):
 
 
 class TaskResultDetail(AnaplanModel):
-    local_message_text: str = Field(description="Error message text.")
+    local_message_text: str | None = Field(None, description="Error message text.")
     occurrences: int = Field(0, description="The number of occurrences of this error.")
     type: str = Field(description="The type of this error.")
-    values: list[str] = Field([], description="Further error information if available.")
+    values: list[str | None] = Field([], description="Further error information if available.")
 
 
 class TaskResult(AnaplanModel):

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/async/async_alm_client.md

@@ -3,3 +3,9 @@
     instance of [AsyncClient](async_client.md). For more details, see the [Guide](../../guides/alm.md).
 
 ::: anaplan_sdk._async_clients._AsyncAlmClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/async/async_audit_client.md

@@ -3,3 +3,9 @@
     instance of [AsyncClient](async_client.md). For more details, see the [Guide](../../guides/audit.md).
 
 ::: anaplan_sdk._async_clients._AsyncAuditClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/async/async_client.md

@@ -0,0 +1,9 @@
+# Bulk API Client (`AsyncClient`)
+
+::: anaplan_sdk.AsyncClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/async/async_cw_client.md

@@ -3,3 +3,9 @@
     instance of [AsyncClient](async_client.md). For more details, see the [Guide](../../guides/cloud_works.md).
 
 ::: anaplan_sdk._async_clients._AsyncCloudWorksClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/async/async_flows_client.md

@@ -3,3 +3,9 @@
     instance of [AsyncClient](async_client.md). For more details, see the [Guide](../../guides/cloud_works.md).
 
 ::: anaplan_sdk._async_clients._cw_flow._AsyncFlowClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/async/async_transactional_client.md

@@ -0,0 +1,11 @@
+???+ note
+     This Class is not meant to be instantiated directly, but rather accessed through the `transactional` Property on an
+     instance of [AsyncClient](async_client.md). For more details, see the [Guide](../../guides/transactional.md).
+
+::: anaplan_sdk._async_clients._AsyncTransactionalClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/exceptions.md

@@ -0,0 +1,9 @@
+::: anaplan_sdk.exceptions
+    options:
+        show_bases: true
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/models/alm.md

@@ -0,0 +1,7 @@
+::: anaplan_sdk.models._alm
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/models/bulk.md

@@ -0,0 +1,7 @@
+::: anaplan_sdk.models._bulk
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/models/cloud_works.md

@@ -0,0 +1,7 @@
+::: anaplan_sdk.models.cloud_works
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/models/flows.md

@@ -0,0 +1,7 @@
+::: anaplan_sdk.models.flows
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/models/transactional.md

@@ -0,0 +1,7 @@
+::: anaplan_sdk.models._transactional
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/sync/sync_alm_client.md

@@ -3,3 +3,9 @@
     instance of [Client](sync_client.md). For more details, see the [Guide](../../guides/alm.md).
 
 ::: anaplan_sdk._clients._AlmClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/sync/sync_audit_client.md

@@ -3,3 +3,9 @@
     instance of [Client](sync_client.md). For more details, see the [Guide](../../guides/audit.md).
 
 ::: anaplan_sdk._clients._AuditClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

anaplan_sdk-0.4.3/docs/api/sync/sync_client.md

@@ -0,0 +1,9 @@
+# Bulk API Client (`Client`)
+
+::: anaplan_sdk.Client
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/sync/sync_cw_client.md

@@ -3,3 +3,9 @@
     instance of [Client](sync_client.md). For more details, see the [Guide](../../guides/cloud_works.md).
 
 ::: anaplan_sdk._async_clients._AsyncCloudWorksClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/sync/sync_flows_client.md

@@ -3,3 +3,9 @@
     instance of [Client](sync_client.md). For more details, see the [Guide](../../guides/cloud_works.md).
 
 ::: anaplan_sdk._async_clients._cw_flow._AsyncFlowClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/api/sync/sync_transactional_client.md

@@ -3,3 +3,9 @@
     instance of [Client](sync_client.md). For more details, see the [Guide](../../guides/transactional.md).
 
 ::: anaplan_sdk._clients._TransactionalClient
+
+<style>
+    [data-md-component="toc"] li:first-of-type{
+        display:  none!important;
+    }
+</style>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/guides/authentication.md

@@ -148,6 +148,12 @@ When using OAuth authentication, the default behavior prompts you to manually op
 
 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:
@@ -164,7 +170,7 @@ The `on_auth_code` callback lets you hook into the Auth Flow to handle the autho
     ```
 === "Asynchronous"
     ```python
-    def on_auth_code(redirect_uri: str) -> str:
+    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(
@@ -221,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.1 → anaplan_sdk-0.4.3}/docs/guides/index.md

@@ -16,6 +16,6 @@ respective Guides to get started with each API.
 - [__CloudWorks API__](cloud_works.md) for orchestrating and automating your Anaplan processes
 - [__ALM API__](alm.md) for managing your Anaplan assets and their lifecycle
 - [__Audit API__](audit.md) for tracking changes and maintaining compliance
-- The Auth APIs are used internally by the SDK to automatically manage authentication.
+- [__Auth APIs__](authentication.md) are used internally by the SDK to automatically manage authentication.
 
 </div>

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/docs/quickstart.md

@@ -56,7 +56,7 @@ common practice.
     files, processes = await gather(anaplan.list_files(), anaplan.list_processes())
     ```
 ??? info "Output"
-    Models used in this Example: [File](api/models.md#anaplan_sdk.models.File), [Process](api/models.md#anaplan_sdk.models.Process).
+    Models used in this Example: [File](api/models/bulk.md#anaplan_sdk.models._bulk.File), [Process](api/models/bulk.md#anaplan_sdk.models._bulk.Process).
     ```python
     [
         File(
@@ -90,7 +90,7 @@ With these two, you're ready to run your first import.
     )
     ```
     
-This will upload the file to Anaplan, trigger the process task, wait for the completion of the task and validate the task result. You can see the details of the task by inspecting the [TaskResult](api/models.md#anaplan_sdk.models.TaskResult).
+This will upload the file to Anaplan, trigger the process task, wait for the completion of the task and validate the task result. You can see the details of the task by inspecting the [TaskResult](api/models/bulk.md#anaplan_sdk.models._bulk.TaskResult).
 
 ## Exporting Data
 
@@ -105,7 +105,7 @@ Conversely, for exporting data, we start by listing the available exports.
     exports = await anaplan.list_exports()
     ```
 ??? info "Output"
-    Models used in this Example: [Export](api/models.md#anaplan_sdk.models.Export).
+    Models used in this Example: [Export](api/models/bulk.md#anaplan_sdk.models._bulk.Export).
     ```python
     [
         Export(

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: Anaplan SDK
-site_description: Provides pythonic access to the Anaplan API.
+site_description: Streamlined Python Interface for Anaplan
 site_url: https://vinzenzklass.github.io/anaplan-sdk/
 repo_name: VinzenzKlass/anaplan-sdk
 repo_url: https://github.com/VinzenzKlass/anaplan-sdk
@@ -24,6 +24,7 @@ theme:
     - content.code.copy
     - content.tabs.link
     - search.suggest
+    - navigation.instant
     - navigation.tabs
     - navigation.top
 
@@ -64,7 +65,12 @@ nav:
           - CloudWorks:
               - Client: 'api/sync/sync_cw_client.md'
               - Flows: 'api/sync/sync_flows_client.md'
-      - Models: 'api/models.md'
+      - Models:
+         - ALM: 'api/models/alm.md'
+         - Bulk: 'api/models/bulk.md'
+         - CloudWorks: 'api/models/cloud_works.md'
+         - Flows: 'api/models/flows.md'
+         - Transactional: 'api/models/transactional.md'
       - Exceptions: 'api/exceptions.md'
   - Concepts:
       - Anaplan Basics: 'anaplan_explained.md'

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "anaplan-sdk"
-version = "0.4.1"
+version = "0.4.3"
 description = "Streamlined Python Interface for Anaplan"
 license = "Apache-2.0"
 authors = [{ name = "Vinzenz Klass", email = "vinzenz.klass@valantic.com" }]
@@ -84,7 +84,7 @@ exclude = [
 
 line-length = 100
 fix = true
-target-version = "py312"
+target-version = "py313"
 
 [tool.ruff.format]
 skip-magic-trailing-comma = true

{anaplan_sdk-0.4.1 → anaplan_sdk-0.4.3}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.10.4"
 
 [[package]]
 name = "anaplan-sdk"
-version = "0.4.1"
+version = "0.4.3"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

anaplan_sdk-0.4.1/docs/api/async/async_client.md

@@ -1 +0,0 @@
-::: anaplan_sdk.AsyncClient

anaplan_sdk-0.4.1/docs/api/async/async_transactional_client.md

@@ -1,5 +0,0 @@
-!!! note
-    This Class is not meant to be instantiated directly, but rather accessed through the `transactional` Property on an
-    instance of [AsyncClient](async_client.md). For more details, see the [Guide](../../guides/transactional.md).
-
-::: anaplan_sdk._async_clients._AsyncTransactionalClient

anaplan_sdk-0.4.1/docs/api/exceptions.md

@@ -1,4 +0,0 @@
-::: anaplan_sdk.exceptions
-    options:
-        show_bases: true
-

anaplan_sdk-0.4.1/docs/api/models.md

@@ -1,4 +0,0 @@
-This Project uses [Pydantic](https://docs.pydantic.dev/latest/) Models. Methods on both the `AsyncClient`
-and `Client` will return one of the models documented below - or list thereof where applicable.
-
-::: anaplan_sdk.models

anaplan_sdk-0.4.1/docs/api/sync/sync_client.md

@@ -1 +0,0 @@
-::: anaplan_sdk.Client