Openstatus Python SDK — Implementation Plan#

Build an official Python SDK for the Openstatus API, mirroring the ergonomics of @openstatusHQ/sdk-node and the architecture of openstatusHQ/sdk-php.

Approach: pull the pre-generated Python message classes from Buf's CDN archive, then hand-write a thin HTTP+JSON transport on top using httpx. No Buf CLI, no protobuf binary wire format, no codegen toolchain dependency for contributors — just JSON over HTTP, type-safe via the generated message classes and .pyi stubs.

1. What the API actually looks like#

Same as documented in sdk-php/docs/decisions.md:

• Server: https://api.openstatus.dev/
• Auth: header x-openstatus-key: <token>
• Path shape: POST /rpc/{package.Service}/{Method} with application/json body (Connect RPC's JSON mode).
• Error envelope (Connect-style):

  { "code": "not_found", "message": "...", "details": [ ... ] }
  

  code is one of: canceled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated.
• Services & methods (~52 RPCs total):
  • HealthService: Check
  • MonitorService: CreateHTTPMonitor, CreateTCPMonitor, CreateDNSMonitor, UpdateHTTPMonitor, UpdateTCPMonitor, UpdateDNSMonitor, GetMonitor, ListMonitors, TriggerMonitor, DeleteMonitor, GetMonitorStatus, GetMonitorSummary, ListMonitorHTTPResponseLogs, GetMonitorHTTPResponseLog
  • StatusReportService: CreateStatusReport, GetStatusReport, ListStatusReports, UpdateStatusReport, DeleteStatusReport, AddStatusReportUpdate
  • StatusPageService: CreateStatusPage, GetStatusPage, ListStatusPages, UpdateStatusPage, DeleteStatusPage, GetStatusPageContent, GetOverallStatus, AddMonitorComponent, AddStaticComponent, RemoveComponent, UpdateComponent, CreateComponentGroup, UpdateComponentGroup, DeleteComponentGroup, SubscribeToPage, UnsubscribeFromPage, CreatePageSubscription, ListSubscribers
  • MaintenanceService: CreateMaintenance, GetMaintenance, ListMaintenances, UpdateMaintenance, DeleteMaintenance
  • NotificationService: CreateNotification, GetNotification, ListNotifications, UpdateNotification, DeleteNotification, SendTestNotification, CheckNotificationLimit

HealthService.Check also accepts GET with a message query param; we only support POST to keep the transport uniform.

2. Foundational decisions#

Why sync and async from day 1 (unlike PHP)#

• httpx.Client and httpx.AsyncClient share virtually the same method signatures, so a single transport core can be specialised twice with a thin wrapper. The duplication is ~50 LOC, not a parallel SDK.
• Async is table-stakes for modern Python (FastAPI, ASGI, asyncio-native apps). Shipping sync-only would push users to wrap our calls in thread pools.
• The generated protobuf messages and error mapper are transport-agnostic — they don't double in size.

3. Codegen: pre-built Buf archive (no Buf CLI)#

Buf hosts pre-generated zips of the protocolbuffers/python and protocolbuffers/pyi outputs for each pinned schema version. Both archives exist on buf.build/gen/archive/... (verified). We pull both so users get type stubs:

curl -fsSL -O https://buf.build/gen/archive/openstatus/api/protocolbuffers/python/v35.0-7d7b7047611f.1.zip
curl -fsSL -O https://buf.build/gen/archive/openstatus/api/protocolbuffers/pyi/v35.0-7d7b7047611f.1.zip

What the python archive contains:

• *_pb2.py per proto file — message classes built on google.protobuf.message.Message.
• Python package layout matches the proto package path (e.g. openstatus/monitor/v1/monitor_pb2.py).
• Enums are emitted as integer constants on the descriptor; getters return int.
• No service stubs (protocolbuffers/python only emits messages) — we hand-write per-RPC dispatch.
• No pyproject.toml, no __init__.py files — we generate empty __init__.py shims during regen so the package tree imports cleanly.

What the pyi archive contains:

• *_pb2.pyi next to each *_pb2.py — full type stubs so MonitorService.list_monitors arguments and return types are typed in IDEs and mypy/pyright.

Both archives reference transitive metadata for buf.validate and gnostic.openapi.v3 annotations. Like the PHP build, these are descriptor-only annotations and don't affect the JSON wire format; the python protobuf runtime tolerates missing optional imports for these.

Regen script#

scripts/regen.sh — the archive version is pinned in the script. Bumping it is an explicit edit + PR (no CLI override), so every schema change shows up as a reviewable diff:

#!/usr/bin/env bash
set -euo pipefail

# Pinned Buf-generated Python archive for buf.build/openstatus/api.
# To upgrade: change this line, run `uv run regen`, commit the result.
readonly BUF_PY_VERSION="v35.0-7d7b7047611f.1"

BASE="https://buf.build/gen/archive/openstatus/api/protocolbuffers"
DEST="src/openstatus/_gen"

rm -rf "$DEST"
mkdir -p "$DEST"

curl -fsSL "$BASE/python/${BUF_PY_VERSION}.zip"  -o /tmp/openstatus-py.zip
curl -fsSL "$BASE/pyi/${BUF_PY_VERSION}.zip"     -o /tmp/openstatus-pyi.zip

unzip -q /tmp/openstatus-py.zip  -d /tmp/openstatus-py
unzip -q /tmp/openstatus-pyi.zip -d /tmp/openstatus-pyi

# protocolbuffers/python archive layout: api_python/openstatus/...
cp -R /tmp/openstatus-py/api_python/openstatus  "$DEST/openstatus"
# protocolbuffers/pyi archive layout: api_pyi/openstatus/... — merge .pyi next to .py
cp -R /tmp/openstatus-pyi/api_pyi/openstatus/.  "$DEST/openstatus/"

# Generated trees ship no __init__.py — create empty shims so imports resolve.
find "$DEST/openstatus" -type d -exec touch {}/__init__.py \;

rm -rf /tmp/openstatus-py* /tmp/openstatus-pyi*

echo "${BUF_PY_VERSION}" > "$DEST/VERSION"

src/openstatus/_gen/VERSION is committed alongside the generated code so the current pin is always visible. src/openstatus/_gen/ itself is also committed so end-users install from PyPI without needing to regen.

Upgrade workflow#

1. Find the latest archive version on buf.build/openstatus/api/sdks/main:protocolbuffers/python.
2. Edit BUF_PY_VERSION in scripts/regen.sh.
3. Run uv run regen (or bash scripts/regen.sh).
4. Commit scripts/regen.sh + the resulting src/openstatus/_gen/ diff in the same PR.
5. The weekly regen.yml workflow (see §13) does steps 2–4 automatically when a new pinned version is published.

4. Repository layout#

sdk-python/
├── docs/decisions.md                    # this file, post-v0.1.0
├── pyproject.toml
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE                              # MIT
├── .editorconfig
├── .gitignore
├── ruff.toml
├── pyrightconfig.json
├── scripts/
│   └── regen.sh
├── examples/
│   ├── basic.py                         # port of example.ts (health, list, logs, log detail)
│   ├── basic_async.py                   # async variant of basic.py
│   └── create_monitor.py                # full HTTPMonitor with assertions/regions
├── src/
│   └── openstatus/
│       ├── __init__.py                  # re-exports: OpenstatusClient, AsyncOpenstatusClient, ClientOptions, exceptions, Region, etc.
│       ├── py.typed                     # PEP 561 marker
│       ├── _client_options.py           # frozen dataclass, kw-only
│       ├── client.py                    # OpenstatusClient + AsyncOpenstatusClient roots
│       ├── _transport.py                # _JsonTransport, _AsyncJsonTransport
│       ├── _errors.py                   # _ConnectErrorMapper
│       ├── exceptions.py                # OpenstatusError + typed subclasses
│       ├── services/
│       │   ├── __init__.py
│       │   ├── health.py                # HealthServiceClient + AsyncHealthServiceClient
│       │   ├── monitor.py
│       │   ├── status_report.py
│       │   ├── status_page.py
│       │   ├── maintenance.py
│       │   └── notification.py
│       └── _gen/                        # buf-generated, committed
│           ├── openstatus/              # *_pb2.py + *_pb2.pyi tree
│           └── VERSION
├── tests/
│   ├── unit/                            # httpx MockTransport-driven, runs in CI
│   └── integration/                     # gated on OPENSTATUS_API_KEY, NOT run in CI
└── .github/workflows/
    ├── ci.yml                           # pytest (unit) + pyright + ruff, py3.10/3.11/3.12/3.13
    └── regen.yml                        # weekly: bump pin + open PR

5. pyproject.toml#

[project]
name = "openstatus"
version = "0.1.0"
description = "Official Python SDK for Openstatus"
readme = "README.md"
license = { text = "MIT" }
authors = [{ name = "Openstatus" }]
requires-python = ">=3.10"
keywords = ["openstatus", "monitoring", "status-page", "uptime", "sdk"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Typing :: Typed",
]
dependencies = [
    "httpx>=0.27",
    "protobuf>=5.28,<7",
]

[project.urls]
Homepage = "https://www.openstatus.dev"
Repository = "https://github.com/openstatusHQ/sdk-python"
Issues = "https://github.com/openstatusHQ/sdk-python/issues"

[dependency-groups]
dev = [
    "pytest>=8",
    "pytest-asyncio>=0.24",
    "pyright>=1.1.380",
    "ruff>=0.6",
    "respx>=0.21",   # httpx mocking helper, optional but ergonomic
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/openstatus"]

[tool.hatch.build.targets.sdist]
include = ["src/openstatus", "README.md", "LICENSE", "CHANGELOG.md"]

[tool.pytest.ini_options]
testpaths = ["tests/unit"]
asyncio_mode = "auto"

[tool.ruff]
line-length = 100
target-version = "py310"
extend-exclude = ["src/openstatus/_gen"]

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "RUF"]

[tool.pyright]
include = ["src/openstatus", "tests"]
exclude = ["src/openstatus/_gen"]
pythonVersion = "3.10"
typeCheckingMode = "strict"

httpx is a hard dependency, not optional — Python's urllib is too low-level and requests is sync-only. The transport core depends only on httpx.Client / httpx.AsyncClient, which users in FastAPI/Django apps can construct with their own configuration (timeouts, proxies, certs) and pass in.

6. ClientOptions (frozen dataclass, kw-only)#

# src/openstatus/_client_options.py
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
import httpx

@dataclass(frozen=True, kw_only=True, slots=True)
class ClientOptions:
    api_key: str | None = None            # falls back to OPENSTATUS_API_KEY
    base_url: str | None = None           # falls back to OPENSTATUS_API_URL, default https://api.openstatus.dev
    timeout: float = 30.0                 # seconds, applied to httpx.Client if user does not supply one
    http_client: httpx.Client | None = None       # user-supplied for OpenstatusClient
    async_http_client: httpx.AsyncClient | None = None  # user-supplied for AsyncOpenstatusClient
    default_headers: dict[str, str] | None = None  # extra headers merged on every call

Env fallbacks match Node and PHP:

• OPENSTATUS_API_KEY — API key
• OPENSTATUS_API_URL — base URL (default https://api.openstatus.dev)

7. Root client & namespace sugar#

Mirrors the Node/PHP shape: client.monitor.v1.MonitorService.list_monitors(...). Method names are snake_case (PEP 8) while the namespace path matches the proto package and the ServiceName casing is preserved so the access path reads the same as in Node:

from openstatus import OpenstatusClient, ClientOptions
from openstatus._gen.openstatus.monitor.v1 import monitor_pb2 as m

client = OpenstatusClient(ClientOptions(api_key="..."))

res = client.monitor.v1.MonitorService.list_monitors(m.ListMonitorsRequest())
for monitor in res.http_monitors:
    print(monitor.name, monitor.url)

And the async equivalent:

from openstatus import AsyncOpenstatusClient

async def main():
    async with AsyncOpenstatusClient(ClientOptions(api_key="...")) as client:
        res = await client.monitor.v1.MonitorService.list_monitors(m.ListMonitorsRequest())

OpenstatusClient.__init__ builds the _JsonTransport once, then constructs nested _Monitor / _Health / _StatusReport / _StatusPage / _Maintenance / _Notification holders. Each holder has a .v1 attribute pointing to a holder that exposes the typed service client. Total sugar code: ~12 tiny dataclasses (~3 lines each).

Both clients support context-manager usage and a .close() method that closes the underlying httpx client (only when the SDK created it).

8. JSON transport (httpx, ~80 LOC sync + ~80 LOC async)#

# src/openstatus/_transport.py
from __future__ import annotations
from typing import TypeVar
import httpx
from google.protobuf.message import Message
from google.protobuf.json_format import MessageToJson, Parse
from ._errors import _ConnectErrorMapper

T = TypeVar("T", bound=Message)

class _JsonTransport:
    def __init__(
        self,
        client: httpx.Client,
        base_url: str,
        default_headers: dict[str, str],
    ) -> None:
        self._client = client
        self._base_url = base_url.rstrip("/")
        self._default_headers = default_headers

    def call(
        self,
        service_fqn: str,
        method: str,
        request: Message,
        response_cls: type[T],
        extra_headers: dict[str, str] | None = None,
    ) -> T:
        url = f"{self._base_url}/rpc/{service_fqn}/{method}"
        headers = {**self._default_headers, **(extra_headers or {})}
        body = MessageToJson(
            request,
            preserving_proto_field_name=False,  # camelCase, matching Connect JSON conventions
            use_integers_for_enums=False,
        )
        resp = self._client.post(url, headers=headers, content=body)
        if resp.status_code >= 400:
            _ConnectErrorMapper.rethrow(resp)
        return Parse(resp.text, response_cls(), ignore_unknown_fields=True)


class _AsyncJsonTransport:
    # identical surface, uses httpx.AsyncClient and `await self._client.post(...)`
    ...

Default headers set by the root client:

• Content-Type: application/json
• Accept: application/json
• User-Agent: openstatus-python/<sdk-version> python/<python-version>
• x-openstatus-key: <api-key> (if api_key set)

The async transport is the same shape with async def call and await self._client.post(...). Both share _ConnectErrorMapper.

9. Service client wrappers (hand-written, one module per service, sync + async)#

# src/openstatus/services/monitor.py
from __future__ import annotations
from openstatus._gen.openstatus.monitor.v1 import monitor_pb2 as m
from openstatus._transport import _JsonTransport, _AsyncJsonTransport

_FQN = "openstatus.monitor.v1.MonitorService"

class MonitorServiceClient:
    def __init__(self, transport: _JsonTransport) -> None:
        self._t = transport

    def list_monitors(
        self,
        request: m.ListMonitorsRequest,
        *,
        headers: dict[str, str] | None = None,
    ) -> m.ListMonitorsResponse:
        return self._t.call(_FQN, "ListMonitors", request, m.ListMonitorsResponse, headers)

    def create_http_monitor(
        self,
        request: m.CreateHTTPMonitorRequest,
        *,
        headers: dict[str, str] | None = None,
    ) -> m.CreateHTTPMonitorResponse:
        return self._t.call(_FQN, "CreateHTTPMonitor", request, m.CreateHTTPMonitorResponse, headers)

    # ... one method per RPC in this service


class AsyncMonitorServiceClient:
    def __init__(self, transport: _AsyncJsonTransport) -> None:
        self._t = transport

    async def list_monitors(
        self,
        request: m.ListMonitorsRequest,
        *,
        headers: dict[str, str] | None = None,
    ) -> m.ListMonitorsResponse:
        return await self._t.call(_FQN, "ListMonitors", request, m.ListMonitorsResponse, headers)

    # ... mirrored async versions

~52 sync + 52 async methods across 6 modules. Each pair is mechanical and ~5 LOC. Method names are snake_case (PEP 8). The duplication is intentional and worth it — it keeps the sync and async surfaces independently inspectable and avoids if asyncio.iscoroutinefunction introspection at call time.

Could codegen these: if maintenance gets painful, a small script can emit services/*.py from a JSON spec of the RPC list. Out of scope for v0.1; revisit at v0.3 if churn justifies it.

10. Error mapping#

_ConnectErrorMapper decodes a httpx.Response (4xx/5xx) and raises a typed subclass.

When the response body is not a valid connect.error envelope (e.g. 502 HTML from a proxy), raise ServiceUnavailableError with the raw body preserved.

OpenstatusError(Exception) carries:

• connect_code: str — the Connect code (e.g. not_found), or "unknown" when the envelope is missing.
• http_status: int — the raw HTTP status code.
• details: list[Any] — the raw details array from the envelope (decoded JSON, no further parsing). Empty list when missing.
• raw_body: str — the original response body, for debugging.
• args[0] / str(exc) — the message from the envelope, or the HTTP reason phrase as fallback.

All subclasses inherit from OpenstatusError, so users can except OpenstatusError as a catch-all.

11. Testing#

• Unit tests (httpx.MockTransport or respx, runs on every PR):
  • Transport sends the correct URL (/rpc/openstatus.monitor.v1.MonitorService/ListMonitors).
  • Headers include x-openstatus-key, User-Agent, Content-Type, Accept when configured, plus per-call overrides.
  • JSON body round-trips: serializing a known message and decoding it back produces equivalent state.
  • 4xx with connect.error body → correct typed exception with connect_code, http_status, details populated.
  • Non-JSON 5xx → ServiceUnavailableError with raw_body preserved.
  • Both sync and async paths covered (parametrised fixture switches client class).
• Integration tests (gated on OPENSTATUS_API_KEY, run locally by maintainers before tagging a release; not wired into CI):
  • HealthService.Check — proves the wire format works against the real API.
  • MonitorService.ListMonitors — proves auth + real JSON decode.
• CI matrix: Python 3.10, 3.11, 3.12, 3.13 on ubuntu-latest. Steps: ruff check + ruff format --check + pyright (strict on src/openstatus/, excluding _gen/) + pytest tests/unit.

12. README & examples#

Full port of the Node SDK README — same TOC, per-service sections, one example per RPC, error-handling section, regions/enums reference. Side-by-side sync and async examples for the top-level snippets so readers can pick. Users compare SDKs by README completeness; parity matters.

examples/basic.py mirrors example.ts: health check, list monitors, list HTTP response logs, fetch one log detail.

examples/basic_async.py is the async equivalent, importing AsyncOpenstatusClient and wrapped in asyncio.run(main()).

examples/create_monitor.py builds a full HTTPMonitor with Periodicity, Region, HTTPMethod, and a StatusCodeAssertion — the hardest first-time task, worth a worked example. Shows how to import enums and message types from openstatus._gen.openstatus.monitor.v1.

README also documents:

• How to use a custom httpx.Client (timeouts, proxies, transport retries via httpx.HTTPTransport(retries=N)).
• The int64 representation note: python protobuf returns int for 64-bit fields on all platforms (no PHP-style int|string quirk — simpler than PHP).
• Recipes for FastAPI (Depends(get_client) pattern) and Django (settings-based singleton) — ~5 lines each.
• Migration notes from the Node SDK structure to Python idioms (camelCase → snake_case for method names; message field access is msg.foo_bar not msg.fooBar).

13. Release & ops#

• Tag v0.1.0 → GitHub Actions publishes to PyPI via Trusted Publishers (no long-lived token). Package name: openstatus. Wheel ships the generated _gen/ tree.
• .github/workflows/regen.yml: weekly cron that checks Buf for a newer archive version. If one exists, edits BUF_PY_VERSION in scripts/regen.sh, runs the script, and opens a PR with both changes. The pin never moves silently — every bump is a reviewable commit.
• CHANGELOG.md in Keep a Changelog format. Update on every release.
• CONTRIBUTING.md documents: how to bump BUF_PY_VERSION, how to run tests (uv run pytest, uv run pyright, uv run ruff check), code style rules (ruff defaults + from __future__ import annotations at top of every hand-written file), PR conventions.
• This document was the original plan.md; it moves to docs/decisions.md post-v0.1.0 so the rationale (why JSON-over-HTTP, why pinned archive, why mirrored Node shape, why sync+async from day 1) survives as a reference.

14. Milestones#

1. Bootstrap — pyproject.toml, scripts/regen.sh, .editorconfig, .gitignore, ruff.toml, pyrightconfig.json, LICENSE, empty CHANGELOG.md + CONTRIBUTING.md, src/openstatus/__init__.py + py.typed, run regen, commit src/openstatus/_gen/.
2. Transport + error mapping — _JsonTransport, _AsyncJsonTransport, ClientOptions, _ConnectErrorMapper, typed exception hierarchy, unit tests with httpx.MockTransport (parametrised sync/async).
3. HealthService end-to-end — smallest service, sync + async wrappers, manual integration check against the real API to validate the wire format.
4. Remaining service wrappers — Monitor → StatusReport → StatusPage → Maintenance → Notification (one PR per service, each with sync + async + unit tests).
5. Root client + namespace sugar — OpenstatusClient and AsyncOpenstatusClient with nested .v1.ServiceName accessors, env-var fallbacks, context-manager support.
6. README + examples — full port from Node SDK, examples/basic.py + examples/basic_async.py + examples/create_monitor.py.
7. CI — ci.yml (pytest unit + pyright + ruff, py3.10–3.13), regen.yml (weekly cron).
8. v0.1.0 release prep — Trusted Publisher setup on PyPI, tag, publish, move plan.md → docs/decisions.md.

15. Trade-offs vs alternatives#

The archive approach is the leanest: no toolchain dependency for contributors (just curl + unzip), type-safe message classes that match the proto source of truth byte-for-byte (with .pyi stubs for IDE/pyright), and only ~160 lines of transport (sync + async) + ~52 × 2 one-liners of service dispatch to maintain ourselves.

betterproto was considered for nicer dataclass-style messages, but it introduces a codegen toolchain dependency and its JSON output is not guaranteed to match Connect's JSON conventions — risk not worth it for v0.1.

16. Open questions to confirm before kickoff#

• Async-from-day-1: confirmed worth it (§2). If we want to ship faster, sync-only v0.1 is a valid fallback — the async transport can land in v0.2 without breaking changes since the class names are distinct.
• google-protobuf runtime version pin: >=5.28,<7 covers the current major + the announced 6.x line. Tighten once we observe wheel compatibility on the CI matrix.
• pyright vs mypy: pyright proposed for stricter inference and better IDE integration. mypy is fine as an alternative if maintainer preference differs.

17. Detailed task breakdown#

Phases map to the milestones in §14. Each task is independently reviewable; ✅ when done. Tasks within a phase are roughly ordered; phases run sequentially.

Phase 0 — Repository scaffolding#

• Initialise git repo and push main to github.com/openstatusHQ/sdk-python
• Add LICENSE (MIT, matching sdk-php and sdk-node)
• Add .gitignore (Python: __pycache__, .venv, dist, build, *.egg-info, .pytest_cache, .ruff_cache)
• Add .editorconfig (4-space indent for .py, LF line endings, trim trailing whitespace)
• Add README.md skeleton (title, one-line description, "Status: pre-alpha" badge, placeholder TOC)
• Add empty CHANGELOG.md with ## [Unreleased] header (Keep a Changelog format)
• Add CONTRIBUTING.md skeleton (sections to fill in as decisions land: dev setup, regen, tests, PR conventions)

Phase 1 — Tooling & project metadata#

• Write pyproject.toml per §5 (project metadata, deps, dependency-groups, hatchling build, tool configs)
• Add ruff.toml (or inline under [tool.ruff] in pyproject.toml)
• Add pyrightconfig.json (strict on src/openstatus/, exclude _gen/)
• Create src/openstatus/__init__.py (empty, to be populated in Phase 5)
• Create src/openstatus/py.typed (empty marker file, PEP 561)
• Run uv sync to install dev deps, commit uv.lock
• Verify uv run ruff check . and uv run pyright both pass on empty package

Phase 2 — Codegen pipeline#

• Write scripts/regen.sh per §3 (pinned BUF_PY_VERSION, downloads both python and pyi archives, merges into src/openstatus/_gen/openstatus/, creates empty __init__.py shims, writes VERSION file)
• Make scripts/regen.sh executable (chmod +x)
• Run bash scripts/regen.sh and verify it produces src/openstatus/_gen/openstatus/{monitor,health,status_report,status_page,maintenance,notification}/v1/*_pb2.py and matching .pyi files
• Verify from openstatus._gen.openstatus.monitor.v1 import monitor_pb2 works from a python REPL
• Verify MessageToJson(monitor_pb2.ListMonitorsRequest()) and Parse('{}', monitor_pb2.ListMonitorsResponse()) round-trip without errors
• Commit src/openstatus/_gen/ tree and VERSION file
• Add [tool.hatch.build.targets.wheel].force-include rule if needed so _gen/ ships in the wheel; verify with uv build + unzip -l dist/*.whl

Phase 3 — Exception hierarchy & error mapper#

• Write src/openstatus/exceptions.py:
  • OpenstatusError(Exception) base with connect_code, http_status, details, raw_body attributes
  • AuthenticationError(OpenstatusError)
  • NotFoundError(OpenstatusError)
  • InvalidArgumentError(OpenstatusError)
  • PermissionDeniedError(OpenstatusError)
  • RateLimitError(OpenstatusError)
  • ServiceUnavailableError(OpenstatusError)
• Write src/openstatus/_errors.py with _ConnectErrorMapper.rethrow(httpx.Response):
  • Decode connect.error envelope (code, message, details)
  • Map code → exception class per §10 table
  • Fallback to ServiceUnavailableError when body is not valid JSON envelope
  • Preserve raw_body, http_status, connect_code on every raised exception
• Add unit tests tests/unit/test_errors.py:
  • Each Connect code maps to its expected exception class
  • Missing envelope → ServiceUnavailableError with connect_code="unknown"
  • HTML 502 body → ServiceUnavailableError with raw_body preserved
  • OpenstatusError.__str__ returns envelope message or HTTP reason phrase

Phase 4 — Transport layer#

• Write src/openstatus/_client_options.py (frozen kw-only slotted dataclass per §6)
• Write src/openstatus/_transport.py:
  • _JsonTransport.__init__(client, base_url, default_headers)
  • _JsonTransport.call(service_fqn, method, request, response_cls, extra_headers) per §8
  • _AsyncJsonTransport with async def call(...) mirroring sync surface
• Add unit tests tests/unit/test_transport.py using httpx.MockTransport:
  • URL is /rpc/openstatus.monitor.v1.MonitorService/ListMonitors
  • Default headers (Content-Type, Accept, User-Agent, x-openstatus-key) sent on every request
  • Per-call extra_headers override defaults
  • Request body is valid JSON, deserialisable into the original message
  • Response body is parsed into the expected message type
  • 4xx response triggers _ConnectErrorMapper.rethrow
• Parametrise test fixtures so the same cases run against sync and async transports

Phase 5 — Root client & namespace sugar#

• Resolve _resolve_options(opts: ClientOptions) -> _ResolvedOptions helper:
  • Read OPENSTATUS_API_KEY env var as api_key fallback
  • Read OPENSTATUS_API_URL env var as base_url fallback, default https://api.openstatus.dev
  • Build default header dict including User-Agent from importlib.metadata.version("openstatus") and platform.python_version()
• Write src/openstatus/client.py:
  • OpenstatusClient.__init__(options: ClientOptions | None = None) — constructs httpx.Client if not user-supplied, builds _JsonTransport, instantiates namespace holders
  • __enter__ / __exit__ for context-manager use
  • .close() — closes owned httpx.Client (no-op if user supplied one)
  • Nested holder classes for monitor, health, status_report, status_page, maintenance, notification; each has a .v1 attribute holding the service client(s)
  • AsyncOpenstatusClient with async __aenter__ / __aexit__ / aclose() mirror
• Populate src/openstatus/__init__.py:
  • Re-export OpenstatusClient, AsyncOpenstatusClient, ClientOptions
  • Re-export all exception classes
  • Set __all__ and __version__
• Add unit tests tests/unit/test_client.py:
  • Env-var fallbacks (OPENSTATUS_API_KEY, OPENSTATUS_API_URL)
  • User-supplied httpx.Client is reused, not replaced
  • Context-manager closes only SDK-owned clients
  • client.monitor.v1.MonitorService resolves to the expected service client type

Phase 6 — Service wrappers (one per service)#

For each service: hand-write sync + async client class with one method per RPC, then add unit tests verifying each method calls the transport with correct (service_fqn, method, request_type, response_type). Single PR per service.

• src/openstatus/services/health.py — HealthServiceClient.check + async variant (1 RPC)
• src/openstatus/services/monitor.py — 14 RPCs × 2 (sync + async):
  • create_http_monitor, create_tcp_monitor, create_dns_monitor
  • update_http_monitor, update_tcp_monitor, update_dns_monitor
  • get_monitor, list_monitors, trigger_monitor, delete_monitor
  • get_monitor_status, get_monitor_summary
  • list_monitor_http_response_logs, get_monitor_http_response_log
• src/openstatus/services/status_report.py — 6 RPCs × 2
• src/openstatus/services/status_page.py — 18 RPCs × 2
• src/openstatus/services/maintenance.py — 5 RPCs × 2
• src/openstatus/services/notification.py — 7 RPCs × 2
• src/openstatus/services/__init__.py re-exports all service client classes
• Unit tests tests/unit/services/test_<service>.py for each service (one parametrised test covering all RPCs is acceptable)

Phase 7 — Integration tests (local-only)#

• tests/integration/conftest.py with pytest.skip if OPENSTATUS_API_KEY env var absent
• tests/integration/test_health.py — real HealthService.check round-trip
• tests/integration/test_monitor_list.py — real MonitorService.list_monitors against authenticated account
• Document in CONTRIBUTING.md how to run: OPENSTATUS_API_KEY=... uv run pytest tests/integration

Phase 8 — Examples#

• examples/basic.py — sync port of sdk-node/example.ts (health, list, logs, log detail)
• examples/basic_async.py — async equivalent of basic.py
• examples/create_monitor.py — full HTTPMonitor with Periodicity, Region, HTTPMethod, StatusCodeAssertion
• Each example: standalone, runnable with uv run python examples/<name>.py, no extra deps

Phase 9 — README & docs#

• Port full TOC from sdk-node README
• "Installation" — pip install openstatus / uv add openstatus
• "Quickstart" — sync + async snippets side by side
• "Authentication" — env var + explicit api_key arg
• "Custom HTTP client" — supplying httpx.Client with custom timeouts/transport
• Per-service sections (Health, Monitor, StatusReport, StatusPage, Maintenance, Notification) with one example per RPC
• "Error handling" — exception hierarchy, catching OpenstatusError, inspecting connect_code / http_status / details
• "Regions / Enums" reference — how to import from _gen and reference enum constants
• "FastAPI integration" recipe (~5 lines, Depends(get_client))
• "Django integration" recipe (~5 lines, settings-backed singleton)
• "Migration from Node SDK" note — camelCase → snake_case mapping
• Move plan.md → docs/decisions.md after v0.1.0 tag (not before — keep planning artifact at root during build-out)

Phase 10 — CI#

• .github/workflows/ci.yml:
  • Trigger on push to main and pull_request
  • Matrix: Python 3.10, 3.11, 3.12, 3.13 × ubuntu-latest
  • Steps: checkout → install uv → uv sync → uv run ruff check . → uv run ruff format --check . → uv run pyright → uv run pytest tests/unit
• .github/workflows/regen.yml:
  • Weekly cron + workflow_dispatch
  • Fetch latest protocolbuffers/python archive version from buf.build/openstatus/api
  • If newer than pinned version: edit BUF_PY_VERSION in scripts/regen.sh, run regen, open PR with the diff
• .github/workflows/release.yml:
  • Trigger on v* tags
  • Steps: checkout → install uv → uv build → publish to PyPI via Trusted Publishers (pypa/gh-action-pypi-publish)
• Add status badges to README.md (CI, PyPI version, supported Python versions)

Phase 11 — Release v0.1.0#

• Set up PyPI Trusted Publisher for openstatusHQ/sdk-python → project openstatus
• Final CHANGELOG.md pass: move [Unreleased] content under [0.1.0] — YYYY-MM-DD
• Verify uv build produces clean sdist + wheel; inspect wheel contents include _gen/, py.typed, *.pyi
• Smoke-test the built wheel in a fresh venv: pip install dist/openstatus-0.1.0-*.whl && python -c "from openstatus import OpenstatusClient; ..."
• Tag v0.1.0, push tag, verify release.yml publishes to PyPI
• Verify install from PyPI: pip install openstatus in a fresh venv works end-to-end
• Move plan.md → docs/decisions.md; update README link
• Announce on Openstatus channels (blog post, X, Discord — coordinated with team)