switch-api 0.6.28__tar.gz → 0.6.30__tar.gz

{switch_api-0.6.28 → switch_api-0.6.30}/HISTORY.md

@@ -1,5 +1,38 @@
 # History
 
+#0.6.30
+
+### Added
+
+In the `integration` module:
+
+- Added `upsert_sensor_state_history()` to append sensor state history records with site-local, UTC, or named-timezone timestamp handling.
+- Added the `update_current_state` option to `upsert_sensor_state_history()` to update each sensor's current state from its latest history record.
+- Added `update_sensor_state()` to update current sensor states in SQL using validated, batched writes with retry handling.
+
+In the `_utils` module:
+
+- Added `set_sql_write_config()` and cached SQL write connection helpers using `pyodbc`.
+- Added `get_connection_string_from_local_file()` to load datacentre-specific MQTT, Redis, and SQL write configuration from a local credentials file.
+
+### Changed
+
+In the `controls` module:
+
+- Updated control components to accept either a single integer priority or a DataFrame column name containing row-level priority values.
+
+#0.6.29
+
+### Changed
+
+In the `authentication` module:
+
+- Added optional `data_center` support to `initialize()`, with `AU` and `US` as the supported values.
+- Authentication login-context and user-profile requests now use the endpoint associated with the selected data center.
+- Interactive production authentication now uses the B2C authority associated with the portfolio's resolved data center (`AustraliaEast` or `CentralUs`).
+- When `data_center` is omitted, authentication defaults to `US` and logs a warning to preserve backward compatibility.
+- Invalid data-center values now raise a `ValueError` with the supported options.
+
 #0.6.18
 ### Changed
 In the `realtime` module:

{switch_api-0.6.28 → switch_api-0.6.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switch_api
-Version: 0.6.28
+Version: 0.6.30
 Summary: A complete package for data ingestion into the Switch Automation Platform.
 Author: Switch Automation Pty Ltd.
 License: MIT License
@@ -58,6 +58,39 @@ pip install switch_api
 
 # History
 
+#0.6.30
+
+### Added
+
+In the `integration` module:
+
+- Added `upsert_sensor_state_history()` to append sensor state history records with site-local, UTC, or named-timezone timestamp handling.
+- Added the `update_current_state` option to `upsert_sensor_state_history()` to update each sensor's current state from its latest history record.
+- Added `update_sensor_state()` to update current sensor states in SQL using validated, batched writes with retry handling.
+
+In the `_utils` module:
+
+- Added `set_sql_write_config()` and cached SQL write connection helpers using `pyodbc`.
+- Added `get_connection_string_from_local_file()` to load datacentre-specific MQTT, Redis, and SQL write configuration from a local credentials file.
+
+### Changed
+
+In the `controls` module:
+
+- Updated control components to accept either a single integer priority or a DataFrame column name containing row-level priority values.
+
+#0.6.29
+
+### Changed
+
+In the `authentication` module:
+
+- Added optional `data_center` support to `initialize()`, with `AU` and `US` as the supported values.
+- Authentication login-context and user-profile requests now use the endpoint associated with the selected data center.
+- Interactive production authentication now uses the B2C authority associated with the portfolio's resolved data center (`AustraliaEast` or `CentralUs`).
+- When `data_center` is omitted, authentication defaults to `US` and logs a warning to preserve backward compatibility.
+- Invalid data-center values now raise a `ValueError` with the supported options.
+
 #0.6.18
 ### Changed
 In the `realtime` module:

{switch_api-0.6.28 → switch_api-0.6.30}/setup.py

@@ -16,7 +16,7 @@ setup(
     long_description_content_type='text/markdown',
     license='MIT License',
     name="switch_api",
-    version="0.6.28",
+    version="0.6.30",
     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.28 → switch_api-0.6.30}/switch_api/__init__.py

@@ -11,7 +11,7 @@ Complete package for ingestion data into the Switch Automation Platform.
 """
 __all__ = ['dataset', 'analytics', 'pipeline', 'error_handlers', 'integration',
            'initialize', 'cache', 'extensions', 'email', 'controls', 'realtime', '_compute', 'generate_filepath',
-           'set_mqtt_broker_config', 'set_realtime_redis_config']
+           'set_mqtt_broker_config', 'set_realtime_redis_config', 'set_sql_write_config']
 
 from .initialize import initialize
 from . import dataset
@@ -28,6 +28,7 @@ from . import realtime
 from . import _compute
 from ._utils._utils import generate_filepath
 from ._utils._mqtt import set_mqtt_broker_config
+from ._utils._sql import set_sql_write_config
 from .realtime import set_realtime_redis_config
 from . import _guide
 
@@ -44,4 +45,4 @@ from . import _guide
 # log.addHandler(_ch)
 # https://dev.to/joaomcteixeira/setting-up-python-logging-for-a-library-app-6ml
 
-__version__ = "0.6.28"
+__version__ = "0.6.30"

{switch_api-0.6.28 → switch_api-0.6.30}/switch_api/_authentication/_authentication.py

@@ -5,13 +5,14 @@
 # --------------------------------------------------------------------------
 import logging
 import sys
+from typing import Optional
 from uuid import UUID
 from msal.oauth2cli.oidc import decode_id_token
 import requests
 from ._credentials_store._credentials_store import SwitchCredentials, store_credentials
 from ._credentials_store._credentials_store import read_credentials
 from ._msal._custom_application import CustomPublicClientApplication
-from .._utils._constants import AUTH_ENDPOINT_DEV, AUTH_ENDPOINT_PROD, SWITCH_ENVIRONMENT
+from .._utils._constants import AUTH_ENDPOINTS, DATA_CENTER, SWITCH_ENVIRONMENT
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.DEBUG)
@@ -30,8 +31,14 @@ _authority = {
         "base_url": "https://switchdevb2c.b2clogin.com/switchdevb2c.onmicrosoft.com",
     },
     "prod": {
-        "base_url": "https://switchautomation.b2clogin.com/switchautomation.onmicrosoft.com",
-        "uitemplateid": "default"
+        "AustraliaEast": {
+            "base_url": "https://switchautomationapac.b2clogin.com/7d5aa686-9840-42a5-9334-084b75385e24",
+            "uitemplateid": "default"
+        },
+        "CentralUs": {
+            "base_url": "https://switchautomation.b2clogin.com/switchautomation.onmicrosoft.com",
+            "uitemplateid": "default"
+        }
     }
 }
 
@@ -69,7 +76,17 @@ def _validate_credentials(creds: SwitchCredentials, version: str):
         return False
 
 
-def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port: int):
+def _resolve_data_center(data_center: Optional[DATA_CENTER]) -> DATA_CENTER:
+    if data_center is None:
+        logger.warning('No data center was provided. Defaulting to US.')
+        return 'US'
+    if data_center not in AUTH_ENDPOINTS:
+        raise ValueError("data_center must be either 'AU' or 'US'.")
+    return data_center
+
+
+def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port: int,
+                           data_center: Optional[DATA_CENTER] = None):
     """Read Credentials
 
     Reads credentials from credential store
@@ -82,6 +99,8 @@ def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port:
         Get credentials for the given portfolio id
     port: int
         Port used for instantiating local server for authentication
+    data_center
+        Data center hosting the portfolio. Defaults to US with a warning when omitted.
 
     Returns
     -------
@@ -90,8 +109,9 @@ def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port:
 
     """
 
+    data_center = _resolve_data_center(data_center)
     login_context = fetch_login_context(
-        environment=environment, api_project_id=portfolio_id)[1]
+        environment=environment, api_project_id=portfolio_id, data_center=data_center)[1]
 
     # Fetch from credentials store if it's already been cached
     iot_endpoint = 'https://realtime-au.switchautomation.com/iot'
@@ -109,11 +129,11 @@ def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port:
 
     # Credentials do not exist, take user through browser auth journey
     config_env = 'dev' if environment == 'Development' else 'prod'
-    authority = f"{_authority[config_env]['base_url']}/{login_context['policyName']}"
+    authority = f"{_authority[config_env][datacenter]['base_url']}/{login_context['policyName']}"
     app = CustomPublicClientApplication(
         login_context['applicationId'], authority=authority)
 
-    uitemplateid = _authority[config_env]['uitemplateid']
+    uitemplateid = _authority[config_env][datacenter]['uitemplateid']
     prompt = login_context['prompt'] if login_context['prompt'] != '' else None
     auth_response = app.acquire_token_interactive_custom(scopes=[], prompt=prompt, port=port,
                                                          auth_params={
@@ -127,9 +147,8 @@ def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port:
 
     id_token = auth_response['id_token']
 
-    api_base_url = AUTH_ENDPOINT_DEV if environment == 'Development' else AUTH_ENDPOINT_PROD
     _, profile = fetch_user_profile_details(
-        api_base_url, id_token, environment, portfolio_id)
+        id_token, environment, portfolio_id, data_center)
 
     if profile is None:
         raise Exception(
@@ -145,20 +164,21 @@ def get_switch_credentials(environment: SWITCH_ENVIRONMENT, portfolio_id, port:
     return credentials
 
 
-def fetch_user_profile_details(api_base_url: str, token: str, environment: SWITCH_ENVIRONMENT, api_project_id: UUID):
+def fetch_user_profile_details(token: str, environment: SWITCH_ENVIRONMENT, api_project_id: UUID,
+                               data_center: Optional[DATA_CENTER] = None):
     """
     Fetch User Profile details with respect to the given environment and portfolio
 
     Parameters
     ----------
-    api_base_url
-        User Profile base url
     token
         Switch token for authentication
     environment
         Either development or production environment
     api_project_id
         Get UserProfile with respect to this portfolio id
+    data_center
+        Data center hosting the portfolio. Allowed values are AU and US. Defaults to US with a warning when omitted.
 
     Returns
     -------
@@ -166,6 +186,9 @@ def fetch_user_profile_details(api_base_url: str, token: str, environment: SWITC
         Returns the User Profile details containing information to call Switch APIs
     """
 
+    data_center = _resolve_data_center(data_center)
+    api_base_url = AUTH_ENDPOINTS[data_center]
+
     payload = {}
     headers = {
         'Content-Type': 'application/json; charset=utf-8',
@@ -188,7 +211,8 @@ def fetch_user_profile_details(api_base_url: str, token: str, environment: SWITC
     return response_status, response.json()
 
 
-def fetch_login_context(environment: SWITCH_ENVIRONMENT, api_project_id: UUID):
+def fetch_login_context(environment: SWITCH_ENVIRONMENT, api_project_id: UUID,
+                        data_center: Optional[DATA_CENTER] = None):
     """
     Fetches login context to assist SSO with Switch Platform
 
@@ -198,6 +222,8 @@ def fetch_login_context(environment: SWITCH_ENVIRONMENT, api_project_id: UUID):
         Either development or production environment
     api_project_id
         Get UserProfile with respect to this portfolio id
+    data_center
+        Data center hosting the portfolio. Allowed values are AU and US. Defaults to US with a warning when omitted.
 
     Returns
     -------
@@ -205,7 +231,8 @@ def fetch_login_context(environment: SWITCH_ENVIRONMENT, api_project_id: UUID):
         Returns the Login Context containing information to authenticate with Switch
     """
 
-    base_url = AUTH_ENDPOINT_DEV if environment == 'Development' else AUTH_ENDPOINT_PROD
+    data_center = _resolve_data_center(data_center)
+    base_url = AUTH_ENDPOINTS[data_center]
 
     payload = {}
     headers = {

{switch_api-0.6.28 → switch_api-0.6.30}/switch_api/_utils/_constants.py

@@ -10,8 +10,9 @@ is not directly referenced by end users.
 from typing import Literal
 __all__ = ['api_prefix', 'argus_prefix', 'DATETIME_COL_FMT', 'DEPLOY_TYPE', 'EXPECTED_DELIVERY', 'WORK_ORDER_PRIORITY',
            'WORK_ORDER_STATUS', 'WORK_ORDER_CATEGORY', 'ERROR_TYPE', 'MAPPING_ENTITIES', 'QUEUE_NAME', 'QUERY_LANGUAGE',
-           'ACCOUNT', 'PROCESS_STATUS', 'AUTH_ENDPOINT_DEV', 'AUTH_ENDPOINT_PROD', 'SCHEDULE_TIMEZONE',
-           'SWITCH_ENVIRONMENT', 'INTEGRATION_SETTINGS_EDITORS', 'DATA_INGESTION_CONTAINER', 'CACHE_SCOPE', 'TAG_LEVEL']
+           'ACCOUNT', 'PROCESS_STATUS', 'AUTH_ENDPOINTS', 'SCHEDULE_TIMEZONE',
+           'SWITCH_ENVIRONMENT', 'DATA_CENTER', 'INTEGRATION_SETTINGS_EDITORS', 'DATA_INGESTION_CONTAINER',
+           'CACHE_SCOPE', 'TAG_LEVEL']
 
 # @deprecated suggestion: Up for deprecation as this is not used anymore in the API
 # api_prefix = "http://localhost:7071/api/SwitchApi/"
@@ -21,8 +22,10 @@ api_prefix = "https://pivotstreams.azurewebsites.net/api/SwitchApi/"
 # argus_prefix = "http://localhost:7071/api/"
 argus_prefix = "https://arguslogicv4b.azurewebsites.net/api/"
 
-AUTH_ENDPOINT_DEV = "https://restapi-dev.switchautomation.com/auth"
-AUTH_ENDPOINT_PROD = "https://restapi-us.switchautomation.com/auth"
+AUTH_ENDPOINTS = {
+    'AU': 'https://restapi-ae.switchautomation.com/auth',
+    'US': 'https://restapi-us.switchautomation.com/auth'
+}
 
 DATETIME_COL_FMT = Literal['DateTime', 'Date', 'Time']
 
@@ -68,6 +71,8 @@ SCHEDULE_TIMEZONE = Literal['Local', 'Utc']
 
 SWITCH_ENVIRONMENT = Literal['Development', 'Staging', 'Testing', 'Production']
 
+DATA_CENTER = Literal['AU', 'US']
+
 SUPPORT_PAYLOAD_TYPE = Literal['Sites', 'Sensors', 'Portfolio']
 
 INTEGRATION_SETTINGS_EDITORS = Literal['text_box', 'numeric_stepper', 'custom_combo', 'tag_groups_combo',
@@ -101,4 +106,4 @@ WS_DEFAULT_PORT = 443
 WS_MQTT_CONNECTION_TIMEOUT = 180
 WS_MQTT_DEFAULT_MAX_TIMEOUT = 180
 WS_MQTT_WAIT_TIME_INTERVAL = 0.1
-WS_MQTT_MESSAGE_WAIT_TIME_INTERVAL = 0.1
+WS_MQTT_MESSAGE_WAIT_TIME_INTERVAL = 0.1

switch_api-0.6.30/switch_api/_utils/_sql.py

@@ -0,0 +1,104 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Switch Automation Pty Ltd. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+"""
+SQL write configuration and connection helpers.
+"""
+import logging
+import sys
+
+import pyodbc
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+consoleHandler = logging.StreamHandler(stream=sys.stdout)
+consoleHandler.setLevel(logging.INFO)
+
+logger.addHandler(consoleHandler)
+formatter = logging.Formatter('%(asctime)s  switch_api.%(module)s.%(funcName)s  %(levelname)s: %(message)s',
+                              datefmt='%Y-%m-%dT%H:%M:%S')
+consoleHandler.setFormatter(formatter)
+
+
+global _sql_write_config
+global _sql_write_conn
+
+_sql_write_config = {
+    "connection_string": "",
+}
+_sql_write_conn = None
+
+
+def _reset_sql_write_conn():
+    """
+    Close the cached SQL write connection and reset it to None.
+    """
+    global _sql_write_conn
+
+    if _sql_write_conn is not None:
+        try:
+            _sql_write_conn.close()
+        except Exception as e:
+            logger.warning(f"Failed to close cached SQL write connection: {e}")
+
+    _sql_write_conn = None
+
+
+def set_sql_write_config(connection_string: str):
+    """
+    Set SQL configuration.
+
+    Parameters
+    ----------
+    connection_string : str
+        The pyodbc connection string used for SQL write operations.
+
+    Raises
+    ------
+    ValueError
+        If connection_string is not a non-empty string.
+    """
+    global _sql_write_config
+
+    if not isinstance(connection_string, str) or not connection_string.strip():
+        raise ValueError("connection_string must be a non-empty string.")
+
+    _reset_sql_write_conn()
+    _sql_write_config = {
+        "connection_string": connection_string,
+    }
+    logger.info("Set SQL configuration")
+
+
+def is_sql_write_configured():
+    """
+    Return whether SQL write configuration has been set.
+    """
+    return bool(_sql_write_config["connection_string"])
+
+
+def get_sql_write_config():
+    """
+    Return a copy of the current SQL write configuration.
+    """
+    return dict(_sql_write_config)
+
+
+def _get_sql_conn():
+    """
+    Return the cached SQL write connection, creating it when required.
+    """
+    global _sql_write_conn
+
+    if not is_sql_write_configured():
+        raise ValueError("SQL write configuration has not been set.")
+
+    if _sql_write_conn is None:
+        logger.info("Creating SQL write connection.")
+        _sql_write_conn = pyodbc.connect(
+            _sql_write_config["connection_string"]
+        )
+
+    return _sql_write_conn

{switch_api-0.6.28 → switch_api-0.6.30}/switch_api/_utils/_utils.py

@@ -27,7 +27,8 @@ from .._utils._constants import (WORK_ORDER_STATUS, WORK_ORDER_CATEGORY, WORK_OR
                                  PERFORMANCE_STATISTIC_METRIC_SYSTEM, RESERVATION_STATUS, RESOURCE_TYPE)
 
 __all__ = ['generate_password', 'convert_to_sqm', 'convert_to_pascal_case', 'ValidatedSetterProperty', 'ApiInputs',
-           'DiscoveryIntegrationInput', 'DataFeedFileProcessOutput', 'requests_retry_session', 'is_valid_uuid', 'convert_bytes']
+           'DiscoveryIntegrationInput', 'DataFeedFileProcessOutput', 'requests_retry_session', 'is_valid_uuid',
+           'convert_bytes', 'get_connection_string_from_local_file']
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.DEBUG)
@@ -132,6 +133,94 @@ DataFeedFileProcessOutput = namedtuple('DataFeedFileProcessOutput',
                                        ])
 
 
+def get_connection_string_from_local_file(filepath: str, api_inputs: ApiInputs):
+    """Load local MQTT, Redis, and SQL write credentials for a datacentre.
+
+    The credentials file must contain ``KEY==VALUE`` entries for the AU and
+    US datacentres. The datacentre is determined from ``api_inputs.api_base_url``.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the local credentials file.
+    api_inputs : ApiInputs
+        Initialized API inputs containing the API base URL.
+
+    Returns
+    -------
+    dict or bool
+        MQTT, Redis, and SQL write configuration dictionaries, or False when
+        the file or datacentre configuration is invalid.
+    """
+    if not os.path.isfile(filepath):
+        logger.error(f"The provided filepath: {filepath} is not valid")
+        return False
+
+    try:
+        with open(filepath, 'r') as file:
+            file_content = file.read().splitlines()
+
+        tmp = dict(
+            line.strip().split('==', 1)
+            for line in file_content
+            if line.strip()
+        )
+    except (OSError, ValueError) as exc:
+        logger.error(f"Unable to read credentials from filepath: {filepath}. {exc}")
+        return False
+
+    try:
+        dc = api_inputs.api_base_url.split('-', 1)[1].split('.')[0]
+    except (AttributeError, IndexError):
+        logger.error("Unable to determine datacentre from ApiInputs['api_base_url']")
+        return False
+
+    if dc == "ae":
+        suffix = "_AU"
+    elif dc == "us":
+        suffix = "_US"
+    else:
+        logger.error("Unable to determine datacentre from ApiInputs['api_base_url']")
+        return False
+
+    try:
+        controls_platform_iot_endpoint = tmp['PLATFORM_IOT_ENDPOINT' + suffix]
+        controls_mqtt_host = tmp['MQTT_HOST' + suffix]
+        controls_mqtt_port = tmp['MQTT_PORT' + suffix]
+        controls_mqtt_username = tmp['MQTT_USERNAME' + suffix]
+        controls_mqtt_password = tmp['MQTT_PASSWORD' + suffix]
+        controls_max_timeout = tmp['CONTROLS_MAX_TIMEOUT' + suffix]
+
+        redis_host = tmp['REDIS_HOST' + suffix]
+        redis_password = tmp['REDIS_PASSWORD' + suffix]
+        sql_write_connection_string = tmp['SQL_WRITE_CONNECTION_STRING' + suffix]
+
+        control_variables = {
+            'iot_endpoint': controls_platform_iot_endpoint,
+            'mqtt_host': controls_mqtt_host,
+            'mqtt_username': controls_mqtt_username,
+            'mqtt_password': controls_mqtt_password,
+            'mqtt_port': int(controls_mqtt_port),
+            'max_timeout': int(controls_max_timeout)
+        }
+        redis_variables = {
+            'redis_host': redis_host,
+            'redis_password': redis_password
+        }
+        sql_write_variables = {
+            'connection_string': sql_write_connection_string
+        }
+    except (KeyError, TypeError, ValueError) as exc:
+        logger.error(f"Invalid local credentials for datacentre {dc}: {exc}")
+        return False
+
+    return {
+        'mqtt_config': control_variables,
+        'redis_config': redis_variables,
+        'sql_write_config': sql_write_variables
+    }
+
+
 def generate_password():
     """Generate a ten-character alphanumeric password with at least one lowercase character, at least one uppercase
     character, and at least three digits.
@@ -530,4 +619,4 @@ def ensure_uuid(value, field_name):
             return uuid.UUID(value)
         except ValueError:
             pass
-    raise ValueError(f"{field_name} must be a valid UUID or UUID string.")
+    raise ValueError(f"{field_name} must be a valid UUID or UUID string.")

{switch_api-0.6.28 → switch_api-0.6.30}/switch_api/controls/controls.py

@@ -218,6 +218,11 @@ def submit_control_continue(api_inputs: ApiInputs, data: pandas.DataFrame, infor
                 f"Default Value column {column_with_default_value} not found in the DataFrame")
             raise ValueError(
                 f"Default Value column {column_with_default_value} not found in the DataFrame")
+        elif isinstance(priority, str) and priority not in data.columns:
+            logger.error(
+                f"Priority column {priority} not found in the DataFrame")
+            raise ValueError(
+                f"Priority column {priority} not found in the DataFrame")
 
         data[column_with_value] = pandas.to_numeric(
             data[column_with_value], errors='coerce')
@@ -228,6 +233,7 @@ def submit_control_continue(api_inputs: ApiInputs, data: pandas.DataFrame, infor
 
             control_df = pandas.DataFrame()
             group[COL_CONTROL_NAME] = name
+            control_priority = group[priority] if isinstance(priority, str) else priority
 
             if column_with_default_value == None:
                 control_df = pandas.DataFrame({
@@ -237,7 +243,7 @@ def submit_control_continue(api_inputs: ApiInputs, data: pandas.DataFrame, infor
                     COL_CONTROL_VALUE: group[column_with_value],
                     COL_CONTROL_CONTINUE_VALUE: group[column_with_continue],
                     COL_CONTROL_TTL: timeout_in_seconds,
-                    COL_CONTROL_PRIORITY: priority
+                    COL_CONTROL_PRIORITY: control_priority
                 })
             else:
                 control_df = pandas.DataFrame({
@@ -248,7 +254,7 @@ def submit_control_continue(api_inputs: ApiInputs, data: pandas.DataFrame, infor
                     COL_CONTROL_CONTINUE_VALUE: group[column_with_continue],
                     COL_CONTROL_DEFAULT_CONTROL_VALUE: group[column_with_default_value],
                     COL_CONTROL_TTL: timeout_in_seconds,
-                    COL_CONTROL_PRIORITY: priority
+                    COL_CONTROL_PRIORITY: control_priority
                 })
 
             try:
@@ -958,7 +964,7 @@ def set_control_cache(api_inputs: ApiInputs, key: str, scope_id: str, data: any)
             f"An unexpected error occurred in setting Control cache: {e}")
         return pandas.DataFrame()
 
-def add_control_component(name: str, column_with_object_installation_id: str, column_with_object_property_id: str, column_with_label: str, column_with_value: str, column_with_continue: str = None, column_with_default_value: str = None, timeout_in_seconds: int = 0, priority: int = 8):
+def add_control_component(name: str, column_with_object_installation_id: str, column_with_object_property_id: str, column_with_label: str, column_with_value: str, column_with_continue: str = None, column_with_default_value: str = None, timeout_in_seconds: int = 0, priority: Union[int, str] = 8):
     """Add Control Components similar to batching the dataframe with named columns.
 
     Parameters
@@ -981,8 +987,9 @@ def add_control_component(name: str, column_with_object_installation_id: str, co
             Time until relinquish happens in seconds. Defaults to 0.
             Setting value to 0 means the control will not relinquish.
             If there's value > 0 then it will always relinquish control.
-        priority (int, optional):
-            Priority value for the control write command. Defaults to 8.
+        priority (int or str, optional):
+            Priority value for the control write command, or the name of the
+            DataFrame column containing row-level priority values. Defaults to 8.
 
     Returns
     -------
@@ -1019,9 +1026,13 @@ def add_control_component(name: str, column_with_object_installation_id: str, co
     if not isinstance(timeout_in_seconds, int) or timeout_in_seconds < 0:
         raise ValueError(
             "The 'timeout_in_seconds' parameter must be a non-negative integer.")
-    if not isinstance(priority, int) or priority < 0:
+    if isinstance(priority, str):
+        if not priority:
+            raise ValueError(
+                "The 'priority' parameter must be a non-empty string or non-negative integer.")
+    elif not isinstance(priority, int) or priority < 0:
         raise ValueError(
-            "The 'priority' parameter must be a non-negative integer.")
+            "The 'priority' parameter must be a non-empty string or non-negative integer.")
 
     _control_components[name] = (
         column_with_object_installation_id,

{switch_api-0.6.28 → switch_api-0.6.30}/switch_api/initialize.py

@@ -6,10 +6,11 @@
 import sys
 import uuid
 import logging
+from typing import Optional
 
 from ._authentication._authentication import get_switch_credentials
 from ._utils._utils import ApiInputs, ApiHeaders
-from ._utils._constants import SWITCH_ENVIRONMENT
+from ._utils._constants import DATA_CENTER, SWITCH_ENVIRONMENT
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.DEBUG)
@@ -23,7 +24,8 @@ formatter = logging.Formatter('%(asctime)s  switch_api.%(module)s.%(funcName)s
 consoleHandler.setFormatter(formatter)
 
 
-def initialize(api_project_id: uuid.UUID, environment: SWITCH_ENVIRONMENT = 'Production', custom_port: int = 51796) -> ApiInputs:
+def initialize(api_project_id: uuid.UUID, environment: SWITCH_ENVIRONMENT = 'Production', custom_port: int = 51796,
+               data_center: Optional[DATA_CENTER] = None) -> ApiInputs:
     """
     Initialize session with API when running scripts on your local machine.
 
@@ -35,6 +37,8 @@ def initialize(api_project_id: uuid.UUID, environment: SWITCH_ENVIRONMENT = 'Pro
         (Optional) The Switch API environment to interact with
     custom_port: int
         (Optional) Custom network port to initialize instance of the server when authenticating
+    data_center: DATA_CENTER
+        (Optional) Data center hosting the portfolio. Defaults to US with a warning when omitted.
 
     Returns
     -------
@@ -48,7 +52,7 @@ def initialize(api_project_id: uuid.UUID, environment: SWITCH_ENVIRONMENT = 'Pro
             f"Invalid value provided '{api_project_id}'- please provide a valid api_project_id. ")
         return False
 
-    creds = get_switch_credentials(environment, api_project_id, custom_port)
+    creds = get_switch_credentials(environment, api_project_id, custom_port, data_center)
 
     logger.info("Successfully initialized.")
     api_base_url = f"https://{creds.api_endpoint}/api/1.0"

{switch_api-0.6.28 → switch_api-0.6.30}/switch_api/integration/__init__.py

@@ -10,12 +10,12 @@ A module for integrating asset creation, asset updates, data ingestion, etc into
 from .integration import (upsert_data, upsert_sites, upsert_workorders, upsert_device_sensors, upsert_device_sensors_ext,
                           upsert_timeseries_ds, replace_data, append_data, upsert_file_row_count,
                           upsert_discovered_records, upsert_timeseries, upsert_tags, upsert_device_metadata,
-                          upsert_reservations, upsert_device_sensors_iq)
+                          upsert_reservations, upsert_device_sensors_iq, upsert_sensor_state_history)
 
 from .helpers import (get_sites, get_tag_groups, get_metadata_keys, get_data, get_device_sensors, get_templates,
                       get_units_of_measure, get_states_by_country, get_operation_state, get_equipment_classes,
                       load_data, get_timezones, amortise_across_days, get_metadata_where_clause, connect_to_sql,
-                      update_last_record_property_value)
+                      update_last_record_property_value, update_sensor_state)
 
 __all__ = ['upsert_data', 'upsert_sites', 'upsert_workorders', 'upsert_device_sensors', 'upsert_device_sensors_ext',
            'upsert_timeseries_ds', 'replace_data', 'append_data', 'get_sites', 'get_tag_groups', 'get_metadata_keys',
@@ -23,4 +23,4 @@ __all__ = ['upsert_data', 'upsert_sites', 'upsert_workorders', 'upsert_device_se
            'get_operation_state', 'get_equipment_classes', 'load_data', 'upsert_file_row_count',
            'upsert_discovered_records', 'upsert_timeseries', 'upsert_tags', 'upsert_device_metadata', 'get_timezones',
            'amortise_across_days', 'get_metadata_where_clause', 'connect_to_sql', 'upsert_reservations', 'upsert_device_sensors_iq',
-           'update_last_record_property_value']
+           'update_last_record_property_value', 'update_sensor_state', 'upsert_sensor_state_history']