uptimer-python-sdk 1.5.0__tar.gz → 1.6.0rc0__tar.gz

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.6.0-rc.0 (2026-08-30)
+
+### Feat
+
+- **api**: post custom observations via client.v2 subjects/signals
+
 ## 1.5.0 (2026-08-20)
 
 ### BREAKING CHANGE

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: uptimer-python-sdk
-Version: 1.5.0
+Version: 1.6.0rc0
 Summary: A Python SDK for hosted and self-hosted Uptimer
 Project-URL: Homepage, https://myuptime.info
 Project-URL: Documentation, https://uptimer.myuptime.info/latest/reference/python-sdk/
@@ -153,6 +153,63 @@ except UptimerError:  # base error, if you need one
     raise
 ```
 
+### Reporting your own observations
+
+Uptimer probes websites itself. For anything else — a cron job, a queue worker,
+a nightly export — you add a **custom signal** to a subject in the Uptimer UI
+and report to it yourself.
+
+Requires Uptimer 1.6.0 or later, and a **custom heartbeat or event** signal. The
+platform HTTP signal of a website monitor is written by Uptimer's own probe and
+refuses posted observations.
+
+```python
+from uptimer.client import UptimerClient
+from uptimer.models.v2 import (
+    OBSERVATION_STATUS_OK,
+    OBSERVATION_STATUS_PROBLEM,
+    CreateObservationRequest,
+)
+
+client = UptimerClient(
+    api_key="your-api-key-here",
+    base_url="http://127.0.0.1:2517/api",
+)
+
+# The two slugs are the address: the subject, and the signal within it. Both
+# are shown on the signal's page in the Uptimer UI.
+observations = client.v2.subjects("checkout-api").signals("worker-pulse").observations
+
+# A heartbeat: "I ran, and I am fine."
+stored = observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_OK))
+
+# Everything except status is optional.
+stored = observations.create(
+    CreateObservationRequest(
+        status=OBSERVATION_STATUS_PROBLEM,
+        observed_at="2026-08-30T12:00:00Z",  # RFC 3339; omit to mean "now"
+        value=0.0,                            # optional numeric reading
+        error="queue backlog over threshold",
+        labels={"instance": "worker-3", "env": "prod"},
+    ),
+)
+
+print(stored.accepted, stored.reject_reason)
+```
+
+`accepted` reports **acceptance, not health**: it says Uptimer stored the
+observation and may evaluate it, not that anything is wrong or fine. Whether an
+observation raises an incident is decided by a *rule* that selects the signal.
+
+An observation Uptimer keeps but will not evaluate — one stamped too far in the
+future, say — comes back with `accepted=False` and a `reject_reason` such as
+`clock_skew`. It is **returned, not raised**: it was received. An exception
+means nothing was stored.
+
+Retries are safe. An observation is identified by its signal, its `observed_at`
+and its labels, so re-sending the same one replaces it rather than counting
+twice.
+
 ### Incident status
 
 `client.v2.incidents.all()` returns only **open** incidents. `status` carries the

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/README.md

@@ -137,6 +137,63 @@ except UptimerError:  # base error, if you need one
     raise
 ```
 
+### Reporting your own observations
+
+Uptimer probes websites itself. For anything else — a cron job, a queue worker,
+a nightly export — you add a **custom signal** to a subject in the Uptimer UI
+and report to it yourself.
+
+Requires Uptimer 1.6.0 or later, and a **custom heartbeat or event** signal. The
+platform HTTP signal of a website monitor is written by Uptimer's own probe and
+refuses posted observations.
+
+```python
+from uptimer.client import UptimerClient
+from uptimer.models.v2 import (
+    OBSERVATION_STATUS_OK,
+    OBSERVATION_STATUS_PROBLEM,
+    CreateObservationRequest,
+)
+
+client = UptimerClient(
+    api_key="your-api-key-here",
+    base_url="http://127.0.0.1:2517/api",
+)
+
+# The two slugs are the address: the subject, and the signal within it. Both
+# are shown on the signal's page in the Uptimer UI.
+observations = client.v2.subjects("checkout-api").signals("worker-pulse").observations
+
+# A heartbeat: "I ran, and I am fine."
+stored = observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_OK))
+
+# Everything except status is optional.
+stored = observations.create(
+    CreateObservationRequest(
+        status=OBSERVATION_STATUS_PROBLEM,
+        observed_at="2026-08-30T12:00:00Z",  # RFC 3339; omit to mean "now"
+        value=0.0,                            # optional numeric reading
+        error="queue backlog over threshold",
+        labels={"instance": "worker-3", "env": "prod"},
+    ),
+)
+
+print(stored.accepted, stored.reject_reason)
+```
+
+`accepted` reports **acceptance, not health**: it says Uptimer stored the
+observation and may evaluate it, not that anything is wrong or fine. Whether an
+observation raises an incident is decided by a *rule* that selects the signal.
+
+An observation Uptimer keeps but will not evaluate — one stamped too far in the
+future, say — comes back with `accepted=False` and a `reject_reason` such as
+`clock_skew`. It is **returned, not raised**: it was received. An exception
+means nothing was stored.
+
+Retries are safe. An observation is identified by its signal, its `observed_at`
+and its labels, so re-sending the same one replaces it rather than counting
+twice.
+
 ### Incident status
 
 `client.v2.incidents.all()` returns only **open** incidents. `status` carries the

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "uptimer-python-sdk"
-version = "1.5.0"
+version = "1.6.0-rc.0"
 description = "A Python SDK for hosted and self-hosted Uptimer"
 readme = "README.md"
 requires-python = ">=3.9"

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/src/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-rc.0"

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/src/uptimer/client.py

@@ -12,9 +12,11 @@ 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 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.

uptimer_python_sdk-1.6.0rc0/src/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_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/src/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)

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/src/uptimer/models/v2/__init__.py

@@ -13,6 +13,7 @@ from .deserialize import (
     from_api,
     from_api_incident,
     from_api_location,
+    from_api_observation,
     from_api_website_monitor,
     from_api_workspace,
 )
@@ -39,23 +40,47 @@ from .monitor import (
     WebsiteMonitorResponse,
     WebsiteMonitorResponseBody,
 )
+from .observation import (
+    REJECT_ACCEPTED,
+    REJECT_CLOCK_SKEW,
+    REJECT_LATE,
+    REJECT_OUT_OF_ORDER,
+    REJECT_OUT_OF_RETENTION,
+    CreateObservationRequest,
+    Observation,
+)
+from .observation import (
+    STATUS_OK as OBSERVATION_STATUS_OK,
+)
+from .observation import (
+    STATUS_PROBLEM as OBSERVATION_STATUS_PROBLEM,
+)
 from .workspace import Workspace
 
 __all__ = [
     "AGREEMENT_ALL",
     "AGREEMENT_ANY",
     "AGREEMENT_MAJORITY",
+    "OBSERVATION_STATUS_OK",
+    "OBSERVATION_STATUS_PROBLEM",
+    "REJECT_ACCEPTED",
+    "REJECT_CLOCK_SKEW",
+    "REJECT_LATE",
+    "REJECT_OUT_OF_ORDER",
+    "REJECT_OUT_OF_RETENTION",
     "STATUS_NO_DATA",
     "STATUS_OK",
     "STATUS_PENDING",
     "STATUS_PROBLEM",
     "STATUS_RECOVERING",
     "BaseWebsiteMonitor",
+    "CreateObservationRequest",
     "CreateWebsiteMonitorRequest",
     "DeleteWebsiteMonitorResponse",
     "Incident",
     "IncidentLocations",
     "Location",
+    "Observation",
     "UpdateWebsiteMonitorRequest",
     "WebsiteMonitor",
     "WebsiteMonitorRequest",
@@ -65,6 +90,7 @@ __all__ = [
     "from_api",
     "from_api_incident",
     "from_api_location",
+    "from_api_observation",
     "from_api_website_monitor",
     "from_api_workspace",
 ]

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/src/uptimer/models/v2/deserialize.py

@@ -17,6 +17,7 @@ from .monitor import (
     WebsiteMonitorResponse,
     WebsiteMonitorResponseBody,
 )
+from .observation import Observation
 from .workspace import Workspace
 
 T = TypeVar("T")
@@ -28,6 +29,7 @@ DeserializableType = Union[
     WebsiteMonitorResponseBody,
     Incident,
     Location,
+    Observation,
     Workspace,
 ]
 
@@ -42,6 +44,7 @@ _KIND_REGISTRY = {
     "website_monitor_response_body": WebsiteMonitorResponseBody,
     "incident": Incident,
     "location": Location,
+    "observation": Observation,
     "workspace": Workspace,
 }
 
@@ -117,3 +120,12 @@ def from_api_incident(data: dict[str, Any]) -> Incident:
         expected = "Incident"
         raise TypeMismatchError(expected, type(obj).__name__)
     return obj
+
+
+def from_api_observation(data: dict[str, Any]) -> Observation:
+    """Deserialize a stored observation."""
+    obj = from_api(data)
+    if not isinstance(obj, Observation):
+        expected = "Observation"
+        raise TypeMismatchError(expected, type(obj).__name__)
+    return obj

uptimer_python_sdk-1.6.0rc0/src/uptimer/models/v2/observation.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# The two words a custom sender may report. There is no "unknown" to send: an
+# observation exists to say whether the sender is ok or in trouble, and an unset
+# status is never read as health.
+STATUS_OK = "ok"
+STATUS_PROBLEM = "problem"
+
+# Why a stored observation will not be evaluated. `accepted` is the only one that
+# means the engine may use the row; the rest are kept and shown so an operator
+# can see that data arrived and was set aside, rather than wondering whether it
+# was ever received.
+REJECT_ACCEPTED = "accepted"
+REJECT_LATE = "late"
+REJECT_OUT_OF_ORDER = "out_of_order"
+# Stamped too far ahead of the server's clock.
+REJECT_CLOCK_SKEW = "clock_skew"
+REJECT_OUT_OF_RETENTION = "out_of_retention"
+
+
+@dataclass
+class CreateObservationRequest:
+    """
+    One observation to report for a custom heartbeat or event signal.
+
+    Only `status` is required. `observed_at` defaults to the moment the server
+    receives the report, which is what a heartbeat usually wants; send it
+    explicitly when reporting something that happened earlier.
+
+    `labels` is your own vocabulary — Uptimer stores it and matches rules
+    against it, and never requires a particular key.
+    """
+
+    status: str
+    # RFC 3339, for example "2026-08-30T12:00:00Z". None means "now".
+    observed_at: str | None = None
+    # The optional numeric reading a rule can compare against a threshold.
+    value: float | None = None
+    # The sender's own error text, for a problem worth explaining.
+    error: str | None = None
+    labels: dict[str, str] | None = None
+
+
+@dataclass
+class Observation:
+    """
+    One observation as the server stored it.
+
+    `accepted` reports ACCEPTANCE, not health: it says the engine may use this
+    row, not that the subject is fine. Whether anything is wrong is decided by a
+    rule, and no rule need select this signal at all. Read `status` for what was
+    reported.
+
+    A refused observation is returned rather than raised as an error — it was
+    stored, it is visible in the Unaccepted log, and `reject_reason` names why
+    it will not be evaluated.
+    """
+
+    subject_id: str  # the subject slug the observation was posted to
+    signal_id: str  # the signal slug within that subject
+    observed_at: str  # when the SENDER observed it
+    received_at: str  # when the server stored it
+    status: str
+    value: float | None
+    error: str
+    labels: dict[str, str] = field(default_factory=dict)
+    accepted: bool = False
+    reject_reason: str = REJECT_ACCEPTED
+    kind: str = "observation"

uptimer_python_sdk-1.6.0rc0/tests/integrations/test_observations.py

@@ -0,0 +1,143 @@
+"""
+Custom observation ingest against a running Uptimer.
+
+Unlike the other integration tests, this one does not drive the browser to mint
+a key: reporting an observation needs a subject and a signal that already exist,
+so the run supplies them. Set
+
+    UPTIMER_API_KEY, UPTIMER_SUBJECT_SLUG, UPTIMER_SIGNAL_SLUG
+
+and optionally UPTIMER_HTTP_SIGNAL_SLUG (a platform HTTP signal, to prove it is
+refused) and UPTIMER_URL. Without the first three the module skips, so a plain
+`--integration` run against a server with no custom signal stays green.
+"""
+
+import os
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from tests.conftest import integration_test
+from uptimer.errors import DefaultUptimerApiError
+from uptimer.models.v2 import (
+    OBSERVATION_STATUS_OK,
+    OBSERVATION_STATUS_PROBLEM,
+    REJECT_ACCEPTED,
+    REJECT_CLOCK_SKEW,
+    CreateObservationRequest,
+)
+
+from .conftest import get_client
+
+API_KEY = os.environ.get("UPTIMER_API_KEY", "")
+SUBJECT_SLUG = os.environ.get("UPTIMER_SUBJECT_SLUG", "")
+SIGNAL_SLUG = os.environ.get("UPTIMER_SIGNAL_SLUG", "")
+HTTP_SIGNAL_SLUG = os.environ.get("UPTIMER_HTTP_SIGNAL_SLUG", "")
+
+needs_signal = pytest.mark.skipif(
+    not (API_KEY and SUBJECT_SLUG and SIGNAL_SLUG),
+    reason="set UPTIMER_API_KEY, UPTIMER_SUBJECT_SLUG and UPTIMER_SIGNAL_SLUG",
+)
+
+
+def _observations(uptimer_url: str):  # noqa: ANN202
+    client = get_client(API_KEY, uptimer_url)
+    return client.v2.subjects(SUBJECT_SLUG).signals(SIGNAL_SLUG).observations
+
+
+def _at(offset: timedelta = timedelta()) -> str:
+    stamped = datetime.now(timezone.utc).replace(microsecond=0) + offset
+    return stamped.isoformat().replace("+00:00", "Z")
+
+
+@integration_test
+@needs_signal
+def test_report_an_accepted_observation(uptimer_url: str):
+    stored = _observations(uptimer_url).create(
+        CreateObservationRequest(
+            status=OBSERVATION_STATUS_OK,
+            observed_at=_at(),
+            value=1.5,
+            labels={"instance": "sdk-it"},
+        ),
+    )
+
+    assert stored.kind == "observation"
+    assert stored.subject_id == SUBJECT_SLUG
+    assert stored.signal_id == SIGNAL_SLUG
+    assert stored.status == OBSERVATION_STATUS_OK
+    assert stored.value == 1.5
+    assert stored.labels == {"instance": "sdk-it"}
+    assert stored.accepted is True
+    assert stored.reject_reason == REJECT_ACCEPTED
+    assert stored.received_at
+
+
+@integration_test
+@needs_signal
+def test_status_only_is_enough(uptimer_url: str):
+    """Everything but status is optional; the server stamps the time."""
+    stored = _observations(uptimer_url).create(
+        CreateObservationRequest(status=OBSERVATION_STATUS_PROBLEM),
+    )
+
+    assert stored.accepted is True
+    assert stored.status == OBSERVATION_STATUS_PROBLEM
+    assert stored.observed_at
+
+
+@integration_test
+@needs_signal
+def test_a_skewed_observation_is_stored_and_not_accepted(uptimer_url: str):
+    """
+    Stored, not raised.
+
+    A timestamp far ahead of the server is kept and shown, never evaluated. The
+    sender is told which of those two happened.
+    """
+    stored = _observations(uptimer_url).create(
+        CreateObservationRequest(
+            status=OBSERVATION_STATUS_OK,
+            observed_at=_at(timedelta(hours=1)),
+            labels={"instance": "sdk-it-skew"},
+        ),
+    )
+
+    assert stored.accepted is False
+    assert stored.reject_reason == REJECT_CLOCK_SKEW
+
+
+@integration_test
+@needs_signal
+def test_an_invalid_status_is_refused(uptimer_url: str):
+    with pytest.raises(DefaultUptimerApiError) as excinfo:
+        _observations(uptimer_url).create(CreateObservationRequest(status="degraded"))
+    assert "status" in excinfo.value.message.lower()
+
+
+@integration_test
+@needs_signal
+def test_an_unknown_signal_is_refused(uptimer_url: str):
+    client = get_client(API_KEY, uptimer_url)
+    observations = client.v2.subjects(SUBJECT_SLUG).signals("no-such-signal").observations
+
+    with pytest.raises(DefaultUptimerApiError) as excinfo:
+        observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_OK))
+    assert excinfo.value.error_type == "not_found"
+
+
+@integration_test
+@pytest.mark.skipif(
+    not (API_KEY and SUBJECT_SLUG and HTTP_SIGNAL_SLUG),
+    reason="set UPTIMER_HTTP_SIGNAL_SLUG to prove the platform signal is refused",
+)
+def test_a_platform_http_signal_is_refused(uptimer_url: str):
+    """Uptimer's own probe owns that stream; a posted claim is not a measurement."""
+    client = get_client(API_KEY, uptimer_url)
+    observations = (
+        client.v2.subjects(SUBJECT_SLUG).signals(HTTP_SIGNAL_SLUG).observations
+    )
+
+    with pytest.raises(DefaultUptimerApiError) as excinfo:
+        observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_OK))
+    assert excinfo.value.error_type == "forbidden"

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/tests/test_model_namespace.py

@@ -37,17 +37,29 @@ def test_v2_exports_the_whole_public_surface():
         "AGREEMENT_ALL",
         "AGREEMENT_ANY",
         "AGREEMENT_MAJORITY",
+        # The observation status words are prefixed: an incident STATUS_OK is a
+        # derived display state, an observation's is what a sender reported.
+        # Same string, different question — so they do not share a name.
+        "OBSERVATION_STATUS_OK",
+        "OBSERVATION_STATUS_PROBLEM",
+        "REJECT_ACCEPTED",
+        "REJECT_CLOCK_SKEW",
+        "REJECT_LATE",
+        "REJECT_OUT_OF_ORDER",
+        "REJECT_OUT_OF_RETENTION",
         "STATUS_NO_DATA",
         "STATUS_OK",
         "STATUS_PENDING",
         "STATUS_PROBLEM",
         "STATUS_RECOVERING",
         "BaseWebsiteMonitor",
+        "CreateObservationRequest",
         "CreateWebsiteMonitorRequest",
         "DeleteWebsiteMonitorResponse",
         "Incident",
         "IncidentLocations",
         "Location",
+        "Observation",
         "UpdateWebsiteMonitorRequest",
         "WebsiteMonitor",
         "WebsiteMonitorRequest",
@@ -57,6 +69,7 @@ def test_v2_exports_the_whole_public_surface():
         "from_api",
         "from_api_incident",
         "from_api_location",
+        "from_api_observation",
         "from_api_website_monitor",
         "from_api_workspace",
     }

uptimer_python_sdk-1.6.0rc0/tests/test_observations_endpoint.py

@@ -0,0 +1,217 @@
+"""
+Custom observation ingest: `client.v2.subjects(s).signals(g).observations`.
+
+The path is the contract as much as the payload — a signal slug is unique
+within its subject, not across the workspace, so the pair is the address and
+both halves must reach the URL intact.
+
+The other half of the contract is what is NOT an error: a stored observation
+the engine will not evaluate comes back with `accepted: False`, because it was
+received. Only a request that stored nothing raises.
+"""
+
+import json
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from tests.conftest import api_response
+from uptimer.client import UptimerClient
+from uptimer.errors import DefaultUptimerApiError
+from uptimer.models.v2 import (
+    OBSERVATION_STATUS_OK,
+    OBSERVATION_STATUS_PROBLEM,
+    REJECT_ACCEPTED,
+    REJECT_CLOCK_SKEW,
+    CreateObservationRequest,
+    Observation,
+    from_api_observation,
+)
+
+
+def _stored(
+    *,
+    accepted: bool = True,
+    reject_reason: str = REJECT_ACCEPTED,
+    status: str = OBSERVATION_STATUS_OK,
+) -> dict:
+    return {
+        "subject_id": "checkout",
+        "signal_id": "worker-pulse",
+        "observed_at": "2026-08-30T12:00:00Z",
+        "received_at": "2026-08-30T12:00:01Z",
+        "status": status,
+        "value": 1.5,
+        "error": "",
+        "labels": {"instance": "i-123"},
+        "accepted": accepted,
+        "reject_reason": reject_reason,
+        "kind": "observation",
+    }
+
+
+def test_paths(uptimer_client: UptimerClient):
+    assert uptimer_client.v2.subjects.path == "v2/subjects"
+    subject = uptimer_client.v2.subjects("checkout")
+    assert subject.signals.path == "v2/subjects/checkout/signals"
+    assert (
+        subject.signals("worker-pulse").observations.path
+        == "v2/subjects/checkout/signals/worker-pulse/observations"
+    )
+
+
+def test_slugs_are_escaped_into_the_path(uptimer_client: UptimerClient):
+    """A slug is data, not a path fragment: a slash must not address elsewhere."""
+    observations = uptimer_client.v2.subjects("a/b").signals("c d").observations
+    assert observations.path == "v2/subjects/a%2Fb/signals/c%20d/observations"
+
+
+@pytest.mark.parametrize("slug", ["", "   "])
+def test_an_empty_slug_is_refused(uptimer_client: UptimerClient, slug: str):
+    with pytest.raises(ValueError, match="slug is required"):
+        uptimer_client.v2.subjects(slug)
+    with pytest.raises(ValueError, match="slug is required"):
+        uptimer_client.v2.subjects("checkout").signals(slug)
+
+
+def test_create_posts_to_the_signals_observations_url(
+    uptimer_client: UptimerClient,
+    httpx_mock: HTTPXMock,
+):
+    httpx_mock.add_response(json=api_response(_stored()))
+
+    uptimer_client.v2.subjects("checkout").signals("worker-pulse").observations.create(
+        CreateObservationRequest(status=OBSERVATION_STATUS_OK),
+    )
+
+    request = httpx_mock.get_requests()[0]
+    assert request.method == "POST"
+    assert str(request.url).endswith(
+        "/v2/subjects/checkout/signals/worker-pulse/observations",
+    )
+
+
+def test_create_sends_only_the_fields_that_were_set(
+    uptimer_client: UptimerClient,
+    httpx_mock: HTTPXMock,
+):
+    """
+    Only what was set is sent.
+
+    The server rejects unknown fields and reads an absent optional differently
+    from a null one — an absent observed_at means "stamp it now".
+    """
+    httpx_mock.add_response(json=api_response(_stored()))
+
+    uptimer_client.v2.subjects("checkout").signals("worker-pulse").observations.create(
+        CreateObservationRequest(status=OBSERVATION_STATUS_OK),
+    )
+
+    body = json.loads(httpx_mock.get_requests()[0].content)
+    assert body == {"status": "ok"}
+
+
+def test_create_sends_every_field_that_was_set(
+    uptimer_client: UptimerClient,
+    httpx_mock: HTTPXMock,
+):
+    httpx_mock.add_response(json=api_response(_stored()))
+
+    uptimer_client.v2.subjects("checkout").signals("worker-pulse").observations.create(
+        CreateObservationRequest(
+            status=OBSERVATION_STATUS_PROBLEM,
+            observed_at="2026-08-30T12:00:00Z",
+            value=0.0,
+            error="connection refused",
+            labels={"instance": "i-123"},
+        ),
+    )
+
+    body = json.loads(httpx_mock.get_requests()[0].content)
+    assert body == {
+        "status": "problem",
+        "observed_at": "2026-08-30T12:00:00Z",
+        "value": 0.0,
+        "error": "connection refused",
+        "labels": {"instance": "i-123"},
+    }
+
+
+def test_create_returns_the_stored_observation(
+    uptimer_client: UptimerClient,
+    httpx_mock: HTTPXMock,
+):
+    httpx_mock.add_response(json=api_response(_stored()))
+
+    stored = uptimer_client.v2.subjects("checkout").signals(
+        "worker-pulse",
+    ).observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_OK))
+
+    assert isinstance(stored, Observation)
+    assert stored.subject_id == "checkout"
+    assert stored.signal_id == "worker-pulse"
+    assert stored.status == OBSERVATION_STATUS_OK
+    assert stored.value == 1.5
+    assert stored.labels == {"instance": "i-123"}
+    assert stored.accepted is True
+    assert stored.reject_reason == REJECT_ACCEPTED
+    assert stored.kind == "observation"
+
+
+def test_a_refused_observation_is_returned_not_raised(
+    uptimer_client: UptimerClient,
+    httpx_mock: HTTPXMock,
+):
+    """
+    A refused observation is a result, not an error.
+
+    It was received and stored; the engine just will not evaluate it. Raising
+    here would tell a sender its data never arrived, which is the opposite of
+    what happened.
+    """
+    httpx_mock.add_response(
+        json=api_response(
+            _stored(
+                accepted=False,
+                reject_reason=REJECT_CLOCK_SKEW,
+                status=OBSERVATION_STATUS_PROBLEM,
+            ),
+        ),
+    )
+
+    stored = uptimer_client.v2.subjects("checkout").signals(
+        "worker-pulse",
+    ).observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_PROBLEM))
+
+    assert stored.accepted is False
+    assert stored.reject_reason == REJECT_CLOCK_SKEW
+
+
+def test_an_api_error_is_raised(
+    uptimer_client: UptimerClient,
+    httpx_mock: HTTPXMock,
+):
+    """A platform HTTP signal refuses posted observations, and so does a bad body."""
+    httpx_mock.add_response(
+        json=api_response(
+            None,
+            error={
+                "code": 2003,
+                "error_type": "forbidden",
+                "message": "Signal does not accept posted observations",
+                "details": "only custom heartbeat and custom event signals accept posted observations",
+            },
+        ),
+    )
+
+    with pytest.raises(DefaultUptimerApiError):
+        uptimer_client.v2.subjects("checkout").signals(
+            "website-http",
+        ).observations.create(CreateObservationRequest(status=OBSERVATION_STATUS_OK))
+
+
+def test_observation_kind_is_registered():
+    """Without the kind, from_api cannot build this object at all."""
+    stored = from_api_observation(_stored())
+    assert isinstance(stored, Observation)
+    assert stored.accepted is True

{uptimer_python_sdk-1.5.0 → uptimer_python_sdk-1.6.0rc0}/uv.lock

@@ -1150,7 +1150,7 @@ wheels = [
 
 [[package]]
 name = "uptimer-python-sdk"
-version = "1.5.0"
+version = "1.6.0-rc.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },