anaplan-sdk 0.2.10__tar.gz → 0.3.0__tar.gz

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/.gitignore

@@ -1,3 +1,4 @@
+.prettierrc
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.2.10
+Version: 0.3.0
 Summary: Provides pythonic access to the Anaplan API
 Project-URL: Homepage, https://vinzenzklass.github.io/anaplan-sdk/
 Project-URL: Repository, https://github.com/VinzenzKlass/anaplan-sdk
@@ -38,7 +38,7 @@ implementation details like authentication, error handling, chunking, compressio
 This Projects supports
 the [Bulk APIs](https://help.anaplan.com/use-the-bulk-apis-93218e5e-00e5-406e-8361-09ab861889a7),
 the [Transactional APIs](https://help.anaplan.com/use-the-transactional-apis-cc1c1e91-39fc-4272-a4b5-16bc91e9c313) and
-the [ALM APsI](https://help.anaplan.com/application-lifecycle-management-api-2565cfa6-e0c2-4e24-884e-d0df957184d6),
+the [ALM APIs](https://help.anaplan.com/application-lifecycle-management-api-2565cfa6-e0c2-4e24-884e-d0df957184d6),
 the [Audit APIs](https://auditservice.docs.apiary.io/#),
 providing both synchronous and asynchronous Clients.
 

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/README.md

@@ -21,7 +21,7 @@ implementation details like authentication, error handling, chunking, compressio
 This Projects supports
 the [Bulk APIs](https://help.anaplan.com/use-the-bulk-apis-93218e5e-00e5-406e-8361-09ab861889a7),
 the [Transactional APIs](https://help.anaplan.com/use-the-transactional-apis-cc1c1e91-39fc-4272-a4b5-16bc91e9c313) and
-the [ALM APsI](https://help.anaplan.com/application-lifecycle-management-api-2565cfa6-e0c2-4e24-884e-d0df957184d6),
+the [ALM APIs](https://help.anaplan.com/application-lifecycle-management-api-2565cfa6-e0c2-4e24-884e-d0df957184d6),
 the [Audit APIs](https://auditservice.docs.apiary.io/#),
 providing both synchronous and asynchronous Clients.
 

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/anaplan_sdk/_async_clients/_bulk.py

@@ -3,8 +3,7 @@ Asynchronous Client.
 """
 
 import logging
-import time
-from asyncio import gather
+from asyncio import gather, sleep
 from copy import copy
 from typing import AsyncIterator, Iterator
 
@@ -14,7 +13,17 @@ from typing_extensions import Self
 from anaplan_sdk._auth import AnaplanBasicAuth, AnaplanCertAuth, get_certificate, get_private_key
 from anaplan_sdk._base import _AsyncBaseClient, action_url
 from anaplan_sdk.exceptions import AnaplanActionError, InvalidIdentifierException
-from anaplan_sdk.models import Action, Export, File, Import, Model, Process, Workspace
+from anaplan_sdk.models import (
+    Action,
+    Export,
+    File,
+    Import,
+    Model,
+    Process,
+    TaskStatus,
+    TaskSummary,
+    Workspace,
+)
 
 from ._alm import _AsyncAlmClient
 from ._audit import _AsyncAuditClient
@@ -250,7 +259,7 @@ class AsyncClient(_AsyncBaseClient):
             for e in (await self._get(f"{self._url}/exports")).get("exports", [])
         ]
 
-    async def run_action(self, action_id: int) -> None:
+    async def run_action(self, action_id: int) -> TaskStatus:
         """
         Runs the specified Anaplan Action and validates the spawned task. If the Action fails or
         completes with errors, will raise an :py:class:`AnaplanActionError`. Failed Tasks are
@@ -268,16 +277,15 @@ class AsyncClient(_AsyncBaseClient):
         task_id = await self.invoke_action(action_id)
         task_status = await self.get_task_status(action_id, task_id)
 
-        while "COMPLETE" not in task_status.get("taskState"):
-            time.sleep(self.status_poll_delay)
+        while task_status.task_state != "COMPLETE":
+            await sleep(self.status_poll_delay)
             task_status = await self.get_task_status(action_id, task_id)
 
-        if task_status.get("taskState") == "COMPLETE" and not task_status.get("result").get(
-            "successful"
-        ):
+        if task_status.task_state == "COMPLETE" and not task_status.result.successful:
             raise AnaplanActionError(f"Task '{task_id}' completed with errors.")
 
         logger.info(f"Task '{task_id}' completed successfully.")
+        return task_status
 
     async def get_file(self, file_id: int) -> bytes:
         """
@@ -390,29 +398,31 @@ class AsyncClient(_AsyncBaseClient):
         await self.run_action(action_id)
         return await self.get_file(action_id)
 
-    async def list_task_status(self, action_id: int) -> list:
+    async def list_task_status(self, action_id: int) -> list[TaskSummary]:
         """
         Retrieves the status of all tasks spawned by the specified action.
         :param action_id: The identifier of the action that was invoked.
         :return: The list of tasks spawned by the action.
         """
-        return (await self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks")).get(
-            "tasks", []
-        )
+        return [
+            TaskSummary.model_validate(e)
+            for e in (
+                await self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks")
+            ).get("tasks", [])
+        ]
 
-    async def get_task_status(
-        self, action_id: int, task_id: str
-    ) -> dict[str, float | int | str | list | dict | bool]:
+    async def get_task_status(self, action_id: int, task_id: str) -> TaskStatus:
         """
         Retrieves the status of the specified task.
         :param action_id: The identifier of the action that was invoked.
         :param task_id: The identifier of the spawned task.
-        :return: The status of the task as returned by the API. For more information
-                 see: https://anaplan.docs.apiary.io.
+        :return: The status of the task.
         """
-        return (
-            await self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks/{task_id}")
-        ).get("task")
+        return TaskStatus.model_validate(
+            (
+                await self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks/{task_id}")
+            ).get("task")
+        )
 
     async def invoke_action(self, action_id: int) -> str:
         """

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/anaplan_sdk/_async_clients/_transactional.py

@@ -1,3 +1,6 @@
+import warnings
+from asyncio import gather
+from itertools import chain
 from typing import Any
 
 import httpx
@@ -13,6 +16,8 @@ from anaplan_sdk.models import (
     Module,
 )
 
+warnings.filterwarnings("always", category=DeprecationWarning)
+
 
 class _AsyncTransactionalClient(_AsyncBaseClient):
     def __init__(self, client: httpx.AsyncClient, model_id: str, retry_count: int) -> None:
@@ -27,7 +32,7 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         """
         return [
             Module.model_validate(e)
-            for e in (await self._get(f"{self._url}/modules")).get("modules")
+            for e in (await self._get(f"{self._url}/modules")).get("modules", [])
         ]
 
     async def get_model_status(self) -> ModelStatus:
@@ -50,7 +55,7 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
             if only_module_id
             else f"{self._url}/lineItems?includeAll=true"
         )
-        return [LineItem.model_validate(e) for e in (await self._get(url)).get("items")]
+        return [LineItem.model_validate(e) for e in (await self._get(url)).get("items", [])]
 
     async def list_lists(self) -> list[List]:
         """
@@ -58,7 +63,7 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         :return: All Lists on this model.
         """
         return [
-            List.model_validate(e) for e in (await self._get(f"{self._url}/lists")).get("lists")
+            List.model_validate(e) for e in (await self._get(f"{self._url}/lists")).get("lists", [])
         ]
 
     async def get_list_metadata(self, list_id: int) -> ListMetadata:
@@ -85,28 +90,64 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
             )
         ]
 
-    async def add_items_to_list(
-        self, list_id: int, items: list[dict[str, str | dict]]
+    async def insert_list_items(
+        self, list_id: int, items: list[dict[str, str | int | dict]]
     ) -> InsertionResult:
         """
-        Adds items to a List.
+        Insert new items to the given list. The items must be a list of dictionaries with at least
+        the keys `code` and `name`. You can optionally pass further keys for parents, extra
+        properties etc.
         :param list_id: The ID of the List.
-        :param items: The items to add to the List.
-        :return: The result of the insertion.
-        """
-        # TODO: Paginate by 100k records.
-        return InsertionResult.model_validate(
-            await self._post(f"{self._url}/lists/{list_id}/items?action=add", json={"items": items})
+        :param items: The items to insert into the List.
+        :return: The result of the insertion, indicating how many items were added,
+                 ignored or failed.
+        """
+        if len(items) <= 100_000:
+            return InsertionResult.model_validate(
+                await self._post(
+                    f"{self._url}/lists/{list_id}/items?action=add", json={"items": items}
+                )
+            )
+        responses = await gather(
+            *(
+                self._post(f"{self._url}/lists/{list_id}/items?action=add", json={"items": chunk})
+                for chunk in (items[i : i + 100_000] for i in range(0, len(items), 100_000))
+            )
         )
+        failures, added, ignored, total = [], 0, 0, 0
+        for res in responses:
+            failures.append(res.get("failures", []))
+            added += res.get("added", 0)
+            total += res.get("total", 0)
+            ignored += res.get("ignored", 0)
 
-    async def delete_list_items(self, list_id: int, items: list[dict[str, str | int]]) -> None:
+        return InsertionResult(
+            added=added, ignored=ignored, total=total, failures=list(chain.from_iterable(failures))
+        )
+
+    async def delete_list_items(self, list_id: int, items: list[dict[str, str | int]]) -> int:
         """
         Deletes items from a List.
         :param list_id: The ID of the List.
         :param items: The items to delete from the List. Must be a dict with either `code` or `id`
                       as the keys to identify the records to delete.
         """
-        await self._post(f"{self._url}/lists/{list_id}/items?action=delete", json={"items": items})
+        if len(items) <= 100_000:
+            return (
+                await self._post(
+                    f"{self._url}/lists/{list_id}/items?action=delete", json={"items": items}
+                )
+            ).get("deleted", 0)
+
+        responses = await gather(
+            *(
+                self._post(
+                    f"{self._url}/lists/{list_id}/items?action=delete", json={"items": chunk}
+                )
+                for chunk in (items[i : i + 100_000] for i in range(0, len(items), 100_000))
+            )
+        )
+        return sum(res.get("deleted", 0) for res in responses)
 
     async def reset_list_index(self, list_id: int) -> None:
         """
@@ -115,7 +156,7 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         """
         await self._post_empty(f"{self._url}/lists/{list_id}/resetIndex")
 
-    async def write_to_module(
+    async def update_module_data(
         self, module_id: int, data: list[dict[str, Any]]
     ) -> int | dict[str, Any]:
         """
@@ -129,3 +170,25 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         """
         res = await self._post(f"{self._url}/modules/{module_id}/data", json=data)
         return res if "failures" in res else res["numberOfCellsChanged"]
+
+    async def write_to_module(
+        self, module_id: int, data: list[dict[str, Any]]
+    ) -> int | dict[str, Any]:
+        warnings.warn(
+            "`write_to_module()` is deprecated and will be removed in a future version. "
+            "Use `update_module_data()` instead.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
+        return await self.update_module_data(module_id, data)
+
+    async def add_items_to_list(
+        self, list_id: int, items: list[dict[str, str | int | dict]]
+    ) -> InsertionResult:
+        warnings.warn(
+            "`add_items_to_list()` is deprecated and will be removed in a future version. "
+            "Use `insert_list_items()` instead.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
+        return await self.insert_list_items(list_id, items)

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/anaplan_sdk/_auth.py

@@ -12,86 +12,67 @@ from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives import hashes, serialization
 from cryptography.hazmat.primitives.asymmetric.padding import PKCS1v15
 from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
-from httpx import HTTPError
 
-from .exceptions import InvalidCredentialsException, InvalidPrivateKeyException
+from .exceptions import AnaplanException, InvalidCredentialsException, InvalidPrivateKeyException
 
 logger = logging.getLogger("anaplan_sdk")
 
 
-class AnaplanBasicAuth(httpx.Auth):
+class _AnaplanAuth(httpx.Auth):
     requires_response_body = True
 
-    def __init__(
-        self,
-        user_email: str,
-        password: str,
-    ):
-        self._user_email = user_email
-        self._password = password
-        self._token = self._init_token()
+    def __init__(self):
+        self._auth_request = self._build_auth_request()
+        logger.info("Creating Authentication Token.")
+        with httpx.Client(timeout=15.0) as client:
+            res = client.send(self._auth_request)
+            self._parse_auth_response(res)
+
+    def _build_auth_request(self) -> httpx.Request:
+        raise NotImplementedError("Must be implemented in subclass.")
 
     def auth_flow(self, request):
         request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
         response = yield request
         if response.status_code == 401:
             logger.info("Token expired, refreshing.")
-            response = yield self._basic_auth_request()
-            if "tokenInfo" not in response.json():
-                raise InvalidCredentialsException
-            self._token = response.json().get("tokenInfo").get("tokenValue")
+            auth_res = yield self._auth_request
+            self._parse_auth_response(auth_res)
             request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
             yield request
 
-    def _basic_auth_request(self):
-        credentials = b64encode(f"{self._user_email}:{self._password}".encode()).decode()
+    def _parse_auth_response(self, response: httpx.Response) -> None:
+        if response.status_code == 401:
+            raise InvalidCredentialsException
+        if not response.is_success:
+            raise AnaplanException(f"Authentication failed: {response.status_code} {response.text}")
+        self._token: str = response.json()["tokenInfo"]["tokenValue"]
+
+
+class AnaplanBasicAuth(_AnaplanAuth):
+    def __init__(self, user_email: str, password: str):
+        self.user_email = user_email
+        self.password = password
+        super().__init__()
+
+    def _build_auth_request(self) -> httpx.Request:
+        cred = b64encode(f"{self.user_email}:{self.password}".encode()).decode()
         return httpx.Request(
             method="post",
             url="https://auth.anaplan.com/token/authenticate",
-            headers={"Authorization": f"Basic {credentials}"},
+            headers={"Authorization": f"Basic {cred}"},
         )
 
-    def _init_token(self) -> str:
-        try:
-            logger.info("Creating Authentication Token.")
-            credentials = b64encode(f"{self._user_email}:{self._password}".encode()).decode()
-            res = httpx.post(
-                url="https://auth.anaplan.com/token/authenticate",
-                headers={"Authorization": f"Basic {credentials}"},
-                timeout=15,
-            )
-            res.raise_for_status()
-            return res.json().get("tokenInfo").get("tokenValue")
-        except HTTPError as error:
-            raise InvalidCredentialsException from error
-
-
-class AnaplanCertAuth(httpx.Auth):
-    requires_response_body = True
+
+class AnaplanCertAuth(_AnaplanAuth):
     requires_request_body = True
 
-    def __init__(
-        self,
-        certificate: bytes,
-        private_key: RSAPrivateKey,
-    ):
+    def __init__(self, certificate: bytes, private_key: RSAPrivateKey):
         self._certificate = certificate
         self._private_key = private_key
-        self._token = self._init_token()
+        super().__init__()
 
-    def auth_flow(self, request):
-        request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
-        response = yield request
-        if response.status_code == 401:
-            logger.info("Token expired or invalid, refreshing.")
-            response = yield self._cert_auth_request()
-            if "tokenInfo" not in response.json():
-                raise InvalidCredentialsException
-            self._token = response.json().get("tokenInfo").get("tokenValue")
-            request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
-            yield request
-
-    def _cert_auth_request(self):
+    def _build_auth_request(self) -> httpx.Request:
         encoded_cert, encoded_string, encoded_signed_string = self._prep_credentials()
         return httpx.Request(
             method="post",
@@ -103,24 +84,6 @@ class AnaplanCertAuth(httpx.Auth):
             json={"encodedData": encoded_string, "encodedSignedData": encoded_signed_string},
         )
 
-    def _init_token(self) -> str:
-        try:
-            logger.info("Creating Authentication Token.")
-            encoded_cert, encoded_string, encoded_signed_string = self._prep_credentials()
-            res = httpx.post(
-                url="https://auth.anaplan.com/token/authenticate",
-                headers={
-                    "Authorization": f"CACertificate {encoded_cert}",
-                    "Content-Type": "application/json",
-                },
-                json={"encodedData": encoded_string, "encodedSignedData": encoded_signed_string},
-                timeout=15,
-            )
-            res.raise_for_status()
-            return res.json().get("tokenInfo").get("tokenValue")
-        except HTTPError as error:
-            raise InvalidCredentialsException from error
-
     def _prep_credentials(self) -> tuple[str, str, str]:
         message = os.urandom(150)
         return (

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/anaplan_sdk/_base.py

@@ -2,7 +2,10 @@
 Provides Base Classes for this project.
 """
 
+import asyncio
 import logging
+import random
+import time
 from gzip import compress
 from typing import Any, Callable, Coroutine, Literal
 
@@ -51,6 +54,13 @@ class _BaseClient:
         for i in range(max(self._retry_count, 1)):
             try:
                 response = func(*args, **kwargs)
+                if response.status_code == 429:
+                    if i >= self._retry_count - 1:
+                        raise AnaplanException("Rate limit exceeded.")
+                    backoff_time = max(i, 1) * random.randint(2, 5)
+                    logger.info(f"Rate limited. Retrying in {backoff_time} seconds.")
+                    time.sleep(backoff_time)
+                    continue
                 response.raise_for_status()
                 return response
             except HTTPError as error:
@@ -99,6 +109,13 @@ class _AsyncBaseClient:
         for i in range(max(self._retry_count, 1)):
             try:
                 response = await func(*args, **kwargs)
+                if response.status_code == 429:
+                    if i >= self._retry_count - 1:
+                        raise AnaplanException("Rate limit exceeded.")
+                    backoff_time = (i + 1) * random.randint(3, 5)
+                    logger.info(f"Rate limited. Retrying in {backoff_time} seconds.")
+                    await asyncio.sleep(backoff_time)
+                    continue
                 response.raise_for_status()
                 return response
             except HTTPError as error:

{anaplan_sdk-0.2.10 → anaplan_sdk-0.3.0}/anaplan_sdk/_clients/_bulk.py

@@ -15,7 +15,17 @@ from typing_extensions import Self
 from anaplan_sdk._auth import AnaplanBasicAuth, AnaplanCertAuth, get_certificate, get_private_key
 from anaplan_sdk._base import _BaseClient, action_url
 from anaplan_sdk.exceptions import AnaplanActionError, InvalidIdentifierException
-from anaplan_sdk.models import Action, Export, File, Import, Model, Process, Workspace
+from anaplan_sdk.models import (
+    Action,
+    Export,
+    File,
+    Import,
+    Model,
+    Process,
+    TaskStatus,
+    TaskSummary,
+    Workspace,
+)
 
 from ._alm import _AlmClient
 from ._audit import _AuditClient
@@ -252,7 +262,7 @@ class Client(_BaseClient):
             Export.model_validate(e) for e in (self._get(f"{self._url}/exports")).get("exports", [])
         ]
 
-    def run_action(self, action_id: int) -> None:
+    def run_action(self, action_id: int) -> TaskStatus:
         """
         Runs the specified Anaplan Action and validates the spawned task. If the Action fails or
         completes with errors, will raise an :py:class:`AnaplanActionError`. Failed Tasks are
@@ -270,16 +280,15 @@ class Client(_BaseClient):
         task_id = self.invoke_action(action_id)
         task_status = self.get_task_status(action_id, task_id)
 
-        while "COMPLETE" not in task_status.get("taskState"):
+        while task_status.task_state != "COMPLETE":
             time.sleep(self.status_poll_delay)
             task_status = self.get_task_status(action_id, task_id)
 
-        if task_status.get("taskState") == "COMPLETE" and not task_status.get("result").get(
-            "successful"
-        ):
+        if task_status.task_state == "COMPLETE" and not task_status.result.successful:
             raise AnaplanActionError(f"Task '{task_id}' completed with errors.")
 
         logger.info(f"Task '{task_id}' completed successfully.")
+        return task_status
 
     def get_file(self, file_id: int) -> bytes:
         """
@@ -383,26 +392,30 @@ class Client(_BaseClient):
         self.run_action(action_id)
         return self.get_file(action_id)
 
-    def list_task_status(self, action_id: int) -> list:
+    def list_task_status(self, action_id: int) -> list[TaskSummary]:
         """
         Retrieves the status of all tasks spawned by the specified action.
         :param action_id: The identifier of the action that was invoked.
         :return: The list of tasks spawned by the action.
         """
-        return self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks").get("tasks", [])
+        return [
+            TaskSummary.model_validate(e)
+            for e in self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks").get(
+                "tasks", []
+            )
+        ]
 
-    def get_task_status(
-        self, action_id: int, task_id: str
-    ) -> dict[str, float | int | str | list | dict | bool]:
+    def get_task_status(self, action_id: int, task_id: str) -> TaskStatus:
         """
         Retrieves the status of the specified task.
         :param action_id: The identifier of the action that was invoked.
         :param task_id: The identifier of the spawned task.
-        :return: The status of the task as returned by the API. For more information
-                 see: https://anaplan.docs.apiary.io.
+        :return: The status of the task.
         """
-        return self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks/{task_id}").get(
-            "task"
+        return TaskStatus.model_validate(
+            self._get(f"{self._url}/{action_url(action_id)}/{action_id}/tasks/{task_id}").get(
+                "task"
+            )
         )
 
     def invoke_action(self, action_id: int) -> str: