uptimer-python-sdk 1.5.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

uptimer/__init__.py

@@ -4,9 +4,9 @@ Uptimer Python SDK.
 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.5.x speaks to
-uptimer 1.5.0 and later. Patch numbers are independent, so an SDK fix can ship
+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.5.0"
+__version__ = "1.6.0"

uptimer/client.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import cast
 
 from uptimer.compat import ensure_v2_supported
+from uptimer.endpoints.v1 import V1Endpoint
 from uptimer.endpoints.v2 import V2Endpoint
 from uptimer.http import UptimerHttpLib
 
@@ -12,14 +13,22 @@ class UptimerClient:
     The Uptimer API client.
 
     Resources are reached through the API version that serves them:
-    `client.v2.workspaces`, `client.v2.locations`, `client.v2.incidents` and
-    `client.v2.monitoring.websites`. This SDK does not speak API v1 — see the
-    migration note in the README if you are coming from 0.4.x.
+    `client.v2.workspaces`, `client.v2.locations`, `client.v2.incidents`,
+    `client.v2.monitoring.websites` and
+    `client.v2.subjects(subject).signals(signal).observations`.
+
+    This is a v2 client. `client.v1` exists for one thing only: uptimer 1.7.0
+    serves WEBSITE incident acknowledgement under `/v1/rules/...`, because
+    website monitoring is v1's resource and custom monitoring is v2's. Reading
+    and writing website monitors themselves stays on
+    `client.v2.monitoring.websites` — 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.
     """
 
+    v1: V1Endpoint
     v2: V2Endpoint
 
     def __init__(self, api_key: str, base_url: str):
@@ -28,6 +37,7 @@ class UptimerClient:
         self._wire()
 
     def _wire(self) -> None:
+        self.v1 = V1Endpoint(self._http_lib)
         self.v2 = V2Endpoint(self._http_lib)
 
     def version(self) -> str:

uptimer/endpoints/subjects.py

@@ -0,0 +1,439 @@
+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_acknowledgement,
+    from_api_maintenance,
+    from_api_observation,
+    from_api_subject,
+    from_api_subject_incident,
+)
+
+if TYPE_CHECKING:
+    from uptimer.http import UptimerHttpLib
+    from uptimer.models.v2 import (
+        CreateObservationRequest,
+        CreateSubjectRequest,
+        IncidentAcknowledgement,
+        MaintenanceWindow,
+        Observation,
+        Subject,
+        SubjectIncident,
+    )
+
+
+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 custom subject.
+
+    Call it with a slug to reach one:
+    `client.v2.subjects("nightly-export").signals("worker-pulse")`.
+
+    There is no listing or authoring here. Uptimer 1.6.0 serves those routes —
+    the Signals screen has an API half — but this SDK does not wrap them yet:
+    add a signal in the Uptimer UI, and use this 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 SubjectIncidentEndpoint(BaseEndpoint):
+    """One incident of a custom subject, addressed by its opaque id."""
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        incident_id: str,
+        parent_segments: str | list[str] | None = None,
+        workspace_id: str | None = None,
+    ):
+        super().__init__(http, _slug(incident_id, "incident"), parent_segments)
+        self._workspace_id = workspace_id
+
+    def acknowledge(self) -> IncidentAcknowledgement:
+        """
+        Record that you have seen THIS incident. Requires uptimer 1.7.0+.
+
+        It says a person looked; it changes nothing the engine decided. The
+        verdict, the evidence and the close hold carry on. Its one effect on
+        alerting is that the four-hour reminders for this incident stop
+        (uptimer 1.7.0); nothing else is silenced, and the recovery still
+        arrives.
+
+        There is no body and no actor argument: the person recorded is the owner
+        of the API key, and the time is the time of the call. The server refuses
+        a body rather than letting one client file an acknowledgement under
+        another person's name.
+
+        Repeating it is safe. A second call records nothing, adds no second
+        history entry, and returns the FIRST person's name and time with
+        `recorded=False`.
+
+        Raises DefaultUptimerApiError when the incident is not this subject's —
+        another subject's, another workspace's, or a website monitor's — and
+        when it has closed. Nothing is retried through the other family: a
+        website incident is acknowledged through `client.v1.rules(...)`, and
+        this method will not do it for you.
+        """
+        params = {"workspace_id": self._workspace_id} if self._workspace_id else None
+        response = self.http.client.post(f"{self.url}/acknowledge", params=params)
+        result = self.http.parse_response(response=response)
+        return from_api_acknowledgement(result)
+
+
+class SubjectIncidentsEndpoint(BaseEndpoint):
+    """
+    The OPEN incidents of one custom subject. Requires uptimer 1.7.0+.
+
+    This is where an acknowledgement target comes from. The acknowledge call
+    takes one exact incident id and refuses to guess — a subject can have
+    several incidents open at once — so the flow is: list these, choose the one
+    you mean, acknowledge it by id.
+
+    `client.v2.incidents` is the WEBSITE list and does not serve custom
+    subjects; this is its custom counterpart, scoped to one subject.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+        workspace_id: str | None = None,
+    ):
+        super().__init__(http, "incidents", parent_segments)
+        self._workspace_id = workspace_id
+
+    def __call__(self, incident_id: str) -> SubjectIncidentEndpoint:
+        return SubjectIncidentEndpoint(
+            self.http,
+            incident_id,
+            [*self._parent_segments, self.segment],
+            self._workspace_id,
+        )
+
+    def all(self) -> list[SubjectIncident]:
+        """
+        Every open incident of this subject, newest trouble first.
+
+        Open ones only, and all of them: pending, recovering and no-data
+        included, and already-acknowledged ones too — that somebody is on one is
+        half of what this answers. A subject with nothing wrong returns [].
+
+        Closed history is not here; it lives on the subject timeline in the
+        dashboard.
+        """
+        params = {"workspace_id": self._workspace_id} if self._workspace_id else None
+        response = self.http.client.get(self.url, params=params)
+        result = self.http.parse_response(response=response)
+        return [from_api_subject_incident(item) for item in result]
+
+
+class MaintenanceEndpoint(BaseEndpoint):
+    """
+    The maintenance window of one custom subject. Requires uptimer 1.7.0+.
+
+    A window holds back this subject's PROBLEM notifications until the time you
+    choose. Nothing else changes: monitoring runs, incidents open and close, the
+    timeline records all of it — so afterwards the outage reads exactly as it
+    happened. Recoveries are never held back.
+
+    Four operations: read it, start one, move its end, end it early. Moving the
+    end is a real update — the window keeps its identity and its start, and
+    nothing that reads it sees the subject briefly leave maintenance.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+        workspace_id: str | None = None,
+    ):
+        super().__init__(http, "maintenance", parent_segments)
+        self._workspace_id = workspace_id
+
+    def _params(self) -> dict | None:
+        return {"workspace_id": self._workspace_id} if self._workspace_id else None
+
+    def get(self) -> MaintenanceWindow | None:
+        """
+        Return the window running on this subject, or None.
+
+        None is an ANSWER, not an error: a script checking whether it is safe to
+        deploy should not have to catch an exception for the ordinary case.
+        """
+        response = self.http.client.get(self.url, params=self._params())
+        result = self.http.parse_response(response=response)
+        if result is None:
+            return None
+        return from_api_maintenance(result)
+
+    def start(self, ends_at: str) -> MaintenanceWindow:
+        """
+        Start a window now, ending at `ends_at`.
+
+        `ends_at` is an RFC 3339 timestamp and carries its own zone, so there is
+        nothing to guess — pass "2026-09-13T18:00:00Z" or your own offset.
+
+        Raises DefaultUptimerApiError when the time has already passed, when a
+        window is already running on this subject (cancel it first), when the
+        subject is a website check — those are managed from the dashboard — or
+        when the caller is not an editor of that workspace.
+        """
+        response = self.http.client.post(
+            self.url,
+            params=self._params(),
+            json={"ends_at": ends_at},
+        )
+        result = self.http.parse_response(response=response)
+        return from_api_maintenance(result)
+
+    def update_end(self, ends_at: str) -> MaintenanceWindow:
+        """
+        Move the end of the window that is already running.
+
+        It is an UPDATE, not a cancel and a new window: the window keeps its
+        identity and its start, so "since when have we been silencing this?"
+        keeps one answer, and nothing that reads it sees the subject briefly
+        leave maintenance. Nothing is notified — moving an end time is a
+        correction to a plan, not an event.
+
+        `ends_at` is RFC 3339, as it is for `start`. A time that has already
+        passed raises rather than ending the window: to stop it now, call
+        `cancel()`. So does a subject with nothing running — there is no end to
+        move — and a caller who is not an editor.
+        """
+        response = self.http.client.post(
+            f"{self.url}/ends_at",
+            params=self._params(),
+            json={"ends_at": ends_at},
+        )
+        result = self.http.parse_response(response=response)
+        return from_api_maintenance(result)
+
+    def cancel(self) -> MaintenanceWindow:
+        """
+        End the running window now, and return it as it was recorded.
+
+        Notifications are back to normal immediately. Raises
+        DefaultUptimerApiError when there is nothing to cancel: "it was already
+        over" is worth knowing rather than reporting as success.
+        """
+        response = self.http.client.delete(self.url, params=self._params())
+        result = self.http.parse_response(response=response)
+        return from_api_maintenance(result)
+
+
+class SubjectEndpoint(BaseEndpoint):
+    """One monitored subject, addressed by its slug."""
+
+    signals: SignalsEndpoint
+    incidents: SubjectIncidentsEndpoint
+    maintenance: MaintenanceEndpoint
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        subject_slug: str,
+        parent_segments: str | list[str] | None = None,
+        workspace_id: str | None = None,
+    ):
+        super().__init__(http, _slug(subject_slug, "subject"), parent_segments)
+        self.signals = SignalsEndpoint(http, [*self._parent_segments, self.segment])
+        self.incidents = SubjectIncidentsEndpoint(
+            http,
+            [*self._parent_segments, self.segment],
+            workspace_id,
+        )
+        self.maintenance = MaintenanceEndpoint(
+            http,
+            [*self._parent_segments, self.segment],
+            workspace_id,
+        )
+
+
+class SubjectsEndpoint(BaseEndpoint):
+    """
+    The workspace's CUSTOM monitored subjects.
+
+    Uptimer splits its API by subject kind: website monitoring is
+    `client.v2.monitoring.websites`, and this is the custom half. Neither one
+    serves the other's subjects — a website subject's slug is refused here.
+
+    Two ways in, because there are two things to do with a subject:
+
+    - call it with a slug to reach what is under one —
+      `client.v2.subjects("nightly-export").signals("worker-pulse").observations`;
+    - call the methods here to list, fetch, or create one.
+
+    There is no update or delete. Deleting a subject takes its whole history
+    with it, which is not something to do by accident from a script.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "subjects", parent_segments)
+
+    def __call__(self, subject_slug: str, workspace_id: str | None = None) -> SubjectEndpoint:
+        """
+        Reach one subject by slug.
+
+        `workspace_id` settles an ambiguity rather than being required: a slug
+        is unique within a workspace, not across them. Pass it when the same
+        slug exists in two workspaces you belong to, and the incident routes
+        under this subject will carry it.
+        """
+        return SubjectEndpoint(
+            self.http,
+            subject_slug,
+            [*self._parent_segments, self.segment],
+            workspace_id,
+        )
+
+    def all(self, workspace_id: str) -> list[Subject]:
+        """
+        Every CUSTOM subject in a workspace.
+
+        Website monitoring is not here — it is `client.v2.monitoring.websites`.
+        Against a 1.6.0 server every item reads `subject_kind == "custom"`;
+        `subject_kind` is still on the model, because an older server answered
+        this route with both kinds.
+        """
+        response = self.http.client.get(self.url, params={"workspace_id": workspace_id})
+        result = self.http.parse_response(response=response)
+        return [from_api_subject(item) for item in result]
+
+    def get(self, subject_slug: str, workspace_id: str | None = None) -> Subject:
+        """
+        One custom subject by its slug.
+
+        `workspace_id` is optional and settles an ambiguity rather than being
+        required: a slug is unique within a workspace, not across them, so pass
+        it when the same slug exists in two workspaces you belong to. Without
+        it the server searches your memberships and says so if the answer is
+        more than one.
+
+        A website subject's slug raises a DefaultUptimerApiError saying it is
+        managed elsewhere.
+        """
+        params = {"workspace_id": workspace_id} if workspace_id else None
+        response = self.http.client.get(
+            f"{self.url}/{_slug(subject_slug, 'subject')}",
+            params=params,
+        )
+        result = self.http.parse_response(response=response)
+        return from_api_subject(result)
+
+    def create(self, subject: CreateSubjectRequest) -> Subject:
+        """
+        Create one empty Custom subject.
+
+        It arrives with nothing under it: no signal, no rule, no HTTP probe.
+        Add a signal to it in the Uptimer UI, then report to that signal through
+        `client.v2.subjects(...).signals(...).observations`.
+
+        Website monitoring is created by `client.v2.monitoring.websites.create`
+        instead — it needs a URL, an interval and locations, and asking for one
+        here is refused with a DefaultUptimerApiError saying so.
+        """
+        response = self.http.client.post(self.url, json=asdict(subject))
+        result = self.http.parse_response(response=response)
+        return from_api_subject(result)

uptimer/endpoints/v1.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from uptimer.endpoints.endpoint import BaseEndpoint
+from uptimer.models.v2 import from_api_acknowledgement
+
+if TYPE_CHECKING:
+    from uptimer.http import UptimerHttpLib
+    from uptimer.models.v2 import IncidentAcknowledgement
+
+
+def _segment(value: str, what: str) -> str:
+    """Escape one identifier for a URL path segment."""
+    if not value or not value.strip():
+        message = f"{what} is required"
+        raise ValueError(message)
+    return quote(value, safe="")
+
+
+class WebsiteIncidentEndpoint(BaseEndpoint):
+    """One incident of a website monitor, addressed by its opaque id."""
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        incident_id: str,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, _segment(incident_id, "incident id"), parent_segments)
+
+    def acknowledge(self) -> IncidentAcknowledgement:
+        """
+        Record that you have seen THIS website incident. Requires uptimer 1.7.0+.
+
+        Find the id with `client.v2.incidents.all(workspace_id)`, which lists
+        open website incidents with the monitor each belongs to.
+
+        It says a person looked; it changes nothing the engine decided — the
+        verdict, the evidence and the close hold all carry on. Its one effect on
+        alerting is that the four-hour reminders for this incident stop (uptimer
+        1.7.0); nothing else is silenced, and the recovery still arrives. There
+        is no body and no actor argument: the person recorded is the owner of
+        the API key, at the time of the call.
+
+        Repeating it is safe: a second call records nothing and returns the
+        FIRST person's name and time with `recorded=False`.
+
+        Raises DefaultUptimerApiError when the incident is not this monitor's —
+        another monitor's, another workspace's, or a custom subject's — and when
+        it has closed. A custom incident is acknowledged through
+        `client.v2.subjects(...).incidents(...)`, and this will not do it for
+        you: the families do not fall back to one another.
+        """
+        response = self.http.client.post(f"{self.url}/acknowledge")
+        result = self.http.parse_response(response=response)
+        return from_api_acknowledgement(result)
+
+
+class WebsiteIncidentsEndpoint(BaseEndpoint):
+    """
+    The incidents of one website monitor, addressed by id.
+
+    There is no listing here: open website incidents are listed for a whole
+    workspace by `client.v2.incidents.all(workspace_id)`, which is the discovery
+    path this SDK has had since 1.5.0 and which already names each incident's
+    monitor. This exists to act on one of them.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "incidents", parent_segments)
+
+    def __call__(self, incident_id: str) -> WebsiteIncidentEndpoint:
+        return WebsiteIncidentEndpoint(
+            self.http,
+            incident_id,
+            [*self._parent_segments, self.segment],
+        )
+
+
+class RuleEndpoint(BaseEndpoint):
+    """One website monitor, addressed by its uid."""
+
+    incidents: WebsiteIncidentsEndpoint
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        monitor_uid: str,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, _segment(monitor_uid, "monitor uid"), parent_segments)
+        self.incidents = WebsiteIncidentsEndpoint(http, [*self._parent_segments, self.segment])
+
+
+class RulesEndpoint(BaseEndpoint):
+    """
+    Website monitors, as API v1 calls them.
+
+    Call it with a monitor's uid to reach what is under one:
+    `client.v1.rules(monitor_uid).incidents(incident_id).acknowledge()`.
+
+    Reading and writing monitors themselves stays on
+    `client.v2.monitoring.websites` — the same resource in v2's words, and the
+    one this SDK is built around.
+    """
+
+    def __init__(
+        self,
+        http: UptimerHttpLib,
+        parent_segments: str | list[str] | None = None,
+    ):
+        super().__init__(http, "rules", parent_segments)
+
+    def __call__(self, monitor_uid: str) -> RuleEndpoint:
+        return RuleEndpoint(self.http, monitor_uid, [*self._parent_segments, self.segment])
+
+
+class V1Endpoint(BaseEndpoint):
+    """
+    API v1, narrowly: `client.v1`.
+
+    This SDK is a v2 client, and that has not changed. v1 appears here for one
+    reason: uptimer 1.7.0 serves WEBSITE acknowledgement under
+    `/v1/rules/{uid}/incidents/{id}/acknowledge`, because website monitoring is
+    v1's resource (Decision 0015) and custom monitoring is v2's. Each kind
+    acknowledges through its own family, and neither route accepts the other's
+    incidents.
+
+    So this namespace is the acknowledgement door for website monitors, and
+    nothing else: no rule listing, no create, no update, no delete. Those live
+    on `client.v2.monitoring.websites`, which speaks v2's vocabulary and is
+    where a v2 client belongs.
+    """
+
+    rules: RulesEndpoint
+
+    def __init__(self, http: UptimerHttpLib):
+        super().__init__(http, "v1")
+        self.rules = RulesEndpoint(http, [self.segment])

uptimer/endpoints/v2.py

@@ -5,6 +5,7 @@ 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
 
@@ -28,6 +29,7 @@ class V2Endpoint(BaseEndpoint):
     locations: LocationsEndpoint
     incidents: IncidentsEndpoint
     monitoring: MonitoringEndpoint
+    subjects: SubjectsEndpoint
 
     def __init__(self, http: UptimerHttpLib):
         super().__init__(http, "v2")
@@ -36,3 +38,4 @@ class V2Endpoint(BaseEndpoint):
         self.locations = LocationsEndpoint(http, parent)
         self.incidents = IncidentsEndpoint(http, parent)
         self.monitoring = MonitoringEndpoint(http, parent)
+        self.subjects = SubjectsEndpoint(http, parent)