libreclient 0.1.0__py3-none-any.whl

libreclient/__init__.py

@@ -0,0 +1,10 @@
+from . import models
+from .client import LibreClientAsync, LibreClientSync
+from .config import LibreConfig
+
+__all__ = [
+    "LibreClientAsync",
+    "LibreClientSync",
+    "LibreConfig",
+    "models",
+]

libreclient/__init__.pyi

@@ -0,0 +1,4 @@
+from .client import LibreClientAsync, LibreClientSync
+from .config import LibreConfig
+
+__all__ = ["LibreClientAsync", "LibreClientSync", "LibreConfig"]

libreclient/_base_client.py

@@ -0,0 +1,70 @@
+"""Shared base client functionality for sync/async LibreNMS clients."""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, cast
+
+from .config import LibreConfig
+
+
+class BaseLibreClient(LibreConfig, ABC):
+    """Common transport helpers used by both sync and async clients.
+
+    Route namespaces implemented as async code can call these methods and work
+    with either concrete client implementation.
+    """
+
+    def _api_url(self, path: str) -> str:
+        suffix = path if path.startswith("/") else f"/{path}"
+        return f"{self.base_url}{suffix}"
+
+    @abstractmethod
+    async def _request_raw(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Execute one HTTP request and return the raw response object."""
+
+    async def _request(
+        self, method: str, path: str, **kwargs: Any
+    ) -> dict | list:
+        response = await self._request_raw(
+            method, self._api_url(path), **kwargs
+        )
+        return await _json_from_response(response)
+
+    async def _request_bytes(
+        self, method: str, path: str, **kwargs: Any
+    ) -> bytes:
+        response = await self._request_raw(
+            method, self._api_url(path), **kwargs
+        )
+        payload = response.content
+        if inspect.isawaitable(payload):
+            payload = await payload
+        return cast("bytes", payload)
+
+    async def _get(self, path: str, **kwargs: Any) -> dict | list:
+        return await self._request("GET", path, **kwargs)
+
+    async def _post(self, path: str, **kwargs: Any) -> dict:
+        return await self._request("POST", path, **kwargs)
+
+    async def _put(self, path: str, **kwargs: Any) -> dict:
+        return await self._request("PUT", path, **kwargs)
+
+    async def _patch(self, path: str, **kwargs: Any) -> dict:
+        return await self._request("PATCH", path, **kwargs)
+
+    async def _delete(self, path: str, **kwargs: Any) -> dict:
+        return await self._request("DELETE", path, **kwargs)
+
+    async def _get_bytes(self, path: str, **kwargs: Any) -> bytes:
+        return await self._request_bytes("GET", path, **kwargs)
+
+
+async def _json_from_response(response: Any) -> dict | list:
+    """Normalize niquests response.json() for sync/async response types."""
+    payload = response.json()
+    if inspect.isawaitable(payload):
+        payload = await payload
+    return cast("dict", payload)

libreclient/client.py

@@ -0,0 +1,325 @@
+"""
+LibreNMS API clients — synchronous and asynchronous.
+"""
+
+from typing import Any
+
+import niquests
+from pydantic import PrivateAttr
+
+from ._base_client import BaseLibreClient
+from .routes import (
+    AlertsAsync,
+    AlertsSync,
+    ArpAsync,
+    ArpSync,
+    BillsAsync,
+    BillsSync,
+    DeviceGroupsAsync,
+    DeviceGroupsSync,
+    DevicesAsync,
+    DevicesSync,
+    IndexAsync,
+    IndexSync,
+    InventoryAsync,
+    InventorySync,
+    LocationsAsync,
+    LocationsSync,
+    LogsAsync,
+    LogsSync,
+    PollerGroupsAsync,
+    PollerGroupsSync,
+    PollersAsync,
+    PollersSync,
+    PortGroupsAsync,
+    PortgroupsAsync,
+    PortGroupsSync,
+    PortgroupsSync,
+    PortsAsync,
+    PortSecurityAsync,
+    PortSecuritySync,
+    PortsSync,
+    RoutingAsync,
+    RoutingSync,
+    ServicesAsync,
+    ServicesSync,
+    SwitchingAsync,
+    SwitchingSync,
+    SystemAsync,
+    SystemSync,
+)
+
+
+class LibreClientSync(BaseLibreClient):
+    """Synchronous LibreNMS API client backed by :class:`niquests.Session`."""
+
+    _session: niquests.Session = PrivateAttr()
+    _alerts: AlertsSync = PrivateAttr()
+    _arp: ArpSync = PrivateAttr()
+    _bills: BillsSync = PrivateAttr()
+    _device_groups: DeviceGroupsSync = PrivateAttr()
+    _devices: DevicesSync = PrivateAttr()
+    _index: IndexSync = PrivateAttr()
+    _inventory: InventorySync = PrivateAttr()
+    _locations: LocationsSync = PrivateAttr()
+    _logs: LogsSync = PrivateAttr()
+    _poller_groups: PollerGroupsSync = PrivateAttr()
+    _pollers: PollersSync = PrivateAttr()
+    _port_groups: PortGroupsSync = PrivateAttr()
+    _port_security: PortSecuritySync = PrivateAttr()
+    _portgroups: PortgroupsSync = PrivateAttr()
+    _ports: PortsSync = PrivateAttr()
+    _routing: RoutingSync = PrivateAttr()
+    _services: ServicesSync = PrivateAttr()
+    _switching: SwitchingSync = PrivateAttr()
+    _system: SystemSync = PrivateAttr()
+
+    def model_post_init(self, __context) -> None:
+        self._session = niquests.Session()
+        self._session.headers.update({"X-Auth-Token": self.token})
+        self._session.verify = self.verify_ssl
+        self._alerts = AlertsSync(self)
+        self._arp = ArpSync(self)
+        self._bills = BillsSync(self)
+        self._device_groups = DeviceGroupsSync(self)
+        self._devices = DevicesSync(self)
+        self._index = IndexSync(self)
+        self._inventory = InventorySync(self)
+        self._locations = LocationsSync(self)
+        self._logs = LogsSync(self)
+        self._poller_groups = PollerGroupsSync(self)
+        self._pollers = PollersSync(self)
+        self._port_groups = PortGroupsSync(self)
+        self._port_security = PortSecuritySync(self)
+        self._portgroups = PortgroupsSync(self)
+        self._ports = PortsSync(self)
+        self._routing = RoutingSync(self)
+        self._services = ServicesSync(self)
+        self._switching = SwitchingSync(self)
+        self._system = SystemSync(self)
+
+    async def _request_raw(self, method: str, url: str, **kwargs) -> Any:
+        return self._session.request(method, url, **kwargs)
+
+    @property
+    def alerts(self) -> AlertsSync:
+        return self._alerts
+
+    @property
+    def arp(self) -> ArpSync:
+        return self._arp
+
+    @property
+    def bills(self) -> BillsSync:
+        return self._bills
+
+    @property
+    def device_groups(self) -> DeviceGroupsSync:
+        return self._device_groups
+
+    @property
+    def devices(self) -> DevicesSync:
+        return self._devices
+
+    @property
+    def index(self) -> IndexSync:
+        return self._index
+
+    @property
+    def inventory(self) -> InventorySync:
+        return self._inventory
+
+    @property
+    def locations(self) -> LocationsSync:
+        return self._locations
+
+    @property
+    def logs(self) -> LogsSync:
+        return self._logs
+
+    @property
+    def poller_groups(self) -> PollerGroupsSync:
+        return self._poller_groups
+
+    @property
+    def pollers(self) -> PollersSync:
+        return self._pollers
+
+    @property
+    def port_groups(self) -> PortGroupsSync:
+        return self._port_groups
+
+    @property
+    def port_security(self) -> PortSecuritySync:
+        return self._port_security
+
+    @property
+    def portgroups(self) -> PortgroupsSync:
+        return self._portgroups
+
+    @property
+    def ports(self) -> PortsSync:
+        return self._ports
+
+    @property
+    def routing(self) -> RoutingSync:
+        return self._routing
+
+    @property
+    def services(self) -> ServicesSync:
+        return self._services
+
+    @property
+    def switching(self) -> SwitchingSync:
+        return self._switching
+
+    @property
+    def system(self) -> SystemSync:
+        return self._system
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "LibreClientSync":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+
+class LibreClientAsync(BaseLibreClient):
+    """Asynchronous LibreNMS API client backed by :class:`niquests.AsyncSession`."""
+
+    _session: niquests.AsyncSession = PrivateAttr()
+    _alerts: AlertsAsync = PrivateAttr()
+    _arp: ArpAsync = PrivateAttr()
+    _bills: BillsAsync = PrivateAttr()
+    _device_groups: DeviceGroupsAsync = PrivateAttr()
+    _devices: DevicesAsync = PrivateAttr()
+    _index: IndexAsync = PrivateAttr()
+    _inventory: InventoryAsync = PrivateAttr()
+    _locations: LocationsAsync = PrivateAttr()
+    _logs: LogsAsync = PrivateAttr()
+    _poller_groups: PollerGroupsAsync = PrivateAttr()
+    _pollers: PollersAsync = PrivateAttr()
+    _port_groups: PortGroupsAsync = PrivateAttr()
+    _port_security: PortSecurityAsync = PrivateAttr()
+    _portgroups: PortgroupsAsync = PrivateAttr()
+    _ports: PortsAsync = PrivateAttr()
+    _routing: RoutingAsync = PrivateAttr()
+    _services: ServicesAsync = PrivateAttr()
+    _switching: SwitchingAsync = PrivateAttr()
+    _system: SystemAsync = PrivateAttr()
+
+    def model_post_init(self, __context) -> None:
+        self._session = niquests.AsyncSession()
+        self._session.headers.update({"X-Auth-Token": self.token})
+        self._session.verify = self.verify_ssl
+
+        self._alerts = AlertsAsync(self)
+        self._arp = ArpAsync(self)
+        self._bills = BillsAsync(self)
+        self._device_groups = DeviceGroupsAsync(self)
+        self._devices = DevicesAsync(self)
+        self._index = IndexAsync(self)
+        self._inventory = InventoryAsync(self)
+        self._locations = LocationsAsync(self)
+        self._logs = LogsAsync(self)
+        self._poller_groups = PollerGroupsAsync(self)
+        self._pollers = PollersAsync(self)
+        self._port_groups = PortGroupsAsync(self)
+        self._port_security = PortSecurityAsync(self)
+        self._portgroups = PortgroupsAsync(self)
+        self._ports = PortsAsync(self)
+        self._routing = RoutingAsync(self)
+        self._services = ServicesAsync(self)
+        self._switching = SwitchingAsync(self)
+        self._system = SystemAsync(self)
+
+    async def _request_raw(self, method: str, url: str, **kwargs) -> Any:
+        return await self._session.request(method, url, **kwargs)
+
+    @property
+    def alerts(self) -> AlertsAsync:
+        return self._alerts
+
+    @property
+    def arp(self) -> ArpAsync:
+        return self._arp
+
+    @property
+    def bills(self) -> BillsAsync:
+        return self._bills
+
+    @property
+    def device_groups(self) -> DeviceGroupsAsync:
+        return self._device_groups
+
+    @property
+    def devices(self) -> DevicesAsync:
+        return self._devices
+
+    @property
+    def index(self) -> IndexAsync:
+        return self._index
+
+    @property
+    def inventory(self) -> InventoryAsync:
+        return self._inventory
+
+    @property
+    def locations(self) -> LocationsAsync:
+        return self._locations
+
+    @property
+    def logs(self) -> LogsAsync:
+        return self._logs
+
+    @property
+    def poller_groups(self) -> PollerGroupsAsync:
+        return self._poller_groups
+
+    @property
+    def pollers(self) -> PollersAsync:
+        return self._pollers
+
+    @property
+    def port_groups(self) -> PortGroupsAsync:
+        return self._port_groups
+
+    @property
+    def port_security(self) -> PortSecurityAsync:
+        return self._port_security
+
+    @property
+    def portgroups(self) -> PortgroupsAsync:
+        return self._portgroups
+
+    @property
+    def ports(self) -> PortsAsync:
+        return self._ports
+
+    @property
+    def routing(self) -> RoutingAsync:
+        return self._routing
+
+    @property
+    def services(self) -> ServicesAsync:
+        return self._services
+
+    @property
+    def switching(self) -> SwitchingAsync:
+        return self._switching
+
+    @property
+    def system(self) -> SystemAsync:
+        return self._system
+
+    async def close(self) -> None:
+        await self._session.close()
+
+    async def __aenter__(self) -> "LibreClientAsync":
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.close()

libreclient/config.py

@@ -0,0 +1,59 @@
+"""
+LibreNMS client configuration via Pydantic Settings.
+"""
+
+import re
+
+from pydantic import AnyHttpUrl, Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class LibreConfig(BaseSettings):
+    """Configuration for the LibreNMS API client.
+
+    Values can be supplied directly or via environment variables prefixed
+    with ``LIBRENMS_`` (e.g. ``LIBRENMS_URL``, ``LIBRENMS_TOKEN``).
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="LIBRENMS_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    url: AnyHttpUrl = Field(
+        ...,
+        description="Base URL of the LibreNMS instance, e.g. https://librenms.example.com",
+    )
+    token: str = Field(..., description="LibreNMS API token (X-Auth-Token)")
+    verify_ssl: bool = Field(True, description="Verify TLS/SSL certificates")
+    api_version: str = Field(
+        "v0", description="API version segment, e.g. 'v0'"
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_url_and_api_version(cls, data):
+        """If `url` includes `/api/vN`, strip it from url and set `api_version`."""
+        if not isinstance(data, dict):
+            return data
+
+        raw_url = data.get("url")
+        if raw_url is None:
+            return data
+
+        url_str = str(raw_url)
+        # Find embedded API version path, e.g. https://host/api/v1
+        match = re.search(r"/api/(v\d+)(?:/|$)", url_str)
+        if not match:
+            return data
+
+        data["api_version"] = match.group(1)
+        data["url"] = url_str[: match.start()].rstrip("/")
+        return data
+
+    @property
+    def base_url(self) -> str:
+        """Full API base URL, e.g. https://librenms.example.com/api/v0."""
+        return f"{str(self.url).rstrip('/')}/api/{self.api_version}"

libreclient/models/__init__.py

@@ -0,0 +1,83 @@
+"""Pydantic models for LibreNMS API responses.
+
+Import from here for convenience, or directly from sub-modules for clarity.
+"""
+
+# Base models (shared across all routes)
+from ._base import ApiResponse, ApiResponseWithId, ListResponse
+
+# Per-route response models
+from .alerts import (
+    AlertsResponse,
+    AlertTemplateCreatedResponse,
+    AlertTemplatesResponse,
+    RulesResponse,
+)
+from .arp import ArpResponse
+from .bills import BillHistoryResponse, BillsResponse
+from .device_groups import DeviceGroupDevicesResponse, DeviceGroupsResponse
+from .devices import (
+    ComponentsResponse,
+    DeviceFdbResponse,
+    DevicePortsResponse,
+    DeviceResponse,
+    DevicesResponse,
+)
+from .index import IndexResponse
+from .inventory import InventoryResponse
+from .locations import LocationsResponse
+from .logs import LogsResponse
+from .poller_groups import PollerGroupsResponse
+from .pollers import PollersResponse
+from .port_groups import PortGroupsResponse
+from .port_security import PortSecurityResponse
+from .portgroups import PortgroupsResponse
+from .ports import (
+    PortDescriptionResponse,
+    PortIpResponse,
+    PortResponse,
+    PortsResponse,
+    PortTransceiverResponse,
+)
+from .routing import RoutingResponse
+from .services import ServicesResponse
+from .switching import SwitchingResponse
+from .system import SystemResponse
+
+__all__ = [
+    "AlertTemplateCreatedResponse",
+    "AlertTemplatesResponse",
+    "AlertsResponse",
+    "ApiResponse",
+    "ApiResponseWithId",
+    "ArpResponse",
+    "BillHistoryResponse",
+    "BillsResponse",
+    "ComponentsResponse",
+    "DeviceFdbResponse",
+    "DeviceGroupDevicesResponse",
+    "DeviceGroupsResponse",
+    "DevicePortsResponse",
+    "DeviceResponse",
+    "DevicesResponse",
+    "IndexResponse",
+    "InventoryResponse",
+    "ListResponse",
+    "LocationsResponse",
+    "LogsResponse",
+    "PollerGroupsResponse",
+    "PollersResponse",
+    "PortDescriptionResponse",
+    "PortGroupsResponse",
+    "PortIpResponse",
+    "PortResponse",
+    "PortSecurityResponse",
+    "PortTransceiverResponse",
+    "PortgroupsResponse",
+    "PortsResponse",
+    "RoutingResponse",
+    "RulesResponse",
+    "ServicesResponse",
+    "SwitchingResponse",
+    "SystemResponse",
+]

libreclient/models/_base.py

@@ -0,0 +1,35 @@
+"""
+Base response models shared across all route modules.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApiResponse(BaseModel):
+    """Base response envelope — every API call returns at least these."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    status: str = "ok"
+    message: str = ""
+
+
+class ApiResponseWithId(ApiResponse):
+    """Response that includes a created/affected resource id."""
+
+    id: int
+
+
+class ListResponse(ApiResponse):
+    """Response containing a counted list of resources.
+
+    Subclass this and override ``data`` with the appropriate
+    ``validation_alias`` for the API's response key.
+    """
+
+    count: int = 0
+    data: list[Any] = Field(default_factory=list)

libreclient/models/alerts.py

@@ -0,0 +1,31 @@
+"""Response models for Alerts routes."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ._base import ApiResponseWithId, ListResponse
+
+
+class AlertsResponse(ListResponse):
+    """Response from get_alert / list_alerts."""
+
+    data: list[dict] = Field(default_factory=list, validation_alias="alerts")
+
+
+class RulesResponse(ListResponse):
+    """Response from get_alert_rule / list_alert_rules."""
+
+    data: list[dict] = Field(default_factory=list, validation_alias="rules")
+
+
+class AlertTemplatesResponse(ListResponse):
+    """Response from get_alert_template / list_alert_templates."""
+
+    data: list[dict] = Field(
+        default_factory=list, validation_alias="alert_templates"
+    )
+
+
+class AlertTemplateCreatedResponse(ApiResponseWithId):
+    """Response from add_alert_template (returns the new template id)."""

libreclient/models/arp.py

@@ -0,0 +1,13 @@
+"""Response models for ARP routes."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ._base import ListResponse
+
+
+class ArpResponse(ListResponse):
+    """Response from list_arp."""
+
+    data: list[dict] = Field(default_factory=list, validation_alias="arp")

libreclient/models/bills.py

@@ -0,0 +1,21 @@
+"""Response models for Bills routes."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ._base import ListResponse
+
+
+class BillsResponse(ListResponse):
+    """Response from list_bills / get_bill."""
+
+    data: list[dict] = Field(default_factory=list, validation_alias="bills")
+
+
+class BillHistoryResponse(ListResponse):
+    """Response from get_bill_history."""
+
+    data: list[dict] = Field(
+        default_factory=list, validation_alias="bill_history"
+    )

libreclient/models/device_groups.py

@@ -0,0 +1,19 @@
+"""Response models for Device Groups routes."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ._base import ListResponse
+
+
+class DeviceGroupsResponse(ListResponse):
+    """Response from get_devicegroups."""
+
+    data: list[dict] = Field(default_factory=list, validation_alias="groups")
+
+
+class DeviceGroupDevicesResponse(ListResponse):
+    """Response from get_devices_by_group."""
+
+    data: list[dict] = Field(default_factory=list, validation_alias="devices")