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

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

@@ -1,3 +1,17 @@
+## 1.7.0 (2026-09-14)
+
+### Feat
+
+- change maintenance end time on Custom subjects
+- subject maintenance window client
+- acknowledge Website and Custom incidents on separate clients
+
+## 1.6.0 (2026-09-08)
+
+### Feat
+
+- **sdk**: list and create Website/Custom subjects
+
 ## 1.6.0-rc.0 (2026-08-30)
 
 ### Feat

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.5
+Metadata-Version: 2.4
 Name: uptimer-python-sdk
-Version: 1.6.0rc0
+Version: 1.7.0
 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,65 @@ except UptimerError:  # base error, if you need one
     raise
 ```
 
+### Subjects: your custom monitoring
+
+A **subject** is one monitored thing. Every subject is one of two kinds, and the
+kind says how it is configured:
+
+- **website** — Uptimer's own probe watches a URL, and the website check form
+  owns its signal and its rule;
+- **custom** — yours, reporting through the signals you add to it.
+
+Uptimer 1.6.0 splits its API along that line, and so does this SDK: website
+monitoring is `client.v2.monitoring.websites`, and `client.v2.subjects` is the
+**custom** half. Neither serves the other's subjects — passing a website
+subject's slug to a `subjects` call is refused.
+
+Requires Uptimer 1.6.0 or later.
+
+```python
+from uptimer.client import UptimerClient
+from uptimer.models.v2 import SUBJECT_KIND_CUSTOM, CreateSubjectRequest
+
+client = UptimerClient(
+    api_key="your-api-key-here",
+    base_url="http://127.0.0.1:2517/api",
+)
+
+# The workspace's custom subjects. Website checks are not here.
+for subject in client.v2.subjects.all("your-workspace-id"):
+    print(subject.id, subject.subject_kind, subject.signal_count)
+
+# Create an 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 with the observations API below.
+created = client.v2.subjects.create(
+    CreateSubjectRequest(name="Nightly export", workspace_id="your-workspace-id"),
+)
+assert created.subject_kind == SUBJECT_KIND_CUSTOM
+assert created.signal_count == 0
+
+# `id` is the subject's slug — the same name the observation route addresses it
+# by, and it never moves when the subject is renamed.
+fetched = client.v2.subjects.get(created.id, workspace_id="your-workspace-id")
+```
+
+`kind` and `subject_kind` are different fields on purpose. `kind` is `"subject"`
+on every one of these objects — it says what you are holding, the way every v2
+object does. `subject_kind` says how the subject is configured, and against a
+1.6.0 server everything these calls return reads `"custom"`; `is_custom` is the
+typed way to read it. `SUBJECT_KIND_WEBSITE` and `is_website` stay in the model
+for a payload from an older server.
+
+**Website monitoring is not created here.** It needs a URL, an interval and
+locations, so it has its own call — `client.v2.monitoring.websites.create` —
+and asking for `subject_kind="website"` on this route is refused with a message
+saying so.
+
+**Signals and rules are added in the Uptimer UI.** Uptimer 1.6.0 also serves
+them over the API, under `/v2/subjects/{subject}/signals` and
+`/v2/subjects/{subject}/rules`; this SDK does not wrap those routes yet.
+
 ### Reporting your own observations
 
 Uptimer probes websites itself. For anything else — a cron job, a queue worker,
@@ -210,6 +269,140 @@ 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.
 
+### Acknowledging an incident
+
+**New in 1.7.0.** Acknowledging says a **person has seen** an open incident. It
+changes nothing the engine decided — the verdict, the evidence, the close hold
+and the alerting all carry on — and it is recorded once, with who and when.
+
+Each kind of monitoring acknowledges through **its own family**, the same split
+subjects follow: a website incident under its monitor on v1, a custom incident
+under its subject on v2. Neither method falls back to the other, and there is no
+kind-agnostic one: acknowledging is a claim about a specific incident, and an
+SDK that guessed which family it belonged to could claim the wrong one.
+
+**Availability.** These methods are part of the SDK's **1.7.0** release: they are
+not in the published 1.6.0 package, so until 1.7.0 is on PyPI use them from a
+checkout of this repository. They need a matching **Uptimer 1.7.0+** server —
+the routes do not exist before that — and on
+[myuptime.info](https://myuptime.info) they arrive when the hosted service picks
+up the 1.7.0 API.
+
+**Custom monitoring** — list the subject's open incidents, pick one, acknowledge
+it by id:
+
+```python
+from uptimer.client import UptimerClient
+
+client = UptimerClient(
+    api_key="your-api-key-here",
+    base_url="http://127.0.0.1:2517/api",
+)
+
+subject = client.v2.subjects("payments-worker", "your-workspace-id")
+
+# Open incidents of this subject: all of them, newest trouble first. A subject
+# can have one open per rule, so each names the rule that opened it.
+open_incidents = subject.incidents.all()
+for incident in open_incidents:
+    print(incident.id, incident.rule_name, incident.status, incident.acknowledged)
+
+# Nothing open is an ordinary answer, not an error.
+if open_incidents:
+    # Acknowledge the one you mean, by the id the listing gave you. No body and
+    # no actor argument: the person recorded is the owner of the API key, at the
+    # time of the call.
+    target = open_incidents[0]
+    record = subject.incidents(target.id).acknowledge()
+    print(record.acknowledged_by, record.acknowledged_at, record.recorded)
+```
+
+**Website monitoring** — the ids come from the workspace incident list this SDK
+has had since 1.5.0, which already names each incident's monitor:
+
+```python
+# An empty list means nothing is wrong: the loop simply does not run.
+for incident in client.v2.incidents.all("your-workspace-id"):
+    record = client.v1.rules(incident.monitor_id).incidents(incident.id).acknowledge()
+    print(record.incident_id, record.acknowledged_by, record.recorded)
+```
+
+`client.v1` exists for this one route. This is still a v2 client — website
+monitors are read and written through `client.v2.monitoring.websites` — but
+Uptimer serves website acknowledgement under `/v1/rules/...`, because website
+monitoring is v1's resource and custom monitoring is v2's.
+
+What the answer says:
+
+| field | meaning |
+|---|---|
+| `recorded` | whether **this call** wrote it. `False` means it was already acknowledged and nothing changed |
+| `acknowledged_by` / `acknowledged_at` | the record — on a repeat, the **first** person's name and time, not yours |
+| `status` | the incident's condition, unchanged by acknowledging it |
+| `monitor_id` | set for a website incident; `None` for a custom one |
+| `subject_id` / `rule_id` | set for a custom incident; `None` for a website one |
+| `closed_at` | set if the incident had already closed |
+
+**Repeating it is safe.** A second call adds no second history entry and returns
+the original name and time with `recorded=False` — so a retry after a timeout is
+not a second claim.
+
+**Refusals are raised, never worked around.** A `DefaultUptimerApiError` means
+the incident is not this parent's — another monitor's, another subject's,
+another workspace's, or the other kind of monitoring. Nothing is retried through
+the other family.
+
+**Closing cuts both ways, and the two are different.** A **first**
+acknowledgement of an incident that has already closed is refused
+(`Incident is closed`): there is nothing left to be on, and anything open now is
+a different incident. But an incident acknowledged **while it was open** keeps
+that record after it closes, so asking again is not an error — it answers the
+original name and time with `recorded=False` and `closed_at` set. The look did
+happen.
+
+### Maintenance windows
+
+**New in 1.7.0.** A maintenance window holds back one subject's **problem**
+notifications until a time you choose — for a deploy, a migration, anything that
+will make it look broken on purpose. Monitoring, incidents and the timeline are
+untouched, and **recoveries are never held back**: "it is back" is the message
+you most want afterwards.
+
+Same availability as acknowledgement above: the SDK's 1.7.0 release against an
+uptimer 1.7.0+ server, Custom subjects only (a website check is put into
+maintenance from its page in the dashboard).
+
+```python
+maintenance = client.v2.subjects("payments-worker", "your-workspace-id").maintenance
+
+# Nothing scheduled is None — an answer, not an error.
+if maintenance.get() is None:
+    window = maintenance.start("2026-09-13T18:00:00Z")
+    print(window.active, window.ends_at, window.muted)
+
+# The work is taking longer: move the end of the SAME window.
+maintenance.update_end("2026-09-13T20:00:00Z")
+
+# When it is done. Notifications are normal again immediately.
+maintenance.cancel()
+```
+
+`ends_at` is RFC 3339 and carries its own zone, for both `start` and
+`update_end`. The window starts **immediately**.
+
+`update_end` is a real update, not a cancel and a new window: it keeps the
+window's identity and its start, so "since when have we been silencing this?"
+keeps one answer and nothing sees the subject briefly leave maintenance. Moving
+the end into the past raises rather than stopping the window — to stop it now,
+`cancel()`.
+
+`MaintenanceWindow` tells its three states apart by its fields — `active` true
+is running, `cancelled_at` set is ended early, and neither is a window that ran
+out — and `muted` says what waits, in the server's own words.
+
+A past end time, a window already running, a website subject, or a caller who is
+not an editor raise `DefaultUptimerApiError`. Reading takes the viewer role.
+
 ### Incident status
 
 `client.v2.incidents.all()` returns only **open** incidents. `status` carries the

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

@@ -137,6 +137,65 @@ except UptimerError:  # base error, if you need one
     raise
 ```
 
+### Subjects: your custom monitoring
+
+A **subject** is one monitored thing. Every subject is one of two kinds, and the
+kind says how it is configured:
+
+- **website** — Uptimer's own probe watches a URL, and the website check form
+  owns its signal and its rule;
+- **custom** — yours, reporting through the signals you add to it.
+
+Uptimer 1.6.0 splits its API along that line, and so does this SDK: website
+monitoring is `client.v2.monitoring.websites`, and `client.v2.subjects` is the
+**custom** half. Neither serves the other's subjects — passing a website
+subject's slug to a `subjects` call is refused.
+
+Requires Uptimer 1.6.0 or later.
+
+```python
+from uptimer.client import UptimerClient
+from uptimer.models.v2 import SUBJECT_KIND_CUSTOM, CreateSubjectRequest
+
+client = UptimerClient(
+    api_key="your-api-key-here",
+    base_url="http://127.0.0.1:2517/api",
+)
+
+# The workspace's custom subjects. Website checks are not here.
+for subject in client.v2.subjects.all("your-workspace-id"):
+    print(subject.id, subject.subject_kind, subject.signal_count)
+
+# Create an 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 with the observations API below.
+created = client.v2.subjects.create(
+    CreateSubjectRequest(name="Nightly export", workspace_id="your-workspace-id"),
+)
+assert created.subject_kind == SUBJECT_KIND_CUSTOM
+assert created.signal_count == 0
+
+# `id` is the subject's slug — the same name the observation route addresses it
+# by, and it never moves when the subject is renamed.
+fetched = client.v2.subjects.get(created.id, workspace_id="your-workspace-id")
+```
+
+`kind` and `subject_kind` are different fields on purpose. `kind` is `"subject"`
+on every one of these objects — it says what you are holding, the way every v2
+object does. `subject_kind` says how the subject is configured, and against a
+1.6.0 server everything these calls return reads `"custom"`; `is_custom` is the
+typed way to read it. `SUBJECT_KIND_WEBSITE` and `is_website` stay in the model
+for a payload from an older server.
+
+**Website monitoring is not created here.** It needs a URL, an interval and
+locations, so it has its own call — `client.v2.monitoring.websites.create` —
+and asking for `subject_kind="website"` on this route is refused with a message
+saying so.
+
+**Signals and rules are added in the Uptimer UI.** Uptimer 1.6.0 also serves
+them over the API, under `/v2/subjects/{subject}/signals` and
+`/v2/subjects/{subject}/rules`; this SDK does not wrap those routes yet.
+
 ### Reporting your own observations
 
 Uptimer probes websites itself. For anything else — a cron job, a queue worker,
@@ -194,6 +253,140 @@ 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.
 
+### Acknowledging an incident
+
+**New in 1.7.0.** Acknowledging says a **person has seen** an open incident. It
+changes nothing the engine decided — the verdict, the evidence, the close hold
+and the alerting all carry on — and it is recorded once, with who and when.
+
+Each kind of monitoring acknowledges through **its own family**, the same split
+subjects follow: a website incident under its monitor on v1, a custom incident
+under its subject on v2. Neither method falls back to the other, and there is no
+kind-agnostic one: acknowledging is a claim about a specific incident, and an
+SDK that guessed which family it belonged to could claim the wrong one.
+
+**Availability.** These methods are part of the SDK's **1.7.0** release: they are
+not in the published 1.6.0 package, so until 1.7.0 is on PyPI use them from a
+checkout of this repository. They need a matching **Uptimer 1.7.0+** server —
+the routes do not exist before that — and on
+[myuptime.info](https://myuptime.info) they arrive when the hosted service picks
+up the 1.7.0 API.
+
+**Custom monitoring** — list the subject's open incidents, pick one, acknowledge
+it by id:
+
+```python
+from uptimer.client import UptimerClient
+
+client = UptimerClient(
+    api_key="your-api-key-here",
+    base_url="http://127.0.0.1:2517/api",
+)
+
+subject = client.v2.subjects("payments-worker", "your-workspace-id")
+
+# Open incidents of this subject: all of them, newest trouble first. A subject
+# can have one open per rule, so each names the rule that opened it.
+open_incidents = subject.incidents.all()
+for incident in open_incidents:
+    print(incident.id, incident.rule_name, incident.status, incident.acknowledged)
+
+# Nothing open is an ordinary answer, not an error.
+if open_incidents:
+    # Acknowledge the one you mean, by the id the listing gave you. No body and
+    # no actor argument: the person recorded is the owner of the API key, at the
+    # time of the call.
+    target = open_incidents[0]
+    record = subject.incidents(target.id).acknowledge()
+    print(record.acknowledged_by, record.acknowledged_at, record.recorded)
+```
+
+**Website monitoring** — the ids come from the workspace incident list this SDK
+has had since 1.5.0, which already names each incident's monitor:
+
+```python
+# An empty list means nothing is wrong: the loop simply does not run.
+for incident in client.v2.incidents.all("your-workspace-id"):
+    record = client.v1.rules(incident.monitor_id).incidents(incident.id).acknowledge()
+    print(record.incident_id, record.acknowledged_by, record.recorded)
+```
+
+`client.v1` exists for this one route. This is still a v2 client — website
+monitors are read and written through `client.v2.monitoring.websites` — but
+Uptimer serves website acknowledgement under `/v1/rules/...`, because website
+monitoring is v1's resource and custom monitoring is v2's.
+
+What the answer says:
+
+| field | meaning |
+|---|---|
+| `recorded` | whether **this call** wrote it. `False` means it was already acknowledged and nothing changed |
+| `acknowledged_by` / `acknowledged_at` | the record — on a repeat, the **first** person's name and time, not yours |
+| `status` | the incident's condition, unchanged by acknowledging it |
+| `monitor_id` | set for a website incident; `None` for a custom one |
+| `subject_id` / `rule_id` | set for a custom incident; `None` for a website one |
+| `closed_at` | set if the incident had already closed |
+
+**Repeating it is safe.** A second call adds no second history entry and returns
+the original name and time with `recorded=False` — so a retry after a timeout is
+not a second claim.
+
+**Refusals are raised, never worked around.** A `DefaultUptimerApiError` means
+the incident is not this parent's — another monitor's, another subject's,
+another workspace's, or the other kind of monitoring. Nothing is retried through
+the other family.
+
+**Closing cuts both ways, and the two are different.** A **first**
+acknowledgement of an incident that has already closed is refused
+(`Incident is closed`): there is nothing left to be on, and anything open now is
+a different incident. But an incident acknowledged **while it was open** keeps
+that record after it closes, so asking again is not an error — it answers the
+original name and time with `recorded=False` and `closed_at` set. The look did
+happen.
+
+### Maintenance windows
+
+**New in 1.7.0.** A maintenance window holds back one subject's **problem**
+notifications until a time you choose — for a deploy, a migration, anything that
+will make it look broken on purpose. Monitoring, incidents and the timeline are
+untouched, and **recoveries are never held back**: "it is back" is the message
+you most want afterwards.
+
+Same availability as acknowledgement above: the SDK's 1.7.0 release against an
+uptimer 1.7.0+ server, Custom subjects only (a website check is put into
+maintenance from its page in the dashboard).
+
+```python
+maintenance = client.v2.subjects("payments-worker", "your-workspace-id").maintenance
+
+# Nothing scheduled is None — an answer, not an error.
+if maintenance.get() is None:
+    window = maintenance.start("2026-09-13T18:00:00Z")
+    print(window.active, window.ends_at, window.muted)
+
+# The work is taking longer: move the end of the SAME window.
+maintenance.update_end("2026-09-13T20:00:00Z")
+
+# When it is done. Notifications are normal again immediately.
+maintenance.cancel()
+```
+
+`ends_at` is RFC 3339 and carries its own zone, for both `start` and
+`update_end`. The window starts **immediately**.
+
+`update_end` is a real update, not a cancel and a new window: it keeps the
+window's identity and its start, so "since when have we been silencing this?"
+keeps one answer and nothing sees the subject briefly leave maintenance. Moving
+the end into the past raises rather than stopping the window — to stop it now,
+`cancel()`.
+
+`MaintenanceWindow` tells its three states apart by its fields — `active` true
+is running, `cancelled_at` set is ended early, and neither is a window that ran
+out — and `muted` says what waits, in the server's own words.
+
+A past end time, a window already running, a website subject, or a caller who is
+not an editor raise `DefaultUptimerApiError`. Reading takes the viewer role.
+
 ### Incident status
 
 `client.v2.incidents.all()` returns only **open** incidents. `status` carries the

{uptimer_python_sdk-1.6.0rc0 → uptimer_python_sdk-1.7.0}/Taskfile.yml

@@ -1,5 +1,8 @@
 # Dev + git release tasks for the uptimer Python SDK. All tooling via `uv` (uv.lock).
 # PyPI publish lives in the private product repo: /work → task sdk:publish*
+#
+# HARD RULE: never publish an SDK prerelease (rc/a/b/dev) to TestPyPI or PyPI.
+# OSS/SaaS may cut RCs; this package ships final X.Y.Z only. Verify locally.
 version: '3'
 
 tasks:
@@ -27,9 +30,17 @@ tasks:
       - task: test
 
   release:
-    desc: 'Cut a release: cq, then `cz bump` (version + CHANGELOG + tag) + push. Commit first. Prefer manual tag when version is already set.'
+    desc: 'Cut a FINAL release only: cq, then `cz bump` (no --prerelease) + push. Never cut an SDK RC for PyPI. Commit first.'
     cmds:
       - task: cq
       - cz bump --yes
+      - |
+        ver=$(cz version --project)
+        case "$ver" in
+          *rc*|*RC*|*alpha*|*beta*|*dev*|*pre*)
+            echo "REFUSED: cz produced prerelease $ver — do not push or publish. SDK ships final X.Y.Z only." >&2
+            exit 1
+            ;;
+        esac
       - git push --follow-tags
-      - 'echo ">> released v$(cz version --project) — publish from /work: task sdk:publish:test, then task sdk:publish"'
+      - 'echo ">> released v$(cz version --project) — publish from /work only if FINAL: task sdk:publish:test, then task sdk:publish"'

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

@@ -1,10 +1,14 @@
 [build-system]
-requires = ["hatchling"]
+# Pinned below 1.28: from that version hatchling writes Metadata-Version 2.5,
+# which twine 6.x (packaging 25) refuses to validate, so `twine check` fails on
+# an artifact that is otherwise fine. 2.4 is what the release path can verify.
+# Lift the pin once twine and packaging accept 2.5.
+requires = ["hatchling<1.28"]
 build-backend = "hatchling.build"
 
 [project]
 name = "uptimer-python-sdk"
-version = "1.6.0-rc.0"
+version = "1.7.0"
 description = "A Python SDK for hosted and self-hosted Uptimer"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,6 +30,10 @@ include = ["LICENSE", "NOTICE", "README.md"]
 [tool.commitizen]
 name = "cz_conventional_commits"
 tag_format = "$version"
+# Create ANNOTATED tags: `git push --follow-tags` in `task release` SKIPS
+# lightweight ones, so the 1.7.0 bump commit went up without its tag and the
+# tag had to be pushed by hand afterwards.
+annotated_tag = true
 version_scheme = "semver2"
 version_provider = "uv"
 update_changelog_on_bump = true

{uptimer_python_sdk-1.6.0rc0 → uptimer_python_sdk-1.7.0}/src/uptimer/__init__.py

@@ -9,4 +9,4 @@ 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"
+__version__ = "1.6.0"

{uptimer_python_sdk-1.6.0rc0 → uptimer_python_sdk-1.7.0}/src/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
 
@@ -14,14 +15,20 @@ class UptimerClient:
     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.
+    `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):
@@ -30,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: