switch-api 0.6.13__tar.gz → 0.6.15__tar.gz

{switch_api-0.6.13 → switch_api-0.6.15}/HISTORY.md

@@ -1,5 +1,27 @@
 # History
 
+#0.6.15
+### Added
+In the `automation` module:
+- Added `send_cds_command()` to allow programmatic execution of CDS action commands (`Start`, `Stop`, `Restart`) for a specified data feed.
+- Added `deploy_as_cds_data_feed()` to support deployment of custom drivers as CDS-triggered data feeds with settings.
+- Added `deploy_as_webhooks_data_feed()` to enable deployment of custom drivers as webhook-triggered data feeds with support for client signing secrets, task priority, and framework configuration.
+
+In the `utils` module:
+- Added `ensure_uuid()` helper function to validate and normalize UUID inputs, supporting both `uuid.UUID` objects and UUID strings.
+
+### Modified
+In the `constants` module:
+- Extended `TASK_PRIORITY` to include new priority levels `control` and `lendlease-beot`.
+
+#0.6.14
+### Modified
+In the `integration` module:
+- Updated `add_carbon_column()` to enforce priority selection of carbon calculation rules.
+- When overlapping date ranges exist for the same `ObjectPropertyId`, the rule with a non-null `ObjectPropertyTemplateID` is now preferred over the default (NULL) rule.
+- Ensured only one carbon calculation is applied per input row to prevent duplicate records.
+- Refactored logic to preserve original row count and avoid row loss during rule matching.
+
 #0.6.13
 ### Added
 In the `controls` module

{switch_api-0.6.13 → switch_api-0.6.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: switch_api
-Version: 0.6.13
+Version: 0.6.15
 Summary: A complete package for data ingestion into the Switch Automation Platform.
 Home-page: UNKNOWN
 Author: Switch Automation Pty Ltd.
@@ -38,6 +38,28 @@ pip install switch_api
 
 # History
 
+#0.6.15
+### Added
+In the `automation` module:
+- Added `send_cds_command()` to allow programmatic execution of CDS action commands (`Start`, `Stop`, `Restart`) for a specified data feed.
+- Added `deploy_as_cds_data_feed()` to support deployment of custom drivers as CDS-triggered data feeds with settings.
+- Added `deploy_as_webhooks_data_feed()` to enable deployment of custom drivers as webhook-triggered data feeds with support for client signing secrets, task priority, and framework configuration.
+
+In the `utils` module:
+- Added `ensure_uuid()` helper function to validate and normalize UUID inputs, supporting both `uuid.UUID` objects and UUID strings.
+
+### Modified
+In the `constants` module:
+- Extended `TASK_PRIORITY` to include new priority levels `control` and `lendlease-beot`.
+
+#0.6.14
+### Modified
+In the `integration` module:
+- Updated `add_carbon_column()` to enforce priority selection of carbon calculation rules.
+- When overlapping date ranges exist for the same `ObjectPropertyId`, the rule with a non-null `ObjectPropertyTemplateID` is now preferred over the default (NULL) rule.
+- Ensured only one carbon calculation is applied per input row to prevent duplicate records.
+- Refactored logic to preserve original row count and avoid row loss during rule matching.
+
 #0.6.13
 ### Added
 In the `controls` module

{switch_api-0.6.13 → switch_api-0.6.15}/setup.py

@@ -16,7 +16,7 @@ setup(
     long_description_content_type='text/markdown',
     license='MIT License',
     name="switch_api",
-    version="0.6.13",
+    version="0.6.15",
     packages=find_packages(include=["switch_api", "switch_api.*"]),
     install_requires=['pandas==1.5.3', 'requests', 'azure-storage-blob', 'pandera[io]==0.7.1', 'azure-servicebus',
                       'msal>=1.11.0', 'paho-mqtt==1.6.1', 'uvicorn==0.22.0', 'fastapi==0.98.0', 'pyodbc==4.0.39', 'cachetools==5.5.0', 

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/__init__.py

@@ -42,4 +42,4 @@ from . import _guide
 # log.addHandler(_ch)
 # https://dev.to/joaomcteixeira/setting-up-python-logging-for-a-library-app-6ml
 
-__version__ = "0.6.13"
+__version__ = "0.6.15"

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/_utils/_constants.py

@@ -31,10 +31,10 @@ DATETIME_COL_FMT = Literal['DateTime', 'Date', 'Time']
 #  'Split year and month in 2 columns',
 #  'Start and End Date in 2 columns']
 
-EXPECTED_DELIVERY = Literal['5min', '15min', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Quarterly']
+EXPECTED_DELIVERY = Literal[ 'AdHoc', '1min', '5min', '15min', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Quarterly']
 
 # deploy_type 'File' for (FTP. Email, Upload)
-DEPLOY_TYPE = Literal['Email', 'Ftp', 'Upload', 'Timer']
+DEPLOY_TYPE = Literal['Email', 'Ftp', 'Upload', 'Timer', 'CDS']
 
 ACCOUNT = Literal['SwitchStorage', 'SwitchContainer', 'Argus', 'DataIngestion', 'GatewayMqttStorage']
 
@@ -45,11 +45,11 @@ QUERY_LANGUAGE = Literal['sql', 'kql']
 RESPONSE_TYPE = Literal['dataframe', 'json', 'string']
 
 ERROR_TYPE = Literal['DateTime', 'MissingDevices', 'NonNumeric', 'MissingRequiredField(s)', 'MissingSite(s)',
-                     'DuplicateRecords', 'MissingSensors', 'UnableToReadFile', 'InvalidFileType', 'InvalidInputSettings', 'ReadingSummariesTimeout']
+                     'DuplicateRecords', 'MissingSensors', 'UnableToReadFile', 'InvalidFileType', 'InvalidInputSettings', 'ReadingSummariesTimeout', 'InvalidDataType', 'NullValues']
 
 PROCESS_STATUS = Literal['ActionRequired', 'Failed']
 
-MAPPING_ENTITIES = Literal['Installations', 'Devices/Sensors', 'Readings', 'Work Orders', 'IQ']
+MAPPING_ENTITIES = Literal['Installations', 'Devices/Sensors', 'Readings', 'Work Orders', 'IQ', 'CustomData', 'Benchmarks']
 
 WORK_ORDER_CATEGORY = Literal['Preventative Maintenance', 'Tenant Request']
 
@@ -81,9 +81,9 @@ DATA_SET_QUERY_PARAMETER_TYPES = Literal['String', 'Number', 'DateTime', 'Keywor
 
 ADX_TABLE_DEF_TYPES = Literal['object', 'dynamic', 'int32', 'int64', 'float32', 'float64', 'datetime', 'string']
 
-TASK_PRIORITY = Literal['default', 'standard', 'advanced']
+TASK_PRIORITY = Literal['default', 'standard', 'advanced', 'control', 'lendlease-beot']
 
-TASK_FRAMEWORK = Literal['PythonScriptFramework', 'TaskInsightsEngine']
+TASK_FRAMEWORK = Literal['PythonScriptFramework', 'TaskInsightsEngine', 'CDSEngine']
 
 AMORTISATION_METHOD = Literal['Exclusive', 'Inclusive']
 
@@ -95,6 +95,8 @@ GUIDES_SCOPE = Literal['Portfolio-wide']
 
 IMPORT_STATUS = Literal['New', 'ToImport', 'OnHold', 'Exclude', 'Edited', 'ToRemove']
 
+CDS_ACTION_COMMAND = Literal["Start", "Stop", "Restart"]
+
 WS_DEFAULT_PORT = 443
 WS_MQTT_CONNECTION_TIMEOUT = 180
 WS_MQTT_DEFAULT_MAX_TIMEOUT = 180

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/_utils/_utils.py

@@ -521,3 +521,13 @@ def requests_retry_session2(retries: int = 5, status_forcelist: List[int] = [408
     session.mount('https://', adapter=adapter)
     session.retries = retries
     return session
+
+def ensure_uuid(value, field_name):
+    if isinstance(value, uuid.UUID):
+        return value
+    if isinstance(value, str):
+        try:
+            return uuid.UUID(value)
+        except ValueError:
+            pass
+    raise ValueError(f"{field_name} must be a valid UUID or UUID string.")

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/integration/integration.py

@@ -1855,6 +1855,7 @@ def upsert_timeseries(df: pandas.DataFrame, api_inputs: ApiInputs, is_local_time
         df = df.assign(Carbon=0.0)
 
         df = df.copy()
+        df['__row_id'] = np.arange(len(df))
         carbon_calcs_df = carbon_calculations_df.copy()
 
         if 'ObjectPropertyID' in carbon_calcs_df.columns:
@@ -1864,7 +1865,7 @@ def upsert_timeseries(df: pandas.DataFrame, api_inputs: ApiInputs, is_local_time
         if not pd.api.types.is_datetime64_any_dtype(df['TimestampLocal']):
             df['TimestampLocal'] = pd.to_datetime(df['TimestampLocal'])
 
-        required_carbon_cols = ['ObjectPropertyId', 'CarbonExpression', 'FromDate', 'ToDate']
+        required_carbon_cols = ['ObjectPropertyId', 'CarbonExpression', 'FromDate', 'ToDate', 'ObjectPropertyTemplateID']
         if not all(col in carbon_calcs_df.columns for col in required_carbon_cols):
             logger.error(f"Missing required columns in carbon calculations DataFrame. Required: {required_carbon_cols}")
             return df.assign(Carbon=0.0)
@@ -1877,29 +1878,47 @@ def upsert_timeseries(df: pandas.DataFrame, api_inputs: ApiInputs, is_local_time
         carbon_calcs_df['ToDate'] = pd.to_datetime(carbon_calcs_df['ToDate'])
 
         merged_df = pd.merge(df, carbon_calcs_df, on='ObjectPropertyId', how='left', indicator=True)
-        no_valid_carbon_calcs = merged_df[merged_df._merge== 'left_only']
 
         matches_mask = (merged_df['TimestampLocal'] >= merged_df['FromDate']) & \
                         (merged_df['TimestampLocal'] <= merged_df['ToDate'])
-        valid_carbon_calcs = merged_df[matches_mask]
 
-        if valid_carbon_calcs.shape[0]>0:
-            unique_expressions = valid_carbon_calcs['CarbonExpression'].unique()
+        valid_carbon_calcs = merged_df[matches_mask].copy()
+
+        if not valid_carbon_calcs.empty:
+            # priority: non-NULL ObjectPropertyTemplateID first
+            valid_carbon_calcs["__tmplt_priority"] = valid_carbon_calcs["ObjectPropertyTemplateID"].notna().astype(int)
+
+            # choose ONE calc row per original df row
+            valid_carbon_calcs = (
+                valid_carbon_calcs
+                .sort_values(["__row_id", "__tmplt_priority"], ascending=[True, False])
+                .drop_duplicates(subset="__row_id", keep="first")
+            )
+
+            unique_expressions = valid_carbon_calcs["CarbonExpression"].dropna().unique()
             for expr in unique_expressions:
-                expr_mask = valid_carbon_calcs['CarbonExpression'] == expr
-                numexpr_expression = expr.replace('[Value]', 'Value')
-                valid_carbon_calcs.loc[expr_mask, 'Carbon'] = numexpr.evaluate(
-                    numexpr_expression, 
-                    local_dict = {'Value': valid_carbon_calcs.loc[expr_mask, 'Value'].values}
+                expr_mask = valid_carbon_calcs["CarbonExpression"] == expr
+                numexpr_expression = expr.replace("[Value]", "Value")
+                valid_carbon_calcs.loc[expr_mask, "Carbon"] = numexpr.evaluate(
+                    numexpr_expression,
+                    local_dict={"Value": valid_carbon_calcs.loc[expr_mask, "Value"].values}
                 )
-        
-        final_df = pd.concat([no_valid_carbon_calcs, valid_carbon_calcs])
-        final_row_count = final_df.shape[0]
 
-        logger.info(f"Original row count = {original_row_count}, final row count = {final_row_count}. Matches = {original_row_count==final_row_count}")
-        final_df = final_df.drop(columns=['CarbonExpression', 'FromDate', 'ToDate', '_merge'])
+            df = df.merge(
+                valid_carbon_calcs[["__row_id", "Carbon"]],
+                on="__row_id",
+                how="left",
+                suffixes=("", "_calc"),
+            )
+            df["Carbon"] = df["Carbon_calc"].fillna(df["Carbon"])
+            df = df.drop(columns=["Carbon_calc"])
+
+        final_row_count = df.shape[0]
+        logger.info(
+            f"Original row count = {original_row_count}, final row count = {final_row_count}. Matches = {original_row_count==final_row_count}"
+        )
 
-        return final_df
+        return df.drop(columns=["__row_id"])
 
     def create_meta_column(df, slice_columns, save_slices, cost_carbon_calculation):
         """Handles creating the 'Meta' column and optionally saves additional columns as slices."""

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/pipeline/__init__.py

@@ -75,13 +75,13 @@ functions for retrieving details of existing tasks on the Switch Automation Plat
 """
 
 from .pipeline import (IntegrationTask, QueueTask, LogicModuleTask, AnalyticsTask, DiscoverableIntegrationTask,
-                       EventWorkOrderTask, BlobTask, Guide, IQTask, logger)
+                       EventWorkOrderTask, BlobTask, Guide, IQTask, CDSTask, logger)
 from .automation import Automation
 from .definitions import (IntegrationDeviceConfigPropertyDefinition, IntegrationDeviceDefinition,
                           AnalyticsSettings, EventWorkOrderFieldDefinition, IntegrationSettings)
 
 
 __all__ = ['IntegrationTask', 'QueueTask', 'LogicModuleTask', 'AnalyticsTask', 'DiscoverableIntegrationTask',
-           'EventWorkOrderTask', 'BlobTask', 'Guide', 'IQTask', 'Automation', 'logger', 'IntegrationDeviceConfigPropertyDefinition',
+           'EventWorkOrderTask', 'BlobTask', 'Guide', 'IQTask', 'CDSTask', 'Automation', 'logger', 'IntegrationDeviceConfigPropertyDefinition',
            'IntegrationDeviceDefinition', 'EventWorkOrderFieldDefinition',
            'AnalyticsSettings', 'IntegrationSettings']

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/pipeline/automation.py

@@ -23,12 +23,12 @@ import sys
 import uuid
 from io import StringIO
 from azure.servicebus import ServiceBusClient, ServiceBusReceiveMode
-from .._utils._utils import _is_valid_regex, ApiInputs, _column_name_cap, DataFeedFileProcessOutput
+from .._utils._utils import _is_valid_regex, ApiInputs, _column_name_cap, DataFeedFileProcessOutput, ensure_uuid
 from .._utils._marketplace import add_marketplace_item
-from .._utils._constants import (argus_prefix, EXPECTED_DELIVERY, MAPPING_ENTITIES,
+from .._utils._constants import (CDS_ACTION_COMMAND, argus_prefix, EXPECTED_DELIVERY, MAPPING_ENTITIES,
                                  QUEUE_NAME, ERROR_TYPE, SCHEDULE_TIMEZONE, DEPLOY_TYPE, TASK_PRIORITY, TASK_FRAMEWORK, GUIDES_EXTERNAL_TYPES, GUIDES_SCOPE)
 from .._utils._platform import _get_ingestion_service_bus_connection_string, Blob
-from .pipeline import (Task, QueueTask, IntegrationTask, LogicModuleTask, AnalyticsTask, EventWorkOrderTask,
+from .pipeline import (CDSTask, Task, QueueTask, IntegrationTask, LogicModuleTask, AnalyticsTask, EventWorkOrderTask,
                        DiscoverableIntegrationTask, BlobTask, Guide, IQTask)
 from ..extensions import ExtensionTask, replace_extensions_imports, has_extensions_support
 from .definitions import (IntegrationDeviceDefinition, EventWorkOrderFieldDefinition, AnalyticsSettings,
@@ -1040,6 +1040,227 @@ class Automation:
         df.columns = _column_name_cap(df.columns)
 
         return df
+    
+    @staticmethod
+    def deploy_as_cds_data_feed(task: Task,
+                                api_inputs: ApiInputs, 
+                                data_feed_id: uuid.UUID,
+                                expected_delivery: EXPECTED_DELIVERY,
+                                settings: dict = {},
+                                data_feed_name: str = None):
+        """
+
+        Parameters
+        ----------
+        task : Task
+            The custom driver class created from the Abstract Base Class 'Task'
+        api_inputs : ApiInputs
+            Object returned by the initialize() function.
+        data_feed_id : uuid.UUID
+            The DataFeedId to update if existing, else will create a new record with the given value.
+        expected_delivery : EXPECTED_DELIVERY
+            The expected delivery frequency of the data.
+        data_feed_name : str, Optional
+            The name of the data feed (to be displayed in Task Insights UI). If not provided, will default to the
+            task name.
+        settings : dict
+            List of settings used to deploy the driver. May containing information needed to access 3rd party api
+             - e.g. URI, Username, Pwd, AccessToken, etc
+
+        Returns
+        -------
+        df : pandas.DataFrame
+            Dataframe containing the details of the deployed https endpoint data feed.
+
+        """
+        if not isinstance(task, CDSTask):
+            logger.error(f"deploy_as_cds_data_feed only accepts tasks that implement CDSTask, got {type(task).__name__}")
+            return pandas.DataFrame()
+
+        if api_inputs.api_base_url == '' or api_inputs.bearer_token == '':
+            logger.error("You must call initialize() before using API.")
+            return pandas.DataFrame()
+
+        if data_feed_id is None and data_feed_name is None:
+            data_feed_id = uuid.UUID('00000000-0000-0000-0000-000000000000')
+            data_feed_name = task.__class__.__qualname__
+        elif data_feed_id is not None and data_feed_name is None:
+            data_feed_id = data_feed_id
+            data_feed_name = data_feed_name
+            
+        if not set([expected_delivery]).issubset(set(EXPECTED_DELIVERY.__args__)):
+            logger.error('expected_delivery parameter must be set to one of the allowed values defined by the '
+                         'EXPECTED_DELIVERY literal: %s', EXPECTED_DELIVERY.__args__)
+            return pandas.DataFrame()
+        
+        if settings and not isinstance(settings, dict):
+            logger.error("setting parameter should be of type dict.")
+            return pandas.DataFrame()
+
+        headers = api_inputs.api_headers.default
+
+        logger.info('Deploy %s (%s) as a data feed for ApiProjectID: %s', type(task).__name__, str(task.id), api_inputs.api_project_id)
+        
+        task_framework: TASK_FRAMEWORK = 'CDSEngine'
+        task_priority: TASK_PRIORITY = 'standard'
+
+        logger.info('Task Framework is "%s"', str(task_framework))
+        logger.info('Task Priotiy is "%s"', str(task_priority))
+
+        payload = {
+            "driverId": str(task.id),
+            "dataFeedId": str(data_feed_id),
+            "name": data_feed_name,
+            "feedType": "CDS",
+            "sourceType": "CDS",
+            "expectedDelivery": expected_delivery,
+            "taskFramework": task_framework,
+            "taskPriority": task_priority,
+            "settings": settings
+        }
+
+        url = f"{api_inputs.api_projects_endpoint}/{api_inputs.api_project_id}/data-ingestion/tasks/deployment"
+
+        logger.info("Sending request: POST %s", url)
+
+        response = requests.post(url, json=payload, headers=headers)
+        response_status = '{} {}'.format(response.status_code, response.reason)
+        if response.status_code != 200:
+            logger.error("API Call was not successful. Response Status: %s. Reason: %s.", response.status_code,
+                         response.reason)
+            return response_status, pandas.DataFrame()
+        elif len(response.text) == 0:
+            logger.error('No data returned for this API call. %s', response.request.url)
+            return response_status, pandas.DataFrame()
+
+        df = pandas.read_json(StringIO(response.text), typ='Series').to_frame().T
+        df.columns = _column_name_cap(df.columns)
+
+        return df
+
+    @staticmethod
+    def deploy_as_webhooks_data_feed(task: Task,
+                                   api_inputs: ApiInputs, 
+                                   data_feed_id: uuid.UUID,
+                                   client_signing_secret: str,
+                                   expected_delivery: EXPECTED_DELIVERY,
+                                   settings: dict = {},
+                                   data_feed_name: str = None,
+                                   task_priority: TASK_PRIORITY = 'standard',
+                                   task_framework: TASK_FRAMEWORK = 'TaskInsightsEngine'):
+        
+        """Deploy the custom driver as a Webhook triggered Data Feed.
+
+        Parameters
+        ----------
+        task : Task
+            The custom driver class created from the Abstract Base Class 'Task'
+        api_inputs : ApiInputs
+            Object returned by the initialize() function.
+        data_feed_id : uuid.UUID
+            The DataFeedId to update if existing, else will create a new record with the given value.
+        client_signing_secret : uuid.UUID
+            Client Signing Secret 
+        expected_delivery : EXPECTED_DELIVERY
+            The expected delivery frequency of the data.
+        queue_name : QUEUE_NAME, optional
+            The queue name (Default value = 'task').
+        data_feed_name : str, Optional
+            The name of the data feed (to be displayed in Task Insights UI). If not provided, will default to the
+            task name.
+        task_priority: TASK_PRIORITY
+            Determines the priority of the datafeed tasks when processing. This equates to how much resources would be alloted
+            to run the task - 'default`, 'standard', or 'advanced'. Defaults to 'default'.
+        task_framework: TASK_FRAMEWORK
+            Determines the framework of the datafeed tasks when processing.
+            'PythonScriptFramework' for the old task runner engine.
+            'TaskInsightsEngine' for the new task running in container apps.
+        settings : dict
+            List of settings used to deploy the driver. May containing information needed to access 3rd party api
+             - e.g. URI, Username, Pwd, AccessToken, etc
+
+        Returns
+        -------
+        df : pandas.DataFrame
+            Dataframe containing the details of the deployed webhook endpoint data feed.
+
+        """
+
+        if api_inputs.api_base_url == '' or api_inputs.bearer_token == '':
+            logger.error("You must call initialize() before using API.")
+            return pandas.DataFrame()
+
+        if data_feed_id is None and data_feed_name is None:
+            data_feed_id = uuid.UUID('00000000-0000-0000-0000-000000000000')
+            data_feed_name = task.__class__.__qualname__
+        elif data_feed_id is not None and data_feed_name is None:
+            data_feed_id = data_feed_id
+            data_feed_name = data_feed_name
+
+        if client_signing_secret == '' or client_signing_secret == None:
+            logger.error("Client Signing Secret cannot be null.")
+            return pandas.DataFrame()
+
+        headers = api_inputs.api_headers.default
+
+        if not set([expected_delivery]).issubset(set(EXPECTED_DELIVERY.__args__)):
+            logger.error('expected_delivery parameter must be set to one of the allowed values defined by the '
+                         'EXPECTED_DELIVERY literal: %s', EXPECTED_DELIVERY.__args__)
+            return pandas.DataFrame()
+
+        if not set([task_framework]).issubset(set(TASK_FRAMEWORK.__args__)):
+            logger.error('task_framework parameter must be set to one of the allowed values defined by the '
+                         'TASK_FRAMEWORK literal: %s', TASK_FRAMEWORK.__args__)
+            return pandas.DataFrame()
+
+        if not set([task_priority]).issubset(set(TASK_PRIORITY.__args__)):
+            logger.error('task_priority parameter must be set to one of the allowed values defined by the '
+                         'TASK_PRIORITY literal: %s', TASK_PRIORITY.__args__)
+            return pandas.DataFrame()
+        
+        if settings and not isinstance(settings, dict):
+            logger.error("setting parameter should be of type dict.")
+            return pandas.DataFrame()
+
+        logger.info('Deploy %s (%s) as a data feed for ApiProjectID: %s', type(task).__name__, str(task.id),
+                    api_inputs.api_project_id)
+        logger.info('Task Framework is "%s"', str(task_framework))
+        logger.info('Task Priotiy is "%s"', str(task_priority))
+
+        payload = {
+            "dataFeedId": str(data_feed_id),
+            "driverId": str(task.id),
+            "name": data_feed_name,
+            "feedType": "Webhooks",
+            "expectedDelivery": expected_delivery,
+            "sourceType": "Webhooks",
+            "taskFramework": task_framework,
+            "taskPriority": task_priority,
+            "webhook": {
+                "clientSigningSecret": client_signing_secret
+            },
+            "settings": settings
+        }
+
+        url = f"{api_inputs.api_projects_endpoint}/{api_inputs.api_project_id}/data-ingestion/tasks/deployment"
+
+        logger.info("Sending request: POST %s", url)
+
+        response = requests.post(url, json=payload, headers=headers)
+        response_status = '{} {}'.format(response.status_code, response.reason)
+
+        if response.status_code != 200:
+            logger.error("API Call was not successful. Response Status: %s. Reason: %s.", response.status_code,
+                         response.reason)
+            return response_status, pandas.DataFrame()
+        elif len(response.text) == 0:
+            logger.error('No data returned for this API call. %s', response.request.url)
+            return response_status, pandas.DataFrame()
+
+        df = pandas.read_json(StringIO(response.text), typ='Series').to_frame().T
+        df.columns = _column_name_cap(df.columns)
+
+        return df
 
     @staticmethod
     def deploy_as_blob_data_feed(task: BlobTask,
@@ -1377,6 +1598,10 @@ class Automation:
         # Check if there's any timer deploy_type being cancelled, delete it as well by calling delete method
         if any("Timer" in deploy_type for deploy_type in deployment_type):
             return Automation.delete_deployed_data_feed(api_inputs=api_inputs, data_feed_id=data_feed_id)
+        
+        # Check if there's any CDS deploy_type being cancelled, send `STOP` action command by calling send_cds_command()
+        if any("CDS" in deploy_type for deploy_type in deployment_type):
+            return Automation.send_cds_command(api_inputs=api_inputs, data_feed_id=data_feed_id, action_command='Stop')
 
         df = pandas.read_json(response.text, typ='Series').to_frame().T
         df.columns = _column_name_cap(df.columns)
@@ -1385,7 +1610,8 @@ class Automation:
 
     @staticmethod
     def delete_deployed_data_feed(api_inputs: ApiInputs, data_feed_id: uuid.UUID):
-        """Delete deployment for a given `data_feed_id`.
+        """
+        Delete timer schedule for a given `data_feed_id`.
 
         Parameters
         ----------
@@ -1813,3 +2039,111 @@ class Automation:
         task_code += 'task = ' + task_type.__name__ + '()'
 
         return task_code
+
+    @staticmethod
+    def send_cds_command(
+            api_inputs: ApiInputs,
+            data_feed_id: uuid.UUID,
+            action_command: CDS_ACTION_COMMAND):
+        """Send a CDS action command for a given data feed.
+
+        This method sends a POST request to the CDS action-command endpoint for the
+        specified data feed. It validates the required API inputs and command values
+        before building the request payload and submitting it to the API.
+
+        Parameters
+        ----------
+        api_inputs : ApiInputs
+            Object returned by the initialize.initialize() function. This must contain
+            a valid ``api_base_url``, ``bearer_token``, ``api_project_id``,
+            ``api_projects_endpoint``, and default request headers.
+        data_feed_id : uuid.UUID
+            The unique identifier of the data feed that the CDS command will be sent to.
+        action_command : CDS_ACTION_COMMAND
+            The action command to execute for the target data feed. This must be set
+            to one of the allowed literal values defined by ``CDS_ACTION_COMMAND``.
+
+        Returns
+        -------
+        pandas.DataFrame
+            A dataframe containing the API response when the request is successful.
+
+        tuple[str, pandas.DataFrame]
+            Returns a tuple of ``(response_status, empty_dataframe)`` when the API call
+            is not successful.
+
+        pandas.DataFrame
+            Returns an empty dataframe when API inputs are not initialized or when no
+            data is returned from the API.
+
+        Raises
+        ------
+        ValueError
+            Raised when:
+            - ``api_inputs`` is None
+            - ``data_feed_id`` is not a valid ``uuid.UUID``
+            - ``action_command`` is not one of the allowed ``CDS_ACTION_COMMAND`` values
+
+        Notes
+        -----
+        This method performs the following steps:
+
+        1. Validates the required inputs.
+        2. Builds the request payload using the API project ID, data feed ID,
+            and action command.
+        3. Sends a POST request to the CDS action-command API endpoint.
+        4. Converts the JSON response into a single-row pandas dataframe.
+        5. Normalizes the dataframe column names using ``_column_name_cap``.
+
+        Examples
+        --------
+        >>> df = sw.pipeline.Automation._send_cds_command(
+        ...     api_inputs=api_inputs,
+        ...     data_feed_id=uuid.UUID("12345678-1234-1234-1234-123456789abc"),
+        ...     action_command="Start"
+        ... )
+
+        """
+
+        # ensure data_feed_id is UUID
+        data_feed_id = ensure_uuid(data_feed_id, "data_feed_id")
+
+        # Validate api_inputs
+        if api_inputs is None:
+            raise ValueError("api_inputs cannot be None.")
+
+        if not api_inputs.api_base_url or not api_inputs.bearer_token:
+            logger.error("You must call initialize() before using API.")
+            return pandas.DataFrame()
+
+        # Validate enums/literals
+        if action_command not in CDS_ACTION_COMMAND.__args__:
+            raise ValueError('action_command parameter must be set to one of the allowed values defined by the '
+                         'CDS_ACTION_COMMAND literal: %s', CDS_ACTION_COMMAND.__args__)
+        
+        payload = {
+            "apiProjectId": api_inputs.api_project_id,
+            "dataFeedId": str(data_feed_id),
+            "actionCommand": action_command
+        }
+
+        url = f"{api_inputs.api_projects_endpoint}/{api_inputs.api_project_id}/data-ingestion/data-feed/{data_feed_id}/cds/action-command"
+
+        logger.info("Sending request: POST %s", url)
+
+        headers = api_inputs.api_headers.default
+        response = requests.post(url, json=payload, headers=headers)
+        response_status = '{} {}'.format(response.status_code, response.reason)
+
+        if response.status_code != 200:
+            logger.error("API Call was not successful. Response Status: %s. Reason: %s.", response.status_code,
+                         response.reason)
+            return response_status, pandas.DataFrame()
+        elif len(response.text) == 0:
+            logger.error('No data returned for this API call. %s', response.request.url)
+            return response_status, pandas.DataFrame()
+
+        df = pandas.read_json(StringIO(response.text), typ='Series').to_frame().T
+        df.columns = _column_name_cap(df.columns)
+
+        return df

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api/pipeline/pipeline.py

@@ -621,6 +621,16 @@ class LogicModuleTask(Task):
 
     # Needs to be implemented into the deploy_on_timer
 
+class CDSTask(Task):
+    """
+    Base class for long-running CDS driver tasks.
+
+    Implement process_loop() for continuous execution / polling / worker-style behavior.
+    """
+
+    @abstractmethod
+    def process_loop(self, api_inputs, settings):
+        pass
 
 class RunAt(enum.Enum):
     """ """

{switch_api-0.6.13 → switch_api-0.6.15}/switch_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: switch-api
-Version: 0.6.13
+Version: 0.6.15
 Summary: A complete package for data ingestion into the Switch Automation Platform.
 Home-page: UNKNOWN
 Author: Switch Automation Pty Ltd.
@@ -38,6 +38,28 @@ pip install switch_api
 
 # History
 
+#0.6.15
+### Added
+In the `automation` module:
+- Added `send_cds_command()` to allow programmatic execution of CDS action commands (`Start`, `Stop`, `Restart`) for a specified data feed.
+- Added `deploy_as_cds_data_feed()` to support deployment of custom drivers as CDS-triggered data feeds with settings.
+- Added `deploy_as_webhooks_data_feed()` to enable deployment of custom drivers as webhook-triggered data feeds with support for client signing secrets, task priority, and framework configuration.
+
+In the `utils` module:
+- Added `ensure_uuid()` helper function to validate and normalize UUID inputs, supporting both `uuid.UUID` objects and UUID strings.
+
+### Modified
+In the `constants` module:
+- Extended `TASK_PRIORITY` to include new priority levels `control` and `lendlease-beot`.
+
+#0.6.14
+### Modified
+In the `integration` module:
+- Updated `add_carbon_column()` to enforce priority selection of carbon calculation rules.
+- When overlapping date ranges exist for the same `ObjectPropertyId`, the rule with a non-null `ObjectPropertyTemplateID` is now preferred over the default (NULL) rule.
+- Ensured only one carbon calculation is applied per input row to prevent duplicate records.
+- Refactored logic to preserve original row count and avoid row loss during rule matching.
+
 #0.6.13
 ### Added
 In the `controls` module