uptimer-python-sdk 0.4.0__py3-none-any.whl → 1.6.0rc0__py3-none-any.whl

uptimer/__init__.py

@@ -1,3 +1,12 @@
-"""Uptimer Python SDK."""
+"""
+Uptimer Python SDK.
 
-__version__ = "0.4.0"
+Targets Uptimer API v2 only. Code written against 0.4.x keeps working against
+the server — API v1 is unchanged and supported — but must stay on the 0.4.x SDK.
+
+The version tracks the uptimer release this SDK targets: 1.6.x speaks to
+uptimer 1.6.0 and later. Patch numbers are independent, so an SDK fix can ship
+without a server release. See product Decision 0013.
+"""
+
+__version__ = "1.6.0-rc.0"

uptimer/client.py

@@ -2,25 +2,70 @@ from __future__ import annotations
 
 from typing import cast
 
-from uptimer.endpoints.v1 import V1Endpoint
+from uptimer.compat import ensure_v2_supported
+from uptimer.endpoints.v2 import V2Endpoint
 from uptimer.http import UptimerHttpLib
 
 
 class UptimerClient:
-    v1: V1Endpoint
+    """
+    The Uptimer API client.
+
+    Resources are reached through the API version that serves them:
+    `client.v2.workspaces`, `client.v2.locations`, `client.v2.incidents`,
+    `client.v2.monitoring.websites` and
+    `client.v2.subjects(subject).signals(signal).observations`. This SDK does
+    not speak API v1 — see the migration note in the README if you are coming
+    from 0.4.x.
+
+    `version()` and the compatibility helpers stay here rather than under a
+    version namespace, because `/version` is shared and unversioned.
+    """
+
+    v2: V2Endpoint
 
     def __init__(self, api_key: str, base_url: str):
         self._http_lib = UptimerHttpLib(api_key, base_url)
-        self.v1 = V1Endpoint(self._http_lib)
+        self._checked_compat = False
+        self._wire()
+
+    def _wire(self) -> None:
+        self.v2 = V2Endpoint(self._http_lib)
 
     def version(self) -> str:
+        """
+        Return the server version.
+
+        `/version` is a shared global endpoint, not a versioned one, so this
+        works against any server — including one too old for the rest of this
+        SDK.
+        """
         response = self._http_lib.client.get(self._http_lib.build_url("version"))
         return cast("str", self._http_lib.parse_response(response=response))
 
+    def check_compatibility(self) -> str:
+        """
+        Verify the server provides API v2, and return its version.
+
+        Raises IncompatibleServerError if it does not. Called once per client
+        by ensure_compatible(); call it directly to fail fast at startup.
+        """
+        version = self.version()
+        ensure_v2_supported(version)
+        self._checked_compat = True
+        return version
+
+    def ensure_compatible(self) -> None:
+        """Run the compatibility check once, then never again."""
+        if not self._checked_compat:
+            self.check_compatibility()
+
     def set_uptimer_http_lib(self, http_lib: UptimerHttpLib) -> None:
         self._http_lib = http_lib
+        self._checked_compat = False
+        self._wire()
 
 
 class UptimerCloudClient(UptimerClient):
     def __init__(self, api_key: str):
-        super().__init__(api_key, "https://api.myuptime.info")
+        super().__init__(api_key, "https://myuptime.info/api")

uptimer/compat.py

@@ -0,0 +1,58 @@
+"""
+Server compatibility.
+
+This SDK targets API v2 only. A server that predates v2 answers /v2 with 404,
+which on its own tells a user nothing — so the version is checked first and the
+404 is translated as a fallback.
+
+Why both: `uptimer` and `myuptime.info` version independently over the same
+shared API (1.5.x and 15.x). A numeric minimum catches the self-hosted case
+cleanly, but cannot express "hosted 14.0.3 has no v2" — 14 is greater than 1.
+The 404 path catches what the number cannot.
+"""
+
+from __future__ import annotations
+
+import re
+
+from uptimer import __version__
+from uptimer.errors import IncompatibleServerError
+
+
+def _minimum_from_own_version() -> tuple[int, int, int]:
+    """
+    Return the oldest server version this SDK speaks to.
+
+    The SDK's major.minor tracks the uptimer release it targets (Decision
+    0013), so 1.5.x requires a 1.5.0 server. Deriving it here rather than
+    writing the number down twice means the two cannot drift apart.
+    """
+    parts = __version__.split(".")
+    return (int(parts[0]), int(parts[1]), 0)
+
+
+MINIMUM_UPTIMER_VERSION = _minimum_from_own_version()
+
+_VERSION_RE = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)")
+
+
+def parse_version(version: str) -> tuple[int, int, int] | None:
+    """
+    Parse a server version, or None if it is not a release number.
+
+    "dev" and anything unparseable return None and are treated as usable: a
+    developer running from source must not be locked out by a version string.
+    """
+    match = _VERSION_RE.match(version.strip())
+    if not match:
+        return None
+    return (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+
+
+def ensure_v2_supported(version: str) -> None:
+    """Raise IncompatibleServerError if this server is too old for API v2."""
+    parsed = parse_version(version)
+    if parsed is None:
+        return
+    if parsed < MINIMUM_UPTIMER_VERSION:
+        raise IncompatibleServerError(version)

uptimer/endpoints/incidents.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from uptimer.endpoints.endpoint import BaseEndpoint
+from uptimer.models.v2 import from_api_incident
+
+if TYPE_CHECKING:
+    from uptimer.http import UptimerHttpLib
+    from uptimer.models.v2 import Incident
+
+
+class IncidentsEndpoint(BaseEndpoint):
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "incidents", parent_segments)
+
+    def all(
+        self,
+        workspace_id: str,
+        monitor_id: str | None = None,
+    ) -> list[Incident]:
+        """
+        Open incidents in a workspace, newest trouble first.
+
+        Only open ones: this answers "what is wrong now". Pass monitor_id to
+        narrow it to a single monitor.
+        """
+        params = {"workspace_id": workspace_id}
+        if monitor_id:
+            params["monitor_id"] = monitor_id
+        response = self.http.client.get(self.url, params=params)
+        result = self.http.parse_response(response=response)
+        return [from_api_incident(item) for item in result]

uptimer/endpoints/{regions.py → locations.py}

@@ -3,22 +3,23 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from uptimer.endpoints.endpoint import BaseEndpoint
-from uptimer.models import from_api_region
+from uptimer.models.v2 import from_api_location
 
 if TYPE_CHECKING:
     from uptimer.http import UptimerHttpLib
-    from uptimer.models.region import Region
+    from uptimer.models.v2 import Location
 
 
-class RegionsEndpoint(BaseEndpoint):
+class LocationsEndpoint(BaseEndpoint):
     def __init__(
         self,
         http: UptimerHttpLib,
         parent_segments: str | list[str] | None = None,
     ):
-        super().__init__(http, "regions", parent_segments)
+        super().__init__(http, "locations", parent_segments)
 
-    def all(self) -> list[Region]:
+    def all(self) -> list[Location]:
+        """Every location checks can run from."""
         response = self.http.client.get(self.url)
         result = self.http.parse_response(response=response)
-        return [from_api_region(region) for region in result]
+        return [from_api_location(item) for item in result]

uptimer/endpoints/subjects.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from uptimer.endpoints.endpoint import BaseEndpoint
+from uptimer.models.v2 import from_api_observation
+
+if TYPE_CHECKING:
+    from uptimer.http import UptimerHttpLib
+    from uptimer.models.v2 import CreateObservationRequest, Observation
+
+
+def _slug(value: str, what: str) -> str:
+    """
+    Escape one slug for a URL path segment.
+
+    A slug is the API name of a subject or signal, and it lands in the path. It
+    is quoted rather than trusted so a value containing a slash addresses a
+    signal named that, instead of silently reaching a different resource.
+    """
+    if not value or not value.strip():
+        message = f"{what} slug is required"
+        raise ValueError(message)
+    return quote(value, safe="")
+
+
+def _payload(observation: CreateObservationRequest) -> dict:
+    """
+    Serialize an observation, omitting what was not set.
+
+    The server rejects unknown fields and distinguishes an absent optional from
+    a null one — an absent `observed_at` means "stamp it now", where a null
+    would be a malformed timestamp. So unset fields are left out rather than
+    sent as None.
+    """
+    body = asdict(observation)
+    return {key: value for key, value in body.items() if value is not None}
+
+
+class ObservationsEndpoint(BaseEndpoint):
+    """
+    The observations of one signal.
+
+    Reached through the signal that owns them —
+    `client.v2.subjects(subject).signals(signal).observations` — because a
+    signal slug is unique within its subject, not across the workspace. The pair
+    is the address.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "observations", parent_segments)
+
+    def create(self, observation: CreateObservationRequest) -> Observation:
+        """
+        Report one observation, and return it as the server stored it.
+
+        Only custom heartbeat and event signals accept this. A platform HTTP
+        signal is written by Uptimer's own probe and refuses posted
+        observations, which arrives as a DefaultUptimerApiError.
+
+        A stored observation the engine will not evaluate is RETURNED, not
+        raised: check `accepted` and `reject_reason` on the result. An error is
+        raised only when nothing was stored — a bad status, an unparsable
+        timestamp, a signal that does not exist, or no permission.
+        """
+        response = self.http.client.post(self.url, json=_payload(observation))
+        result = self.http.parse_response(response=response)
+        return from_api_observation(result)
+
+
+class SignalEndpoint(BaseEndpoint):
+    """One signal of a subject, addressed by its slug."""
+
+    observations: ObservationsEndpoint
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        signal_slug: str,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, _slug(signal_slug, "signal"), parent_segments)
+        self.observations = ObservationsEndpoint(
+            http,
+            [*self._parent_segments, self.segment],
+        )
+
+
+class SignalsEndpoint(BaseEndpoint):
+    """
+    The signals of one subject.
+
+    Call it with a slug to reach one:
+    `client.v2.subjects("checkout").signals("worker-pulse")`.
+
+    There is no listing or authoring here. Signals are created and managed in
+    the Uptimer UI; the SDK exists to report data to one that already exists.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "signals", parent_segments)
+
+    def __call__(self, signal_slug: str) -> SignalEndpoint:
+        return SignalEndpoint(self.http, signal_slug, self._parent_segments_with_self())
+
+    def _parent_segments_with_self(self) -> list[str]:
+        return [*self._parent_segments, self.segment]
+
+
+class SubjectEndpoint(BaseEndpoint):
+    """One monitored subject, addressed by its slug."""
+
+    signals: SignalsEndpoint
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        subject_slug: str,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, _slug(subject_slug, "subject"), parent_segments)
+        self.signals = SignalsEndpoint(http, [*self._parent_segments, self.segment])
+
+
+class SubjectsEndpoint(BaseEndpoint):
+    """
+    The monitored subjects.
+
+    Call it with a slug to reach one: `client.v2.subjects("checkout")`.
+
+    Deliberately narrow: there is no subject CRUD here. The one thing this
+    namespace exists for is reporting observations to a custom signal, and the
+    path to that is the subject that owns it.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "subjects", parent_segments)
+
+    def __call__(self, subject_slug: str) -> SubjectEndpoint:
+        return SubjectEndpoint(self.http, subject_slug, [*self._parent_segments, self.segment])

uptimer/endpoints/v2.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from uptimer.endpoints.endpoint import BaseEndpoint
+from uptimer.endpoints.incidents import IncidentsEndpoint
+from uptimer.endpoints.locations import LocationsEndpoint
+from uptimer.endpoints.subjects import SubjectsEndpoint
+from uptimer.endpoints.websites import MonitoringEndpoint
+from uptimer.endpoints.workspaces import WorkspacesEndpoint
+
+if TYPE_CHECKING:
+    from uptimer.http import UptimerHttpLib
+
+
+class V2Endpoint(BaseEndpoint):
+    """
+    API v2, the whole of it: `client.v2`.
+
+    The API is versioned by path, so the SDK keeps that version visible rather
+    than hiding it behind bare attributes (Decision 0012). Every resource here
+    builds its URL from this namespace's segment, which is why `/v2` appears in
+    exactly one place.
+
+    `/version` is shared and unversioned, so it stays on the client itself.
+    """
+
+    workspaces: WorkspacesEndpoint
+    locations: LocationsEndpoint
+    incidents: IncidentsEndpoint
+    monitoring: MonitoringEndpoint
+    subjects: SubjectsEndpoint
+
+    def __init__(self, http: UptimerHttpLib):
+        super().__init__(http, "v2")
+        parent = [self.segment]
+        self.workspaces = WorkspacesEndpoint(http, parent)
+        self.locations = LocationsEndpoint(http, parent)
+        self.incidents = IncidentsEndpoint(http, parent)
+        self.monitoring = MonitoringEndpoint(http, parent)
+        self.subjects = SubjectsEndpoint(http, parent)

uptimer/endpoints/websites.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+
+from uptimer.endpoints.endpoint import BaseEndpoint
+from uptimer.models.v2 import DeleteWebsiteMonitorResponse, from_api_website_monitor
+
+if TYPE_CHECKING:
+    from uptimer.http import UptimerHttpLib
+    from uptimer.models.v2 import (
+        CreateWebsiteMonitorRequest,
+        UpdateWebsiteMonitorRequest,
+        WebsiteMonitor,
+    )
+
+
+def _strip_kinds(value: object) -> object:
+    """
+    Drop every `kind` from a request body, at any depth.
+
+    `kind` is what the server tells a client an object is; it is not something a
+    client sets. Echoing it back suggests otherwise, and the server ignores it
+    either way.
+    """
+    if isinstance(value, dict):
+        return {k: _strip_kinds(v) for k, v in value.items() if k != "kind"}
+    if isinstance(value, list):
+        return [_strip_kinds(v) for v in value]
+    return value
+
+
+def _payload(data: object) -> dict:
+    """
+    Serialize a request dataclass, dropping fields the server fills in.
+
+    An empty agreement means "leave it alone", which the server expresses by
+    omission, so it is stripped rather than sent as "" — those are different
+    requests.
+    """
+    body = asdict(data)  # type: ignore[call-overload]
+    body.pop("id", None)
+    if not body.get("agreement"):
+        body.pop("agreement", None)
+    return _strip_kinds(body)  # type: ignore[return-value]
+
+
+class WebsitesEndpoint(BaseEndpoint):
+    """
+    Website monitoring: the built-in template that watches a URL.
+
+    Nested under /v2/monitoring because it is one template among the several
+    coming later, not the general monitor model.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "websites", parent_segments)
+
+    def all(self, workspace_id: str) -> list[WebsiteMonitor]:
+        """Every website monitor in a workspace."""
+        params = {"workspace_id": workspace_id}
+        response = self.http.client.get(self.url, params=params)
+        result = self.http.parse_response(response=response)
+        return [from_api_website_monitor(item) for item in result]
+
+    def get(self, monitor_id: str) -> WebsiteMonitor:
+        """One website monitor by id."""
+        response = self.http.client.get(f"{self.url}/{monitor_id}")
+        result = self.http.parse_response(response=response)
+        return from_api_website_monitor(result)
+
+    def create(self, monitor: CreateWebsiteMonitorRequest) -> WebsiteMonitor:
+        """Create a website monitor, with its signal and rule."""
+        response = self.http.client.post(self.url, json=_payload(monitor))
+        result = self.http.parse_response(response=response)
+        return from_api_website_monitor(result)
+
+    def update(
+        self,
+        monitor_id: str,
+        monitor: UpdateWebsiteMonitorRequest,
+    ) -> WebsiteMonitor:
+        """Replace a website monitor's configuration."""
+        response = self.http.client.post(
+            f"{self.url}/{monitor_id}",
+            json=_payload(monitor),
+        )
+        result = self.http.parse_response(response=response)
+        return from_api_website_monitor(result)
+
+    def delete(self, monitor_id: str) -> DeleteWebsiteMonitorResponse:
+        """Delete a website monitor and everything under it."""
+        response = self.http.client.delete(f"{self.url}/{monitor_id}")
+        result = self.http.parse_response(response=response)
+        return DeleteWebsiteMonitorResponse(
+            message=result["message"],
+            monitor_id=result["monitor_id"],
+        )
+
+
+class MonitoringEndpoint(BaseEndpoint):
+    """The monitoring templates. Today there is one: websites."""
+
+    websites: WebsitesEndpoint
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "monitoring", parent_segments)
+        self.websites = WebsitesEndpoint(http, [*self._parent_segments, "monitoring"])

uptimer/endpoints/workspaces.py

@@ -3,11 +3,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from uptimer.endpoints.endpoint import BaseEndpoint
-from uptimer.models import from_api_workspace
+from uptimer.models.v2 import from_api_workspace
 
 if TYPE_CHECKING:
     from uptimer.http import UptimerHttpLib
-    from uptimer.models.workspace import Workspace
+    from uptimer.models.v2 import Workspace
 
 
 class WorkspacesEndpoint(BaseEndpoint):
@@ -19,6 +19,7 @@ class WorkspacesEndpoint(BaseEndpoint):
         super().__init__(http, "workspaces", parent_segments)
 
     def all(self) -> list[Workspace]:
+        """Every workspace this API key can reach."""
         response = self.http.client.get(self.url)
         result = self.http.parse_response(response=response)
-        return [from_api_workspace(workspace) for workspace in result]
+        return [from_api_workspace(item) for item in result]

uptimer/errors.py

@@ -23,3 +23,21 @@ class DefaultUptimerApiError(UptimerError):
         self.message = error.get("message", "")
         self.details = error.get("details", "")
         super().__init__(f"API error: {self.code} {self.message}")
+
+
+class IncompatibleServerError(UptimerError):
+    """
+    The server does not provide API v2, which this SDK requires.
+
+    Carries the server's own version so the message names the situation rather
+    than surfacing a bare 404.
+    """
+
+    def __init__(self, server_version: str):
+        self.server_version = server_version
+        super().__init__(
+            f"This server reports version {server_version}, which does not "
+            "provide API v2. uptimer-python-sdk 1.5.x requires API v2 "
+            "(uptimer 1.5.0+ or myuptime.info 15.1.0+). For API v1, use "
+            "uptimer-python-sdk 0.4.x.",
+        )

uptimer/http.py

@@ -5,7 +5,11 @@ from typing import Any
 import httpx
 
 from uptimer.endpoints.endpoint import BaseEndpoint
-from uptimer.errors import DefaultUptimerApiError, UptimerInvalidHttpCodeError
+from uptimer.errors import (
+    DefaultUptimerApiError,
+    IncompatibleServerError,
+    UptimerInvalidHttpCodeError,
+)
 
 
 class WorkspacesEndpoint(BaseEndpoint):
@@ -38,6 +42,13 @@ class UptimerHttpLib:
     def parse_response(
         response: httpx.Response,
     ) -> Any:  # noqa: ANN401
+        if response.status_code == 404 and "/v2/" in str(response.request.url):
+            # A server without API v2 has no /v2 routes at all. Saying "404"
+            # here would leave the user guessing; the version gate in
+            # client.check_compatibility() catches this earlier when the
+            # version number can express it, and this catches the rest.
+            unknown = "unknown (no /v2 routes)"
+            raise IncompatibleServerError(unknown)
         if response.status_code != 200:
             raise UptimerInvalidHttpCodeError(
                 response.request.url,

uptimer/models/__init__.py

@@ -1,9 +1,15 @@
-from .deserialize import (
-    from_api,
-    from_api_region,
-    from_api_rule,
-    from_api_workspace,
-)
+"""
+Model exceptions, and the versioned model namespaces beneath this one.
+
+**No API type is exported here.** v2's types live in `uptimer.models.v2`:
+
+    from uptimer.models.v2 import CreateWebsiteMonitorRequest, Location
+
+Only the deserialization exceptions sit at this level, because they are
+version-independent — the same `TypeMismatchError` is raised whichever API
+version produced the payload.
+"""
+
 from .errors import (
     DeserializationError,
     InvalidDataTypeError,
@@ -12,36 +18,12 @@ from .errors import (
     TypeMismatchError,
     UnknownKindError,
 )
-from .region import Region
-from .rule import (
-    BaseRule,
-    CreateRuleRequest,
-    DeleteRuleResponse,
-    Rule,
-    RuleRequest,
-    RuleResponse,
-    RuleResponseBody,
-)
-from .workspace import Workspace
 
 __all__ = [
-    "BaseRule",
-    "CreateRuleRequest",
-    "DeleteRuleResponse",
     "DeserializationError",
     "InvalidDataTypeError",
     "MissingKindError",
     "ModelError",
-    "Region",
-    "Rule",
-    "RuleRequest",
-    "RuleResponse",
-    "RuleResponseBody",
     "TypeMismatchError",
     "UnknownKindError",
-    "Workspace",
-    "from_api",
-    "from_api_region",
-    "from_api_rule",
-    "from_api_workspace",
 ]