hyperping 0.1.0__py3-none-any.whl

hyperping/__init__.py

@@ -0,0 +1,151 @@
+"""Hyperping API client.
+
+A Python client for the `Hyperping <https://hyperping.io>`_ monitoring API,
+providing typed models, automatic retries with exponential backoff, and a
+circuit breaker for fault tolerance.
+
+Quick start::
+
+    from hyperping import HyperpingClient
+
+    with HyperpingClient(api_key="sk_...") as client:
+        monitors = client.list_monitors()
+        for m in monitors:
+            print(f"{m.name}: {'down' if m.down else 'up'}")
+"""
+
+from hyperping._version import __version__
+from hyperping.client import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+    CircuitState,
+    HyperpingClient,
+    RetryConfig,
+)
+from hyperping.endpoints import (
+    API_BASE,
+    API_PATHS,
+    ENDPOINTS,
+    HYPERPING_API_BASE,
+    APIVersion,
+    Endpoint,
+    EndpointConfig,
+    get_endpoint_url,
+    get_version_for_endpoint,
+)
+from hyperping.exceptions import (
+    HyperpingAPIError,
+    HyperpingAuthError,
+    HyperpingNotFoundError,
+    HyperpingRateLimitError,
+    HyperpingValidationError,
+)
+from hyperping.models import (
+    DEFAULT_REGIONS,
+    AddIncidentUpdateRequest,
+    APIErrorResponse,
+    DnsRecordType,
+    HttpMethod,
+    Incident,
+    IncidentCreate,
+    IncidentStatus,
+    IncidentType,
+    IncidentUpdate,
+    IncidentUpdateCreate,
+    IncidentUpdateRequest,
+    IncidentUpdateType,
+    LocalizedText,
+    Maintenance,
+    MaintenanceCreate,
+    MaintenanceUpdate,
+    Monitor,
+    MonitorBase,
+    MonitorCreate,
+    MonitorFrequency,
+    MonitorListResponse,
+    MonitorProtocol,
+    MonitorReport,
+    MonitorTimeout,
+    MonitorUpdate,
+    NotificationOption,
+    OutageDetail,
+    OutageStats,
+    Region,
+    ReportPeriod,
+    RequestHeader,
+    StatusPage,
+    StatusPageCreate,
+    StatusPageSubscriber,
+    StatusPageUpdate,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Client
+    "HyperpingClient",
+    # Configuration
+    "RetryConfig",
+    "CircuitBreakerConfig",
+    "CircuitBreaker",
+    "CircuitState",
+    # Endpoints
+    "API_BASE",
+    "Endpoint",
+    "APIVersion",
+    "EndpointConfig",
+    "ENDPOINTS",
+    "get_endpoint_url",
+    "get_version_for_endpoint",
+    # Convenience aliases (also used in tests)
+    "HYPERPING_API_BASE",
+    "API_PATHS",
+    # Exceptions
+    "HyperpingAPIError",
+    "HyperpingAuthError",
+    "HyperpingNotFoundError",
+    "HyperpingRateLimitError",
+    "HyperpingValidationError",
+    # Monitor enums
+    "HttpMethod",
+    "MonitorFrequency",
+    "MonitorTimeout",
+    "Region",
+    "MonitorProtocol",
+    "DnsRecordType",
+    "DEFAULT_REGIONS",
+    # Monitors
+    "MonitorBase",
+    "Monitor",
+    "MonitorCreate",
+    "MonitorUpdate",
+    "MonitorReport",
+    "MonitorListResponse",
+    "RequestHeader",
+    # Incidents
+    "AddIncidentUpdateRequest",
+    "Incident",
+    "IncidentCreate",
+    "IncidentStatus",
+    "IncidentType",
+    "IncidentUpdate",
+    "IncidentUpdateCreate",
+    "IncidentUpdateRequest",
+    "IncidentUpdateType",
+    "LocalizedText",
+    # Maintenance
+    "Maintenance",
+    "MaintenanceCreate",
+    "MaintenanceUpdate",
+    "NotificationOption",
+    # Reports
+    "ReportPeriod",
+    "OutageDetail",
+    "OutageStats",
+    "APIErrorResponse",
+    # Status Pages
+    "StatusPage",
+    "StatusPageCreate",
+    "StatusPageUpdate",
+    "StatusPageSubscriber",
+]

hyperping/_incidents_mixin.py

@@ -0,0 +1,198 @@
+"""Incident operations mixin for HyperpingClient.
+
+Provides CRUD methods for Hyperping incidents (v3 API). Mixed into
+:class:`~hyperping.client.HyperpingClient` at class definition time.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import ValidationError
+
+from hyperping.endpoints import Endpoint
+from hyperping.models import (
+    AddIncidentUpdateRequest,
+    Incident,
+    IncidentCreate,
+    IncidentStatus,
+    IncidentUpdateCreate,
+    IncidentUpdateRequest,
+    LocalizedText,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class IncidentsMixin:
+    """Incident-related API operations."""
+
+    def _request(  # type: ignore[empty-body]
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...  # provided by HyperpingClient
+
+    def list_incidents(self, status: str | None = None) -> list[Incident]:
+        """List all incidents.
+
+        Args:
+            status: Filter by status (``investigating``, ``identified``,
+                ``monitoring``, ``resolved``).
+
+        Returns:
+            List of :class:`Incident` objects. Incidents that fail to parse
+            are silently skipped with a warning log.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        params = {}
+        if status:
+            params["status"] = status
+
+        response = self._request("GET", Endpoint.INCIDENTS, params=params if params else None)
+
+        # Handle different response formats
+        if isinstance(response, list):
+            incidents_data = response
+        elif "incidents" in response:
+            incidents_data = response["incidents"]
+        else:
+            incidents_data = response.get("data", [])
+
+        incidents = []
+        skipped = 0
+        for data in incidents_data:
+            try:
+                incidents.append(Incident.model_validate(data))
+            except (ValueError, ValidationError) as e:
+                skipped += 1
+                logger.warning(f"Failed to parse incident data: {e}", extra={"data": data})
+
+        if skipped:
+            logger.warning(
+                f"{skipped} of {len(incidents_data)} incidents could not be parsed and were skipped"
+            )
+
+        return incidents
+
+    def get_incident(self, incident_id: str) -> Incident:
+        """Get a single incident by ID.
+
+        Args:
+            incident_id: Incident ID
+
+        Returns:
+            Incident object
+
+        Raises:
+            HyperpingNotFoundError: If incident not found
+        """
+        response = self._request("GET", f"{Endpoint.INCIDENTS}/{incident_id}")
+        return Incident.model_validate(response)
+
+    def create_incident(self, incident: IncidentCreate) -> Incident:
+        """Create a new incident.
+
+        Args:
+            incident: Incident creation data.
+
+        Returns:
+            Created :class:`Incident` object.
+
+        Raises:
+            HyperpingValidationError: If the payload fails server-side validation.
+            HyperpingAPIError: On unexpected API errors.
+
+        Note:
+            v3 API returns {"message": "...", "uuid": "..."} on create,
+            not the full incident object. The full incident is fetched after creation.
+        """
+        payload = incident.model_dump(exclude_none=True, by_alias=True, mode="json")
+        response = self._request("POST", Endpoint.INCIDENTS, json=payload)
+        # v3 API returns minimal response with just uuid
+        if "uuid" in response and "title" not in response:
+            # Fetch the full incident after creation
+            return self.get_incident(response["uuid"])
+        return Incident.model_validate(response)
+
+    def update_incident(self, incident_id: str, update: IncidentUpdateRequest) -> Incident:
+        """Update an existing incident.
+
+        Args:
+            incident_id: Incident UUID.
+            update: Fields to update.
+
+        Returns:
+            Updated :class:`Incident` object.
+
+        Raises:
+            HyperpingNotFoundError: If the incident does not exist.
+            HyperpingValidationError: If the payload fails server-side validation.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        payload = update.model_dump(exclude_none=True, by_alias=True)
+        response = self._request("PUT", f"{Endpoint.INCIDENTS}/{incident_id}", json=payload)
+        return Incident.model_validate(response)
+
+    def add_incident_update(
+        self,
+        incident_id: str,
+        update: IncidentUpdateCreate,
+    ) -> Incident:
+        """Add an update to an incident.
+
+        Args:
+            incident_id: Incident UUID.
+            update: Update data with message and new status.
+
+        Returns:
+            Updated :class:`Incident` object (re-fetched after posting the update).
+
+        Raises:
+            HyperpingNotFoundError: If the incident does not exist.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        payload = update.model_dump(exclude_none=True, by_alias=True)
+        url = f"{Endpoint.INCIDENTS}/{incident_id}/updates"
+        self._request("POST", url, json=payload)  # Returns {"message": "..."} — not a full Incident
+        return self.get_incident(incident_id)
+
+    def resolve_incident(self, incident_id: str, message: str | None = None) -> Incident:
+        """Resolve an incident.
+
+        Args:
+            incident_id: Incident UUID.
+            message: Optional resolution message. Defaults to
+                ``"This incident has been resolved."``.
+
+        Returns:
+            Resolved :class:`Incident` object.
+
+        Raises:
+            HyperpingNotFoundError: If the incident does not exist.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        update = AddIncidentUpdateRequest(
+            text=LocalizedText(en=message or "This incident has been resolved."),
+            type=IncidentStatus.RESOLVED,
+            date=datetime.now(UTC).isoformat(),
+        )
+        return self.add_incident_update(incident_id, update)
+
+    def delete_incident(self, incident_id: str) -> None:
+        """Delete an incident.
+
+        Args:
+            incident_id: Incident ID
+
+        Raises:
+            HyperpingNotFoundError: If incident not found
+        """
+        self._request("DELETE", f"{Endpoint.INCIDENTS}/{incident_id}")

hyperping/_maintenance_mixin.py

@@ -0,0 +1,195 @@
+"""Maintenance operations mixin for HyperpingClient.
+
+Provides CRUD methods for Hyperping maintenance windows (v1 API). Mixed into
+:class:`~hyperping.client.HyperpingClient` at class definition time.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import ValidationError
+
+from hyperping.endpoints import Endpoint
+from hyperping.models import (
+    Maintenance,
+    MaintenanceCreate,
+    MaintenanceUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MaintenanceMixin:
+    """Maintenance-related API operations."""
+
+    def _request(  # type: ignore[empty-body]
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...  # provided by HyperpingClient
+
+    def list_maintenance(self, status: str | None = None) -> list[Maintenance]:
+        """List all maintenance windows.
+
+        Args:
+            status: Filter by status (``scheduled``, ``in_progress``, ``completed``).
+
+        Returns:
+            List of :class:`Maintenance` objects. Windows that fail to parse
+            are silently skipped with a warning log.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        params = {}
+        if status:
+            params["status"] = status
+
+        response = self._request("GET", Endpoint.MAINTENANCE, params=params if params else None)
+
+        # Handle different response formats
+        # API returns {"maintenanceWindows": [...]} as of current version
+        if isinstance(response, list):
+            maintenance_data = response
+        elif "maintenanceWindows" in response:
+            maintenance_data = response["maintenanceWindows"]
+        elif "maintenance" in response:
+            maintenance_data = response["maintenance"]
+        else:
+            maintenance_data = response.get("data", [])
+
+        windows = []
+        skipped = 0
+        for data in maintenance_data:
+            try:
+                windows.append(Maintenance.model_validate(data))
+            except (ValueError, ValidationError) as e:
+                skipped += 1
+                logger.warning(f"Failed to parse maintenance data: {e}", extra={"data": data})
+
+        if skipped:
+            logger.warning(
+                f"{skipped} of {len(maintenance_data)} maintenance windows "
+                "could not be parsed and were skipped"
+            )
+
+        return windows
+
+    def get_maintenance(self, maintenance_id: str) -> Maintenance:
+        """Get a single maintenance window by ID.
+
+        Args:
+            maintenance_id: Maintenance ID
+
+        Returns:
+            Maintenance object
+
+        Raises:
+            HyperpingNotFoundError: If maintenance not found
+        """
+        response = self._request("GET", f"{Endpoint.MAINTENANCE}/{maintenance_id}")
+        return Maintenance.model_validate(response)
+
+    def create_maintenance(self, maintenance: MaintenanceCreate) -> Maintenance:
+        """Create a new maintenance window.
+
+        Args:
+            maintenance: Maintenance creation data.
+
+        Returns:
+            Created :class:`Maintenance` object.
+
+        Raises:
+            HyperpingValidationError: If the payload fails server-side validation.
+            HyperpingAPIError: On unexpected API errors.
+
+        Note:
+            v1 API returns {"uuid": "..."} on create, not the full maintenance object.
+            The full maintenance window is fetched after creation.
+        """
+        payload = maintenance.model_dump(exclude_none=True, by_alias=True, mode="json")
+        response = self._request("POST", Endpoint.MAINTENANCE, json=payload)
+        # v1 API returns minimal response with just uuid
+        if "uuid" in response and "name" not in response:
+            # Fetch the full maintenance after creation
+            return self.get_maintenance(response["uuid"])
+        return Maintenance.model_validate(response)
+
+    def update_maintenance(
+        self,
+        maintenance_id: str,
+        update: MaintenanceUpdate,
+    ) -> Maintenance:
+        """Update an existing maintenance window.
+
+        The v1 API PUT requires a full payload (partial updates return 401).
+        We fetch the current state and merge the supplied fields before sending.
+
+        Args:
+            maintenance_id: Maintenance ID
+            update: Fields to update (only non-None fields are applied)
+
+        Returns:
+            Updated Maintenance object
+        """
+        current = self.get_maintenance(maintenance_id)
+        partial = update.model_dump(exclude_none=True, by_alias=True, mode="json")
+
+        payload: dict[str, object] = {
+            "name": current.name,
+            "start_date": current.start_date,
+            "end_date": current.end_date,
+            "monitors": current.monitors,
+        }
+        payload.update(partial)
+
+        response = self._request("PUT", f"{Endpoint.MAINTENANCE}/{maintenance_id}", json=payload)
+        return Maintenance.model_validate(response)
+
+    def delete_maintenance(self, maintenance_id: str) -> None:
+        """Delete a maintenance window.
+
+        Args:
+            maintenance_id: Maintenance ID
+
+        Raises:
+            HyperpingNotFoundError: If maintenance not found
+        """
+        self._request("DELETE", f"{Endpoint.MAINTENANCE}/{maintenance_id}")
+
+    def get_active_maintenance(self) -> list[Maintenance]:
+        """Get currently active maintenance windows.
+
+        Returns:
+            List of active :class:`Maintenance` objects.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        all_maintenance = self.list_maintenance()
+        now = datetime.now(UTC)
+
+        return [m for m in all_maintenance if m.is_active(now)]
+
+    def is_monitor_in_maintenance(self, monitor_uuid: str) -> bool:
+        """Check if a monitor is currently in a maintenance window.
+
+        Args:
+            monitor_uuid: Monitor UUID to check.
+
+        Returns:
+            ``True`` if the monitor is in an active maintenance window.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        active = self.get_active_maintenance()
+        return any(m.affects_monitor(monitor_uuid) for m in active)