anaplan-sdk 0.4.5__py3-none-any.whl → 0.5.0a1__py3-none-any.whl

anaplan_sdk/_async_clients/_transactional.py

@@ -1,27 +1,72 @@
+import logging
 from asyncio import gather
 from itertools import chain
-from typing import Any
+from typing import Any, Literal, overload
 
 import httpx
 
-from anaplan_sdk._base import _AsyncBaseClient
+from anaplan_sdk._base import (
+    _AsyncBaseClient,
+    parse_calendar_response,
+    parse_insertion_response,
+    validate_dimension_id,
+)
+from anaplan_sdk.exceptions import InvalidIdentifierException
 from anaplan_sdk.models import (
+    CurrentPeriod,
+    Dimension,
+    DimensionWithCode,
+    FiscalYear,
     InsertionResult,
     LineItem,
     List,
     ListItem,
     ListMetadata,
+    Model,
+    ModelCalendar,
     ModelStatus,
     Module,
+    View,
+    ViewInfo,
 )
+from anaplan_sdk.models._transactional import ListDeletionResult
+
+logger = logging.getLogger("anaplan_sdk")
 
 
 class _AsyncTransactionalClient(_AsyncBaseClient):
     def __init__(self, client: httpx.AsyncClient, model_id: str, retry_count: int) -> None:
         self._url = f"https://api.anaplan.com/2/0/models/{model_id}"
+        self._model_id = model_id
         super().__init__(retry_count, client)
 
-    async def list_modules(self) -> list[Module]:
+    async def get_model_details(self) -> Model:
+        """
+        Retrieves the Model details for the current Model.
+        :return: The Model details.
+        """
+        res = await self._get(self._url, params={"modelDetails": "true"})
+        return Model.model_validate(res["model"])
+
+    async def get_model_status(self) -> ModelStatus:
+        """
+        Gets the current status of the Model.
+        :return: The current status of the Model.
+        """
+        res = await self._get(f"{self._url}/status")
+        return ModelStatus.model_validate(res["requestStatus"])
+
+    async def wake_model(self) -> None:
+        """Wake up the current model."""
+        await self._post_empty(f"{self._url}/open", headers={"Content-Type": "application/text"})
+        logger.info(f"Woke up model '{self._model_id}'.")
+
+    async def close_model(self) -> None:
+        """Close the current model."""
+        await self._post_empty(f"{self._url}/close", headers={"Content-Type": "application/text"})
+        logger.info(f"Closed model '{self._model_id}'.")
+
+    async def get_modules(self) -> list[Module]:
         """
         Lists all the Modules in the Model.
         :return: The List of Modules.
@@ -31,29 +76,40 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
             for e in await self._get_paginated(f"{self._url}/modules", "modules")
         ]
 
-    async def get_model_status(self) -> ModelStatus:
+    async def get_views(self) -> list[View]:
         """
-        Gets the current status of the Model.
-        :return: The current status of the Model.
+        Lists all the Views in the Model. This will include all Modules and potentially other saved
+        views.
+        :return: The List of Views.
         """
-        return ModelStatus.model_validate(
-            (await self._get(f"{self._url}/status")).get("requestStatus")
-        )
+        params = {"includesubsidiaryviews": True}
+        return [
+            View.model_validate(e)
+            for e in await self._get_paginated(f"{self._url}/views", "views", params=params)
+        ]
 
-    async def list_line_items(self, only_module_id: int | None = None) -> list[LineItem]:
+    async def get_view_info(self, view_id: int) -> ViewInfo:
+        """
+        Gets the detailed information about a View.
+        :param view_id: The ID of the View.
+        :return: The information about the View.
+        """
+        return ViewInfo.model_validate((await self._get(f"{self._url}/views/{view_id}")))
+
+    async def get_line_items(self, only_module_id: int | None = None) -> list[LineItem]:
         """
         Lists all the Line Items in the Model.
         :param only_module_id: If provided, only Line Items from this Module will be returned.
-        :return: All Line Items on this Model.
+        :return: All Line Items on this Model or only from the specified Module.
         """
-        url = (
+        res = await self._get(
             f"{self._url}/modules/{only_module_id}/lineItems?includeAll=true"
             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 res.get("items", [])]
 
-    async def list_lists(self) -> list[List]:
+    async def get_lists(self) -> list[List]:
         """
         Lists all the Lists in the Model.
         :return: All Lists on this model.
@@ -73,18 +129,31 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
             (await self._get(f"{self._url}/lists/{list_id}")).get("metadata")
         )
 
-    async def get_list_items(self, list_id: int) -> list[ListItem]:
+    @overload
+    async def get_list_items(
+        self, list_id: int, return_raw: Literal[False] = False
+    ) -> list[ListItem]: ...
+
+    @overload
+    async def get_list_items(
+        self, list_id: int, return_raw: Literal[True] = True
+    ) -> list[dict[str, Any]]: ...
+
+    async def get_list_items(
+        self, list_id: int, return_raw: bool = False
+    ) -> list[ListItem] | list[dict[str, Any]]:
         """
         Gets all the items in a List.
         :param list_id: The ID of the List.
+        :param return_raw: If True, returns the items as a list of dictionaries instead of ListItem
+               objects. If you use the result of this call in a DataFrame or you simply pass on the
+               data, you will want to set this to avoid unnecessary (de-)serialization.
         :return: All items in the List.
         """
-        return [
-            ListItem.model_validate(e)
-            for e in (await self._get(f"{self._url}/lists/{list_id}/items?includeAll=true")).get(
-                "listItems"
-            )
-        ]
+        res = await self._get(f"{self._url}/lists/{list_id}/items?includeAll=true")
+        if return_raw:
+            return res.get("listItems", [])
+        return [ListItem.model_validate(e) for e in res.get("listItems", [])]
 
     async def insert_list_items(
         self, list_id: int, items: list[dict[str, str | int | dict]]
@@ -106,30 +175,29 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         :return: The result of the insertion, indicating how many items were added,
                  ignored or failed.
         """
+        if not items:
+            return InsertionResult(added=0, ignored=0, failures=[], total=0)
         if len(items) <= 100_000:
-            return InsertionResult.model_validate(
+            result = InsertionResult.model_validate(
                 await self._post(
                     f"{self._url}/lists/{list_id}/items?action=add", json={"items": items}
                 )
             )
+            logger.info(f"Inserted {result.added} items into list '{list_id}'.")
+            return result
         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)
-
-        return InsertionResult(
-            added=added, ignored=ignored, total=total, failures=list(chain.from_iterable(failures))
-        )
+        result = parse_insertion_response(responses)
+        logger.info(f"Inserted {result.added} items into list '{list_id}'.")
+        return result
 
-    async def delete_list_items(self, list_id: int, items: list[dict[str, str | int]]) -> int:
+    async def delete_list_items(
+        self, list_id: int, items: list[dict[str, str | int]]
+    ) -> ListDeletionResult:
         """
         Deletes items from a List. If you pass a long list, it will be split into chunks of 100,000
         items, the maximum allowed by the API.
@@ -143,14 +211,18 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
 
         :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.
+                      as the keys to identify the records to delete. Specifying both will error.
+        :return: The result of the deletion, indicating how many items were deleted or failed.
         """
+        if not items:
+            return ListDeletionResult(deleted=0, failures=[])
         if len(items) <= 100_000:
-            return (
-                await self._post(
-                    f"{self._url}/lists/{list_id}/items?action=delete", json={"items": items}
-                )
-            ).get("deleted", 0)
+            res = await self._post(
+                f"{self._url}/lists/{list_id}/items?action=delete", json={"items": items}
+            )
+            info = ListDeletionResult.model_validate(res)
+            logger.info(f"Deleted {info.deleted} items from list '{list_id}'.")
+            return info
 
         responses = await gather(
             *(
@@ -160,7 +232,12 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
                 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)
+        info = ListDeletionResult(
+            deleted=sum(res.get("deleted", 0) for res in responses),
+            failures=list(chain.from_iterable(res.get("failures", []) for res in responses)),
+        )
+        logger.info(f"Deleted {info} items from list '{list_id}'.")
+        return info
 
     async def reset_list_index(self, list_id: int) -> None:
         """
@@ -168,6 +245,7 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         :param list_id: The ID of the List.
         """
         await self._post_empty(f"{self._url}/lists/{list_id}/resetIndex")
+        logger.info(f"Reset index for list '{list_id}'.")
 
     async def update_module_data(
         self, module_id: int, data: list[dict[str, Any]]
@@ -187,4 +265,117 @@ class _AsyncTransactionalClient(_AsyncBaseClient):
         :return: The number of cells changed or the response with the according error details.
         """
         res = await self._post(f"{self._url}/modules/{module_id}/data", json=data)
+        if "failures" not in res:
+            logger.info(f"Updated {res['numberOfCellsChanged']} cells in module '{module_id}'.")
         return res if "failures" in res else res["numberOfCellsChanged"]
+
+    async def get_current_period(self) -> CurrentPeriod:
+        """
+        Gets the current period of the model.
+        :return: The current period of the model.
+        """
+        res = await self._get(f"{self._url}/currentPeriod")
+        return CurrentPeriod.model_validate(res["currentPeriod"])
+
+    async def set_current_period(self, date: str) -> CurrentPeriod:
+        """
+        Sets the current period of the model to the given date.
+        :param date: The date to set the current period to, in the format 'YYYY-MM-DD'.
+        :return: The updated current period of the model.
+        """
+        res = await self._put(f"{self._url}/currentPeriod", {"date": date})
+        logger.info(f"Set current period to '{date}'.")
+        return CurrentPeriod.model_validate(res["currentPeriod"])
+
+    async def set_current_fiscal_year(self, year: str) -> FiscalYear:
+        """
+        Sets the current fiscal year of the model.
+        :param year: The fiscal year to set, in the format specified in the model, e.g. FY24.
+        :return: The updated fiscal year of the model.
+        """
+        res = await self._put(f"{self._url}/modelCalendar/fiscalYear", {"year": year})
+        logger.info(f"Set current fiscal year to '{year}'.")
+        return FiscalYear.model_validate(res["modelCalendar"]["fiscalYear"])
+
+    async def get_model_calendar(self) -> ModelCalendar:
+        """
+        Get the calendar settings of the model.
+        :return: The calendar settings of the model.
+        """
+        return parse_calendar_response(await self._get(f"{self._url}/modelCalendar"))
+
+    async def get_dimension_items(self, dimension_id: int) -> list[DimensionWithCode]:
+        """
+        Get all items in a dimension. This will fail if the dimensions holds more than 1_000_000
+        items. Valid Dimensions are:
+
+        - Lists (101xxxxxxxxx)
+        - List Subsets (109xxxxxxxxx)
+        - Line Item Subsets (114xxxxxxxxx)
+        - Users (101999999999)
+        For lists and users, you should prefer using the `get_list_items` and `get_users` methods,
+        respectively, instead.
+        :param dimension_id: The ID of the dimension to list items for.
+        :return: A list of Dimension items.
+        """
+        res = await self._get(f"{self._url}/dimensions/{validate_dimension_id(dimension_id)}/items")
+        return [DimensionWithCode.model_validate(e) for e in res.get("items", [])]
+
+    async def lookup_dimension_items(
+        self, dimension_id: int, codes: list[str] = None, names: list[str] = None
+    ) -> list[DimensionWithCode]:
+        """
+        Looks up items in a dimension by their codes or names. If both are provided, both will be
+        searched for. You must provide at least one of `codes` or `names`. Valid Dimensions to
+        lookup are:
+
+        - Lists (101xxxxxxxxx)
+        - Time (20000000003)
+        - Version (20000000020)
+        - Users (101999999999)
+        :param dimension_id: The ID of the dimension to lookup items for.
+        :param codes: A list of codes to lookup in the dimension.
+        :param names: A list of names to lookup in the dimension.
+        :return: A list of Dimension items that match the provided codes or names.
+        """
+        if not codes and not names:
+            raise ValueError("At least one of 'codes' or 'names' must be provided.")
+        if not (
+            dimension_id == 101999999999
+            or 101_000_000_000 <= dimension_id < 102_000_000_000
+            or dimension_id == 20000000003
+            or dimension_id == 20000000020
+        ):
+            raise InvalidIdentifierException(
+                "Invalid dimension_id. Must be a List (101xxxxxxxxx), Time (20000000003), "
+                "Version (20000000020), or Users (101999999999)."
+            )
+        res = await self._post(
+            f"{self._url}/dimensions/{dimension_id}/items", json={"codes": codes, "names": names}
+        )
+        return [DimensionWithCode.model_validate(e) for e in res.get("items", [])]
+
+    async def get_view_dimension_items(self, view_id: int, dimension_id: int) -> list[Dimension]:
+        """
+        Get the members of a dimension that are part of the given View. This call returns data as
+        filtered by the page builder when they configure the view. This call respects hidden items,
+        filtering selections, and Selective Access. If the view contains hidden or filtered items,
+        these do not display in the response. This will fail if the dimensions holds more than
+        1_000_000 items. The response returns Items within a flat list (no hierarchy) and order
+        is not guaranteed.
+        :param view_id: The ID of the View.
+        :param dimension_id: The ID of the Dimension to get items for.
+        :return: A list of Dimensions used in the View.
+        """
+        res = await self._get(f"{self._url}/views/{view_id}/dimensions/{dimension_id}/items")
+        return [Dimension.model_validate(e) for e in res.get("items", [])]
+
+    async def get_line_item_dimensions(self, line_item_id: int) -> list[Dimension]:
+        """
+        Get the dimensions of a Line Item. This will return all dimensions that are used in the
+        Line Item.
+        :param line_item_id: The ID of the Line Item.
+        :return: A list of Dimensions used in the Line Item.
+        """
+        res = await self._get(f"{self._url}/lineItems/{line_item_id}/dimensions")
+        return [Dimension.model_validate(e) for e in res.get("dimensions", [])]

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