lvi-api-client 0.2.2__tar.gz → 0.2.4__tar.gz

{lvi_api_client-0.2.2 → lvi_api_client-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvi-api-client
-Version: 0.2.2
+Version: 0.2.4
 Summary: LogicVein API Client Library
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

lvi_api_client-0.2.4/VERSION

@@ -0,0 +1 @@
+0.2.4

{lvi_api_client-0.2.2 → lvi_api_client-0.2.4}/src/logicvein/lvi_api_client.py

@@ -3863,18 +3863,40 @@ class LogicVeinAPIClient:
         return False
 
     def associate_monitor_set(self, set_id: int, host_queries: List[str]) -> bool:
-        """Associate a monitor set with device(s).
+        """Deploy a monitor set to the devices that match every one of the given queries.
 
-        Calls Collection.associateMonitorSet. Returns null on success.
+        Calls Collection.associateMonitorSet. The server answers null whether or not any device
+        matched, so check :meth:`get_monitors_for_host` to know what was deployed.
+
+        The server combines the queries with AND, so one entry for each device matches none of
+        them. Name several devices in one entry, each with its network:
+        ``['ipCsv=192.0.2.1@Default,192.0.2.2@Default']``. An address with no network of its own is
+        not looked up in the network named after a later one. Another query can narrow it:
+        ``['ipCsv=192.0.2.1@Default,192.0.2.2@Default', 'ipAddress=192.0.2.1']``.
+
+        With no queries the server deploys to every device, so that is refused here rather than
+        passed on from an empty list.
 
         Args:
             set_id (int): The ID of the monitor set to associate.
-            host_queries (List[str]): List of host query strings in format 'ipCsv=IP@NetworkName'.
-                Example: ['ipCsv=192.168.1.6@Default']
+            host_queries (List[str]): The queries, at least one, none of them blank, and at most
+                one of them an ``ipCsv`` query.
 
         Returns:
-            bool: True if successful (result is null), otherwise False.
-        """
+            bool: True if the server answered without an error, otherwise False. This does not
+            mean any device matched.
+
+        Raises:
+            ValueError: If there is no query, a query is blank, or more than one is ``ipCsv``.
+                Nothing is sent.
+        """
+        if not host_queries or any(not query.strip() for query in host_queries):
+            raise ValueError("host_queries needs at least one query and no blank ones: none would match every device")
+        if sum(query.strip().startswith("ipCsv=") for query in host_queries) > 1:
+            raise ValueError(
+                "Queries combine with AND, so several ipCsv queries cannot name several devices. "
+                "List them in one: ipCsv=IP@Network,IP@Network"
+            )
         response = self.call("Collection.associateMonitorSet", setId=set_id, hostQueries=host_queries)
 
         if response and isinstance(response, dict) and "result" in response and response["result"] in (None, "None"):
@@ -3891,14 +3913,18 @@ class LogicVeinAPIClient:
         set, or with the ID of an existing monitor, and leaves the old one as it was. Use
         :meth:`save_monitor` to change one.
 
+        The server answers success but stores neither ``disabled`` nor ``hostSpecific`` as true,
+        here or in :meth:`save_monitor`. To stop a monitor on a device, use
+        :meth:`disable_monitor_for_host`.
+
         Each monitor object should have:
             {
                 "monitorId": int - Use -1 for new monitors; assigned ID returned in response,
                 "monitorName": str - Monitor name,
                 "setId": int - Must match set_id,
                 "monitorType": str - Type (e.g. "snmp", "tcp", "icmp", "telegraf", "web", "catchalltrap"),
-                "disabled": bool - Whether the monitor is disabled,
-                "hostSpecific": bool - Whether the monitor is host-specific,
+                "disabled": bool - Stored as false whatever is sent,
+                "hostSpecific": bool - Stored as false whatever is sent,
                 "managedNetworks": list[str] - Networks the monitor belongs to,
                 "retentionPolicy": str - Data retention (e.g. "THREE_MONTHS"),
                 "json": dict - Monitor-type-specific config (OIDs, pollingPeriod, table, triggers, etc.),
@@ -3951,7 +3977,8 @@ class LogicVeinAPIClient:
         Args:
             set_name (str): The set's name. Use :meth:`is_monitor_set_name_unique` to check it first.
             managed_networks (List[str]): The networks the set belongs to, at least one.
-            smart_set (bool): Whether this is a smart set.
+            smart_set (bool): Whether this is a smart set, one applied automatically to newly
+                discovered devices.
 
         Returns:
             Dict[str, Any]: The saved set (``setId``, ``setName``, ``smartSet``,
@@ -4054,7 +4081,9 @@ class LogicVeinAPIClient:
     def save_monitor(self, monitor: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         """Update a monitor in place.
 
-        The monitor keeps its ID, and a device it is deployed to gets the change.
+        The monitor keeps its ID, and a device it is deployed to gets the change. A change to
+        ``disabled`` or ``isHostSpecific`` is answered with success and not stored, and a changed
+        ``monitorType`` is answered with HTTP 500, which raises.
 
         Args:
             monitor (Dict[str, Any]): The whole record as :meth:`get_monitors_for_set` returns
@@ -4076,8 +4105,9 @@ class LogicVeinAPIClient:
             network (str): Network the device belongs to.
 
         Returns:
-            List[Dict[str, Any]]: The monitors, each with ``monitorId``, ``monitorName`` and
-            ``setId``. The list is empty only when the server says the device has none,
+            List[Dict[str, Any]]: The monitors, each with ``monitorId``, ``monitorName``, ``setId``
+            and ``disabled``, which is the state on this device. The list is empty only when the
+            server says the device has none,
             which it also says for a device that does not exist.
 
         Raises:
@@ -4090,6 +4120,68 @@ class LogicVeinAPIClient:
             raise ValueError(f"Collection.getMonitorsForHost did not return a list for device {device_uuid}")
         return monitors
 
+    def disable_monitor_for_host(self, monitor_id: int, device_uuid: str, network: str) -> bool:
+        """Stop a deployed monitor on one device, leaving it deployed and other devices as they are.
+
+        Deploying the set again keeps the monitor disabled, and repeating this does no harm.
+
+        Args:
+            monitor_id (int): ID of the monitor.
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+
+        Returns:
+            bool: True if the device now shows the monitor disabled. False if it does not, as for
+            a monitor not deployed to that device.
+
+        Raises:
+            ValueError: If the device's monitors cannot be read afterwards.
+        """
+        return self._set_monitor_disabled_for_host("disableMonitorForHost", monitor_id, device_uuid, network, True)
+
+    def enable_monitor_for_host(self, monitor_id: int, device_uuid: str, network: str) -> bool:
+        """Start a monitor again on a device where it was disabled.
+
+        Repeating this does no harm.
+
+        Args:
+            monitor_id (int): ID of the monitor.
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+
+        Returns:
+            bool: True if the device now shows the monitor enabled. False if it does not, as for
+            a monitor not deployed to that device.
+
+        Raises:
+            ValueError: If the device's monitors cannot be read afterwards.
+        """
+        return self._set_monitor_disabled_for_host("enableMonitorForHost", monitor_id, device_uuid, network, False)
+
+    def _set_monitor_disabled_for_host(
+        self, method: str, monitor_id: int, device_uuid: str, network: str, disabled: bool
+    ) -> bool:
+        """Call a per-device enable or disable, and read back whether it took effect.
+
+        The server answers null to these whatever happens, even for an unknown monitor or
+        device or the wrong network, so only the device's own monitors can show the outcome.
+
+        Args:
+            method (str): The method's name under Collection.
+            monitor_id (int): ID of the monitor.
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+            disabled (bool): The state the call should leave.
+
+        Returns:
+            bool: Whether the device shows the monitor in that state.
+        """
+        self.call(f"Collection.{method}", monitorId=monitor_id, uuid=device_uuid, network=network)
+        return any(
+            monitor.get("monitorId") == monitor_id and monitor.get("disabled") is disabled
+            for monitor in self.get_monitors_for_host(device_uuid, network)
+        )
+
     def validate_monitor_sets_against_device(
         self, monitor_set_ids: List[int], host_queries: List[str]
     ) -> Dict[str, Any]:

{lvi_api_client-0.2.2 → lvi_api_client-0.2.4}/src/lvi_api_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvi-api-client
-Version: 0.2.2
+Version: 0.2.4
 Summary: LogicVein API Client Library
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

{lvi_api_client-0.2.2 → lvi_api_client-0.2.4}/tests/test_server_request_shapes.py

@@ -543,3 +543,80 @@ class TestCreateRuleSet:
         with pytest.raises(ValueError):
             client.create_rule_set(name, adapter, document, **arguments)
         assert server.requests == []
+
+
+class TestMonitorStateOnADevice:
+    """On a real server these answer null whatever happens, so the device's monitors decide."""
+
+    @pytest.mark.parametrize(
+        "call, method, disabled",
+        [
+            ("disable_monitor_for_host", "Collection.disableMonitorForHost", True),
+            ("enable_monitor_for_host", "Collection.enableMonitorForHost", False),
+        ],
+    )
+    def test_the_request_and_a_read_back_of_the_device(self, connect, call, method, disabled):
+        client, server = connect(
+            {method: None, "Collection.getMonitorsForHost": [{"monitorId": 7, "disabled": disabled}]}
+        )
+        assert getattr(client, call)(7, "u1", "n1") is True
+        assert server.requests == [
+            (method, {"monitorId": 7, "uuid": "u1", "network": "n1"}),
+            ("Collection.getMonitorsForHost", {"uuid": "u1", "network": "n1"}),
+        ]
+
+    @pytest.mark.parametrize(
+        "call, rows",
+        [
+            pytest.param("disable_monitor_for_host", [{"monitorId": 7, "disabled": False}], id="disable did not take"),
+            pytest.param("enable_monitor_for_host", [{"monitorId": 7, "disabled": True}], id="enable did not take"),
+            pytest.param("disable_monitor_for_host", [], id="not on the device"),
+            pytest.param("disable_monitor_for_host", [{"monitorId": 8, "disabled": True}], id="another monitor"),
+            pytest.param(
+                "enable_monitor_for_host", [{"monitorId": 8, "disabled": False}], id="another monitor, enable"
+            ),
+        ],
+    )
+    def test_a_null_answer_is_not_success(self, connect, call, rows):
+        client, _ = connect({"Collection.getMonitorsForHost": rows})
+        assert getattr(client, call)(7, "u1", "n1") is False
+
+    def test_a_failed_read_raises(self, connect):
+        client, _ = connect({"Collection.getMonitorsForHost": None})
+        with pytest.raises(ValueError):
+            client.disable_monitor_for_host(7, "u1", "n1")
+
+
+class TestDeployingASet:
+    """On a real server several ipCsv queries match nothing, and no query matches every device."""
+
+    @pytest.mark.parametrize(
+        "queries",
+        [
+            pytest.param(["ipCsv=192.0.2.1@n1"], id="one device"),
+            pytest.param(["ipCsv=192.0.2.1@n1,192.0.2.2@n1"], id="several devices in one entry"),
+            pytest.param(["ipCsv=192.0.2.1@n1,192.0.2.2@n1", "ipAddress=192.0.2.1"], id="narrowed by another query"),
+            pytest.param(["sysObjectID=1.3.6.1.4.1.9.1.324", "sysDescr=*C2950*"], id="other queries together"),
+        ],
+    )
+    def test_queries_the_server_can_act_on_are_sent_as_given(self, connect, queries):
+        client, server = connect({"Collection.associateMonitorSet": None})
+        assert client.associate_monitor_set(2, queries) is True
+        assert server.sent("Collection.associateMonitorSet") == {"setId": 2, "hostQueries": queries}
+
+    @pytest.mark.parametrize(
+        "queries",
+        [
+            pytest.param([], id="no queries"),
+            pytest.param([""], id="a blank query"),
+            pytest.param(["  "], id="a query of spaces"),
+            pytest.param(["ipCsv=192.0.2.1@n1", ""], id="a blank among others"),
+            pytest.param(["ipCsv=192.0.2.1@n1", "ipCsv=192.0.2.2@n1"], id="one entry per device"),
+            pytest.param(["ipCsv=192.0.2.1@n1", " ipCsv=192.0.2.2@n1"], id="one entry per device, spaced"),
+        ],
+    )
+    def test_queries_that_would_match_everything_or_nothing_are_never_sent(self, connect, queries):
+        client, server = connect({"Collection.associateMonitorSet": None})
+        with pytest.raises(ValueError):
+            client.associate_monitor_set(2, queries)
+        assert server.requests == []

lvi_api_client-0.2.2/VERSION

@@ -1 +0,0 @@
-0.2.2