pgchangefeed 0.1.0__tar.gz

pgchangefeed-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: pgchangefeed
+Version: 0.1.0
+Summary: Official Python client library for PG Change Feed (HTTP API).
+Author: pt9912
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pt9912/pg-change-feed
+Project-URL: Repository, https://github.com/pt9912/pg-change-feed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# PG Change Feed — Python SDK
+
+Official Python client library for [PG Change Feed](https://github.com/pt9912/pg-change-feed), a durable change feed system for PostgreSQL built on logical replication.
+
+This package (`pgchangefeed`) lets a Python application consume PG Change Feed's HTTP API without implementing the wire protocol itself — see [`LH-FA-SST-009`](https://github.com/pt9912/pg-change-feed/blob/main/spec/lastenheft.md) for the requirement this SDK fulfills.
+
+## Status
+
+This package is at an early, pre-1.0 stage (`0.x.y`, [ADR-0107](https://github.com/pt9912/pg-change-feed/blob/main/docs/plan/adr/0107-python-pypi-zweites-sdk-package.md)). The current release provides the shared connection configuration (`ClientOptions`: server address and bearer token) and a full HTTP API client surface (`PgChangeFeedHttpClient`): consumer registration/acknowledgement/position/removal, table enable/disable, status, table listing, retention, and reading changes — the nine `SPEC-018` capabilities plus `GET /changes` (`SPEC-022`). gRPC, SSE and NATS-vollinhalt delivery remain out of scope for this package's first release and would be added by a follow-up release (`ADR-0107` Festlegung 1).
+
+If a surface you need isn't covered yet, the direct wire protocol remains fully usable on its own — no `examples/python/` reference client exists yet (`ADR-0107` §Kontext); see the [`examples`](https://github.com/pt9912/pg-change-feed/tree/main/examples) reference clients for other languages in the main repository.
+
+## Installation
+
+```
+pip install pgchangefeed
+```
+
+## Documentation
+
+This README intentionally does not duplicate the wire protocol documentation. For the full picture — server setup, HTTP/gRPC/SSE/NATS delivery paths, and operational guidance — see the [project README](https://github.com/pt9912/pg-change-feed/blob/main/README.md) and the technical specification (`spec/pflichtenheft.md`, `SPEC-018`) in the main repository.
+
+## License
+
+MIT — see [LICENSE](https://github.com/pt9912/pg-change-feed/blob/main/LICENSE).

pgchangefeed-0.1.0/README.md

@@ -0,0 +1,25 @@
+# PG Change Feed — Python SDK
+
+Official Python client library for [PG Change Feed](https://github.com/pt9912/pg-change-feed), a durable change feed system for PostgreSQL built on logical replication.
+
+This package (`pgchangefeed`) lets a Python application consume PG Change Feed's HTTP API without implementing the wire protocol itself — see [`LH-FA-SST-009`](https://github.com/pt9912/pg-change-feed/blob/main/spec/lastenheft.md) for the requirement this SDK fulfills.
+
+## Status
+
+This package is at an early, pre-1.0 stage (`0.x.y`, [ADR-0107](https://github.com/pt9912/pg-change-feed/blob/main/docs/plan/adr/0107-python-pypi-zweites-sdk-package.md)). The current release provides the shared connection configuration (`ClientOptions`: server address and bearer token) and a full HTTP API client surface (`PgChangeFeedHttpClient`): consumer registration/acknowledgement/position/removal, table enable/disable, status, table listing, retention, and reading changes — the nine `SPEC-018` capabilities plus `GET /changes` (`SPEC-022`). gRPC, SSE and NATS-vollinhalt delivery remain out of scope for this package's first release and would be added by a follow-up release (`ADR-0107` Festlegung 1).
+
+If a surface you need isn't covered yet, the direct wire protocol remains fully usable on its own — no `examples/python/` reference client exists yet (`ADR-0107` §Kontext); see the [`examples`](https://github.com/pt9912/pg-change-feed/tree/main/examples) reference clients for other languages in the main repository.
+
+## Installation
+
+```
+pip install pgchangefeed
+```
+
+## Documentation
+
+This README intentionally does not duplicate the wire protocol documentation. For the full picture — server setup, HTTP/gRPC/SSE/NATS delivery paths, and operational guidance — see the [project README](https://github.com/pt9912/pg-change-feed/blob/main/README.md) and the technical specification (`spec/pflichtenheft.md`, `SPEC-018`) in the main repository.
+
+## License
+
+MIT — see [LICENSE](https://github.com/pt9912/pg-change-feed/blob/main/LICENSE).

pgchangefeed-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pgchangefeed"
+version = "0.1.0"
+# README.md liegt eine Ebene hoeher (sdks/python/README.md, Sprachwurzel-
+# Ebene, analog sdks/csharp/README.md) -- setuptools erlaubt fuer `readme`
+# aber keinen Pfad ausserhalb des Projekt-Wurzelverzeichnisses (real geprueft:
+# `DistutilsOptionError: Cannot access '.../README.md' (or anything outside
+# '...')`, Plan-Nachzug §3). Der Docker-Bau (sdks/python/Dockerfile) kopiert
+# die Datei deshalb an diese lokale Stelle -- dasselbe Muster wie die
+# `.proto`-Einspeisung in sdks/csharp/Dockerfile (COPY an eine vom
+# Projekt erwartete relative Stelle, ohne sie im committeten Baum zu
+# duplizieren).
+description = "Official Python client library for PG Change Feed (HTTP API)."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "pt9912" }]
+requires-python = ">=3.14"
+# Einzige Fremdabhaengigkeit (ADR-0107 Festlegung 1: httpx, keine weitere,
+# keine schwere Fremdabhaengigkeit) -- wird von der HTTP-API-Client-Flaeche
+# (src/pgchangefeed/http_client.py) fuer die HTTP-Requests genutzt.
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/pt9912/pg-change-feed"
+Repository = "https://github.com/pt9912/pg-change-feed"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

pgchangefeed-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pgchangefeed-0.1.0/src/pgchangefeed/__init__.py

@@ -0,0 +1,35 @@
+"""PG Change Feed Python client library.
+
+This release exposes the shared connection configuration
+(`ClientOptions`) and the HTTP API client surface (`PgChangeFeedHttpClient`):
+the nine SPEC-018 capabilities plus reading persisted changes
+(`ReadChanges`, SPEC-022). gRPC, SSE and NATS-Vollinhalt delivery remain
+out of scope for this package (ADR-0107 Festlegung 1) -- a follow-up
+release would add a separate client surface for them.
+"""
+
+from pgchangefeed.exceptions import (
+    PgChangeFeedBadRequestError,
+    PgChangeFeedError,
+    PgChangeFeedForbiddenError,
+    PgChangeFeedMalformedResponseError,
+    PgChangeFeedNotFoundError,
+    PgChangeFeedServerError,
+    PgChangeFeedUnauthorizedError,
+    PgChangeFeedUnexpectedStatusError,
+)
+from pgchangefeed.http_client import PgChangeFeedHttpClient
+from pgchangefeed.options import ClientOptions
+
+__all__ = [
+    "ClientOptions",
+    "PgChangeFeedHttpClient",
+    "PgChangeFeedError",
+    "PgChangeFeedBadRequestError",
+    "PgChangeFeedUnauthorizedError",
+    "PgChangeFeedForbiddenError",
+    "PgChangeFeedNotFoundError",
+    "PgChangeFeedServerError",
+    "PgChangeFeedUnexpectedStatusError",
+    "PgChangeFeedMalformedResponseError",
+]

pgchangefeed-0.1.0/src/pgchangefeed/exceptions.py

@@ -0,0 +1,57 @@
+"""Typed error hierarchy for PG Change Feed HTTP/JSON API responses.
+
+Mirrors the uniform SPEC-018 error body (``{"error": "<text>"}``) as typed
+exceptions instead of a raw ``httpx`` exception, consistent across every
+``PgChangeFeedHttpClient`` method -- one base class a caller can catch
+regardless of the concrete status code.
+"""
+
+from __future__ import annotations
+
+
+class PgChangeFeedError(Exception):
+    """Base type for every typed error ``PgChangeFeedHttpClient`` raises."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class PgChangeFeedBadRequestError(PgChangeFeedError):
+    """``400`` -- an invalid request body or a violated domain invariant
+    (SPEC-018/SPEC-022)."""
+
+
+class PgChangeFeedUnauthorizedError(PgChangeFeedError):
+    """``401`` -- a missing bearer token, or one that matches no configured
+    token class (SPEC-018)."""
+
+
+class PgChangeFeedForbiddenError(PgChangeFeedError):
+    """``403`` -- a known token whose rights class does not reach the
+    called endpoint, e.g. a ``reader`` token against an ``admin`` endpoint
+    (SPEC-018)."""
+
+
+class PgChangeFeedNotFoundError(PgChangeFeedError):
+    """``404`` -- the addressed table is physically missing at the source
+    (only ``EnableTable``/``DisableTable``/``GetStatus``, SPEC-018)."""
+
+
+class PgChangeFeedServerError(PgChangeFeedError):
+    """``500`` -- an unexpected internal server error (SPEC-018/SPEC-022)."""
+
+
+class PgChangeFeedUnexpectedStatusError(PgChangeFeedError):
+    """Any non-success status code outside the five SPEC-018/SPEC-022
+    document (400/401/403/404/500) -- a defensive fallback that is itself
+    not part of the documented wire contract."""
+
+
+class PgChangeFeedMalformedResponseError(PgChangeFeedError):
+    """A success status code (``2xx``) whose body does not match the
+    expected SPEC-018/SPEC-022 response shape -- invalid JSON, or valid
+    JSON missing an expected field. Outside every shape SPEC-018/SPEC-022
+    document; kept typed and distinct from the status-code errors above so
+    a caller can still catch ``PgChangeFeedError`` uniformly across every
+    method."""

pgchangefeed-0.1.0/src/pgchangefeed/http_client.py

@@ -0,0 +1,257 @@
+"""Public entry point for the PG Change Feed HTTP/JSON API.
+
+One method per wire capability: the nine port-covered capabilities of
+SPEC-018 (``RegisterConsumer``, ``AcknowledgeConsumer``,
+``GetConsumerPosition``, ``RemoveConsumer``, ``EnableTable``,
+``DisableTable``, ``GetStatus``, ``ListTables``, ``RunRetention``) plus
+reading persisted changes (``ReadChanges``, SPEC-022). Requests/responses
+are typed data classes that mirror the SPEC-018/SPEC-022 JSON schemas
+exactly (``pgchangefeed.models``); every non-success response becomes a
+typed ``PgChangeFeedError`` subclass instead of a raw ``httpx`` exception,
+and a success (``2xx``) response whose body does not match the documented
+shape -- invalid JSON, or valid JSON missing an expected field -- becomes
+a typed ``PgChangeFeedMalformedResponseError`` instead of letting a raw
+parsing exception leak through. Both paths run through the same
+``_handle`` helper, so this holds uniformly across every method rather
+than being reimplemented ten times.
+
+The ``httpx.Client`` is injected, not owned -- the caller controls its
+lifetime, connection pooling and transport (including a
+``httpx.MockTransport`` for tests); this type never closes it. The bearer
+token and server address come from ``ClientOptions``, supplied at
+construction -- no module-level or global state, a process can hold
+several independently configured instances at once.
+
+Draht-Kenntnis-Quelle: ``spec/pflichtenheft.md`` SPEC-018/SPEC-022
+(direkt), im Zweifel der Go-Server-Adapter selbst (nur gelesen, nicht
+importiert -- kein Python-Import eines privaten Baums dieses Repos) --
+kein ``examples/python/``-Referenz-Client existiert (ADR-0107 §Kontext).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+import httpx
+
+from pgchangefeed.exceptions import (
+    PgChangeFeedBadRequestError,
+    PgChangeFeedError,
+    PgChangeFeedForbiddenError,
+    PgChangeFeedMalformedResponseError,
+    PgChangeFeedNotFoundError,
+    PgChangeFeedServerError,
+    PgChangeFeedUnauthorizedError,
+    PgChangeFeedUnexpectedStatusError,
+)
+from pgchangefeed.models import (
+    AcknowledgeConsumerRequest,
+    AcknowledgeConsumerResponse,
+    ConsumerPositionResponse,
+    DisableTableRequest,
+    DisableTableResponse,
+    EnableTableRequest,
+    EnableTableResponse,
+    ListTablesResponse,
+    ReadChangesResponse,
+    RegisterConsumerRequest,
+    RegisterConsumerResponse,
+    RemoveConsumerResponse,
+    RunRetentionRequest,
+    RunRetentionResponse,
+    TableStatusResponse,
+)
+from pgchangefeed.options import ClientOptions
+
+T = TypeVar("T")
+
+_STATUS_TO_ERROR: dict[int, type[PgChangeFeedError]] = {
+    400: PgChangeFeedBadRequestError,
+    401: PgChangeFeedUnauthorizedError,
+    403: PgChangeFeedForbiddenError,
+    404: PgChangeFeedNotFoundError,
+    500: PgChangeFeedServerError,
+}
+
+
+class PgChangeFeedHttpClient:
+    """Client for the nine SPEC-018 capabilities plus ``ReadChanges`` (SPEC-022)."""
+
+    def __init__(self, client: httpx.Client, options: ClientOptions) -> None:
+        self._client = client
+        self._options = options
+
+    # --- RegisterConsumer -- POST /consumers (admin, LH-FA-CON-001) ---
+
+    def register_consumer(self, request: RegisterConsumerRequest) -> RegisterConsumerResponse:
+        body = {"consumer_id": request.consumer_id, "name": request.name}
+        return self._post("/consumers", body, RegisterConsumerResponse.from_json)
+
+    # --- AcknowledgeConsumer -- POST /consumers/acknowledge (admin, LH-FA-CON-004) ---
+
+    def acknowledge_consumer(
+        self, request: AcknowledgeConsumerRequest
+    ) -> AcknowledgeConsumerResponse:
+        body = {
+            "consumer_id": request.consumer_id,
+            "source_id": request.source_id,
+            "offset": request.offset,
+        }
+        return self._post("/consumers/acknowledge", body, AcknowledgeConsumerResponse.from_json)
+
+    # --- GetConsumerPosition -- GET /consumers/position (reader|admin, LH-FA-CON-003/005) ---
+
+    def get_consumer_position(self, consumer_id: str) -> ConsumerPositionResponse:
+        return self._get(
+            "/consumers/position",
+            {"consumer_id": consumer_id},
+            ConsumerPositionResponse.from_json,
+        )
+
+    # --- RemoveConsumer -- POST /consumers/remove (admin, LH-FA-CON-006) ---
+
+    def remove_consumer(self, consumer_id: str) -> RemoveConsumerResponse:
+        return self._post(
+            "/consumers/remove", {"consumer_id": consumer_id}, RemoveConsumerResponse.from_json
+        )
+
+    # --- EnableTable -- POST /tables/enable (admin, LH-FA-CFG-001) ---
+
+    def enable_table(self, request: EnableTableRequest) -> EnableTableResponse:
+        body = {
+            "source": request.source,
+            "schema": request.schema,
+            "table": request.table,
+            "table_id": request.table_id,
+            "schema_version_id": request.schema_version_id,
+            "version": request.version,
+            "publication": request.publication,
+        }
+        return self._post("/tables/enable", body, EnableTableResponse.from_json)
+
+    # --- DisableTable -- POST /tables/disable (admin, LH-FA-CFG-002) ---
+
+    def disable_table(self, request: DisableTableRequest) -> DisableTableResponse:
+        body = {
+            "source": request.source,
+            "schema": request.schema,
+            "table": request.table,
+            "publication": request.publication,
+        }
+        return self._post("/tables/disable", body, DisableTableResponse.from_json)
+
+    # --- GetStatus -- GET /tables/status (reader|admin, LH-FA-CFG-003) ---
+
+    def get_status(
+        self, source: str, schema: str, table: str, publication: str
+    ) -> TableStatusResponse:
+        return self._get(
+            "/tables/status",
+            {"source": source, "schema": schema, "table": table, "publication": publication},
+            TableStatusResponse.from_json,
+        )
+
+    # --- ListTables -- GET /tables (reader|admin, LH-FA-CFG-004) ---
+
+    def list_tables(self, source: str, publication: str) -> ListTablesResponse:
+        return self._get(
+            "/tables",
+            {"source": source, "publication": publication},
+            ListTablesResponse.from_json,
+        )
+
+    # --- RunRetention -- POST /retention/run (admin, LH-FA-RET-002..004) ---
+
+    def run_retention(self, request: RunRetentionRequest) -> RunRetentionResponse:
+        body = {"source": request.source, "min_age_nanos": request.min_age_nanos}
+        return self._post("/retention/run", body, RunRetentionResponse.from_json)
+
+    # --- ReadChanges -- GET /changes (reader|admin, SPEC-022) ---
+
+    def read_changes(
+        self,
+        source: str,
+        schema: str | None = None,
+        table: str | None = None,
+        from_: int | None = None,
+        to: int | None = None,
+        limit: int | None = None,
+    ) -> ReadChangesResponse:
+        """``from``/``to`` are ``commit_position`` values, ``from``
+        inclusive and ``to`` exclusive (SPEC-022); ``from_`` avoids
+        shadowing the Python keyword ``from`` while sending the ``from``
+        query parameter the wire contract expects. There is no default
+        ``limit``.
+        """
+        return self._get(
+            "/changes",
+            {
+                "source": source,
+                "schema": schema,
+                "table": table,
+                "from": from_,
+                "to": to,
+                "limit": limit,
+            },
+            ReadChangesResponse.from_json,
+        )
+
+    # --- transport plumbing ---
+
+    def _url(self, path: str) -> str:
+        return f"{self._options.address.rstrip('/')}{path}"
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._options.api_token}"}
+
+    def _get(self, path: str, params: dict[str, Any], mapper: Callable[[Any], T]) -> T:
+        response = self._client.get(
+            self._url(path), params=_drop_none(params), headers=self._headers()
+        )
+        return self._handle(response, mapper)
+
+    def _post(self, path: str, body: dict[str, Any], mapper: Callable[[Any], T]) -> T:
+        response = self._client.post(self._url(path), json=body, headers=self._headers())
+        return self._handle(response, mapper)
+
+    def _handle(self, response: httpx.Response, mapper: Callable[[Any], T]) -> T:
+        if not 200 <= response.status_code < 300:
+            raise _build_error(response)
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise PgChangeFeedMalformedResponseError(
+                response.status_code,
+                f"PG Change Feed HTTP API returned status {response.status_code} with a response "
+                "body that is not valid JSON -- a protocol violation outside SPEC-018/SPEC-022's "
+                "documented shapes.",
+            ) from exc
+        try:
+            return mapper(payload)
+        except (KeyError, TypeError) as exc:
+            raise PgChangeFeedMalformedResponseError(
+                response.status_code,
+                f"PG Change Feed HTTP API returned status {response.status_code} with a response "
+                "body missing an expected SPEC-018/SPEC-022 field -- a protocol violation outside "
+                "the documented shapes.",
+            ) from exc
+
+
+def _drop_none(params: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in params.items() if value is not None}
+
+
+def _build_error(response: httpx.Response) -> PgChangeFeedError:
+    message = _extract_error_message(response)
+    error_cls = _STATUS_TO_ERROR.get(response.status_code, PgChangeFeedUnexpectedStatusError)
+    return error_cls(response.status_code, message)
+
+
+def _extract_error_message(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text
+    if isinstance(body, dict) and "error" in body:
+        return str(body["error"])
+    return response.text

pgchangefeed-0.1.0/src/pgchangefeed/models.py

@@ -0,0 +1,260 @@
+"""Typed request/response data classes mirroring the SPEC-018/SPEC-022 JSON
+schemas exactly.
+
+Field names and types are taken directly from spec/pflichtenheft.md
+SPEC-018 (HTTP-API: Endpunkte und Token-Header-Form) and SPEC-022
+(HTTP-API: Changes lesen, GET /changes) -- not from the C# sibling
+package, which serves only as a structural reference, not a wire
+reference (ADR-0107). Every attribute name equals the JSON field name
+verbatim, so no case-mapping layer is needed between the two.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# --- RegisterConsumer -- POST /consumers (admin, LH-FA-CON-001) ---
+
+
+@dataclass(frozen=True)
+class RegisterConsumerRequest:
+    consumer_id: str
+    name: str
+
+
+@dataclass(frozen=True)
+class RegisterConsumerResponse:
+    consumer_id: str
+    name: str
+    already_registered: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> RegisterConsumerResponse:
+        return cls(
+            consumer_id=data["consumer_id"],
+            name=data["name"],
+            already_registered=data["already_registered"],
+        )
+
+
+# --- AcknowledgeConsumer -- POST /consumers/acknowledge (admin, LH-FA-CON-004) ---
+
+
+@dataclass(frozen=True)
+class AcknowledgeConsumerRequest:
+    consumer_id: str
+    source_id: str
+    offset: int
+
+
+@dataclass(frozen=True)
+class AcknowledgeConsumerResponse:
+    consumer_id: str
+    source_id: str
+    offset: int
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> AcknowledgeConsumerResponse:
+        return cls(
+            consumer_id=data["consumer_id"],
+            source_id=data["source_id"],
+            offset=data["offset"],
+        )
+
+
+# --- GetConsumerPosition -- GET /consumers/position (reader|admin, LH-FA-CON-003/005) ---
+
+
+@dataclass(frozen=True)
+class ConsumerPositionResponse:
+    consumer_id: str
+    source_id: str
+    offset: int
+    acknowledged: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> ConsumerPositionResponse:
+        return cls(
+            consumer_id=data["consumer_id"],
+            source_id=data["source_id"],
+            offset=data["offset"],
+            acknowledged=data["acknowledged"],
+        )
+
+
+# --- RemoveConsumer -- POST /consumers/remove (admin, LH-FA-CON-006) ---
+
+
+@dataclass(frozen=True)
+class RemoveConsumerResponse:
+    consumer_id: str
+    removed: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> RemoveConsumerResponse:
+        return cls(consumer_id=data["consumer_id"], removed=data["removed"])
+
+
+# --- EnableTable -- POST /tables/enable (admin, LH-FA-CFG-001) ---
+
+
+@dataclass(frozen=True)
+class EnableTableRequest:
+    source: str
+    schema: str
+    table: str
+    table_id: str
+    schema_version_id: str
+    version: int
+    publication: str
+
+
+@dataclass(frozen=True)
+class EnableTableResponse:
+    table_id: str
+    source: str
+    schema: str
+    table: str
+    already_enabled: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> EnableTableResponse:
+        return cls(
+            table_id=data["table_id"],
+            source=data["source"],
+            schema=data["schema"],
+            table=data["table"],
+            already_enabled=data["already_enabled"],
+        )
+
+
+# --- DisableTable -- POST /tables/disable (admin, LH-FA-CFG-002) ---
+
+
+@dataclass(frozen=True)
+class DisableTableRequest:
+    source: str
+    schema: str
+    table: str
+    publication: str
+
+
+@dataclass(frozen=True)
+class DisableTableResponse:
+    removed: bool
+    retained: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> DisableTableResponse:
+        return cls(removed=data["removed"], retained=data["retained"])
+
+
+# --- GetStatus -- GET /tables/status (reader|admin, LH-FA-CFG-003) ---
+
+
+@dataclass(frozen=True)
+class TableStatusResponse:
+    enabled: bool
+    retained: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> TableStatusResponse:
+        return cls(enabled=data["enabled"], retained=data["retained"])
+
+
+# --- ListTables -- GET /tables (reader|admin, LH-FA-CFG-004) ---
+
+
+@dataclass(frozen=True)
+class TableInfo:
+    table_id: str
+    source: str
+    schema: str
+    table: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> TableInfo:
+        return cls(
+            table_id=data["table_id"],
+            source=data["source"],
+            schema=data["schema"],
+            table=data["table"],
+        )
+
+
+@dataclass(frozen=True)
+class ListTablesResponse:
+    tables: list[TableInfo] = field(default_factory=list)
+    retained: list[TableInfo] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> ListTablesResponse:
+        return cls(
+            tables=[TableInfo.from_json(item) for item in data["tables"]],
+            retained=[TableInfo.from_json(item) for item in data["retained"]],
+        )
+
+
+# --- RunRetention -- POST /retention/run (admin, LH-FA-RET-002..004) ---
+
+
+@dataclass(frozen=True)
+class RunRetentionRequest:
+    source: str
+    min_age_nanos: int
+
+
+@dataclass(frozen=True)
+class RunRetentionResponse:
+    deleted: int
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> RunRetentionResponse:
+        return cls(deleted=data["deleted"])
+
+
+# --- ReadChanges -- GET /changes (reader|admin, SPEC-022) ---
+
+
+@dataclass(frozen=True)
+class Change:
+    commit_position: int
+    change_id: str
+    transaction_id: str
+    source_table_id: str
+    schema: str
+    table: str
+    sequence: int
+    operation: str
+    old_image: Any | None
+    new_image: Any | None
+    schema_version: str
+    committed_at: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Change:
+        return cls(
+            commit_position=data["commit_position"],
+            change_id=data["change_id"],
+            transaction_id=data["transaction_id"],
+            source_table_id=data["source_table_id"],
+            schema=data["schema"],
+            table=data["table"],
+            sequence=data["sequence"],
+            operation=data["operation"],
+            old_image=data["old_image"],
+            new_image=data["new_image"],
+            schema_version=data["schema_version"],
+            committed_at=data["committed_at"],
+        )
+
+
+@dataclass(frozen=True)
+class ReadChangesResponse:
+    changes: list[Change] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> ReadChangesResponse:
+        return cls(changes=[Change.from_json(item) for item in data["changes"]])

pgchangefeed-0.1.0/src/pgchangefeed/options.py

@@ -0,0 +1,35 @@
+"""Shared connection configuration for PG Change Feed client surfaces.
+
+ADR-0107 Festlegung 1 scopes the first Python package release to the HTTP
+API (SPEC-018) only -- no gRPC/SSE/NATS surface exists yet in this package.
+This class still holds only the two values every wire surface needs
+regardless of transport (base address, bearer token), so a later surface
+can reuse it without a breaking change to this constructor -- no
+anticipation of endpoint methods themselves (analogy:
+sdks/csharp/PgChangeFeed.Client/PgChangeFeedClientOptions.cs).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ClientOptions:
+    """Connection configuration for a PG Change Feed client surface.
+
+    Attributes:
+        address: Base address of the PG Change Feed server (the HTTP
+            endpoint, for the surface currently covered by this package).
+        api_token: Bearer token sent as an authorization credential
+            (SPEC-018).
+    """
+
+    address: str
+    api_token: str
+
+    def __post_init__(self) -> None:
+        if not self.address or not self.address.strip():
+            raise ValueError("address must not be empty")
+        if not self.api_token or not self.api_token.strip():
+            raise ValueError("api_token must not be empty")

pgchangefeed-0.1.0/src/pgchangefeed.egg-info/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: pgchangefeed
+Version: 0.1.0
+Summary: Official Python client library for PG Change Feed (HTTP API).
+Author: pt9912
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pt9912/pg-change-feed
+Project-URL: Repository, https://github.com/pt9912/pg-change-feed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# PG Change Feed — Python SDK
+
+Official Python client library for [PG Change Feed](https://github.com/pt9912/pg-change-feed), a durable change feed system for PostgreSQL built on logical replication.
+
+This package (`pgchangefeed`) lets a Python application consume PG Change Feed's HTTP API without implementing the wire protocol itself — see [`LH-FA-SST-009`](https://github.com/pt9912/pg-change-feed/blob/main/spec/lastenheft.md) for the requirement this SDK fulfills.
+
+## Status
+
+This package is at an early, pre-1.0 stage (`0.x.y`, [ADR-0107](https://github.com/pt9912/pg-change-feed/blob/main/docs/plan/adr/0107-python-pypi-zweites-sdk-package.md)). The current release provides the shared connection configuration (`ClientOptions`: server address and bearer token) and a full HTTP API client surface (`PgChangeFeedHttpClient`): consumer registration/acknowledgement/position/removal, table enable/disable, status, table listing, retention, and reading changes — the nine `SPEC-018` capabilities plus `GET /changes` (`SPEC-022`). gRPC, SSE and NATS-vollinhalt delivery remain out of scope for this package's first release and would be added by a follow-up release (`ADR-0107` Festlegung 1).
+
+If a surface you need isn't covered yet, the direct wire protocol remains fully usable on its own — no `examples/python/` reference client exists yet (`ADR-0107` §Kontext); see the [`examples`](https://github.com/pt9912/pg-change-feed/tree/main/examples) reference clients for other languages in the main repository.
+
+## Installation
+
+```
+pip install pgchangefeed
+```
+
+## Documentation
+
+This README intentionally does not duplicate the wire protocol documentation. For the full picture — server setup, HTTP/gRPC/SSE/NATS delivery paths, and operational guidance — see the [project README](https://github.com/pt9912/pg-change-feed/blob/main/README.md) and the technical specification (`spec/pflichtenheft.md`, `SPEC-018`) in the main repository.
+
+## License
+
+MIT — see [LICENSE](https://github.com/pt9912/pg-change-feed/blob/main/LICENSE).

pgchangefeed-0.1.0/src/pgchangefeed.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/pgchangefeed/__init__.py
+src/pgchangefeed/exceptions.py
+src/pgchangefeed/http_client.py
+src/pgchangefeed/models.py
+src/pgchangefeed/options.py
+src/pgchangefeed.egg-info/PKG-INFO
+src/pgchangefeed.egg-info/SOURCES.txt
+src/pgchangefeed.egg-info/dependency_links.txt
+src/pgchangefeed.egg-info/requires.txt
+src/pgchangefeed.egg-info/top_level.txt
+tests/test_http_client.py
+tests/test_options.py

pgchangefeed-0.1.0/src/pgchangefeed.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pgchangefeed-0.1.0/src/pgchangefeed.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.27
+
+[test]
+pytest>=8

pgchangefeed-0.1.0/src/pgchangefeed.egg-info/top_level.txt

@@ -0,0 +1 @@
+pgchangefeed

pgchangefeed-0.1.0/tests/test_http_client.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import httpx
+import pytest
+
+from pgchangefeed.exceptions import (
+    PgChangeFeedBadRequestError,
+    PgChangeFeedForbiddenError,
+    PgChangeFeedMalformedResponseError,
+    PgChangeFeedNotFoundError,
+    PgChangeFeedServerError,
+    PgChangeFeedUnauthorizedError,
+    PgChangeFeedUnexpectedStatusError,
+)
+from pgchangefeed.http_client import PgChangeFeedHttpClient
+from pgchangefeed.models import (
+    AcknowledgeConsumerRequest,
+    DisableTableRequest,
+    EnableTableRequest,
+    RegisterConsumerRequest,
+    RunRetentionRequest,
+)
+from pgchangefeed.options import ClientOptions
+
+ADDRESS = "https://feed.example.invalid"
+ADMIN_TOKEN = "admin-token"
+READER_TOKEN = "reader-token"
+
+
+def _make_client(
+    handler: Callable[[httpx.Request], httpx.Response], token: str = ADMIN_TOKEN
+) -> PgChangeFeedHttpClient:
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.Client(transport=transport)
+    options = ClientOptions(address=ADDRESS, api_token=token)
+    return PgChangeFeedHttpClient(http_client, options)
+
+
+def _handler_returning(status_code: int, payload: object) -> Callable[[httpx.Request], httpx.Response]:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status_code, json=payload)
+
+    return handler
+
+
+# --- Happy path, one per SPEC-018 capability plus ReadChanges (SPEC-022) ---
+
+
+def test_register_consumer_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/consumers"
+        assert request.headers["authorization"] == f"Bearer {ADMIN_TOKEN}"
+        return httpx.Response(
+            201,
+            json={"consumer_id": "c1", "name": "Consumer 1", "already_registered": False},
+        )
+
+    client = _make_client(handler)
+    response = client.register_consumer(RegisterConsumerRequest(consumer_id="c1", name="Consumer 1"))
+    assert response.consumer_id == "c1"
+    assert response.name == "Consumer 1"
+    assert response.already_registered is False
+
+
+def test_acknowledge_consumer_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/consumers/acknowledge"
+        return httpx.Response(
+            200,
+            json={"consumer_id": "c1", "source_id": "s1", "offset": 42},
+        )
+
+    client = _make_client(handler)
+    response = client.acknowledge_consumer(
+        AcknowledgeConsumerRequest(consumer_id="c1", source_id="s1", offset=42)
+    )
+    assert response.consumer_id == "c1"
+    assert response.source_id == "s1"
+    assert response.offset == 42
+
+
+def test_get_consumer_position_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/consumers/position"
+        assert request.url.params["consumer_id"] == "c1"
+        return httpx.Response(
+            200,
+            json={"consumer_id": "c1", "source_id": "s1", "offset": 7, "acknowledged": True},
+        )
+
+    client = _make_client(handler)
+    response = client.get_consumer_position("c1")
+    assert response.offset == 7
+    assert response.acknowledged is True
+
+
+def test_remove_consumer_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/consumers/remove"
+        return httpx.Response(200, json={"consumer_id": "c1", "removed": True})
+
+    client = _make_client(handler)
+    response = client.remove_consumer("c1")
+    assert response.removed is True
+
+
+def test_enable_table_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/tables/enable"
+        return httpx.Response(
+            201,
+            json={
+                "table_id": "t1",
+                "source": "src",
+                "schema": "public",
+                "table": "orders",
+                "already_enabled": False,
+            },
+        )
+
+    client = _make_client(handler)
+    response = client.enable_table(
+        EnableTableRequest(
+            source="src",
+            schema="public",
+            table="orders",
+            table_id="t1",
+            schema_version_id="sv1",
+            version=1,
+            publication="pub",
+        )
+    )
+    assert response.table_id == "t1"
+    assert response.already_enabled is False
+
+
+def test_disable_table_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/tables/disable"
+        return httpx.Response(200, json={"removed": True, "retained": False})
+
+    client = _make_client(handler)
+    response = client.disable_table(
+        DisableTableRequest(source="src", schema="public", table="orders", publication="pub")
+    )
+    assert response.removed is True
+    assert response.retained is False
+
+
+def test_get_status_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/tables/status"
+        assert request.url.params["source"] == "src"
+        assert request.url.params["publication"] == "pub"
+        return httpx.Response(200, json={"enabled": True, "retained": False})
+
+    client = _make_client(handler)
+    response = client.get_status(source="src", schema="public", table="orders", publication="pub")
+    assert response.enabled is True
+    assert response.retained is False
+
+
+def test_list_tables_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/tables"
+        return httpx.Response(
+            200,
+            json={
+                "tables": [{"table_id": "t1", "source": "src", "schema": "public", "table": "orders"}],
+                "retained": [],
+            },
+        )
+
+    client = _make_client(handler)
+    response = client.list_tables(source="src", publication="pub")
+    assert len(response.tables) == 1
+    assert response.tables[0].table_id == "t1"
+    assert response.retained == []
+
+
+def test_run_retention_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/retention/run"
+        return httpx.Response(200, json={"deleted": 3})
+
+    client = _make_client(handler)
+    response = client.run_retention(RunRetentionRequest(source="src", min_age_nanos=0))
+    assert response.deleted == 3
+
+
+def test_read_changes_happy_path() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/changes"
+        assert request.url.params["source"] == "src"
+        assert request.url.params["from"] == "1"
+        assert "limit" not in request.url.params
+        return httpx.Response(
+            200,
+            json={
+                "changes": [
+                    {
+                        "commit_position": 1,
+                        "change_id": "chg1",
+                        "transaction_id": "tx1",
+                        "source_table_id": "t1",
+                        "schema": "public",
+                        "table": "orders",
+                        "sequence": 1,
+                        "operation": "INSERT",
+                        "old_image": None,
+                        "new_image": {"id": 1},
+                        "schema_version": "sv1",
+                        "committed_at": "2026-09-19T00:00:00Z",
+                    }
+                ]
+            },
+        )
+
+    client = _make_client(handler)
+    response = client.read_changes(source="src", from_=1)
+    assert len(response.changes) == 1
+    change = response.changes[0]
+    assert change.operation == "INSERT"
+    assert change.new_image == {"id": 1}
+    assert change.old_image is None
+
+
+def test_read_changes_empty_result_is_not_an_error() -> None:
+    client = _make_client(_handler_returning(200, {"changes": []}))
+    response = client.read_changes(source="src")
+    assert response.changes == []
+
+
+# --- Auth boundary (SPEC-018: 401 missing/unknown token, 403 reader-vs-admin) ---
+
+
+def _auth_aware_handler(admin_only_paths: set[str]) -> Callable[[httpx.Request], httpx.Response]:
+    def handler(request: httpx.Request) -> httpx.Response:
+        auth = request.headers.get("authorization", "")
+        if not auth.startswith("Bearer "):
+            return httpx.Response(401, json={"error": "missing bearer token"})
+        token = auth.removeprefix("Bearer ")
+        if token not in (ADMIN_TOKEN, READER_TOKEN):
+            return httpx.Response(401, json={"error": "unknown bearer token"})
+        if request.url.path in admin_only_paths and token != ADMIN_TOKEN:
+            return httpx.Response(403, json={"error": "insufficient rights"})
+        return httpx.Response(200, json={"consumer_id": "c1", "removed": False})
+
+    return handler
+
+
+def test_unknown_token_returns_typed_unauthorized_error() -> None:
+    client = _make_client(_auth_aware_handler({"/consumers/remove"}), token="unknown-token")
+    with pytest.raises(PgChangeFeedUnauthorizedError) as exc_info:
+        client.remove_consumer("c1")
+    assert exc_info.value.status_code == 401
+
+
+def test_reader_token_against_admin_endpoint_returns_typed_forbidden_error() -> None:
+    client = _make_client(_auth_aware_handler({"/consumers/remove"}), token=READER_TOKEN)
+    with pytest.raises(PgChangeFeedForbiddenError) as exc_info:
+        client.remove_consumer("c1")
+    assert exc_info.value.status_code == 403
+
+
+# --- Remaining status-code mapping (SPEC-018/SPEC-022: 400/404/500, defensive fallback) ---
+
+
+def test_400_returns_typed_bad_request_error_with_error_message() -> None:
+    client = _make_client(_handler_returning(400, {"error": "source ist Pflichtfeld"}))
+    with pytest.raises(PgChangeFeedBadRequestError) as exc_info:
+        client.read_changes(source="src")
+    assert exc_info.value.status_code == 400
+    assert "Pflichtfeld" in str(exc_info.value)
+
+
+def test_404_returns_typed_not_found_error() -> None:
+    client = _make_client(_handler_returning(404, {"error": "Tabelle existiert nicht an der Quelle"}))
+    with pytest.raises(PgChangeFeedNotFoundError) as exc_info:
+        client.get_status(source="src", schema="public", table="missing", publication="pub")
+    assert exc_info.value.status_code == 404
+
+
+def test_500_returns_typed_server_error() -> None:
+    client = _make_client(_handler_returning(500, {"error": "interner Fehler"}))
+    with pytest.raises(PgChangeFeedServerError) as exc_info:
+        client.list_tables(source="src", publication="pub")
+    assert exc_info.value.status_code == 500
+
+
+def test_undocumented_status_returns_typed_unexpected_status_error() -> None:
+    client = _make_client(_handler_returning(409, {"error": "conflict"}))
+    with pytest.raises(PgChangeFeedUnexpectedStatusError) as exc_info:
+        client.list_tables(source="src", publication="pub")
+    assert exc_info.value.status_code == 409
+
+
+def test_error_body_without_error_field_falls_back_to_raw_text() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(400, content=b"not json at all")
+
+    client = _make_client(handler)
+    with pytest.raises(PgChangeFeedBadRequestError) as exc_info:
+        client.list_tables(source="src", publication="pub")
+    assert "not json at all" in str(exc_info.value)
+
+
+# --- Malformed 2xx body: must raise a typed error, never a raw parsing exception ---
+
+
+def test_non_json_success_body_raises_typed_malformed_response_error() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"not json at all")
+
+    client = _make_client(handler)
+    with pytest.raises(PgChangeFeedMalformedResponseError) as exc_info:
+        client.list_tables(source="src", publication="pub")
+    assert exc_info.value.status_code == 200
+
+
+def test_success_body_missing_expected_field_raises_typed_malformed_response_error() -> None:
+    client = _make_client(_handler_returning(200, {"unexpected": "shape"}))
+    with pytest.raises(PgChangeFeedMalformedResponseError) as exc_info:
+        client.list_tables(source="src", publication="pub")
+    assert exc_info.value.status_code == 200

pgchangefeed-0.1.0/tests/test_options.py

@@ -0,0 +1,19 @@
+import pytest
+
+from pgchangefeed import ClientOptions
+
+
+def test_client_options_holds_address_and_token() -> None:
+    options = ClientOptions(address="https://example.invalid", api_token="secret")
+    assert options.address == "https://example.invalid"
+    assert options.api_token == "secret"
+
+
+def test_client_options_rejects_empty_address() -> None:
+    with pytest.raises(ValueError):
+        ClientOptions(address="", api_token="secret")
+
+
+def test_client_options_rejects_empty_token() -> None:
+    with pytest.raises(ValueError):
+        ClientOptions(address="https://example.invalid", api_token="")