anaplan-sdk 0.3.1__py3-none-any.whl → 0.4.0a1__py3-none-any.whl

anaplan_sdk/_clients/_cloud_works.py

@@ -0,0 +1,342 @@
+from typing import Any, Literal
+
+import httpx
+
+from anaplan_sdk._base import (
+    _BaseClient,
+    connection_body_payload,
+    construct_payload,
+    integration_payload,
+    schedule_payload,
+)
+from anaplan_sdk.models.cloud_works import (
+    Connection,
+    ConnectionBody,
+    ConnectionInput,
+    Integration,
+    IntegrationInput,
+    IntegrationProcessInput,
+    NotificationConfig,
+    NotificationInput,
+    RunError,
+    RunStatus,
+    RunSummary,
+    ScheduleInput,
+    SingleIntegration,
+)
+
+from ._cw_flow import _FlowClient
+
+
+class _CloudWorksClient(_BaseClient):
+    def __init__(self, client: httpx.Client, retry_count: int) -> None:
+        self._url = "https://api.cloudworks.anaplan.com/2/0/integrations"
+        self._flow = _FlowClient(client, retry_count)
+        super().__init__(retry_count, client)
+
+    @property
+    def flows(self) -> _FlowClient:
+        """
+        Access the Integration Flow APIs.
+        """
+        return self._flow
+
+    def list_connections(self) -> list[Connection]:
+        """
+        List all Connections available in CloudWorks.
+        :return: A list of connections.
+        """
+        return [
+            Connection.model_validate(e)
+            for e in self._get_paginated(f"{self._url}/connections", "connections")
+        ]
+
+    def create_connection(self, con_info: ConnectionInput | dict[str, Any]) -> str:
+        """
+        Create a new connection in CloudWorks.
+        :param con_info: The connection information. This can be a ConnectionInput instance or a
+               dictionary as per the documentation. If a dictionary is passed, it will be validated
+               against the ConnectionInput model before sending the request.
+        :return: The ID of the new connection.
+        """
+        res = self._post(
+            f"{self._url}/connections", json=construct_payload(ConnectionInput, con_info)
+        )
+        return res["connections"]["connectionId"]
+
+    def update_connection(self, con_id: str, con_info: ConnectionBody | dict[str, Any]) -> None:
+        """
+        Update an existing connection in CloudWorks.
+        :param con_id: The ID of the connection to update.
+        :param con_info: The name and details of the connection. You must pass all the same details
+               as when initially creating the connection again. If you want to update only some of
+               the details, use the `patch_connection` method instead.
+        """
+        self._put(f"{self._url}/connections/{con_id}", json=connection_body_payload(con_info))
+
+    def patch_connection(self, con_id: str, body: dict[str, Any]) -> None:
+        """
+        Update an existing connection in CloudWorks.
+        :param con_id: The ID of the connection to update.
+        :param body: The name and details of the connection. You can pass all the same details as
+               when initially creating the connection again, or just any one of them.
+        """
+        self._patch(f"{self._url}/connections/{con_id}", json=body)
+
+    def delete_connection(self, con_id: str) -> None:
+        """
+        Delete an existing connection in CloudWorks.
+        :param con_id: The ID of the connection to delete.
+        """
+        self._delete(f"{self._url}/connections/{con_id}")
+
+    def list_integrations(
+        self, sort_by_name: Literal["ascending", "descending"] = "ascending"
+    ) -> list[Integration]:
+        """
+        List all integrations in CloudWorks.
+        :param sort_by_name: Sort the integrations by name in ascending or descending order.
+        :return: A list of integrations.
+        """
+        params = {"sortBy": "name" if sort_by_name == "ascending" else "-name"}
+        return [
+            Integration.model_validate(e)
+            for e in self._get_paginated(f"{self._url}", "integrations", params=params)
+        ]
+
+    def get_integration(self, integration_id: str) -> SingleIntegration:
+        """
+        Get the details of a specific integration in CloudWorks.
+
+        **Note: This will not include the integration type! While present when listing integrations,
+        the integration type is not included in the details of a single integration.**
+        :param integration_id: The ID of the integration to retrieve.
+        :return: The details of the integration, without the integration type.
+        """
+        return SingleIntegration.model_validate(
+            (self._get(f"{self._url}/{integration_id}"))["integration"]
+        )
+
+    def create_integration(
+        self, body: IntegrationInput | IntegrationProcessInput | dict[str, Any]
+    ) -> str:
+        """
+        Create a new integration in CloudWorks. If not specified, the integration type will be
+        either "Import" or "Export" based on the source and target you provide.
+
+        If you want to instead create a process Integration, you can do so by specifying
+        the `process_id` parameter and passing several jobs. **Be careful to ensure, that all ids
+        specified in the job inputs match what is defined in your model and matches the process.**
+        If this is not the case, this will error, occasionally with a misleading error message,
+        i.e. `XYZ is not defined in your model` even though it is, Anaplan just does not know what
+        to do with it in the location you specified.
+
+        You can also use CloudWorks Integrations to simply schedule a process. To do this, you
+        can simply pass an IntegrationProcessInput instance with the process_id and no jobs. This
+        will create a process integration that will run the process you specified.
+        :param body: The integration information. This can be an
+               IntegrationInput | IntegrationProcessInput instance or a dictionary as per the
+               documentation. If a dictionary is passed, it will be validated against the
+               IntegrationInput model before sending the request.
+        :return: The ID of the new integration.
+        """
+        json = integration_payload(body)
+        return (self._post(f"{self._url}", json=json))["integration"]["integrationId"]
+
+    def update_integration(
+        self, integration_id: str, body: IntegrationInput | IntegrationProcessInput | dict[str, Any]
+    ) -> None:
+        """
+        Update an existing integration in CloudWorks.
+        :param integration_id: The ID of the integration to update.
+        :param body: The name and details of the integration. You must pass all the same details
+               as when initially creating the integration again. If you want to update only some
+               of the details, use the `patch_integration` method instead.
+        """
+        json = integration_payload(body)
+        self._put(f"{self._url}/{integration_id}", json=json)
+
+    def run_integration(self, integration_id: str) -> str:
+        """
+        Run an integration in CloudWorks.
+        :param integration_id: The ID of the integration to run.
+        :return: The ID of the run instance.
+        """
+        return (self._post_empty(f"{self._url}/{integration_id}/run"))["run"]["id"]
+
+    def delete_integration(self, integration_id: str) -> None:
+        """
+        Delete an existing integration in CloudWorks.
+        :param integration_id: The ID of the integration to delete.
+        """
+        self._delete(f"{self._url}/{integration_id}")
+
+    def get_run_history(self, integration_id: str) -> list[RunSummary]:
+        """
+        Get the run history of a specific integration in CloudWorks.
+        :param integration_id: The ID of the integration to retrieve the run history for.
+        :return: A list of run statuses.
+        """
+        return [
+            RunSummary.model_validate(e)
+            for e in (self._get(f"{self._url}/runs/{integration_id}"))["history_of_runs"].get(
+                "runs", []
+            )
+        ]
+
+    def get_run_status(self, run_id: str) -> RunStatus:
+        """
+        Get the status of a specific run in CloudWorks.
+        :param run_id: The ID of the run to retrieve.
+        :return: The details of the run.
+        """
+        return RunStatus.model_validate((self._get(f"{self._url}/run/{run_id}"))["run"])
+
+    def get_run_error(self, run_id: str) -> RunError | None:
+        """
+        Get the error details of a specific run in CloudWorks. This exposes potential underlying
+        errors like the error of the invoked action, failure dumps and other details.
+        :param run_id: The ID of the run to retrieve.
+        :return: The details of the run error.
+        """
+        run = self._get(f"{self._url}/runerror/{run_id}")
+        return RunError.model_validate(run["runs"]) if run.get("runs") else None
+
+    def create_schedule(
+        self, integration_id: str, schedule: ScheduleInput | dict[str, Any]
+    ) -> None:
+        """
+        Schedule an integration in CloudWorks.
+        :param integration_id: The ID of the integration to schedule.
+        :param schedule: The schedule information. This can be a ScheduleInput instance or a
+               dictionary as per the documentation. If a dictionary is passed, it will be validated
+               against the ScheduleInput model before sending the request.
+        """
+        self._post(
+            f"{self._url}/{integration_id}/schedule",
+            json=schedule_payload(integration_id, schedule),
+        )
+
+    def update_schedule(
+        self, integration_id: str, schedule: ScheduleInput | dict[str, Any]
+    ) -> None:
+        """
+        Update an integration Schedule in CloudWorks. A schedule must already exist.
+        :param integration_id: The ID of the integration to schedule.
+        :param schedule: The schedule information. This can be a ScheduleInput instance or a
+               dictionary as per the documentation. If a dictionary is passed, it will be validated
+               against the ScheduleInput model before sending the request.
+        """
+        self._put(
+            f"{self._url}/{integration_id}/schedule",
+            json=schedule_payload(integration_id, schedule),
+        )
+
+    def set_schedule_status(
+        self, integration_id: str, status: Literal["enabled", "disabled"]
+    ) -> None:
+        """
+        Set the status of an integration schedule in CloudWorks. A schedule must already exist.
+        :param integration_id: The ID of the integration to schedule.
+        :param status: The status of the schedule. This can be either "enabled" or "disabled".
+        """
+        self._post_empty(f"{self._url}/{integration_id}/schedule/status/{status}")
+
+    def delete_schedule(self, integration_id: str) -> None:
+        """
+        Delete an integration schedule in CloudWorks. A schedule must already exist.
+        :param integration_id: The ID of the integration to schedule.
+        """
+        self._delete(f"{self._url}/{integration_id}/schedule")
+
+    def get_notification_config(
+        self, notification_id: str | None = None, integration_id: str | None = None
+    ) -> NotificationConfig:
+        """
+        Get the notification configuration, either by its Id, or the notification configuration
+        for a specific integration. If the integration_id is specified, the notification_id
+        will be ignored.
+        :param notification_id: The ID of the notification configuration to retrieve.
+        :param integration_id: The ID of the integration to retrieve the notification
+               configuration for.
+        :return: The details of the notification configuration.
+        """
+        if not (notification_id or integration_id):
+            raise ValueError("Either notification_id or integration_id must be specified.")
+        if integration_id:
+            notification_id = (self.get_integration(integration_id)).notification_id
+        return NotificationConfig.model_validate(
+            (self._get(f"{self._url}/notification/{notification_id}"))["notifications"]
+        )
+
+    def create_notification_config(self, config: NotificationInput | dict[str, Any]) -> str:
+        """
+        Create a notification configuration for an integration in CloudWorks. This will error if
+        there is already a notification configuration for the integration, which is also the case
+        by default. In this case, you will want to use the `update_notification_config` method
+        instead, to partially update the existing configuration or overwrite it.
+        :param config: The notification configuration. This can be a NotificationInput instance or
+               a dictionary as per the documentation. If a dictionary is passed, it will be
+               validated against the NotificationConfig model before sending the request.
+        :return: The ID of the new notification configuration.
+        """
+        res = self._post(
+            f"{self._url}/notification", json=construct_payload(NotificationInput, config)
+        )
+        return res["notification"]["notificationId"]
+
+    def update_notification_config(
+        self, notification_id: str, config: NotificationInput | dict[str, Any]
+    ) -> None:
+        """
+        Update a notification configuration for an integration in CloudWorks. You cannot pass empty
+        values or nulls to any of the fields If you want to for e.g. override  an existing list of
+        users with an empty one, you must delete the notification configuration and create a new
+        one with only the values you want to keep.
+        :param notification_id: The ID of the notification configuration to update.
+        :param config: The notification configuration. This can be a NotificationInput instance or
+               a dictionary as per the documentation. If a dictionary is passed, it will be
+               validated against the NotificationConfig model before sending the request.
+        """
+        self._put(
+            f"{self._url}/notification/{notification_id}",
+            json=construct_payload(NotificationInput, config),
+        )
+
+    def delete_notification_config(
+        self, notification_id: str | None = None, integration_id: str | None = None
+    ) -> None:
+        """
+        Delete a notification configuration for an integration in CloudWorks, either by its Id, or
+        the notification configuration for a specific integration. If the integration_id is
+        specified, the notification_id will be ignored.
+        :param notification_id: The ID of the notification configuration to delete.
+        :param integration_id: The ID of the integration to delete the notification config of.
+        """
+        if not (notification_id or integration_id):
+            raise ValueError("Either notification_id or integration_id must be specified.")
+        if integration_id:
+            notification_id = (self.get_integration(integration_id)).notification_id
+        self._delete(f"{self._url}/notification/{notification_id}")
+
+    def get_import_error_dump(self, run_id: str) -> bytes:
+        """
+        Get the error dump of a specific import run in CloudWorks. Calling this for a run_id that
+        did not generate any failure dumps will produce an error.
+
+        **Note that if you need the error dump of an action in a process, you must use the
+        `get_process_error_dump` method instead.**
+        :param run_id: The ID of the run to retrieve.
+        :return: The error dump.
+        """
+        return self._get_binary(f"{self._url}/run/{run_id}/dump")
+
+    def get_process_error_dump(self, run_id: str, action_id: int | str) -> bytes:
+        """
+        Get the error dump of a specific import run in CloudWorks, that is part of a process.
+        Calling this for a run_id that did not generate any failure dumps will produce an error.
+        :param run_id: The ID of the run to retrieve.
+        :param action_id: The ID of the action to retrieve. This can be found in the RunError.
+        :return: The error dump.
+        """
+        return self._get_binary(f"{self._url}/run/{run_id}/process/import/{action_id}/dumps")

anaplan_sdk/_clients/_cw_flow.py

@@ -0,0 +1,78 @@
+from typing import Any
+
+import httpx
+
+from anaplan_sdk._base import _BaseClient, construct_payload
+from anaplan_sdk.models.flows import Flow, FlowInput, FlowSummary
+
+
+class _FlowClient(_BaseClient):
+    def __init__(self, client: httpx.Client, retry_count: int) -> None:
+        self._url = "https://api.cloudworks.anaplan.com/2/0/integrationflows"
+        super().__init__(retry_count, client)
+
+    def list_flows(self, current_user_only: bool = False) -> list[FlowSummary]:
+        """
+        List all flows in CloudWorks.
+        :param current_user_only: Filters the flows to only those created by the current user.
+        :return: A list of FlowSummaries.
+        """
+        params = {"myIntegrations": 1 if current_user_only else 0}
+        return [
+            FlowSummary.model_validate(e)
+            for e in self._get_paginated(self._url, "integrationFlows", page_size=25, params=params)
+        ]
+
+    def get_flow(self, flow_id: str) -> Flow:
+        """
+        Get a flow by its ID. This returns the full flow object, including the contained steps and
+        continuation behavior.
+        :param flow_id: The ID of the flow to get.
+        :return: The Flow object.
+        """
+        return Flow.model_validate((self._get(f"{self._url}/{flow_id}"))["integrationFlow"])
+
+    def run_flow(self, flow_id: str, only_steps: list[str] = None) -> str:
+        """
+        Run a flow by its ID. Make sure that neither the flow nor any of its contained are running.
+        If this is the case, the task will error. Anaplan neither schedules these tasks nor can it
+        handle concurrent executions.
+        :param flow_id: The ID of the flow to run.
+        :param only_steps: A list of step IDs to run. If not provided, only these will be run.
+        :return: The ID of the run.
+        """
+        url = f"{self._url}/{flow_id}/run"
+        res = (
+            self._post(url, json={"stepsToRun": only_steps})
+            if only_steps
+            else self._post_empty(url)
+        )
+        return res["run"]["id"]
+
+    def create_flow(self, flow: FlowInput | dict[str, Any]) -> str:
+        """
+        Create a new flow in CloudWorks. Be careful not to omit the `depends_on` field. Anaplan
+        will accept these values, but an invalid, corrupted flow will be created, as all Flows must
+        have at least 2 Steps, and they must always be sequential
+        :param flow: The flow to create. This can be a FlowInput object or a dictionary.
+        :return: The ID of the created flow.
+        """
+        res = self._post(self._url, json=construct_payload(FlowInput, flow))
+        return res["integrationFlow"]["integrationFlowId"]
+
+    def update_flow(self, flow_id: str, flow: FlowInput | dict[str, Any]) -> None:
+        """
+        Update a flow in CloudWorks. You must provide the full flow object, partial updates are not
+        supported.
+        :param flow_id: The ID of the flow to update.
+        :param flow: The flow to update. This can be a FlowInput object or a dictionary.
+        """
+        self._put(f"{self._url}/{flow_id}", json=construct_payload(FlowInput, flow))
+
+    def delete_flow(self, flow_id: str) -> None:
+        """
+        Delete a flow in CloudWorks. This will not delete its contained steps. This will fail if
+        the flow is running or if it has any running steps.
+        :param flow_id: The ID of the flow to delete.
+        """
+        self._delete(f"{self._url}/{flow_id}")

anaplan_sdk/_clients/_transactional.py

@@ -19,7 +19,6 @@ from anaplan_sdk.models import (
 
 class _TransactionalClient(_BaseClient):
     def __init__(self, client: httpx.Client, model_id: str, retry_count: int) -> None:
-        self._client = client
         self._url = f"https://api.anaplan.com/2/0/models/{model_id}"
         super().__init__(retry_count, client)
 

anaplan_sdk/models/__init__.py

@@ -0,0 +1,49 @@
+from ._alm import ModelRevision, Revision, SyncTask
+from ._base import AnaplanModel
+from ._bulk import (
+    Action,
+    Export,
+    ExportTypes,
+    File,
+    Import,
+    ImportTypes,
+    List,
+    ListMetadata,
+    Model,
+    Process,
+    TaskResult,
+    TaskResultDetail,
+    TaskStatus,
+    TaskSummary,
+    Workspace,
+)
+from ._transactional import Failure, InsertionResult, LineItem, ListItem, ModelStatus, Module, User
+
+__all__ = [
+    "AnaplanModel",
+    "ExportTypes",
+    "ImportTypes",
+    "Workspace",
+    "Model",
+    "ModelStatus",
+    "ModelRevision",
+    "File",
+    "List",
+    "ListItem",
+    "ListMetadata",
+    "Action",
+    "Import",
+    "Export",
+    "Process",
+    "Module",
+    "LineItem",
+    "TaskSummary",
+    "TaskResult",
+    "TaskResultDetail",
+    "TaskStatus",
+    "SyncTask",
+    "User",
+    "Failure",
+    "InsertionResult",
+    "Revision",
+]

anaplan_sdk/models/_alm.py

@@ -0,0 +1,55 @@
+from pydantic import Field
+
+from ._base import AnaplanModel
+
+
+class Revision(AnaplanModel):
+    id: str = Field(description="The unique identifier of this revision.")
+    name: str = Field(description="The name of this revision.")
+    description: str | None = Field(
+        None, description="The description of this revision. Not always present."
+    )
+    created_on: str = Field(description="The creation date of this revision in ISO format.")
+    created_by: str = Field(
+        description="The unique identifier of the user who created this revision."
+    )
+    creation_method: str = Field(description="The creation method of this revision.")
+    applied_on: str = Field(description="The application date of this revision in ISO format.")
+    applied_by: str = Field(
+        description="The unique identifier of the user who applied this revision."
+    )
+
+
+class ModelRevision(AnaplanModel):
+    id: str = Field(
+        validation_alias="modelId",
+        description="The unique identifier of the model this revision belongs to.",
+    )
+    name: str = Field(
+        default="",
+        validation_alias="modelName",
+        description=(
+            "The name of the model this revision belongs to. This can be an empty string, when the "
+            "calling user does not have access to the model, but is workspace admin in the "
+            "workspace."
+        ),
+    )
+    workspace_id: str = Field(
+        description="The unique identifier of the workspace this revision belongs to."
+    )
+    applied_by: str = Field(
+        description="The unique identifier of the user who applied this revision."
+    )
+    applied_on: str = Field(description="The application date of this revision in ISO format.")
+    applied_method: str = Field(description="The application method of this revision.")
+    deleted: bool | None = Field(
+        None,
+        validation_alias="modelDeleted",
+        description="Whether the model has been deleted or not.",
+    )
+
+
+class SyncTask(AnaplanModel):
+    id: str = Field(validation_alias="taskId", description="The unique identifier of this task.")
+    task_state: str = Field(description="The state of this task.")
+    creation_time: int = Field(description="The creation time of this task.")

anaplan_sdk/models/_base.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, ConfigDict, field_serializer
+from pydantic.alias_generators import to_camel
+
+
+class AnaplanModel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    @field_serializer(
+        "action_id",
+        "file_id",
+        "process_id",
+        "id",
+        when_used="unless-none",
+        check_fields=False,
+    )  # While these are of type int, they are serialized as strings in the API payloads
+    def str_serializer(self, v: int) -> str:
+        return str(v)