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

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

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

lvi_api_client-0.2.9/VERSION

@@ -0,0 +1 @@
+0.2.9

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

@@ -3,7 +3,7 @@ import json
 import logging
 import os
 import re
-from typing import Any, Dict, List, MutableMapping, Optional, Sequence, Tuple, Union
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
 from xml.etree import ElementTree
 from xml.sax.saxutils import escape
 
@@ -211,7 +211,10 @@ class LogicVeinAPIClient:
             f"LogicVeinAPIClient initialized: host={self.host}, username={self.username}, using_token={bool(self.api_token)}, ignore_env={ignore_env}"
         )
         self.base_url = f"https://{self.host}/rest"
-        self.headers: MutableMapping[str, Union[str, bytes]] = {"Content-Type": "application/json"}
+        # The session holds this same mapping, so its headers are exactly these (requests' defaults are not sent).
+        self.headers: requests.structures.CaseInsensitiveDict[str] = requests.structures.CaseInsensitiveDict(
+            {"Content-Type": "application/json"}
+        )
         if self.api_token:
             self.headers["Authorization"] = f"Bearer {self.api_token}"
         self.lvi_client = requests.Session()
@@ -1840,7 +1843,8 @@ class LogicVeinAPIClient:
                 "summary": str - Incident summary,
                 "severity": str - "INFO", "WARNING", "ERROR", or "CRITICAL",
                 "priority": str - "LOW", "MEDIUM", "HIGH", or "CRITICAL",
-                "status": str - "OPEN", "WORKING", or "CLOSED",
+                "status": str - "OPEN", "RESOLVED" or "DEFERRED" seen on a server; whether
+                    "WORKING" or "CLOSED" exist has not been measured,
                 "resolution": str - "PENDING" or "RESOLVED",
                 "assignee": str - Assigned username (empty string if unassigned),
                 "labels": list[str] - Label tags,
@@ -1875,14 +1879,15 @@ class LogicVeinAPIClient:
     # Incidents
     # =====================================================
 
-    def get_incident_by_id(self, incident_id: int) -> Dict[str, Any]:
+    def get_incident_by_id(self, incident_id: int) -> Optional[Dict[str, Any]]:
         """Get an incident by its ID from the LogicVein server.
 
         Args:
             incident_id (int): The ID of the incident.
 
         Returns:
-            Dict[str, Any]: The incident if it exists, otherwise an empty dictionary.
+            Dict[str, Any]: The incident, or None for an unknown ID, which the server answers with
+            a null result. An empty dictionary only when the server gives no result at all.
         """
         response = self.call("Incidents.getIncidentById", incidentId=incident_id)
 
@@ -2549,6 +2554,8 @@ class LogicVeinAPIClient:
     def delete_managed_network(self, network_name: str) -> bool:
         """Delete a managed network from the LogicVein server.
 
+        An alert policy whose only network this is goes with it.
+
         Args:
             network_name (str): The name of the managed network to delete.
 
@@ -3648,6 +3655,8 @@ class LogicVeinAPIClient:
         """Get actions configured for an alert policy.
 
         Calls Collection.getActionsForPolicy. Returns the result list directly (not paginated).
+        Settings come back as stored, secrets included: an exec action's ``password`` and a
+        trap action's ``community`` are not masked, and the web UI sends them back unchanged.
         Each action has:
             {
                 "actionId": int - Action ID,
@@ -3677,6 +3686,10 @@ class LogicVeinAPIClient:
         Returns the saved actions with assigned actionIds (new actions use -1 as input id,
         which is replaced with the assigned ID in the response).
 
+        The saved actions **replace** all of the policy's actions; they are not added to them.
+        An empty list does nothing, so it cannot clear a policy's actions. ``username`` is
+        filled in with the caller's when left out.
+
         Each action object should have:
             {
                 "actionId": int - Use -1 for new actions,
@@ -4288,6 +4301,33 @@ class LogicVeinAPIClient:
         Returns:
             List[Dict[str, Any]]: All matching alert policies.
         """
+        return self._search_alert_policies(managed_networks, queries, sort_column, descending, page_size, strict=False)
+
+    def _search_alert_policies(
+        self,
+        managed_networks: List[str],
+        queries: List[str],
+        sort_column: str,
+        descending: bool,
+        page_size: int,
+        strict: bool,
+    ) -> List[Dict[str, Any]]:
+        """Read every page of alert policies.
+
+        Args:
+            managed_networks (List[str]): Networks to search. Empty for all.
+            queries (List[str]): Query filters.
+            sort_column (str): Column to sort by.
+            descending (bool): Sort descending if True.
+            page_size (int): Records per API call.
+            strict (bool): Raise on an answer with no policies list, rather than stopping there.
+
+        Returns:
+            List[Dict[str, Any]]: All matching alert policies.
+
+        Raises:
+            ValueError: If ``strict`` and an answer has no policies list.
+        """
         all_policies: List[Dict[str, Any]] = []
         offset = 0
 
@@ -4306,8 +4346,11 @@ class LogicVeinAPIClient:
             }
             response = self.call("Collection.searchAlertPolicies", **params)
 
-            if response and isinstance(response, dict) and "result" in response and "policies" in response["result"]:
-                batch = response["result"]["policies"]
+            result = response.get("result") if isinstance(response, dict) else None
+            if isinstance(result, dict) and isinstance(result.get("policies"), list):
+                batch = result["policies"]
+            elif strict:
+                raise ValueError("Collection.searchAlertPolicies did not answer with a list of policies")
             else:
                 break
 
@@ -4325,6 +4368,12 @@ class LogicVeinAPIClient:
 
         Calls Collection.saveAlertPolicy. The response mirrors the input policy object.
         Use policyId=-1 (or omit) to create a new policy; provide an existing policyId to update.
+        The result carries the new policy's ID.
+
+        Saving an existing policy **removes all its actions**, although ``actionTypes`` still
+        lists them: save them again with :meth:`save_alert_actions`, as the web UI does. Saving
+        a name that is already in use makes a second policy of that name; check with
+        :meth:`is_alert_policy_name_unique` first.
 
         The policy object has:
             {
@@ -4347,6 +4396,117 @@ class LogicVeinAPIClient:
             return response["result"]
         return None
 
+    def delete_alert_policy(self, policy_id: int, reassign_policy_id: int = -1) -> bool:
+        """Delete an alert policy, with its actions, refusing one still in use.
+
+        A policy that alert triggers still use (:meth:`is_alert_policy_referenced`) may not be
+        deleted on its own: as in the web UI, which asks for an alternate policy to take those
+        triggers, ``reassign_policy_id`` must name another existing policy. Otherwise this
+        raises before deleting anything.
+
+        Calls Collection.deleteAlertPolicy with ``policyId`` and ``reassignPolicyId``, as the UI
+        does; the server refuses ``policyId`` alone. It answers true when it deletes the policy
+        and false for an unknown ID. The policies are then read back, and the result is whether
+        this one is gone: an answer that cannot show it raises rather than reading as deleted.
+        Errors from the calls themselves (``LogicVeinAPIError``, ``requests`` errors) propagate.
+
+        Args:
+            policy_id (int): The ID of the policy to delete.
+            reassign_policy_id (int): The policy to move its triggers to, required when the
+                policy is in use; -1 for none.
+
+        Returns:
+            bool: True if the policy is gone afterwards.
+
+        Raises:
+            ValueError: If the policy is in use and no other existing policy is given to take
+                its triggers, if the policies cannot be read (an answer with no list of policies,
+                or a policy without an ID), or if the reference check does not answer true or false.
+        """
+        if reassign_policy_id == policy_id:
+            raise ValueError(f"Alert policy {policy_id} cannot take its own triggers; name another policy")
+        in_use = self.is_alert_policy_referenced(policy_id)
+        if reassign_policy_id != -1:
+            if reassign_policy_id not in self._alert_policy_ids():
+                raise ValueError(f"Alert policy {reassign_policy_id}, to take the triggers, does not exist")
+        elif in_use:
+            raise ValueError(
+                f"Alert policy {policy_id} is used by alert triggers, so it may not be deleted until another "
+                "policy takes them: pass reassign_policy_id"
+            )
+        self.call("Collection.deleteAlertPolicy", policyId=policy_id, reassignPolicyId=reassign_policy_id)
+        return policy_id not in self._alert_policy_ids()
+
+    def _alert_policy_ids(self) -> List[int]:
+        """Read the IDs of every alert policy, failing on an answer that cannot list them.
+
+        Returns:
+            List[int]: The IDs.
+
+        Raises:
+            ValueError: If the answer has no list of policies, or a policy without an ID.
+        """
+        policies = self._search_alert_policies([], [], "policyName", False, 500, strict=True)
+        ids = [policy.get("policyId") if isinstance(policy, dict) else None for policy in policies]
+        known = [found for found in ids if isinstance(found, int)]
+        if len(known) != len(ids):
+            raise ValueError("Collection.searchAlertPolicies answered with a policy that has no ID")
+        return known
+
+    def is_alert_policy_referenced(self, policy_id: int) -> bool:
+        """Check whether anything refers to an alert policy.
+
+        Calls Collection.isAlertPolicyReferenced, which the web UI calls before deleting one: a
+        policy in use may only be deleted with another policy to take its alert triggers (see
+        :meth:`delete_alert_policy`). On the lab, a policy no monitor trigger names also
+        answered true, so more than monitor triggers count. An unknown ID answers false.
+
+        Args:
+            policy_id (int): The ID of the policy.
+
+        Returns:
+            bool: True if the policy is referenced.
+
+        Raises:
+            ValueError: If the server's answer is not true or false.
+        """
+        response = self.call("Collection.isAlertPolicyReferenced", policyId=policy_id)
+        referenced = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(referenced, bool):
+            raise ValueError(f"Collection.isAlertPolicyReferenced did not answer true or false for {policy_id}")
+        return referenced
+
+    def is_alert_policy_name_unique(
+        self, policy_name: str, managed_networks: List[str], ignore_policy_id: int = -1
+    ) -> bool:
+        """Check whether an alert policy name is free in some networks.
+
+        Calls Collection.isAlertPolicyNameUnique, with the parameters the web UI sends as a
+        name is typed. :meth:`save_alert_policy` does not check: it saves a second policy of
+        a name in use.
+
+        Args:
+            policy_name (str): The name to check.
+            managed_networks (List[str]): The networks to check it in.
+            ignore_policy_id (int): A policy to leave out, such as the one being renamed. -1 for none.
+
+        Returns:
+            bool: True if the name is free.
+
+        Raises:
+            ValueError: If the server's answer is not true or false.
+        """
+        response = self.call(
+            "Collection.isAlertPolicyNameUnique",
+            policyName=policy_name,
+            managedNetworks=managed_networks,
+            ignorePolicyId=ignore_policy_id,
+        )
+        unique = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(unique, bool):
+            raise ValueError(f"Collection.isAlertPolicyNameUnique did not answer true or false for {policy_name}")
+        return unique
+
     # =====================================================
     # Maps / Topology
     # =====================================================

{lvi_api_client-0.2.6 → lvi_api_client-0.2.9}/src/lvi_api_client.egg-info/PKG-INFO

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

{lvi_api_client-0.2.6 → lvi_api_client-0.2.9}/src/lvi_api_client.egg-info/SOURCES.txt

@@ -9,5 +9,6 @@ src/lvi_api_client.egg-info/SOURCES.txt
 src/lvi_api_client.egg-info/dependency_links.txt
 src/lvi_api_client.egg-info/requires.txt
 src/lvi_api_client.egg-info/top_level.txt
+tests/test_check_version_bump.py
 tests/test_lvi_api_client.py
 tests/test_server_request_shapes.py

lvi_api_client-0.2.9/tests/test_check_version_bump.py

@@ -0,0 +1,62 @@
+"""Tests for scripts/ci/check_version_bump.py."""
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_PATH = Path(__file__).resolve().parent.parent / "scripts" / "ci" / "check_version_bump.py"
+_SPEC = importlib.util.spec_from_file_location("check_version_bump", _PATH)
+assert _SPEC is not None and _SPEC.loader is not None, _PATH
+check = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(check)
+
+LOG = "# Changelog\n\n## [0.2.7] - 2026-11-08\n\n### Fixed\n- Something.\n\n## [0.2.6] - 2026-11-07\n"
+
+
+def test_a_heading_for_the_version_passes():
+    assert check.changelog_problem(LOG, "0.2.7") == ""
+
+
+@pytest.mark.parametrize(
+    "changelog",
+    [
+        "## [Unreleased]\n\n### Fixed\n- Something.\n\n## [0.2.6] - 2026-11-07\n",
+        "Fixed in [0.2.7], see below.\n## [0.2.6]\n",
+        "## [0.2.70] - 2026-11-08\n",
+    ],
+    ids=["only unreleased", "not a heading", "another version"],
+)
+def test_no_heading_for_the_version_fails(changelog):
+    assert "no '## [0.2.7]' heading" in check.changelog_problem(changelog, "0.2.7")
+
+
+def _run(monkeypatch, tmp_path, changed, version, changelog, base_version="0.2.6"):
+    (tmp_path / "VERSION").write_text(version + "\n")
+    (tmp_path / "CHANGELOG.md").write_text(changelog)
+    monkeypatch.setattr(check, "REPO_ROOT", tmp_path)
+
+    def git(*args):
+        return "\n".join(changed) if args[0] == "diff" else base_version + "\n"
+
+    monkeypatch.setattr(check, "_git", git)
+    monkeypatch.setattr("sys.argv", ["check_version_bump.py", "--base", "abc123"])
+    return check.main()
+
+
+def test_a_bump_with_entries_left_under_unreleased_fails(monkeypatch, tmp_path, capsys):
+    changelog = "## [Unreleased]\n\n### Fixed\n- Something.\n"
+    assert _run(monkeypatch, tmp_path, ["src/x.py", "VERSION", "CHANGELOG.md"], "0.2.7", changelog) == 1
+    assert "no '## [0.2.7]' heading" in capsys.readouterr().out
+
+
+def test_a_bump_without_a_src_change_still_needs_the_heading(monkeypatch, tmp_path):
+    assert _run(monkeypatch, tmp_path, ["VERSION"], "0.2.7", "## [0.2.6]\n") == 1
+
+
+def test_a_bump_with_its_heading_passes(monkeypatch, tmp_path):
+    assert _run(monkeypatch, tmp_path, ["src/x.py", "VERSION", "CHANGELOG.md"], "0.2.7", LOG) == 0
+
+
+def test_a_docs_change_needs_nothing(monkeypatch, tmp_path):
+    assert _run(monkeypatch, tmp_path, ["CHANGELOG.md", "README.md"], "0.2.6", "## [Unreleased]\n") == 0

{lvi_api_client-0.2.6 → lvi_api_client-0.2.9}/tests/test_lvi_api_client.py

@@ -48,6 +48,16 @@ class TestLogicVeinAPIClientUnit:
             assert "Authorization" in client.headers
             assert client.headers["Authorization"] == "Bearer test-token-123"
 
+    def test_the_session_sends_only_the_clients_headers(self, mock_env):
+        """The session holds the client's own header mapping, with no requests defaults added."""
+        client = LogicVeinAPIClient()
+        assert client.lvi_client.headers is client.headers
+        assert dict(client.lvi_client.headers) == {
+            "Content-Type": "application/json",
+            "Authorization": "Bearer test-token-123",
+        }
+        assert client.lvi_client.headers["content-type"] == "application/json"
+
     def test_initialization_with_kwargs(self, monkeypatch):
         """Test client initialization with kwargs instead of env vars."""
         # Clear env vars so kwargs take precedence

{lvi_api_client-0.2.6 → lvi_api_client-0.2.9}/tests/test_server_request_shapes.py

@@ -620,3 +620,116 @@ class TestDeployingASet:
         with pytest.raises(ValueError):
             client.associate_monitor_set(2, queries)
         assert server.requests == []
+
+
+class TestAlertPolicies:
+    """Deleting alert policies and the checks the web UI makes around saving and deleting them."""
+
+    @staticmethod
+    def listing(*ids):
+        return {"policies": [{"policyId": i, "policyName": f"p{i}"} for i in ids]}
+
+    def test_a_delete_of_a_policy_not_in_use_sends_what_the_ui_sends_and_reads_the_policies_back(self, connect):
+        client, server = connect(
+            {
+                "Collection.isAlertPolicyReferenced": False,
+                "Collection.deleteAlertPolicy": True,
+                "Collection.searchAlertPolicies": self.listing(1),
+            }
+        )
+        assert client.delete_alert_policy(65) is True
+        assert server.sent("Collection.isAlertPolicyReferenced") == {"policyId": 65}
+        assert server.sent("Collection.deleteAlertPolicy") == {"policyId": 65, "reassignPolicyId": -1}
+        assert server.sent("Collection.searchAlertPolicies")["managedNetworks"] == []
+
+    def test_a_policy_still_listed_after_a_delete_is_not_deleted(self, connect):
+        client, _ = connect(
+            {
+                "Collection.isAlertPolicyReferenced": False,
+                "Collection.deleteAlertPolicy": False,
+                "Collection.searchAlertPolicies": self.listing(65),
+            }
+        )
+        assert client.delete_alert_policy(65) is False
+
+    def test_a_policy_in_use_is_not_deleted_without_a_policy_to_take_its_triggers(self, connect):
+        client, server = connect({"Collection.isAlertPolicyReferenced": True})
+        with pytest.raises(ValueError, match="used by alert triggers"):
+            client.delete_alert_policy(65)
+        assert [method for method, _ in server.requests] == ["Collection.isAlertPolicyReferenced"]
+
+    def test_a_policy_in_use_is_deleted_with_another_to_take_its_triggers(self, connect):
+        client, server = connect(
+            {
+                "Collection.isAlertPolicyReferenced": True,
+                "Collection.deleteAlertPolicy": True,
+                "Collection.searchAlertPolicies": self.listing(1, 65),
+            }
+        )
+        # The read-back still lists 65 because this fake does not delete; what matters is the request.
+        client.delete_alert_policy(65, reassign_policy_id=1)
+        assert server.sent("Collection.deleteAlertPolicy") == {"policyId": 65, "reassignPolicyId": 1}
+
+    @pytest.mark.parametrize("reassign", [65, 2])
+    def test_a_policy_to_take_the_triggers_must_be_another_that_exists(self, connect, reassign):
+        client, server = connect(
+            {"Collection.isAlertPolicyReferenced": True, "Collection.searchAlertPolicies": self.listing(1, 65)}
+        )
+        with pytest.raises(ValueError):
+            client.delete_alert_policy(65, reassign_policy_id=reassign)
+        assert "Collection.deleteAlertPolicy" not in [method for method, _ in server.requests]
+
+    def test_a_reference_check_with_no_answer_deletes_nothing(self, connect):
+        client, server = connect({"Collection.isAlertPolicyReferenced": None})
+        with pytest.raises(ValueError):
+            client.delete_alert_policy(65)
+        assert "Collection.deleteAlertPolicy" not in [method for method, _ in server.requests]
+
+    @pytest.mark.parametrize(
+        "answer", [None, {}, {"policies": None}, {"policies": [{}]}, {"policies": [{"policyId": None}, "x"]}]
+    )
+    def test_a_failed_read_back_raises_rather_than_reading_as_deleted(self, connect, answer):
+        client, _ = connect(
+            {
+                "Collection.isAlertPolicyReferenced": False,
+                "Collection.deleteAlertPolicy": True,
+                "Collection.searchAlertPolicies": answer,
+            }
+        )
+        with pytest.raises(ValueError):
+            client.delete_alert_policy(65)
+
+    def test_a_failed_search_still_reads_as_no_policies(self, connect):
+        client, _ = connect({"Collection.searchAlertPolicies": None})
+        assert client.search_alert_policies() == []
+
+    @pytest.mark.parametrize("answer", [True, False])
+    def test_a_reference_check_sends_the_id_and_returns_the_answer(self, connect, answer):
+        client, server = connect({"Collection.isAlertPolicyReferenced": answer})
+        assert client.is_alert_policy_referenced(27) is answer
+        assert server.sent("Collection.isAlertPolicyReferenced") == {"policyId": 27}
+
+    def test_a_reference_check_with_no_answer_raises_rather_than_reading_as_unreferenced(self, connect):
+        client, _ = connect({"Collection.isAlertPolicyReferenced": None})
+        with pytest.raises(ValueError):
+            client.is_alert_policy_referenced(27)
+
+    @pytest.mark.parametrize("answer", [True, False])
+    def test_a_name_check_sends_what_the_ui_sends_and_returns_the_answer(self, connect, answer):
+        client, server = connect({"Collection.isAlertPolicyNameUnique": answer})
+        assert client.is_alert_policy_name_unique("p1", ["Default"], ignore_policy_id=1) is answer
+        assert server.sent("Collection.isAlertPolicyNameUnique") == {
+            "policyName": "p1",
+            "managedNetworks": ["Default"],
+            "ignorePolicyId": 1,
+        }
+
+    def test_a_name_check_ignores_no_policy_by_default(self, connect):
+        client, server = connect({"Collection.isAlertPolicyNameUnique": True})
+        client.is_alert_policy_name_unique("p1", ["Default"])
+        assert server.sent("Collection.isAlertPolicyNameUnique")["ignorePolicyId"] == -1
+
+    def test_a_name_check_with_no_answer_raises_rather_than_reading_as_taken(self, connect):
+        client, _ = connect({"Collection.isAlertPolicyNameUnique": None})
+        with pytest.raises(ValueError):
+            client.is_alert_policy_name_unique("p1", ["Default"])

lvi_api_client-0.2.6/VERSION

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