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

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

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

lvi_api_client-0.2.6/VERSION

@@ -0,0 +1 @@
+0.2.6

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

@@ -3003,6 +3003,7 @@ class LogicVeinAPIClient:
             commands (str): CLI commands to run, one per line.
             job_name (str): Display name for the job.
             backup_on_completion (bool): If True, LVI backs up the device after the job runs.
+            description (str): The job's description. Empty uses ``job_name``.
 
         Returns:
             Dict[str, Any]: The saved job record (contains ``jobId``), or None on failure.
@@ -3011,7 +3012,7 @@ class LogicVeinAPIClient:
             {
                 "jobId": 0,
                 "jobName": job_name,
-                "description": description or "Job scheduled by ServiceNow",
+                "description": description or job_name,
                 "managedNetworks": [network],
                 "jobType": "Script Tool Job",
                 "subType": "org.ziptie.tools.scripts.commandRunner",
@@ -3052,6 +3053,8 @@ class LogicVeinAPIClient:
             network (str): LVI managed network the device belongs to.
             commands (str): CLI commands to run, one per line.
             job_name (str): Display name for the job in the LVI scheduler.
+            backup_on_completion (bool): If True, LVI backs up the device after the job runs.
+            description (str): The job's description. Empty uses ``job_name``.
 
         Returns:
             Dict[str, Any]: The job execution result dict from LVI (contains ``id``
@@ -3071,7 +3074,7 @@ class LogicVeinAPIClient:
                 "tool": "org.ziptie.tools.scripts.commandRunner",
                 "backupOnCompletion": "true" if backup_on_completion else "false",
             },
-            description=description or "Job scheduled by ServiceNow",
+            description=description or job_name,
         )
 
     # =====================================================
@@ -3863,18 +3866,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. The server answers null whether or not any device
+        matched, so check :meth:`get_monitors_for_host` to know what was deployed.
 
-        Calls Collection.associateMonitorSet. Returns null on success.
+        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 +3916,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 +3980,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 +4084,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 +4108,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 +4123,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]:
@@ -4528,27 +4623,32 @@ class LogicVeinAPIClient:
         where ``recordId`` is the ``id`` field from a ``getExecutionDetails``
         record.
 
+        The server finds the output by ``recordId`` alone: a record of another
+        execution comes back as long as the execution ID exists.
+
         Args:
             execution_id: The execution ID (``executionId`` from the job result).
             record_id: The per-device record ID (``id`` from ``getExecutionDetails``).
 
         Returns:
-            The raw output text, or an empty string if the request fails.
+            The raw output text.
+
+        Raises:
+            requests.HTTPError: If the server refuses the request, for example
+                401 for a bad token, 404 for an unknown execution or 500 for a
+                malformed ID.
+            ValueError: If the server has no record with that ID. It answers
+                200 with an empty body and no content type then, which is not
+                an empty output: a Command Runner output holds at least the
+                command and the prompt.
         """
         url = f"https://{self.host}/servlet/pluginDetail"
         params = {"executionId": execution_id, "recordId": record_id}
-        try:
-            response = self.lvi_client.get(url, params=params, timeout=self.timeout)
-            response.raise_for_status()
-            return response.text
-        except Exception as exc:
-            logger.warning(
-                "get_execution_output failed for executionId=%s recordId=%s: %s",
-                execution_id,
-                record_id,
-                exc,
-            )
-            return ""
+        response = self.lvi_client.get(url, params=params, timeout=self.timeout)
+        response.raise_for_status()
+        if not response.content and not response.headers.get("Content-Type"):
+            raise ValueError(f"No output record {record_id} in execution {execution_id}")
+        return response.text
 
     # =====================================================
     # ZeroTouch

{lvi_api_client-0.2.2 → lvi_api_client-0.2.6}/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.6
 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.6}/tests/test_lvi_api_client.py

@@ -5048,7 +5048,7 @@ class TestCreateCommandRunnerJob:
 
 
 class TestGetExecutionOutput:
-    """Tests for get_execution_output (lines 3641-3674): success and exception paths."""
+    """Tests for get_execution_output: the text on success, and an error for every failure."""
 
     @pytest.fixture
     def client(self, monkeypatch):
@@ -5057,39 +5057,50 @@ class TestGetExecutionOutput:
         with patch("src.logicvein.lvi_api_client.requests.Session"):
             return LogicVeinAPIClient()
 
+    @staticmethod
+    def answer(status, body=b"", content_type=None):
+        """A real requests.Response, shaped like the lab server's answers (issue #6)."""
+        response = requests.Response()
+        response.status_code = status
+        response._content = body
+        response.encoding = "utf-8"
+        if content_type:
+            response.headers["Content-Type"] = content_type
+        response.url = "https://test.example.com/servlet/pluginDetail"
+        return response
+
     def test_get_execution_output_success(self, client):
-        """get_execution_output returns response text on success."""
-        mock_get_response = Mock()
-        mock_get_response.raise_for_status = Mock()
-        mock_get_response.text = "show version output\nCisco IOS Version 15.1"
-        client.lvi_client.get = Mock(return_value=mock_get_response)
+        """get_execution_output returns the text, and asks for the execution and record."""
+        output = b"show clock\r\n16:57:34.919 UTC Sat Nov 7 2026\r\nc1800#"
+        client.lvi_client.get = Mock(return_value=self.answer(200, output, "text/plain;charset=utf-8"))
 
         result = client.get_execution_output(execution_id=42, record_id=7)
 
-        assert result == "show version output\nCisco IOS Version 15.1"
-        client.lvi_client.get.assert_called_once()
-        call_args = client.lvi_client.get.call_args
-        assert "executionId" in call_args.kwargs["params"]
-        assert call_args.kwargs["params"]["executionId"] == 42
-        assert call_args.kwargs["params"]["recordId"] == 7
+        assert result == output.decode()
+        assert client.lvi_client.get.call_args.kwargs["params"] == {"executionId": 42, "recordId": 7}
 
-    def test_get_execution_output_http_error_returns_empty_string(self, client):
-        """get_execution_output returns '' when raise_for_status raises."""
-        mock_get_response = Mock()
-        mock_get_response.raise_for_status.side_effect = requests.HTTPError("403 Forbidden")
-        client.lvi_client.get = Mock(return_value=mock_get_response)
+    @pytest.mark.parametrize("status", [401, 404, 500])
+    def test_get_execution_output_http_error_raises(self, client, status):
+        """A refused read raises instead of reading as an empty output (issue #6)."""
+        page = b"<!doctype html><html></html>"
+        client.lvi_client.get = Mock(return_value=self.answer(status, page, "text/html;charset=utf-8"))
 
-        result = client.get_execution_output(execution_id=42, record_id=7)
+        with pytest.raises(requests.HTTPError):
+            client.get_execution_output(execution_id=42, record_id=7)
 
-        assert result == ""
+    def test_get_execution_output_unknown_record_raises(self, client):
+        """The server answers an unknown record with 200, no body and no content type (issue #6)."""
+        client.lvi_client.get = Mock(return_value=self.answer(200))
 
-    def test_get_execution_output_connection_error_returns_empty_string(self, client):
-        """get_execution_output returns '' when a connection exception is raised."""
-        client.lvi_client.get = Mock(side_effect=requests.exceptions.ConnectionError("refused"))
+        with pytest.raises(ValueError, match="No output record 7 in execution 42"):
+            client.get_execution_output(execution_id=42, record_id=7)
 
-        result = client.get_execution_output(execution_id=99, record_id=1)
+    def test_get_execution_output_connection_error_raises(self, client):
+        """A transport failure propagates instead of reading as an empty output (issue #6)."""
+        client.lvi_client.get = Mock(side_effect=requests.exceptions.ConnectionError("refused"))
 
-        assert result == ""
+        with pytest.raises(requests.exceptions.ConnectionError):
+            client.get_execution_output(execution_id=99, record_id=1)
 
 
 class TestRunCommandRunnerJob:
@@ -5121,6 +5132,27 @@ class TestRunCommandRunnerJob:
         assert result["executionId"] == "exec-77"
         client.lvi_client.post.assert_called_once()
 
+    def test_run_command_runner_job_describes_the_job_by_its_name(self, client, mock_response):
+        """An empty description uses the job name, not "Job scheduled by ServiceNow" (issue #5)."""
+        mock_response.json.return_value = {"jsonrpc": "2.0", "id": "t", "result": {"executionId": 1}}
+        client.lvi_client.post = Mock(return_value=mock_response)
+
+        client.run_command_runner_job("10.1.1.1", "Default", "show version", job_name="NTP check")
+
+        body = json.loads(client.lvi_client.post.call_args.kwargs["data"])
+        assert body["method"] == "Scheduler.runNow"
+        assert body["params"]["jobData"]["description"] == "NTP check"
+
+    def test_run_command_runner_job_keeps_a_given_description(self, client, mock_response):
+        """A description the caller gives is sent as it is."""
+        mock_response.json.return_value = {"jsonrpc": "2.0", "id": "t", "result": {"executionId": 1}}
+        client.lvi_client.post = Mock(return_value=mock_response)
+
+        client.run_command_runner_job("10.1.1.1", "Default", "show version", description="Change 42")
+
+        body = json.loads(client.lvi_client.post.call_args.kwargs["data"])
+        assert body["params"]["jobData"]["description"] == "Change 42"
+
     def test_run_command_runner_job_with_backup(self, client, mock_response):
         """run_command_runner_job passes backup_on_completion=True in job parameters."""
         mock_response.json.return_value = {
@@ -5201,15 +5233,15 @@ class TestCreateCommandRunnerJobBackupAndDescription:
         body = json.loads(client.lvi_client.post.call_args.kwargs["data"])
         assert body["params"]["jobData"]["description"] == "My custom description"
 
-    def test_empty_description_defaults_to_service_now_string(self, client, mock_response):
-        """create_command_runner_job defaults description when empty string passed."""
+    def test_empty_description_defaults_to_the_job_name(self, client, mock_response):
+        """create_command_runner_job describes the job by its name, not by any one caller (issue #5)."""
         mock_response.json.return_value = {"jsonrpc": "2.0", "id": "t", "result": {"jobId": 12}}
         client.lvi_client.post = Mock(return_value=mock_response)
 
-        client.create_command_runner_job("10.1.1.1", "Default", "show version", description="")
+        client.create_command_runner_job("10.1.1.1", "Default", "show version", job_name="NTP check", description="")
 
         body = json.loads(client.lvi_client.post.call_args.kwargs["data"])
-        assert body["params"]["jobData"]["description"] == "Job scheduled by ServiceNow"
+        assert body["params"]["jobData"]["description"] == "NTP check"
 
 
 class TestRunJobNowSubTypeBranch:

{lvi_api_client-0.2.2 → lvi_api_client-0.2.6}/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