opennms-api-wrapper 0.2.0__py3-none-any.whl

opennms_api_wrapper/__init__.py

@@ -0,0 +1,10 @@
+"""opennms_api_wrapper – a thin Python wrapper for the OpenNMS REST API."""
+from .client import OpenNMS
+from importlib.metadata import version, PackageNotFoundError
+
+__all__ = ["OpenNMS"]
+
+try:
+    __version__ = version("opennms-api-wrapper")
+except PackageNotFoundError:
+    __version__ = "unknown"

opennms_api_wrapper/_acks.py

@@ -0,0 +1,52 @@
+"""Acknowledgements REST API – /rest/acks."""
+
+
+class AcksMixin:
+    def get_acks(self, limit: int = 10, offset: int = 0, **filters):
+        """List acknowledgements.
+
+        Args:
+            limit: Max number of results to return. Use ``0`` for all.
+            offset: Zero-based offset for pagination.
+            **filters: Additional Hibernate query filters passed directly as query parameters (e.g. ``severity="MAJOR"``).
+        """
+        params = {"limit": limit, "offset": offset}
+        params.update(filters)
+        return self._get("acks", params=params)
+
+    def get_ack(self, ack_id: int):
+        """Return the acknowledgement with the given ID."""
+        return self._get(f"acks/{ack_id}")
+
+    def get_ack_count(self) -> int:
+        """Return the total number of acknowledgements."""
+        return self._get("acks/count")
+
+    # Write (form-encoded POST)
+
+    def create_ack(self, action: str, alarm_id: int = None,
+                   notification_id: int = None):
+        """Create or modify an acknowledgement.
+
+        Args:
+            action: One of ``"ack"``, ``"unack"``, ``"clear"``, ``"esc"``.
+            alarm_id: Target alarm ID (mutually exclusive with
+                notification_id).
+            notification_id: Target notification ID.
+        """
+        data = {"action": action}
+        if alarm_id is not None:
+            data["alarmId"] = alarm_id
+        if notification_id is not None:
+            data["notifId"] = notification_id
+        return self._post("acks", form_data=data)
+
+    # Convenience wrappers
+
+    def ack_notification(self, notification_id: int):
+        """Acknowledge notification *notification_id*."""
+        return self.create_ack("ack", notification_id=notification_id)
+
+    def unack_notification(self, notification_id: int):
+        """Remove acknowledgement from notification *notification_id*."""
+        return self.create_ack("unack", notification_id=notification_id)

opennms_api_wrapper/_alarm_history.py

@@ -0,0 +1,30 @@
+"""Alarm History REST API – /rest/alarms/history."""
+
+
+class AlarmHistoryMixin:
+    def get_alarm_history(self, at: int = None):
+        """Return last known state of all active alarms.
+
+        Args:
+            at: Optional millisecond epoch timestamp for historical lookup.
+        """
+        params = {}
+        if at is not None:
+            params["at"] = at
+        return self._get("alarms/history", params=params or None)
+
+    def get_alarm_history_at(self, alarm_id: int, at: int = None):
+        """Return final known state of *alarm_id* (optionally at a point in time).
+
+        Args:
+            alarm_id: The alarm database ID.
+            at: Optional millisecond epoch timestamp.
+        """
+        params = {}
+        if at is not None:
+            params["at"] = at
+        return self._get(f"alarms/history/{alarm_id}", params=params or None)
+
+    def get_alarm_history_states(self, alarm_id: int):
+        """Return all state transitions for *alarm_id*."""
+        return self._get(f"alarms/history/{alarm_id}/states")

opennms_api_wrapper/_alarm_stats.py

@@ -0,0 +1,24 @@
+"""Alarm Statistics REST API – /rest/stats/alarms."""
+
+
+class AlarmStatsMixin:
+    def get_alarm_stats(self, **filters):
+        """Return alarm statistics.
+
+        Args:
+            **filters: Additional Hibernate query filters passed directly as query parameters (e.g. ``severity="MAJOR"``).
+                Supports the same filter parameters as ``get_alarms()``.
+        """
+        return self._get("stats/alarms", params=filters or None)
+
+    def get_alarm_stats_by_severity(self, severities: list = None):
+        """Return alarm statistics grouped by severity.
+
+        Args:
+            severities: Optional list of severity strings to include,
+                e.g. ``["MAJOR", "CRITICAL"]``.
+        """
+        params = {}
+        if severities:
+            params["severities"] = ",".join(severities)
+        return self._get("stats/alarms/by-severity", params=params or None)

opennms_api_wrapper/_alarms.py

@@ -0,0 +1,130 @@
+"""Alarms REST API – /rest/alarms and /api/v2/alarms."""
+
+
+class AlarmsMixin:
+    def get_alarms(self, limit: int = 10, offset: int = 0,
+                   order_by: str = None, order: str = None, **filters):
+        """List alarms (v1).
+
+        Args:
+            limit: Max number of results to return. Use ``0`` for all.
+            offset: Zero-based offset for pagination.
+            order_by: Field name to sort by.
+            order: Sort direction: ``"asc"`` or ``"desc"``.
+            **filters: Additional Hibernate query filters passed directly as
+                query parameters (e.g. ``severity="MAJOR"``). Pass
+                ``comparator`` to change the match type (eq/ilike/…).
+        """
+        params = {"limit": limit, "offset": offset}
+        if order_by:
+            params["orderBy"] = order_by
+        if order:
+            params["order"] = order
+        params.update(filters)
+        return self._get("alarms", params=params)
+
+    def get_alarm(self, alarm_id: int):
+        """Return the alarm with the given ID."""
+        return self._get(f"alarms/{alarm_id}")
+
+    def get_alarm_count(self) -> int:
+        """Return the total number of alarms."""
+        return self._get("alarms/count")
+
+    # Single-alarm actions (v1 PUT with query params)
+
+    def ack_alarm(self, alarm_id: int, ack_user: str = None):
+        """Acknowledge alarm *alarm_id*.
+
+        Args:
+            ack_user: Acknowledge on behalf of this user (requires admin role).
+        """
+        params = {"ack": "true"}
+        if ack_user:
+            params["ackUser"] = ack_user
+        return self._put(f"alarms/{alarm_id}", params=params)
+
+    def unack_alarm(self, alarm_id: int):
+        """Remove acknowledgement from alarm *alarm_id*."""
+        return self._put(f"alarms/{alarm_id}", params={"ack": "false"})
+
+    def clear_alarm(self, alarm_id: int):
+        """Clear alarm *alarm_id* (sets severity to CLEARED)."""
+        return self._put(f"alarms/{alarm_id}", params={"clear": "true"})
+
+    def escalate_alarm(self, alarm_id: int):
+        """Escalate the severity of alarm *alarm_id* by one step."""
+        return self._put(f"alarms/{alarm_id}", params={"escalate": "true"})
+
+    # Bulk alarm actions
+
+    def bulk_ack_alarms(self, **filters):
+        """Acknowledge all alarms matching the given filters.
+
+        Args:
+            **filters: Additional Hibernate query filters passed directly as query parameters (e.g. ``severity="MAJOR"``).
+        """
+        params = {"ack": "true"}
+        params.update(filters)
+        return self._put("alarms", params=params)
+
+    def bulk_unack_alarms(self, **filters):
+        """Remove acknowledgement from all alarms matching the given filters.
+
+        Args:
+            **filters: Additional Hibernate query filters passed directly as query parameters (e.g. ``severity="MAJOR"``).
+        """
+        params = {"ack": "false"}
+        params.update(filters)
+        return self._put("alarms", params=params)
+
+    def bulk_clear_alarms(self, **filters):
+        """Clear all alarms matching the given filters.
+
+        Args:
+            **filters: Additional Hibernate query filters passed directly as query parameters (e.g. ``severity="MAJOR"``).
+        """
+        params = {"clear": "true"}
+        params.update(filters)
+        return self._put("alarms", params=params)
+
+    def bulk_escalate_alarms(self, **filters):
+        """Escalate all alarms matching the given filters.
+
+        Args:
+            **filters: Additional Hibernate query filters passed directly as query parameters (e.g. ``severity="MAJOR"``).
+        """
+        params = {"escalate": "true"}
+        params.update(filters)
+        return self._put("alarms", params=params)
+
+    # v2 alarms (FIQL filtering)
+
+    def get_alarms_v2(self, fiql: str = None, limit: int = 10,
+                      offset: int = 0, order_by: str = None,
+                      order: str = None):
+        """List alarms using the v2 API with optional FIQL filter string.
+
+        Args:
+            fiql: FIQL filter string (e.g. ``"alarm.severity==MAJOR"``).
+            limit: Max number of results to return. Use ``0`` for all.
+            offset: Zero-based offset for pagination.
+            order_by: Field name to sort by.
+            order: Sort direction: ``"asc"`` or ``"desc"``.
+
+        Example::
+
+            client.get_alarms_v2(fiql="alarm.severity==MAJOR")
+        """
+        params = {"limit": limit, "offset": offset}
+        if fiql:
+            params["_s"] = fiql
+        if order_by:
+            params["orderBy"] = order_by
+        if order:
+            params["order"] = order
+        return self._get("alarms", params=params, v2=True)
+
+    def get_alarm_v2(self, alarm_id: int):
+        """Return a single alarm by ID using the v2 API."""
+        return self._get(f"alarms/{alarm_id}", v2=True)

opennms_api_wrapper/_base.py

@@ -0,0 +1,104 @@
+"""Base HTTP client for the OpenNMS REST API."""
+import requests
+
+
+class _OpenNMSBase:
+    """Base class providing authenticated HTTP helpers."""
+
+    def __init__(self, url: str, username: str, password: str,
+                 verify_ssl: bool = True, timeout: int = 30):
+        """Initialize base URLs, credentials, and a shared requests session.
+
+        Args:
+            url: Base URL of the OpenNMS server (e.g. ``"https://onms.example.com"``).
+            username: OpenNMS username for HTTP Basic authentication.
+            password: Password for HTTP Basic authentication.
+            verify_ssl: When ``False`` SSL certificate verification is
+                disabled. Defaults to ``True``.
+            timeout: Socket timeout in seconds for all HTTP requests.
+                Defaults to ``30``.  Pass ``None`` to disable.
+        """
+        base = url.rstrip("/")
+        self._v1_url = f"{base}/opennms/rest"
+        self._v2_url = f"{base}/opennms/api/v2"
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.auth = (username, password)
+        self._session.headers.update({
+            "Accept": "application/json, text/plain;q=0.9",
+            "Content-Type": "application/json",
+        })
+        self._session.verify = verify_ssl
+
+    def _url(self, path: str, v2: bool = False) -> str:
+        """Build a full endpoint URL, using the v2 base if *v2* is True."""
+        base = self._v2_url if v2 else self._v1_url
+        return f"{base}/{path.lstrip('/')}"
+
+    def _parse(self, resp: requests.Response):
+        """Parse an HTTP response into a Python object.
+
+        Returns a dict/list for JSON, int or str for text/plain, and None
+        for empty 204 responses.  Raises ``requests.exceptions.HTTPError``
+        on non-2xx status codes.
+        """
+        resp.raise_for_status()
+        if not resp.content:
+            return None
+        ct = resp.headers.get("Content-Type", "")
+        if "application/json" in ct:
+            return resp.json()
+        if "text/plain" in ct:
+            text = resp.text.strip()
+            try:
+                return int(text)
+            except ValueError:
+                return text
+        try:
+            return resp.json()
+        except Exception:
+            return resp.text
+
+    def _get(self, path: str, params: dict = None, v2: bool = False):
+        """Send a GET request and return the parsed response."""
+        resp = self._session.get(self._url(path, v2), params=params,
+                                 timeout=self._timeout)
+        return self._parse(resp)
+
+    def _post(self, path: str, json_data=None, form_data: dict = None,
+              params: dict = None, v2: bool = False):
+        """Send a POST request and return the parsed response.
+
+        Sends form-encoded data when *form_data* is provided, otherwise JSON.
+        """
+        url = self._url(path, v2)
+        if form_data is not None:
+            resp = self._session.post(url, data=form_data, params=params,
+                                      headers={"Content-Type": "application/x-www-form-urlencoded"},
+                                      timeout=self._timeout)
+        else:
+            resp = self._session.post(url, json=json_data, params=params,
+                                      timeout=self._timeout)
+        return self._parse(resp)
+
+    def _put(self, path: str, json_data=None, form_data: dict = None,
+             params: dict = None, v2: bool = False):
+        """Send a PUT request and return the parsed response.
+
+        Sends form-encoded data when *form_data* is provided, otherwise JSON.
+        """
+        url = self._url(path, v2)
+        if form_data is not None:
+            resp = self._session.put(url, data=form_data, params=params,
+                                     headers={"Content-Type": "application/x-www-form-urlencoded"},
+                                     timeout=self._timeout)
+        else:
+            resp = self._session.put(url, json=json_data, params=params,
+                                     timeout=self._timeout)
+        return self._parse(resp)
+
+    def _delete(self, path: str, params: dict = None, v2: bool = False):
+        """Send a DELETE request and return the parsed response."""
+        resp = self._session.delete(self._url(path, v2), params=params,
+                                    timeout=self._timeout)
+        return self._parse(resp)

opennms_api_wrapper/_business_services.py

@@ -0,0 +1,42 @@
+"""Business Service Monitoring REST API v2 – /api/v2/business-services."""
+
+
+class BusinessServicesMixin:
+    def get_business_services(self):
+        """List all business services."""
+        return self._get("business-services", v2=True)
+
+    def get_business_service(self, service_id: int):
+        """Get a specific business service by *service_id*."""
+        return self._get(f"business-services/{service_id}", v2=True)
+
+    def create_business_service(self, service: dict):
+        """Create a new business service.
+
+        Args:
+            service: Business service definition dict. Common keys:
+                ``name`` (str), ``attributes`` (dict of key/value pairs),
+                ``reduceFunction`` (dict with a ``type`` key),
+                ``edges`` (list of edge configuration dicts). Example::
+
+                    {
+                        "name": "My App",
+                        "attributes": {"dc": "us-east-1"},
+                        "reduceFunction": {"type": "HighestSeverity"},
+                    }
+        """
+        return self._post("business-services", json_data=service, v2=True)
+
+    def update_business_service(self, service_id: int, service: dict):
+        """Update a business service.
+
+        Args:
+            service_id: Database ID of the business service to update.
+            service: Updated business service definition dict.
+        """
+        return self._put(f"business-services/{service_id}", json_data=service,
+                         v2=True)
+
+    def delete_business_service(self, service_id: int):
+        """Delete a business service."""
+        return self._delete(f"business-services/{service_id}", v2=True)

opennms_api_wrapper/_categories.py

@@ -0,0 +1,73 @@
+"""Categories REST API – /rest/categories."""
+
+
+class CategoriesMixin:
+    # ==================================================================
+    # Categories CRUD
+    # ==================================================================
+
+    def get_categories(self):
+        """List all configured surveillance categories."""
+        return self._get("categories")
+
+    def get_category(self, category: str):
+        """Get a specific category by *category* name."""
+        return self._get(f"categories/{category}")
+
+    def create_category(self, category: dict):
+        """Add a new surveillance category.
+
+        Args:
+            category: Category dict. Example:
+                ``{"name": "Production", "authorizedGroups": []}``
+        """
+        return self._post("categories", json_data=category)
+
+    def update_category(self, category: str, data: dict):
+        """Update a category.
+
+        Args:
+            category: Category name to update.
+            data: Dict of category fields to change.
+        """
+        return self._put(f"categories/{category}", json_data=data)
+
+    def delete_category(self, category: str):
+        """Delete a category."""
+        return self._delete(f"categories/{category}")
+
+    # ==================================================================
+    # Category ↔ Node associations
+    # ==================================================================
+
+    def get_node_categories_list(self, node_id):
+        """Get all categories for *node_id*."""
+        return self._get(f"categories/nodes/{node_id}")
+
+    def get_category_for_node(self, category: str, node_id):
+        """Get a specific category for *node_id*."""
+        return self._get(f"categories/{category}/nodes/{node_id}")
+
+    def associate_category_with_node(self, category: str, node_id):
+        """Associate *category* with *node_id*."""
+        return self._put(f"categories/{category}/nodes/{node_id}")
+
+    def dissociate_category_from_node(self, category: str, node_id):
+        """Remove *category* from *node_id*."""
+        return self._delete(f"categories/{category}/nodes/{node_id}")
+
+    # ==================================================================
+    # Category ↔ Group associations
+    # ==================================================================
+
+    def get_categories_for_group(self, group: str):
+        """Get categories associated with user group *group*."""
+        return self._get(f"categories/groups/{group}")
+
+    def associate_category_with_group(self, category: str, group: str):
+        """Associate *category* with user group *group*."""
+        return self._put(f"categories/{category}/groups/{group}")
+
+    def dissociate_category_from_group(self, category: str, group: str):
+        """Remove *category* from user group *group*."""
+        return self._delete(f"categories/{category}/groups/{group}")

opennms_api_wrapper/_device_config.py

@@ -0,0 +1,102 @@
+"""Device Configuration REST API – /rest/device-config."""
+
+
+class DeviceConfigMixin:
+    def get_device_configs(self, limit: int = 10, offset: int = 0,
+                           order_by: str = None, order: str = None,
+                           device_name: str = None, ip_address: str = None,
+                           config_type: str = None,
+                           created_after: int = None,
+                           created_before: int = None):
+        """List all device configurations (sorted by lastUpdated by default).
+
+        Args:
+            limit: Max number of results to return. Use ``0`` for all.
+            offset: Zero-based offset for pagination.
+            order_by: Field name to sort by.
+            order: Sort direction: ``"asc"`` or ``"desc"``.
+            device_name: Filter by device hostname.
+            ip_address: Filter by IP address.
+            config_type: Filter by config type string.
+            created_after: Filter to configs created after this ms epoch.
+            created_before: Filter to configs created before this ms epoch.
+        """
+        params: dict = {"limit": limit, "offset": offset}
+        if order_by:
+            params["orderBy"] = order_by
+        if order:
+            params["order"] = order
+        if device_name:
+            params["deviceName"] = device_name
+        if ip_address:
+            params["ipAddress"] = ip_address
+        if config_type:
+            params["configType"] = config_type
+        if created_after is not None:
+            params["createdAfter"] = created_after
+        if created_before is not None:
+            params["createdBefore"] = created_before
+        return self._get("device-config", params=params)
+
+    def get_device_config(self, config_id: int):
+        """Get device configuration for a specific database *config_id*."""
+        return self._get(f"device-config/{config_id}")
+
+    def get_device_config_by_interface(self, interface_id: int):
+        """Get all configs for a specific *interface_id*."""
+        return self._get(f"device-config/interface/{interface_id}")
+
+    def get_latest_device_configs(self, limit: int = 10, offset: int = 0,
+                                  order_by: str = None, order: str = None,
+                                  search: str = None, status: str = None):
+        """Return the latest config for all devices.
+
+        Args:
+            limit: Max number of results to return. Use ``0`` for all.
+            offset: Zero-based offset for pagination.
+            order_by: Field name to sort by.
+            order: Sort direction: ``"asc"`` or ``"desc"``.
+            search: Search term for device name / IP.
+            status: Filter by backup status.
+        """
+        params: dict = {"limit": limit, "offset": offset}
+        if order_by:
+            params["orderBy"] = order_by
+        if order:
+            params["order"] = order
+        if search:
+            params["search"] = search
+        if status:
+            params["status"] = status
+        return self._get("device-config/latest", params=params)
+
+    def download_device_configs(self, config_ids: list):
+        """Download configs for one or more *config_ids*.
+
+        Args:
+            config_ids: List of integer config IDs to download.
+        """
+        params = {"id": ",".join(str(i) for i in config_ids)}
+        return self._get("device-config/download", params=params)
+
+    def backup_device_config(self, backups: list):
+        """Trigger a backup retrieval for one or more interfaces.
+
+        Args:
+            backups: List of backup request dicts. Each dict has keys:
+                ``ipAddress`` (str): Interface IP address.
+                ``location`` (str): Monitoring location name (e.g.
+                ``"Default"``). ``serviceName`` (str): Service name (e.g.
+                ``"DeviceConfig-default"``). ``blocking`` (bool): Whether
+                to wait for the backup to complete. Example::
+
+                    [
+                        {
+                            "ipAddress": "192.168.1.1",
+                            "location": "Default",
+                            "serviceName": "DeviceConfig-default",
+                            "blocking": False,
+                        }
+                    ]
+        """
+        return self._post("device-config/backup", json_data=backups)

opennms_api_wrapper/_discovery.py

@@ -0,0 +1,48 @@
+"""Discovery REST API v2 – /api/v2/discovery."""
+
+
+class DiscoveryMixin:
+    def discover(self, config: dict):
+        """Submit a one-time discovery scan configuration (v2).
+
+        Args:
+            config: Discovery configuration dict. Supported keys (all lists
+                default to empty):
+
+                - ``specifics`` (list): Individual IPs to scan. Each entry::
+
+                      {"ip": "192.168.0.1", "location": "Default",
+                       "retries": 1, "timeout": 2000, "foreignSource": "FS"}
+
+                - ``include_ranges`` (list): IP ranges to scan. Each entry::
+
+                      {"begin": "192.168.0.1", "end": "192.168.0.254",
+                       "location": "Default", "retries": 1, "timeout": 2000}
+
+                - ``exclude_ranges`` (list): IP ranges to exclude. Each entry::
+
+                      {"begin": "192.168.0.100", "end": "192.168.0.110"}
+
+                - ``include_urls`` (list): URLs with newline-delimited IPs.
+                  Each entry::
+
+                      {"url": "http://example.com/ips.txt", "location": "Default"}
+
+        Note: The v2 discovery endpoint is documented as XML-only.  This
+        method sends JSON; if your OpenNMS version rejects it with HTTP 415
+        please open an issue — the workaround is to submit the request
+        manually with an XML body matching the ``discovery-configuration``
+        schema.
+
+        Example::
+
+            client.discover({
+                "specifics": [
+                    {"ip": "10.0.0.1", "location": "Default", "foreignSource": "Routers"}
+                ],
+                "include_ranges": [
+                    {"begin": "10.0.1.1", "end": "10.0.1.254"}
+                ],
+            })
+        """
+        return self._post("discovery", json_data=config, v2=True)