fix:PRComments

Author: RSam-NI

examples/alarm/alarm.py

@@ -30,15 +30,17 @@
     transition=SetAlarmTransition(
         occurred_at=datetime.now(),
         severity_level=AlarmSeverityLevel.HIGH,
-        condition="Temperature exceeded threshold",
+        value="85",
+        condition="Greater than 80",
+        short_text="Temperature is high",
+        detail_text="Temperature sensor reading is 85°C (higher than the configured threshold of 80°C)",
     ),
 )
 # Returns instance_id - a server-generated unique identifier for this specific alarm occurrence
 id = client.create_or_update_alarm(create_request)
 
 # Get the alarm by its instance ID (the unique occurrence identifier)
-if id:
-    alarm = client.get_alarm(id)
+alarm = client.get_alarm(instance_id=id)
 print(f"Retrieved alarm: {alarm.alarm_id}, Condition: {alarm.condition}")
 
 # Update the alarm with a higher severity (same alarm_id, updates the same instance)
@@ -47,7 +49,10 @@
     transition=SetAlarmTransition(
         occurred_at=datetime.now(),
         severity_level=AlarmSeverityLevel.CRITICAL,
-        condition="Temperature critically high",
+        value="95",
+        condition="Greater than 90",
+        short_text="Temperature is critical",
+        detail_text="Temperature sensor reading is 95°C (higher than the configured threshold of 90°C)",
     ),
 )
 client.create_or_update_alarm(update_request)
@@ -71,9 +76,8 @@
     for transition in alarm.transitions:
         print(f"- {transition.transition_type}: {transition.condition}")
 
-if id:
-    # Acknowledge the alarm
-    client.acknowledge_alarms(ids=[id])
+# Acknowledge the alarm
+client.acknowledge_alarms(instance_ids=[id])
 
 # Clear the alarm with 409 conflict handling - Method 1: Manual exception handling
 # A 409 Conflict response indicates that the requested transition would not change the alarm's state.
@@ -105,6 +109,5 @@
 else:
     print(f"Alarm cleared successfully: {result}")
 
-if id:
-    # Delete the alarm by its instance ID
-    client.delete_alarm(id)
+# Delete the alarm by its instance ID
+client.delete_alarm(instance_id=id)

nisystemlink/clients/alarm/_alarm_client.py

@@ -1,6 +1,6 @@
 """Implementation of Alarm Client"""
 
-from typing import List
+from typing import List, Literal, overload
 
 from nisystemlink.clients import core
 from nisystemlink.clients.core._uplink._base_client import BaseClient
@@ -39,12 +39,12 @@ def __init__(self, configuration: core.HttpConfiguration | None = None):
         args=[Field("instanceIds"), Field("forceClear")],
     )
     def acknowledge_alarms(
-        self, ids: List[str], *, force_clear: bool = False
+        self, instance_ids: List[str], *, force_clear: bool = False
     ) -> models.AcknowledgeAlarmsResponse:
         """Acknowledges one or more alarm instances by their instance IDs.
 
         Args:
-            ids: List of instance IDs (unique occurrence identifiers) of the alarms to acknowledge.
+            instance_ids: List of instance IDs (unique occurrence identifiers) of the alarms to acknowledge.
                  These are the server-generated IDs returned when creating/updating alarms,
                  not the user-defined alarm_id.
             force_clear: Whether or not the affected alarms should have their clear field set to true.
@@ -59,6 +59,22 @@ def acknowledge_alarms(
         """
         ...
 
+    @overload
+    def create_or_update_alarm(  # noqa: E704
+        self,
+        request: models.CreateOrUpdateAlarmRequest,
+        *,
+        ignore_conflict: Literal[False] = False,
+    ) -> str: ...
+
+    @overload
+    def create_or_update_alarm(  # noqa: E704
+        self,
+        request: models.CreateOrUpdateAlarmRequest,
+        *,
+        ignore_conflict: Literal[True],
+    ) -> str | None: ...
+
     def create_or_update_alarm(
         self,
         request: models.CreateOrUpdateAlarmRequest,
@@ -91,15 +107,12 @@ def create_or_update_alarm(
                 or attempting to set an alarm which is already set at the given severity level.
                 This error can be suppressed by setting ignore_conflict=True.
         """
-        if ignore_conflict:
-            try:
-                return self._create_or_update_alarm(request)
-            except core.ApiException as e:
-                if e.http_status_code == 409:
-                    return None
-                raise
-        else:
+        try:
             return self._create_or_update_alarm(request)
+        except core.ApiException as e:
+            if ignore_conflict and e.http_status_code == 409:
+                return None
+            raise
 
     @post("instances", return_key="instanceId")
     def _create_or_update_alarm(
@@ -109,11 +122,11 @@ def _create_or_update_alarm(
         ...
 
     @get("instances/{instance_id}", args=[Path("instance_id")])
-    def get_alarm(self, id: str) -> models.Alarm:
+    def get_alarm(self, instance_id: str) -> models.Alarm:
         """Gets an alarm by its instance_id.
 
         Args:
-            id: The unique instance ID (occurrence identifier) of the alarm to retrieve.
+            instance_id: The unique instance ID (occurrence identifier) of the alarm to retrieve.
                 This is the server-generated ID returned from create_or_update_alarm(),
                 not the user-defined alarm_id.
 
@@ -126,11 +139,11 @@ def get_alarm(self, id: str) -> models.Alarm:
         ...
 
     @delete("instances/{instance_id}", args=[Path("instance_id")])
-    def delete_alarm(self, id: str) -> None:
+    def delete_alarm(self, instance_id: str) -> None:
         """Deletes an alarm by its instance_id.
 
         Args:
-            id: The unique instance ID (occurrence identifier) of the alarm to delete.
+            instance_id: The unique instance ID (occurrence identifier) of the alarm to delete.
                 This is the server-generated ID returned from create_or_update_alarm(),
                 not the user-defined alarm_id.
 
@@ -140,11 +153,11 @@ def delete_alarm(self, id: str) -> None:
         ...
 
     @post("delete-instances-by-instance-id", args=[Field("instanceIds")])
-    def delete_alarms(self, ids: List[str]) -> models.DeleteAlarmsResponse:
+    def delete_alarms(self, instance_ids: List[str]) -> models.DeleteAlarmsResponse:
         """Deletes multiple alarm instances by their instance IDs.
 
         Args:
-            ids: List of instance IDs (unique occurrence identifiers) of the alarms to delete.
+            instance_ids: List of instance IDs (unique occurrence identifiers) of the alarms to delete.
                  These are the server-generated IDs returned when creating/updating alarms,
                  not the user-defined alarm_id.
 

nisystemlink/clients/alarm/models/_alarm.py

@@ -13,7 +13,7 @@ class AlarmSeverityLevel(IntEnum):
     """
 
     CLEAR = -1
-    """Indicates an alarm clearance."""
+    """Severity level for cleared alarms."""
 
     LOW = 1
     """Low severity level."""
@@ -57,6 +57,7 @@ class AlarmTransition(JsonModel):
     Valid values for CLEAR transitions are [-1, -1].
     Valid values for SET transitions are [1, 2147483647].
     Note that the SystemLink Alarm UI only has display strings for SET severities in the range [1, 4].
+    The AlarmSeverityLevel enum provides values for standard severity levels.
     """
 
     value: str

nisystemlink/clients/alarm/models/_create_or_update_alarm_request.py

@@ -4,7 +4,7 @@
 from nisystemlink.clients.core._uplink._json_model import JsonModel
 from pydantic import model_validator
 
-from ._alarm import AlarmTransitionType
+from ._alarm import AlarmSeverityLevel, AlarmTransitionType
 
 
 class CreateAlarmTransition(JsonModel):
@@ -22,6 +22,7 @@ class CreateAlarmTransition(JsonModel):
     Valid values for CLEAR transitions are [-1, -1].
     Valid values for SET transitions are [1, 2147483647].
     Note that the SystemLink Alarm UI only has display strings for SET severities in the range [1, 4].
+    The AlarmSeverityLevel enum provides values for standard severity levels.
     """
 
     value: str | None = None
@@ -74,12 +75,12 @@ class ClearAlarmTransition(CreateAlarmTransition):
     """
 
     transition_type: AlarmTransitionType = AlarmTransitionType.CLEAR
-    severity_level: int | None = -1
+    severity_level: int | None = AlarmSeverityLevel.CLEAR
 
     @model_validator(mode="after")
     def _set_clear_defaults(self) -> "ClearAlarmTransition":
         self.transition_type = AlarmTransitionType.CLEAR
-        self.severity_level = -1
+        self.severity_level = AlarmSeverityLevel.CLEAR
         return self
 
 
@@ -103,7 +104,11 @@ class CreateOrUpdateAlarmRequest(JsonModel):
     """
 
     transition: CreateAlarmTransition
-    """Contains information about a transition used to create or update an instance of an alarm."""
+    """Contains information about a transition used to create or update an instance of an alarm.
+
+    Consider using SetAlarmTransition to trigger an alarm or ClearAlarmTransition to clear an alarm.
+    These convenience classes automatically set the appropriate transition type and severity level.
+    """
 
     notification_strategy_ids: List[str] | None = None
     """The IDs of the notification strategies which should be triggered.