pingloom 0.1.0__py3-none-any.whl

pingloom/__init__.py

@@ -0,0 +1,33 @@
+"""PingLoom Python client."""
+
+from ._version import __version__
+from .client import PingLoom
+from .errors import (
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    InvalidRequestError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    PingLoomError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "__version__",
+    "PingLoom",
+    "PingLoomError",
+    "ConfigurationError",
+    "NetworkError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ServerError",
+]

pingloom/_mask.py

@@ -0,0 +1,25 @@
+"""Key masking. The API key must never appear in logs, errors or reprs."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+_KEY_RE = re.compile(r"pl_(?:live|test)_[A-Za-z0-9_\-]{4,}")
+
+
+def mask_key(key: Optional[str]) -> str:
+    """Return `pl_live_****abcd` for a key, or `****` when it does not look like one."""
+    if not key:
+        return "(no key)"
+    m = re.match(r"^(pl_(?:live|test)_)", key)
+    if m and len(key) >= len(m.group(1)) + 8:
+        return f"{m.group(1)}****{key[-4:]}"
+    return "****"
+
+
+def scrub(text: str, key: Optional[str] = None) -> str:
+    """Mask the known key and anything shaped like a PingLoom key inside free text."""
+    if key:
+        text = text.replace(key, mask_key(key))
+    return _KEY_RE.sub(lambda m: mask_key(m.group(0)), text)

pingloom/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pingloom/client.py

@@ -0,0 +1,171 @@
+"""PingLoom client. Standard library only (urllib)."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from ._mask import mask_key, scrub
+from ._version import __version__
+from .errors import ConfigurationError, NetworkError, PingLoomError, error_for
+
+# TODO(T07/T08): add heartbeat() and decision helpers here once those endpoints are merged.
+
+_RETRY_CAP_SECONDS = 30.0
+
+
+DEFAULT_BASE_URL = "https://api.pingloom.dev"
+
+class PingLoom:
+    """Server-side client. Never use it in browser or mobile code: the key must stay on your server.
+
+    `api_key` defaults to $PINGLOOM_API_KEY and `base_url` to $PINGLOOM_BASE_URL, else the hosted API.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        backoff: float = 0.5,
+        _sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._api_key = api_key or os.environ.get("PINGLOOM_API_KEY") or ""
+        url = base_url or os.environ.get("PINGLOOM_BASE_URL") or DEFAULT_BASE_URL
+        if not self._api_key:
+            raise ConfigurationError("No API key. Pass api_key or set PINGLOOM_API_KEY.")
+        self.base_url = url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.backoff = backoff
+        self._sleep = _sleep
+
+    def __repr__(self) -> str:
+        return f"PingLoom(api_key={mask_key(self._api_key)!r}, base_url={self.base_url!r})"
+
+    # -- public API ---------------------------------------------------------------------------
+
+    def send(
+        self,
+        title: str,
+        body: Optional[str] = None,
+        channel: Optional[str] = None,
+        priority: Optional[str] = None,
+        data: Optional[Mapping[str, Any]] = None,
+        action_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> str:
+        """Send a notification and return the event ID.
+
+        Without `idempotency_key` a random one is generated per call so that automatic retries cannot create
+        duplicates. Derive your own key from the business event (for example "order-1042-paid") when you also
+        want repeated calls of your own to be safe.
+        """
+        payload: Dict[str, Any] = {"title": title}
+        for name, value in (
+            ("body", body),
+            ("channel", channel),
+            ("priority", priority),
+            ("data", dict(data) if data is not None else None),
+            ("action_url", action_url),
+        ):
+            if value is not None:
+                payload[name] = value
+        key = idempotency_key or uuid.uuid4().hex
+        result = self._request("POST", "/v1/notifications", payload, {"Idempotency-Key": key})
+        return str(result["event_id"])
+
+    def status(self, event_id: str) -> Dict[str, Any]:
+        """Read an event back. The key needs the events:read scope."""
+        if not event_id or "/" in event_id:
+            raise ValueError("event_id must be a non-empty event ID")
+        return self._request("GET", f"/v1/notifications/{urllib.parse.quote(event_id, safe='')}", None, {})
+
+    # -- internals ----------------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, payload: Optional[dict], extra: Dict[str, str]) -> Dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"pingloom-python/{__version__}",
+            **extra,
+        }
+        raw = None
+        if payload is not None:
+            raw = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            outcome = self._once(method, path, raw, headers)
+            if not isinstance(outcome, PingLoomError):
+                return outcome
+            if attempt >= self.max_retries or not _retryable(outcome):
+                raise outcome
+            self._sleep(self._delay(attempt, outcome))
+            attempt += 1
+
+    def _once(self, method: str, path: str, raw: Optional[bytes], headers: Dict[str, str]) -> Any:
+        req = urllib.request.Request(self.base_url + path, data=raw, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:  # noqa: S310 - the scheme is the caller's
+                return _parse(res.read())
+        except urllib.error.HTTPError as e:
+            return self._http_error(e)
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as e:
+            return NetworkError(scrub(f"Could not reach PingLoom: {getattr(e, 'reason', e)}", self._api_key))
+
+    def _http_error(self, e: urllib.error.HTTPError) -> PingLoomError:
+        body = _parse(e.read(), strict=False)
+        env = body.get("error") if isinstance(body, dict) and isinstance(body.get("error"), dict) else {}
+        code = str(env.get("code") or "UNKNOWN")
+        message = scrub(str(env.get("message") or e.reason or f"HTTP {e.code}"), self._api_key)
+        retry_after = _float(e.headers.get("Retry-After")) if e.headers else None
+        cls = error_for(e.code, code)
+        return cls(
+            message,
+            status=e.code,
+            code=code,
+            request_id=env.get("request_id"),
+            details=env.get("details") if isinstance(env.get("details"), list) else None,
+            retry_after=retry_after,
+        )
+
+    def _delay(self, attempt: int, error: PingLoomError) -> float:
+        if error.retry_after is not None:
+            return min(max(error.retry_after, 0.0), _RETRY_CAP_SECONDS)
+        return min(self.backoff * (2**attempt) * (0.5 + random.random() / 2), _RETRY_CAP_SECONDS)
+
+
+def _retryable(error: PingLoomError) -> bool:
+    if error.status == 0:
+        return not isinstance(error, ConfigurationError)  # network error
+    if error.status == 429:
+        return error.code != "QUOTA_EXCEEDED"
+    return error.status >= 500
+
+
+def _parse(raw: bytes, strict: bool = True) -> Any:
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        if strict:
+            raise PingLoomError("PingLoom returned a response that is not JSON.", code="BAD_RESPONSE") from None
+        return {}
+
+
+def _float(v: Optional[str]) -> Optional[float]:
+    try:
+        return float(v) if v is not None else None
+    except ValueError:
+        return None

pingloom/errors.py

@@ -0,0 +1,93 @@
+"""Typed exceptions mapped from the PingLoom error envelope {"error": {"code", "message", "request_id"}}."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+
+class PingLoomError(Exception):
+    """Base class. `status` is 0 for errors that never reached the API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "UNKNOWN",
+        request_id: Optional[str] = None,
+        details: Optional[List[Any]] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.details = details or []
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code != "UNKNOWN":
+            parts.append(f"[{self.code}]")
+        if self.request_id:
+            parts.append(f"(request {self.request_id})")
+        return " ".join(parts)
+
+
+class ConfigurationError(PingLoomError):
+    """Missing API key or base URL. Raised before any request is made."""
+
+
+class NetworkError(PingLoomError):
+    """The request could not reach the API (DNS, connection, timeout)."""
+
+
+class InvalidRequestError(PingLoomError):
+    """400, 413, 415 or 422: fix the request. See `details`."""
+
+
+class AuthenticationError(PingLoomError):
+    """401: the key is missing, unknown, revoked or expired."""
+
+
+class PermissionDeniedError(PingLoomError):
+    """403: the key lacks the needed scope."""
+
+
+class NotFoundError(PingLoomError):
+    """404."""
+
+
+class ConflictError(PingLoomError):
+    """409: IDEMPOTENCY_CONFLICT (same key, different body) or PROJECT_ARCHIVED. Do not retry."""
+
+
+class RateLimitError(PingLoomError):
+    """429 RATE_LIMITED. Retried automatically; raised after the retries run out."""
+
+
+class QuotaExceededError(PingLoomError):
+    """429 QUOTA_EXCEEDED: the monthly quota is used. Never retried."""
+
+
+class ServerError(PingLoomError):
+    """5xx. Retried with the same idempotency key; raised after the retries run out."""
+
+
+def error_for(status: int, code: str) -> type:
+    if status == 429:
+        return QuotaExceededError if code == "QUOTA_EXCEEDED" else RateLimitError
+    if status == 401:
+        return AuthenticationError
+    if status == 403:
+        return PermissionDeniedError
+    if status == 404:
+        return NotFoundError
+    if status == 409:
+        return ConflictError
+    if status >= 500:
+        return ServerError
+    if 400 <= status < 500:
+        return InvalidRequestError
+    return PingLoomError

pingloom-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: pingloom
+Version: 0.1.0
+Summary: Python client for the PingLoom notification API (server-side only).
+Project-URL: Homepage, https://pingloom.dev
+Author: Srish Rachamalla
+License: MIT
+Keywords: alerts,notifications,on-call,pingloom,push,webhook
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pingloom (Python)
+
+Python client for the [PingLoom](https://pingloom.dev) notification API. Standard library only, Python 3.9+.
+
+Server-side only: the API key (`pl_live_...` or `pl_test_...`) must never go into browser or mobile code.
+
+```bash
+pip install pingloom
+export PINGLOOM_API_KEY=pl_test_...
+```
+
+```python
+from pingloom import PingLoom
+
+pl = PingLoom()  # reads PINGLOOM_API_KEY; talks to https://api.pingloom.dev (override with PINGLOOM_BASE_URL)
+event_id = pl.send(
+    "Backup finished", body="42 GB in 3 min", channel="ops", priority="high", idempotency_key="backup-2026-10-30"
+)
+print(pl.status(event_id)["status"])  # provider_accepted means FCM accepted it, not that a phone got it
+```
+
+`send(title, body=None, channel=None, priority=None, data=None, action_url=None, idempotency_key=None)` returns the event ID. `status(event_id)` needs the `events:read` scope.
+
+## Errors and retries
+
+Every API error is a typed exception carrying `status`, `code`, `message`, `request_id` and `details`:
+
+| Exception | When |
+| --- | --- |
+| `InvalidRequestError` | 400, 413, 415, 422 |
+| `AuthenticationError` | 401 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 (`IDEMPOTENCY_CONFLICT`, `PROJECT_ARCHIVED`) |
+| `RateLimitError` | 429 `RATE_LIMITED`, after retries |
+| `QuotaExceededError` | 429 `QUOTA_EXCEEDED`, never retried |
+| `ServerError` | 5xx, after retries |
+| `NetworkError` | no response, after retries |
+| `ConfigurationError` | missing key or base URL |
+
+`429 RATE_LIMITED`, `5xx` and network errors are retried (default 3 times) with exponential backoff, or `Retry-After` when sent. Retries reuse the same `Idempotency-Key`, so they cannot create duplicates. When you do not pass `idempotency_key`, a random one is generated per call. Pass your own, derived from the business event, to make repeated calls of your own safe too.
+
+The key is never logged: `repr(client)` and error text show `pl_live_****abcd`.
+
+## Develop
+
+```bash
+pip install pytest
+python -m pytest
+```

pingloom-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pingloom/__init__.py,sha256=ap_AcBJ3KTFMGf6uCa2FG3Ug4QGbuT4Dyt5q-jl2YqE,664
+pingloom/_mask.py,sha256=Vmge87ijCYrcU-TdLNNk25QMiSfJ_1frJ6mB7nqtFkM,808
+pingloom/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pingloom/client.py,sha256=PAV6lhDa8GYN_rFHV14wiHE_kouxK5N7urnQNkC0cbU,6897
+pingloom/errors.py,sha256=lUWimEUBZlsZbkTpIzdm0Ljbxgw9C29TNzuTl2qdavk,2648
+pingloom/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pingloom-0.1.0.dist-info/METADATA,sha256=qkC0u_uYUlI0Bnoheehk6eNkbutNfT8F_HVzTlpYByU,2552
+pingloom-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pingloom-0.1.0.dist-info/RECORD,,

pingloom-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any