digitalai_release_sdk 26.3.0b1__tar.gz

digitalai_release_sdk-26.3.0b1/.gitignore

@@ -0,0 +1,22 @@
+# IDE
+.idea/
+
+# Python
+*.py[cod]
+__pycache__/
+
+# Venv
+.venv/
+venv
+
+# System
+.DS_Store
+
+# Pip
+*.egg-info
+dist/
+requirements.txt
+
+# Testing
+.pytest_cache/
+.coverage

digitalai_release_sdk-26.3.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digital.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

digitalai_release_sdk-26.3.0b1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: digitalai_release_sdk
+Version: 26.3.0b1
+Summary: Digital.ai Release SDK
+Project-URL: Homepage, https://digital.ai/
+Project-URL: Documentation, https://docs.digital.ai/release/docs/category/python-sdk
+Author-email: "Digital.ai" <pypi-devops@digital.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: dataclasses-json<1.0.0,>=0.6.7
+Requires-Dist: kubernetes<36.0.0,>=35.0.0
+Requires-Dist: pycryptodomex<4.0.0,>=3.23.0
+Requires-Dist: python-dateutil<3.0.0,>=2.9.0
+Requires-Dist: requests<3.0.0,>=2.32.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Digital.ai Release Python SDK
+
+The **Digital.ai Release Python SDK** (`digitalai-release-sdk`) provides a set of tools for developers to create container-based integration with Digital.ai Release. It simplifies integration creation by offering built-in functions to interact with the execution environment.
+
+## Features
+- Define custom tasks using the `BaseTask` abstract class.
+- Easily manage input and output properties.
+- Interact with the Digital.ai Release environment seamlessly.
+- Simplified API client for efficient communication with Release API, with support for username/password or personal access token authentication.
+- Built-in helpers to resolve Release entity IDs (release, phase, task, and folder).
+
+
+## Installation
+Install the SDK using `pip`:
+
+```sh
+pip install digitalai-release-sdk
+```
+
+## Getting Started
+
+### Example Task: `hello.py`
+
+The following example demonstrates how to create a simple task using the SDK:
+
+```python
+from digitalai.release.integration import BaseTask
+
+class Hello(BaseTask):
+    
+    def execute(self) -> None:
+        # Get the name from the input
+        name = self.input_properties.get('yourName')
+        if not name:
+            raise ValueError("The 'yourName' field cannot be empty")
+
+        # Create greeting message
+        greeting = f"Hello {name}"
+
+        # Add greeting to the task's comment section in the UI
+        self.add_comment(greeting)
+
+        # Store greeting as an output property
+        self.set_output_property('greeting', greeting)
+```
+
+## Changelog
+
+### Version 26.3.0 (Beta)
+
+#### 🚀 Features
+
+- `get_release_api_client()` now supports optional credentials/server URL and `requests` library arguments.
+- Added `get_phase_id()` and `get_folder_id()` helper methods to `BaseTask`.
+
+#### 🛠️ Enhancements
+
+- Improved stability and error handling for API requests and Kubernetes tasks.
+
+---
+
+## 🔗 Related Resources
+
+- 🧪 **Python Template Project**: [release-integration-template-python](https://github.com/digital-ai/release-integration-template-python)  
+  A starting point for building custom integrations using Digital.ai Release and Python.
+
+- 📘 **Official Documentation**: [Digital.ai Release Python SDK Docs](https://docs.digital.ai/release/docs/category/python-sdk)  
+  Comprehensive guide to using the Python SDK and building custom tasks.
+
+- 📦 **Digital.ai Release Python SDK**: [digitalai-release-sdk on PyPI](https://pypi.org/project/digitalai-release-sdk/)  
+  The official SDK package for integrating with Digital.ai Release.
+
+

digitalai_release_sdk-26.3.0b1/README.md

@@ -0,0 +1,73 @@
+# Digital.ai Release Python SDK
+
+The **Digital.ai Release Python SDK** (`digitalai-release-sdk`) provides a set of tools for developers to create container-based integration with Digital.ai Release. It simplifies integration creation by offering built-in functions to interact with the execution environment.
+
+## Features
+- Define custom tasks using the `BaseTask` abstract class.
+- Easily manage input and output properties.
+- Interact with the Digital.ai Release environment seamlessly.
+- Simplified API client for efficient communication with Release API, with support for username/password or personal access token authentication.
+- Built-in helpers to resolve Release entity IDs (release, phase, task, and folder).
+
+
+## Installation
+Install the SDK using `pip`:
+
+```sh
+pip install digitalai-release-sdk
+```
+
+## Getting Started
+
+### Example Task: `hello.py`
+
+The following example demonstrates how to create a simple task using the SDK:
+
+```python
+from digitalai.release.integration import BaseTask
+
+class Hello(BaseTask):
+    
+    def execute(self) -> None:
+        # Get the name from the input
+        name = self.input_properties.get('yourName')
+        if not name:
+            raise ValueError("The 'yourName' field cannot be empty")
+
+        # Create greeting message
+        greeting = f"Hello {name}"
+
+        # Add greeting to the task's comment section in the UI
+        self.add_comment(greeting)
+
+        # Store greeting as an output property
+        self.set_output_property('greeting', greeting)
+```
+
+## Changelog
+
+### Version 26.3.0 (Beta)
+
+#### 🚀 Features
+
+- `get_release_api_client()` now supports optional credentials/server URL and `requests` library arguments.
+- Added `get_phase_id()` and `get_folder_id()` helper methods to `BaseTask`.
+
+#### 🛠️ Enhancements
+
+- Improved stability and error handling for API requests and Kubernetes tasks.
+
+---
+
+## 🔗 Related Resources
+
+- 🧪 **Python Template Project**: [release-integration-template-python](https://github.com/digital-ai/release-integration-template-python)  
+  A starting point for building custom integrations using Digital.ai Release and Python.
+
+- 📘 **Official Documentation**: [Digital.ai Release Python SDK Docs](https://docs.digital.ai/release/docs/category/python-sdk)  
+  Comprehensive guide to using the Python SDK and building custom tasks.
+
+- 📦 **Digital.ai Release Python SDK**: [digitalai-release-sdk on PyPI](https://pypi.org/project/digitalai-release-sdk/)  
+  The official SDK package for integrating with Digital.ai Release.
+
+

digitalai_release_sdk-26.3.0b1/digitalai/release/integration/__init__.py

@@ -0,0 +1,6 @@
+from .base_task import BaseTask
+from .input_context import InputContext
+from .output_context import OutputContext
+from .exceptions import AbortException
+from .reporting_records import BuildRecord, PlanRecord, ItsmRecord,CodeComplianceRecord, DeploymentRecord
+from .logger import dai_logger

digitalai_release_sdk-26.3.0b1/digitalai/release/integration/base_task.py

@@ -0,0 +1,219 @@
+import sys
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+from .input_context import AutomatedTaskAsUserContext
+from .output_context import OutputContext
+from .exceptions import AbortException
+from .ids import Ids
+from .logger import dai_logger
+from digitalai.release.release_api_client import ReleaseAPIClient
+
+
+class BaseTask(ABC):
+    """
+    An abstract base class representing a task that can be executed.
+    """
+
+    def __init__(self):
+        self.task_id = None
+        self.release_context = None
+        self.release_server_url = None
+        self.input_properties = None
+        self.output_context = None
+
+    def execute_task(self) -> None:
+        """
+        Executes the task by calling the execute method. If an AbortException is raised during execution,
+        the task's exit code is set to 1 and the program exits with a status code of 1. If any other exception
+        is raised, the task's exit code is also set to 1.
+        """
+        try:
+            self.output_context = OutputContext(0, "", {}, [])
+            self.execute()
+        except AbortException:
+            dai_logger.info("Abort requested")
+            self.set_exit_code(1)
+            self.set_error_message("Abort requested")
+            sys.exit(1)
+        except Exception as e:
+            dai_logger.error("Unexpected error occurred", exc_info=True)
+            self.set_exit_code(1)
+            self.set_error_message(str(e))
+
+    @abstractmethod
+    def execute(self) -> None:
+        """
+        This is an abstract method that must be implemented by subclasses of BaseTask. It represents the main
+        logic of the task.
+        """
+        pass
+
+    def abort(self) -> None:
+        """
+        Sets the task's exit code to 1 and exits the program with a status code of 1.
+        """
+        self.set_exit_code(1)
+        sys.exit(1)
+
+    def get_output_context(self) -> OutputContext:
+        """
+        Returns the OutputContext object associated with the task.
+        """
+        return self.output_context
+
+    def get_output_properties(self) -> Dict[str, Any]:
+        """
+        Returns the output properties dictionary of the task's OutputContext object.
+        """
+        return self.output_context.output_properties
+
+    def get_input_properties(self) -> Dict[str, Any]:
+        """
+        Returns the input properties dictionary of the task
+        """
+        if not self.input_properties:
+            raise ValueError(f"Input properties have not been set")
+        return self.input_properties
+
+    def set_output_property(self, name: str, value: Any) -> None:
+        """
+        Sets the name and value of an output property of the task
+        """
+        if not name:
+            raise ValueError("Output property name cannot be empty")
+
+        accepted_data_types = (str, int, list, dict, bool)
+
+        if value and not isinstance(value, accepted_data_types):
+            raise ValueError(
+                f"Invalid data type for value '{value}' in name '{name}' in set_output_property. Accepted data types "
+                f"are: str, int, list, dict, bool")
+
+        self.output_context.output_properties[name] = value
+
+    def set_exit_code(self, value) -> None:
+        """
+        Sets the exit code of the task's OutputContext object.
+        """
+        self.output_context.exit_code = value
+
+    def set_error_message(self, value) -> None:
+        """
+        Sets the error message of the task's OutputContext object.
+        """
+        self.output_context.job_error_message = value
+
+    def add_comment(self, comment: str) -> None:
+        """
+        Logs a comment of the task.
+        """
+        dai_logger.debug(f"##[start: comment]{comment}##[end: comment]")
+
+    def set_status_line(self, status_line: str) -> None:
+        """
+        Set the status of the task.
+        """
+        dai_logger.debug(f"##[start: status]{status_line}##[end: status]")
+
+    def add_reporting_record(self, reporting_record: Any) -> None:
+        """
+        Adds a reporting record to the OutputContext
+        """
+        self.output_context.reporting_records.append(reporting_record)
+
+    def get_release_server_url(self) -> str:
+        """
+        Returns the Release server URL of the associated task
+        """
+        return self.release_server_url
+
+    def get_task_user(self) -> Optional[AutomatedTaskAsUserContext]:
+        """
+        Returns the user details that are executing the task, or ``None`` when no
+        release context is available.
+        """
+        if not self.release_context:
+            return None
+        return self.release_context.automated_task_as_user
+
+    def get_release_id(self) -> str:
+        """
+        Returns the Release ID of the task
+        """
+        return self.release_context.id
+
+    def get_task_id(self) -> str:
+        """
+        Returns the Task ID of the task
+        """
+        return self.task_id
+
+    def get_phase_id(self) -> str:
+        """
+        Returns the Phase ID of the task, derived from the task id.
+        """
+        return Ids.phase_id_from(self.get_task_id())
+
+    def get_folder_id(self) -> str:
+        """
+        Returns the ID of the folder that contains the release, derived from the
+        release id.
+        """
+        return Ids.find_folder_id(self.get_release_id())
+
+    def get_release_api_client(self,
+                               server_address: str = None,
+                               username: str = None,
+                               password: str = None,
+                               personal_access_token: str = None,
+                               **kwargs) -> ReleaseAPIClient:
+        """
+        Returns a ReleaseAPIClient object.
+
+        All arguments are optional. When omitted, the client is configured from the
+        task context (server URL and the 'Run as user' credentials). Any argument
+        that is provided overrides the corresponding task default.
+
+        :param server_address: Optional Release server URL. Defaults to the task's server URL.
+        :param username: Optional username. Defaults to the task user's username.
+        :param password: Optional password. Defaults to the task user's password.
+        :param personal_access_token: Optional personal access token for authentication.
+        :param kwargs: Additional session parameters (e.g., headers, timeout).
+        """
+        task_user = self.get_task_user()
+        server_address = server_address or self.get_release_server_url()
+
+        if personal_access_token:
+            if not server_address:
+                raise ValueError(
+                    "Cannot connect to Release API without server URL. "
+                    "Make sure that the release server URL is available."
+                )
+            return ReleaseAPIClient(server_address,
+                                    personal_access_token=personal_access_token,
+                                    **kwargs)
+
+        username = username or (task_user and task_user.username)
+        password = password or (task_user and task_user.password)
+        self._validate_api_credentials(server_address, username, password)
+        return ReleaseAPIClient(server_address, username, password, **kwargs)
+
+    def _validate_api_credentials(self, server_address: str = None,
+                                  username: str = None, password: str = None) -> None:
+        """
+        Validates that the necessary credentials are available for connecting to the Release API.
+        """
+        task_user = self.get_task_user()
+        if not all([
+            server_address or self.get_release_server_url(),
+            username or (task_user and task_user.username),
+            password or (task_user and task_user.password)
+        ]):
+            raise ValueError(
+                "Cannot connect to Release API without server URL, username, or password. "
+                "Make sure that the 'Run as user' property is set on the release."
+            )
+
+
+

digitalai_release_sdk-26.3.0b1/digitalai/release/integration/exceptions.py

@@ -0,0 +1,8 @@
+class AbortException(BaseException):
+    """Exception class to be raised when a process needs to be prematurely terminated.
+
+    This exception can be caught and handled by the calling code to gracefully terminate
+    the process and clean up any resources before exiting.
+    """
+    pass
+

digitalai_release_sdk-26.3.0b1/digitalai/release/integration/ids.py

@@ -0,0 +1,52 @@
+"""
+Helpers for parsing Release object ids.
+
+Release object ids are slash-separated paths, e.g.
+    Applications/Folder.../Release.../Phase.../Task...
+The server derives the enclosing phase/folder by walking up that path (see
+com.xebialabs.xlrelease.repository.Ids). A task only receives its own task and
+release ids, so we reproduce the same walk to resolve the phase and folder.
+"""
+
+_ID_SEPARATOR = '/'
+_PHASE_PREFIX = 'Phase'
+_FOLDER_PREFIX = 'Folder'
+
+
+class Ids:
+    """Path-based parsing of Release object ids (mirrors the server's Ids)."""
+
+    @staticmethod
+    def segment_name(object_id: str) -> str:
+        """Return the last path segment of an id (Ids.getName)."""
+        if _ID_SEPARATOR not in object_id:
+            return object_id
+        return object_id[object_id.rfind(_ID_SEPARATOR) + 1:]
+
+    @staticmethod
+    def parent_id(object_id: str) -> str:
+        """Return the id with its last path segment removed (Ids.getParentId)."""
+        return object_id[:object_id.rfind(_ID_SEPARATOR)]
+
+    @staticmethod
+    def is_root(object_id: str) -> bool:
+        """True when the id has no parent, i.e. no separator (Ids.isRoot)."""
+        return _ID_SEPARATOR not in object_id
+
+    @staticmethod
+    def phase_id_from(object_id: str) -> str:
+        """Return the enclosing phase id of ``object_id`` (Ids.phaseIdFrom)."""
+        ancestry = object_id
+        while not Ids.segment_name(ancestry).startswith(_PHASE_PREFIX):
+            if Ids.is_root(ancestry):
+                raise ValueError(f"No phase found in id '{object_id}'")
+            ancestry = Ids.parent_id(ancestry)
+        return ancestry
+
+    @staticmethod
+    def find_folder_id(object_id: str) -> str:
+        """Return the enclosing folder id of ``object_id`` (Ids.findFolderId)."""
+        parent = object_id
+        while not Ids.segment_name(parent).startswith(_FOLDER_PREFIX) and not Ids.is_root(parent):
+            parent = Ids.parent_id(parent)
+        return parent

digitalai_release_sdk-26.3.0b1/digitalai/release/integration/input_context.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Dict, Optional
+from dataclasses_json import dataclass_json, LetterCase
+
+
+@dataclass_json
+@dataclass
+class PropertyDefinition:
+    """
+    Definition of a property.
+
+    Attributes:
+    - name (str): Name of the property.
+    - kind (str): Kind of the property (e.g. 'CI', 'string').
+    - category (str): Category of the property (e.g. 'input', 'output').
+    - password (bool): Whether the property is a password.
+    - value (Any): Value of the property.
+    """
+    name: str
+    kind: str
+    category: str
+    password: bool
+    value: Any
+
+    def property_value(self):
+        """
+        Get the value of the property, recursively unwrapping nested CI properties.
+
+        Returns:
+        - Any: The value of the property.
+        """
+        if self.kind == 'CI' and self.value:
+            ci = CiDefinition.from_dict(self.value)
+            return {p.name: p.property_value() for p in ci.properties}
+        else:
+            return self.value
+
+    def secret_value(self):
+        """
+        Get the password values of the property, recursively unwrapping nested CI properties.
+
+        Returns:
+        - list: A list of password values.
+        """
+        if self.kind == 'CI' and self.value:
+            ci = CiDefinition.from_dict(self.value)
+            return [p.value for p in ci.properties if p.password and p.value]
+        else:
+            return [self.value] if self.password and self.value else []
+
+
+@dataclass_json
+@dataclass
+class CiDefinition:
+    """
+    Definition of a CI.
+
+    Attributes:
+    - id (str): ID of the CI.
+    - type (str): Type of the CI.
+    - properties (List[PropertyDefinition]): List of properties for the CI.
+    """
+    id: Optional[str] = None
+    type: Optional[str] = None
+    properties: List[PropertyDefinition] = field(default_factory=list)
+
+
+@dataclass_json
+@dataclass
+class TaskContext(CiDefinition):
+    """
+    Context of a task.
+
+    Attributes:
+    - id (str): ID of the CI.
+    - type (str): Type of the CI.
+    - properties (List[PropertyDefinition]): List of properties for the CI.
+    """
+
+    def output_properties(self) -> List[str]:
+        """
+        Get the names of the output properties of the task.
+
+        Returns:
+        - list: A list of output property names.
+        """
+        return [p.name for p in self.properties if p.category == 'output']
+
+    def secrets(self) -> List[str]:
+        """
+        Get the password values of the task, recursively unwrapping nested CI properties.
+
+        Returns:
+        - list: A list of password values.
+        """
+        secret_list = []
+        for p in self.properties:
+            secret_list.extend(p.secret_value())
+        return secret_list
+
+    def build_locals(self) -> Dict[str, Any]:
+        """
+        Build a dictionary of the task's property values.
+
+        Returns:
+        - dict: A dictionary of property names to values.
+        """
+        return {p.name: p.property_value() for p in self.properties}
+
+    def script_location(self) -> str:
+        """
+        Get the value of the 'scriptLocation' property.
+
+        Returns:
+        - str: The value of the 'scriptLocation' property.
+        """
+        return next((p.value for p in self.properties if p.name == 'scriptLocation'), '')
+
+
+@dataclass_json
+@dataclass
+class AutomatedTaskAsUserContext:
+    """
+    Context for running an automated task as a specific user.
+
+    Attributes:
+    - username (str): The username to run the task as.
+    - password (str): The password for the user.
+    """
+    username: Optional[str] = None
+    password: Optional[str] = None
+
+
+@dataclass_json(letter_case=LetterCase.CAMEL)
+@dataclass
+class ReleaseContext:
+    """
+    Context of a release.
+
+    Attributes:
+    - id (str): ID of the release.
+    - automated_task_as_user (AutomatedTaskAsUserContext): Context for running
+        an automated task as a specific user.
+    """
+    id: Optional[str] = None
+    automated_task_as_user: Optional[AutomatedTaskAsUserContext] = field(default_factory=AutomatedTaskAsUserContext)
+
+
+@dataclass_json()
+@dataclass
+class InputContext:
+    """
+    Input context for a task.
+
+    Attributes:
+    - release (ReleaseContext): Context of the release.
+    - task (TaskContext): Context of the task.
+    """
+    release: Optional[ReleaseContext] = None
+    task: Optional[TaskContext] = None
+