anaplan-sdk 0.4.4a4__py3-none-any.whl → 0.5.0a1__py3-none-any.whl

anaplan_sdk/_base.py

@@ -13,7 +13,15 @@ import httpx
 from httpx import HTTPError, Response
 
 from .exceptions import AnaplanException, AnaplanTimeoutException, InvalidIdentifierException
-from .models import AnaplanModel
+from .models import (
+    AnaplanModel,
+    InsertionResult,
+    ModelCalendar,
+    MonthsQuartersYearsCalendar,
+    WeeksGeneralCalendar,
+    WeeksGroupingCalendar,
+    WeeksPeriodsCalendar,
+)
 from .models.cloud_works import (
     AmazonS3ConnectionInput,
     AzureBlobConnectionInput,
@@ -36,61 +44,70 @@ class _BaseClient:
     def __init__(self, retry_count: int, client: httpx.Client):
         self._retry_count = retry_count
         self._client = client
+        logger.debug(f"Initialized BaseClient with retry_count={retry_count}.")
 
     def _get(self, url: str, **kwargs) -> dict[str, Any]:
-        return self._run_with_retry(self._client.get, url, **kwargs).json()
+        return self.__run_with_retry(self._client.get, url, **kwargs).json()
 
     def _get_binary(self, url: str) -> bytes:
-        return self._run_with_retry(self._client.get, url).content
+        return self.__run_with_retry(self._client.get, url).content
 
     def _post(self, url: str, json: dict | list) -> dict[str, Any]:
-        return self._run_with_retry(self._client.post, url, headers=_json_header, json=json).json()
+        return self.__run_with_retry(self._client.post, url, headers=_json_header, json=json).json()
 
     def _put(self, url: str, json: dict | list) -> dict[str, Any]:
-        return (self._run_with_retry(self._client.put, url, headers=_json_header, json=json)).json()
+        res = self.__run_with_retry(self._client.put, url, headers=_json_header, json=json)
+        return res.json() if res.num_bytes_downloaded > 0 else {}
 
     def _patch(self, url: str, json: dict | list) -> dict[str, Any]:
         return (
-            self._run_with_retry(self._client.patch, url, headers=_json_header, json=json)
+            self.__run_with_retry(self._client.patch, url, headers=_json_header, json=json)
         ).json()
 
     def _delete(self, url: str) -> dict[str, Any]:
-        return (self._run_with_retry(self._client.delete, url, headers=_json_header)).json()
+        return (self.__run_with_retry(self._client.delete, url, headers=_json_header)).json()
 
-    def _post_empty(self, url: str) -> dict[str, Any]:
-        res = self._run_with_retry(self._client.post, url)
+    def _post_empty(self, url: str, **kwargs) -> dict[str, Any]:
+        res = self.__run_with_retry(self._client.post, url, **kwargs)
         return res.json() if res.num_bytes_downloaded > 0 else {}
 
-    def _put_binary_gzip(self, url: str, content: bytes) -> Response:
-        return self._run_with_retry(
-            self._client.put, url, headers=_gzip_header, content=compress(content)
-        )
+    def _put_binary_gzip(self, url: str, content: str | bytes) -> Response:
+        content = compress(content.encode() if isinstance(content, str) else content)
+        return self.__run_with_retry(self._client.put, url, headers=_gzip_header, content=content)
 
     def __get_page(self, url: str, limit: int, offset: int, result_key: str, **kwargs) -> list:
+        logger.debug(f"Fetching page: offset={offset}, limit={limit} from {url}.")
         kwargs["params"] = kwargs.get("params") or {} | {"limit": limit, "offset": offset}
         return self._get(url, **kwargs).get(result_key, [])
 
     def __get_first_page(self, url: str, limit: int, result_key: str, **kwargs) -> tuple[list, int]:
+        logger.debug(f"Fetching first page with limit={limit} from {url}.")
         kwargs["params"] = kwargs.get("params") or {} | {"limit": limit}
         res = self._get(url, **kwargs)
-        return res.get(result_key, []), res["meta"]["paging"]["totalSize"]
+        total_items, first_page = res["meta"]["paging"]["totalSize"], res.get(result_key, [])
+        logger.debug(f"Found {total_items} total items, retrieved {len(first_page)} in first page.")
+        return first_page, total_items
 
     def _get_paginated(
         self, url: str, result_key: str, page_size: int = 5_000, **kwargs
     ) -> Iterator[dict[str, Any]]:
+        logger.debug(f"Starting paginated fetch from {url} with page_size={page_size}.")
         first_page, total_items = self.__get_first_page(url, page_size, result_key, **kwargs)
         if total_items <= page_size:
+            logger.debug("All items fit in first page, no additional requests needed.")
             return iter(first_page)
 
+        pages_needed = ceil(total_items / page_size)
+        logger.debug(f"Fetching {pages_needed - 1} additional pages with {page_size} items each.")
         with ThreadPoolExecutor() as executor:
             pages = executor.map(
                 lambda n: self.__get_page(url, page_size, n * page_size, result_key, **kwargs),
-                range(1, ceil(total_items / page_size)),
+                range(1, pages_needed),
             )
-
+        logger.debug(f"Completed paginated fetch of {total_items} total items.")
         return chain(first_page, *pages)
 
-    def _run_with_retry(self, func: Callable[..., Response], *args, **kwargs) -> Response:
+    def __run_with_retry(self, func: Callable[..., Response], *args, **kwargs) -> Response:
         for i in range(max(self._retry_count, 1)):
             try:
                 response = func(*args, **kwargs)
@@ -98,7 +115,7 @@ class _BaseClient:
                     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.")
+                    logger.warning(f"Rate limited. Retrying in {backoff_time} seconds.")
                     time.sleep(backoff_time)
                     continue
                 response.raise_for_status()
@@ -116,58 +133,65 @@ class _AsyncBaseClient:
     def __init__(self, retry_count: int, client: httpx.AsyncClient):
         self._retry_count = retry_count
         self._client = client
+        logger.debug(f"Initialized AsyncBaseClient with retry_count={retry_count}.")
 
     async def _get(self, url: str, **kwargs) -> dict[str, Any]:
-        return (await self._run_with_retry(self._client.get, url, **kwargs)).json()
+        return (await self.__run_with_retry(self._client.get, url, **kwargs)).json()
 
     async def _get_binary(self, url: str) -> bytes:
-        return (await self._run_with_retry(self._client.get, url)).content
+        return (await self.__run_with_retry(self._client.get, url)).content
 
     async def _post(self, url: str, json: dict | list) -> dict[str, Any]:
         return (
-            await self._run_with_retry(self._client.post, url, headers=_json_header, json=json)
+            await self.__run_with_retry(self._client.post, url, headers=_json_header, json=json)
         ).json()
 
     async def _put(self, url: str, json: dict | list) -> dict[str, Any]:
-        return (
-            await self._run_with_retry(self._client.put, url, headers=_json_header, json=json)
-        ).json()
+        res = await self.__run_with_retry(self._client.put, url, headers=_json_header, json=json)
+        return res.json() if res.num_bytes_downloaded > 0 else {}
 
     async def _patch(self, url: str, json: dict | list) -> dict[str, Any]:
         return (
-            await self._run_with_retry(self._client.patch, url, headers=_json_header, json=json)
+            await self.__run_with_retry(self._client.patch, url, headers=_json_header, json=json)
         ).json()
 
     async def _delete(self, url: str) -> dict[str, Any]:
-        return (await self._run_with_retry(self._client.delete, url, headers=_json_header)).json()
+        return (await self.__run_with_retry(self._client.delete, url, headers=_json_header)).json()
 
-    async def _post_empty(self, url: str) -> dict[str, Any]:
-        res = await self._run_with_retry(self._client.post, url)
+    async def _post_empty(self, url: str, **kwargs) -> dict[str, Any]:
+        res = await self.__run_with_retry(self._client.post, url, **kwargs)
         return res.json() if res.num_bytes_downloaded > 0 else {}
 
-    async def _put_binary_gzip(self, url: str, content: bytes) -> Response:
-        return await self._run_with_retry(
-            self._client.put, url, headers=_gzip_header, content=compress(content)
+    async def _put_binary_gzip(self, url: str, content: str | bytes) -> Response:
+        content = compress(content.encode() if isinstance(content, str) else content)
+        return await self.__run_with_retry(
+            self._client.put, url, headers=_gzip_header, content=content
         )
 
     async def __get_page(
         self, url: str, limit: int, offset: int, result_key: str, **kwargs
     ) -> list:
+        logger.debug(f"Fetching page: offset={offset}, limit={limit} from {url}.")
         kwargs["params"] = kwargs.get("params") or {} | {"limit": limit, "offset": offset}
         return (await self._get(url, **kwargs)).get(result_key, [])
 
     async def __get_first_page(
         self, url: str, limit: int, result_key: str, **kwargs
     ) -> tuple[list, int]:
+        logger.debug(f"Fetching first page with limit={limit} from {url}.")
         kwargs["params"] = kwargs.get("params") or {} | {"limit": limit}
         res = await self._get(url, **kwargs)
-        return res.get(result_key, []), res["meta"]["paging"]["totalSize"]
+        total_items, first_page = res["meta"]["paging"]["totalSize"], res.get(result_key, [])
+        logger.debug(f"Found {total_items} total items, retrieved {len(first_page)} in first page.")
+        return first_page, total_items
 
     async def _get_paginated(
         self, url: str, result_key: str, page_size: int = 5_000, **kwargs
     ) -> Iterator[dict[str, Any]]:
+        logger.debug(f"Starting paginated fetch from {url} with page_size={page_size}.")
         first_page, total_items = await self.__get_first_page(url, page_size, result_key, **kwargs)
         if total_items <= page_size:
+            logger.debug("All items fit in first page, no additional requests needed.")
             return iter(first_page)
         pages = await gather(
             *(
@@ -175,9 +199,10 @@ class _AsyncBaseClient:
                 for n in range(1, ceil(total_items / page_size))
             )
         )
+        logger.info(f"Completed paginated fetch of {total_items} total items.")
         return chain(first_page, *pages)
 
-    async def _run_with_retry(
+    async def __run_with_retry(
         self, func: Callable[..., Coroutine[Any, Any, Response]], *args, **kwargs
     ) -> Response:
         for i in range(max(self._retry_count, 1)):
@@ -187,7 +212,7 @@ class _AsyncBaseClient:
                     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.")
+                    logger.warning(f"Rate limited. Retrying in {backoff_time} seconds.")
                     await asyncio.sleep(backoff_time)
                     continue
                 response.raise_for_status()
@@ -295,3 +320,59 @@ def raise_error(error: HTTPError) -> None:
 
     logger.error(f"Error: {error}")
     raise AnaplanException from error
+
+
+def parse_calendar_response(data: dict) -> ModelCalendar:
+    """
+    Parse calendar response and return appropriate calendar model.
+    :param data: The calendar data from the API response.
+    :return: The calendar settings of the model based on calendar type.
+    """
+    calendar_data = data["modelCalendar"]
+    cal_type = calendar_data["calendarType"]
+    if cal_type == "Calendar Months/Quarters/Years":
+        return MonthsQuartersYearsCalendar.model_validate(calendar_data)
+    if cal_type == "Weeks: 4-4-5, 4-5-4 or 5-4-4":
+        return WeeksGroupingCalendar.model_validate(calendar_data)
+    if cal_type == "Weeks: General":
+        return WeeksGeneralCalendar.model_validate(calendar_data)
+    if cal_type == "Weeks: 13 4-week Periods":
+        return WeeksPeriodsCalendar.model_validate(calendar_data)
+    raise AnaplanException(
+        "Unknown calendar type encountered. Please report this issue: "
+        "https://github.com/VinzenzKlass/anaplan-sdk/issues/new"
+    )
+
+
+def parse_insertion_response(data: list[dict]) -> InsertionResult:
+    failures, added, ignored, total = [], 0, 0, 0
+    for res in data:
+        failures.append(res.get("failures", []))
+        added += res.get("added", 0)
+        total += res.get("total", 0)
+        ignored += res.get("ignored", 0)
+    return InsertionResult(
+        added=added, ignored=ignored, total=total, failures=list(chain.from_iterable(failures))
+    )
+
+
+def validate_dimension_id(dimension_id: int) -> int:
+    if not (
+        dimension_id == 101999999999
+        or 101_000_000_000 <= dimension_id < 102_000_000_000
+        or 109_000_000_000 <= dimension_id < 110_000_000_000
+        or 114_000_000_000 <= dimension_id < 115_000_000_000
+    ):
+        raise InvalidIdentifierException(
+            "Invalid dimension_id. Must be a List (101xxxxxxxxx), List Subset (109xxxxxxxxx), "
+            "Line Item Subset (114xxxxxxxxx), or Users (101999999999)."
+        )
+    msg = (
+        "Using `get_dimension_items` for {} is discouraged. "
+        "Prefer `{}` for better performance and more details on the members."
+    )
+    if dimension_id == 101999999999:
+        logger.warning(msg.format("Users", "get_users"))
+    if 101000000000 <= dimension_id < 102000000000:
+        logger.warning(msg.format("Lists", "get_list_items"))
+    return dimension_id

anaplan_sdk/_clients/_alm.py

@@ -1,14 +1,60 @@
+import logging
+from time import sleep
+from typing import Literal, overload
+
 import httpx
 
 from anaplan_sdk._base import _BaseClient
-from anaplan_sdk.models import ModelRevision, Revision, SyncTask
+from anaplan_sdk.exceptions import AnaplanActionError
+from anaplan_sdk.models import (
+    ModelRevision,
+    ReportTask,
+    Revision,
+    SummaryReport,
+    SyncTask,
+    TaskSummary,
+)
+
+logger = logging.getLogger("anaplan_sdk")
 
 
 class _AlmClient(_BaseClient):
-    def __init__(self, client: httpx.Client, model_id: str, retry_count: int) -> None:
-        self._url = f"https://api.anaplan.com/2/0/models/{model_id}/alm"
+    def __init__(
+        self, client: httpx.Client, model_id: str, retry_count: int, status_poll_delay: int
+    ) -> None:
+        self.status_poll_delay = status_poll_delay
+        self._model_id = model_id
+        self._url = f"https://api.anaplan.com/2/0/models/{model_id}"
         super().__init__(retry_count, client)
 
+    def change_model_status(self, status: Literal["online", "offline"]) -> None:
+        """
+        Use this call to change the status of a model.
+        :param status: The status of the model. Can be either "online" or "offline".
+        """
+        logger.info(f"Changed model status to '{status}' for model {self._model_id}.")
+        self._put(f"{self._url}/onlineStatus", json={"status": status})
+
+    def get_revisions(self) -> list[Revision]:
+        """
+        Use this call to return a list of revisions for a specific model.
+        :return: A list of revisions for a specific model.
+        """
+        res = self._get(f"{self._url}/alm/revisions")
+        return [Revision.model_validate(e) for e in res.get("revisions", [])]
+
+    def get_latest_revision(self) -> Revision | None:
+        """
+        Use this call to return the latest revision for a specific model. The response is in the
+        same format as in Getting a list of syncable revisions between two models.
+
+        If a revision exists, the return list should contain one element only which is the
+        latest revision.
+        :return: The latest revision for a specific model, or None if no revisions exist.
+        """
+        res = (self._get(f"{self._url}/alm/latestRevision")).get("revisions")
+        return Revision.model_validate(res[0]) if res else None
+
     def get_syncable_revisions(self, source_model_id: str) -> list[Revision]:
         """
         Use this call to return the list of revisions from your source model that can be
@@ -19,48 +65,80 @@ class _AlmClient(_BaseClient):
         :param source_model_id: The ID of the source model.
         :return: A list of revisions that can be synchronized to the target model.
         """
-        return [
-            Revision.model_validate(e)
-            for e in self._get(
-                f"{self._url}/syncableRevisions?sourceModelId={source_model_id}"
-            ).get("revisions", [])
-        ]
+        res = self._get(f"{self._url}/alm/syncableRevisions?sourceModelId={source_model_id}")
+        return [Revision.model_validate(e) for e in res.get("revisions", [])]
 
-    def get_latest_revision(self) -> list[Revision]:
+    def create_revision(self, name: str, description: str) -> Revision:
         """
-        Use this call to return the latest revision for a specific model. The response is in the
-        same format as in Getting a list of syncable revisions between two models.
-
-        If a revision exists, the return list should contain one element only which is the
-        latest revision.
-        :return: The latest revision for a specific model.
+        Create a new revision for the model.
+        :param name: The name (title) of the revision.
+        :param description: The description of the revision.
+        :return: The created Revision Info.
         """
-        return [
-            Revision.model_validate(e)
-            for e in self._get(f"{self._url}/latestRevision").get("revisions", [])
-        ]
+        res = self._post(
+            f"{self._url}/alm/revisions", json={"name": name, "description": description}
+        )
+        rev = Revision.model_validate(res["revision"])
+        logger.info(f"Created revision '{name} ({rev.id})'for model {self._model_id}.")
+        return rev
 
-    def get_sync_tasks(self) -> list[SyncTask]:
+    def get_sync_tasks(self) -> list[TaskSummary]:
+        """
+        List the sync tasks for a target mode. The returned the tasks are either in progress, or
+        they completed within the last 48 hours.
+        :return: A list of sync tasks in descending order of creation time.
         """
-        Use this endpoint to return a list of sync tasks for a target model, where the tasks are
-        either in progress, or they were completed within the last 48 hours.
+        res = self._get(f"{self._url}/alm/syncTasks")
+        return [TaskSummary.model_validate(e) for e in res.get("tasks", [])]
 
-        The list is in descending order of when the tasks were created.
-        :return: A list of sync tasks for a target model.
+    def get_sync_task(self, task_id: str) -> SyncTask:
+        """
+        Get the information for a specific sync task.
+        :param task_id: The ID of the sync task.
+        :return: The sync task information.
         """
-        return [
-            SyncTask.model_validate(e) for e in self._get(f"{self._url}/syncTasks").get("tasks", [])
-        ]
+        res = self._get(f"{self._url}/alm/syncTasks/{task_id}")
+        return SyncTask.model_validate(res["task"])
 
-    def get_revisions(self) -> list[Revision]:
+    def sync_models(
+        self,
+        source_revision_id: str,
+        source_model_id: str,
+        target_revision_id: str,
+        wait_for_completion: bool = True,
+    ) -> SyncTask:
         """
-        Use this call to return a list of revisions for a specific model.
-        :return: A list of revisions for a specific model.
+        Create a synchronization task between two revisions. This will synchronize the
+        source revision of the source model to the target revision of the target model. This will
+        fail if the source revision is incompatible with the target revision.
+        :param source_revision_id: The ID of the source revision.
+        :param source_model_id: The ID of the source model.
+        :param target_revision_id: The ID of the target revision.
+        :param wait_for_completion: If True, the method will poll the task status and not return
+               until the task is complete. If False, it will spawn the task and return immediately.
+        :return: The created sync task.
         """
-        return [
-            Revision.model_validate(e)
-            for e in self._get(f"{self._url}/revisions").get("revisions", [])
-        ]
+        payload = {
+            "sourceRevisionId": source_revision_id,
+            "sourceModelId": source_model_id,
+            "targetRevisionId": target_revision_id,
+        }
+        res = self._post(f"{self._url}/alm/syncTasks", json=payload)
+        task = self.get_sync_task(res["task"]["taskId"])
+        logger.info(
+            f"Started sync task '{task.id}' from Model '{source_model_id}' "
+            f"(Revision '{source_revision_id}') to Model '{self._model_id}'."
+        )
+        if not wait_for_completion:
+            return task
+        while (task := self.get_sync_task(task.id)).task_state != "COMPLETE":
+            sleep(self.status_poll_delay)
+        if not task.result.successful:
+            msg = f"Sync task {task.id} completed with errors: {task.result.error}."
+            logger.error(msg)
+            raise AnaplanActionError(msg)
+        logger.info(f"Sync task {task.id} completed successfully.")
+        return task
 
     def get_models_for_revision(self, revision_id: str) -> list[ModelRevision]:
         """
@@ -69,9 +147,141 @@ class _AlmClient(_BaseClient):
         :param revision_id: The ID of the revision.
         :return: A list of models that had a specific revision applied to them.
         """
-        return [
-            ModelRevision.model_validate(e)
-            for e in self._get(f"{self._url}/revisions/{revision_id}/appliedToModels").get(
-                "appliedToModels", []
-            )
-        ]
+        res = self._get(f"{self._url}/alm/revisions/{revision_id}/appliedToModels")
+        return [ModelRevision.model_validate(e) for e in res.get("appliedToModels", [])]
+
+    def create_comparison_report(
+        self,
+        source_revision_id: str,
+        source_model_id: str,
+        target_revision_id: str,
+        wait_for_completion: bool = True,
+    ) -> ReportTask:
+        """
+        Generate a full comparison report between two revisions. This will list all the changes made
+        to the source revision compared to the target revision.
+        :param source_revision_id: The ID of the source revision.
+        :param source_model_id: The ID of the source model.
+        :param target_revision_id: The ID of the target revision.
+        :param wait_for_completion: If True, the method will poll the task status and not return
+               until the task is complete. If False, it will spawn the task and return immediately.
+        :return: The created report task summary.
+        """
+        payload = {
+            "sourceRevisionId": source_revision_id,
+            "sourceModelId": source_model_id,
+            "targetRevisionId": target_revision_id,
+        }
+        res = self._post(f"{self._url}/alm/comparisonReportTasks", json=payload)
+        task = self.get_comparison_report_task(res["task"]["taskId"])
+        logger.info(
+            f"Started Comparison Report task '{task.id}' between Model '{source_model_id}' "
+            f"(Revision '{source_revision_id}') and Model '{self._model_id}'."
+        )
+        if not wait_for_completion:
+            return task
+        while (task := self.get_comparison_report_task(task.id)).task_state != "COMPLETE":
+            sleep(self.status_poll_delay)
+        if not task.result.successful:
+            msg = f"Comparison Report task {task.id} completed with errors: {task.result.error}."
+            logger.error(msg)
+            raise AnaplanActionError(msg)
+        logger.info(f"Comparison Report task {task.id} completed successfully.")
+        return task
+
+    def get_comparison_report_task(self, task_id: str) -> ReportTask:
+        """
+        Get the task information for a comparison report task.
+        :param task_id: The ID of the comparison report task.
+        :return: The report task information.
+        """
+        res = self._get(f"{self._url}/alm/comparisonReportTasks/{task_id}")
+        return ReportTask.model_validate(res["task"])
+
+    def get_comparison_report(self, task: ReportTask) -> bytes:
+        """
+        Get the report for a specific task.
+        :param task: The report task object containing the task ID.
+        :return: The binary content of the comparison report.
+        """
+        return self._get_binary(
+            f"{self._url}/alm/comparisonReports/"
+            f"{task.result.target_revision_id}/{task.result.source_revision_id}"
+        )
+
+    @overload
+    def create_comparison_summary(
+        self,
+        source_revision_id: str,
+        source_model_id: str,
+        target_revision_id: str,
+        wait_for_completion: Literal[True] = True,
+    ) -> SummaryReport: ...
+
+    @overload
+    def create_comparison_summary(
+        self,
+        source_revision_id: str,
+        source_model_id: str,
+        target_revision_id: str,
+        wait_for_completion: Literal[False] = False,
+    ) -> ReportTask: ...
+
+    def create_comparison_summary(
+        self,
+        source_revision_id: str,
+        source_model_id: str,
+        target_revision_id: str,
+        wait_for_completion: bool = True,
+    ) -> ReportTask | SummaryReport:
+        """
+        Generate a comparison summary between two revisions.
+        :param source_revision_id: The ID of the source revision.
+        :param source_model_id: The ID of the source model.
+        :param target_revision_id: The ID of the target revision.
+        :param wait_for_completion: If True, the method will poll the task status and not return
+               until the task is complete. If False, it will spawn the task and return immediately.
+        :return: The created summary task or the summary report, if `wait_for_completion` is True.
+        """
+        payload = {
+            "sourceRevisionId": source_revision_id,
+            "sourceModelId": source_model_id,
+            "targetRevisionId": target_revision_id,
+        }
+        res = self._post(f"{self._url}/alm/summaryReportTasks", json=payload)
+        task = self.get_comparison_summary_task(res["task"]["taskId"])
+        logger.info(
+            f"Started Comparison Summary task '{task.id}' between Model '{source_model_id}' "
+            f"(Revision '{source_revision_id}') and Model '{self._model_id}'."
+        )
+        if not wait_for_completion:
+            return task
+        while (task := self.get_comparison_summary_task(task.id)).task_state != "COMPLETE":
+            sleep(self.status_poll_delay)
+        if not task.result.successful:
+            msg = f"Comparison Summary task {task.id} completed with errors: {task.result.error}."
+            logger.error(msg)
+            raise AnaplanActionError(msg)
+        logger.info(f"Comparison Summary task {task.id} completed successfully.")
+        return self.get_comparison_summary(task)
+
+    def get_comparison_summary_task(self, task_id: str) -> ReportTask:
+        """
+        Get the task information for a comparison summary task.
+        :param task_id: The ID of the comparison summary task.
+        :return: The report task information.
+        """
+        res = self._get(f"{self._url}/alm/summaryReportTasks/{task_id}")
+        return ReportTask.model_validate(res["task"])
+
+    def get_comparison_summary(self, task: ReportTask) -> SummaryReport:
+        """
+        Get the comparison summary for a specific task.
+        :param task: The summary task object containing the task ID.
+        :return: The binary content of the comparison summary.
+        """
+        res = self._get(
+            f"{self._url}/alm/summaryReports/"
+            f"{task.result.target_revision_id}/{task.result.source_revision_id}"
+        )
+        return SummaryReport.model_validate(res["summaryReport"])

anaplan_sdk/_clients/_audit.py

@@ -1,4 +1,4 @@
-from typing import Literal
+from typing import Any, Literal
 
 import httpx
 
@@ -15,7 +15,7 @@ class _AuditClient(_BaseClient):
         self._url = "https://audit.anaplan.com/audit/api/1/events"
         super().__init__(retry_count, client)
 
-    def list_users(self, search_pattern: str | None = None) -> list[User]:
+    def get_users(self, search_pattern: str | None = None) -> list[User]:
         """
         Lists all the Users in the authenticated users default tenant.
         :param search_pattern: Optional filter for users. When provided, case-insensitive matches
@@ -39,13 +39,15 @@ class _AuditClient(_BaseClient):
             self._get(f"https://api.anaplan.com/2/0/users/{user_id}").get("user")
         )
 
-    def get_events(self, days_into_past: int = 30, event_type: Event = "all") -> list:
+    def get_events(
+        self, days_into_past: int = 30, event_type: Event = "all"
+    ) -> list[dict[str, Any]]:
         """
         Get audit events from Anaplan Audit API.
         :param days_into_past: The nuber of days into the past to get events for. The API provides
                data for up to 30 days.
         :param event_type: The type of events to get.
-        :return: A list of audit events.
+        :return: A list of log entries, each containing a dictionary with event details.
         """
         return list(
             self._get_paginated(