hyperping 1.0.1__tar.gz → 1.2.1__tar.gz

{hyperping-1.0.1 → hyperping-1.2.1}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-04-09
+
+### Added
+
+- **`AsyncHyperpingClient`** — full async counterpart to `HyperpingClient`. All resources
+  (monitors, incidents, maintenance, outages, status pages, healthchecks) are available via
+  `await`. Retry logic uses `asyncio.sleep`; circuit breaker and `RetryConfig` are shared with
+  the sync client. Exported from `hyperping` top-level.
+- **`HealthchecksMixin`** — full CRUD for push-based cron/heartbeat monitoring:
+  `list_healthchecks`, `get_healthcheck`, `create_healthcheck`, `update_healthcheck`,
+  `delete_healthcheck`, `pause_healthcheck`, `resume_healthcheck`. `Healthcheck`,
+  `HealthcheckCreate`, `HealthcheckUpdate` models exported from `hyperping`.
+- **Pagination** on `list_outages`, `list_status_pages`, `list_subscribers`. Pass
+  `page=None` (default) to auto-fetch all pages via `hasNextPage`; pass an explicit
+  `int` to retrieve a single page. `status` and `outage_type` filter params added to
+  `list_outages`.
+- **Typed `OutageAction`** return type for `acknowledge_outage`, `resolve_outage`,
+  `escalate_outage`, `unacknowledge_outage` (was `dict[str, Any]`).
+- **`_internals.py`** — shared `RETRY_AFTER_MAX`, `DEFAULT_USER_AGENT`, `sanitize_for_log`
+  used by both sync and async clients (eliminates private cross-module imports).
+- **`_monitor_constants.py`** — shared `VALID_PERIODS`, `MONITOR_WRITABLE_FIELDS`
+  constants used by both sync and async monitor mixins.
+- **`collect_all_pages` / `collect_all_pages_async`** helpers in `_utils.py` for
+  transparent multi-page result aggregation.
+
 ## [1.0.0] - 2026-04-05
 
 First stable release. The public API is production-ready and covered by semver

{hyperping-1.0.1 → hyperping-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.0.1
+Version: 1.2.1
 Summary: Python SDK for the Hyperping uptime monitoring and incident management API
 Project-URL: Homepage, https://github.com/develeap/hyperping-python
 Project-URL: Documentation, https://github.com/develeap/hyperping-python#readme
@@ -30,7 +30,7 @@ Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: pydantic; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -80,6 +80,24 @@ with HyperpingClient(api_key="sk_...") as client:
     client.resolve_incident(incident.uuid, "All systems operational")
 ```
 
+## Async Client
+
+An async-first client is available for use with `asyncio` and `anyio`-based frameworks:
+
+```python
+from hyperping import AsyncHyperpingClient
+
+async def main():
+    async with AsyncHyperpingClient(api_key="sk_...") as client:
+        monitors = await client.list_monitors()
+        for m in monitors:
+            print(f"{m.name}: {'down' if m.down else 'up'}")
+
+        outage = await client.acknowledge_outage("out_uuid", message="On it")
+```
+
+The async client supports all the same resources, retry behaviour, and circuit breaker as the sync client. Use `RetryConfig` and `CircuitBreakerConfig` in exactly the same way.
+
 ## Authentication
 
 Pass your API key directly or via environment variable:
@@ -140,7 +158,8 @@ in_maint = client.is_monitor_in_maintenance("mon_uuid")
 ### Outages
 
 ```python
-outages = client.list_outages()
+outages = client.list_outages()              # auto-fetches all pages
+outages = client.list_outages(page=0)        # single page
 client.acknowledge_outage("out_uuid", message="On it")
 client.resolve_outage("out_uuid", message="Fixed")
 client.escalate_outage("out_uuid")
@@ -149,18 +168,31 @@ client.escalate_outage("out_uuid")
 ### Status Pages
 
 ```python
-pages = client.list_status_pages(search="prod")
+pages = client.list_status_pages(search="prod")    # auto-fetches all pages
+pages = client.list_status_pages(page=0)            # single page
 page  = client.get_status_page("sp_uuid")
 created = client.create_status_page(StatusPageCreate(name="Prod", subdomain="prod-status"))
 client.update_status_page("sp_uuid", StatusPageUpdate(name="Production Status"))
 client.delete_status_page("sp_uuid")
 
 # Subscribers
-subs = client.list_subscribers("sp_uuid")
+subs = client.list_subscribers("sp_uuid")           # auto-fetches all pages
 sub  = client.add_subscriber("sp_uuid", "user@example.com")
 client.remove_subscriber("sp_uuid", sub.id)
 ```
 
+### Healthchecks
+
+```python
+checks = client.list_healthchecks()
+check  = client.get_healthcheck("hc_uuid")
+created = client.create_healthcheck(HealthcheckCreate(name="Nightly Job", period=86400, grace=3600))
+client.update_healthcheck("hc_uuid", HealthcheckUpdate(grace=7200))
+client.pause_healthcheck("hc_uuid")
+client.resume_healthcheck("hc_uuid")
+client.delete_healthcheck("hc_uuid")
+```
+
 ## Error Handling
 
 ```python

{hyperping-1.0.1 → hyperping-1.2.1}/README.md

@@ -43,6 +43,24 @@ with HyperpingClient(api_key="sk_...") as client:
     client.resolve_incident(incident.uuid, "All systems operational")
 ```
 
+## Async Client
+
+An async-first client is available for use with `asyncio` and `anyio`-based frameworks:
+
+```python
+from hyperping import AsyncHyperpingClient
+
+async def main():
+    async with AsyncHyperpingClient(api_key="sk_...") as client:
+        monitors = await client.list_monitors()
+        for m in monitors:
+            print(f"{m.name}: {'down' if m.down else 'up'}")
+
+        outage = await client.acknowledge_outage("out_uuid", message="On it")
+```
+
+The async client supports all the same resources, retry behaviour, and circuit breaker as the sync client. Use `RetryConfig` and `CircuitBreakerConfig` in exactly the same way.
+
 ## Authentication
 
 Pass your API key directly or via environment variable:
@@ -103,7 +121,8 @@ in_maint = client.is_monitor_in_maintenance("mon_uuid")
 ### Outages
 
 ```python
-outages = client.list_outages()
+outages = client.list_outages()              # auto-fetches all pages
+outages = client.list_outages(page=0)        # single page
 client.acknowledge_outage("out_uuid", message="On it")
 client.resolve_outage("out_uuid", message="Fixed")
 client.escalate_outage("out_uuid")
@@ -112,18 +131,31 @@ client.escalate_outage("out_uuid")
 ### Status Pages
 
 ```python
-pages = client.list_status_pages(search="prod")
+pages = client.list_status_pages(search="prod")    # auto-fetches all pages
+pages = client.list_status_pages(page=0)            # single page
 page  = client.get_status_page("sp_uuid")
 created = client.create_status_page(StatusPageCreate(name="Prod", subdomain="prod-status"))
 client.update_status_page("sp_uuid", StatusPageUpdate(name="Production Status"))
 client.delete_status_page("sp_uuid")
 
 # Subscribers
-subs = client.list_subscribers("sp_uuid")
+subs = client.list_subscribers("sp_uuid")           # auto-fetches all pages
 sub  = client.add_subscriber("sp_uuid", "user@example.com")
 client.remove_subscriber("sp_uuid", sub.id)
 ```
 
+### Healthchecks
+
+```python
+checks = client.list_healthchecks()
+check  = client.get_healthcheck("hc_uuid")
+created = client.create_healthcheck(HealthcheckCreate(name="Nightly Job", period=86400, grace=3600))
+client.update_healthcheck("hc_uuid", HealthcheckUpdate(grace=7200))
+client.pause_healthcheck("hc_uuid")
+client.resume_healthcheck("hc_uuid")
+client.delete_healthcheck("hc_uuid")
+```
+
 ## Error Handling
 
 ```python

{hyperping-1.0.1 → hyperping-1.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.0.1"
+version = "1.2.1"
 description = "Python SDK for the Hyperping uptime monitoring and incident management API"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}
@@ -31,7 +31,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=8.0",
+    "pytest>=9.0.3",
     "pytest-cov",
     "respx>=0.21",
     "ruff>=0.4",
@@ -56,6 +56,7 @@ exclude = [".claude/", ".github/", "dist/", "uv.lock", "BACKLOG.md"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "--cov=hyperping --cov-report=term-missing --cov-fail-under=85"
+asyncio_mode = "auto"
 
 [tool.mypy]
 python_version = "3.11"
@@ -68,3 +69,8 @@ target-version = "py311"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP"]
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=0.23.0",
+]

{hyperping-1.0.1 → hyperping-1.2.1}/src/hyperping/__init__.py

@@ -14,6 +14,7 @@ Quick start::
             print(f"{m.name}: {'down' if m.down else 'up'}")
 """
 
+from hyperping._async_client import AsyncHyperpingClient
 from hyperping._version import __version__
 from hyperping.client import (
     CircuitBreaker,
@@ -38,6 +39,9 @@ from hyperping.models import (
     DEFAULT_REGIONS,
     AddIncidentUpdateRequest,
     DnsRecordType,
+    Healthcheck,
+    HealthcheckCreate,
+    HealthcheckUpdate,
     HttpMethod,
     Incident,
     IncidentCreate,
@@ -60,6 +64,7 @@ from hyperping.models import (
     MonitorUpdate,
     NotificationOption,
     Outage,
+    OutageAction,
     OutageDetail,
     OutageStats,
     Region,
@@ -74,7 +79,8 @@ from hyperping.models import (
 __all__ = [
     # Version
     "__version__",
-    # Client
+    # Clients
+    "AsyncHyperpingClient",
     "HyperpingClient",
     # Configuration
     "RetryConfig",
@@ -130,6 +136,11 @@ __all__ = [
     "OutageStats",
     # Outages
     "Outage",
+    "OutageAction",
+    # Healthchecks
+    "Healthcheck",
+    "HealthcheckCreate",
+    "HealthcheckUpdate",
     # Status Pages
     "StatusPage",
     "StatusPageCreate",

hyperping-1.2.1/src/hyperping/_async_client.py

@@ -0,0 +1,351 @@
+"""Async Hyperping API client with retry logic and error handling.
+
+This module provides the :class:`AsyncHyperpingClient` class, a fully async
+counterpart to :class:`~hyperping.client.HyperpingClient`.
+
+Example::
+
+    async with AsyncHyperpingClient(api_key="sk_...") as client:
+        monitors = await client.list_monitors()
+        for m in monitors:
+            print(f"{m.name}: {'down' if m.down else 'up'}")
+"""
+
+import asyncio
+import logging
+import random
+from typing import Any
+
+import httpx
+from pydantic import SecretStr
+
+from hyperping._async_healthchecks_mixin import AsyncHealthchecksMixin
+from hyperping._async_incidents_mixin import AsyncIncidentsMixin
+from hyperping._async_maintenance_mixin import AsyncMaintenanceMixin
+from hyperping._async_monitors_mixin import AsyncMonitorsMixin
+from hyperping._async_outages_mixin import AsyncOutagesMixin
+from hyperping._async_statuspages_mixin import AsyncStatusPagesMixin
+from hyperping._circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+)
+from hyperping._internals import DEFAULT_USER_AGENT, RETRY_AFTER_MAX, sanitize_for_log
+from hyperping.client import DEFAULT_RETRY_CONFIG, RetryConfig
+from hyperping.endpoints import API_BASE
+from hyperping.exceptions import (
+    HyperpingAPIError,
+    HyperpingAuthError,
+    HyperpingRateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncHyperpingClient(
+    AsyncMonitorsMixin,
+    AsyncIncidentsMixin,
+    AsyncMaintenanceMixin,
+    AsyncOutagesMixin,
+    AsyncStatusPagesMixin,
+    AsyncHealthchecksMixin,
+):
+    """Async client for interacting with the Hyperping API.
+
+    Handles authentication, retry logic, and error mapping using
+    ``httpx.AsyncClient`` for non-blocking I/O.
+
+    Example::
+
+        async with AsyncHyperpingClient(api_key="sk_xxx") as client:
+            monitors = await client.list_monitors()
+            for m in monitors:
+                print(f"{m.name}: {'down' if m.down else 'up'}")
+    """
+
+    DEFAULT_BASE_URL = API_BASE
+    DEFAULT_TIMEOUT = 30.0
+
+    def __init__(
+        self,
+        api_key: str | SecretStr,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry_config: RetryConfig | None = None,
+        circuit_breaker_config: CircuitBreakerConfig | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        """Initialize the async Hyperping API client.
+
+        Args:
+            api_key: Hyperping API key (starts with ``sk_``). Accepts a plain
+                string or a :class:`pydantic.SecretStr`.
+            base_url: Override the default API base URL.
+            timeout: HTTP request timeout in seconds.
+            retry_config: Retry behaviour configuration.
+            circuit_breaker_config: Circuit breaker configuration.
+            user_agent: Custom ``User-Agent`` header value.
+        """
+        raw_key = api_key.get_secret_value() if isinstance(api_key, SecretStr) else api_key
+        if not raw_key or not raw_key.strip():
+            raise ValueError("api_key must be a non-empty string")
+        self._api_key = SecretStr(raw_key) if isinstance(api_key, str) else api_key
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.retry_config = retry_config or DEFAULT_RETRY_CONFIG
+        self._circuit_breaker = CircuitBreaker(circuit_breaker_config)
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self._api_key.get_secret_value()}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": user_agent or DEFAULT_USER_AGENT,
+            },
+            timeout=self.timeout,
+        )
+
+    def __repr__(self) -> str:
+        return f"AsyncHyperpingClient(base_url={self.base_url!r})"
+
+    async def close(self) -> None:
+        """Close the async HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHyperpingClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    @property
+    def circuit_breaker(self) -> CircuitBreaker:
+        """Access the circuit breaker state (for monitoring)."""
+        return self._circuit_breaker
+
+    # ==================== Error Handling ====================
+
+    def _parse_error_body(self, response: httpx.Response) -> dict[str, Any]:
+        """Parse the JSON body from an error response."""
+        try:
+            return response.json()  # type: ignore[no-any-return]
+        except (ValueError, httpx.DecodingError):
+            return {"error": response.text or "Unknown error"}
+
+    def _parse_retry_after(self, response: httpx.Response) -> int | None:
+        """Extract and parse the ``Retry-After`` header value."""
+        retry_after = response.headers.get("Retry-After")
+        if not retry_after:
+            return None
+        try:
+            return int(retry_after)
+        except ValueError:
+            return None
+
+    def _handle_response_error(self, response: httpx.Response) -> None:
+        """Map HTTP errors to typed exceptions."""
+        from hyperping.exceptions import (
+            HyperpingNotFoundError,
+            HyperpingValidationError,
+        )
+
+        status = response.status_code
+        request_id = response.headers.get("x-request-id")
+        body = self._parse_error_body(response)
+        error_msg = body.get("error") or body.get("message") or f"HTTP {status}"
+
+        if status in (401, 403):
+            raise HyperpingAuthError(
+                message=f"Authentication failed: {error_msg}",
+                status_code=status,
+                response_body=None,
+                request_id=request_id,
+            )
+        if status == 404:
+            raise HyperpingNotFoundError(
+                message=f"Resource not found: {error_msg}",
+                status_code=status,
+                response_body=body,
+                request_id=request_id,
+            )
+        if status == 429:
+            raise HyperpingRateLimitError(
+                message=f"Rate limit exceeded: {error_msg}",
+                status_code=status,
+                response_body=body,
+                retry_after=self._parse_retry_after(response),
+                request_id=request_id,
+            )
+        if status in (400, 422):
+            from hyperping.exceptions import HyperpingValidationError
+            raise HyperpingValidationError(
+                message=f"Validation error: {error_msg}",
+                status_code=status,
+                response_body=body,
+                validation_errors=body.get("details") or body.get("errors"),
+                request_id=request_id,
+            )
+        raise HyperpingAPIError(
+            message=f"API error: {error_msg}",
+            status_code=status,
+            response_body=body,
+            request_id=request_id,
+        )
+
+    # ==================== Request Helpers ====================
+
+    def _compute_sleep_time(self, response: httpx.Response, delay: float) -> float:
+        """Compute how long to sleep before retrying a failed request."""
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            if retry_after:
+                try:
+                    return min(float(retry_after), RETRY_AFTER_MAX)
+                except (ValueError, OverflowError):
+                    pass
+        return delay + random.uniform(0, delay * 0.25)
+
+    def _should_retry(self, status_code: int, attempt: int) -> bool:
+        """Return True if this status/attempt combination warrants a retry."""
+        return (
+            status_code in self.retry_config.retry_on_status
+            and attempt < self.retry_config.max_retries
+        )
+
+    async def _execute_single_attempt(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]] | httpx.Response:
+        """Execute a single async HTTP request attempt."""
+        logger.debug(
+            "API request: %s %s (attempt)",
+            method,
+            path,
+            extra={
+                "json": sanitize_for_log(json),
+                "params": sanitize_for_log(params),
+            },
+        )
+
+        response = await self._client.request(method=method, url=path, json=json, params=params)
+
+        if response.status_code >= 400:
+            return response
+
+        self._circuit_breaker.record_success()
+        if response.status_code == 204:
+            return {}
+        return response.json()  # type: ignore[no-any-return]
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        """Make an async HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API path (e.g., Endpoint.MONITORS)
+            json: Request body as dict
+            params: Query parameters
+
+        Returns:
+            Response body as dict or list
+
+        Raises:
+            HyperpingAPIError: On API errors after retries exhausted
+        """
+        if not self._circuit_breaker.call_allowed():
+            cb = self._circuit_breaker
+            raise HyperpingAPIError(
+                f"Circuit breaker OPEN - API calls suspended. "
+                f"Consecutive failures: {cb.failure_count}. "
+                f"Will recover after {cb.recovery_timeout}s."
+            )
+
+        last_exception: Exception | None = None
+        delay = self.retry_config.initial_delay
+        max_attempts = self.retry_config.max_retries + 1
+
+        for attempt in range(max_attempts):
+            try:
+                result = await self._execute_single_attempt(method, path, json, params)
+
+                if not isinstance(result, httpx.Response):
+                    return result
+
+                response = result
+                if self._should_retry(response.status_code, attempt):
+                    sleep_time = self._compute_sleep_time(response, delay)
+                    logger.warning(
+                        "Retrying after %.2fs due to %d (attempt %d/%d)",
+                        sleep_time,
+                        response.status_code,
+                        attempt + 1,
+                        max_attempts,
+                    )
+                    await asyncio.sleep(sleep_time)
+                    delay = min(
+                        delay * self.retry_config.backoff_factor,
+                        self.retry_config.max_delay,
+                    )
+                    continue
+
+                if response.status_code >= 500:
+                    self._circuit_breaker.record_failure()
+                self._handle_response_error(response)
+
+            except (httpx.TimeoutException, httpx.RequestError) as e:
+                last_exception = e
+                if attempt < self.retry_config.max_retries:
+                    label = "timeout" if isinstance(e, httpx.TimeoutException) else str(e)
+                    sleep_time = delay + random.uniform(0, delay * 0.25)
+                    logger.warning(
+                        "Request %s, retrying after %.2fs (attempt %d/%d)",
+                        label,
+                        sleep_time,
+                        attempt + 1,
+                        max_attempts,
+                    )
+                    await asyncio.sleep(sleep_time)
+                    delay = min(
+                        delay * self.retry_config.backoff_factor,
+                        self.retry_config.max_delay,
+                    )
+                    continue
+                self._circuit_breaker.record_failure()
+                if isinstance(e, httpx.TimeoutException):
+                    raise HyperpingAPIError(
+                        f"Request timeout after {max_attempts} attempts"
+                    ) from e
+                raise HyperpingAPIError(f"Request failed: {e}") from e
+
+        raise HyperpingAPIError(  # pragma: no cover
+            "Request failed after all retries"
+        ) from last_exception
+
+    # ==================== Health Check ====================
+
+    async def ping(self) -> bool:
+        """Test API connectivity and authentication.
+
+        Returns:
+            True if connection successful
+
+        Raises:
+            HyperpingAuthError: If authentication fails
+            HyperpingAPIError: If connection fails
+        """
+        try:
+            await self.list_monitors()
+            return True
+        except HyperpingAuthError:
+            raise
+        except (HyperpingAPIError, httpx.RequestError, httpx.TimeoutException) as e:
+            raise HyperpingAPIError(f"API connectivity test failed: {e}") from e