fix:PRComments

Author: RSam-NI

examples/alarm/alarm.py

@@ -11,7 +11,7 @@
     SetAlarmTransition,
     TransitionInclusionOption,
 )
-from nisystemlink.clients.core import HttpConfiguration
+from nisystemlink.clients.core import ApiException, HttpConfiguration
 
 # Setup the server configuration to point to your instance of SystemLink Enterprise
 server_configuration = HttpConfiguration(
@@ -75,15 +75,35 @@
 # Acknowledge the alarm
 client.acknowledge_alarms(ids=[id])
 
-# Clear the alarm
+# 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.
+# This allows stateless applications to simply attempt state transitions without first checking
+# the current state. For example, a monitoring system can repeatedly try to CLEAR an alarm
+# when conditions return to normal, and the API will return 409 if already cleared.
 clear_request = CreateOrUpdateAlarmRequest(
     alarm_id=alarm_id,
     transition=ClearAlarmTransition(
         occurred_at=datetime.now(),
         condition="Temperature returned to normal",
     ),
 )
-client.create_or_update_alarm(clear_request)
+try:
+    client.create_or_update_alarm(clear_request)
+    print("Alarm cleared successfully")
+except ApiException as e:
+    if e.http_status_code == 409:
+        print("Alarm is already in the requested state (409 Conflict)")
+    else:
+        raise
+
+# Clear the alarm with 409 conflict handling - Method 2: Using ignore_conflict parameter
+# This approach is cleaner for stateless applications that don't care about 409 errors.
+# Returns None if the alarm is already in the requested state.
+result = client.create_or_update_alarm(clear_request, ignore_conflict=True)
+if result is None:
+    print("No state change needed (alarm already in requested state)")
+else:
+    print(f"Alarm cleared successfully: {result}")
 
 # Delete the alarm by its instance ID
 client.delete_alarm(id)

nisystemlink/clients/alarm/_alarm_client.py

@@ -59,8 +59,9 @@ def acknowledge_alarms(
         """
         ...
 
-    @post("instances", return_key="instanceId")
-    def create_or_update_alarm(self, request: models.CreateOrUpdateAlarmRequest) -> str:
+    def create_or_update_alarm(
+        self, request: models.CreateOrUpdateAlarmRequest, *, ignore_conflict: bool = False
+    ) -> str | None:
         """Creates or updates an instance, or occurrence, of an alarm.
 
         Creates or updates an alarm based on the requested transition and the state
@@ -70,17 +71,38 @@ def create_or_update_alarm(self, request: models.CreateOrUpdateAlarmRequest) ->
         Args:
             request: The request containing alarm_id (user-defined identifier),
                     transition details, and other alarm properties.
+            ignore_conflict: If True, 409 Conflict errors will be ignored and None will be returned.
+                           If False (default), 409 errors will raise an ApiException.
+                           Setting this to True is useful for stateless applications that want to
+                           attempt state transitions without checking the current alarm state first.
 
         Returns:
             The instance_id (unique occurrence identifier) of the created or modified alarm.
             Use this ID for operations like get_alarm(), delete_alarm(), or acknowledge.
+            Returns None if ignore_conflict is True and a 409 Conflict occurs.
 
         Raises:
             ApiException: if unable to communicate with the `/nialarm` Service or provided invalid arguments.
                 A 409 Conflict error occurs when the request does not represent a valid transition
                 for an existing alarm, such as attempting to clear an alarm which is already clear,
                 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:
+            return self._create_or_update_alarm(request)
+
+    @post("instances", return_key="instanceId")
+    def _create_or_update_alarm(
+        self, request: models.CreateOrUpdateAlarmRequest
+    ) -> str:
+        """Internal implementation of create_or_update_alarm."""
         ...
 
     @get("instances/{instance_id}", args=[Path("instance_id")])

tests/integration/alarm/test_alarm_client.py

@@ -454,3 +454,56 @@ def test__create_alarm_with_invalid_severity__raises_ApiException_BadRequest(
         )
         with pytest.raises(ApiException, match="Bad Request"):
             client.create_or_update_alarm(request)
+
+    def test__create_or_update_alarm_with_conflict_and_ignore_conflict_true__returns_none(
+        self,
+        client: AlarmClient,
+        create_alarms: Callable[[str, int, str], str],
+        unique_identifier: Callable[[], str],
+    ):
+        """Test that ignore_conflict=True returns None on 409 Conflict."""
+        alarm_id = unique_identifier()
+
+        # Create an alarm
+        create_alarms(alarm_id, AlarmSeverityLevel.HIGH, "Initial Condition")
+
+        # Try to create another alarm with the same alarm_id and same severity (would cause 409)
+        duplicate_request = CreateOrUpdateAlarmRequest(
+            alarm_id=alarm_id,
+            transition=SetAlarmTransition(
+                occurred_at=datetime.now(timezone.utc),
+                severity_level=AlarmSeverityLevel.HIGH,
+                condition="Initial Condition",
+            ),
+        )
+
+        # With ignore_conflict=True, should return None instead of raising exception
+        result = client.create_or_update_alarm(duplicate_request, ignore_conflict=True)
+        assert result is None
+
+    def test__create_or_update_alarm_with_conflict_and_ignore_conflict_false__raises_exception(
+        self,
+        client: AlarmClient,
+        create_alarms: Callable[[str, int, str], str],
+        unique_identifier: Callable[[], str],
+    ):
+        """Test that ignore_conflict=False (default) raises ApiException on 409 Conflict."""
+        alarm_id = unique_identifier()
+
+        # Create an alarm
+        create_alarms(alarm_id, AlarmSeverityLevel.HIGH, "Initial Condition")
+
+        # Try to create another alarm with the same alarm_id and same severity (would cause 409)
+        duplicate_request = CreateOrUpdateAlarmRequest(
+            alarm_id=alarm_id,
+            transition=SetAlarmTransition(
+                occurred_at=datetime.now(timezone.utc),
+                severity_level=AlarmSeverityLevel.HIGH,
+                condition="Initial Condition",
+            ),
+        )
+
+        # With ignore_conflict=False (default), should raise ApiException
+        with pytest.raises(ApiException) as exc_info:
+            client.create_or_update_alarm(duplicate_request, ignore_conflict=False)
+        assert exc_info.value.http_status_code == 409